galaxy-game/gateway/docs/flows.md

Request and Push Flows

Public Auth Flow

sequenceDiagram
    participant Client
    participant Gateway
    participant Limiter as Public anti-abuse
    participant Auth as AuthServiceClient

    Client->>Gateway: POST /api/v1/public/auth/send-email-code
    Gateway->>Limiter: classify + rate-limit + body checks
    Limiter-->>Gateway: allowed
    Gateway->>Auth: SendEmailCode(email)
    Auth-->>Gateway: challenge_id
    Gateway-->>Client: 200 {challenge_id}

    Client->>Gateway: POST /api/v1/public/auth/confirm-email-code
    Gateway->>Limiter: classify + rate-limit + body checks
    Limiter-->>Gateway: allowed
    Gateway->>Auth: ConfirmEmailCode(challenge_id, code, client_public_key, time_zone)
    Auth-->>Gateway: device_session_id
    Gateway-->>Client: 200 {device_session_id}

Authenticated ExecuteCommand Flow

sequenceDiagram
    participant Client
    participant Gateway
    participant Cache as SessionCache
    participant Replay as ReplayStore
    participant Policy as Rate limit / policy
    participant Downstream

    Client->>Gateway: ExecuteCommand(envelope, payload_bytes, signature)
    Gateway->>Gateway: validate envelope + protocol_version
    Gateway->>Cache: lookup(device_session_id)
    Cache-->>Gateway: session record
    Gateway->>Gateway: verify payload_hash
    Gateway->>Gateway: verify Ed25519 signature
    Gateway->>Gateway: verify freshness window
    Gateway->>Replay: reserve(device_session_id, request_id, ttl)
    Replay-->>Gateway: accepted
    Gateway->>Policy: apply IP/session/user/message_type budgets
    Policy-->>Gateway: allowed
    Gateway->>Downstream: verified authenticated command
    Downstream-->>Gateway: result_code + payload_bytes
    Gateway->>Gateway: hash payload + sign response
    Gateway-->>Client: ExecuteCommandResponse + signature

Direct Gateway -> User Self-Service Flow

sequenceDiagram
    participant Client
    participant Gateway
    participant User as User Service

    Client->>Gateway: ExecuteCommand(user.account.get | user.profile.update | user.settings.update)
    Gateway->>Gateway: verify envelope + session + signature + replay
    Gateway->>Gateway: decode FlatBuffers payload
    Gateway->>User: trusted REST/JSON internal request
    User-->>Gateway: JSON account aggregate or JSON error envelope
    Gateway->>Gateway: encode FlatBuffers success or error payload
    Gateway->>Gateway: sign response
    Gateway-->>Client: ExecuteCommandResponse(result_code, payload_bytes, signature)

SubscribeEvents Lifecycle

sequenceDiagram
    participant Client
    participant Gateway
    participant Cache as SessionCache
    participant Replay as ReplayStore
    participant Hub as PushHub
    participant Stream as Client event stream
    participant Sess as Session event stream

    Client->>Gateway: SubscribeEvents(envelope, signature)
    Gateway->>Gateway: validate envelope + verify request
    Gateway->>Cache: lookup(device_session_id)
    Cache-->>Gateway: session record
    Gateway->>Replay: reserve(device_session_id, request_id, ttl)
    Replay-->>Gateway: accepted
    Gateway->>Client: gateway.server_time event
    Gateway->>Hub: register(user_id, device_session_id)

    Stream-->>Gateway: client-facing event for user_id / device_session_id
    Gateway->>Hub: publish signed event
    Hub-->>Client: matching event delivery

    Sess-->>Gateway: revoked session snapshot
    Gateway->>Hub: revoke(device_session_id)
    Hub-->>Client: stream closes with FAILED_PRECONDITION

    Note over Gateway,Hub: During shutdown the gateway closes PushHub before gRPC graceful stop.
    Hub-->>Client: stream closes with UNAVAILABLE