466 lines
18 KiB
Markdown
466 lines
18 KiB
Markdown
# SOR.Chat 12-Factor Refactor Plan
|
|
|
|
Date: 2026-06-10
|
|
|
|
Scope reviewed:
|
|
- `Server/src/SOR.Chat`
|
|
- Chat persistence in `Server/src/SOR.Database/Contexts/ChatDbContext.cs`
|
|
- Chat entities and enums under `Server/src/SOR.Database`
|
|
- Chat wiring in `Server/src/SOR.Host`
|
|
|
|
Reference: https://12factor.net/
|
|
|
|
## Executive Summary
|
|
|
|
`SOR.Chat` is a service module registered by `SOR.Host` when `ENABLED_SERVICES` includes `chat`. It owns durable chat channels, messages, memberships, direct messages, friends, blocking, presence, notifications, party invites, and match chat lifecycle. It also starts `ChatLifecycleHostedService`, which listens for game-started and game-ended events and creates/archives match chat memberships.
|
|
|
|
The service already has a useful foundation:
|
|
|
|
- Chat state is durable in PostgreSQL through `ChatDbContext`.
|
|
- Channel membership has a database uniqueness constraint.
|
|
- Blocked-user pairs have a database uniqueness constraint.
|
|
- Message history is paged and persisted.
|
|
- Match channels are created from game lifecycle events.
|
|
- Party invites use `IClientPush` for live notification delivery.
|
|
- Chat handlers consistently use authenticated account IDs from the connection.
|
|
|
|
The main 12-Factor gaps are structural and operational:
|
|
|
|
- Message handlers contain transport handling, authorization checks, business rules, EF queries, mutations, DTO mapping, and response mapping.
|
|
- `ChatLifecycleHostedService` always starts with the chat service and mixes request/response chat handling with event-driven lifecycle work.
|
|
- Chat limits are compile-time constants instead of typed, validated config.
|
|
- There is no visible rate limiting or spam/abuse policy for message sends, friend requests, invites, or notifications.
|
|
- Normal `chat.send` persists and acknowledges a message, but this module does not clearly own live fan-out to other channel members.
|
|
- Singleton channel and match-channel creation are idempotent at the application level but not strongly protected by database constraints.
|
|
- Notification creation/delivery is not centralized behind a notification service.
|
|
- Presence is database-backed, but online/offline semantics, TTL, and disconnect behavior are not clear.
|
|
- Retention, moderation, deletion, and audit policy are not explicit.
|
|
|
|
The plan is to keep `SOR.Chat` as the social and chat module, but split it into thin handlers backed by messaging, social graph, presence, notification, lifecycle, moderation, and retention services with typed options and dependency-aware readiness.
|
|
|
|
## Current Structure Observations
|
|
|
|
### Strong Foundations
|
|
|
|
- `AddChatService` registers all chat handlers from one composition point.
|
|
- `ChatDbContext` uses a dedicated `chat` schema.
|
|
- Messages are stored durably and indexed by channel and send time.
|
|
- `ChatMember` enforces unique channel/account membership.
|
|
- `BlockedUser` enforces unique blocker/blocked pairs.
|
|
- Notifications are persisted so clients can fetch missed items after reconnect.
|
|
- `ChatChannelMembership` centralizes default global/lobby and match membership helpers.
|
|
- `ChatSendHandler` checks channel membership before writing.
|
|
- DM and friend workflows honor block relationships.
|
|
- Match membership creation and archival use NATS events through `IEventBus`.
|
|
|
|
### Main Problems
|
|
|
|
- `AddChatService` registers both request handlers and the lifecycle hosted service together.
|
|
- Lifecycle subscriptions log and exit if a subscription loop crashes; there is no restart/backoff loop.
|
|
- If multiple chat service instances subscribe to lifecycle events without queue semantics, duplicate work can occur. Some operations are idempotent, but singleton channel and match channel creation can race.
|
|
- `ChatLimits.MaxMessageLength`, `DefaultPageSize`, and `MaxPageSize` are hardcoded.
|
|
- There are no visible per-account or per-channel rate limits.
|
|
- Chat handlers directly use EF contexts and repeat membership/social checks.
|
|
- `ChatSendHandler` does not visibly push/broadcast the new message to other channel members.
|
|
- Party invite push is immediate but not paired with durable notification creation in the handler.
|
|
- Friend request, friend accept, outbid, and match-invite notification types exist in the entity comments, but notification creation is not centralized in the chat module.
|
|
- Blocking removes friend rows but does not visibly leave shared party/DM channels or hide existing history by policy.
|
|
- Message deletion fields exist, but no user/admin delete/edit handlers are visible in `SOR.Chat`.
|
|
- There is no visible `Server/tests/SOR.Chat.Tests` project.
|
|
|
|
## Target Chat Shape
|
|
|
|
Keep `SOR.Chat` as the service module, but split it into focused layers:
|
|
|
|
```text
|
|
Server/src/SOR.Chat/
|
|
Configuration/
|
|
ChatOptions.cs
|
|
ChatMessageOptions.cs
|
|
ChatRateLimitOptions.cs
|
|
ChatPresenceOptions.cs
|
|
ChatRetentionOptions.cs
|
|
ChatOptionsValidator.cs
|
|
Bootstrap/
|
|
ChatRegistration.cs
|
|
ChatHandlersRegistration.cs
|
|
ChatLifecycleRegistration.cs
|
|
ChatHealthChecks.cs
|
|
Contracts/
|
|
ChatMessages.cs
|
|
ChatErrors.cs
|
|
Application/
|
|
Messaging/
|
|
ChatMessageService.cs
|
|
ChatChannelQueryService.cs
|
|
ChatFanoutService.cs
|
|
Membership/
|
|
ChatMembershipService.cs
|
|
MatchChatLifecycleService.cs
|
|
PartyService.cs
|
|
Social/
|
|
FriendService.cs
|
|
BlockService.cs
|
|
SocialQueryService.cs
|
|
Presence/
|
|
PresenceService.cs
|
|
PresenceQueryService.cs
|
|
Notifications/
|
|
NotificationService.cs
|
|
NotificationDeliveryService.cs
|
|
Moderation/
|
|
ChatModerationService.cs
|
|
ChatRetentionService.cs
|
|
Persistence/
|
|
IChatRepository.cs
|
|
IChatUnitOfWork.cs
|
|
IDisplayNameReader.cs
|
|
Handlers/
|
|
ChatSendHandler.cs
|
|
ChatGetMessagesHandler.cs
|
|
...
|
|
Workers/
|
|
ChatLifecycleHostedService.cs
|
|
ChatRetentionJob.cs
|
|
```
|
|
|
|
Desired process roles:
|
|
|
|
- `chat`: handles request/response chat messages.
|
|
- `chat-lifecycle`: listens to game lifecycle events and updates match chat membership.
|
|
- `chat-jobs`: runs retention, moderation cleanup, notification cleanup, and backfill jobs.
|
|
|
|
For small deployments those roles can still be co-located, but registration should make the role boundary explicit.
|
|
|
|
## 12-Factor Gap Map
|
|
|
|
### 1. Codebase
|
|
|
|
Mostly aligned. Chat is one module in the server codebase, but handlers currently carry most of the application logic.
|
|
|
|
Plan:
|
|
- Keep one chat module.
|
|
- Extract application services by domain: messaging, social graph, presence, notifications, party, and lifecycle.
|
|
- Keep handlers as transport adapters.
|
|
- Add focused tests for application services and lifecycle behavior.
|
|
|
|
### 2. Dependencies
|
|
|
|
Mostly aligned. Chat depends on database contexts, shared networking abstractions, push abstractions, and NATS event bus abstractions.
|
|
|
|
Plan:
|
|
- Keep dependencies behind abstractions.
|
|
- Introduce repositories/readers for chat and identity display names.
|
|
- Keep `IClientPush` behind a notification/fan-out service rather than injecting it into individual workflow handlers.
|
|
- Keep lifecycle event consumption behind a dedicated worker registration.
|
|
|
|
### 3. Config
|
|
|
|
Weakly aligned. Chat limits and operational behavior are compile-time constants.
|
|
|
|
Plan:
|
|
- Add typed `ChatOptions`.
|
|
- Move message length, page sizes, rate limits, presence TTL, retention windows, party limits, and lifecycle worker behavior into config.
|
|
- Validate options at startup.
|
|
|
|
Candidate config shape:
|
|
|
|
```json
|
|
{
|
|
"Chat": {
|
|
"Messages": {
|
|
"MaxMessageLength": 500,
|
|
"DefaultPageSize": 50,
|
|
"MaxPageSize": 100
|
|
},
|
|
"RateLimits": {
|
|
"MessagesPerMinute": 30,
|
|
"FriendRequestsPerHour": 20,
|
|
"PartyInvitesPerMinute": 10
|
|
},
|
|
"Presence": {
|
|
"OfflineAfterSeconds": 120,
|
|
"MaxPresenceBatchSize": 100
|
|
},
|
|
"Retention": {
|
|
"DeletedMessageRetentionDays": 365,
|
|
"NotificationRetentionDays": 90,
|
|
"MatchChannelArchiveDays": 30
|
|
},
|
|
"Lifecycle": {
|
|
"Enabled": true,
|
|
"UseQueueGroup": true,
|
|
"RetryDelaySeconds": 5
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4. Backing Services
|
|
|
|
Partially aligned. PostgreSQL, NATS, and Redis-backed push delivery are backing services, but readiness is not dependency-aware.
|
|
|
|
Plan:
|
|
- Treat `ChatDbContext`, identity display-name reads, NATS lifecycle subscriptions, and Redis/client push as attached resources.
|
|
- Add readiness checks for active process roles.
|
|
- Document whether chat can run in history-only mode if push is unavailable.
|
|
- Add a clear dependency matrix for request handlers versus lifecycle workers.
|
|
|
|
### 5. Build, Release, Run
|
|
|
|
Mostly aligned. Chat has no build-time assets and does not run migrations itself.
|
|
|
|
Plan:
|
|
- Keep migrations outside normal chat runtime startup.
|
|
- Treat retention policy and moderation rules as release config.
|
|
- Add release checks for schema migrations, lifecycle worker count, and required NATS subjects.
|
|
|
|
### 6. Processes
|
|
|
|
Partially aligned. Chat request handling and lifecycle event processing are co-registered.
|
|
|
|
Plan:
|
|
- Split registration into:
|
|
- `AddChatCore`
|
|
- `AddChatHandlers`
|
|
- `AddChatLifecycleWorker`
|
|
- `AddChatJobs`
|
|
- Let host process formation decide whether lifecycle workers run.
|
|
- Add startup validation for unsafe lifecycle scaling if event delivery is broadcast rather than queue-grouped.
|
|
|
|
### 7. Port Binding
|
|
|
|
Aligned through `SOR.Host`. Chat does not bind ports directly.
|
|
|
|
Plan:
|
|
- Keep port binding in Host/Gateway.
|
|
- Expose chat readiness through host health checks.
|
|
- Do not add chat-specific listeners.
|
|
|
|
### 8. Concurrency
|
|
|
|
Partially aligned. Some database uniqueness constraints exist, but several workflows depend on pre-checks.
|
|
|
|
Plan:
|
|
- Add database uniqueness or conditional creation for singleton global/lobby channels.
|
|
- Add uniqueness for match channels by match ID.
|
|
- Make DM channel creation concurrency-safe.
|
|
- Make party membership constraints enforceable, such as one active party per account.
|
|
- Make friend-request pair uniqueness order-independent at the database level.
|
|
- Add retry handling for unique constraint races and transient Postgres failures.
|
|
|
|
### 9. Disposability
|
|
|
|
Partially aligned. Handlers use cancellation tokens, but lifecycle loops do not restart after unexpected failure.
|
|
|
|
Plan:
|
|
- Make lifecycle subscriptions supervised with retry/backoff.
|
|
- Ensure `StopAsync` cancellation exits subscriptions promptly.
|
|
- Avoid long-running work inside request handlers.
|
|
- Make job processes cancellation-aware.
|
|
|
|
### 10. Dev/Prod Parity
|
|
|
|
Partially aligned. Chat uses the same database and message abstractions in all environments, but operational behavior is not fully represented in config.
|
|
|
|
Plan:
|
|
- Provide local config for chat limits, lifecycle worker behavior, and retention.
|
|
- Keep lifecycle behavior testable locally with NATS.
|
|
- Add seed/dev helpers for default channels if needed, but keep production creation idempotent.
|
|
|
|
### 11. Logs
|
|
|
|
Weakly aligned. Lifecycle failures are logged, but normal chat/social operations do not have centralized structured audit logs.
|
|
|
|
Plan:
|
|
- Add structured logs and metrics through application services.
|
|
- Track message send count, send failures, blocked send attempts, DM opens, friend request status changes, party invites, notification creation/delivery, lifecycle events, and subscription restarts.
|
|
- Avoid logging message content by default.
|
|
|
|
Suggested fields:
|
|
|
|
- `accountId`
|
|
- `channelId`
|
|
- `channelType`
|
|
- `messageId`
|
|
- `recipientAccountId`
|
|
- `notificationId`
|
|
- `matchId`
|
|
- `operation`
|
|
- `errorCode`
|
|
|
|
### 12. Admin Processes
|
|
|
|
Partially aligned. The data model supports deletion/moderation concepts, but operational admin processes are not explicit.
|
|
|
|
Plan:
|
|
- Add admin/job processes for message moderation, soft-delete, retention cleanup, notification cleanup, and archived channel cleanup.
|
|
- Add audit records for moderator actions.
|
|
- Add dry-run mode for retention cleanup.
|
|
- Integrate chat moderation surfaces in Admin behind application services instead of direct DbContext edits.
|
|
|
|
## Refactor Phases
|
|
|
|
### Phase 0: Baseline Tests
|
|
|
|
Goals:
|
|
- Preserve current chat behavior before extraction.
|
|
|
|
Work:
|
|
- Add tests for message send membership checks.
|
|
- Add tests for DM open with existing channel, new channel, self-DM rejection, and block rejection.
|
|
- Add tests for friend request/respond/remove flows.
|
|
- Add tests for block/unblock behavior.
|
|
- Add tests for party invite/respond/leave/rename flows.
|
|
- Add tests for default and match membership helpers.
|
|
|
|
Done when:
|
|
- Current chat workflows are covered before structural changes.
|
|
|
|
### Phase 1: Typed Options
|
|
|
|
Goals:
|
|
- Make chat behavior configurable and validated.
|
|
|
|
Work:
|
|
- Add `ChatOptions` and nested option classes.
|
|
- Replace `ChatLimits` constants with options while preserving current defaults.
|
|
- Add validation for page sizes, message length, rate-limit values, and retention windows.
|
|
|
|
Done when:
|
|
- Chat limits can be changed per environment without code changes.
|
|
- Invalid chat config fails startup for active chat roles.
|
|
|
|
### Phase 2: Thin Handlers and Application Services
|
|
|
|
Goals:
|
|
- Move workflow logic out of message handlers.
|
|
|
|
Work:
|
|
- Extract `ChatMessageService`, `ChannelQueryService`, `FriendService`, `BlockService`, `PresenceService`, `NotificationService`, and `PartyService`.
|
|
- Keep handlers responsible for deserialization, authenticated account ID extraction, service call, and response mapping.
|
|
- Centralize display-name lookup through `IDisplayNameReader`.
|
|
|
|
Done when:
|
|
- Handlers are small and business rules are testable without transport plumbing.
|
|
|
|
### Phase 3: Delivery and Notification Boundary
|
|
|
|
Goals:
|
|
- Decide and implement clear live delivery semantics.
|
|
|
|
Work:
|
|
- Define whether chat messages are pull-only, push fan-out, or event-driven fan-out.
|
|
- If fan-out is required, add `ChatFanoutService` using `IClientPush`.
|
|
- Centralize durable notification creation and push delivery in `NotificationService`.
|
|
- Make notification push best-effort but durable notification storage authoritative.
|
|
|
|
Done when:
|
|
- Clients have a clear contract for receiving new messages and missed notifications.
|
|
- Party invites, friend requests, and other notifications share one delivery path.
|
|
|
|
### Phase 4: Lifecycle Worker Split
|
|
|
|
Goals:
|
|
- Make game lifecycle chat updates operationally safe.
|
|
|
|
Work:
|
|
- Move `ChatLifecycleHostedService` into explicit `AddChatLifecycleWorker` registration.
|
|
- Add supervised retry/backoff loops around subscriptions.
|
|
- Add queue-group or lease semantics if multiple lifecycle workers can run.
|
|
- Add idempotency and database constraints for match-channel creation.
|
|
|
|
Done when:
|
|
- Lifecycle processing can scale safely or is explicitly limited to one worker.
|
|
- Subscription failures self-recover.
|
|
|
|
### Phase 5: Concurrency and Invariants
|
|
|
|
Goals:
|
|
- Move critical social/chat invariants into database-backed guarantees.
|
|
|
|
Work:
|
|
- Add a unique constraint for singleton channel types where `MatchId` is null.
|
|
- Add a unique constraint for match channels by match ID.
|
|
- Add an order-independent friendship pair key or normalized pair columns.
|
|
- Add a durable constraint or claim path for one active party per account.
|
|
- Handle unique-constraint races as successful idempotent outcomes where appropriate.
|
|
|
|
Done when:
|
|
- Concurrent requests cannot create duplicate default channels, match channels, DMs, friend relationships, or party memberships.
|
|
|
|
### Phase 6: Rate Limits and Abuse Controls
|
|
|
|
Goals:
|
|
- Make chat safe under spam and abuse.
|
|
|
|
Work:
|
|
- Add rate limits for sends, DMs, friend requests, party invites, and notification mutations.
|
|
- Add optional content moderation hooks.
|
|
- Add block enforcement through shared policy services.
|
|
- Add admin controls for mute, suspend chat, and message soft-delete if not already elsewhere.
|
|
|
|
Done when:
|
|
- Chat abuse controls are configurable, observable, and testable.
|
|
|
|
### Phase 7: Retention, Moderation, and Audit
|
|
|
|
Goals:
|
|
- Make chat data lifecycle explicit.
|
|
|
|
Work:
|
|
- Add retention jobs for notifications, archived match channels, and deleted-message content.
|
|
- Add moderator action audit logs.
|
|
- Decide whether soft-deleted message content is retained, cleared, or encrypted after a retention window.
|
|
- Add dry-run mode for cleanup jobs.
|
|
|
|
Done when:
|
|
- Chat retention and moderation behavior is documented and automated.
|
|
|
|
### Phase 8: Observability and Readiness
|
|
|
|
Goals:
|
|
- Make chat operations diagnosable in production.
|
|
|
|
Work:
|
|
- Add readiness checks for `ChatDbContext`, identity display-name reads, NATS lifecycle, and push availability by active role.
|
|
- Add metrics for messages sent, fan-out failures, notification backlog, lifecycle events, subscription restarts, rate-limit rejections, and moderation actions.
|
|
- Add runbook notes for stuck lifecycle events, missing channels, push outages, and retention jobs.
|
|
|
|
Done when:
|
|
- Operators can see whether chat persistence, delivery, lifecycle, and notification paths are healthy.
|
|
|
|
## Suggested Work Order
|
|
|
|
1. Add baseline tests for chat, social, presence, and party workflows.
|
|
2. Add typed options with current default values.
|
|
3. Extract application services behind existing handlers.
|
|
4. Centralize notification creation and delivery.
|
|
5. Decide and implement chat message fan-out semantics.
|
|
6. Split lifecycle worker registration and add supervised retry.
|
|
7. Add database constraints for concurrency-sensitive invariants.
|
|
8. Add rate limits and moderation policy hooks.
|
|
9. Add retention jobs, audit logs, readiness checks, metrics, and runbooks.
|
|
|
|
## Completion Criteria
|
|
|
|
The refactor is complete when:
|
|
|
|
- Chat handlers are thin transport adapters.
|
|
- Chat limits, rate limits, presence behavior, lifecycle behavior, and retention are typed config.
|
|
- Message fan-out and missed-notification semantics are explicit.
|
|
- Lifecycle event processing is safe to run at the configured scale.
|
|
- Database constraints enforce key social and channel invariants.
|
|
- Notification creation and push delivery use one service path.
|
|
- Chat moderation, deletion, and retention behavior are documented and implemented.
|
|
- Readiness checks account for chat persistence, lifecycle subscriptions, and push dependencies.
|
|
- Tests cover messaging, DMs, social graph, blocking, parties, presence, notifications, and lifecycle membership.
|
|
|
|
## Immediate Low-Risk Next Steps
|
|
|
|
- Add `ChatOptions` with defaults matching `ChatLimits`.
|
|
- Add tests for `ChatChannelMembership` and `ChatSendHandler` membership enforcement.
|
|
- Split `AddChatService` internally into `AddChatHandlers` and `AddChatLifecycleWorker` without changing host behavior.
|
|
- Add a runbook note documenting the current lifecycle subscription scaling assumption.
|
|
- Centralize notification creation before adding more notification-producing workflows.
|