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

17 KiB

SOR.Host 12-Factor Refactor Plan

Date: 2026-06-08

Scope reviewed:

  • Server/src/SOR.Host
  • Server/Dockerfile.host
  • Server/architecture.md
  • Shared runtime dependencies wired by SOR.Host: Redis, NATS, WebSocket transport, Redis push, Serilog, health checks, service modules

Reference: https://12factor.net/

Executive Summary

SOR.Host is already close to the 12-Factor shape in several important ways. It is the single deployable server binary, binds its own port, reads service formation from ENABLED_SERVICES, writes logs to console through Serilog, and relies on environment-overridable configuration.

The main gaps are not conceptual; they are structural and operational:

  • Program.cs is the only host source file and contains all boot logic, infrastructure wiring, service selection, endpoint mapping, CDN proxy behavior, and runtime startup.
  • ENABLED_SERVICES parsing is string-based and defaults to all, which is convenient locally but risky as a production default.
  • Redis and NATS are always required even when the enabled service set might not need both.
  • /health is currently a basic liveness endpoint; dependency-aware readiness is still a TODO.
  • Config is environment-overridable, but host-level options are not typed or validated at startup.
  • The CDN proxy is embedded directly in host startup instead of being a small endpoint module with typed options and test coverage.
  • SOR.Host references every service module and transport implementation, which is intentional, but the formation matrix and dependency requirements are not codified.
  • Admin/release tasks such as database migration and repair jobs should run as explicit one-off processes, not implicit runtime startup work.

The plan is to keep SOR.Host as the composition root, but split bootstrapping into clear host modules: configuration validation, service formation, infrastructure registration, endpoint mapping, health/readiness, and operational process definitions.

Current Structure Observations

Strong Foundations

  • SOR.Host is the only executable project and uses Microsoft.NET.Sdk.Web.
  • All other server modules are referenced as libraries.
  • Concrete transport and infrastructure implementations are wired in the host, keeping most modules dependent on abstractions.
  • ENABLED_SERVICES supports process formation without changing code.
  • The Dockerfile separates restore/build/publish from runtime.
  • The runtime container exposes port 8080, sets ASPNETCORE_URLS=http://+:8080, and runs as a non-root user.
  • Serilog is configured through application configuration and writes to console.
  • Production config can be overridden with environment variables such as ConnectionStrings__Redis, ConnectionStrings__Default, and Nats__Url.

Main Problems

  • Host responsibilities are packed into one top-level Program.cs.
  • Missing config validation allows malformed formations or missing attached resources to fail late.
  • Service names are free-form strings, so typos silently disable intended services unless no services remain.
  • ENABLED_SERVICES=all as a default can accidentally start every module.
  • Redis, NATS, and Redis push are registered globally even if the active process type does not need them.
  • Kestrel port behavior includes a hardcoded 8080 branch for co-located auth/gateway.
  • Only /health exists; there is no separate readiness endpoint for dependency checks.
  • CDN proxy settings are inline and default to a production-looking URL.
  • Ability-system logger initialization reaches from host into game internals.
  • There is no host test project visible under Server/tests.

Target Host Shape

Keep SOR.Host as the composition root, but split it into focused files:

Server/src/SOR.Host/
  Program.cs
  Configuration/
    HostOptions.cs
    ServiceFormationOptions.cs
    CdnProxyOptions.cs
    InfrastructureOptions.cs
    OptionsValidation.cs
  Formation/
    EnabledServices.cs
    ServiceName.cs
    ServiceFormation.cs
    ServiceDependencyMatrix.cs
  Bootstrap/
    HostLogging.cs
    HostKestrel.cs
    HostInfrastructure.cs
    HostServiceModules.cs
    HostEndpoints.cs
    HostHealthChecks.cs
  Endpoints/
    CdnProxyEndpoint.cs
  Diagnostics/
    StartupSummary.cs

Program.cs should become a short sequence:

var builder = WebApplication.CreateBuilder(args);
var formation = builder.Configuration.GetRequiredServiceFormation();

builder.ConfigureHostLogging();
builder.ConfigureHostKestrel(formation);
builder.Services.AddHostOptions(builder.Configuration);
builder.Services.AddHostInfrastructure(builder.Configuration, formation);
builder.Services.AddEnabledServiceModules(builder.Configuration, formation);
builder.Services.AddHostHealthChecks(builder.Configuration, formation);

var app = builder.Build();
app.MapHostEndpoints(formation);
app.LogStartupSummary(formation);
await app.RunAsync();

12-Factor Gap Map

I. Codebase

Status: Mostly aligned.

Current state:

  • One codebase contains the host and all service modules.
  • One deployable host binary can represent many deploy formations.

Plan:

  • Keep one host codebase.
  • Document process formations as config, not separate branches:
    • gateway
    • auth
    • game
    • matchmaking
    • ai
    • content
    • support
    • combined local all
  • Add a service formation matrix to document which backing services each formation requires.

II. Dependencies

Status: Mostly aligned.

Current state:

  • Host references all service modules and concrete networking implementations.
  • NuGet versions are centrally managed.

Plan:

  • Keep SOR.Host as the only project that references concrete transport implementations.
  • Split host boot code without creating new runtime packages unless needed.
  • Add a dependency audit for host project references so every referenced module maps to an allowed service name.
  • Consider trimming deployment images later, but do not split binaries until process formation proves it needs that.

III. Config

Status: Partially aligned.

Current state:

  • Config can be overridden by environment variables.
  • Service selection is read directly from Environment.GetEnvironmentVariable("ENABLED_SERVICES").
  • Some values are inline or unvalidated.

Plan:

  • Move service formation into typed config:
    • primary env key remains ENABLED_SERVICES
    • bind to ServiceFormationOptions
    • validate service names
    • reject empty formations
  • Change production default behavior so missing ENABLED_SERVICES fails in Production; keep all only for development if desired.
  • Add typed options and validation for:
    • Services
    • Nats
    • ConnectionStrings
    • Cdn
    • WebSocket
    • Gateway
    • host ports and auth loopback behavior
  • Avoid production-looking defaults for optional external endpoints unless explicitly configured.

IV. Backing Services

Status: Partially aligned.

Current state:

  • Redis, NATS, PostgreSQL, CDN, and Keycloak are treated as attached resources via config.
  • Redis and NATS are registered for all formations.

Plan:

  • Define per-service attached-resource requirements.
  • Register Redis only when any enabled service requires Redis.
  • Register NATS only when any enabled service requires NATS.
  • Register Redis push only when enabled modules need client push.
  • Register CDN proxy only when explicitly enabled or when the formation requires it.
  • Surface missing attached resources through startup validation and readiness checks.

V. Build, Release, Run

Status: Mostly aligned.

Current state:

  • Dockerfile separates build and runtime stages.
  • Runtime configuration is injected through environment variables.

Plan:

  • Keep build and runtime separated.
  • Add release-phase documentation:
    • build image
    • run tests
    • run database migrations as one-off process
    • deploy runtime formations
  • Avoid implicit migration or maintenance work in SOR.Host startup.
  • Add startup summary logging that reports formation and enabled infrastructure without exposing secrets.

VI. Processes

Status: Partially aligned.

Current state:

  • Host can run one or more service modules in a single process.
  • all is useful locally.

Plan:

  • Treat each ENABLED_SERVICES value as a process type.
  • Make process formation explicit and validated.
  • Avoid hidden coupling such as game automatically registering AI infrastructure unless the relationship is documented in the formation matrix.
  • Separate long-running runtime processes from one-off admin processes.

VII. Port Binding

Status: Mostly aligned.

Current state:

  • Host binds ports through Kestrel and Docker exposes 8080.
  • Co-located auth/gateway has a special loopback HTTP/2 listener.

Plan:

  • Move Kestrel setup into HostKestrel.
  • Make public HTTP port configurable through normal ASP.NET Core configuration.
  • Make internal auth gRPC loopback port explicit and validated.
  • Document which formations expose public HTTP/WebSocket endpoints and which run worker-style with only health endpoints.

VIII. Concurrency

Status: Mostly aligned at host level.

Current state:

  • Concurrency is mainly delegated to service modules and hosted services.
  • Host starts all enabled module hosted services in one process.

Plan:

  • Document expected scale-out behavior per formation.
  • Ensure host-level infrastructure clients are singleton and safe for concurrent use.
  • Add readiness checks that account for startup dependencies before traffic reaches the process.
  • Avoid process-local host state that affects request correctness.

IX. Disposability

Status: Partially aligned.

Current state:

  • await app.RunAsync() integrates with ASP.NET Core shutdown.
  • Hosted services receive StopAsync.

Plan:

  • Add startup validation so bad configuration fails before partial service startup.
  • Keep startup fast by avoiding broad maintenance scans in runtime boot.
  • Ensure all hosted services honor cancellation tokens.
  • Add graceful shutdown documentation for gateway, game, matchmaking, and AI formations.
  • Add termination-drain guidance for WebSocket gateway deployments.

X. Dev/Prod Parity

Status: Partially aligned.

Current state:

  • Local defaults exist in appsettings.json.
  • ENABLED_SERVICES=all differs from production-style process formation.

Plan:

  • Add two local run modes:
    • convenience mode: ENABLED_SERVICES=all
    • production-like mode: separate host processes with explicit formations
  • Keep config keys identical across dev/staging/prod.
  • Add local compose or run documentation for Redis, NATS, PostgreSQL, and split host processes.

XI. Logs

Status: Mostly aligned, with a few gaps.

Current state:

  • Serilog writes to console.
  • Host startup logs enabled services.
  • Some game logging is initialized from host via a static call.

Plan:

  • Keep logs as stdout event streams.
  • Add structured startup summary:
    • environment
    • formation
    • public endpoints
    • required attached resources
    • readiness endpoint path
  • Avoid logging secrets or full connection strings.
  • Remove module-internal static logger initialization from host when the game module is refactored.

XII. Admin Processes

Status: Needs work.

Current state:

  • SOR.Host is a long-running runtime process.
  • SOR.Tools exists for tooling, but host does not define release/admin process conventions.

Plan:

  • Keep SOR.Host focused on long-running service processes.
  • Use SOR.Tools or a dedicated operations project for one-off tasks:
    • database migrations
    • game cleanup/repair jobs
    • content sync jobs
    • seed jobs
  • Document how one-off processes get the same config and attached resources as runtime processes.

Refactor Phases

Phase 0: Baseline and Tests

Deliverables:

  • Add Server/tests/SOR.Host.Tests.
  • Test service formation parsing:
    • all
    • comma-separated service names
    • whitespace and casing
    • empty values
    • unknown service names
    • production missing value behavior
  • Test dependency matrix:
    • Redis required only for formations that need it
    • NATS required only for formations that need it
    • gateway requires WebSocket settings
    • auth loopback behavior is deterministic

Acceptance:

  • Host startup rules can be changed without guessing about formation behavior.

Phase 1: Extract Service Formation

Deliverables:

  • Add EnabledServices, ServiceName, and ServiceFormation.
  • Replace local IsEnabled function with a tested formation object.
  • Define known service names in one place.
  • Fail fast on unknown service names.

Acceptance:

  • Program.cs no longer parses service strings directly.
  • Formation errors produce clear startup messages.

Phase 2: Extract Host Bootstrap Modules

Deliverables:

  • Move logging setup to HostLogging.
  • Move Kestrel setup to HostKestrel.
  • Move Redis/NATS/WebSocket/Redis-push registration to HostInfrastructure.
  • Move service module registration to HostServiceModules.
  • Move endpoint mapping to HostEndpoints.

Acceptance:

  • Program.cs is short and reads as startup orchestration.
  • Boot behavior remains unchanged except for intentional validation.

Phase 3: Typed Options and Validation

Deliverables:

  • Add host-level options classes.
  • Validate required config based on enabled formation.
  • Validate URLs, ports, service endpoints, message sizes, and timeouts.
  • Make production defaults stricter than development defaults.

Acceptance:

  • Missing or invalid critical config fails during startup.
  • No service starts with a malformed attached resource setting.

Phase 4: Dependency-Aware Infrastructure Registration

Deliverables:

  • Add ServiceDependencyMatrix.
  • Register Redis, NATS, Redis push, WebSocket, CDN proxy, and gRPC routes only when required.
  • Keep shared serializer registration unconditional if it is low-cost and universally used.

Acceptance:

  • Worker formations do not require unrelated resources.
  • Startup errors match the enabled service set.

Phase 5: Health and Readiness

Deliverables:

  • Keep /health as cheap liveness.
  • Add /ready for dependency readiness.
  • Add Redis readiness when Redis is required.
  • Add NATS readiness when NATS is required.
  • Add database readiness for enabled service contexts.
  • Add CDN readiness only if CDN proxy is enabled and the check is cheap.

Acceptance:

  • Kubernetes can distinguish a running process from a process ready to serve traffic.
  • Dependency failures are visible without reading logs.

Phase 6: CDN Proxy Endpoint Module

Deliverables:

  • Extract inline CDN proxy mapping into CdnProxyEndpoint.
  • Add typed CdnProxyOptions.
  • Make proxy enablement explicit.
  • Add timeout and error behavior.
  • Keep CORS behavior explicit and configurable.

Acceptance:

  • CDN proxy behavior can be tested and configured independently from host startup.

Phase 7: Release and Admin Process Documentation

Deliverables:

  • Document runtime process formations.
  • Document release phase:
    • build
    • test
    • migrate
    • deploy
  • Document admin process conventions using SOR.Tools or a dedicated operations executable.

Acceptance:

  • Operational work is not hidden inside runtime boot.
  • A deployment can be reasoned about as build, release, and run stages.

Suggested Milestone Order

  1. Add host tests for service formation parsing.
  2. Extract and validate EnabledServices.
  3. Extract host bootstrap modules from Program.cs.
  4. Add typed options and startup validation.
  5. Add dependency-aware infrastructure registration.
  6. Add /ready and dependency health checks.
  7. Extract CDN proxy endpoint.
  8. Document process formations and release/admin process conventions.
  9. Remove host-to-module static logger initialization when SOR.Game logging is refactored.

Risk Register

Risk Why It Matters Mitigation
Breaking local all mode Local development likely depends on ENABLED_SERVICES=all. Keep development default or document explicit local setting.
Over-validating optional resources A process may fail because host requires a resource it does not use. Drive validation from the dependency matrix.
Readiness checks too expensive Expensive readiness can overload dependencies. Keep checks shallow and cached where needed.
Service name typos currently tolerated Failing fast may reveal bad deploy config. Make the error clear and roll out in staging first.
CDN proxy behavior changes Browser clients may depend on current proxy semantics. Extract with tests before changing defaults.
Host startup refactor affects module registration order Hosted service order can affect runtime behavior. Preserve ordering in tests and startup summary.

Definition of Done

The host refactor is complete when:

  • Program.cs is only startup orchestration.
  • Service formation is typed, validated, and tested.
  • Unknown or empty service formations fail clearly.
  • Production does not silently default to all.
  • Infrastructure registration and config validation are driven by enabled services.
  • /health and /ready have distinct meanings.
  • Logs remain stdout event streams and include a structured startup summary.
  • CDN proxy behavior is isolated behind an endpoint module with typed options.
  • Release/admin processes are documented separately from long-running runtime startup.
  • SOR.Host remains the single composition root for concrete service and transport wiring.