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:

```bash
cp .env.example .env
```

Configure your environment variables:

```env
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

```bash
cargo run
```

#### Production (Docker)

```bash
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:

```rust
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:

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

## Development

### Building from Source

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

### Running Tests

```bash
cargo test
```

### Logging

Set the `RUST_LOG` environment variable to control log levels:

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

## License

MIT