feat: authsession service

2026-04-08 16:23:07 +02:00
parent 28f04916af
commit 86a68ed9d0
174 changed files with 31732 additions and 112 deletions
@@ -0,0 +1,176 @@
+# 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