docs: rename file
This commit is contained in:
IliaDenisov
+254
@@ -0,0 +1,254 @@
|
||||
# Services Architecture
|
||||
|
||||
Galaxy Plus: Turn-based Strategy Game
|
||||
|
||||
## Purpose
|
||||
|
||||
This document fixes the high-level service architecture of the system.
|
||||
It is the starting point for implementing the external edge layer, authentication/session management, business services, and push delivery.
|
||||
|
||||
## Main Principles
|
||||
|
||||
- The system exposes a single external entry point: **Edge Gateway**.
|
||||
- Internal business services are **not reachable directly from outside**.
|
||||
- Any external command, except public auth commands, must be authenticated before it is routed further.
|
||||
- Gateway handles only edge concerns. Business validation and domain rules remain inside business services.
|
||||
- Gateway owns external delivery channels; the v1 implementation uses
|
||||
authenticated gRPC server-streaming push, while long-polling remains out of
|
||||
scope.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Client["Clients\n(native and browser)"]
|
||||
Gateway["Edge Gateway\npublic REST + authenticated gRPC"]
|
||||
Auth["Auth / Session Service"]
|
||||
Business["Business Services"]
|
||||
Redis["Redis\nsession cache + replay keys + event streams"]
|
||||
Telemetry["Telemetry Backends\nPrometheus / OTLP"]
|
||||
|
||||
Client --> Gateway
|
||||
Gateway --> Auth
|
||||
Gateway --> Business
|
||||
Gateway --> Redis
|
||||
Gateway --> Telemetry
|
||||
Auth --> Redis
|
||||
Business --> Redis
|
||||
```
|
||||
|
||||
## Main Components
|
||||
|
||||
### 1. Edge Gateway
|
||||
|
||||
The gateway is the only public entry point for client traffic.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- transport parsing
|
||||
- authentication of external requests
|
||||
- transport integrity checks
|
||||
- session cache lookup
|
||||
- request signature verification
|
||||
- timestamp window verification
|
||||
- anti-replay checks
|
||||
- rate limiting and abuse protection
|
||||
- command routing
|
||||
- basic policy enforcement
|
||||
- authenticated gRPC server-streaming push connection handling
|
||||
- delivery of client-facing events from pub/sub
|
||||
|
||||
The gateway must not implement domain-specific business logic.
|
||||
|
||||
### 2. Auth / Session Service
|
||||
|
||||
This service owns authentication and device session lifecycle.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- `send_email_code`
|
||||
- `confirm_email_code`
|
||||
- device session creation
|
||||
- public key registration for device sessions
|
||||
- session revoke / logout
|
||||
- persistence of session state
|
||||
- publishing session state changes for cache invalidation/update
|
||||
|
||||
This service is the source of truth for `device_session` state.
|
||||
|
||||
### 3. Session Store
|
||||
|
||||
Persistent storage for device sessions.
|
||||
|
||||
Typical fields:
|
||||
|
||||
- `device_session_id`
|
||||
- `user_id`
|
||||
- client public key
|
||||
- session status
|
||||
- creation / revoke timestamps
|
||||
- optional client metadata
|
||||
|
||||
### 4. Session Cache
|
||||
|
||||
Fast lookup cache used by the gateway.
|
||||
|
||||
Purpose:
|
||||
|
||||
- resolve `device_session_id -> user_id + public_key + status`
|
||||
- avoid synchronous calls from gateway to auth/session service on every request
|
||||
|
||||
Cache updates should be driven by session lifecycle events and may also use TTL.
|
||||
|
||||
### 5. Anti-Replay Store
|
||||
|
||||
Edge-level storage for recently seen transport `request_id` values.
|
||||
|
||||
Purpose:
|
||||
|
||||
- reject replayed authenticated transport messages within the allowed time window
|
||||
|
||||
This is transport-level replay protection, not business idempotency.
|
||||
|
||||
### 6. Rate Limit Store
|
||||
|
||||
Shared state for edge-level throttling and abuse control.
|
||||
|
||||
Typical dimensions:
|
||||
|
||||
- IP / network
|
||||
- `device_session_id`
|
||||
- `user_id`
|
||||
- command class
|
||||
|
||||
### 7. Business Services
|
||||
|
||||
Internal services that process authenticated commands.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- business validation
|
||||
- authorization by `user_id`
|
||||
- ownership checks
|
||||
- domain invariants
|
||||
- state transitions
|
||||
- business idempotency where required
|
||||
- publishing domain events and/or client-facing events
|
||||
|
||||
Business services do not verify external signatures and do not access external clients directly.
|
||||
|
||||
### 8. Event Bus / Pub-Sub
|
||||
|
||||
Used for internal event distribution.
|
||||
|
||||
Purposes:
|
||||
|
||||
- session cache invalidation/update
|
||||
- client-facing event delivery through the gateway
|
||||
- optional internal domain event propagation between services
|
||||
|
||||
## External Flows
|
||||
|
||||
### Public Auth Flow
|
||||
|
||||
These commands are public and do not require an existing device session:
|
||||
|
||||
- `send_email_code`
|
||||
- `confirm_email_code`
|
||||
|
||||
Flow:
|
||||
|
||||
1. client sends public auth command to gateway
|
||||
2. gateway applies public-edge checks (format, rate limits, abuse policy)
|
||||
3. gateway routes command to auth/session service
|
||||
4. auth/session service performs auth logic
|
||||
5. if login is confirmed, auth/session service creates `device_session`
|
||||
6. auth/session service publishes cache update/invalidation event
|
||||
|
||||
### Authenticated Command Flow
|
||||
|
||||
All other external commands require authentication.
|
||||
|
||||
Flow:
|
||||
|
||||
1. client sends authenticated request to gateway
|
||||
2. gateway validates transport envelope presence and protocol version
|
||||
3. gateway resolves `device_session_id` through session cache
|
||||
4. gateway rejects unknown or revoked sessions
|
||||
5. gateway verifies request signature
|
||||
6. gateway verifies timestamp window
|
||||
7. gateway verifies anti-replay constraints
|
||||
8. gateway applies rate limits and basic policy checks
|
||||
9. gateway extracts authenticated context, including `user_id`
|
||||
10. gateway routes the request to the target business service based on `message_type`
|
||||
|
||||
No business service should receive an unauthenticated external request.
|
||||
|
||||
### Push Flow
|
||||
|
||||
The gateway owns external delivery connections.
|
||||
The v1 gateway uses authenticated gRPC server-streaming push.
|
||||
Long-polling remains out of scope for the implemented gateway.
|
||||
|
||||
Flow:
|
||||
|
||||
1. client opens authenticated push connection through gateway
|
||||
2. gateway binds connection to `user_id` and `device_session_id`
|
||||
3. gateway starts the channel with a signed service event that includes the
|
||||
current server time for clock offset calculation
|
||||
4. internal services publish client-facing events to pub/sub targeted by
|
||||
`user_id` and optionally by `device_session_id`
|
||||
5. gateway consumes those events and delivers them to the proper client
|
||||
connections
|
||||
|
||||
Gateway is a delivery layer, not the source of business events.
|
||||
|
||||
## Internal Contract Between Gateway and Business Services
|
||||
|
||||
Business services should receive an internal authenticated command, not raw external transport data.
|
||||
|
||||
Typical internal authenticated context:
|
||||
|
||||
- `user_id`
|
||||
- `device_session_id`
|
||||
- `message_type`
|
||||
- verified payload bytes
|
||||
- transport `request_id`
|
||||
- optional command id / trace id
|
||||
- optional client metadata relevant for logging
|
||||
|
||||
Business services must trust only the gateway as their external ingress.
|
||||
|
||||
## Separation of Responsibilities
|
||||
|
||||
### Gateway is responsible for
|
||||
|
||||
- who sent the request
|
||||
- whether transport integrity is valid
|
||||
- whether the request is fresh
|
||||
- whether replay is detected
|
||||
- whether request volume is acceptable
|
||||
- where to route the request
|
||||
|
||||
### Business services are responsible for
|
||||
|
||||
- whether the user is allowed to perform the business action
|
||||
- whether the target object belongs to the user
|
||||
- whether the domain state transition is valid
|
||||
- whether business idempotency rules are satisfied
|
||||
|
||||
## Revocation Behavior
|
||||
|
||||
When a device session is revoked:
|
||||
|
||||
- auth/session service updates the source of truth
|
||||
- auth/session service publishes revoke/invalidation event
|
||||
- gateway updates or invalidates session cache
|
||||
- gateway rejects further requests for that session
|
||||
- gateway closes active authenticated push streams bound to that session, if applicable
|
||||
|
||||
## Non-Goals
|
||||
|
||||
The gateway is not a place for full domain authorization logic.
|
||||
It must not become a business “god service”.
|
||||
|
||||
The auth/session service is not the hot path for every authenticated request.
|
||||
The gateway should authenticate most requests from cache, not by synchronous round-trips.
|
||||
Reference in New Issue
Block a user