galaxy-game/authsession/docs/runtime.md

Runtime and Components

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

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