developer/galaxy-game
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat: support time_zone for user registration context

Browse Source
This commit is contained in:
Ilia Denisov
2026-04-09 09:00:06 +02:00
parent e6b73a8f55
commit 7043af4cb3
40 changed files with 3452 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files
user/PLAN.md
+644
View File
@@ -0,0 +1,644 @@
# User Service Implementation Plan
## Planning Principles
This plan is aligned with the current repository architecture and is written
for an experienced middle-level Go developer implementing an internal trusted
microservice.
Execution priorities:
- preserve the frozen auth and geo ownership boundaries
- keep user state authoritative in one service
- prefer explicit command behavior over generic patch behavior
- keep synchronous read paths simple for auth and lobby
- separate current effective state from append-only or historical records where
fast reads matter
- keep the first version storage-agnostic at the domain boundary even if Redis
is the initial backend
## Stage 01 — Freeze Vocabulary, Contracts, and Cross-Service Ownership
### Goal
Remove naming ambiguity and freeze the service boundary before implementation.
### Tasks
- Freeze the regular-user-only scope of `User Service`.
- Freeze that system-admin identity is out of scope and belongs to later
`Admin Service`.
- Freeze the self-service vocabulary:
- `GetMyAccount`
- `UpdateMyProfile`
- `UpdateMySettings`
- Freeze that `race_name` replaces `display_name`.
- Freeze the current ownership split for `declared_country`:
- current value in `User Service`
- workflow and history in `Geo Profile Service`
- Freeze the auth-facing internal REST endpoints already reserved by
`Auth / Session Service`.
- Freeze the need for create-only registration context on
`EnsureUserByEmail`.
### Deliverables
- service README with stable terminology
- short internal ADR or equivalent note for `declared_country` ownership split
- short internal ADR or equivalent note for regular-user versus admin identity
split
### Exit Criteria
- no unresolved naming conflict remains around `race_name`,
`declared_country`, entitlement, sanction, or limit semantics
- no service boundary question remains open for auth, lobby, or geo
### Targeted Tests
- none yet beyond documentation review
## Stage 02 — Define Domain Entities and Redis-Backed Logical State
### Goal
Describe the persistent state clearly enough that storage adapters can be built
without revisiting core semantics.
### Tasks
- Define logical entities for:
- user account
- race-name reservation
- blocked e-mail subject
- entitlement period record
- current entitlement snapshot
- sanction record
- limit record
- Freeze required fields, timestamps, and identifiers for each entity.
- Decide Redis logical key layout and lookup indexes without leaking them into
the domain layer.
- Freeze deterministic pagination keys for admin listing.
- Define how active/effective evaluation works for sanctions and limits.
### Deliverables
- domain entity definitions
- storage design notes for Redis keys and secondary indexes
- active/effective evaluation rules
### Exit Criteria
- every required read and mutation can map to a clear logical entity set
- Redis adapters can be implemented directly from the frozen logical model
### Targeted Tests
- domain validation tests for required fields
- tests for effective-state evaluation of active versus expired records
## Stage 03 — Implement Auth-Facing Resolution, Ensure, Existence, and E-Mail Blocking
### Goal
Provide the minimum trusted API needed by `Auth / Session Service`.
### Tasks
- Implement:
- resolve by e-mail
- ensure by e-mail
- exists by user id
- block by user id
- block by e-mail
- Preserve exact route shapes already reserved by the auth REST client.
- Implement the separate blocked-email-subject model.
- Make `BlockByEmail` idempotent for both existing-user and no-user cases.
- Ensure `ResolveByEmail` and `EnsureUserByEmail` both respect blocked-email
subjects.
### Deliverables
- trusted internal REST handlers for auth-facing endpoints
- domain services for resolution and block behavior
- Redis-backed storage for user existence and blocked-email subjects
### Exit Criteria
- auth can distinguish `existing`, `creatable`, and `blocked`
- blocked e-mail subjects prevent user creation before a user exists
- `BlockByUserID` and `BlockByEmail` are idempotent
### Targeted Tests
- resolve existing/creatable/blocked by e-mail
- ensure existing/created/blocked outcomes
- blocked e-mail subject prevents creation before user record exists
- block by user id on unknown user returns not found
- repeated block calls stay idempotent
## Stage 04 — Add New-User Creation Context from Auth
### Goal
Support first-login user creation with initial settings captured at confirm
time.
### Tasks
- Extend `EnsureUserByEmail` contract with create-only registration context:
- `preferred_language`
- `time_zone`
- Validate `preferred_language` as BCP 47.
- Validate `time_zone` as IANA TZ name.
- Generate initial `race_name` in `player-<shortid>` form during creation.
- Initialize the newly created user with:
- free entitlement
- no active sanctions
- no custom limits
- Ignore registration context for existing users.
- Document required follow-up changes in `gateway` and `authsession`.
### Deliverables
- extended ensure-by-email request model
- create-user domain service
- generated-race-name helper
### Exit Criteria
- first successful ensure-create path can fully initialize a new user
- existing-user ensure does not overwrite language or time zone
### Targeted Tests
- new user created with generated `race_name`, derived `preferred_language`,
and required client `time_zone`
- existing user ensure ignores create-only registration context
- invalid BCP 47 or IANA inputs are rejected on create path
## Stage 05 — Implement Self-Service Account Read and Split Profile/Settings Mutations
### Goal
Expose the minimal authenticated account surface routed by `Edge Gateway`.
### Tasks
- Implement `GetMyAccount`.
- Implement `UpdateMyProfile` for `race_name` only.
- Implement `UpdateMySettings` for:
- `preferred_language`
- `time_zone`
- Ensure `GetMyAccount` returns:
- account identity fields
- current entitlement snapshot
- active sanctions
- active effective limits
- read-only `declared_country`
- Reject attempts to mutate `email` or `declared_country` through self-service
flows.
- Enforce `profile_update_block` sanction on both self-service mutations.
### Deliverables
- authenticated application services for account read and updates
- gateway-facing handler or adapter contracts for future routing
- DTOs for account aggregate and mutation requests
### Exit Criteria
- authenticated users can read current account state in one aggregate
- profile and settings changes are clearly separated
- self-service updates cannot mutate forbidden fields
### Targeted Tests
- `GetMyAccount` returns current entitlement, active sanctions, active limits,
and read-only `declared_country`
- `UpdateMyProfile` cannot change email or `declared_country`
- `UpdateMySettings` validates BCP 47 and IANA values
- active `profile_update_block` denies both update flows
## Stage 06 — Implement race_name Uniqueness Policy Behind a Dedicated Interface
### Goal
Keep `race_name` uniqueness strict and replaceable.
### Tasks
- Introduce a dedicated race-name policy interface.
- Implement canonicalization for uniqueness checks:
- case-insensitive folding
- confusable anti-fraud normalization
- Add Redis-backed reservation storage for canonicalized keys.
- Preserve original casing for stored and returned `race_name`.
- Ensure rename flow handles reservation swap safely.
- Keep the interface narrow so a future shared name-catalog service can replace
the local implementation.
### Deliverables
- race-name policy interface
- local normalization implementation
- reservation adapter and conflict handling
### Exit Criteria
- no two users can hold conflicting `race_name` values under the frozen policy
- self-service rename is atomic with respect to uniqueness reservation
### Targeted Tests
- uniqueness rejects case-insensitive collisions
- uniqueness rejects common anti-fraud-confusable collisions
- rename releases the old reservation only after the new one is secured
- failed reservation backend causes mutation to fail closed
## Stage 07 — Implement Entitlement History Plus Materialized Current Snapshot
### Goal
Support both auditability and fast synchronous entitlement reads.
### Tasks
- Implement period-based entitlement history records.
- Implement a materialized current entitlement snapshot.
- Define the v1 plan catalog:
- `free`
- `paid_monthly`
- `paid_yearly`
- `paid_lifetime`
- Implement explicit trusted entitlement commands:
- grant paid access
- extend paid access
- revoke paid access
- Update current snapshot transactionally with each successful entitlement
mutation.
- Ensure the default new-user path creates the correct free snapshot.
### Deliverables
- entitlement domain model
- history store
- current snapshot store
- trusted entitlement command handlers
### Exit Criteria
- current effective entitlement is always readable without replaying history
- history and snapshot stay consistent across supported mutation paths
### Targeted Tests
- entitlement period mutations update the materialized current snapshot
correctly
- free default is created for new users
- extending or revoking access preserves deterministic current-state behavior
## Stage 08 — Implement Sanctions and Limit Records with Active/Effective Evaluation
### Goal
Support negative policy and quota overrides without scattering policy logic into
consumers.
### Tasks
- Implement sanction records with optional expiry.
- Implement limit records with numeric values and optional expiry.
- Freeze v1 sanction catalog:
- `login_block`
- `private_game_create_block`
- `private_game_manage_block`
- `game_join_block`
- `profile_update_block`
- Freeze v1 limit catalog:
- `max_owned_private_games`
- `max_active_private_games`
- `max_pending_public_applications`
- `max_pending_private_join_requests`
- `max_pending_private_invites_sent`
- `max_active_game_memberships`
- Implement active/effective evaluation with current time.
- Implement trusted explicit commands to apply/remove sanctions and set/remove
limits.
### Deliverables
- sanction model and store
- limit model and store
- effective-state evaluator
- trusted mutation handlers
### Exit Criteria
- active sanctions and active limits can be read consistently from one user
account view
- expired or removed records are not treated as active
### Targeted Tests
- active sanctions appear in account reads
- expired sanctions and limits stop affecting effective state
- applying and removing sanctions/limits is idempotent where appropriate
## Stage 09 — Implement Lobby Eligibility Snapshot API
### Goal
Give `Game Lobby` one synchronous read that contains everything it needs for
user-level access decisions.
### Tasks
- Design and implement one trusted query by `user_id`.
- Return:
- existence
- current entitlement snapshot
- active lobby-relevant sanctions
- effective lobby-relevant limits
- derived booleans for lobby decisions
- Keep the response read-optimized so lobby does not need multiple dependent
calls back into `User Service`.
- Define deterministic not-found behavior.
### Deliverables
- lobby eligibility query endpoint
- response DTO
- mapping from entitlement/sanction/limit state to derived eligibility fields
### Exit Criteria
- `Game Lobby` can decide create/join/manage eligibility from one read
- no extra fan-out to other user sub-queries is required
### Targeted Tests
- lobby eligibility snapshot reflects paid status, sanctions, and limits
- unknown user returns stable not-found behavior
- derived booleans remain consistent with raw effective state
## Stage 10 — Implement Geo declared_country Sync Command
### Goal
Support the current-country denormalization path owned by `Geo Profile Service`.
### Tasks
- Implement one explicit trusted command to sync current `declared_country`.
- Validate ISO alpha-2 input.
- Ensure the command updates only the current value on the user account.
- Do not add country history behavior to `User Service`.
- Preserve explicit not-found behavior for unknown `user_id`.
- Emit the corresponding auxiliary declared-country change event after a
successful commit.
### Deliverables
- geo-facing sync endpoint
- application service for country sync
- event publication on successful mutation
### Exit Criteria
- geo can synchronize current `declared_country` without introducing hidden
history in `User Service`
- unknown users are rejected deterministically
### Targeted Tests
- geo country sync changes only current `declared_country`
- invalid country codes are rejected
- country sync emits the correct auxiliary event after commit
## Stage 11 — Implement Admin Lookup, Filtered Listing, and Explicit Trusted Mutations
### Goal
Provide the operational surface required by future `Admin Service` and manual
operations.
### Tasks
- Implement exact reads by:
- `user_id`
- normalized `email`
- exact `race_name`
- Implement paginated listing with richer filters:
- paid/free state
- paid expiry
- current `declared_country`
- sanction code
- limit code
- eligibility markers
- Freeze deterministic ordering for the listing.
- Implement the explicit trusted command surface for:
- entitlement grant/extend/revoke
- sanction apply/remove
- limit set/remove
- declared-country sync
- Preserve audit metadata on every trusted mutation.
### Deliverables
- admin/internal read endpoints
- filtered listing endpoint
- explicit trusted mutation endpoints
### Exit Criteria
- future `Admin Service` can operate fully through this trusted API without
needing direct storage access
- list filtering and pagination are deterministic
### Targeted Tests
- admin listing filters behave deterministically
- exact lookups by `user_id`, email, and `race_name` resolve the correct user
- every trusted mutation preserves actor and reason metadata
## Stage 12 — Add Per-Domain-Area Async Events and Observability
### Goal
Make production behavior observable without treating events as the source of
truth.
### Tasks
- Publish per-domain-area events for:
- profile changes
- settings changes
- entitlement changes
- sanction changes
- limit changes
- declared-country changes
- Add structured logs for trusted mutations and critical failures.
- Add metrics for:
- auth-facing resolution outcomes
- user creation outcomes
- race-name reservation conflicts
- entitlement mutation outcomes
- sanction and limit mutation outcomes
- event publication failures
- Add tracing spans on synchronous internal request paths where useful.
### Deliverables
- event publisher integration
- structured logging hooks
- metrics and tracing instrumentation
### Exit Criteria
- mutation flows are observable in production without ad hoc logging
- event publication failure does not compromise source-of-truth persistence
### Targeted Tests
- async event publication failure does not lose source-of-truth state
- event payloads include minimum required metadata
- observability hooks do not change business behavior
## Stage 13 — Add Contract Tests Against Auth, Lobby, and Geo Expectations
### Goal
Verify the service not only in isolation, but against the internal contracts it
must satisfy for other services.
### Tasks
- Add compatibility tests against the frozen auth-facing REST contract.
- Add compatibility tests for the future ensure-by-email registration context.
- Add lobby eligibility snapshot contract tests.
- Add geo country-sync contract tests.
- Add account aggregate tests matching gateway-routed user expectations.
- Add tests for deterministic admin listing filters and ordering.
### Deliverables
- cross-service contract test suite
- test fixtures for auth/lobby/geo integration expectations
### Exit Criteria
- no ambiguity remains about service behavior expected by auth, lobby, or geo
- regressions in reserved internal contract shapes are caught automatically
### Targeted Tests
- new user created on first successful confirm with generated `race_name`,
derived `preferred_language`, and required client `time_zone`
- existing user confirm ignores create-only registration context
- blocked e-mail subject prevents user creation before a user record exists
- `GetMyAccount` returns current entitlement, active sanctions, active limits,
and read-only `declared_country`
- lobby eligibility snapshot reflects paid status, sanctions, and limits
- geo country sync changes only current `declared_country`
## Stage 14 — Add Rollout Notes for Gateway/Auth/OpenAPI Updates and Shared geoip
### Goal
Prepare the surrounding platform changes required for the service to work in
its intended end-to-end form.
### Tasks
- Document the required `gateway` public `confirm-email-code` addition of
`time_zone`.
- Document the required `authsession` public OpenAPI mirror change.
- Document the required `authsession -> user` ensure contract extension for
create-only registration context.
- Document the required shared `pkg/geoip` package for gateway and geo.
- Document README follow-up updates needed in `gateway` and `geoprofile`.
- Define rollout order so the cross-service contract changes do not land in an
unsafe sequence.
### Deliverables
- rollout checklist
- dependency order notes
- cross-repo or cross-module follow-up ticket list
### Exit Criteria
- the implementation can be integrated into surrounding services without
rediscovering hidden dependencies
- no required upstream or downstream change is left implicit
### Targeted Tests
- documentation review only
## Recommended First Working Slice
The smallest useful end-to-end slice is:
1. Stage 01
2. Stage 02
3. Stage 03
4. Stage 04
This slice makes it possible to support auth-driven user creation and blocking
before the rest of the service surface exists.
## Recommended Second Slice
The next highest-value slice is:
1. Stage 05
2. Stage 06
3. Stage 07
4. Stage 08
5. Stage 09
This slice gives the platform usable account reads, self-service profile and
settings updates, and the lobby eligibility integration.
## Final Acceptance Criteria
The first production-capable v1 of `User Service` should satisfy all of the
following:
- new users can be created through auth with generated `race_name`, derived
`preferred_language`, and required client `time_zone`
- existing-user auth confirm ignores create-only registration context
- blocked e-mail subjects prevent new-user creation before a user record exists
- `race_name` uniqueness rejects case-insensitive and anti-fraud-confusable
collisions
- `GetMyAccount` returns current entitlement, active sanctions, active limits,
and read-only `declared_country`
- `UpdateMyProfile` cannot change email or `declared_country`
- `UpdateMySettings` validates BCP 47 and IANA values
- entitlement period mutations update the materialized current snapshot
correctly
- lobby eligibility snapshot reflects paid status, sanctions, and limits
- geo `declared_country` sync changes only current account state
- admin listing filters and ordering are deterministic
- async event publication failure does not lose source-of-truth state
## Implementation Order Summary
Recommended implementation order:
1. freeze vocabulary and ownership
2. define domain entities and logical storage
3. build auth-facing resolution and blocking
4. add new-user creation context
5. build self-service account read and updates
6. add race-name uniqueness policy
7. build entitlement history and current snapshot
8. build sanctions and limits
9. add lobby eligibility snapshot
10. add geo country sync
11. add admin reads, listing, and mutations
12. add events and observability
13. add cross-service contract tests
14. document and sequence rollout dependencies
user/README.md
+801
View File
@@ -0,0 +1,801 @@
# User Service
## Context and Purpose
`User Service` is the internal source of truth for regular Galaxy Plus platform
users.
The service exists to solve six closely related problems:
- Own the durable platform user account identified by `user_id`.
- Store the current editable self-service profile and settings of a user.
- Materialize the current effective entitlement state used by the rest of the
platform.
- Store user-specific sanctions and limit overrides that affect access
decisions.
- Expose synchronous trusted APIs needed by `Auth / Session Service`,
`Game Lobby`, `Geo Profile Service`, and future administrative tooling.
- Publish auxiliary user-domain change events without turning events into the
source of truth.
The service is intentionally the owner of regular user identity only.
System-administrator identity is outside this service and belongs to the later
`Admin Service` architecture.
## Explicit Non-Goals
The following are intentionally out of scope for this service:
- Authentication challenges, device sessions, or request-signing state.
- System-administrator identity or administrator role management.
- Ownership of game membership, invites, roster, or per-game moderation.
- Automatic billing computation or payment-provider integration in v1.
- History of `declared_country` changes.
- Geo-IP lookup or country-review workflow logic.
- Direct public unauthenticated exposure.
- Using async events as the authoritative representation of user state.
## Place in the Existing Microservice System
`User Service` operates inside the trusted internal platform and integrates
with:
- `Edge Gateway`
- `Auth / Session Service`
- `Game Lobby`
- `Geo Profile Service`
- `Admin Service` later
- `Billing Service` later
- internal event bus
`Edge Gateway` routes authenticated user-facing account operations to this
service.
`Auth / Session Service` uses this service to resolve, create, and block users
during the public e-mail-code login flow.
`Game Lobby` uses this service for synchronous eligibility checks that depend
on current entitlement, sanctions, and limit state.
`Geo Profile Service` remains the owner of country-change workflow and history,
but synchronizes the latest effective `declared_country` into this service.
`Admin Service` will later use the trusted internal read and mutation APIs
defined here. Administrator accounts themselves still do not belong to
`User Service`.
`Billing Service` is future-only in v1 and will later feed entitlement
outcomes through the trusted entitlement mutation path defined here.
The event bus is an auxiliary propagation channel and not the source of truth.
## Responsibility Boundaries
`User Service` owns:
- regular platform `user_id`
- login/contact e-mail stored on the user account
- `race_name`
- `preferred_language`
- `time_zone`
- current effective `declared_country`
- current effective entitlement snapshot
- entitlement history records
- active and historical user sanctions
- active and historical user-specific limit overrides
- blocked e-mail subjects that may exist before any user record exists
- synchronous trusted reads used for auth, lobby, geo, and admin workflows
- auxiliary user-domain events
`User Service` does not own:
- system-admin accounts
- `device_session` or revoke state
- full payment history
- game ownership, game membership, or game-level bans
- `declared_country` history or approval workflow
- per-request country observations
## High-Level Architecture
```mermaid
flowchart LR
Gateway[Edge Gateway]
Auth[Auth / Session Service]
Lobby[Game Lobby]
Geo[Geo Profile Service]
Admin[Admin Service]
Billing[Billing Service]
User[User Service]
Redis[Redis]
Bus[Event Bus]
Gateway --> User
Auth --> User
Lobby --> User
Geo --> User
Admin --> User
Billing --> User
User --> Redis
User --> Bus
```
## Semantic Model
The service works with several core concepts.
### User Account
The user account is the canonical regular-user aggregate.
Required logical fields:
- `user_id`
- normalized `email`
- `race_name`
- `preferred_language`
- `time_zone`
- current effective `declared_country`
- creation timestamp
- last update timestamp
Important rules:
- `email` is the primary login/contact identifier for end users.
- `email` is not directly editable through self-service profile updates.
- future e-mail change is a separate confirm-based workflow and is not part of
v1 `User Service` mutations.
- `declared_country` is readable in account views but writable only through the
trusted geo sync path.
### race_name
`race_name` is the user-facing account name.
Properties:
- It is globally unique.
- It is not an identity key. Internal identity remains `user_id`, and end-user
login identity remains `email`.
- It is stored and returned in the original user-provided casing.
- Uniqueness is enforced through a dedicated policy boundary rather than by
naive string equality.
The uniqueness policy must at minimum:
- compare case-insensitively
- reject common confusable substitutions used for impersonation, such as
`I` versus `1`, `O` versus `0`, and `B` versus `8`
- remain replaceable behind a dedicated interface because a future shared name
catalog service is expected
### preferred_language and time_zone
`preferred_language` and `time_zone` are explicit user settings, not inferred
runtime facts.
Properties:
- `preferred_language` uses BCP 47 language tags.
- `time_zone` uses IANA time zone names.
- both values exist on every created user in v1
- both values are editable later through self-service settings mutation
Initial creation rules:
- `preferred_language` is supplied to `User Service` through auth create-only
registration context
- the value is derived by `Edge Gateway` from local geoip country plus local
country-to-language mapping
- when that lookup cannot determine a language, gateway falls back to `en`
- `time_zone` is supplied by the client in public `confirm-email-code`
`User Service` does not perform its own geo lookup for this purpose.
### declared_country
`declared_country` is the latest effective user-declared country.
Properties:
- It uses ISO 3166-1 alpha-2.
- It is the read-optimized current value only.
- It is owned for storage by `User Service`.
- It is owned for mutation workflow and history by `Geo Profile Service`.
This split is intentional:
- reads of current account state go to `User Service`
- reads of review workflow and country history go to `Geo Profile Service`
### Entitlement
Entitlement describes the paid/free access state of a user account.
The plan catalog fixed for v1 is:
- `free`
- `paid_monthly`
- `paid_yearly`
- `paid_lifetime`
The service stores both:
- immutable or append-only entitlement period history records
- a materialized current effective entitlement snapshot for synchronous reads
The current effective snapshot is not computed on every request. It is updated
when trusted entitlement mutations succeed.
Period history records store:
- `user_id`
- `plan_code`
- `source`
- actor identity or actor type
- `reason_code`
- `starts_at`
- optional `ends_at`
- creation timestamp
Current effective snapshot stores at minimum:
- `user_id`
- current `plan_code`
- effective paid/free state
- effective period bounds when applicable
- source metadata needed by operations and admin reads
- last recomputation timestamp
In v1, entitlement mutations come from explicit trusted admin/internal
commands. Later, `Billing Service` uses the same mutation path.
### Sanctions
Sanctions are negative policy records that may deny or restrict access
regardless of entitlement state.
The initial sanction set for v1 is:
- `login_block`
- `private_game_create_block`
- `private_game_manage_block`
- `game_join_block`
- `profile_update_block`
Each sanction record stores:
- `user_id`
- `sanction_code`
- scope
- `reason_code`
- actor identity or actor type
- `applied_at`
- optional `expires_at`
- optional removal metadata if later removed
Sanctions are typed records rather than inline booleans so the service can keep
auditability and deterministic active-state evaluation.
### User-Specific Limits
User-specific limits are count-based override records that shape access and
eligibility decisions.
The initial limit set for v1 is:
- `max_owned_private_games`
- `max_active_private_games`
- `max_pending_public_applications`
- `max_pending_private_join_requests`
- `max_pending_private_invites_sent`
- `max_active_game_memberships`
Each limit record stores:
- `user_id`
- `limit_code`
- numeric value
- `reason_code`
- actor identity or actor type
- `applied_at`
- optional `expires_at`
- optional removal metadata if later removed
Limit rules:
- limits are count-based only in v1
- limits are user-specific overrides, not the global default catalog itself
- effective eligibility combines entitlement-derived defaults with active
user-specific overrides
### Blocked E-Mail Subject
`User Service` must support blocking an e-mail subject before any user account
exists.
This requires a separate blocked-email-subject model.
Required logical fields:
- normalized `email`
- `reason_code`
- block timestamp
- optional actor metadata when available
- optional expiry or removal metadata if policy later requires it
- optional resolved `user_id` when the e-mail already belongs to an existing
user
This model exists to support `Auth / Session Service` flows such as
`BlockByEmail` and `ResolveByEmail` before user creation.
## Data Ownership Rules
The ownership split is intentional and must remain stable.
- `User Service` owns regular user identity and current effective account
state.
- `Auth / Session Service` owns login challenge and session lifecycle state.
- `Game Lobby` owns game membership and game-specific moderation.
- `Geo Profile Service` owns geo workflow and `declared_country` history.
- `Admin Service` later owns administrator identity and UI orchestration.
In particular:
- no service other than `Geo Profile Service` should mutate
`declared_country`
- no service other than `User Service` should create or edit regular user
profile/settings records
- no other service should maintain its own source of truth for current
entitlements
## User-Facing Interface Model
User-facing traffic reaches `User Service` only through authenticated gateway
routing.
The v1 aggregate query is:
- `GetMyAccount`
The v1 self-service mutations are:
- `UpdateMyProfile`
- `UpdateMySettings`
### GetMyAccount
`GetMyAccount` returns one read-optimized account aggregate for the currently
authenticated regular user.
The aggregate should include at minimum:
- `user_id`
- `email`
- `race_name`
- `preferred_language`
- `time_zone`
- current `declared_country`
- current entitlement snapshot
- active sanctions
- active effective limits
- account timestamps needed by clients
`declared_country` is read-only in this aggregate.
### UpdateMyProfile
`UpdateMyProfile` updates self-service profile fields only.
Editable fields in v1:
- `race_name`
Rules:
- e-mail cannot be changed here
- `declared_country` cannot be changed here
- `race_name` must pass global uniqueness policy before commit
- active `profile_update_block` sanction rejects the mutation
### UpdateMySettings
`UpdateMySettings` updates self-service settings only.
Editable fields in v1:
- `preferred_language`
- `time_zone`
Rules:
- values are validated as BCP 47 and IANA formats
- active `profile_update_block` sanction rejects the mutation
## Trusted Internal API Model
All service-to-service integration in v1 is documented as trusted JSON REST.
### Auth-Facing Contract
The auth-facing contract is already reserved by `Auth / Session Service` and
must remain stable.
Frozen endpoints:
- `POST /api/v1/internal/user-resolutions/by-email`
- `GET /api/v1/internal/users/{user_id}/exists`
- `POST /api/v1/internal/users/ensure-by-email`
- `POST /api/v1/internal/users/{user_id}/block`
- `POST /api/v1/internal/user-blocks/by-email`
Auth-facing behavior:
- resolve by e-mail returns `existing`, `creatable`, or `blocked`
- ensure by e-mail returns `existing`, `created`, or `blocked`
- block by user id and block by e-mail are idempotent
- blocked e-mail subjects are respected even when no user exists yet
`EnsureUserByEmail` is extended for v1 user creation context.
Recommended request shape:
```json
{
"email": "pilot@example.com",
"registration_context": {
"preferred_language": "en",
"time_zone": "Europe/Berlin"
}
}
```
Rules for `registration_context`:
- it is used only when the user is created
- it is ignored for an existing user
- it must not overwrite settings of an existing user
- it is required by the future auth contract because first successful confirm
may create the user
### Lobby-Facing Eligibility Snapshot
`Game Lobby` needs one synchronous query by `user_id`.
Purpose:
- determine whether the user currently may create or join game flows
- obtain effective quotas relevant to lobby decisions
The response should include at minimum:
- whether the user exists
- current entitlement snapshot
- active sanctions relevant to lobby actions
- effective limit values relevant to lobby actions
- derived booleans such as whether private-game creation is currently allowed
This query is intentionally one read-optimized snapshot rather than multiple
smaller cross-service round trips.
### Geo-Facing Declared Country Sync
`Geo Profile Service` needs one explicit trusted command to synchronize the
current effective `declared_country`.
Required behavior:
- update only the current `declared_country` value in `User Service`
- not create or manage country history here
- fail explicitly on unknown `user_id`
- remain synchronous so geo workflow can decide whether its own version record
becomes effective
### Admin/Internal Reads
The trusted admin/internal read surface must support:
- exact lookup by `user_id`
- exact lookup by normalized `email`
- exact lookup by exact `race_name`
- paginated listing with filters
The v1 listing filters must support at minimum:
- paid/free state
- paid expiry window
- current `declared_country`
- active sanction code
- active limit code
- relevant eligibility markers
Listing must use deterministic pagination and stable ordering.
Recommended default ordering is newest first by `created_at`, with `user_id`
used as the deterministic tiebreaker.
### Admin/Internal Mutations
Trusted mutations remain explicit-command based.
The minimum command vocabulary in v1 is:
- grant paid access
- extend paid access
- revoke paid access
- apply sanction
- remove sanction
- set limit
- remove limit
- sync declared country
These are intentionally explicit commands rather than one generic patch API.
The service should preserve reason and actor metadata on every trusted
administrative mutation.
## New User Creation Flow
```mermaid
sequenceDiagram
participant Client
participant Gateway
participant Auth as Auth / Session Service
participant User as User Service
Client->>Gateway: confirm-email-code(code, client_public_key, time_zone)
Gateway->>Gateway: local geoip lookup and country-to-language mapping
Gateway->>Auth: confirm-email-code(..., time_zone)
Auth->>User: ensure-by-email(email, registration_context)
alt user already exists
User-->>Auth: existing user_id
else new user
User->>User: create user with generated race_name
User->>User: initialize language, time zone, free entitlement
User-->>Auth: created user_id
end
Auth-->>Gateway: device_session_id
Gateway-->>Client: device_session_id
```
New-user defaults:
- generated `race_name` in `player-<shortid>` form
- `preferred_language` from gateway-derived registration context
- `time_zone` from client-provided registration context
- `free` entitlement
- no active sanctions
- no custom limit overrides
## Interface Between Entitlement, Sanction, and Limit Evaluation
The service must keep these three layers separate.
- entitlement provides the base paid/free access state
- sanctions can deny actions regardless of entitlement
- user-specific limits can narrow or override numeric quotas
This means:
- a paid user may still be denied private-game creation by sanction
- a non-blocked user may still be quota-limited by effective count limits
- lobby checks should consume one effective snapshot rather than reimplementing
this evaluation itself
## Events
Events are auxiliary notifications only. They are not the source of truth.
The service should emit per-domain-area events for:
- profile changes
- settings changes
- entitlement changes
- sanction changes
- limit changes
- declared-country changes
Recommended event classes:
- `user.profile.changed`
- `user.settings.changed`
- `user.entitlement.changed`
- `user.sanction.changed`
- `user.limit.changed`
- `user.declared_country.changed`
Each event should include at minimum:
- `user_id`
- event timestamp
- mutation source
- correlation or request metadata when available
- enough event-specific detail to identify the changed domain area
Loss of an event must not lose the authoritative business state.
## Data Entities
This section defines the core logical entities. These are domain entities, not
mandatory final physical Redis key names.
### User Account Record
Required logical fields:
- `user_id`
- normalized `email`
- `race_name`
- `preferred_language`
- `time_zone`
- current `declared_country`
- `created_at`
- `updated_at`
### race_name Reservation
Required logical fields:
- canonical uniqueness key produced by the race-name policy
- referenced `user_id`
- original stored `race_name`
- reservation timestamp
This entity exists so uniqueness policy stays replaceable and explicit.
### Blocked E-Mail Subject Entity
Required logical fields:
- normalized `email`
- `reason_code`
- block status
- `blocked_at`
- optional resolved `user_id`
### Entitlement Period Record
Required logical fields:
- `user_id`
- `plan_code`
- `source`
- actor metadata
- `reason_code`
- `starts_at`
- optional `ends_at`
- record creation timestamp
### Current Entitlement Snapshot
Required logical fields:
- `user_id`
- effective `plan_code`
- paid/free state
- effective period bounds
- source metadata
- snapshot update timestamp
### Sanction Record
Required logical fields:
- `user_id`
- `sanction_code`
- scope
- `reason_code`
- actor metadata
- `applied_at`
- optional `expires_at`
- current status metadata
### Limit Record
Required logical fields:
- `user_id`
- `limit_code`
- numeric value
- `reason_code`
- actor metadata
- `applied_at`
- optional `expires_at`
- current status metadata
## Failure and Degradation Model
The service is synchronous for critical reads and mutations.
### Auth Dependency Failure
If `User Service` is unavailable during auth flows:
- `Auth / Session Service` must fail the affected operation explicitly
- no user should be created partially without source-of-truth persistence
### Event Publication Failure
If event publication fails:
- the source-of-truth mutation still remains committed
- failure is logged and metered
- downstream consumers recover from direct reads if needed
### race_name Uniqueness Backend Failure
If the dedicated race-name uniqueness policy backend fails:
- self-service profile update must fail closed
- new-user creation must fail explicitly rather than create ambiguous names
### Geo Sync Failure
If `Geo Profile Service` cannot synchronize `declared_country` into
`User Service`:
- geo must treat the change as not yet effective
- `User Service` must not create hidden partial country history
## Minimal Initial API Surface
The minimum useful v1 API surface is:
- gateway-routed authenticated:
- `GetMyAccount`
- `UpdateMyProfile`
- `UpdateMySettings`
- trusted internal auth:
- resolve by e-mail
- ensure by e-mail
- exists by user id
- block by user id
- block by e-mail
- trusted internal lobby:
- get user eligibility snapshot
- trusted internal geo:
- sync current `declared_country`
- trusted internal admin:
- exact user reads
- filtered user listing
- entitlement mutations
- sanction mutations
- limit mutations
## Cross-Service Follow-Up Dependencies
The service design here depends on later follow-up work in other modules.
Required follow-up items:
- `Edge Gateway` public `confirm-email-code` contract must add required
`time_zone`.
- `Auth / Session Service` public OpenAPI must mirror the same `time_zone`
addition.
- `Auth / Session Service -> User Service` ensure-by-email contract must add
create-only registration context with `preferred_language` and `time_zone`.
- a shared `pkg/geoip` package must be introduced for `Edge Gateway` and
`Geo Profile Service`
- `gateway/README.md` should later document the local geoip dependency used for
initial language derivation
- `geoprofile/README.md` should later document the shared `pkg/geoip`
dependency explicitly alongside its own local geo lookup
## Design Trade-Offs Accepted by This Architecture
- Current entitlement is materialized for fast reads instead of computed from
history on each request.
- User-specific limits are count-based only in v1 to keep evaluation simple.
- `race_name` uniqueness is stricter than plain case-insensitive comparison to
reduce impersonation risk.
- `User Service` stores only the latest effective `declared_country` while geo
owns the workflow and version history.
- Explicit trusted commands are preferred over generic patch semantics so
administrative changes remain auditable and predictable.
## Implementation Readiness Statement
This service specification is intended to be implementation-ready for a first
production-capable internal version.
The main remaining work is not product ambiguity inside `User Service`, but
follow-up cross-service contract changes in `gateway`, `authsession`, and the
future shared `pkg/geoip` package.
user/openapi.yaml
+1376
View File
File diff suppressed because it is too large Load Diff