Files
sor/SOR.Chat.12FactorPlan.md
T
2026-07-02 13:09:05 -04:00

18 KiB

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:

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:

{
  "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.