17 KiB
SOR.Host 12-Factor Refactor Plan
Date: 2026-06-08
Scope reviewed:
Server/src/SOR.HostServer/Dockerfile.hostServer/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.csis the only host source file and contains all boot logic, infrastructure wiring, service selection, endpoint mapping, CDN proxy behavior, and runtime startup.ENABLED_SERVICESparsing is string-based and defaults toall, 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.
/healthis 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.Hostreferences 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.Hostis the only executable project and usesMicrosoft.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_SERVICESsupports process formation without changing code.- The Dockerfile separates restore/build/publish from runtime.
- The runtime container exposes port
8080, setsASPNETCORE_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, andNats__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=allas 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
8080branch for co-located auth/gateway. - Only
/healthexists; 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:
gatewayauthgamematchmakingaicontentsupport- 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.Hostas 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
- primary env key remains
- Change production default behavior so missing
ENABLED_SERVICESfails inProduction; keepallonly for development if desired. - Add typed options and validation for:
ServicesNatsConnectionStringsCdnWebSocketGateway- 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.Hoststartup. - 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.
allis useful locally.
Plan:
- Treat each
ENABLED_SERVICESvalue as a process type. - Make process formation explicit and validated.
- Avoid hidden coupling such as
gameautomatically 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=alldiffers 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
- convenience mode:
- 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.Hostis a long-running runtime process.SOR.Toolsexists for tooling, but host does not define release/admin process conventions.
Plan:
- Keep
SOR.Hostfocused on long-running service processes. - Use
SOR.Toolsor 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, andServiceFormation. - Replace local
IsEnabledfunction with a tested formation object. - Define known service names in one place.
- Fail fast on unknown service names.
Acceptance:
Program.csno 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.csis 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
/healthas cheap liveness. - Add
/readyfor 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.Toolsor 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
- Add host tests for service formation parsing.
- Extract and validate
EnabledServices. - Extract host bootstrap modules from
Program.cs. - Add typed options and startup validation.
- Add dependency-aware infrastructure registration.
- Add
/readyand dependency health checks. - Extract CDN proxy endpoint.
- Document process formations and release/admin process conventions.
- Remove host-to-module static logger initialization when
SOR.Gamelogging 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.csis 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.
/healthand/readyhave 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.Hostremains the single composition root for concrete service and transport wiring.