calendar-microservice/README.md

Calendar Microservice

A Rust-based REST API microservice for Google Calendar integration using service account authentication with domain-wide delegation support.

Features

• Complete Event Management: Create, read, update, delete, and list calendar events
• Google Calendar API Integration: Full integration with Google Calendar v3 API
• Domain-Wide Delegation: Impersonate users within your Google Workspace domain
• API Key Authentication: Secure access via X-API-Key header
• Token Caching: Efficient OAuth token management to minimize authentication requests
• Docker Support: Ready for containerized deployment

Prerequisites

• Rust 1.75+ (for development)
• Docker & Docker Compose (for deployment)
• A Google Cloud project with Calendar API enabled
• A Google service account with domain-wide delegation configured

Quick Start

1. Environment Setup

Copy the example environment file:

cp .env.example .env

Configure your environment variables:

HOST=127.0.0.1
PORT=4000
API_KEY=your-secret-api-key-here
GOOGLE_CALENDAR_ID=your-calendar-id@group.calendar.google.com
GOOGLE_SERVICE_ACCOUNT_KEY=/path/to/service_account_key.json

2. Google Cloud Setup

1. Create a service account in Google Cloud Console
2. Enable the Google Calendar API for your project
3. Download the service account key JSON file
4. Configure domain-wide delegation in Google Workspace Admin Console with scope:
   • https://www.googleapis.com/auth/calendar

3. Running the Service

Development

cargo run

Production (Docker)

docker-compose up -d

The service will be available at http://localhost:4000.

API Documentation

Authentication

All API endpoints (except /api/v1/health) require authentication via the X-API-Key header:

X-API-Key: your-secret-api-key-here

Endpoints

Health Check

GET /api/v1/health

Returns service health status. No authentication required.

Create Event

POST /api/v1/events
Content-Type: application/json

{
  "id": "optional-custom-id",
  "summary": "Meeting with Team",
  "description": "Weekly sync meeting",
  "location": "Conference Room A",
  "start": {
    "dateTime": "2024-06-15T10:00:00Z",
    "timeZone": "UTC"
  },
  "end": {
    "dateTime": "2024-06-15T11:00:00Z",
    "timeZone": "UTC"
  },
  "attendees": [
    {
      "email": "attendee@example.com",
      "displayName": "John Doe"
    }
  ]
}

Get Event

GET /api/v1/events/{event_id}

List Events

GET /api/v1/events?timeMin=2024-06-01T00:00:00Z&timeMax=2024-06-30T23:59:59Z&maxResults=10&q=meeting

Query parameters:

• timeMin: Start of time range (RFC3339)
• timeMax: End of time range (RFC3339)
• maxResults: Maximum number of events to return
• q: Search term

Update Event

PUT /api/v1/events/{event_id}
Content-Type: application/json

{
  "summary": "Updated Meeting Title",
  "description": "Updated description"
}

Delete Event

DELETE /api/v1/events/{event_id}

Configuration

Environment Variables

Variable	Description	Default
HOST	Server bind address	127.0.0.1
PORT	Server port	4000
API_KEY	Secret key for API authentication	Required
GOOGLE_CALENDAR_ID	ID of the Google Calendar to manage	Required
GOOGLE_SERVICE_ACCOUNT_KEY	Path to service account key file, base64 encoded JSON, or raw JSON	Required

Service Account Key Formats

The GOOGLE_SERVICE_ACCOUNT_KEY can be provided in three formats:

1. File path: /path/to/service_account_key.json
2. Base64 encoded: cat service-account.json | base64 -w 0
3. Raw JSON: {"type": "service_account", ...} (not recommended for production)

CORS Configuration

CORS is configured in src/main.rs. Modify the allowed origins for your deployment:

let cors = Cors::default()
    .allowed_origin("https://your-app.com")
    // ...

Project Structure

├── Cargo.toml
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── src/
    ├── main.rs           # Application entry point
    ├── config.rs         # Configuration management
    ├── handlers/         # HTTP request handlers
    │   ├── events.rs     # Event CRUD operations
    │   └── health.rs     # Health check endpoint
    ├── middleware/       # HTTP middleware
    │   └── auth.rs       # API key authentication
    ├── models/           # Data models
    │   ├── error.rs      # Error handling
    │   └── event.rs      # Event structures
    └── services/         # Business logic
        └── google_calendar.rs  # Google Calendar API client

Error Handling

The service returns standard HTTP status codes:

Status	Description
200 OK	Successful operation
201 Created	Event created successfully
204 No Content	Event deleted successfully
400 Bad Request	Invalid request data
401 Unauthorized	Invalid or missing API key
404 Not Found	Event not found
502 Bad Gateway	Google API error
500 Internal Server Error	Server error

Error responses include a JSON body:

{
  "error": "Error type",
  "message": "Detailed error message"
}

Development

Building from Source

git clone <repository>
cd calendar-microservice
cargo build --release

Running Tests

cargo test

Logging

Set the RUST_LOG environment variable to control log levels:

RUST_LOG=info cargo run
RUST_LOG=debug cargo run  # More verbose

License

MIT