galaxy-game/authsession/docs/runtime.md

# Runtime and Components

The diagram below focuses on the deployed `galaxy/authsession` process and its
runtime dependencies.

```mermaid
flowchart LR
    subgraph Clients
        Gateway["Edge Gateway"]
        Internal["Trusted internal callers"]
    end

    subgraph Authsession["Auth / Session Service process"]
        PublicHTTP["Public HTTP listener\n/api/v1/public/auth/*"]
        InternalHTTP["Trusted internal listener\n/api/v1/internal/*"]
        Services["Application services"]
        Runtime["Clock, IDs, code generation, hashing"]
        Telemetry["Logs, traces, metrics"]
    end

    Redis["Redis\nchallenges + sessions + config + projection + throttle"]
    User["User Service\nstub or REST"]
    Mail["Mail Service\nstub or REST"]
    GatewayCache["Gateway session cache\nand session-events stream"]

    Gateway --> PublicHTTP
    Internal --> InternalHTTP
    PublicHTTP --> Services
    InternalHTTP --> Services
    Services --> Runtime
    Services --> Redis
    Services --> User
    Services --> Mail
    Services --> GatewayCache
    PublicHTTP --> Telemetry
    InternalHTTP --> Telemetry
```

## Listeners

`authsession` exposes exactly two HTTP listeners:

| Listener | Default addr | Purpose |
| --- | --- | --- |
| Public HTTP | `:8080` | Unauthenticated public auth routes consumed directly or through gateway |
| Internal HTTP | `:8081` | Trusted read, revoke, and block operations |

Shared listener defaults:

- read-header timeout: `2s`
- read timeout: `10s`
- idle timeout: `1m`
- per-request application timeout: `3s`

Intentional omissions:

- no `/healthz`
- no `/readyz`
- no `/metrics`
- no separate admin listener

## Startup Wiring

`cmd/authsession` loads process config, builds the logger and telemetry
runtime, then assembles the application through `internal/app.NewRuntime`.

`NewRuntime` wires:

- Redis-backed `ChallengeStore`
- Redis-backed `SessionStore`
- Redis-backed `ConfigProvider`
- Redis-backed gateway `ProjectionPublisher`
- Redis-backed resend-throttle `SendEmailCodeAbuseProtector`
- local runtime helpers for clock, ID generation, code generation, and code
  hashing
- user-service adapter selected by `AUTHSESSION_USER_SERVICE_MODE`
- mail-service adapter selected by `AUTHSESSION_MAIL_SERVICE_MODE`
- public and internal HTTP servers

Before startup completes, the process performs bounded `PING` checks for every
Redis-backed adapter listed above. Startup fails fast if any Redis-backed
dependency is unavailable or misconfigured.

## Redis Namespaces

Default Redis naming:

- challenges: `authsession:challenge:`
- sessions: `authsession:session:`
- user-to-session index: `authsession:user-sessions:`
- user-to-active-session index: `authsession:user-active-sessions:`
- session limit key: `authsession:config:active-session-limit`
- send-email-code throttle keys: `authsession:send-email-code-throttle:`
- gateway session cache keys: `gateway:session:`
- gateway session-events stream: `gateway:session_events`

The authsession process owns the source-of-truth namespaces and writes the
gateway-facing projection namespaces as a derived integration view.

## Configuration Groups

Required for all process starts:

- `AUTHSESSION_REDIS_ADDR`

Core process config:

- `AUTHSESSION_SHUTDOWN_TIMEOUT`
- `AUTHSESSION_LOG_LEVEL`

Public HTTP config:

- `AUTHSESSION_PUBLIC_HTTP_ADDR`
- `AUTHSESSION_PUBLIC_HTTP_READ_HEADER_TIMEOUT`
- `AUTHSESSION_PUBLIC_HTTP_READ_TIMEOUT`
- `AUTHSESSION_PUBLIC_HTTP_IDLE_TIMEOUT`
- `AUTHSESSION_PUBLIC_HTTP_REQUEST_TIMEOUT`

Internal HTTP config:

- `AUTHSESSION_INTERNAL_HTTP_ADDR`
- `AUTHSESSION_INTERNAL_HTTP_READ_HEADER_TIMEOUT`
- `AUTHSESSION_INTERNAL_HTTP_READ_TIMEOUT`
- `AUTHSESSION_INTERNAL_HTTP_IDLE_TIMEOUT`
- `AUTHSESSION_INTERNAL_HTTP_REQUEST_TIMEOUT`

Redis connectivity and namespace config:

- `AUTHSESSION_REDIS_USERNAME`
- `AUTHSESSION_REDIS_PASSWORD`
- `AUTHSESSION_REDIS_DB`
- `AUTHSESSION_REDIS_TLS_ENABLED`
- `AUTHSESSION_REDIS_OPERATION_TIMEOUT`
- `AUTHSESSION_REDIS_CHALLENGE_KEY_PREFIX`
- `AUTHSESSION_REDIS_SESSION_KEY_PREFIX`
- `AUTHSESSION_REDIS_USER_SESSIONS_KEY_PREFIX`
- `AUTHSESSION_REDIS_USER_ACTIVE_SESSIONS_KEY_PREFIX`
- `AUTHSESSION_REDIS_SESSION_LIMIT_KEY`
- `AUTHSESSION_REDIS_GATEWAY_SESSION_CACHE_KEY_PREFIX`
- `AUTHSESSION_REDIS_GATEWAY_SESSION_EVENTS_STREAM`
- `AUTHSESSION_REDIS_GATEWAY_SESSION_EVENTS_STREAM_MAX_LEN`
- `AUTHSESSION_REDIS_SEND_EMAIL_CODE_THROTTLE_KEY_PREFIX`

User-service integration:

- `AUTHSESSION_USER_SERVICE_MODE=stub|rest`
- `AUTHSESSION_USER_SERVICE_BASE_URL`
- `AUTHSESSION_USER_SERVICE_REQUEST_TIMEOUT`

Mail-service integration:

- `AUTHSESSION_MAIL_SERVICE_MODE=stub|rest`
- `AUTHSESSION_MAIL_SERVICE_BASE_URL`
- `AUTHSESSION_MAIL_SERVICE_REQUEST_TIMEOUT`

Telemetry:

- `OTEL_SERVICE_NAME`
- `OTEL_TRACES_EXPORTER`
- `OTEL_METRICS_EXPORTER`
- `OTEL_EXPORTER_OTLP_PROTOCOL`
- `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`
- `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL`
- `AUTHSESSION_OTEL_STDOUT_TRACES_ENABLED`
- `AUTHSESSION_OTEL_STDOUT_METRICS_ENABLED`

## Runtime Notes

- user-service and mail-service default to `stub`, which keeps local startup
  backward-compatible and does not require external URLs
- read-style user-service REST methods retry once on transport errors and HTTP
  `502`, `503`, or `504`
- user-service mutation methods do not auto-retry
- mail-service REST requests do not auto-retry, to avoid duplicate delivery
- authsession exports telemetry through OTel providers only; it does not serve
  Prometheus text exposition directly