Gateway¶

The Go gateway is the single entry point for all external requests. It handles authentication, rate limiting, request proxying, and WebSocket connections.

Route Map¶

Public Endpoints¶

Protected Endpoints (JWT required)¶

Middleware Stack¶

Applied in order:

1. RequestID -- Generates UUID, stores in X-Request-ID header and request context
2. Logger -- Logs method, path, status, duration_ms via slog
3. Recoverer -- Catches panics, logs stack trace, returns HTTP 500
4. CORS -- Allows all origins, methods (GET, POST, PUT, PATCH, DELETE, OPTIONS)
5. Metrics -- Prometheus HTTP request instrumentation
6. Auth -- JWT Bearer token validation (HS256) on protected routes
7. RateLimit -- Redis-backed per-service sliding window

Authentication¶

The gateway implements DB-backed multi-user auth with OAuth (GitHub/Google), 15-minute JWT access tokens, and 30-day opaque refresh tokens with rotation.

User Header Forwarding¶

After JWT validation, the gateway injects the following headers into proxied requests so downstream services can identify the authenticated user without re-validating the token:

Token Design¶

Refresh tokens use rotation with family tracking. If a revoked token is reused, the entire token family is invalidated (theft detection).

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@orion.local", "password": "orion_dev"}'

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "ort_a1b2c3d4e5f6...",
  "token_type": "Bearer",
  "expires_in": 900,
  "user": {
    "id": "uuid",
    "email": "admin@orion.local",
    "name": "Admin",
    "role": "admin"
  }
}

# 1. Redirect user to initiate OAuth
curl -L http://localhost:8000/api/v1/auth/oauth/github
# → 302 to https://github.com/login/oauth/authorize?client_id=...&state=...

# 2. GitHub redirects back to callback with code
# GET /api/v1/auth/oauth/github/callback?code=xxx&state=yyy
# → Sets cookies and redirects to dashboard

curl -X POST http://localhost:8000/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "ort_a1b2c3d4e5f6..."}'

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secure123", "name": "New User"}'

WebSocket¶

The WebSocket hub subscribes to Redis channels matching orion.* and broadcasts events to connected clients.

• Endpoint: GET /ws?token=<jwt>
• Ping interval: 30 seconds
• Read timeout: 60 seconds
• Protocol: JSON messages matching the Redis event payload structure

:material-rate-limit: Rate Limiting¶

Per-service rate limits applied via Redis sliding windows:

Configuration¶