ui calculator
This commit is contained in:
Ilia Denisov
@@ -1,34 +1,229 @@
|
||||
# Galaxy
|
||||
# Services Architecture
|
||||
|
||||
Galaxy is a turn-based strategy game which took place in space.
|
||||
Galaxy Plus: Turn-based Strategy Game
|
||||
|
||||
At the highest level Game has a Backend service and an UI Client.
|
||||
## Purpose
|
||||
|
||||
## Backend service
|
||||
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.
|
||||
|
||||
Backend service is presented by several "microservices" with a different set of responsibilities.
|
||||
## Main Principles
|
||||
|
||||
- AuthN Proxy Service: handles all incoming requests,
|
||||
immediately rejects not-authenticated requests and passes authenticated request to the next service.
|
||||
- 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.
|
||||
- Push / long-polling delivery is also handled by the gateway.
|
||||
|
||||
- AuthZ Service: checks permissions avaliable to the authenticated user and passes request to the next service
|
||||
if user is authorized to use specific game api.
|
||||
## Main Components
|
||||
|
||||
- Games Orchestrator Service:
|
||||
- finds appropriate Game Server according to Client's request data,
|
||||
- passes user's commands to the selected Game Server,
|
||||
- reads response and bounces it back up to request chain to the Client,
|
||||
- manages Game Server state for health monitoring and making next turn.
|
||||
### 1. Edge Gateway
|
||||
|
||||
- Game Servers: several instances of ongoing games with avaliable unprotected API ready to receive Player's and Administrator's commands.
|
||||
The gateway is the only public entry point for client traffic.
|
||||
|
||||
## UI Client
|
||||
Responsibilities:
|
||||
|
||||
UI Client is capable of:
|
||||
- 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
|
||||
- long-polling / push connection handling
|
||||
- delivery of client-facing events from pub/sub
|
||||
|
||||
- Register a new player and login for an existing player using only e-mail and one-time codes,
|
||||
- Enlist to a new Game from available onboard Games list,
|
||||
- Request list of Games in which Player participating,
|
||||
- Request, store and display particular Game data,
|
||||
- Use push-like mechanism for receiving asynchronous updates from Server,
|
||||
- Offline mode when no internet connection is available or user desired to work offline.
|
||||
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 `command_type`
|
||||
|
||||
No business service should receive an unauthenticated external request.
|
||||
|
||||
### Push / Long-Polling Flow
|
||||
|
||||
The gateway owns external push / long-polling connections.
|
||||
|
||||
Flow:
|
||||
|
||||
1. client opens authenticated push / long-polling connection through gateway
|
||||
2. gateway binds connection to `user_id` and `device_session_id`
|
||||
3. gateway may send current server time for clock offset calculation
|
||||
4. internal services publish client-facing events to pub/sub
|
||||
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`
|
||||
- `command_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 push / long-polling connections 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