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

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