feat: backend service

gateway/docs/runtime.md

@@ -14,48 +14,47 @@ flowchart LR
         PublicHTTP["Public HTTP listener\n/healthz /readyz /api/v1/public/auth/*"]
         AuthGRPC["Authenticated gRPC listener\nExecuteCommand / SubscribeEvents"]
         AdminHTTP["Optional admin HTTP listener\n/metrics"]
-        SessionSnap["In-memory session snapshot cache"]
+        BackendREST["backendclient.RESTClient\nsessions + public auth + user/lobby"]
+        BackendPush["backendclient.PushClient\nSubscribePush consumer"]
         Replay["Replay reservation client"]
         PushHub["PushHub"]
-        SessSub["Session event subscriber"]
-        ClientSub["Client event subscriber"]
+        Dispatcher["Push event dispatcher"]
         Telemetry["Logs, traces, metrics"]
     end
 
     Public --> PublicHTTP
     Authd --> AuthGRPC
-    AuthGRPC --> SessionSnap
+    PublicHTTP --> BackendREST
+    AuthGRPC --> BackendREST
     AuthGRPC --> Replay
     AuthGRPC --> PushHub
-    SessSub --> SessionSnap
-    SessSub --> PushHub
-    ClientSub --> PushHub
+    BackendPush --> Dispatcher
+    Dispatcher --> PushHub
     PublicHTTP --> Telemetry
     AuthGRPC --> Telemetry
     AdminHTTP --> Telemetry
 
-    Redis["Redis\nsession records + replay keys + streams"]
-    AuthSvc["Auth / Session Service"]
-    Downstream["Downstream business services"]
+    Redis["Redis\nanti-replay reservations only"]
+    Backend["backend service\nHTTP + gRPC"]
     Metrics["Prometheus / OTLP collectors"]
 
-    PublicHTTP -. public auth adapter .-> AuthSvc
-    SessionSnap --> Redis
+    BackendREST --> Backend
+    BackendPush --> Backend
     Replay --> Redis
-    SessSub --> Redis
-    ClientSub --> Redis
-    AuthGRPC --> Downstream
     Telemetry --> Metrics
 ```
 
 Notes:
 
-- `cmd/gateway` refuses startup when Redis connectivity or the response signer
-  is misconfigured.
+- `cmd/gateway` refuses startup when Redis connectivity, the backend endpoint,
+  or the response signer is misconfigured.
+- Session lookup is synchronous: every authenticated gRPC request triggers one
+  `GET /api/v1/internal/sessions/{id}` call to backend; there is no
+  process-local projection.
+- `backendclient.PushClient` keeps a long-lived `Push.SubscribePush` stream
+  open. The dispatcher converts inbound `pushv1.PushEvent` frames into either
+  `PushHub.Publish` (for client events) or `PushHub.RevokeDeviceSession` /
+  `PushHub.RevokeAllForUser` (for `session_invalidation`).
+- `user.*` and `lobby.*` authenticated routes are forwarded to backend through
+  the same REST client, with `X-User-Id` carrying the verified identity.
 - The admin listener is optional and serves only Prometheus text metrics.
-- Public auth routing stays available without an upstream adapter, but returns
-  `503 service_unavailable`.
-- The default runtime reserves direct `user.*` authenticated self-service
-  routes. When `GATEWAY_USER_SERVICE_BASE_URL` is unset those routes stay
-  mounted but fail closed as dependency-unavailable instead of returning a
-  route miss.