Fable test

This commit is contained in:
dingo
2026-07-02 13:09:05 -04:00
parent ed300d4e4f
commit b96b8b89c0
29 changed files with 7462 additions and 169 deletions
@@ -0,0 +1 @@
uid://boknaojgo0qni
@@ -0,0 +1 @@
uid://borckhkljxkbb
@@ -172,8 +172,14 @@ func on_cost_group_pick_request(req: Dictionary) -> void:
var option_idx: int = 0
for entry: Variant in entries:
var entry_d: Dictionary = entry as Dictionary
var label: String = str(entry_d.get("typestr", entry_d.get("typeStr", "Option %d" % (option_idx + 1))))
var btn: Button = Button.new()
# Keys are normalised to lowercase; the server serializes CostEntry.Type/Amount.
var label: String = str(entry_d.get("type", ""))
var amt: int = int(entry_d.get("amount", 0))
if label.is_empty():
label = "Option %d" % (option_idx + 1)
elif amt > 0:
label = "%s ×%d" % [label, amt]
var btn: Button = Button.new()
btn.text = label
btn.add_theme_font_size_override("font_size", 12)
var cap_idx: int = option_idx
@@ -232,10 +238,11 @@ func on_action_group_pick_request(req: Dictionary) -> void:
var option_idx: int = 0
for act: Variant in actions:
var act_d: Dictionary = act as Dictionary
var label: String = str(act_d.get("label", "Action %d" % (option_idx + 1)))
var label: String = str(act_d.get("label", ""))
if label.is_empty():
# Keys are normalised to lowercase; the target's type key is "type".
var tgt: Dictionary = act_d.get("target", {}) as Dictionary
label = "%s %s" % [tgt.get("ownership", ""), tgt.get("targetType", "")]
label = "%s %s" % [tgt.get("ownership", ""), tgt.get("type", "")]
label = label.strip_edges()
if label.is_empty():
label = "Action %d" % (option_idx + 1)
@@ -103,6 +103,25 @@ func _acquire_from_pool(card_type: String) -> StaticBody3D:
return body
func _set_body_click_collision_enabled(body: StaticBody3D, enabled: bool) -> void:
if not is_instance_valid(body):
return
body.collision_layer = 1 if enabled else 0
body.collision_mask = 1 if enabled else 0
_set_descendant_click_collision_enabled(body, enabled)
func _set_descendant_click_collision_enabled(node: Node, enabled: bool) -> void:
if node is CollisionShape3D:
(node as CollisionShape3D).disabled = not enabled
if node is CollisionObject3D:
var collision_object: CollisionObject3D = node as CollisionObject3D
collision_object.collision_layer = 1 if enabled else 0
collision_object.collision_mask = 1 if enabled else 0
for child: Node in node.get_children():
_set_descendant_click_collision_enabled(child, enabled)
# ── Incremental rebuild ───────────────────────────────────────────────────────
## Incremental diff: add/remove units without recreating unchanged ones.
@@ -317,6 +336,7 @@ func add_unit_mesh(unit: Dictionary, team_color: Color, is_enemy: bool = false,
if not _pool_hit:
body.add_child(shape)
_set_body_click_collision_enabled(body, card_type != "Ruin")
body.add_child(mi)
body.set_meta("above_tile", above_tile)
body.position = wp + Vector3(0, tile_base + tile_h + above_tile, 0)
@@ -422,6 +442,8 @@ func add_unit_mesh(unit: Dictionary, team_color: Color, is_enemy: bool = false,
if raw_aabb.size != Vector3.ZERO:
model_node.position.y = -above_tile - target_scale.y * raw_aabb.position.y
unit_meshes[iid] = model_node
if card_type == "Ruin":
_set_body_click_collision_enabled(b, false)
if Time.get_ticks_msec() <= int(materialize_until.get(iid, 0)):
if ascend_arrival:
_play_ascend_arrival_shader(model_node, team_color)
@@ -1161,6 +1183,8 @@ func do_model_retry(iid: String, model_url: String, attempt: int, etag: String =
if raw_aabb.size != Vector3.ZERO:
model_node.position.y = -above_tile - target_scale.y * raw_aabb.position.y
unit_meshes[iid] = model_node
if card_type == "Ruin":
_set_body_click_collision_enabled(body, false)
var ap: AnimationPlayer = find_animation_player(model_node)
anim_players[iid] = ap
if ap != null:
@@ -555,8 +555,7 @@ func _on_board_clicked(screen_pos: Vector2) -> void:
var unit_id: String = _mouse_to_unit_id(screen_pos)
if unit_id.is_empty() and coord.x >= 0:
var tile: Dictionary = Game.get_tile(coord.x, coord.y)
var raw_occ: Variant = tile.get("occupantId")
unit_id = str(raw_occ) if raw_occ != null else ""
unit_id = _non_ruin_occupant_id(tile)
_sel_ctrl.handle_board_click(screen_pos, coord, unit_id)
_update_hover(screen_pos)
if unit_id.is_empty():
@@ -871,8 +870,7 @@ func _update_hover(mouse_pos: Vector2) -> void:
if coord.x >= 0:
tile = Game.get_tile(coord.x, coord.y)
if occ_id.is_empty():
var raw_occ: Variant = tile.get("occupantId")
occ_id = str(raw_occ) if raw_occ != null else ""
occ_id = _non_ruin_occupant_id(tile)
if coord == _hovered_coord:
return
_reset_unit_hover_glow()
@@ -1280,7 +1278,20 @@ func _mouse_to_unit_id(mouse_pos: Vector2) -> String:
var body: PhysicsBody3D = _pathfinder.raycast_body(mouse_pos)
if body == null:
return ""
return str(body.get_meta("unit_id", ""))
var unit_id: String = str(body.get_meta("unit_id", ""))
if _unit_reg != null and _unit_reg.is_ruin_instance(unit_id):
return ""
return unit_id
func _non_ruin_occupant_id(tile: Dictionary) -> String:
var raw_occ: Variant = tile.get("occupantId")
var occupant_id: String = "" if raw_occ == null else str(raw_occ)
if occupant_id.is_empty() or occupant_id == "null":
return ""
if _unit_reg != null and _unit_reg.is_ruin_instance(occupant_id):
return ""
return occupant_id
func _terra_count_for_card(card: Dictionary) -> int:
+340
View File
@@ -0,0 +1,340 @@
# SOR Ability System — Review & Solutions
> **IMPLEMENTATION STATUS (2026-07-02):** Phases 1–2 plus the builder/client quick wins are
> **implemented** (server builds clean). Summary of what landed:
>
> - **C1 fixed** — Passives execute `ActionGroup` via new `GetStaticActions` (AbilitySystem).
> - **C2 fixed** — `AllBattlefieldUnits` / `FindUnitAnywhere` helpers; ArchSpirit now included in
> FireTrigger scans, passive application (incl. `ReEvaluateConditionalPassives`), aura-on-enter,
> `OwnershipIs`, occupant lookups, and **all** `Resume*` source lookups.
> - **C3 partly fixed** — now fired AND matched: `OnUnitAbilityActivated`, `OnDamageDealt` (ability +
> combat damage), `OnHealed`, `OnTokenSummoned`, `OnCardDrawn` (engine draw + ability draw),
> `OnSPGained`/`OnSPSpent`/`OnSTGained`/`OnSTSpent` (turn accumulation, costs, channel/ascend
> payments, ModifySP/ST), `OnUnitLeaveBattlefield` (kill, return-to-hand, send-to-discard).
> Still unimplemented and now **delisted from the builder**: OnUnitMPSpent, OnStatModified,
> OnAbilityAdded/Removed, OnGenusChanged, OnTileAffinityChanged, OnCardDiscarded,
> OnCardReturnedToHand/Deck, OnDeckShuffled, OnCardsRevealed, OnTargetedByAbility, OnEffectApplied.
> - **C4 fixed** — Repentance/Instinct discard *before* `FireCardEffects`; resume paths use
> `FindUnitAnywhere`; `ResumeCostPick`/`ResumeCostGroupPick` no longer drop paid abilities.
> - **C5 fixed** — full `ActionsJson` pushed for triggered-target prompts (indices now align).
> - **C6 fixed** — `"Base"` removed from the builder (healed to `"Current"` on load);
> `ParseAbilities` catches `JsonException` per card.
> - **C7 fixed** — `ChannelCard`, `SetStatModMultiplier`, `ModifySacrificeTokenReturn` delisted.
> - **H1 partly** — Amount/AmountComparator + DamageType + OnChanneled.CardDefinitionId +
> OnUnitAbilityActivated.Filter now evaluated in `TriggerMatches`.
> - **H3 fixed** — trigger counts, prevent markers, sequence depth moved onto `GameState`.
> - **H4 fixed** — PreventDeath honours `DamageTakenSetToHp`/`DamageIgnored` and protects leaders.
> - **H5 partly** — Push/Pull step per-tile + `BlockedDamage`; TakeControl re-owns the board tile;
> ChannelCardFromZone checks SP/ST sufficiency (all 3 sites); DrawCards honours `CanDrawCards`
> and `Both`/`Any`; CloneSpiritAsToken wires passives + TokenSummoned.
> - **H6 fixed** — team-aware Ally/Enemy pools, `Ownership=Random` shuffles, `Ownership=Target`
> chains to the prior action's targets, `PreValidateClientTileTargets` flattens sub-groups.
> - **H7 fixed** — DOT/HOT tick only at the applying player's turn end.
> - **Builder** — UpTo checkbox added (parsed/compiled); dead triggers/effects delisted.
> - **Client** — cost-group / action-group prompt labels fixed (normalized keys + amounts).
>
> **Deferred** (see §7): validation-on-save endpoint (Phase 2.9), remaining H5 effects
> (SearchAndPlace→Battlefield, RevealCards N/ToOwnership, ChannelCardFromZone Filters/range flags,
> TakeControl duration reversal), H8 duration edge cases, H9 builder round-trip preservation,
> Phase 3 builder fields, Phase 4 client parity items (zone-scope card picking, prompt resilience,
> filter parity, OR-group UX), Phase 5 hygiene.
**Date:** 2026-07-02
**Scope reviewed:**
- Server engine: `Server/src/SOR.Game/Abilities/*` (AbilitySystem.cs, AbilityContext.cs, all Models), `GameEngine.cs`, `Handlers/GameHandlerBase.cs`
- Admin authoring: `Server/src/SOR.Admin/Components/Pages/Cards/AbilityBuilder.razor`, `CardEditor.razor`
- Client play: `Client/origin-client/scenes/game/*` (ability_targeting.gd, server_prompt_handler.gd, selection_controller.gd, game_screen.gd)
- Card types considered: **Spirit / ArchSpirit / Instinct / Repentance / Ruin** (plus SpiritToken & Terramorpha where they interact)
---
## 1. Executive summary
The ability pipeline (Builder JSON → engine resolution → client targeting/prompts) is architecturally sound, but the three layers have drifted apart. The most damaging discrepancies:
| # | Issue | Impact |
|---|-------|--------|
| C1 | Builder always emits `ActionGroup`; the **Passive** path executes only the obsolete flat `Actions` array | **Every Passive ability authored in the admin tool does nothing in game** |
| C2 | ArchSpirit lives in `player.ArchSpirit`, not `player.Field`; nearly all engine scans/lookups search `Field` only | **ArchSpirit Triggered abilities never fire; ArchSpirit Passives never apply; ArchSpirit Actives that pause (cost/target picks) are lost on resume** |
| C3 | ~14 trigger types offered by the builder are never matched and/or never fired by the engine | Designers can author dead triggers with no warning |
| C4 | All resume paths (`ResumeCostPick`, `ResumeTargetPick`, `ResumeActionGroupPick`, …) look up the ability source **only among battlefield FieldCards** | Repentance/Instinct effects that pause mid-resolution lose their source (the card is already discarded); costs can be paid with the effects silently dropped |
| C5 | Triggered-ability target prompt sends the client **only the first pick action** (client submits `ActionIndex=0`), but `ResumeTriggeredAbility` replays the **full** action array with original indices | Any triggered ability whose pick action is not action 0 throws `INSUFFICIENT_TARGETS` after the player picks |
| C6 | Builder offers `StatTarget = "Base"` which does not exist in the server enum | One bad dropdown selection makes the card's **entire** AbilitiesJson fail deserialization — `ParseAbilities` throws inside `FireTrigger`/`ActivateAbility` for that card |
| C7 | Three builder-offered effects have **no runtime implementation**: `SetStatModMultiplier`, `ChannelCard`, `ModifySacrificeTokenReturn` | Silent no-ops in play |
Sections 3–6 give the full catalog; Section 7 is the phased fix plan with exact file/function targets.
---
## 2. How the pipeline fits together (context)
1. **Authoring** — `AbilityBuilder.razor` edits `AbilityDefinition[]` JSON stored on `CardDefinition.AbilitiesJson`. It always emits the modern `ActionGroup` shape (`Compile()`, line ~2843) and reads both `ActionGroup` and legacy `Actions` on load.
2. **Resolution** — `AbilitySystem` (static class) parses AbilitiesJson per call. Entry points:
- `ActivateAbility` (player-activated Active on a unit),
- `FireCardEffects` (Repentance/Instinct on channel — runs their `Active` defs),
- `FireTrigger` (Triggered defs, scanned from Battlefield + Hand/Discard/Deck when `SourceZoneGate` set),
- `ApplyPassivesForSource` / `ApplyPassivesToNewTarget` (Passive),
- Aura evaluation (`EvaluateAuras*`, `ApplyAuraEffects`),
- `FireRuinAbilities` (turn-start Ruin activation).
Interactive pauses are stored on `GameState` as `Pending*` records and resumed by `Resume*` methods; `GameHandlerBase.PushPendingPromptsAsync` pushes them to the chooser client. State is only persisted on handler success (exception ⇒ in-memory mutation discarded).
3. **Client** — `ability_targeting.gd` walks the flattened action list collecting `{actionIndex, instanceId|coord|branchIndex}` targets before sending `activate_ability` / `play_card_with_targets`; `server_prompt_handler.gd` renders the eight server-driven `Pending*` prompts.
---
## 3. Critical findings (break correctness now)
### C1 — Passive abilities authored in the builder never execute
- `ApplyPassivesForSource` (AbilitySystem.cs:5170) and `ApplyPassivesToNewTarget` (:5196) call `ExecuteActions(def.Actions, …)` — the `[Obsolete]` flat array.
- The builder **always** writes `ActionGroup` and never writes `Actions` (AbilityBuilder.razor `Compile()`, ~line 2843), so `def.Actions` is `[]` for every builder-authored card.
- The Aura path does this correctly via `GetEffectiveActions` (:5495). Only Passives are broken.
**Fix:** in both passive methods, replace `def.Actions` with `GetEffectiveActions(def, ctx, 0, null, def.Duration ?? fallback) ?? []`. Note interactive OR/XOR groups make no sense for Passives — either flatten with `FlattenAndGroup(def.ActionGroup)` or validate/reject OR-root Passives in the builder.
### C2 — ArchSpirit is invisible to most of the ability engine
`player.ArchSpirit` is *not* in `player.Field` (see `GameEngine.PlaceArchSpirit` / `Ascend` :508–516). Consequences:
| Path | Location | Effect |
|------|----------|--------|
| `FireTrigger` scan builds candidates from Field/Hand/Discard/Deck only (:301–308) | ArchSpirit **Triggered abilities never fire** |
| `ApplyPassivesForSource` looks up source in `p.Field` (:5156–5159) | ArchSpirit **Passives never apply** (GameEngine.cs:581 calls it, it returns silently) |
| `ApplyPassivesToNewTarget` iterates `player.Field` sources (:5185) | ArchSpirit passives never re-apply to newly placed units |
| `EvaluateAurasOnEnter` looks up the *new* unit in `p.Field` (:5342–5345) | Placing/ascending an ArchSpirit never fires its own aura-enter (movement transitions are OK — `BoardUnits` includes the arch) |
| All `Resume*` methods find source via `SelectMany(p => p.Field)` (e.g. :749, :944, :1004, :1150, :1343, :1500, :1678, :1943) | ArchSpirit Actives that pause **lose their source**; worst case `ResumeCostPick` pays the cost then `return state` (:947) — cost consumed, effects never run |
| `FindCardOwner` (:3879) ignores ArchSpirit | e.g. `OwnershipIsCondition` on an arch subject returns false |
**Fix:** add one helper and use it everywhere:
```csharp
private static IEnumerable<FieldCard> AllBattlefieldUnits(PlayerState p) {
if (p.ArchSpirit is not null) yield return p.ArchSpirit;
foreach (var fc in p.Field.OfType<FieldCard>()) yield return fc;
}
```
(`BoardUnits` already exists for auras — promote it/extend it and use it in `FireTrigger`, both passive methods, `EvaluateAurasOnEnter/OnLeave`, all `Resume*` source lookups, and `FindCardOwner` (or add a `FindUnitAnywhere`).)
### C3 — Trigger support matrix has three failure tiers
The builder offers 40 trigger types (`TriggerTypesList`, AbilityBuilder.razor:2200). Runtime support:
**Tier B — fired by engine but never matched** (missing `case` in `TriggerMatches`, AbilitySystem.cs:4369):
- `OnUnitAbilityActivated` (fired at GameEngine.cs:1152 — dead on arrival)
**Tier C — matched but never fired anywhere** (no `FireTrigger` call with that kind):
- `OnDamageDealt` (ApplyDamageToUnit fires `BeforeDamageApplied` and `DamagePrevented` but never `DamageDealt`; combat in GameEngine doesn't either)
- `OnUnitLeaveBattlefield`
- `OnSPGained`, `OnSPSpent`, `OnSTGained`, `OnSTSpent` (neither SP/ST costs in `PaySingleCost` nor `ModifySP/ST` effects nor turn accumulation fire them)
- `OnCardDrawn` (`DrawCards` helper :3827 and engine draw path don't fire it)
**Tier D — neither fired nor matched, and most lack a `TriggerEventKind` member** (AbilityContext.cs:84):
- `OnUnitMPSpent`, `OnHealed`, `OnTokenSummoned`, `OnStatModified`, `OnAbilityAdded`, `OnAbilityRemoved`, `OnGenusChanged`, `OnTileAffinityChanged` (kind exists, unmatched/unfired), `OnCardDiscarded`, `OnCardReturnedToHand`, `OnCardReturnedToDeck`, `OnDeckShuffled`, `OnCardsRevealed`, `OnTargetedByAbility`, `OnEffectApplied`
**Fix (two-pronged):**
1. Short term — remove Tier C/D triggers from `TriggerTypesList` (or badge them "NOT IMPLEMENTED") so designers can't author dead cards.
2. Engine work — per trigger: add the `TriggerEventKind` member, the `TriggerMatches` case, and the `FireTrigger` call at the mutation site (e.g. `OnHealed` inside `HealEffect`/HOT tick; `OnCardDrawn` inside `DrawCards`; `OnDamageDealt` at the end of `ApplyDamageToUnit` and the engine combat path; `OnUnitLeaveBattlefield` in `KillUnit`/`ReturnToHand`/`SendToDiscard`; `OnTileAffinityChanged` in the tile effects + Terramorpha channel; `OnTokenSummoned` in `SummonToken`/`CloneSpiritAsToken`).
### C4 — Resume paths lose non-battlefield sources (Repentance/Instinct, zone-gated triggers)
- `GameEngine.ChannelCard` (:441–457) pays cost, calls `FireCardEffects`, then **discards the card even if a pause was set**, and fires the `Channeled` trigger immediately.
- If any action pauses (OR-group pick, opponent target pick, `StackDeck`, `ChannelCardFromZone` TargetTile, cost group…), every `Resume*` looks the source up in `Field` → null:
- `ResumeCostGroupPick`/`ResumeCostPick`/`ResumeTriggeredAbility` **return early** — the remaining effects are silently dropped (cost already paid).
- `ResumeActionGroupPick`/`ResumeTargetPick`/`ResumeTilePick` continue with `Source = null` — source-relative filters, ranges, `DealDamageToSelf`, `Self.*` value refs all silently degrade.
- Same story for `SourceZoneGate` triggers firing from Hand/Discard/Deck: `ResumeTriggeredAbility` (:1943) can't find the hand card and drops the ability.
**Fix:**
1. Add a universal source lookup (`FindUnitAnywhere`: Field + ArchSpirit + Hand + Discard + Deck across players) used by all `Resume*` methods.
2. In `ResumeCostPick`, don't `return state` when the source is gone *after* the cost was paid — either refuse to pay (check first) or execute the actions with a null-source context.
3. In `ChannelCard`, move the discard + `Channeled` trigger into a completion callback: only discard when `!state.HasPendingInteraction()`, and let the final `Resume*` complete the discard (store `PendingChannelCompletion { cardInstanceId }` on state, or simpler: discard immediately but pass the discarded card instance into the resume context via `SourceInstanceId` + the universal lookup from (1)).
### C5 — Triggered-target prompt index contract is broken
- `PushPendingPromptsAsync` (GameHandlerBase.cs:405–425) extracts the **first** action needing a pick and sends only that one; the client (ability_targeting.gd `on_triggered_target_request`) builds `ability_def` from it and submits targets with `actionIndex = 0`.
- `ResumeTriggeredAbility` (AbilitySystem.cs:1959) replays the **entire** `pending.ActionsJson` array; `ResolveTargets` matches `t.ActionIndex == actionIndex` with the *original* index. If the pick action is at index ≥ 1, the client's `actionIndex 0` never matches → `INSUFFICIENT_TARGETS` thrown after the player already picked. (Compare `ResumeTargetPick`, which correctly replays the paused action *at index 0* — :1689–1695.)
**Fix (choose one):**
- (a) Send the **full** `ActionsJson` in `TriggeredTargetRequestPush` and let the client walk all actions (it already knows how — auto-skip server-resolved ones). Client change: none (it already handles an array).
- (b) Keep first-action-only push, but record the original index in `PendingTriggeredTarget` and re-map client `ActionIndex 0 → storedIndex` in `ResumeTriggeredAbility`.
Recommend (a) — it also fixes triggered abilities needing picks in *multiple* actions.
### C6 — Builder can emit values the engine cannot deserialize; one bad ability poisons the whole card
- `StatTargetValues = ["Current", "Base", "Max"]` (AbilityBuilder.razor:2167, dropdown used at :3560). Server `StatTarget` enum has only `Current, Max` (Effects.cs:128). `"Base"` → `JsonException` on `ParseAbilities`.
- `ParseAbilities` (AbilitySystem.cs:77) has no error isolation. It is called for every card in `FireTrigger`'s scan — one malformed card breaks **every** trigger evaluation and any activation of that card, throwing out of engine mutation paths.
**Fix:**
1. Remove `"Base"` from the dropdown (map existing saved `"Base"` → `"Current"` on parse).
2. Make `ParseAbilities` resilient: try/catch per card returning `[]` with a logged warning (and ideally per-array-element leniency).
3. Add a server-side **validation endpoint** used by CardEditor Save: round-trip the compiled JSON through `AbilitySystem.CreateJsonOptions()` deserialization and refuse to save on error (see §7 Phase 2).
### C7 — Builder-offered effects with no runtime implementation
No `case` exists in `ExecuteEffect` for:
- `SetStatModMultiplierEffect` (offered in "Stat Modification")
- `ChannelCardEffect` (offered in "Zone Operations" — superseded by `ChannelCardFromZone` but still listed)
- `ModifySacrificeTokenReturnEffect` (offered in "Token & Deferred"; note `SetFixedSacrificeReturn` *is* implemented)
**Fix:** implement or delist. Recommend: remove `ChannelCard` from `EffectGroups` (keep parse-compat), implement `ModifySacrificeTokenReturn` (delta version of the existing fixed override), and either implement or remove `SetStatModMultiplier`.
---
## 4. High findings (wrong results in real games)
### H1 — Trigger parameter fields are ignored during matching
`TriggerMatches` checks kind + ownership only. Ignored everywhere: `Amount`/`AmountComparator` (OnDamageDealt, OnDamagePrevented, OnHealed, BeforeDamageApplied, OnUnitMPSpent, OnSP*/OnST*), `DamageType` (OnDamageDealt), `Filter` (OnUnitMove/Attack/Death/EnterBattlefield/…), `CardDefinitionId` (OnChanneled), `OccupantFilters` (Ruin triggers), `Cause` (OnCardDiscarded), `Stat` (OnStatModified). The builder happily authors all of these.
**Fix:** thread `occurrence.Data.Amount` etc. through `TriggerMatches` (a `CompareInt(t.AmountComparator, occ.Data?.Amount ?? 0, t.Amount.Value)` guard per trigger with `Amount`), and evaluate `Filter` against the acting unit (`occ.Data.SourceId`) the way `TriggerSourceMatchesFilter` already does for OnDamageDealt.
### H2 — Client cannot pick cards in zone scopes; sends player accountIds instead
For `Scope ∈ {Hand, Deck, Discard, AnyZone}` with a card-type target, the client shows a **player/zone** panel and submits `instanceId = accountId` (ability_targeting.gd:792–831). The server filters candidates by `clientIds` containing card InstanceIds (AbilitySystem.cs:2048–2056) → zero matches → `INSUFFICIENT_TARGETS`.
**Fix:** two options —
- Server: when `Scope != Battlefield` and the submitted id matches a player accountId, treat it as "restrict pool to that player" and auto-pick/prompt within it; or emit a proper `PendingTargetPick` with a candidate card list (like `CostPickRequestPush` does).
- Client: implement a card-picker panel fed by a server-provided candidates list. Recommend the server-push route — hidden zones (Deck, opponent Hand) must not leak card lists to the client without server mediation anyway.
### H3 — Static mutable state in `AbilitySystem` (cross-game leakage, no rollback, lost on restart)
`_triggerCountsPerTurn`, `_triggerCountsPerGame`, `_preventNextDamageByUnit`, `_preventDeathUnits`, `_sequenceDepth` (AbilitySystem.cs:46–57) are `static` process-wide:
- Two concurrent sessions share `_sequenceDepth` → `UntilEndOfSequence` effects can expire early/late in the *other* game.
- Instance IDs are 8 hex chars — collisions across sessions make shields/limits bleed between games.
- Handler exceptions roll back `GameState` (state is re-loaded from JSON per action; `SaveStateAsync` only on success) but **not** these dictionaries → a failed action can leave a phantom damage shield or a consumed trigger-limit.
- Server restart loses active PreventDeath/PreventNextDamage markers even though the reversal `ActiveEffect` rows persist in state (the reversal then no-ops incorrectly / marker missing).
**Fix:** move all five into `GameState` (e.g. `Dictionary<string,int?> PreventNextDamageByUnit`, `HashSet<string> PreventDeathUnits`, `Dictionary<string,int> TriggerUsesThisTurn` keyed `"{instanceId}:{abilityKey}"` and cleared on turn advance, `int SequenceDepth`). They serialize with the state and roll back naturally.
### H4 — `PreventDeathEffect` options ignored; ArchSpirit death bypasses prevention
- `KillUnit` (:3717–3721) always sets HP to `max(cur,1)`; `DamageTakenSetToHp` and `DamageIgnored` are never read.
- ArchSpirit (leader) death eliminates the player *before* `BeforeUnitDeath` fires or `_preventDeathUnits` is consulted (:3694–3706) — a "prevent death" effect on your ArchSpirit does nothing.
**Fix:** consult prevention (and fire `BeforeUnitDeath`) before the leader-elimination branch; honor the two option fields in the non-leader branch.
### H5 — Effect semantics diverge from their models (silent partial implementations)
| Effect | Field(s) ignored / wrong | Location |
|--------|--------------------------|----------|
| `PushUnit` / `PullUnit` | `BlockedDamage` never applied; blocked displacement silently aborts; push moves diagonally in one jump instead of stepping tiles | `DisplaceUnit` :3756 |
| `TakeControl` | `Duration` ignored (control is permanent, no reversal tracked); board `Tile.OccupantOwner` not updated (ownership filters/`OwnershipIs` now disagree with the board); no aura/passive re-evaluation | :2905 |
| `SearchAndPlace` | `Destination="Battlefield"` puts the card in **Discard** | :3444–3453 |
| `RevealCards` | `N` and `ToOwnership` ignored; just flags the single action target `IsRevealed` | :2773 |
| `ChannelCardFromZone` | No SP/ST sufficiency check — `CurrentSp/St` can go **negative** (:3268, :1589, :1421); `Filters`, `InOwnChannelRange`, `InTargetChannelRange`, `IgnoreTurnConstraint` never evaluated |
| `DrawCards` | Ignores `PlayerState.CanDrawCards`; `Player="Both"/"Any"` (builder options) unsupported — `ResolvePlayerForEffect` (:3948) only knows `enemy/opponent` vs actor; no `CardDrawn` trigger |
| `DiscardCards` | Ignores the action's resolved target — always uses its own `Player` string; `Filters` picks first-N, no player choice |
| `SetHealthMinimum` | One-shot raise only; no tracked floor (later damage ignores the minimum) | :2837 |
| `SummonToken` `TokenDefJson` | Deserialized with the ability JSON options; builder writes PascalCase fields — OK today, but `AbilitiesJson` nested string means token abilities are never validated |
| `Heal` / HOT | No `OnHealed` trigger (see C3); heal past `MaxHealth=null` capped at int.MaxValue (fine) |
| `ModifySP/ST` | No SPGained/SPSpent/STGained/STSpent triggers (see C3) |
### H6 — Targeting resolution correctness gaps
- **`TargetOwnership.Ally` ≡ `Enemy`**: `BuildCandidates` (:2173–2179) maps both to "every other player" with no `AreAllies` check — wrong in Teams/MultiTeam. Also `TargetOwnership.Enemy` includes allies.
- **`Ownership=Random` isn't random**: it's treated as server-resolved (:2061–2065) but candidates are never shuffled — `.Take(N)` picks the first N deterministic entries (:2092–2105). (`Chooser=Random` *is* shuffled — :2036–2046.)
- **`Ownership=Target` (chained) is unimplemented for card targets**: only `TargetType.Player` handles it (:1988–1992). For unit/card types it falls through to "all players' cards" and takes first-N. Chained targeting currently only works via `SearchDeck.ThenGroup` pre-seeding and `WithinRangeOf`/value `Ref`s.
- `PreValidateClientTileTargets` (:250) only walks the top-level AND group's direct actions — tile targets inside nested sub-groups skip pre-validation (cost is then wasted on a bad pick because use-count/cost happen before the nested validation throws).
### H7 — DOT/HOT tick multiplies with player count
`TickActiveEffects(state, activePlayerId)` (:4955) never uses `activePlayerId` — every `IsTick` effect ticks at **every** player's turn end. In a 4-player FreePlay lobby a "2 damage per turn" DOT deals 8 per round.
**Fix:** tick only when the tick's anchor matches (e.g. `td.OwnerAccountId == activePlayerId`, or better: give ticks an explicit `PlayerScope`).
### H8 — Duration edge cases
- `UntilStartOfOwnerTurn` and `UntilStartOfSourceOwnerTurn` are handled identically (:5022–5029) — both use `td.OwnerAccountId` (the *ability actor*), never the source unit's owner (differs after TakeControl / opponent-cast buffs).
- `WhileCondition` only re-evaluates at turn boundaries — mid-turn state changes (movement, damage) don't expire it, unlike conditional passives which re-evaluate via `ReEvaluateConditionalPassives`.
- `ReapplyAurasAtTurnStart` (:5390) strips **all** tracked effects for a source→target pair without reversal — including *non-aura* effects the same unit applied via an Active ability → permanent stat drift.
- Builder never offers `WhileCondition` (not in `DurationTypeValues`) — fine, but then the engine's `WhileCondition` machinery is unreachable from authored content; decide to expose or remove.
### H9 — Builder round-trips lose data (silent stripping on open+save)
`ParseJson`/`Compile` drop anything the UI doesn't model. Opening a hand-authored card and saving silently deletes:
- Cost `PickMode`, `Filters`, nested `CostGroup.Groups`
- `TargetCount.UpTo` (always compiled `false`, :2891), `Chooser=Ally`
- All but the **first** target filter, and all filter parameters (only `$type` is kept, :2895–2897)
- `Action.ChooseOne` (branches) — not parsed at all
- Nested sub-group `Groups` (compiled as empty array, :2838)
- `TriggerLimitPerGame`, `SourceZoneGate`, `OnEnterAuraActions`, `OnLeaveAuraActions`, `Duration.PlayerScope`, trigger `AmountComparator`/`Filter` objects (only SourceFilter `$type` for OnDamageDealt)
**Fix:** preserve-unknown strategy — keep the original `JsonObject` per ability and only overwrite the fields the UI actually edits; or add explicit UI for each (see §7 Phase 3 priority list).
---
## 5. Medium findings (UX, robustness, drift)
**Server**
- M1. `FireTrigger` supports only **one** `PendingTriggeredTarget` at a time — a second matching ability in the same occurrence is *skipped entirely* (returns at :416 mid-scan), not queued. Trigger limits are also incremented before the pause/execution, so an abandoned pick burns the per-turn/per-game use.
- M2. Interactive `PickMode` is only honored for 3 of 8 cost types (:588–592); others silently auto-resolve. Builder can't set PickMode at all (see H9) — so today all costs auto-resolve; once the builder exposes PickMode this mismatch will surface.
- M3. `IsAllyTurnCondition` evaluates identically to `IsOwnTurn` (:4071); `Own()` maps `owner/self` through `AreAllies` (teammates count as "Owner") — intended for teams but contradicts the model docs; `PlayerPropertyCompareCondition` maps `ally → self` (:4184).
- M4. `HasFlagFilter` supports only 4 of the documented flags (:4317–4324; `CanDefend`, `CanBeSacrificed`, etc. always false).
- M5. `ResolveValue` supports only `Damage/Health/Defense/MP/SpCost/StCost` — no `MaxHealth`, `Tier`, player properties; `ResolveAffinity` supports only `Self.Affinity` (no `Target.Affinity` despite doc examples in AffinityExpr).
- M6. `RemoveAbilityEffect` matches by `Name` — abilities without names can't be removed/disabled; `AbilityUsesThisTurn` and trigger limits key by index/name — renaming an ability in the builder resets/breaks disable lists (`DisabledAbilities` stores names).
- M7. `FireCardEffects` runs **all** Active defs on a Repentance/Instinct card against the *same* clientTargets; the client only collects targets for the **first** Active def (game_screen.gd:685–710). CardEditor's "Exactly one · Active or Triggered" badge (:358–361) is advisory only — nothing enforces it, and a **Triggered** def on these cards can never fire anyway (they never reach the battlefield and the builder can't set `SourceZoneGate=Hand`).
- M8. Active ability `Range` on a Repentance/Instinct card breaks resolution: `FilterTargetsByAbilityRange` requires `ctx.Source is FieldCard` with a position (:2110–2117) → empty targets → `INSUFFICIENT_TARGETS`. The builder shows Range for every Active ability regardless of card type.
- M9. Ruin cards: engine only auto-activates `OnRuinActivationTrigger` abilities (`FireRuinAbilities`); an Active ability on a Ruin is server-legal but unreachable from the client (ruins are excluded from unit selection — selection_controller.gd:168–178). Builder gives no guidance.
**Client**
- M10. Client-side filter/condition coverage is a small subset of the server's: unit filters only `WithinRange`/`IsAdjacentToSource`; tile filters only `TileWithinRange`/`TileAffinityMatches`/`TileIsUnoccupied`; conditions only `IsOnTileWithAffinity` (ability_targeting.gd:485–581). Everything else (Genus, CardType, Tier, Health, Ownership filter, TileOccupancy, TileIsOnPlayerSide, channel-range tiles…) is not enforced in highlights → players click "valid-looking" targets that the server rejects with a generic error, or `UpTo` selections silently shrink.
- M11. Prompt panels clear `pending_req_id` and hide **before** the server confirms (e.g. `finish_cost_pick` server_prompt_handler.gd:138; tile pick selection_controller.gd:185–191). If the server rejects the pick (`INVALID_TILE`, `INVALID_COST_PICK_SELECTION`), the client has no prompt and no request id — the player is stuck until a reconnect re-push (`GameGetStateHandler`). Fix: keep the prompt until an ack, or re-open it from the error response.
- M12. Cosmetic label bugs: cost-group options read `typestr` but the normalized key is `type` → all options render "Option N" (server_prompt_handler.gd:175); action-group options read `targetType` but the key is `type` → labels show ownership only (:238).
- M13. Client OR/XOR handling: `flatten_and_group` (ability_targeting.gd:866) appends the OR group's leaf actions into the flat list and collects targets for them, but the server pauses for `PendingActionGroupPick` *before* costs and discards those targets — the player targets things twice (once speculatively, once after the pick). Consider detecting OR-root groups client-side and skipping upfront targeting.
- M14. Multiplayer allies: highlight pools use `Game.get_all_enemy_units()` + own field only — allied units in Teams mode are never offered for `Ownership=Ally/Any` targeting.
- M15. Off-turn Instinct is supported end-to-end (client gate game_screen.gd:641, server gate GameEngine.cs:272–276) — but the ability panel/highlight paths never check `CanChannelInstinct` etc.; server rejects with generic errors.
---
## 6. Card-type-specific summary
| Card type | Channel/entry path | What works | What's broken |
|-----------|--------------------|-----------|---------------|
| **Spirit** | `ChannelCard` → battlefield; Actives via `ActivateAbility`; Triggered via battlefield scan; Passives at placement | Active flow incl. costs, OR-groups, most effects; triggered scan; auras | Passives dead (C1); trigger param filters ignored (H1); zone-scope targeting (H2) |
| **ArchSpirit** | `PlaceArchSpirit` / `Ascend` / `Transition`; lives in `player.ArchSpirit` | Active abilities *until they pause*; auras on movement; DOT/reversals (explicit arch lookups exist) | Triggered never fire, Passives never apply, aura-on-enter skipped at placement, paused Actives lost on resume (C2); PreventDeath ineffective on leader (H4) |
| **Instinct** | Hand click → first Active def targeted → `ChannelCard` → `FireCardEffects` → discard; playable off-turn | Simple immediate effects with upfront targets | Any pausing effect loses the source & can drop remaining effects (C4); only first Active def gets targets (M7); Range breaks resolution (M8); Triggered defs unreachable (M7) |
| **Repentance** | Same as Instinct, but active-player-only | Same | Same as Instinct |
| **Ruin** | `ChannelCard` → random matching tile; `FireRuinAbilities` each turn-start picks ONE eligible `OnRuinActivation` ability at random | Turn-start activation incl. conditions, disable-duration, observer triggers, source-skip guard | Active abilities unreachable from client (M9); `OccupantFilters` ignored (H1); ruin triggered abilities other than OnRuinActivation only fire from battlefield scan (they do — ruins are in Field — OK) |
| **SpiritToken** | `SummonToken` / `CloneSpiritAsToken` | Stat cloning, aura/passive hookup on summon (SummonToken path) | `CloneSpiritAsToken` skips `ApplyPassivesForSource/ToNewTarget` (only aura enter, :3371); `OnTokenSummoned` never fires (C3) |
---
## 7. Solution map — phased plan
### Phase 1 — Stop the bleeding (small, high-yield engine fixes)
1. **Passives use ActionGroup** — `AbilitySystem.cs:5170, 5196`: swap `def.Actions` → flattened `GetEffectiveActions`. *(C1 — one-line-ish, unblocks all authored passives)*
2. **Universal unit lookup** — add `AllBattlefieldUnits` / `FindUnitAnywhere`; apply to `FireTrigger` scan, passive methods, `EvaluateAurasOnEnter/OnLeave`, `FindCardOwner`, and all 8 `Resume*` source lookups. *(C2, C4)*
3. **Triggered-target contract** — push full `ActionsJson` in `TriggeredTargetRequestPush` (GameHandlerBase.cs:407–413). *(C5)*
4. **Deserialization hardening** — try/catch per card in `ParseAbilities`; remove `"Base"` from `StatTargetValues`. *(C6)*
5. **Delist dead content in the builder** — remove Tier C/D triggers from `TriggerTypesList` (or suffix " (coming soon)" and block Compile); remove `ChannelCard`, `SetStatModMultiplier`, `ModifySacrificeTokenReturn` from `EffectGroups` until implemented. *(C3, C7)*
6. **ResumeCostPick ordering** — verify source exists (via new lookup) *before* paying the interactive cost; execute actions with degraded context rather than returning. *(C4)*
7. **Tick scoping** — use `activePlayerId` in `TickActiveEffects`. *(H7)*
### Phase 2 — Correctness of state & validation
8. **Move static state into GameState** — prevent markers, trigger counts, sequence depth (H3). Add turn-advance cleanup for per-turn counts.
9. **Server-side ability validation on save** — new endpoint (or direct call in CardEditor Save): deserialize compiled JSON with engine options; walk definitions for structural lint (Passive with OR-root group, Active Range on non-unit card types, Triggered without TriggerEvent, trigger types not in the supported set, effects without runtime cases, `TokenDefJson` parse check incl. nested AbilitiesJson). Surface errors in the builder UI. *(C6/C7 prevention, M7/M8/M9 guidance)*
10. **PreventDeath completeness** — honor `DamageTakenSetToHp`/`DamageIgnored`; check prevention + fire `BeforeUnitDeath` for leaders before elimination. *(H4)*
11. **Trigger param matching** — Amount/comparator, DamageType, Filter, CardDefinitionId, OccupantFilters in `TriggerMatches`. *(H1)*
12. **Targeting fixes** — team-aware `Ally`/`Enemy` in `BuildCandidates`; shuffle for `Ownership=Random`; implement chained `Ownership=Target` for card targets (resolve to prior action's resolved targets); recurse `PreValidateClientTileTargets` into sub-groups. *(H6)*
13. **Fire the missing engine triggers** — `DamageDealt`, `CardDrawn`, `SPGained/Spent`, `STGained/Spent`, `UnitLeaveBattlefield`, then re-enable them in the builder list. Add `Healed`, `TokenSummoned`, `TileAffinityChanged` next (require new `TriggerEventKind` members + match cases). *(C3)*
14. **Effect semantics** — `ChannelCardFromZone` cost check (no negative SP) + honor `Filters`/channel-range flags; `SearchAndPlace` Battlefield destination (reuse `ReturnToBattlefieldEffect` logic); `TakeControl` duration reversal + `Board.PlaceUnit` re-own + aura/passive re-eval; `Push/Pull` BlockedDamage + per-tile stepping; `RevealCards` N/ToOwnership; `DrawCards` CanDrawCards + Both/Any; token summon passive hookup in `CloneSpiritAsToken`. *(H5)*
15. **Repentance/Instinct pause lifecycle** — defer discard + `Channeled` trigger until no pending interaction (C4.3); enforce "exactly one Active" for these card types in validation.
### Phase 3 — Builder completeness (respect what the engine supports)
16. **Round-trip preservation** — keep unedited JSON properties per ability (retain original `JsonObject`, patch only UI-owned fields). *(H9 — do this before adding new fields so old data stops being destroyed)*
17. New UI fields, in value order: `UpTo` checkbox; multi-filter editor with parameters (reuse `ConditionGroups` pattern); cost `PickMode` + cost `Filters`; `TriggerLimitPerGame` + `SourceZoneGate` (needed for hand-triggered Instinct designs); `ChooseOne` branch editor; trigger `AmountComparator`/`Filter`; aura `OnEnter/OnLeaveAuraActions`; `Chooser=Ally`; `ReturnToDeck Position=Random`.
18. **Card-type-aware authoring** — when the editor hosts a Repentance/Instinct card: hide Range/UsesPerTurn/Aura/Passive options, enforce single Active; for Ruin: default to `OnRuinActivation` triggered template; for ArchSpirit/Spirit: full set. (CardEditor already knows the card type — pass it as a parameter to `AbilityBuilder`.)
19. **Form-view sub-group actions** — render the full action editor for sub-group actions (currently only add/remove rows, :797–811).
### Phase 4 — Client alignment
20. **Zone-scope card picking** — server-mediated candidate push (like cost pick) + client card list panel. *(H2)*
21. **Prompt resilience** — don't clear `pending_req_id`/panel until server ack; on error response with a pending prompt still in state, re-show it. *(M11)*
22. **Label fixes** — normalized-key lookups (`type`, `amount`) in cost/action group prompts; show cost amounts. *(M12)*
23. **Filter parity** — port the remaining target filters/conditions used by live cards to `unit_passes_filters`/`tile_passes_filters` (Genus, CardTypeIs, Tier, Health, Ownership, TileOccupancy, TileIsOnPlayerSide, channel-range). Consider generating a shared filter-spec (server exports a JSON schema of filter semantics) instead of double implementation.
24. **OR-group UX** — skip upfront targeting for OR/XOR root groups (server prompts anyway). *(M13)*
25. **Allied targeting** — include allied players' units in highlight pools for Teams. *(M14)*
### Phase 5 — Performance / hygiene (low)
- Cache parsed `AbilityDefinition[]` per (`InstanceId`, AbilitiesJson hash) — `FireTrigger` currently JSON-parses every card in every zone on every event.
- Prune `_triggerCountsPerTurn` on turn advance (moot if moved into state, Phase 2.8).
- Remove duplicate `[PolyType]` attributes on sealed condition/filter classes (declared on both the base and themselves).
- `IsAllyTurnCondition` real implementation or removal; document team semantics of `Owner`.
- Deduplicate `_jsonOpts` vs `CreateJsonOptions()`.
---
## 8. Suggested test plan
**Engine unit tests (SOR.Game):**
1. *Passive via ActionGroup*: builder-shaped JSON (ActionGroup only) Passive `+1 Damage to Self` — assert stat applied on placement, reverted on death. (Red today.)
2. *ArchSpirit triggered*: arch with `OnTurnStart → DrawCards` — assert fires. (Red today.)
3. *ArchSpirit active with SelfPick discard cost*: activate, resume cost pick — assert effects execute and cost paid exactly once. (Red today.)
4. *Triggered pick at action index 1*: triggered def `[buff self, deal 2 to chosen enemy]` — resume with client pick — assert no INSUFFICIENT_TARGETS. (Red today.)
5. *Repentance with StackDeck (chooser Self)*: channel, resume reveal pick — assert deck reordered and card discarded exactly once. (Partially red.)
6. *Trigger matrix contract test*: reflection over `TriggerTypesList` (builder) ⇒ each must have a PolyType, a `TriggerEventKind`, a `TriggerMatches` case (assert non-`false` for a synthetic occurrence), and at least one `FireTrigger` call site (static analysis list). Keeps builder/engine in lockstep.
7. *Effect matrix contract test*: every `EffectGroups` entry has an `ExecuteEffect` case (e.g. via a test that executes each effect against a dummy target and asserts *something* observable or a known no-op whitelist).
8. *DOT in 3-player game*: assert one tick per round, not per player-turn.
9. *Round-trip test (Admin)*: for each feature-bearing sample JSON (PickMode, UpTo, ChooseOne, SourceZoneGate…), `ParseJson` → `Compile` → assert JSON-equivalent.
**Manual/integration:**
- Ruin with two OnRuinActivation abilities + occupant filter; Instinct channeled on opponent's turn with an OR cost group; aura linger duration across ascension; TakeControl across turn boundary.
---
*Line references are to the state of the code on 2026-07-02 (branch `master`). All findings were verified by reading the code — none are speculative — except where marked "Consider/decide".*
+494
View File
@@ -0,0 +1,494 @@
# SOR.Admin 12-Factor Refactor Plan
Date: 2026-06-10
Scope reviewed:
- `Server/src/SOR.Admin`
- `Server/Dockerfile.admin`
- Admin dependencies in `SOR.Ai`, `SOR.Cdn`, `SOR.Database`, `SOR.Networking.Nats`, and `SOR.Shared`
- Admin Blazor pages under `Server/src/SOR.Admin/Components/Pages`
Reference: https://12factor.net/
## Executive Summary
`SOR.Admin` is a separate deployable Blazor Server application, not a service module inside `SOR.Host`. It already has several 12-Factor-friendly traits: its own Dockerfile, port binding through ASP.NET Core, Keycloak OIDC authentication, Redis-backed DataProtection keys for multi-pod cookie compatibility, environment-overridable configuration, and explicit dependencies on PostgreSQL, Redis, NATS, CDN/S3-compatible storage, and Keycloak.
The main gaps are structural and operational:
- `Program.cs` is a large composition root that configures auth, SignalR, Identity, Redis, DataProtection, NATS, AI services, CDN, all DbContexts, forwarded headers, routes, migrations, and OIDC discovery.
- The app runs all schema migrations during normal web startup.
- Most Blazor pages inject `DbContext` directly and contain query, command, validation, and UI logic together.
- Several admin pages are very large, especially `AbilityBuilder.razor`, `CardEditor.razor`, `BoardTemplateBuilderPage.razor`, `AccountDetail.razor`, `TileModelManagerPage.razor`, and `CdnBrowser.razor`.
- Admin depends on every database schema, which is valid for an admin console but needs explicit readiness and operational boundaries.
- CDN and file upload paths are mixed into UI components.
- `FeatureFlags.razor` says Redis feature flag wiring is pending even though Redis is registered in `Program.cs`.
- External browser assets are loaded from public CDNs at runtime.
- Health is liveness-only; readiness does not account for PostgreSQL, Redis, NATS, CDN, or Keycloak.
The plan is to keep `SOR.Admin` as a separate deployable admin web app, but split startup, move page logic behind application services, separate one-off maintenance tasks from runtime startup, and add typed config, readiness checks, and auditability.
## Current Structure Observations
### Strong Foundations
- `SOR.Admin` is its own executable project and Docker image.
- Keycloak OIDC protects the app with a fallback policy requiring the `sor-admin` role.
- Redis-backed DataProtection keys allow multiple Admin pods to decrypt the same auth cookies.
- The app supports TLS-terminating ingress through forwarded headers.
- `Dockerfile.admin` uses separate build and runtime stages and runs as a non-root user.
- Admin pages cover the expected operational domains: accounts, cards, collection, bazaar, chat, game, content, AI, support, versioning, website, and reports.
- CDN operations are behind `ICdnClient` for uploads, even though some components also use S3 directly for browsing.
### Main Problems
- Runtime startup applies migrations for all contexts.
- `Program.cs` has too many responsibilities and no typed admin-specific options.
- Redis connection defaults to `localhost:6379` if not configured.
- NATS defaults to `nats://localhost:4222` if not configured.
- SignalR maximum receive size is hardcoded to 100 MB.
- Cookie lifetime and admin role name are hardcoded.
- Identity password policy for admin account-management pages is hardcoded.
- OIDC discovery is checked at startup but failure is logged rather than affecting readiness.
- Data access is spread across Razor components through direct `DbContext` injection.
- Some pages perform high-impact operations such as account banning, collection changes, chat moderation, content edits, and CDN uploads without a central audit boundary.
- There is no visible `Server/tests/SOR.Admin.Tests` project.
## Target Admin Shape
Keep `SOR.Admin` as the deployable web admin app, but split it into focused areas:
```text
Server/src/SOR.Admin/
Program.cs
Configuration/
AdminOptions.cs
AdminAuthOptions.cs
AdminUploadOptions.cs
AdminDependencyOptions.cs
AdminOptionsValidator.cs
Bootstrap/
AdminAuthentication.cs
AdminAuthorization.cs
AdminDataProtection.cs
AdminDatabases.cs
AdminInfrastructure.cs
AdminEndpoints.cs
AdminHealthChecks.cs
Application/
Accounts/
Cards/
Content/
Bazaar/
Game/
Chat/
Collection/
Support/
Website/
Ai/
FeatureFlags/
Components/
Pages/
Shared/
Audit/
IAdminAuditLog.cs
AdminAuditEvent.cs
Operations/
MigrationRunner.cs
SeedRunner.cs
```
`Program.cs` should become startup orchestration only:
```csharp
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAdminOptions(builder.Configuration);
builder.Services.AddAdminAuthentication(builder.Configuration);
builder.Services.AddAdminAuthorization(builder.Configuration);
builder.Services.AddAdminDataProtection(builder.Configuration);
builder.Services.AddAdminInfrastructure(builder.Configuration);
builder.Services.AddAdminApplicationServices();
builder.Services.AddAdminHealthChecks(builder.Configuration);
var app = builder.Build();
app.UseAdminPipeline();
app.MapAdminEndpoints();
await app.RunAsync();
```
## 12-Factor Gap Map
### I. Codebase
Status: Mostly aligned.
Current state:
- `SOR.Admin` is in the same monorepo but is a separate executable and Docker image.
Plan:
- Keep Admin in the monorepo.
- Document Admin as its own deployable web process.
- Avoid coupling Admin runtime startup to unrelated service runtime behavior.
### II. Dependencies
Status: Mostly aligned, with frontend asset and layering gaps.
Current state:
- NuGet dependencies are centrally versioned.
- Admin references `SOR.Ai`, `SOR.Cdn`, `SOR.Database`, `SOR.Networking.Nats`, and `SOR.Shared`.
- Browser CSS/icons are loaded from jsDelivr at runtime.
Plan:
- Keep server dependencies explicit.
- Vendor or package frontend assets through the build instead of relying on public CDN availability at runtime.
- Move direct S3 browsing logic behind a CDN browser service.
- Avoid adding service-module references unless Admin actually needs runtime behavior from them.
### III. Config
Status: Partially aligned.
Current state:
- Keycloak values, connection strings, and CDN values can be overridden by env vars.
- Several operational values are hardcoded.
Plan:
- Add typed options and startup validation for:
- `Admin:RequiredRole`
- `Admin:CookieHours`
- `Admin:SignalRMaxMessageBytes`
- `Admin:MaxUploadBytes`
- `Admin:RunMigrationsOnStartup`
- `Admin:TrustForwardedHeaders`
- `Keycloak`
- `ConnectionStrings`
- `Redis`
- `Nats`
- `Cdn`
- In production, fail fast when required backing-service config is absent instead of silently defaulting to localhost.
### IV. Backing Services
Status: Mostly aligned, but readiness is incomplete.
Current state:
- Admin depends on PostgreSQL schemas, Redis, Keycloak, CDN/S3-compatible storage, and NATS.
- DataProtection keys are stored in Redis.
Plan:
- Treat all backing services as attachable resources via config.
- Add readiness checks for:
- identity database
- catalog database
- collection database
- bazaar database
- chat database
- game database
- support database
- Redis
- Keycloak discovery
- NATS when AI/admin messaging is enabled
- CDN/S3 when content upload/browser features are enabled
- Keep DataProtection key storage in Redis for multi-pod deployments.
### V. Build, Release, Run
Status: Partially aligned.
Current state:
- Docker build and runtime stages are separate.
- Runtime startup applies migrations for every context.
Plan:
- Keep Docker build/release separation.
- Move migrations out of web runtime startup into a release/admin process.
- Add a release checklist:
- build image
- run tests
- run database migrations
- seed roles if needed
- deploy Admin runtime
- Keep `RunMigrationsOnStartup` only as an explicit local-development escape hatch.
### VI. Processes
Status: Partially aligned.
Current state:
- Admin is a stateful-feeling Blazor Server process because user interaction lives on SignalR circuits.
- Correctness state lives in backing services, not process memory.
- AI calibration and self-play jobs are registered inside the Admin web process.
Plan:
- Keep Admin web process focused on interactive admin UI.
- Move long-running AI calibration/self-play operations to explicit job services or admin-triggered background jobs with durable status.
- Avoid running expensive maintenance work inline on the Blazor circuit.
- Ensure Admin can run multiple replicas without per-process correctness assumptions.
### VII. Port Binding
Status: Aligned.
Current state:
- Admin binds through ASP.NET Core and Docker exposes `8080`.
- It is designed to sit behind TLS-terminating ingress.
Plan:
- Keep port binding in Admin.
- Keep forwarded-header behavior configurable and documented.
- Add explicit ingress/OIDC redirect URI runbook entries.
### VIII. Concurrency
Status: Partially aligned.
Current state:
- Blazor Server circuits can hold scoped services for a long time.
- Pages inject EF Core DbContexts directly.
- Some components already note stale DbContext/concurrency issues.
Plan:
- Prefer `IDbContextFactory<TContext>` or short-lived application service scopes for page operations.
- Move write operations into application services with transaction boundaries.
- Add optimistic concurrency handling for content and catalog editors.
- Add per-operation cancellation and timeout behavior for uploads and long queries.
- Prevent large page components from retaining stale tracked entities for too long.
### IX. Disposability
Status: Partially aligned.
Current state:
- Web startup can block on migrations and OIDC discovery.
- Redis connection is eagerly created.
- Long-running admin operations may execute inside the web process.
Plan:
- Keep startup fast by moving migrations to release/admin process.
- Make readiness account for OIDC discovery instead of only logging failures.
- Ensure long-running jobs can be cancelled or resumed.
- Use bounded upload sizes and cancellation tokens for CDN uploads.
### X. Dev/Prod Parity
Status: Partially aligned.
Current state:
- Local defaults exist in `appsettings.json`.
- Production depends on Keycloak, Redis, PostgreSQL, CDN, and NATS.
Plan:
- Document local Admin dependencies and setup:
- PostgreSQL
- Redis
- Keycloak or a local OIDC test realm
- CDN/S3-compatible storage
- NATS for AI-triggering features
- Keep config keys identical across environments.
- Use feature toggles to disable unavailable local backing services cleanly.
### XI. Logs
Status: Partially aligned.
Current state:
- Admin uses ASP.NET Core logging.
- Some high-impact admin actions are not centralized for audit logging.
Plan:
- Keep logs as stdout event streams.
- Add structured audit logging for:
- account creation
- role changes
- bans/unbans
- session revocation
- catalog/card edits
- CDN uploads/deletions
- bazaar/store edits
- chat moderation
- game/session interventions
- feature flag changes
- Avoid logging secrets, access tokens, raw cookies, or CDN credentials.
### XII. Admin Processes
Status: Needs work.
Current state:
- Admin web startup currently runs migrations.
- Admin also exposes interactive pages for operational actions.
Plan:
- Separate one-off admin processes from Admin web runtime:
- migrate all databases
- seed roles and initial admin users
- repair content metadata
- cleanup stale sessions/uploads
- run AI calibration jobs
- validate Keycloak/OIDC setup
- Keep web Admin as a UI for invoking or monitoring operations, not the only executor of maintenance work.
## Refactor Phases
### Phase 0: Baseline and Tests
Deliverables:
- Add `Server/tests/SOR.Admin.Tests`.
- Add tests for:
- config validation
- auth policy requiring `sor-admin`
- route authorization defaults
- health and readiness endpoint behavior
- core application services after extraction
- Add smoke tests for page-level critical flows where feasible.
Acceptance:
- Startup behavior and security defaults are covered before refactoring.
### Phase 1: Split Program Startup
Deliverables:
- Extract authentication/OIDC setup.
- Extract authorization setup.
- Extract Redis/DataProtection setup.
- Extract database registration.
- Extract NATS/CDN/AI service registration.
- Extract HTTP pipeline and endpoints.
Acceptance:
- `Program.cs` is short and reads as orchestration.
- Startup behavior is unchanged except for intentional validation.
### Phase 2: Typed Options and Validation
Deliverables:
- Add admin options classes.
- Validate Keycloak authority/client/secret requirements.
- Validate Redis, NATS, CDN, upload, SignalR, and cookie settings.
- Remove localhost fallback behavior in production.
Acceptance:
- Bad production config fails before serving requests.
### Phase 3: Move Migrations to Admin Process
Deliverables:
- Extract `MigrateAllAsync` into a reusable migration runner.
- Add explicit command/process for migrations.
- Make startup migrations disabled by default in production.
Acceptance:
- Admin web startup does not mutate database schemas unless explicitly configured for local development.
### Phase 4: Application Services Per Domain
Deliverables:
- Add focused application services for:
- accounts
- cards/catalog
- ability builder
- content/CDN
- bazaar
- chat moderation
- game operations
- support
- website content
- AI operations
- feature flags
- Move page write logic into services.
Acceptance:
- Razor components no longer directly own persistence rules for high-impact mutations.
### Phase 5: Component Decomposition
Deliverables:
- Split large components:
- `AbilityBuilder.razor`
- `CardEditor.razor`
- `BoardTemplateBuilderPage.razor`
- `AccountDetail.razor`
- `TileModelManagerPage.razor`
- `CdnBrowser.razor`
- Move repeated editor/picker/upload UI into shared components.
- Move non-UI logic to services.
Acceptance:
- Large pages become composable views over testable services.
### Phase 6: Health, Readiness, and Observability
Deliverables:
- Keep `/health` as liveness.
- Add `/ready` for dependency readiness.
- Add readiness checks for required databases, Redis, Keycloak, NATS, and CDN where enabled.
- Add admin audit event logging.
Acceptance:
- Kubernetes can keep Admin out of rotation when dependencies are unavailable.
- High-impact admin actions have a traceable audit trail.
### Phase 7: Feature Flags and Operational Jobs
Deliverables:
- Wire `FeatureFlags.razor` to Redis through a service.
- Add explicit job/operation services for AI calibration and maintenance actions.
- Add durable job status if operations can outlive the circuit.
Acceptance:
- Admin can manage feature flags through the UI.
- Long-running operations are not tied to a single Blazor circuit.
### Phase 8: Frontend Asset and Upload Hardening
Deliverables:
- Vendor Bootstrap and Bootstrap Icons or package them as static assets.
- Make upload size limits configurable.
- Add CDN upload validation for extension/content type/size.
- Add cancellation and timeout handling for upload operations.
Acceptance:
- Admin runtime does not depend on public frontend CDNs.
- Upload behavior is explicit and controlled.
## Suggested Milestone Order
1. Add Admin tests for startup/security defaults.
2. Split `Program.cs` into bootstrap modules.
3. Add typed options and production validation.
4. Move migrations to explicit release/admin process.
5. Add readiness endpoint and dependency checks.
6. Extract application services for high-impact domains.
7. Decompose the largest Razor components.
8. Add audit logging for admin mutations.
9. Wire feature flags to Redis through a service.
10. Harden frontend assets and uploads.
## Risk Register
| Risk | Why It Matters | Mitigation |
|---|---|---|
| Migration behavior changes | Admin currently migrates all schemas on startup. | Add explicit migration command and local-only compatibility flag. |
| Auth redirect loops | OIDC, cookies, DataProtection, and forwarded headers are sensitive. | Preserve current behavior with tests before refactoring. |
| Stale EF tracking in Blazor circuits | Long-lived circuits can hold stale DbContexts/entities. | Use short-lived services or `IDbContextFactory`. |
| Large component regressions | Admin editors contain complex workflows. | Extract services first, then split UI in small steps. |
| Missing audit trail | Admin actions can alter production state. | Add centralized audit logging around write services. |
| Upload overload | Blazor Server uploads flow through SignalR. | Configurable limits, validation, and cancellation. |
| External CDN outage | Bootstrap/jsDelivr outage affects Admin UI. | Vendor frontend assets in the app build. |
## Definition of Done
The Admin refactor is complete when:
- `Program.cs` is only startup orchestration.
- Admin config is typed, validated, and production-safe.
- Runtime web startup does not apply migrations by default.
- `/health` and `/ready` have distinct meanings.
- Admin pages call application services for data access and mutations.
- Large Razor components are decomposed into smaller components and services.
- Admin operations have structured audit logging.
- Redis-backed DataProtection remains configured for multi-pod deployments.
- Keycloak/OIDC, Redis, PostgreSQL, NATS, and CDN dependencies are represented in readiness.
- Long-running maintenance and AI calibration work runs as explicit jobs or admin processes, not hidden web startup behavior.
+480
View File
@@ -0,0 +1,480 @@
# SOR.Ai 12-Factor Refactor Plan
Date: 2026-06-10
Scope reviewed:
- `Server/src/SOR.Ai`
- `Server/docs/SOR.Ai-Architecture-Plan.md`
- AI wiring in `Server/src/SOR.Host`
- AI touchpoints in `SOR.Game`, `SOR.Database`, `SOR.Networking.Abstractions`, and `SOR.Shared`
Reference: https://12factor.net/
## Executive Summary
`SOR.Ai` is a service module, not its own executable. It is registered by `SOR.Host` when the game service is enabled, while `AiPlayerSessionManager` is only started when `ENABLED_SERVICES` includes `ai`. That gives the project a useful split between AI message handlers and the dedicated AI worker loop, but the split is currently implicit and easy to misconfigure.
The project already has strong foundations:
- AI players are modeled as normal accounts and participate through the same game message handler path as human clients.
- Decision logic is separated into random, heuristic, MCTS, and neural engines.
- The runtime worker uses a hosted service and cancellation tokens.
- Neural inference is optional and falls back when no ONNX model is configured.
- Training, replay export, calibration, lobby AI slots, and admin match services are separate namespaces.
The main 12-Factor gaps are structural and operational:
- One DI module registers runtime worker infrastructure, lobby handlers, startup seeding, neural loading, admin-only services, self-play, calibration, and database contexts together.
- AI account and deck seeding runs during normal application startup.
- `AiPlayerSessionManager` keeps active sessions in process memory and assumes only one AI worker subscribes to game events.
- Turn execution starts fire-and-forget tasks and does not centrally track all in-flight session work for shutdown.
- Worker delays, polling intervals, difficulty profiles, strategy definitions, parallelism, and model contract details are mostly code constants instead of validated config.
- Neural model loading is path-based and static-accessible through `NeuralModelRegistry.Instance`, making model artifacts a filesystem concern rather than an attached release resource.
- Training and calibration jobs run inside the same module as runtime AI and need clearer process boundaries.
The plan is to keep `SOR.Ai` as the AI domain module, but split registration into explicit roles: game-facing AI handlers, AI runtime worker, admin AI services, and offline training/calibration jobs.
## Current Structure Observations
### Strong Foundations
- `SOR.Ai` depends on `SOR.Networking.Abstractions` and invokes existing game handlers through `IMessageHandler`.
- `AiNoOpClientConnection` lets AI use the normal authenticated game pipeline without a real socket.
- `AiAccountRegistry` exposes `IAiAccountRegistry` so `SOR.Game` can detect AI accounts without referencing the AI project directly.
- `AiPlayerSessionManager` is intentionally registered as a singleton but only hosted by the dedicated `ai` process role.
- `AiPlayerSession` polls game state and drives placement, draw, and main-phase decisions.
- Decision engines are grouped by behavior and difficulty: random, heuristic, Monte Carlo, and neural.
- Neural model startup is tolerant of a missing model and does not hard-fail lower environments.
- Training artifacts are represented through `TrainingRecord`, `TrainingDataWriter`, replay export, self-play, and calibration services.
### Main Problems
- `AddAiService` has too many responsibilities for a single registration method.
- Calling `AddAiService` from `game` means AI startup seed and neural loader run on every game-enabled host, even when the host is not the AI worker.
- The runtime role boundary depends on comments and `ENABLED_SERVICES` discipline rather than typed options and startup validation.
- `AiPlayerSessionManager` stores active sessions in a `ConcurrentDictionary<Guid, List<AiPlayerSession>>`, which cannot survive process restart and cannot coordinate multiple AI workers.
- NATS subscriptions are documented as no queue group, so multiple AI worker subscribers would all receive the same event.
- AI session tasks are started with `Task.Run` and discarded.
- ELO recording is also fire-and-forget.
- Turn execution directly resolves handlers from scoped DI and creates concrete decision engines with `new`, which makes runtime orchestration harder to test and observe.
- The neural model is loaded from `Ai:NeuralModelPath` and exposed through a static `NeuralModelRegistry.Instance`.
- Difficulty profiles, think times, mistake rates, strategies, model input/output names, self-play parallelism, and polling behavior are not externally validated runtime config.
- Seeding AI accounts/decks during app startup mixes release/admin work into the long-running web or worker process.
- Training and calibration can be triggered from admin services, but they are not clearly isolated as one-off admin processes.
## Target AI Shape
Keep `SOR.Ai` as the AI module, but organize it around explicit responsibilities:
```text
Server/src/SOR.Ai/
Configuration/
AiOptions.cs
AiRuntimeOptions.cs
AiNeuralOptions.cs
AiTrainingOptions.cs
AiSeedingOptions.cs
AiOptionsValidator.cs
Bootstrap/
AiCoreRegistration.cs
AiHandlerRegistration.cs
AiRuntimeRegistration.cs
AiAdminRegistration.cs
AiTrainingRegistration.cs
AiHealthChecks.cs
Runtime/
AiPlayerSessionManager.cs
AiSessionCoordinator.cs
AiSessionLeaseStore.cs
AiTurnExecutor.cs
AiTurnDispatcher.cs
AiRuntimeMetrics.cs
Decisions/
IAiDecisionEngineFactory.cs
AiDecisionEngineFactory.cs
Random/
Heuristic/
Mcts/
Neural/
Lobby/
AiLobbyService.cs
AiSlotAssigner.cs
AiDeckResolver.cs
Persistence/
IAiAccountRepository.cs
IAiDeckRepository.cs
IAiEloRepository.cs
IAiTrainingDataStore.cs
Models/
IAiModelStore.cs
NeuralModelRegistry.cs
NeuralModelVersion.cs
Operations/
SeedAiAccountsCommand.cs
SeedAiDecksCommand.cs
RunAiCalibrationCommand.cs
ExportAiTrainingDataCommand.cs
Admin/
AiMatchService.cs
```
Desired process roles:
- `game`: registers game handlers plus AI lobby handlers needed by player/admin messages.
- `ai-worker`: starts the AI session runtime and owns turn execution.
- `admin`: uses AI admin services but does not start AI runtime loops.
- `ai-jobs`: runs seeding, calibration, replay export, self-play, and model-management jobs as one-off processes.
## 12-Factor Gap Map
### 1. Codebase
Partially aligned. `SOR.Ai` is one codebase module, but it currently mixes online runtime AI, message handlers, admin services, training, seeding, calibration, and neural model management.
Plan:
- Keep one module, but split registration and namespaces by role.
- Document which services are valid in each process type.
- Add tests around role registration so `game`, `ai-worker`, `admin`, and `ai-jobs` do not accidentally start each other's work.
### 2. Dependencies
Partially aligned. Dependencies are explicit in `SOR.Ai.csproj`, including `Microsoft.ML.OnnxRuntime`, `SOR.Game`, database projects, shared abstractions, and ASP.NET Core hosting types.
Plan:
- Keep ONNX as an explicit package dependency.
- Introduce abstractions for model storage, session coordination, ELO persistence, and game action invocation.
- Avoid static model access from decision code; inject a model evaluator or model registry abstraction.
- Make the dependency on in-process game handlers explicit through an `IAiGameActionInvoker`.
### 3. Config
Weakly aligned. `Ai:NeuralModelPath` is configuration-driven, but many runtime settings are hardcoded.
Plan:
- Add typed options under `Ai`.
- Validate options at startup for active roles.
- Move runtime constants into config where they affect operations.
- Fail fast when required config for the active role is missing.
Candidate config shape:
```json
{
"Ai": {
"Role": "runtime",
"Runtime": {
"PollIntervalMs": 1000,
"TurnWatchdogMs": 10000,
"MaxConcurrentTurns": 32,
"SessionLeaseSeconds": 60
},
"Neural": {
"ModelPath": "",
"InputName": "features",
"OutputName": "score",
"RequiredForTiers": []
},
"Seeding": {
"EnabledAtStartup": false
},
"Training": {
"MaxParallelGames": 4,
"OutputPath": ""
}
}
}
```
### 4. Backing Services
Partially aligned. PostgreSQL, NATS, and the ONNX model file are effectively backing services, but only database and NATS are treated that way operationally.
Plan:
- Treat the neural model as an attached resource with version, checksum, and readiness state.
- Move model artifacts to object storage, a mounted volume, or a release-provided path with explicit version metadata.
- Treat active AI session ownership as a backing service concern if more than one worker is allowed.
- Store training outputs in an attached data store rather than process-local paths for shared environments.
### 5. Build, Release, Run
Weakly aligned for AI-specific operations. Runtime startup currently performs seeding and model loading. Model artifact availability is not clearly separated from build or release.
Plan:
- Keep the application build independent from the neural model artifact.
- Promote model version and path through release configuration.
- Move account/deck seeding to a release/admin command.
- Make startup read-only except for runtime session claims and telemetry.
- Add a release checklist for model version, model checksum, required database migrations, and AI worker count.
### 6. Processes
Partially aligned. The AI worker is a long-running process role, but role boundaries are spread across `SOR.Host` and `AddAiService`.
Plan:
- Replace one broad `AddAiService` method with role-specific registration methods:
- `AddAiCore`
- `AddAiGameHandlers`
- `AddAiRuntimeWorker`
- `AddAiAdminServices`
- `AddAiTrainingJobs`
- Ensure only `ai-worker` starts `AiPlayerSessionManager`.
- Ensure `game` hosts can process add/remove/configure AI messages without starting session loops.
- Add startup validation that rejects unsafe combinations, such as multiple uncoordinated AI workers.
### 7. Port Binding
Mostly aligned through `SOR.Host`. `SOR.Ai` does not bind ports directly; it participates in host-provided HTTP, health, and NATS connectivity.
Plan:
- Keep port binding in `SOR.Host`.
- Add AI-specific health/readiness endpoints through host health checks.
- Expose AI readiness without adding an AI-specific listener.
### 8. Concurrency
Weakly aligned for horizontal scale. The AI worker uses in-memory sessions and fire-and-forget task scheduling.
Plan:
- Add bounded turn execution with `MaxConcurrentTurns`.
- Track all session and turn tasks so shutdown can wait for or cancel them.
- Replace untracked `Task.Run` calls with a supervised background task registry or channel-based worker queue.
- Add a session lease/claim store if more than one AI worker can run.
- Use NATS queue groups or durable consumer semantics when event fan-out is not desired.
- Define idempotency for `GameStarted`, `GameEnded`, and ELO recording.
### 9. Disposability
Partially aligned. Cancellation tokens are present, but in-flight work is not centrally owned.
Plan:
- Make `StopAsync` cancel polling loops, stop accepting new turns, and wait for active turn tasks up to a configured timeout.
- Check cancellation before each game action invocation.
- Persist enough session progress to recover after an AI worker restart.
- Make model reload and disposal observable and cancellation-aware.
- Move startup seeding out of normal process startup to reduce boot-time side effects.
### 10. Dev/Prod Parity
Partially aligned. Missing neural models fall back gracefully, which helps development, but production expectations are not encoded.
Plan:
- Add environment-specific validation profiles.
- Allow fallback neural behavior in dev/test, but optionally require model availability in production for configured tiers.
- Provide local examples for DB, NATS, model path, and training output paths.
- Keep self-play and calibration behavior consistent between local and production-like job runners.
### 11. Logs
Partially aligned. The module uses structured logging through `ILogger`, but runtime observability is thin.
Plan:
- Add structured logs for session start/end, lease acquisition, turn decision, action dispatch, model version, fallback mode, calibration job status, and ELO updates.
- Add metrics for active AI sessions, turn latency, decision latency, handler failures, model load status, fallback count, and self-play throughput.
- Avoid logging full game state or sensitive account data.
- Add correlation fields: `gameSessionId`, `aiAccountId`, `seatIndex`, `difficulty`, `strategy`, `modelVersion`.
### 12. Admin Processes
Weakly aligned. Seeding, calibration, training, model reload, and replay export are operational tasks but are registered with the same module as runtime services.
Plan:
- Convert seeding to explicit commands or jobs.
- Run calibration and self-play as cancellable background jobs with durable job records.
- Keep admin UI as a trigger/control plane, not the owner of long-running compute.
- Add job status, cancellation, retry, and output artifact tracking.
- Make model reload an admin operation with validation and audit logging.
## Refactor Phases
### Phase 0: Baseline and Safety Tests
Goals:
- Preserve current AI behavior before restructuring.
- Create tests around the most fragile runtime paths.
Work:
- Add tests for `AiSlotAssigner`, `AiDeckResolver`, `AiDifficultyProfiles`, `ActionCandidateGenerator`, and `ScoringFunctions`.
- Add integration-style tests for add/remove/configure AI handlers.
- Add a worker-registration test proving `AiPlayerSessionManager` only starts for the AI runtime role.
- Add tests for missing neural model fallback.
Done when:
- Existing behavior has executable coverage.
- Refactoring can proceed without relying only on manual game testing.
### Phase 1: Typed Configuration
Goals:
- Make AI runtime behavior visible and validated.
Work:
- Add `AiOptions`, `AiRuntimeOptions`, `AiNeuralOptions`, `AiTrainingOptions`, and `AiSeedingOptions`.
- Bind config through `IOptions`.
- Validate active-role requirements at startup.
- Move polling intervals, watchdog timeouts, max concurrency, neural model path, training parallelism, and seeding-at-startup behavior into options.
Done when:
- The AI role fails fast on missing required config.
- Local dev config remains simple.
- Production config can require a model for neural tiers if desired.
### Phase 2: Split Service Registration by Role
Goals:
- Make process formation explicit.
Work:
- Break `AddAiService` into focused registration methods.
- Keep handler registration available to game-enabled hosts.
- Start runtime session management only through `AddAiRuntimeWorker`.
- Register admin services separately from worker services.
- Register training/calibration jobs separately from web/runtime services.
Done when:
- `game`, `ai-worker`, `admin`, and `ai-jobs` can be reasoned about independently.
- Startup comments are backed by code-level registration boundaries.
### Phase 3: Move Seeding Out of Startup
Goals:
- Keep runtime startup disposable and side-effect-light.
Work:
- Convert AI account/deck seeding into explicit commands.
- Keep a guarded development-only startup seed option if needed.
- Make seed commands idempotent and auditable.
- Add release documentation for when seed commands must run.
Done when:
- Production runtime startup no longer mutates seed data by default.
- Seeding is a 12-Factor admin process.
### Phase 4: Supervise Runtime Sessions
Goals:
- Make AI worker concurrency bounded, observable, and disposable.
Work:
- Introduce `AiSessionCoordinator` to own session lifecycle.
- Replace untracked `Task.Run` with tracked tasks or channel-based workers.
- Add bounded turn execution via options.
- Make ELO updates idempotent and supervised.
- Add graceful shutdown behavior that cancels sessions and waits for active turns.
Done when:
- The worker can stop without abandoning unknown in-flight tasks.
- Turn concurrency can be tuned per deployment.
- Worker logs and metrics show active sessions and active turns.
### Phase 5: Add Distributed Session Ownership
Goals:
- Make AI runtime safe to scale beyond one process.
Work:
- Decide whether the supported production model is exactly one AI worker or multiple workers.
- If exactly one worker, enforce that operationally through deployment docs and readiness warnings.
- If multiple workers, add a lease/claim store for `GameSessionId` ownership.
- Use NATS queue groups or durable consumers where duplicate event delivery would be unsafe.
- Add idempotency checks for duplicate `GameStarted` and `GameEnded` events.
Done when:
- Running two AI workers cannot cause duplicate turn execution.
- Session ownership survives worker restart.
### Phase 6: Extract Turn Execution and Game Action Invocation
Goals:
- Make AI turns testable without a full hosted worker.
Work:
- Extract `AiTurnExecutor` from `AiPlayerSession`.
- Extract `IAiGameActionInvoker` for handler lookup and authenticated no-op connection creation.
- Extract `IAiDecisionEngineFactory` instead of constructing engines directly in sessions.
- Keep the actual game action messages unchanged.
Done when:
- A turn can be unit-tested with fake game state, fake decision engine, and fake action invoker.
- Runtime session code mostly coordinates polling, cancellation, and lifecycle.
### Phase 7: Model Artifact Management
Goals:
- Treat neural models as release resources, not incidental local files.
Work:
- Replace static `NeuralModelRegistry.Instance` access with injected model evaluation services.
- Add model metadata: version, checksum, loaded timestamp, input contract, output contract.
- Add readiness state for required neural models.
- Add explicit reload operation with audit logging and failure reporting.
- Decide whether models are local release files, mounted volumes, or object-store artifacts.
Done when:
- The active model version is visible in health/logs/admin.
- Missing or invalid model behavior is controlled by config.
- Neural evaluation no longer depends on global static state.
### Phase 8: Training and Calibration Jobs
Goals:
- Move compute-heavy AI work into proper one-off or worker jobs.
Work:
- Give calibration and self-play durable job records.
- Store output artifacts through an attached resource.
- Configure max parallel games, timeouts, and cancellation.
- Make admin UI trigger jobs and display status instead of owning long-running compute.
- Add replay export and training data retention policies.
Done when:
- Training/calibration can run independently from the web/admin process lifecycle.
- Jobs are resumable or explicitly retryable.
- Output artifacts are discoverable by version.
### Phase 9: Observability and Runbooks
Goals:
- Make AI operations diagnosable in production.
Work:
- Add AI-specific readiness checks.
- Add metrics for session count, turn latency, decision latency, action failure count, fallback count, model status, and job throughput.
- Add an operations runbook covering worker count, model deployment, seed jobs, calibration jobs, and failure recovery.
- Document local dev setup for AI with and without a neural model.
Done when:
- Operators can answer: which games have AI sessions, which model is loaded, whether neural fallback is active, how many turns are pending, and whether training jobs are healthy.
## Suggested Work Order
1. Add baseline tests for pure decision and handler behavior.
2. Add typed options and active-role validation.
3. Split DI registration by AI role.
4. Move seeding to explicit admin/release commands.
5. Supervise runtime tasks and add bounded concurrency.
6. Add session ownership semantics for multi-worker safety.
7. Extract turn execution and action invocation.
8. Replace static neural registry access with injected model services.
9. Move calibration/training to durable job workflows.
10. Add AI readiness checks, metrics, and runbooks.
## Completion Criteria
The refactor is complete when:
- `SOR.Ai` has explicit registration paths for game handlers, runtime worker, admin services, and jobs.
- Runtime startup is read-only except for leases, telemetry, and normal worker state.
- AI worker concurrency and shutdown are bounded and observable.
- Multiple AI workers are either prevented or coordinated safely.
- Neural model artifacts are versioned, validated, and visible through health/admin surfaces.
- Training, calibration, replay export, and seeding run as explicit admin processes.
- Config required for active roles is validated at startup.
- Tests cover decision behavior, AI lobby handlers, neural fallback, and worker registration.
## Immediate Low-Risk Next Steps
- Create `AiOptions` classes and bind them without changing behavior.
- Add role-specific extension methods that internally call the current registrations, then move services gradually.
- Add tests for `AiDifficultyProfiles` and missing neural model fallback.
- Add a runtime warning when `ENABLED_SERVICES` starts the AI worker without the required game/AI handler registrations.
- Add a short runbook documenting the current single-AI-worker assumption.
+455
View File
@@ -0,0 +1,455 @@
# SOR.Auth 12-Factor Refactor Plan
Date: 2026-06-10
Scope reviewed:
- `Server/src/SOR.Auth`
- `Server/src/SOR.Shared.Proto/Protos/auth.proto`
- Identity persistence in `Server/src/SOR.Database/Contexts/SorIdentityDbContext.cs`
- Identity entities under `Server/src/SOR.Database/Entities/Identity`
- Auth and gRPC wiring in `Server/src/SOR.Host`
Reference: https://12factor.net/
## Executive Summary
`SOR.Auth` has a solid base for a 12-Factor service. It is a service module, is enabled by host process formation, exposes a gRPC contract, uses ASP.NET Core Identity for password and lockout behavior, stores durable session records in PostgreSQL, caches active session tokens in Redis, and validates Keycloak tokens through OIDC discovery.
The main issue is structure. `AuthGrpcHandler.cs` currently contains transport handling, login/register workflows, session creation, token hashing, Redis cache behavior, account-property persistence, Keycloak account linking, OAuth feature-flag checks, and response mapping. That makes the service harder to test, harder to validate operationally, and riskier to evolve.
The plan is to keep the public gRPC contract stable while splitting `SOR.Auth` into:
- thin gRPC handlers
- application services for auth workflows
- repositories for Identity database access
- session-store abstractions for Redis plus PostgreSQL
- external identity provider services for Keycloak and future OAuth providers
- typed config and startup validation
- dependency-aware readiness checks
## Current Structure Observations
### Strong Foundations
- `SOR.Auth` is registered through `AddAuthService`.
- Auth uses ASP.NET Core Identity for account creation, password hashing, roles, token providers, and lockout.
- Session tokens are opaque random values.
- Raw session tokens are cached in Redis with TTL.
- Only SHA-256 token hashes are persisted in PostgreSQL.
- `ValidateToken` has a Redis fast path and PostgreSQL fallback.
- Logout and revoke-all-session flows are idempotent in spirit.
- Keycloak JWT validation uses OIDC discovery and cached signing keys.
- Auth gRPC contract is centralized in `auth.proto`.
### Main Problems
- `AuthGrpcHandler.cs` is the service layer, repository layer, session-store layer, provider-integration layer, and transport layer in one file.
- Identity password and lockout options are hardcoded in `ServiceRegistration.cs`.
- Keycloak options are bound but not validated.
- `KeycloakOptions.ClientId` exists but audience validation is disabled and the client ID is not actively enforced.
- Session expiration is hardcoded to 30 days.
- Redis session set entries store raw tokens in `UserSessions`, which is operationally convenient but should be reviewed as a security tradeoff.
- Account property operations are mixed into auth transport handling and likely belong behind a small account-property service.
- OAuth provider support is stubbed inside the handler.
- Feature flags are read directly from Redis in the handler.
- There is no visible `Server/tests/SOR.Auth.Tests` project.
- Auth readiness is not explicit for PostgreSQL, Redis, Keycloak discovery, and gRPC route availability.
## Target Auth Shape
Keep `SOR.Auth` as the service module, but split responsibilities:
```text
Server/src/SOR.Auth/
ServiceRegistration.cs
Configuration/
AuthOptions.cs
PasswordPolicyOptions.cs
SessionOptions.cs
KeycloakOptions.cs
OAuthProviderOptions.cs
AuthOptionsValidator.cs
Contracts/
AuthResponseMapper.cs
AuthErrorCodes.cs
Handlers/
AuthGrpcHandler.cs
Application/
AuthService.cs
SessionService.cs
AccountPropertyService.cs
KeycloakExchangeService.cs
OAuthLoginService.cs
Persistence/
IAccountRepository.cs
IAccountSessionRepository.cs
IAccountPropertyRepository.cs
EfAccountRepository.cs
EfAccountSessionRepository.cs
EfAccountPropertyRepository.cs
Sessions/
ISessionTokenGenerator.cs
ISessionTokenHasher.cs
ISessionCache.cs
RedisSessionCache.cs
SessionRecord.cs
Providers/
KeycloakTokenValidator.cs
IExternalIdentityProvider.cs
GoogleOAuthProvider.cs
SteamOAuthProvider.cs
AppleOAuthProvider.cs
MicrosoftOAuthProvider.cs
Health/
AuthHealthChecks.cs
```
`AuthGrpcHandler` should become transport mapping only:
1. Receive gRPC request.
2. Call the relevant application service.
3. Map result to gRPC response.
4. Avoid direct EF Core, Redis, token generation, and provider-specific logic.
## 12-Factor Gap Map
### I. Codebase
Status: Mostly aligned.
Current state:
- Auth lives in the shared server codebase and is enabled through `ENABLED_SERVICES=auth`.
- Auth contract lives in `SOR.Shared.Proto`.
Plan:
- Keep one codebase.
- Document Auth as an independently scalable process formation.
- Keep generated gRPC contract stable while moving implementation behind application services.
### II. Dependencies
Status: Mostly aligned, with layering gaps.
Current state:
- Auth uses ASP.NET Identity, EF Core via `SOR.Database`, Redis, gRPC, and Microsoft identity token validation packages.
- The handler directly depends on EF Core and Redis.
Plan:
- Keep package dependencies explicit and centrally versioned.
- Move direct EF Core usage behind repositories.
- Move Redis session operations behind `ISessionCache`.
- Keep provider validation libraries isolated under `Providers`.
- Avoid leaking concrete Redis or EF dependencies into handlers.
### III. Config
Status: Partially aligned.
Current state:
- Keycloak config is read from `Keycloak`.
- Connection strings are environment-overridable.
- Password policy, lockout policy, and session TTL are hardcoded.
Plan:
- Add typed options and validation for:
- `Auth:SessionTtlDays`
- `Auth:SingleSessionPerAccount`
- `Auth:TokenBytes`
- `Auth:PasswordPolicy`
- `Auth:Lockout`
- `Keycloak:Authority`
- `Keycloak:ClientId`
- OAuth provider credentials and enablement
- Use `ValidateOnStart` so bad auth config fails before serving requests.
- Keep secrets in environment variables or secret providers, never committed JSON.
### IV. Backing Services
Status: Mostly aligned.
Current state:
- PostgreSQL stores durable identity data and session hashes.
- Redis stores active raw session token lookups and feature flags.
- Keycloak is an external identity provider.
Plan:
- Treat PostgreSQL, Redis, and Keycloak discovery as attached resources.
- Add readiness checks for PostgreSQL and Redis.
- Add optional readiness for Keycloak discovery when Keycloak login is enabled.
- Keep session cache rebuildable from PostgreSQL so Redis remains disposable.
- Document Redis feature flags and their operational ownership.
### V. Build, Release, Run
Status: Mostly aligned.
Current state:
- Auth is built into the host image.
- Runtime formation is selected by `ENABLED_SERVICES`.
- Migrations exist under `SOR.Database`.
Plan:
- Keep build and runtime separated through `SOR.Host`.
- Run Identity database migrations as an explicit release/admin process.
- Do not run migrations implicitly from auth startup.
- Add release checks for password policy, session TTL, Redis connectivity, and Keycloak config.
### VI. Processes
Status: Mostly aligned.
Current state:
- Auth can run as a module in one host process or co-located with gateway.
- Auth stores correctness state in PostgreSQL and Redis, not process memory.
Plan:
- Keep auth process stateless between requests.
- Ensure all session state required for correctness is in PostgreSQL.
- Treat Redis as an acceleration layer and revocation fanout helper.
- Ensure multiple auth replicas can issue, validate, and revoke sessions consistently.
### VII. Port Binding
Status: Aligned through host.
Current state:
- `SOR.Host` maps `AuthGrpcHandler` when auth is enabled.
- Co-located auth/gateway can expose auth gRPC on a loopback HTTP/2 listener.
Plan:
- Keep port binding in host.
- Document supported formations:
- `auth` as internal gRPC service
- `gateway,auth` co-located local or small deployment mode
- Ensure Auth does not assume public internet exposure.
### VIII. Concurrency
Status: Partially aligned.
Current state:
- ASP.NET Core handles concurrent gRPC calls.
- Login revokes prior sessions, then creates a new session.
- Registration checks email/display-name uniqueness before create.
Plan:
- Add database constraints or transactional handling for display-name uniqueness if business rules require it.
- Make session revoke/create flows transactionally safe for concurrent login attempts.
- Use idempotent logout and revoke-all behavior.
- Add tests for concurrent login and registration races.
- Consider optimistic concurrency or serializable transaction boundaries for session replacement.
### IX. Disposability
Status: Mostly aligned.
Current state:
- Auth has no long-running internal loops.
- Keycloak OIDC metadata is cached and refreshed by `ConfigurationManager`.
- Redis cache misses fall back to PostgreSQL.
Plan:
- Keep startup fast.
- Validate config at startup without requiring expensive provider calls unless readiness performs them.
- Ensure all request paths honor `ServerCallContext.CancellationToken`.
- Bound external calls and Redis operations with timeouts where appropriate.
### X. Dev/Prod Parity
Status: Partially aligned.
Current state:
- Local config has Keycloak and connection-string defaults.
- Production credentials are expected from environment variables or secrets.
Plan:
- Add local auth run modes:
- local email/password auth only
- production-like auth with local or staging Keycloak
- Keep config keys identical across environments.
- Document how to seed roles, accounts, and Keycloak client config locally.
### XI. Logs
Status: Mostly aligned.
Current state:
- Auth uses structured logging.
- Successful login/register/session revoke events are logged.
- Some failure logs include email or Keycloak subject.
Plan:
- Keep logs as stdout event streams through host Serilog.
- Never log passwords, raw session tokens, OAuth tokens, or Keycloak access tokens.
- Review PII logging:
- email in registration failure logs
- Keycloak subject in migration logs
- Add consistent fields:
- `AccountId`
- `Provider`
- `ErrorCode`
- `SessionRevokedCount`
- `AuthFlow`
### XII. Admin Processes
Status: Partially aligned.
Current state:
- Auth exposes revoke-all-session RPC.
- Database migrations are external to the service module.
- Role seeding is not visible in `SOR.Auth`.
Plan:
- Keep migrations as one-off release/admin tasks.
- Add explicit admin/process commands for:
- migrate identity database
- seed roles
- revoke expired sessions cleanup
- audit or prune stale account sessions
- validate Keycloak discovery and realm roles
- Keep these out of normal auth runtime startup.
## Refactor Phases
### Phase 0: Baseline and Tests
Deliverables:
- Add `Server/tests/SOR.Auth.Tests`.
- Add tests for:
- login success
- invalid password lockout increment
- locked account
- register email taken
- register display name taken
- weak password mapping
- session create and validate
- Redis miss with PostgreSQL fallback
- logout idempotency
- revoke all sessions
- Keycloak exchange success, missing role, invalid token
- account property get/set/delete/list
Acceptance:
- Current behavior is covered before extracting services.
### Phase 1: Extract Session Services
Deliverables:
- Add `ISessionTokenGenerator`.
- Add `ISessionTokenHasher`.
- Add `ISessionCache`.
- Add `IAccountSessionRepository`.
- Move `CreateSessionAsync`, `ComputeHash`, `ValidateToken`, `Logout`, and revoke-all helper logic into `SessionService`.
Acceptance:
- Session behavior can be tested without gRPC.
- Handler no longer touches Redis directly for session operations.
### Phase 2: Extract Auth Application Service
Deliverables:
- Add `AuthService` for email/password login and registration.
- Move account lookup, password checks, lockout handling, role assignment, and last-login updates into the service.
- Add result models with stable error codes.
Acceptance:
- `AuthGrpcHandler.Login` and `AuthGrpcHandler.Register` only map requests and responses.
### Phase 3: Extract Account Property Service
Deliverables:
- Add `AccountPropertyService`.
- Add repository abstraction for account properties.
- Validate keys and values consistently.
- Decide and document size limits for property keys and values.
Acceptance:
- Account property RPCs no longer directly use EF Core.
### Phase 4: Extract Keycloak Exchange Service
Deliverables:
- Add `KeycloakExchangeService`.
- Keep token validation in `KeycloakTokenValidator`.
- Move account linking, lazy migration, role checks, display-name sync, and session issuance out of handler.
- Validate Keycloak config at startup.
Acceptance:
- Keycloak exchange can be tested by mocking token validation and repositories.
### Phase 5: OAuth Provider Boundary
Deliverables:
- Replace inline OAuth stub with `OAuthLoginService`.
- Add provider interfaces for Google, Steam, Apple, and Microsoft.
- Move feature flag access behind `IFeatureFlagReader`.
- Add provider config validation only when provider is enabled.
Acceptance:
- Disabled providers still return `FEATURE_DISABLED`.
- Enabling a provider does not require editing `AuthGrpcHandler`.
### Phase 6: Config and Health Hardening
Deliverables:
- Add typed `AuthOptions`, `SessionOptions`, `PasswordPolicyOptions`, and validators.
- Move hardcoded password, lockout, and session TTL settings into config.
- Add readiness checks for:
- Identity database
- Redis
- Keycloak discovery when enabled
- Add auth startup summary logging without secrets.
Acceptance:
- Auth fails fast on invalid config.
- `/ready` can reflect auth dependency health when host readiness is implemented.
### Phase 7: Security Review and Cleanup Jobs
Deliverables:
- Review whether raw tokens should remain in Redis user session sets.
- Consider storing token hashes in sets and keeping raw token only as the direct Redis session key.
- Add expired-session cleanup admin task.
- Add audit logging plan for force logout, lockout, and Keycloak migration.
Acceptance:
- Session storage tradeoffs are documented.
- Cleanup is explicit admin process work, not startup behavior.
## Suggested Milestone Order
1. Add auth tests around current behavior.
2. Extract session token generation, hashing, cache, and repository logic.
3. Extract email/password login and registration service.
4. Extract account property service.
5. Extract Keycloak exchange service.
6. Add OAuth provider boundary and feature-flag abstraction.
7. Add typed options and validation.
8. Add readiness checks and auth runbook.
9. Add cleanup/admin tasks for identity maintenance.
## Risk Register
| Risk | Why It Matters | Mitigation |
|---|---|---|
| Session compatibility regression | Existing clients rely on current token behavior. | Keep token format and Redis/Postgres lookup behavior stable during extraction. |
| Login race conditions | Single-session policy can behave unpredictably with concurrent logins. | Add concurrency tests and transactional session replacement. |
| Keycloak migration mistakes | Lazy email-based linking can attach external identity to the wrong account if email trust is weak. | Document trust assumptions and consider verified-email checks. |
| PII leakage in logs | Auth logs can expose email or external subject identifiers. | Audit structured logging fields and redact sensitive values. |
| Redis outage behavior | ValidateToken can fall back to PostgreSQL, but create/logout paths expect Redis. | Define degraded behavior and readiness rules. |
| OAuth implementation creep | Provider-specific flows vary significantly. | Keep provider adapters isolated behind a common interface. |
## Definition of Done
The auth refactor is complete when:
- `AuthGrpcHandler` is a thin gRPC adapter.
- Login, registration, session validation, logout, account properties, Keycloak exchange, and OAuth are separate application services.
- Redis session cache behavior is behind `ISessionCache`.
- PostgreSQL session persistence is behind repositories.
- Password, lockout, session, Keycloak, and OAuth options are typed and validated.
- Auth has focused unit tests and integration tests.
- Readiness covers Identity database, Redis, and enabled external identity providers.
- Logs are structured and avoid credentials, tokens, and unnecessary PII.
- Admin work such as migrations, role seeding, session cleanup, and provider validation runs as explicit one-off processes.
+469
View File
@@ -0,0 +1,469 @@
# SOR.Bazaar 12-Factor Refactor Plan
Date: 2026-06-10
Scope reviewed:
- `Server/src/SOR.Bazaar`
- Bazaar persistence in `Server/src/SOR.Database/Contexts/BazaarDbContext.cs`
- Bazaar entities and migrations under `Server/src/SOR.Database`
- Bazaar wiring in `Server/src/SOR.Host`
Reference: https://12factor.net/
## Executive Summary
`SOR.Bazaar` is a compact service module that registers marketplace and store message handlers when `ENABLED_SERVICES` includes `bazaar`. It handles store browsing, Origin Point balances, booster pack purchases, prebuilt deck purchases, cosmetic purchases, player listings, listing purchases, auction bids, transactions, storefronts, and price suggestions.
The service already has useful 12-Factor foundations:
- It is enabled by host process formation instead of running as a separate custom executable.
- It uses explicit database contexts for bazaar, collection, catalog, and identity data.
- High-value P2P listing purchases use a shared Postgres transaction across contexts.
- Origin Point debits use conditional SQL updates to prevent overspending.
- Message contracts are centralized in `BazaarMessages.cs`.
- The module has no local filesystem state and no direct port binding.
The main gaps are structural and operational:
- Message handlers contain transport handling, validation, business rules, data access, transaction orchestration, DTO mapping, and response mapping.
- Store purchases mutate identity, collection, and bazaar data without a single shared transaction boundary.
- Auction bid and cancellation flows should use the same atomic transaction discipline as fixed-price listing purchases.
- Pricing, page-size limits, foil odds, supported currencies, sale-history windows, and listing rules are hardcoded.
- There is no visible idempotency model for purchase commands, which matters for client retry and message redelivery.
- There is no explicit auction settlement/expiration process.
- Marketplace audit data exists through transactions and purchase records, but there is no central audit boundary for all money/card mutations.
- Readiness is host-level only; Bazaar needs dependency-aware checks for Postgres schemas and any catalog/collection/identity dependencies.
The plan is to keep `SOR.Bazaar` as the marketplace module, but split handlers into thin transport adapters backed by application services, repositories, typed options, and explicit transaction/idempotency boundaries.
## Current Structure Observations
### Strong Foundations
- `AddBazaarService` clearly registers Bazaar handlers from one place.
- `BazaarDbContext` owns store products, listings, transactions, purchase records, booster grants, and auction bids.
- `BazaarHandlerBase` centralizes Origin Point debit/credit helpers.
- `BazaarBuyListingHandler` uses a shared Npgsql transaction across `BazaarDbContext`, `CollectionDbContext`, and `SorIdentityDbContext`.
- P2P listing claim uses a conditional SQL update to avoid duplicate sale claims.
- Listing browsing clamps page size to a maximum of 100.
- Store products support active windows through `AvailableFrom` and `AvailableUntil`.
- Masked listings avoid exposing card definition data to clients.
### Main Problems
- Each handler owns too much business logic.
- `BazaarBuyBoosterPackHandler` is large and combines pack validation, slot JSON parsing, random card grants, Origin Point debiting, collection writes, purchase records, grant records, and response enrichment.
- `BazaarBuyPrebuiltDeckHandler` grants cards/decks and records purchases after debiting Origin Points, but does not use the shared transaction helper.
- `BazaarBuyCosmeticHandler` follows the same store-purchase risk pattern.
- `BazaarCancelListingHandler` can refund an auction winner and cancel a listing without a shared transaction across identity and bazaar contexts.
- `BazaarPlaceBidHandler` uses a shared transaction but loads the current winning bid without a row lock or conditional update pattern.
- `BazaarListCardHandler` checks for active listings before insert, but this should be backed by a database constraint or transactional claim to prevent duplicate active listings under concurrency.
- Auction expiration is checked when placing bids, but there is no obvious background job or admin process that closes expired auctions and settles winners.
- `BazaarBuyListingHandler` creates an unused `PurchaseRecord` object and adds the same `BazaarTransaction` twice before saving.
- Origin Point amounts are cast from decimal to int in several flows.
- Currency is hardcoded to `Gold` in marketplace flows while the balance field is `OriginPoints`, so naming and rules need to be reconciled.
- There is no visible `Server/tests/SOR.Bazaar.Tests` project.
## Target Bazaar Shape
Keep `SOR.Bazaar` as the marketplace service module, but split it into focused layers:
```text
Server/src/SOR.Bazaar/
Configuration/
BazaarOptions.cs
BazaarListingOptions.cs
BazaarStoreOptions.cs
BazaarAuctionOptions.cs
BazaarOptionsValidator.cs
Bootstrap/
BazaarRegistration.cs
BazaarHandlersRegistration.cs
BazaarJobsRegistration.cs
BazaarHealthChecks.cs
Contracts/
BazaarMessages.cs
BazaarErrors.cs
Application/
Store/
StoreQueryService.cs
BoosterPackPurchaseService.cs
PrebuiltDeckPurchaseService.cs
CosmeticPurchaseService.cs
Marketplace/
ListingQueryService.cs
ListingCommandService.cs
ListingPurchaseService.cs
AuctionBidService.cs
AuctionSettlementService.cs
PriceSuggestionService.cs
Persistence/
IBazaarRepository.cs
ICollectionInventoryRepository.cs
ICatalogLookupRepository.cs
IOriginPointLedger.cs
IBazaarUnitOfWork.cs
BazaarTransactionRunner.cs
Idempotency/
IBazaarCommandIdempotencyStore.cs
Mapping/
BazaarDtoMapper.cs
Handlers/
BazaarGetStoreHandler.cs
BazaarBuyBoosterPackHandler.cs
...
Jobs/
SettleExpiredAuctionsJob.cs
RebuildPriceSuggestionsJob.cs
```
Desired handler shape:
- Deserialize request.
- Read authenticated account ID.
- Call one application service.
- Map domain result to `ServerMessage`.
- Avoid direct EF queries in handlers.
## 12-Factor Gap Map
### 1. Codebase
Mostly aligned. `SOR.Bazaar` is one module in the server codebase, but responsibilities are concentrated in message handlers.
Plan:
- Keep one Bazaar module.
- Split business workflows into application services.
- Keep message handlers as transport adapters.
- Add Bazaar tests alongside other server tests.
### 2. Dependencies
Partially aligned. Dependencies are explicit through project references and DI, but business logic depends directly on EF contexts everywhere.
Plan:
- Keep EF Core and Postgres as explicit dependencies.
- Introduce repositories for bazaar, collection, catalog, and identity operations.
- Introduce an `IOriginPointLedger` for all balance changes.
- Introduce `IBazaarUnitOfWork` or `BazaarTransactionRunner` for cross-context transactions.
### 3. Config
Weakly aligned. Bazaar runtime rules are mostly code constants.
Plan:
- Add typed `BazaarOptions`.
- Validate options at startup.
- Move operational rules into config where appropriate.
Candidate config shape:
```json
{
"Bazaar": {
"Listings": {
"DefaultPageSize": 24,
"MaxPageSize": 100,
"MaxAuctionDurationHours": 168,
"AllowMaskedListings": true
},
"Store": {
"FoilChance": 0.05,
"AllowUsdPrices": false
},
"Pricing": {
"SuggestedPriceSaleWindowDays": 30,
"SuggestedPriceMinimumSales": 3,
"SalvageFloorMultiplier": 4
},
"Auctions": {
"SettlementBatchSize": 100,
"SettlementIntervalSeconds": 60
}
}
}
```
### 4. Backing Services
Mostly aligned. Bazaar uses Postgres schemas as attached backing services. Catalog CDN URLs are data references, not direct Bazaar network dependencies.
Plan:
- Treat `BazaarDbContext`, `CollectionDbContext`, `CatalogDbContext`, and `SorIdentityDbContext` as required attached resources.
- Add readiness checks for required schemas/tables.
- Document that multi-context transactions require the same Postgres database/connection target.
- If any future payment provider is added, isolate it as an attached external service with retries, idempotency, and reconciliation.
### 5. Build, Release, Run
Partially aligned. Bazaar runtime does not apply migrations directly, but marketplace data and store products need release discipline.
Plan:
- Keep schema migrations outside normal runtime startup.
- Treat store catalog changes as admin/release data changes.
- Add release checks for active product data, pack slot JSON validity, deck card validity, and cosmetic asset URLs.
- Add seed/import jobs for store product data instead of hand-editing production data.
### 6. Processes
Partially aligned. Bazaar is a request/response service module. Auction settlement is not clearly represented as a process.
Plan:
- Keep request handlers in the `bazaar` service role.
- Add a separate `bazaar-jobs` role for auction settlement, price cache rebuilds, and store-data validation.
- Avoid starting job loops in normal gateway/game/bazaar request workers unless explicitly enabled.
### 7. Port Binding
Aligned through `SOR.Host`. Bazaar does not bind a port directly.
Plan:
- Keep port binding in `SOR.Host`.
- Expose Bazaar readiness through host health checks.
- Do not add a Bazaar-specific HTTP listener.
### 8. Concurrency
Partially aligned. Fixed-price purchases use an atomic claim pattern, but other flows need equivalent guarantees.
Plan:
- Use one transaction runner for all high-value mutations.
- Add database constraints or conditional updates for:
- one active listing per player card
- one winning bid per auction
- listing status transitions
- idempotent purchase command execution
- Use row locks or conditional updates when replacing the winning bid.
- Make auction settlement idempotent.
- Define retry behavior for serialization/deadlock errors.
### 9. Disposability
Mostly aligned for request handlers. There are no long-running loops in `SOR.Bazaar` today.
Plan:
- Continue passing cancellation tokens to EF operations.
- Add cancellation-aware job processing if auction settlement or price rebuild jobs are introduced.
- Keep mutation workflows short and transactional.
- Avoid partial writes by ensuring store purchases and auction cancellation use shared transactions.
### 10. Dev/Prod Parity
Partially aligned. The same Postgres-backed code runs everywhere, but product data and pack JSON validity can drift.
Plan:
- Provide local seed/import data for packs, decks, cosmetics, and listings.
- Add validation commands that run in every environment.
- Keep store product rules environment-neutral unless explicitly configured.
- Use the same auction settlement path locally and in production.
### 11. Logs
Weakly aligned. Handlers do not visibly log business events.
Plan:
- Add structured logs through application services, not every handler.
- Log high-value events: purchase completed, listing created/cancelled/sold, bid placed/refunded, auction settled, insufficient funds, invalid store config.
- Add metrics for purchase latency, listing count, bid failures, settlement lag, transaction rollback count, and idempotency replay count.
- Avoid logging full account inventory or sensitive account details.
Suggested fields:
- `accountId`
- `listingId`
- `purchaseId`
- `productId`
- `playerCardId`
- `amount`
- `currency`
- `messageSeq`
- `idempotencyKey`
### 12. Admin Processes
Partially aligned. Store product and auction operations need explicit admin/job surfaces.
Plan:
- Add admin processes for importing store products, validating pack slot JSON, validating prebuilt decks, and settling expired auctions.
- Add an audit surface for Origin Point changes and item ownership changes.
- Keep admin-triggered jobs durable and retryable.
- Document operational recovery for failed purchase, failed settlement, and inconsistent listing state.
## Refactor Phases
### Phase 0: Baseline Tests and Bug Cleanup
Goals:
- Capture current behavior before structural changes.
- Fix obvious high-risk issues behind tests.
Work:
- Add tests for listing creation, fixed-price purchase, auction bid replacement, auction cancellation refund, booster purchase, prebuilt deck purchase, and cosmetic purchase.
- Add tests for insufficient funds, duplicate listing attempts, own-listing purchase prevention, and expired auctions.
- Cover `BazaarBuyListingHandler` transaction creation so duplicate transaction insertion cannot regress.
- Add tests for invalid booster slot JSON and empty card pools.
Done when:
- Bazaar mutation behavior has executable coverage.
- Refactoring can proceed without relying only on manual client testing.
### Phase 1: Typed Options and Validation
Goals:
- Move operational Bazaar rules into validated config.
Work:
- Add `BazaarOptions`, `BazaarListingOptions`, `BazaarStoreOptions`, `BazaarPricingOptions`, and `BazaarAuctionOptions`.
- Bind and validate options in Bazaar registration.
- Replace hardcoded page-size limits, foil chance, suggested-price windows, and auction duration limits with options.
- Keep defaults equivalent to current behavior.
Done when:
- Bazaar starts with validated options.
- Operators can tune marketplace rules without code changes.
### Phase 2: Application Services
Goals:
- Make handlers thin and workflows testable.
Work:
- Extract store purchase workflows:
- `BoosterPackPurchaseService`
- `PrebuiltDeckPurchaseService`
- `CosmeticPurchaseService`
- Extract marketplace workflows:
- `ListingCommandService`
- `ListingPurchaseService`
- `AuctionBidService`
- `PriceSuggestionService`
- Keep public message contracts unchanged.
Done when:
- Handlers mostly deserialize, call services, and return mapped responses.
- Business workflows can be unit/integration tested without transport boilerplate.
### Phase 3: Transaction Runner and Ledger
Goals:
- Make all money/card mutations atomic and consistent.
Work:
- Create `BazaarTransactionRunner` for shared cross-context transactions.
- Create `IOriginPointLedger` for debit, credit, balance reads, and audit metadata.
- Route all store purchases, listing purchases, bids, refunds, and cancellations through the transaction runner.
- Add explicit transaction result types for rollback-safe errors.
Done when:
- No high-value mutation writes across contexts without a single transaction boundary.
- Origin Point changes have one implementation path.
### Phase 4: Idempotency
Goals:
- Make purchase and bid commands safe under retries.
Work:
- Add an idempotency key to mutating Bazaar requests or derive one from a message envelope if available.
- Store command execution results for purchase/listing/bid commands.
- Return the original result on duplicate command replay.
- Add unique constraints where appropriate.
Done when:
- Client retry cannot double-purchase, double-grant, or double-bid.
- Message redelivery behavior is documented and tested.
### Phase 5: Marketplace Concurrency Hardening
Goals:
- Make P2P marketplace operations safe under high contention.
Work:
- Add a database-backed guarantee that one player card cannot have multiple active listings.
- Make listing status transitions conditional and auditable.
- Make winning bid replacement atomic with row locks or conditional updates.
- Add retry policy for known transient Postgres failures.
- Add settlement-safe state transitions for auctions.
Done when:
- Concurrent listing, buying, bidding, and cancellation tests pass.
- Database constraints enforce the same invariants as application code.
### Phase 6: Auction Settlement Jobs
Goals:
- Represent expired auction processing as a 12-Factor admin process.
Work:
- Add `SettleExpiredAuctionsJob`.
- Transfer card ownership, credit seller, mark listing sold/expired, and create transaction records in one transaction.
- Make settlement idempotent and batch-based.
- Register the job only in a dedicated `bazaar-jobs` role or admin process.
Done when:
- Expired auctions settle without waiting for a user action.
- Settlement can be safely retried.
### Phase 7: Store Data Validation and Import
Goals:
- Treat store product data as release/admin data.
Work:
- Add validation for booster `SlotsJson`.
- Validate that prebuilt deck cards reference published catalog cards.
- Validate cosmetic asset URLs and product availability windows.
- Add import/seed commands for packs, decks, and cosmetics.
Done when:
- Bad store data is caught before players can purchase it.
- Store content can be promoted across environments repeatably.
### Phase 8: Observability and Readiness
Goals:
- Make Bazaar operations diagnosable in production.
Work:
- Add Bazaar readiness checks for required DbContexts.
- Add metrics for purchase success/failure, bid success/failure, settlement lag, active listings, active auctions, and rollback count.
- Add structured audit logs for every Origin Point and ownership mutation.
- Add dashboards or runbook notes for marketplace health.
Done when:
- Operators can answer what purchases, listings, bids, refunds, and settlements occurred and whether any are stuck.
## Suggested Work Order
1. Add baseline tests for high-value mutation flows.
2. Fix obvious duplicate transaction/audit issues under tests.
3. Add typed Bazaar options with current defaults.
4. Extract application services behind existing handlers.
5. Introduce a transaction runner and Origin Point ledger.
6. Add idempotency for purchase/listing/bid commands.
7. Add database constraints and concurrency tests.
8. Add auction settlement as a dedicated job/admin process.
9. Add store data validation/import commands.
10. Add readiness checks, logs, metrics, and runbook documentation.
## Completion Criteria
The refactor is complete when:
- Bazaar handlers are thin transport adapters.
- Store purchases, listing purchases, bids, refunds, and cancellations use one transaction strategy.
- Mutating commands are idempotent under retry/redelivery.
- Database constraints enforce critical marketplace invariants.
- Auction expiration and settlement are handled by a dedicated, retryable process.
- Store product data is validated before release.
- Runtime config is typed and validated.
- Bazaar readiness accounts for required database schemas.
- Tests cover high-value purchase, listing, bidding, and settlement workflows.
## Immediate Low-Risk Next Steps
- Add a `BazaarOptions` class and bind it without changing behavior.
- Add tests around `BazaarBuyListingHandler` to lock down transaction/audit behavior.
- Extract `IOriginPointLedger` while preserving the current SQL update logic.
- Add a validation command for booster pack `SlotsJson`.
- Document the current assumption that all Bazaar-related DbContexts point at the same Postgres database for shared transactions.
+415
View File
@@ -0,0 +1,415 @@
# SOR.Cdn 12-Factor Refactor Plan
Date: 2026-06-10
Scope reviewed:
- `Server/src/SOR.Cdn`
- CDN registration and usage in `Server/src/SOR.Admin`
- CDN proxy endpoint in `Server/src/SOR.Host`
- CDN-related catalog and bazaar entities under `Server/src/SOR.Database`
Reference: https://12factor.net/
## Executive Summary
`SOR.Cdn` is a small infrastructure module that wraps S3-compatible object storage, currently Ceph RadosGW, behind `ICdnClient`. It is primarily used by `SOR.Admin` to upload card art, animation assets, bazaar product images, cosmetic assets, and content assets. `SOR.Host` also exposes a `/cdn/{path}` proxy that forwards browser requests to the public CDN base URL and adds permissive CORS headers.
The module already has several 12-Factor-friendly traits:
- CDN access is configured through the `Cdn` configuration section.
- Credentials are intended to come from environment variables or Kubernetes secrets.
- The S3 client is registered through DI and hidden behind `ICdnClient` for upload/delete operations.
- The module does not keep local filesystem state.
- Public URLs are derived from a configured `PublicBaseUrl`.
- Upload operations return structured results with object key, public URL, error, and ETag.
The main gaps are around config validation, operational boundaries, and consistent abstraction:
- `CdnOptions` requires `EndpointUrl`, `AccessKey`, `SecretKey`, and `BucketName`, but current appsettings comments still refer to older `UploadBaseUrl` and `ApiKey` keys.
- `AddCdnClient` binds options but does not validate required values, URL formats, bucket names, or credential presence.
- Admin pages sometimes inject raw `IAmazonS3` directly for browsing and deleting objects, bypassing `ICdnClient`.
- Upload path construction accepts caller-supplied folder and file names with little normalization policy.
- Uploads force `PublicRead` ACL and immutable caching without a clear environment policy.
- There is no central content validation policy for allowed MIME types, max sizes, folder prefixes, or asset classes.
- Deletes are hard deletes with minimal audit or reference checks.
- CDN health/readiness is not checked, even though Admin depends on it for asset management.
The plan is to keep `SOR.Cdn` as an infrastructure module, but make it a complete object-storage boundary: typed and validated config, controlled key generation, asset policy enforcement, browsing/listing APIs, reference-aware deletion, audit metadata, and dependency-aware readiness.
## Current Structure Observations
### Strong Foundations
- `SOR.Cdn` has a narrow public interface: `ICdnClient`.
- `S3CdnClient` uses `IAmazonS3`, which keeps provider-specific code localized.
- `AmazonS3Client` is registered as a singleton, matching the SDK connection-pool model.
- `ForcePathStyle = true` is explicitly set for Ceph RadosGW compatibility.
- Uploads set cache-control headers for immutable assets.
- Upload results include the S3 `ETag`.
- Admin already uses `ICdnClient` for many upload workflows.
- The database stores CDN URLs and keys in catalog, bazaar, and identity-related entities instead of storing binary asset data.
### Main Problems
- `CdnOptions` is not validated at startup.
- Config comments in `SOR.Admin` and `SOR.Host` appsettings mention `UploadBaseUrl` and `ApiKey`, which no longer match `CdnOptions`.
- `AuthenticationRegion` is hardcoded to `us-east-1`.
- Public-read ACL is hardcoded.
- Immutable cache-control is hardcoded.
- Path generation is simple string concatenation: `{folder.Trim('/')}/{fileName}`.
- File names are supplied by callers, and different admin pages choose folder/key conventions independently.
- Direct `IAmazonS3` usage in Admin pages duplicates listing, URL building, and delete behavior.
- There is no first-class list/copy/head/presign API in `ICdnClient`.
- There is no central asset-policy layer for file extensions, content types, max size, malware scanning hooks, or allowed prefixes.
- Delete operations do not check whether database records still reference the object key or URL.
- Upload success logs include public URLs but do not include stable operation metadata such as key, ETag, size, content type, caller, or asset type.
- The CDN proxy in `SOR.Host` forwards GET requests without cache headers, range support, size limits, request timeout policy, or dependency health.
## Target CDN Shape
Keep `SOR.Cdn` as a reusable infrastructure module, but make it the only object-storage boundary:
```text
Server/src/SOR.Cdn/
Configuration/
CdnOptions.cs
CdnUploadOptions.cs
CdnSecurityOptions.cs
CdnOptionsValidator.cs
Bootstrap/
CdnRegistration.cs
CdnHealthChecks.cs
Storage/
ICdnClient.cs
S3CdnClient.cs
CdnObjectInfo.cs
CdnUploadResult.cs
CdnDeleteResult.cs
CdnListResult.cs
Policy/
ICdnKeyBuilder.cs
CdnKeyBuilder.cs
ICdnAssetPolicy.cs
CdnAssetPolicy.cs
CdnContentTypePolicy.cs
References/
ICdnReferenceScanner.cs
CdnReferenceReport.cs
Audit/
ICdnAuditSink.cs
CdnAuditEvent.cs
```
Desired consumer shape:
- Admin pages upload, list, inspect, and delete objects through `ICdnClient` or higher-level content services.
- No admin component builds public URLs by hand.
- No admin component injects `IAmazonS3` directly.
- Object keys are generated by policy, not raw user filenames.
- Deletion requires a reference check or explicit force-delete path.
## 12-Factor Gap Map
### 1. Codebase
Mostly aligned. `SOR.Cdn` is a small module in the server codebase, but CDN behavior is spread into Admin pages and Host proxy code.
Plan:
- Keep one CDN module.
- Move object listing, public URL building, key normalization, and delete semantics into `SOR.Cdn`.
- Keep Host proxy registration separate but backed by shared CDN options.
### 2. Dependencies
Mostly aligned. The AWS S3 SDK dependency is explicit in `SOR.Cdn.csproj`.
Plan:
- Keep `AWSSDK.S3` isolated in `SOR.Cdn`.
- Remove direct `IAmazonS3` usage from Admin pages over time.
- Add interfaces for object listing, metadata/head checks, and safe deletion.
- Keep provider-specific SDK types out of admin application code.
### 3. Config
Partially aligned. CDN config is externalized but not validated, and current appsettings comments do not match the code.
Plan:
- Update config names to match `CdnOptions`.
- Add validation for required values and URL formats.
- Move region, path-style behavior, ACL, cache-control, max upload size, allowed prefixes, and allowed content types into typed options.
- Validate required CDN config only in processes that actually use CDN write/list features.
Candidate config shape:
```json
{
"Cdn": {
"PublicBaseUrl": "https://cdn.example.com",
"EndpointUrl": "https://s3.example.internal",
"AccessKey": "",
"SecretKey": "",
"BucketName": "sor-assets",
"AuthenticationRegion": "us-east-1",
"ForcePathStyle": true,
"DefaultAcl": "PublicRead",
"CacheControl": "public, max-age=31536000, immutable",
"MaxUploadBytes": 104857600,
"AllowedPrefixes": [ "cardart/", "models/", "cosmetics/", "bazaar/", "audio/" ]
}
}
```
### 4. Backing Services
Mostly aligned. Ceph RadosGW/S3 is an attached backing service.
Plan:
- Treat object storage as a required attached service for Admin asset workflows.
- Add readiness checks for bucket existence and credential permissions.
- Document minimum required S3 permissions: put, get/head, list, delete, and optional copy.
- Keep CDN/public serving independent from application build artifacts.
### 5. Build, Release, Run
Partially aligned. Asset binaries are already external to the app build, but asset promotion and cache policy are not formalized.
Plan:
- Treat CDN assets as release-managed content artifacts.
- Store object metadata in catalog/admin records with ETag, content type, size, uploader, and uploaded timestamp.
- Add import/export or promotion commands for content releases.
- Make cache-control and immutable URL policy explicit in release docs.
- Avoid mutable object keys unless the release process invalidates caches.
### 6. Processes
Partially aligned. CDN upload/list/delete work runs inside Admin. Host also has a CDN proxy endpoint.
Plan:
- Keep normal asset management in Admin.
- Add separate admin/job processes for bulk import, orphan scanning, reference validation, and content promotion.
- Keep CDN proxy concerns in Host or a dedicated edge service, not mixed into `SOR.Cdn` upload logic.
### 7. Port Binding
Aligned for `SOR.Cdn` itself. The module does not bind ports.
Plan:
- Keep port binding in Admin and Host.
- Move shared CDN proxy config and health checks into reusable registration helpers.
- Add timeout, response-header, and range-request policy to the Host proxy if it remains there.
### 8. Concurrency
Partially aligned. S3 operations are naturally concurrent, but key collisions and deletes need policy.
Plan:
- Generate collision-resistant object keys centrally.
- Add optional conditional put behavior where overwrites are disallowed.
- Make delete operations idempotent but audited.
- Prevent deleting keys that are still referenced unless a force flag is explicitly used.
- Add retry policy for transient S3/RadosGW failures.
### 9. Disposability
Mostly aligned. Upload and delete methods accept cancellation tokens.
Plan:
- Pass cancellation tokens from all Admin upload/list/delete calls.
- Configure SDK timeouts.
- Avoid long-running upload work tied only to Blazor circuit lifetime for large files.
- Consider direct-to-object-storage upload flows or background upload jobs if file sizes grow.
### 10. Dev/Prod Parity
Partially aligned. The same client can target Ceph/S3-compatible storage, but local config examples are stale.
Plan:
- Provide a local MinIO or Ceph-compatible dev profile.
- Keep the same bucket/prefix policy locally and in production.
- Document dev/prod differences for public URL, path-style access, ACL support, and CORS.
- Add a simple smoke test command for upload, head, list, and delete.
### 11. Logs
Partially aligned. Upload and delete failures are logged, but audit and metrics are thin.
Plan:
- Add structured logs for upload, delete, list failure, rejected content type, rejected prefix, and reference-check failures.
- Add metrics for upload count, upload bytes, upload latency, failures by operation, delete count, and proxy failures.
- Avoid logging secret values or signed URLs.
Suggested fields:
- `cdnKey`
- `bucket`
- `contentType`
- `contentLength`
- `etag`
- `assetType`
- `adminAccountId`
- `operation`
- `forceDelete`
### 12. Admin Processes
Partially aligned. Admin handles uploads, but bulk maintenance operations are not first-class.
Plan:
- Add admin/job processes for orphan scans, reference validation, asset promotion, cache audit, and bulk delete.
- Record upload/delete audit events in the catalog database or a dedicated audit sink.
- Add a dry-run mode for destructive maintenance.
- Provide a runbook for restoring accidentally deleted assets from object-store versioning/backups if available.
## Refactor Phases
### Phase 0: Config Cleanup and Baseline Tests
Goals:
- Fix documentation/config drift without behavior changes.
Work:
- Update appsettings comments to mention `Cdn__EndpointUrl`, `Cdn__AccessKey`, `Cdn__SecretKey`, and `Cdn__BucketName`.
- Add tests for public URL construction, key construction, missing config validation, and upload failure handling.
- Add a small fake `ICdnClient` for Admin tests.
Done when:
- Config documentation matches the actual `CdnOptions`.
- Existing upload behavior is covered by tests.
### Phase 1: Typed Validation
Goals:
- Fail fast when CDN config is missing or malformed.
Work:
- Add `CdnOptionsValidator`.
- Validate `PublicBaseUrl`, `EndpointUrl`, `BucketName`, and credentials when CDN write/list features are active.
- Add options for region, force path style, ACL, cache-control, and max upload size.
- Keep current defaults where practical.
Done when:
- Admin cannot start with incomplete CDN config unless CDN features are explicitly disabled.
- Secret values remain externalized and are never logged.
### Phase 2: Central Key and URL Policy
Goals:
- Stop every caller from inventing object key conventions.
Work:
- Add `ICdnKeyBuilder`.
- Normalize path separators, reject traversal, reject unsafe characters, and preserve safe extensions.
- Generate collision-resistant keys with asset type, entity ID, timestamp or content hash, and sanitized filename.
- Add a single `BuildPublicUrl` implementation.
Done when:
- Admin pages no longer concatenate CDN URLs manually.
- Upload keys are stable, safe, and predictable.
### Phase 3: Asset Upload Policy
Goals:
- Enforce upload rules centrally.
Work:
- Add `ICdnAssetPolicy`.
- Validate content type, extension, prefix, and max size by asset class.
- Add optional image/model/audio-specific validation hooks.
- Return policy errors before contacting object storage.
Done when:
- Unsafe or unsupported uploads are rejected consistently.
- New asset types require policy configuration, not scattered component edits.
### Phase 4: Complete CDN Client Surface
Goals:
- Remove raw `IAmazonS3` usage from Admin pages.
Work:
- Add list, head, metadata, and safe delete methods to `ICdnClient`.
- Add paged list responses with continuation tokens.
- Add object metadata DTOs with key, size, ETag, last modified, content type, and public URL.
- Refactor `CdnBrowser`, `CardEditor`, and `TileModelManagerPage` to use the CDN abstraction.
Done when:
- `IAmazonS3` is only used inside `SOR.Cdn`.
- Admin object browsing and deletion share one behavior path.
### Phase 5: Reference-Aware Delete and Audit
Goals:
- Prevent accidental content breakage.
Work:
- Add `ICdnReferenceScanner` that checks catalog, bazaar, identity, and content records for a key or URL.
- Add delete modes: soft/unreferenced-only, force, dry-run.
- Record upload and delete audit events.
- Surface reference reports in Admin before destructive actions.
Done when:
- Operators can see what a CDN object is used by before deletion.
- Destructive operations are auditable and reversible where object storage supports it.
### Phase 6: Readiness and Resilience
Goals:
- Make CDN dependency health visible.
Work:
- Add a health check that can verify bucket access with a cheap head/list operation.
- Configure SDK timeouts and retry policy.
- Add metrics for operation latency, errors, and bytes uploaded.
- Add Host CDN proxy timeout and error metrics.
Done when:
- Admin readiness accounts for CDN availability when asset management is enabled.
- CDN failures are visible before users report broken asset workflows.
### Phase 7: Bulk Maintenance and Release Workflows
Goals:
- Treat assets as managed content artifacts.
Work:
- Add jobs for orphan scanning, reference validation, bulk import, and content promotion.
- Add dry-run outputs for all destructive jobs.
- Document cache policy and immutable key expectations.
- Define backup/restore expectations for the bucket.
Done when:
- Content releases can validate their object-store dependencies.
- Operators can clean up unused assets safely.
## Suggested Work Order
1. Fix CDN config documentation drift.
2. Add `CdnOptionsValidator`.
3. Add key builder and public URL builder.
4. Add asset upload policy.
5. Expand `ICdnClient` with list/head/safe delete.
6. Refactor Admin pages away from direct `IAmazonS3`.
7. Add reference-aware delete and audit events.
8. Add CDN health checks, metrics, and retry/timeout policy.
9. Add bulk maintenance jobs and runbooks.
## Completion Criteria
The refactor is complete when:
- CDN config is typed, validated, and accurately documented.
- `SOR.Cdn` is the only module that uses S3 SDK types directly.
- Upload keys and public URLs are generated centrally.
- Uploads are validated by asset policy before storage writes.
- Deletes are reference-aware, auditable, and support dry-run behavior.
- Admin CDN browsing/listing uses the same abstraction as upload/delete.
- CDN readiness checks account for bucket access and credentials.
- Asset promotion, orphan cleanup, and reference validation exist as explicit admin processes.
## Immediate Low-Risk Next Steps
- Update `SOR.Admin` and `SOR.Host` appsettings comments to match current `CdnOptions`.
- Add startup validation for `PublicBaseUrl`, `EndpointUrl`, `AccessKey`, `SecretKey`, and `BucketName`.
- Add a central `BuildPublicUrl` helper to stop duplicating URL construction in Admin pages.
- Add a central key sanitizer before changing upload behavior.
- Document current CDN assumptions: Ceph RadosGW, path-style access, public-read objects, immutable cache headers, and one configured bucket.
+465
View File
@@ -0,0 +1,465 @@
# 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.
+460
View File
@@ -0,0 +1,460 @@
# SOR.Collection 12-Factor Refactor Plan
Date: 2026-06-10
Scope reviewed:
- `Server/src/SOR.Collection`
- Collection persistence in `Server/src/SOR.Database/Contexts/CollectionDbContext.cs`
- Collection entities and migrations under `Server/src/SOR.Database`
- Collection wiring in `Server/src/SOR.Host`
- Cross-module dependencies on `SOR.Catalog`, `SOR.Bazaar`, and `SOR.Auth`/Identity data
Reference: https://12factor.net/
## Executive Summary
`SOR.Collection` is a service module registered by `SOR.Host` when `ENABLED_SERVICES` includes `collection`. It owns player card inventory, player cosmetics, deck CRUD, deck validation, starter deck selection, and card salvage for Origin Points. It reads catalog card definitions, reads Bazaar starter decks and listings, and mutates Identity account balances/state for starter selection and salvage.
The service already has useful 12-Factor foundations:
- It is enabled through host process formation.
- Player inventory and deck state are durable in PostgreSQL through `CollectionDbContext`.
- Deck-card uniqueness is enforced at the database level.
- Player-cosmetic uniqueness is enforced at the database level.
- Cross-schema dependencies are explicit through registered DbContexts.
- Salvage uses a shared Postgres transaction for card deletion and Origin Point credit.
- Public message contracts are centralized in `CollectionMessages.cs`.
The main gaps are structural and operational:
- Message handlers contain transport handling, validation, business rules, EF queries, mutations, transaction handling, deck validation, DTO mapping, and response mapping.
- Deck rules are compile-time constants instead of typed, validated config.
- Starter deck selection mutates collection and identity state through multiple saves without a single shared transaction boundary.
- Salvage has a transaction boundary, but its guards are checked before the transaction and can race with marketplace listing/deck changes.
- Mutating commands do not have a visible idempotency model for client retry or message redelivery.
- Deck validation lives in `CollectionHandlerBase` and mixes rule evaluation, catalog reads, warnings, persistence, and timestamps.
- Collection ownership, deck count, starter selection, and salvage invariants are mostly application-level checks.
- There is no visible readiness check for Collection, Catalog, Bazaar, or Identity database dependencies.
- There is no visible `Server/tests/SOR.Collection.Tests` project.
The plan is to keep `SOR.Collection` as the player inventory and deck module, but split handlers into thin transport adapters backed by inventory, deck, starter-deck, salvage, validation, and repository services with typed rules, transaction safety, idempotency, observability, and dependency-aware readiness.
## Current Structure Observations
### Strong Foundations
- `AddCollectionService` registers collection handlers from one composition point.
- `CollectionDbContext` uses a dedicated `collection` schema.
- `PlayerCard` rows represent individual physical card copies.
- `DeckCard` rows aggregate card definition quantities per deck.
- `DeckCard` enforces one row per card definition per deck.
- `PlayerCosmetic` enforces one row per account/cosmetic pair.
- `DeckRules` centralizes current rule constants.
- `CollectionHandlerBase` centralizes definition loading, art URL lookup, owned-count lookup, and deck validity refresh.
- Starter deck cards are granted as non-tradeable.
- SpiritToken cards are intentionally excluded from player collections.
- Salvage checks ownership, tradeability, active marketplace listing, deck copy requirements, and catalog value before crediting Origin Points.
### Main Problems
- Handler classes are the application layer.
- `CollectionSelectStarterDeckHandler` writes player cards, deck rows, deck cards, deck validity, and `Account.StarterDeckSelectedAt` in separate operations.
- `CollectionSalvageCardHandler` checks active listings and deck usage before starting its transaction.
- Deck creation and clone enforce `MaxDecksPerPlayer` with a pre-count but no database-backed cap or transactional claim.
- Deck add/remove/set-arch-spirit operations rely on post-mutation validity refresh instead of a dedicated deck rule service.
- `CollectionAddCardHandler` has a commented-out Tier-1 ArchSpirit rejection, which makes the intended deck-building rule unclear.
- `CollectionGetCardsHandler` clamps page size to `100` directly instead of using `DeckRules` or options.
- Catalog filters are resolved by loading matching definition IDs, which can become expensive as the catalog grows.
- Starter deck data lives in Bazaar tables, so Collection has a direct read dependency on Bazaar for onboarding.
- Economy behavior for salvage is static and not externally configurable or auditable.
- There is no central inventory ledger/audit trail for grants, salvage, deck changes, or starter selection.
## Target Collection Shape
Keep `SOR.Collection` as the inventory/deck service module, but split it into focused layers:
```text
Server/src/SOR.Collection/
Configuration/
CollectionOptions.cs
DeckRulesOptions.cs
InventoryOptions.cs
SalvageOptions.cs
StarterDeckOptions.cs
CollectionOptionsValidator.cs
Bootstrap/
CollectionRegistration.cs
CollectionHandlersRegistration.cs
CollectionHealthChecks.cs
Contracts/
CollectionMessages.cs
CollectionErrors.cs
Application/
Inventory/
InventoryQueryService.cs
InventoryGrantService.cs
InventoryLedgerService.cs
Decks/
DeckCommandService.cs
DeckQueryService.cs
DeckCloneService.cs
DeckValidationService.cs
DeckRuleSet.cs
StarterDecks/
StarterDeckQueryService.cs
StarterDeckSelectionService.cs
Salvage/
SalvageService.cs
SalvageValueService.cs
Persistence/
ICollectionRepository.cs
ICatalogCardReader.cs
IStarterDeckReader.cs
IMarketplaceListingReader.cs
IOriginPointLedger.cs
ICollectionUnitOfWork.cs
CollectionTransactionRunner.cs
Idempotency/
ICollectionCommandIdempotencyStore.cs
Mapping/
CollectionDtoMapper.cs
Handlers/
CollectionGetCardsHandler.cs
CollectionCreateDeckHandler.cs
...
```
Desired handler shape:
- Deserialize request.
- Read authenticated account ID.
- Call one application service.
- Map domain result to `ServerMessage`.
- Avoid direct EF queries in handlers.
## 12-Factor Gap Map
### 1. Codebase
Mostly aligned. `SOR.Collection` is one module in the server codebase, but workflow logic is concentrated in handlers and helper base classes.
Plan:
- Keep one Collection module.
- Extract inventory, deck, starter deck, and salvage workflows into application services.
- Keep handlers as transport adapters.
- Add focused tests for application services and rule evaluation.
### 2. Dependencies
Partially aligned. Dependencies are explicit through project references and DbContext registration, but handlers depend directly on all persistence concerns.
Plan:
- Introduce repository/read-service abstractions for collection, catalog, starter decks, marketplace listings, and identity balances.
- Introduce `IOriginPointLedger` shared with Bazaar or aligned with Bazaar’s ledger model.
- Isolate cross-context transactions in a `CollectionTransactionRunner`.
- Keep catalog and bazaar dependencies read-only unless a workflow explicitly needs writes.
### 3. Config
Weakly aligned. Deck and collection rules are static constants.
Plan:
- Add typed `CollectionOptions`.
- Move deck sizes, copy limits, max decks, page sizes, starter-selection behavior, and salvage policy into options.
- Validate options at startup.
- Preserve current values as defaults.
Candidate config shape:
```json
{
"Collection": {
"DeckRules": {
"MinDeckSize": 20,
"MaxDeckSize": 120,
"MaxCopiesPerCard": 99,
"MaxDecksPerPlayer": 20,
"AllowTierOneArchSpiritInCardList": true
},
"Inventory": {
"DefaultPageSize": 50,
"MaxPageSize": 100
},
"StarterDecks": {
"SelectionEnabled": true,
"RequireSingleSelection": true
},
"Salvage": {
"Enabled": true,
"FoilMultiplier": 2,
"RequireTradeable": true,
"BlockListedCards": true
}
}
}
```
### 4. Backing Services
Partially aligned. Collection relies on Postgres schemas for collection, catalog, bazaar, and identity data.
Plan:
- Treat Collection, Catalog, Bazaar, and Identity databases as attached backing services for active collection workflows.
- Add readiness checks for each required schema by enabled feature.
- Document that cross-context transactions require those contexts to point at the same Postgres database/connection target.
- If schemas move to separate databases later, introduce an outbox/saga pattern for cross-service mutations.
### 5. Build, Release, Run
Mostly aligned. Collection has no build-time assets and does not run migrations itself.
Plan:
- Keep schema migrations outside normal runtime startup.
- Treat starter deck definitions and salvage value policy as release-managed data/config.
- Add release checks for starter decks, ArchSpirit references, SpiritToken exclusions, and deck rule compatibility.
### 6. Processes
Mostly aligned. Collection is a request/response service module with no hosted worker today.
Plan:
- Keep runtime request handlers in the `collection` role.
- Add optional `collection-jobs` role only for future backfills, deck revalidation, inventory audits, and migration repair jobs.
- Keep jobs separate from normal request workers.
### 7. Port Binding
Aligned through `SOR.Host`. Collection does not bind ports directly.
Plan:
- Keep port binding in Host/Gateway.
- Expose Collection readiness through host health checks.
- Do not add a Collection-specific listener.
### 8. Concurrency
Partially aligned. Some uniqueness constraints exist, but high-value flows rely on pre-checks.
Plan:
- Use transactional/conditional updates for starter deck selection.
- Move all starter selection writes into one transaction.
- Re-check salvage listing/deck/card ownership inside the transaction or use row locks/conditional deletes.
- Add idempotency for starter selection and salvage commands.
- Add retry handling for unique-constraint races and transient Postgres errors.
- Consider database constraints or serialized command handling for max deck count.
### 9. Disposability
Mostly aligned. Request handlers pass cancellation tokens through EF operations and there are no long-running loops.
Plan:
- Keep workflows short and cancellation-aware.
- Avoid partial writes by moving multi-context mutations into transaction runners.
- Add background jobs only with explicit cancellation and progress checkpoints.
### 10. Dev/Prod Parity
Partially aligned. Runtime code is consistent across environments, but starter deck data, catalog definitions, and deck rules can drift.
Plan:
- Provide local seed data for starter decks and test catalogs.
- Add validation commands for starter decks and deck rules.
- Run the same starter deck and salvage validation locally and in production-like environments.
### 11. Logs
Weakly aligned. There is no central structured audit/log boundary for collection mutations.
Plan:
- Add logs and metrics through application services.
- Track deck create/rename/delete/add/remove/clone, starter selection, card grants, salvage, invalid deck changes, and failed rule checks.
- Avoid logging full deck lists by default.
Suggested fields:
- `accountId`
- `deckId`
- `playerCardId`
- `cardDefinitionId`
- `starterDeckId`
- `originPointsAwarded`
- `operation`
- `errorCode`
- `idempotencyKey`
### 12. Admin Processes
Partially aligned. Collection data is maintained through runtime handlers and Admin pages elsewhere, but operational jobs are not explicit.
Plan:
- Add admin/job processes for deck revalidation, inventory audit, starter deck validation, duplicate repair, and salvage policy audit.
- Add dry-run modes for repair jobs.
- Add audit views for card grants, starter selection, salvage, and deck changes.
## Refactor Phases
### Phase 0: Baseline Tests
Goals:
- Preserve current behavior before extraction.
Work:
- Add tests for deck create/rename/delete/clone.
- Add tests for add/remove card rules, owned-copy limits, max deck size, and copy limits.
- Add tests for ArchSpirit rules and tier-chain warnings.
- Add tests for starter deck selection.
- Add tests for salvage guards and reward calculation.
- Add tests for paged/grouped inventory queries.
Done when:
- Current collection behavior is executable and can protect refactors.
### Phase 1: Typed Options
Goals:
- Move operational collection rules into validated config.
Work:
- Add `CollectionOptions`, `DeckRulesOptions`, `InventoryOptions`, `StarterDeckOptions`, and `SalvageOptions`.
- Replace direct constants and literal page limits with options.
- Keep `DeckRules` as a compatibility facade if needed.
- Validate rule consistency at startup.
Done when:
- Deck and inventory limits can be changed without code edits.
- Current behavior is preserved by defaults.
### Phase 2: Application Services and Thin Handlers
Goals:
- Make collection workflows testable without transport plumbing.
Work:
- Extract `DeckCommandService`, `DeckQueryService`, `InventoryQueryService`, `StarterDeckSelectionService`, and `SalvageService`.
- Extract `DeckValidationService` from `CollectionHandlerBase`.
- Centralize DTO mapping.
- Keep public message contracts unchanged.
Done when:
- Handlers mostly deserialize, call services, and return responses.
- Deck validation and salvage logic are independently testable.
### Phase 3: Transaction Runner and Ledger
Goals:
- Make high-value collection mutations atomic and auditable.
Work:
- Add `CollectionTransactionRunner` for collection/identity transactions.
- Add or share `IOriginPointLedger` for salvage credits.
- Route starter selection, salvage, and any future grants through explicit transaction workflows.
- Add inventory ledger events for grants and destroys.
Done when:
- Starter selection cannot partially grant cards without stamping the account, or stamp the account without granting cards.
- Salvage and Origin Point credits share one audited code path.
### Phase 4: Idempotency
Goals:
- Make retry/redelivery safe for high-value commands.
Work:
- Add idempotency support for starter selection, salvage, and deck mutations where duplicate application would be harmful.
- Store command result snapshots or durable command records.
- Return the original result on replay.
Done when:
- Client retry cannot grant starter cards twice, salvage twice, or duplicate deck mutations unexpectedly.
### Phase 5: Concurrency and Invariant Hardening
Goals:
- Protect inventory/deck invariants under concurrent requests.
Work:
- Re-check salvage eligibility inside the transaction.
- Use conditional delete or row lock for the player card being salvaged.
- Protect max deck count under concurrent create/clone.
- Decide and enforce the Tier-1 ArchSpirit card-list rule.
- Add database constraints or repair jobs for invariants that cannot be encoded directly.
Done when:
- Concurrent starter selection, salvage, deck create, and deck edit tests pass.
- Key invariants do not rely only on optimistic pre-checks.
### Phase 6: Starter Deck Data Boundary
Goals:
- Make onboarding data explicit and validated.
Work:
- Add `StarterDeckQueryService` over Bazaar starter deck data.
- Validate starter decks reference published non-token cards and a valid ArchSpirit.
- Add a release/admin validation command for starter decks.
- Document why starter decks live in Bazaar data or move starter deck read models closer to Collection if needed.
Done when:
- Bad starter deck data is caught before players can select it.
- Collection’s dependency on Bazaar starter deck tables is explicit.
### Phase 7: Inventory and Deck Audit
Goals:
- Make player inventory mutations explainable.
Work:
- Add audit records for card grants, starter selection, salvage, deck changes, and repair jobs.
- Add admin/reporting queries for a player’s inventory history.
- Add metrics for deck mutations, validation failures, starter selections, salvage attempts, and salvage credits.
Done when:
- Operators can answer why a card or deck exists, changed, or was destroyed.
### Phase 8: Readiness and Operations
Goals:
- Make Collection operationally visible.
Work:
- Add readiness checks for Collection, Catalog, Bazaar starter-deck reads, and Identity balance writes.
- Add runbooks for failed starter selection, salvage disputes, deck invalidation, and data repair.
- Add optional deck revalidation and inventory audit jobs.
Done when:
- Collection’s dependencies and failure modes are observable before players hit broken workflows.
## Suggested Work Order
1. Add baseline tests for deck rules, starter selection, and salvage.
2. Add typed options with current defaults.
3. Extract deck validation into `DeckValidationService`.
4. Extract application services behind existing handlers.
5. Add a transaction runner and Origin Point ledger path.
6. Make starter selection atomic.
7. Harden salvage concurrency and idempotency.
8. Decide and enforce ArchSpirit deck-list policy.
9. Add starter deck validation jobs.
10. Add audit logs, metrics, readiness checks, and runbooks.
## Completion Criteria
The refactor is complete when:
- Collection handlers are thin transport adapters.
- Deck, inventory, starter deck, and salvage rules are typed config.
- Deck validation is a dedicated service with tests.
- Starter selection and salvage are atomic and idempotent.
- High-value inventory changes are audited.
- Cross-schema dependencies are documented and covered by readiness checks.
- Starter deck data is validated before release.
- Concurrency tests cover starter selection, salvage, deck creation, and deck edits.
- Operators can inspect inventory mutation history and repair invalid deck/inventory states safely.
## Immediate Low-Risk Next Steps
- Add `CollectionOptions` with defaults matching `DeckRules`.
- Add tests around `CollectionSelectStarterDeckHandler` to expose partial-write risk.
- Extract `DeckValidationService` from `CollectionHandlerBase` without changing behavior.
- Add a shared transaction helper for collection/identity writes.
- Document the current assumption that Collection, Identity, Bazaar, and Catalog contexts point at the same Postgres database when shared transactions are needed.
+444
View File
@@ -0,0 +1,444 @@
# SOR.Content 12-Factor Refactor Plan
Date: 2026-06-10
Scope reviewed:
- `Server/src/SOR.Content`
- Catalog persistence in `Server/src/SOR.Database/Contexts/CatalogDbContext.cs`
- Board-template reads from `Server/src/SOR.Database/Contexts/GameDbContext.cs`
- Content wiring in `Server/src/SOR.Host`
- CDN-backed asset references stored in catalog data
Reference: https://12factor.net/
## Executive Summary
`SOR.Content` is a read-heavy service module registered by `SOR.Host` when `ENABLED_SERVICES` includes `content`. It serves card-definition sync, card sets, single card definitions, tile model bindings, tile bottom models, skybox config, highlight config, board templates, and game audio config. Most data comes from the catalog schema; board templates come from the game schema.
The service already has useful 12-Factor foundations:
- It is enabled through host process formation.
- It is stateless from the process perspective.
- It stores durable content in PostgreSQL rather than local files.
- Card sync is cursor-based through `DefinitionVersion`.
- Content assets are referenced by CDN URLs/keys rather than stored in the service.
- Handlers are small compared with mutation-heavy modules.
- The service has no hosted worker and no local filesystem state.
The main 12-Factor gaps are around operational hardening and content-release boundaries:
- Handlers directly query EF contexts and map DTOs inline or through a static mapper.
- Sync page-size limits are hardcoded.
- There is no typed `ContentOptions` for sync limits, cache TTLs, publication behavior, or payload limits.
- Content publication rules are not explicit: some endpoints filter active/enabled rows, while card sync/card lookup expose published/retired flags without a clear client-visible contract.
- There is no visible cache strategy for high-frequency read endpoints.
- CDN asset references are returned without readiness/reference validation.
- Large payload endpoints, especially card sync and board templates, lack explicit size, compression, and pagination strategy.
- Content and game board-template reads are registered together, but dependency/readiness checks do not distinguish catalog and game schema requirements.
- There is no visible test project covering sync cursor behavior or DTO compatibility.
The plan is to keep `SOR.Content` as a read-only content delivery module, but split direct handlers into query/read-model services, add typed config and readiness, define a publication/sync contract, add cache support, and create admin/release validation jobs for CDN-backed content.
## Current Structure Observations
### Strong Foundations
- `AddContentService` registers all content handlers from one place.
- `ContentSyncHandler` pages card definitions by `DefinitionVersion`.
- Sync fetches one extra row to calculate `HasMore` without a count query.
- Sync uses `AsSplitQuery` to avoid cartesian explosion across assets and animation bindings.
- Several endpoints use `AsNoTracking` for read-only queries.
- Catalog schema has indexes for published cards, sets, definition version, asset bindings, tile models, skyboxes, highlight configs, and audio configs.
- DTO contracts are centralized in `ContentMessages.cs`.
- `ContentDtoMapper` centralizes card definition DTO mapping.
- CDN cache-busting is represented through `ContentETag` on card assets.
### Main Problems
- `ContentSyncHandler` clamps page size to `500` directly.
- `SyncCardDefinitionsRequest` default page size is `200`, but limits are not configurable.
- `ContentGetCardDefinitionHandler` returns any card by ID, without an explicit published/retired visibility decision.
- `ContentSyncHandler` syncs all cards above the version watermark, without an explicit published-only or include-retired contract.
- `ContentGetHighlightConfigHandler` returns all rows and comments say this helps admin visibility, but the endpoint is registered as a client content endpoint.
- Tile model bindings do not filter by an active/published concept.
- Board templates include full `TilesJson` and `StartingZonesJson` with no payload-size or pagination policy.
- Readiness is host-level only; content needs CatalogDbContext, and board templates need GameDbContext.
- There is no local cache, Redis cache, ETag/manifest response, or content snapshot/read-model layer.
- CDN-backed URLs are returned even if the objects are missing or invalid.
- Content contracts are broad and likely coupled tightly to client expectations.
## Target Content Shape
Keep `SOR.Content` as the read-only content service module, but split it into focused areas:
```text
Server/src/SOR.Content/
Configuration/
ContentOptions.cs
ContentSyncOptions.cs
ContentCacheOptions.cs
ContentPublicationOptions.cs
ContentOptionsValidator.cs
Bootstrap/
ContentRegistration.cs
ContentHandlersRegistration.cs
ContentHealthChecks.cs
Contracts/
ContentMessages.cs
ContentErrors.cs
ContentManifest.cs
Application/
Cards/
CardContentQueryService.cs
CardSyncService.cs
CardSetQueryService.cs
CardDefinitionMapper.cs
World/
TileModelContentService.cs
SkyboxContentService.cs
HighlightContentService.cs
BoardTemplateContentService.cs
Audio/
GameAudioContentService.cs
Validation/
ContentReferenceValidator.cs
ContentPublicationValidator.cs
Persistence/
ICatalogContentReader.cs
IGameContentReader.cs
IContentVersionReader.cs
Caching/
IContentCache.cs
ContentCacheKeys.cs
ContentSnapshotBuilder.cs
Jobs/
ValidateContentReferencesJob.cs
RebuildContentSnapshotsJob.cs
```
Desired handler shape:
- Deserialize request.
- Call one query service.
- Return a stable content DTO or error.
- Avoid direct EF queries and ad hoc filtering in handlers.
## 12-Factor Gap Map
### 1. Codebase
Mostly aligned. `SOR.Content` is one module, but content query concerns are spread across handlers.
Plan:
- Keep one content module.
- Extract card, world, audio, and board-template query services.
- Keep DTO contracts stable while introducing read-model services underneath.
- Add tests for sync and DTO compatibility.
### 2. Dependencies
Mostly aligned. Dependencies are explicit through `SOR.Database` and networking abstractions.
Plan:
- Keep EF Core access isolated behind readers/query services.
- Keep Catalog and Game database dependencies explicit.
- Treat CDN as an indirect dependency through stored asset references and validation jobs.
- Avoid adding provider-specific CDN dependencies to this read service.
### 3. Config
Weakly aligned. Sync limits and publication behavior are hardcoded or implicit.
Plan:
- Add typed `ContentOptions`.
- Configure sync defaults, max page sizes, cache TTLs, publication scope, payload limits, and optional board-template limits.
- Validate options at startup.
Candidate config shape:
```json
{
"Content": {
"Sync": {
"DefaultPageSize": 200,
"MaxPageSize": 500,
"IncludeUnpublished": false,
"IncludeRetiredTombstones": true
},
"Cache": {
"Enabled": true,
"CardSetsTtlSeconds": 300,
"WorldConfigTtlSeconds": 300,
"BoardTemplatesTtlSeconds": 300
},
"Payloads": {
"MaxBoardTemplates": 200,
"MaxBoardTemplateJsonBytes": 1048576
}
}
}
```
### 4. Backing Services
Partially aligned. Content relies on PostgreSQL catalog and game schemas, and indirectly on CDN object availability.
Plan:
- Treat CatalogDbContext and GameDbContext as attached backing services.
- Add readiness checks per enabled endpoint group.
- Add release validation for CDN object references.
- Document which content endpoints can remain healthy if GameDbContext is unavailable.
### 5. Build, Release, Run
Partially aligned. Content data is external to the app build, but content release validation is not formalized.
Plan:
- Treat card definitions, world config, audio config, board templates, and CDN references as release-managed content.
- Add validation jobs before publishing content.
- Add content manifest/version reporting so clients can reason about what they have cached.
- Keep content migrations outside normal runtime startup.
### 6. Processes
Mostly aligned. Content is a stateless request/response read service.
Plan:
- Keep content serving in the `content` process role.
- Add optional `content-jobs` role for validation, snapshot generation, and cache warmup.
- Do not run content validation jobs in normal request workers unless explicitly enabled.
### 7. Port Binding
Aligned through `SOR.Host`. Content does not bind ports directly.
Plan:
- Keep port binding in Host/Gateway.
- Expose content readiness through host health checks.
- Do not add a content-specific listener.
### 8. Concurrency
Mostly aligned because Content is read-only. The main risk is consistency across admin writes and client sync reads.
Plan:
- Define publication semantics for partial admin edits.
- Use versioned publication transactions for cards/assets if clients require atomic content snapshots.
- Ensure sync cursor behavior handles updates, retirements, and unpublished drafts intentionally.
- Add tests for concurrent update/sync behavior.
### 9. Disposability
Mostly aligned. Handlers are short and pass cancellation tokens through EF operations.
Plan:
- Continue cancellation-aware reads.
- Add bounded cache/snapshot rebuild jobs if introduced.
- Avoid request-time expensive validation against CDN.
### 10. Dev/Prod Parity
Partially aligned. The same DB-backed content model runs everywhere, but dev content and CDN references can drift.
Plan:
- Provide local seed content for card sets, cards, world config, audio, and board templates.
- Provide a local CDN/reference validation profile.
- Keep sync/version behavior identical across environments.
### 11. Logs
Weakly aligned. Content handlers do not visibly emit structured operational metrics.
Plan:
- Add metrics for sync requests, rows returned, payload size, cache hit/miss, query latency, stale cache usage, and validation failures.
- Log content validation failures with stable content IDs and keys, not full payloads.
- Add correlation fields for content version and endpoint.
Suggested fields:
- `endpoint`
- `sinceVersion`
- `currentVersion`
- `pageSize`
- `rowsReturned`
- `hasMore`
- `cacheHit`
- `contentId`
- `contentType`
- `assetUrl`
### 12. Admin Processes
Partially aligned. Content is authored through Admin, but validation/publish processes are not part of `SOR.Content`.
Plan:
- Add admin/job processes for content reference validation, publication validation, snapshot rebuilds, and cache warmup.
- Add dry-run validation reports for cards, animations, tile models, skyboxes, highlights, audio, and board templates.
- Integrate validation results into Admin before publishing or enabling content.
## Refactor Phases
### Phase 0: Baseline Tests
Goals:
- Preserve current response shapes and sync behavior.
Work:
- Add tests for `content.sync` initial sync, pagination, `HasMore`, and `CurrentVersion`.
- Add tests for card DTO mapping with assets and animation bindings.
- Add tests for card set counts.
- Add tests for tile models, tile bottoms, skybox, highlight, audio, and board-template response filters.
Done when:
- Existing content contracts are covered before extraction.
### Phase 1: Typed Options
Goals:
- Make sync and content delivery behavior configurable.
Work:
- Add `ContentOptions`, `ContentSyncOptions`, `ContentCacheOptions`, and `ContentPublicationOptions`.
- Replace hardcoded page-size limits with options.
- Add startup validation.
- Keep defaults matching current behavior until publication rules are deliberately changed.
Done when:
- Content limits and cache settings are externalized.
- Invalid content config fails startup for active content roles.
### Phase 2: Query Services and Thin Handlers
Goals:
- Make handlers transport adapters.
Work:
- Extract `CardSyncService`, `CardContentQueryService`, `CardSetQueryService`, `WorldContentService`, `AudioContentService`, and `BoardTemplateContentService`.
- Move DTO mapping into injectable or testable mappers.
- Keep message contracts unchanged.
Done when:
- Handlers contain minimal request/response plumbing.
- Query behavior is independently testable.
### Phase 3: Publication Contract
Goals:
- Define exactly what clients should receive.
Work:
- Decide whether `content.sync` returns:
- published cards only
- retired tombstones
- unpublished draft cards
- admin-only records
- Decide whether `content.card` can return unpublished content.
- Decide whether highlight config should expose partially configured rows to clients.
- Encode the decision in options, services, and tests.
Done when:
- Client-visible content is not an accidental byproduct of raw table state.
- Sync/update/retire behavior is documented and tested.
### Phase 4: Cache and Manifest Strategy
Goals:
- Reduce repeated database load and give clients stable cache cues.
Work:
- Add in-memory or Redis-backed caching for low-churn endpoints.
- Add a content manifest with current card version, asset/config versions, and optional hashes.
- Add cache invalidation hooks or TTLs.
- Consider precomputed snapshots for full card sync if payload size grows.
Done when:
- High-frequency content endpoints have predictable DB load.
- Clients can identify when their cached content is current.
### Phase 5: Content Validation Jobs
Goals:
- Catch broken content before clients download it.
Work:
- Add validation for card JSON fields, ability payloads, animation bindings, CDN URLs, tile model bindings, skyboxes, highlights, audio config, and board-template JSON.
- Add dry-run reports.
- Add a release/admin command for validation.
Done when:
- Bad content can be detected before publish/enable.
- Admin can see validation failures with actionable IDs.
### Phase 6: CDN Reference Policy
Goals:
- Make asset references reliable without coupling runtime reads to CDN checks.
Work:
- Add `ContentReferenceValidator` that checks stored CDN URLs/keys through CDN tooling or HTTP HEAD/job process.
- Store validation status or reports where Admin can inspect them.
- Decide whether invalid references block publication.
- Keep runtime content reads fast and avoid request-time CDN validation.
Done when:
- Missing assets are caught by validation jobs, not by players.
### Phase 7: Payload and Version Hardening
Goals:
- Keep content sync scalable as catalog size grows.
Work:
- Measure sync payload sizes.
- Add response-size metrics.
- Consider splitting cards, assets, animations, and world config into separate manifests.
- Add board-template pagination or versioning if needed.
- Add compatibility versioning for DTO contracts.
Done when:
- Content payload growth has limits, metrics, and a migration path.
### Phase 8: Readiness and Operations
Goals:
- Make content delivery diagnosable in production.
Work:
- Add readiness checks for CatalogDbContext and GameDbContext.
- Add metrics for query latency, cache hit rate, sync pages, payload sizes, validation status, and manifest version.
- Add runbooks for stale content, broken assets, failed validation, and sync incompatibility.
Done when:
- Operators can answer what content version is live and whether clients can sync it safely.
## Suggested Work Order
1. Add baseline tests for sync and DTO mapping.
2. Add typed `ContentOptions` with current defaults.
3. Extract query services behind existing handlers.
4. Define and test publication visibility rules.
5. Add cache/manifest support for stable content responses.
6. Add content validation jobs and dry-run reports.
7. Add CDN reference validation jobs.
8. Add payload metrics, readiness checks, and runbooks.
## Completion Criteria
The refactor is complete when:
- Content handlers are thin transport adapters.
- Sync limits, publication rules, cache TTLs, and payload limits are typed config.
- Client-visible publication behavior is explicit and tested.
- Content queries can be served from read-model services or cache.
- CDN references and JSON payloads are validated before publish.
- Readiness checks distinguish Catalog and Game dependencies.
- Metrics show sync latency, payload size, cache behavior, and validation health.
- Admin/release workflows can validate content before it becomes client-visible.
## Immediate Low-Risk Next Steps
- Add `ContentOptions` with current sync defaults.
- Add tests for `ContentSyncHandler` cursor pagination.
- Extract `CardSyncService` without changing behavior.
- Document current publication behavior for `content.sync`, `content.card`, and highlight config.
- Add a validation report for missing CDN URLs/keys across catalog content.
+438
View File
@@ -0,0 +1,438 @@
# SOR.Database 12-Factor Refactor Plan
Date: 2026-06-10
Scope reviewed:
- `Server/src/SOR.Database`
- DbContexts for Identity, Catalog, Collection, Bazaar, Chat, Game, and Support
- EF migrations under `Server/src/SOR.Database/Migrations`
- Database registration in server modules, `SOR.Host`, and `SOR.Admin`
- Admin migration startup behavior in `Server/src/SOR.Admin/Program.cs`
Reference: https://12factor.net/
## Executive Summary
`SOR.Database` is the shared persistence module for the server. It contains entity models, EF Core DbContexts, schema-specific migrations, design-time factories, and service registration helpers for seven logical schemas: `identity`, `catalog`, `collection`, `bazaar`, `chat`, `game`, and `support`.
The module already has strong foundations:
- Each domain schema has its own DbContext and migration folder.
- Runtime services register only the DbContexts they need.
- Connection strings are externalized through `ConnectionStrings:{ContextName}` with fallback to `ConnectionStrings:Default`.
- Design-time factories exist for all DbContexts.
- PostgreSQL schemas are explicit through `HasDefaultSchema`.
- Several important uniqueness and query indexes are already modeled.
- Cross-schema IDs are intentionally represented as bare GUIDs where EF foreign keys would couple schemas too tightly.
The main 12-Factor gaps are operational:
- `SOR.Admin` currently applies every schema migration during normal web startup.
- Database connection options are not typed or validated beyond missing connection-string checks.
- Design-time factories fall back to a hardcoded local Postgres connection string.
- EF registration does not define retry policy, command timeout, migrations assembly conventions, pool sizing, or service-specific read/write intent.
- Cross-schema transaction assumptions are implicit. Some application flows rely on all schemas being in the same physical Postgres database.
- Schema ownership is documented in comments but not enforced through code boundaries or deployment process.
- There are no reusable health/readiness checks per DbContext.
- Shared economic logic such as `CardSalvageValues` lives in the database project even though it is domain policy rather than persistence.
The plan is to keep `SOR.Database` as the central persistence package, but harden it around 12-Factor operation: externalized validated config, explicit migration/admin processes, schema ownership, readiness checks, transaction policy, query/index governance, and clean separation between persistence models and domain policy.
## Current Structure Observations
### Strong Foundations
- `ServiceRegistration.cs` has one registration method per DbContext.
- Context-specific connection strings allow production to split schemas later.
- Local development can use one default connection string for all schemas.
- Migrations are grouped by schema folder.
- `SorIdentityDbContext` uses ASP.NET Core Identity but renames tables into the `identity` schema.
- `CatalogDbContext` includes content/versioning indexes such as `DefinitionVersion`.
- `CollectionDbContext` enforces unique deck-card rows and player cosmetic ownership.
- `BazaarDbContext` includes indexes for listings, transactions, purchase records, and bids.
- `ChatDbContext` enforces unique channel membership and block pairs.
- `GameDbContext` enforces unique action-log sequence numbers per session.
- `SupportDbContext` is small and isolated.
### Main Problems
- Runtime database registration is minimal and does not apply provider options consistently.
- There is no `DatabaseOptions` or `DbContextOptions` validation layer.
- Connection strings can silently fall back to `Default`, which is convenient locally but risky when a production schema was expected to be isolated.
- Admin startup runs migrations for all contexts, which couples web boot to schema changes.
- There is no dedicated migration runner/admin process.
- There is no shared health check registration for required schemas.
- Cross-schema references are bare GUIDs, but there are no validation jobs to find orphaned IDs.
- Some domain policy is located in the database project, such as salvage value calculation.
- JSONB payloads are common, but schema/version validation for those payloads lives outside this module or is not centralized.
- Several application-level invariants are noted in comments instead of enforced by database constraints or validation jobs.
## Target Database Shape
Keep `SOR.Database` as the persistence module, but organize operational concerns explicitly:
```text
Server/src/SOR.Database/
Configuration/
DatabaseOptions.cs
DbContextConnectionOptions.cs
DatabaseOptionsValidator.cs
Bootstrap/
DatabaseRegistration.cs
DatabaseHealthChecks.cs
DatabaseProviderOptions.cs
Contexts/
Identity/
Catalog/
Collection/
Bazaar/
Chat/
Game/
Support/
Entities/
...
Migrations/
Identity/
Catalog/
Collection/
Bazaar/
Chat/
Game/
Support/
Operations/
MigrationRunner.cs
SchemaValidationJob.cs
OrphanReferenceValidationJob.cs
IndexAuditJob.cs
Testing/
DbContextModelTests.cs
MigrationSmokeTests.cs
```
Desired process roles:
- Runtime services: register only required DbContexts and never apply migrations.
- `db-migrate`: one-off release/admin process that applies selected migrations.
- `db-validate`: one-off/admin job that checks schema state, cross-schema references, and data invariants.
- Admin web: reads/writes data, but does not own migration execution during normal startup.
## 12-Factor Gap Map
### 1. Codebase
Mostly aligned. Database models and migrations are in one package, but domain policy and persistence concerns are mixed in a few places.
Plan:
- Keep one database package for EF models and migrations.
- Move non-persistence domain policy, such as card salvage economics, toward the owning domain module or a shared domain-policy package.
- Keep schema-specific migrations grouped and named consistently.
### 2. Dependencies
Mostly aligned. EF Core, Npgsql, and Identity EF dependencies are explicit.
Plan:
- Keep provider dependencies isolated in `SOR.Database`.
- Expose registration helpers and health checks, not raw provider setup spread across services.
- Standardize provider options in one place: retry policy, command timeout, migrations assembly, and query-splitting defaults where appropriate.
### 3. Config
Partially aligned. Connection strings are externalized, but behavior is not typed or validated.
Plan:
- Add typed database options.
- Validate required contexts for active services.
- Make fallback-to-default policy configurable and safe by environment.
- Add provider options for timeout, retry count, pool size, and migration behavior.
Candidate config shape:
```json
{
"Database": {
"AllowDefaultConnectionFallback": true,
"CommandTimeoutSeconds": 30,
"EnableRetryOnFailure": true,
"MaxRetryCount": 3,
"MaxRetryDelaySeconds": 5,
"RequireContextSpecificConnectionStrings": false,
"HealthCheckTimeoutSeconds": 3
},
"ConnectionStrings": {
"Default": "",
"Identity": "",
"Catalog": "",
"Collection": "",
"Bazaar": "",
"Chat": "",
"Game": "",
"Support": ""
}
}
```
### 4. Backing Services
Partially aligned. PostgreSQL is the backing service, but the code supports both one physical database and split context databases without making all consequences explicit.
Plan:
- Document which workflows require same-physical-database transactions.
- Add startup validation or warnings when contexts are split but application flows assume shared transactions.
- Add readiness checks per context.
- Add schema-version checks to readiness for stricter environments.
### 5. Build, Release, Run
Weakly aligned today because Admin applies migrations during normal startup.
Plan:
- Move migrations to a dedicated `db-migrate` process.
- Make migration execution explicit in deployment/release pipelines.
- Runtime services should fail readiness if schema is incompatible, not mutate schema during boot.
- Add migration smoke tests and rollback notes for destructive migrations.
### 6. Processes
Partially aligned. DbContexts are registered per service, but migration/admin processes are not separated from Admin runtime.
Plan:
- Add one-off migration runner.
- Add one-off validation jobs for orphan references, data invariants, and index checks.
- Keep normal runtime processes web/worker-only.
### 7. Port Binding
Aligned. `SOR.Database` binds no ports directly.
Plan:
- Keep all HTTP/gRPC/WebSocket binding in Host/Admin.
- Surface database health through consuming processes.
### 8. Concurrency
Partially aligned. Some uniqueness constraints are present, but several important invariants remain application-level.
Plan:
- Audit application-level invariants and decide which should become database constraints, partial indexes, exclusion constraints, or validation jobs.
- Add explicit transaction helpers for same-database multi-context workflows.
- Define policy for split-database workflows: no shared transaction, outbox/saga required.
- Add tests for known concurrency-sensitive invariants.
### 9. Disposability
Partially aligned. DbContexts are scoped through DI, but migration-on-startup reduces disposability.
Plan:
- Remove runtime startup migrations.
- Ensure short command timeouts and cancellation support are consistently applied.
- Keep DbContext lifetimes scoped.
- Add retry policy only for safe transient failures.
### 10. Dev/Prod Parity
Partially aligned. Default connection fallback helps local dev, but can hide production misconfiguration.
Plan:
- Keep simple local setup with one database and many schemas.
- Require explicit connection strings in production.
- Document local migration commands per context.
- Add containerized local Postgres setup and seed/validation commands if not already present.
### 11. Logs
Partially aligned through EF/host logging, but database operations lack consistent operational signals.
Plan:
- Add structured logs for migration start/end/failure, schema validation, health checks, and cross-schema validation jobs.
- Keep SQL command logging disabled or limited in production unless debugging.
- Add metrics for migration duration, failed health checks, connection failures, slow queries, and pool exhaustion if available.
### 12. Admin Processes
Weakly aligned. Migration and validation are admin processes but are currently tied to Admin startup or absent.
Plan:
- Add `db-migrate`, `db-validate`, `db-seed`, and `db-audit` commands/jobs.
- Make destructive operations dry-run capable.
- Add schema and data validation reports for Admin/release workflows.
## Refactor Phases
### Phase 0: Baseline Inventory
Goals:
- Make the current database shape explicit before changing behavior.
Work:
- Document every DbContext, schema, owning service, and consumer service.
- Document cross-schema bare GUID references.
- Document workflows that rely on multiple schemas in one physical database.
- Add model tests that verify schema names, key indexes, and uniqueness constraints.
Done when:
- Database ownership and cross-schema assumptions are visible in docs/tests.
### Phase 1: Typed Database Options
Goals:
- Make provider and fallback behavior explicit.
Work:
- Add `DatabaseOptions`.
- Add connection-string resolution that can enforce context-specific strings in production.
- Add provider configuration for command timeout and transient retry.
- Keep current default fallback behavior for local development.
Done when:
- Runtime services can validate database config before accepting traffic.
- Production can opt out of silent `Default` fallback.
### Phase 2: Shared Registration and Health Checks
Goals:
- Standardize DbContext registration and readiness.
Work:
- Centralize Npgsql provider options.
- Add `AddDatabaseHealthChecks` helpers per context.
- Add optional schema-version compatibility checks.
- Expose health check tags by service/schema.
Done when:
- Host/Admin can report readiness for exactly the schemas each process requires.
### Phase 3: Migration Process Separation
Goals:
- Align build/release/run with 12-Factor.
Work:
- Create a one-off migration runner or documented `dotnet ef database update` release process.
- Remove or gate Admin startup migrations behind a development-only option.
- Add migration ordering/runbook documentation for all schemas.
- Add migration smoke tests in CI.
Done when:
- Normal web/worker startup does not apply schema migrations in production.
- Releases include an explicit migration step.
### Phase 4: Schema Ownership and Boundaries
Goals:
- Reduce accidental cross-domain coupling.
Work:
- Create a schema ownership matrix.
- Mark which modules may write each schema.
- Identify read-only cross-schema dependencies.
- Move domain-policy helpers out of `SOR.Database` where appropriate.
Done when:
- Each schema has a clear owner and allowed consumers.
- Shared database project is not a dumping ground for domain behavior.
### Phase 5: Cross-Schema Transaction Policy
Goals:
- Make multi-context writes safe and explicit.
Work:
- Add a transaction helper for same-connection/same-database multi-context operations.
- Add runtime validation that participating contexts resolve to compatible connection targets.
- Document flows that need outbox/saga if schemas are split across databases.
- Add tests for transaction rollback across contexts.
Done when:
- Bazaar/Collection/Auth-style cross-context mutations have a standard transaction path.
- Splitting schemas across physical databases cannot silently break atomic workflows.
### Phase 6: Constraint and Index Audit
Goals:
- Move critical invariants into the database where practical.
Work:
- Audit unique constraints, partial indexes, and query indexes across all contexts.
- Add missing constraints for application-level invariants where possible.
- Use validation jobs where constraints are impractical.
- Add index usage/slow-query review docs.
Done when:
- High-risk invariants are either database-enforced or validated by an explicit job.
### Phase 7: JSONB and Versioned Payload Governance
Goals:
- Make JSONB payloads maintainable over time.
Work:
- Inventory all JSONB columns and opaque JSON string columns.
- Add payload version fields where needed.
- Add validation helpers/tests for game state, board templates, abilities, lobbies, notifications, and bazaar pack slots.
- Add migration/backfill strategy for JSON payload changes.
Done when:
- JSON payload evolution has tests and migration rules.
### Phase 8: Data Validation and Repair Jobs
Goals:
- Detect cross-schema drift and operational data corruption.
Work:
- Add orphan-reference validation jobs for bare GUID references.
- Add data invariant checks per schema.
- Add dry-run repair jobs for safe cases.
- Report validation status in Admin or release logs.
Done when:
- Operators can detect and triage orphaned IDs, invalid JSON, broken content references, and invalid domain states.
### Phase 9: Observability and Runbooks
Goals:
- Make database operations diagnosable.
Work:
- Add logs/metrics for health checks, migrations, validation jobs, connection failures, slow queries, and command timeouts.
- Add runbooks for migration failure, rollback, lock contention, pool exhaustion, and data repair.
- Document backup/restore expectations per schema.
Done when:
- Database failures have actionable operational guidance.
## Suggested Work Order
1. Create a schema ownership and dependency matrix.
2. Add baseline model tests for schemas, indexes, and uniqueness constraints.
3. Add typed `DatabaseOptions` and shared Npgsql provider setup.
4. Add DbContext-specific health checks.
5. Move production migrations out of Admin startup.
6. Add a migration runner/release process.
7. Standardize multi-context transaction helpers.
8. Audit constraints, indexes, and JSONB payloads.
9. Add validation/repair jobs for cross-schema references.
10. Add database runbooks and operational metrics.
## Completion Criteria
The refactor is complete when:
- Database config is typed and validated.
- Runtime services register only required DbContexts with standard provider options.
- Production migrations run through explicit release/admin processes, not normal web startup.
- DbContext health checks are available and used by consuming processes.
- Cross-schema transaction assumptions are documented, validated, and backed by shared helpers.
- Schema ownership is documented and enforced by conventions/tests.
- Critical invariants are enforced by constraints or validation jobs.
- JSONB payloads have version/validation strategy.
- Operators have runbooks for migrations, backups, restores, locks, slow queries, and data repair.
## Immediate Low-Risk Next Steps
- Add `DatabaseOptions` with current defaults and no behavior change.
- Add a schema ownership matrix to the repo docs.
- Add model tests for key uniqueness/index expectations.
- Add database health check helpers for each DbContext.
- Gate `SOR.Admin` startup migrations behind a development-only option or plan a dedicated migration runner.
+505
View File
@@ -0,0 +1,505 @@
# SOR Game 12-Factor Refactor Plan
Date: 2026-06-08
Scope reviewed:
- `Server/src/SOR.Game`
- Runtime wiring in `Server/src/SOR.Host`
- Shared infrastructure in `Server/src/SOR.Database`, `SOR.Shared`, networking abstractions, Dockerfile, and server architecture docs
Reference: https://12factor.net/
## Executive Summary
`SOR.Game` already has a useful service-module boundary and dependency injection entry point, and the host already supports process-level service selection through `ENABLED_SERVICES`. Those are strong foundations for a 12-Factor-compatible backend.
The main issues are inside the game module shape and runtime behavior:
- `GameEngine.cs`, `AbilitySystem.cs`, `GameMessages.cs`, and `GameHandlerBase.cs` carry too many responsibilities.
- Several handlers contain orchestration, persistence, serialization, and push logic that should live behind services.
- Some runtime state is process-local (`VoteSessionService`, `RuleSuggestionService`, `GameActivityRegistry`) or exposed through static singleton references.
- Startup cleanup is embedded in app boot instead of being available as an explicit one-off operational process.
- Config is mostly environment-ready, but defaults and service-specific options are not consistently typed or validated.
- Health checks are liveness-only and do not yet reflect Redis, NATS, or database readiness.
- There is no visible test project under `Server/tests`, even though the architecture doc expects service tests.
The plan below breaks the work into phases that improve structure first, then operational conformance.
## Current Structure Observations
### Strong Foundations
- One repository contains the server codebase and service modules.
- `Directory.Packages.props` centralizes NuGet versions.
- `Directory.Build.props` sets deterministic builds, nullable references, warnings as errors, and common target framework.
- `SOR.Host` is the single deployable runtime and uses `ENABLED_SERVICES` to select modules.
- `SOR.Game` registers itself through `AddGameService`.
- Redis, NATS, EF Core, and client push are represented as injected infrastructure.
- `Dockerfile.host` uses a build stage and runtime stage, exposes port `8080`, and runs as a non-root user.
- Game spectators are already backed by Redis, which supports horizontal scale better than in-process memory.
### Main Structural Problems
- `GameEngine.cs` is a large static rules engine mixing serialization, initialization, draw/play/move/attack/sacrifice/end-turn flow, DTO projection, deck validation, ELO calculation, and helper parsing.
- `AbilitySystem.cs` is extremely large and likely combines parsing, validation, target resolution, execution, triggers, animations, pending prompts, and state mutation.
- `GameHandlerBase.cs` contains static helpers for pushing state, finalizing games, spectator handling, activity broadcasting, and ranking updates.
- Handler classes often directly use EF Core, JSON serialization, push delivery, and game state mutation instead of delegating to focused application services.
- `GameMessages.cs` is a large message contract file; DTOs and request/response contracts are not grouped by workflow.
- Static singleton references (`GameActivityRegistry.Instance`, `SpectatorRegistryService.Instance`) make the code harder to test and reduce process-model clarity.
- `VoteSessionService`, `RuleSuggestionService`, and `GameActivityRegistry` are process-local. That means behavior can diverge across pods if game traffic is handled by more than one `game` process.
- `GameStartupCleanupService` performs operational repair during process startup. The behavior is useful, but 12-Factor admin-process guidance points toward a one-off task that can be run independently from normal web/process boot.
## Target Architecture
Keep `SOR.Game` as the service module, but make its internal shape closer to this:
```text
Server/src/SOR.Game/
ServiceRegistration.cs
Configuration/
GameOptions.cs
GameTimerOptions.cs
GameCleanupOptions.cs
Contracts/
Commands/
Responses/
Pushes/
Dtos/
Application/
Lobbies/
Sessions/
Turns/
Actions/
Spectating/
Activity/
Ranking/
Domain/
State/
Rules/
Abilities/
Combat/
Board/
Randomness/
Persistence/
IGameSessionRepository.cs
ICustomLobbyRepository.cs
IGamePresetRepository.cs
EfGameSessionRepository.cs
EfCustomLobbyRepository.cs
EfGamePresetRepository.cs
RuntimeState/
IVoteSessionStore.cs
RedisVoteSessionStore.cs
IRuleSuggestionStore.cs
RedisRuleSuggestionStore.cs
IGameActivitySubscriptionStore.cs
RedisGameActivitySubscriptionStore.cs
Operations/
GameStartupCleanupJob.cs
GameSessionRepairJob.cs
Handlers/
GameReadyHandler.cs
...
```
The goal is not to add layers for their own sake. The goal is to make handlers thin, make game rules testable without the host, and move horizontally shared runtime state into attached services.
## 12-Factor Gap Map
### I. Codebase
Status: Mostly aligned.
Current state:
- One repo contains server projects.
- Deploy behavior is selected by config (`ENABLED_SERVICES`), not by code forks.
Plan:
- Keep one repo and one `SOR.Host` deployable for now.
- Document each deploy type as a process formation: `gateway`, `game`, `ai`, `auth`, `content`, `all` for local development.
- Add a clear ownership map for `SOR.Game` subdomains after the refactor.
### II. Dependencies
Status: Mostly aligned.
Current state:
- NuGet versions are centrally declared.
- Docker restore is explicit.
Plan:
- Keep central package management.
- Add a dependency audit task for game: identify direct dependencies from `SOR.Game` to concrete infrastructure and move them behind interfaces where they are not pure domain concerns.
- Avoid adding new cross-module references from `SOR.Game`; prefer `SOR.Networking.Abstractions`, `SOR.Shared`, and explicit service contracts.
### III. Config
Status: Partially aligned.
Current state:
- Connection strings and service URLs can be overridden via environment variables.
- `appsettings.json` contains local defaults and placeholder secrets.
- Game-specific constants are scattered in services and handlers.
Plan:
- Add typed options for game configuration:
- `Game:Timers`
- `Game:Cleanup`
- `Game:RulesDefaults`
- `Game:RuntimeState`
- `Game:Activity`
- Validate options at startup with `ValidateOnStart`.
- Move hardcoded operational values into config where appropriate:
- startup cleanup stale threshold
- spectator TTL
- inactivity thresholds
- turn timer settings
- activity subscription TTL
- Keep secrets and production values out of committed JSON; use environment variables or secret providers.
### IV. Backing Services
Status: Partially aligned.
Current state:
- PostgreSQL, Redis, NATS, CDN, and Keycloak are treated as configurable resources.
- Some game runtime state is still in memory.
Plan:
- Replace process-local runtime state with Redis-backed stores where behavior must survive pod changes:
- preset votes
- rule suggestions
- game activity subscribers
- Keep only truly per-process concerns in memory.
- Define Redis keys in `SOR.Shared.Redis.RedisKeys`.
- Define NATS subjects in `SOR.Shared.Nats.NatsSubjects`.
- Add readiness checks for required attached resources per enabled service.
### V. Build, Release, Run
Status: Mostly aligned, with release gaps.
Current state:
- Docker build and runtime stages are separate.
- Runtime config is injected at run time.
- Database migrations are present, but operational application of migrations is not clearly separated from runtime.
Plan:
- Preserve Docker build/release separation.
- Define a release checklist:
- restore/build/test
- publish container
- run migrations as a one-off process
- start runtime process formation
- Avoid doing schema migration or repair work as implicit web process startup behavior.
### VI. Processes
Status: Needs work.
Current state:
- Game process can run independently via `ENABLED_SERVICES=game`.
- Some mutable state is process-local or static.
Plan:
- Make game handlers and domain logic stateless between requests.
- Move shared ephemeral state into Redis.
- Remove static service lookups by converting static helper flows into injected services.
- Keep game state persistence in PostgreSQL, with Redis only for fast ephemeral coordination and push fanout.
### VII. Port Binding
Status: Mostly aligned.
Current state:
- Host binds via ASP.NET Core/Kestrel.
- Docker exposes `8080`.
- Auth gRPC loopback binding is configured when co-located.
Plan:
- Keep HTTP/WebSocket port binding in `SOR.Host`.
- Ensure process-specific deploys have clear ports and health endpoints.
- Avoid hidden runtime dependencies on external web servers.
### VIII. Concurrency
Status: Partially aligned.
Current state:
- Service selection supports multiple process types.
- NATS and Redis are available for cross-process coordination.
- In-process vote/suggestion/activity state makes multi-pod game scaling risky.
Plan:
- Define process types explicitly:
- `web/gateway`
- `game-worker`
- `ai-worker`
- `matchmaking-worker`
- `admin`
- `maintenance`
- Add a concurrency model for game sessions:
- one command per session at a time
- optimistic concurrency or distributed lock for session state mutation
- idempotent command handling where clients may retry
- Move timers and inactivity monitors to a model that can run safely with multiple game workers.
### IX. Disposability
Status: Partially aligned.
Current state:
- Hosted services use ASP.NET Core lifetime hooks.
- Startup cleanup handles some previous-process failure modes.
- Graceful shutdown behavior for game timers and in-flight game commands is not clearly isolated.
Plan:
- Ensure hosted services honor cancellation tokens consistently.
- Make session mutation operations transactionally safe so termination between state save and finalize can be repaired.
- Move cleanup/repair into idempotent jobs callable as admin processes.
- Keep startup fast; avoid large database scans during normal app boot.
### X. Dev/Prod Parity
Status: Partially aligned.
Current state:
- Local defaults exist for Redis, NATS, PostgreSQL, Keycloak, CDN, and WebSocket settings.
- `ENABLED_SERVICES=all` is convenient for development but differs from scaled production process formation.
Plan:
- Add a local compose/dev profile that runs Redis, NATS, PostgreSQL, and host process formations similarly to production.
- Document local development modes:
- single-process `all`
- production-like split process formation
- Keep config names identical across dev/staging/prod; only values should differ.
### XI. Logs
Status: Partially aligned.
Current state:
- Serilog writes to console, which is correct for event streams.
- `GameEngine.Attack` still writes directly with `Console.WriteLine`.
- Ability logging uses a static logger initializer.
Plan:
- Replace direct console writes with injected or passed logging abstractions.
- Remove static logger initialization from domain code over time.
- Keep all logs structured.
- Audit noisy `Debug` logs, especially ability/game action logs, so production can tune volume through config.
### XII. Admin Processes
Status: Needs work.
Current state:
- `SOR.Tools` exists and can be the home for one-off tasks.
- `GameStartupCleanupService` does repair work during process startup.
- EF migrations exist but the production execution path is not fully documented here.
Plan:
- Move game cleanup/repair operations into explicit one-off tasks under `SOR.Tools` or a dedicated `SOR.Operations` project.
- Add commands:
- `game cleanup-stale-initializing`
- `game repair-ghost-active`
- `db migrate --context GameDbContext`
- `game reconcile-session --session-id ...`
- Keep runtime startup focused on starting the service, not performing maintenance.
## Refactor Phases
### Phase 0: Baseline and Safety Net
Deliverables:
- Add `Server/tests/SOR.Game.Tests`.
- Add unit tests around current behavior before moving code:
- deck validation
- turn-limit winner calculation
- ELO delta calculation
- board generation edge cases
- attack/sacrifice/end-turn golden scenarios
- ability trigger and pending-prompt scenarios
- Add serialization round-trip tests for `GameState` and key game DTOs.
- Add a small integration test harness for handler-to-DbContext flows using test configuration.
Acceptance:
- Tests cover the high-risk behaviors before large file movement.
- No behavior changes are required in this phase.
### Phase 1: Split Contracts and DTOs
Deliverables:
- Split `GameMessages.cs` into workflow-focused files under `Contracts/`.
- Keep public type names stable to avoid client or handler churn.
- Group by domain:
- session messages
- lobby messages
- action messages
- ability prompt messages
- spectator messages
- activity messages
- ranking/outcome messages
Acceptance:
- Build passes.
- Existing message type names and serialized shapes remain compatible.
### Phase 2: Introduce Application Services
Deliverables:
- Create focused application services:
- `GameSessionService`
- `GameLobbyService`
- `GameActionService`
- `GameStatePushService`
- `GameFinalizationService`
- `GameRankingService`
- `GameActivityService`
- Move static helper logic out of `GameHandlerBase`.
- Handlers become thin command adapters:
- parse request
- call application service
- return response
Acceptance:
- Handler classes no longer directly coordinate game finalization, ranking updates, spectator lookup, and state fanout.
- Static singleton service references are removed from new paths.
### Phase 3: Introduce Persistence Interfaces
Deliverables:
- Add repositories for game persistence:
- sessions
- lobbies
- presets
- board templates
- player decks/read models needed by game start
- Centralize JSON field serialization/deserialization for lobby/session extra-player data and rules snapshots.
- Keep EF Core implementations internal.
Acceptance:
- Application services can be unit tested without EF Core.
- Repeated JSON option setup and ad hoc parsing are reduced.
### Phase 4: Split Domain Rules
Deliverables:
- Split `GameEngine` into smaller pure domain components:
- `GameStateSerializer`
- `GameInitializer`
- `DeckValidator`
- `TurnService`
- `CardPlayRules`
- `MovementRules`
- `CombatResolver`
- `GameOutcomeResolver`
- `EloCalculator`
- `GameStateProjector`
- Introduce an injectable randomness abstraction for shuffling and random tile selection.
- Keep pure rule methods free of EF Core, Redis, NATS, client push, and host dependencies.
Acceptance:
- Domain classes can be tested directly.
- Game command behavior remains compatible with current persisted `GameState` JSON.
### Phase 5: Split Ability System
Deliverables:
- Split `AbilitySystem` by responsibility:
- model parsing and polymorphic conversion
- trigger matching
- condition evaluation
- target resolution
- cost resolution
- effect execution
- pending prompt creation
- animation/event projection
- Create golden tests for representative ability cards before and after the split.
Acceptance:
- Ability behavior remains compatible.
- New ability logic can be changed without editing one giant file.
### Phase 6: Externalize Runtime State
Deliverables:
- Replace process-local stores with interfaces:
- `IVoteSessionStore`
- `IRuleSuggestionStore`
- `IGameActivitySubscriptionStore`
- Implement Redis-backed stores with TTLs.
- Keep in-memory implementations only for tests or single-process local development if needed.
Acceptance:
- Multiple `game` pods can observe the same vote/suggestion/activity state.
- Runtime state expires without requiring process cleanup.
### Phase 7: Operational Jobs and Admin Processes
Deliverables:
- Move startup cleanup logic into reusable job classes.
- Add one-off commands in `SOR.Tools`:
- cleanup stale initializing sessions
- repair ghost active sessions
- migrate database contexts
- Make `GameStartupCleanupService` optional via config, then phase it down once operational jobs are in place.
Acceptance:
- Maintenance tasks can be run independently of normal service startup.
- Jobs are idempotent and safe to retry.
### Phase 8: Config, Health, and Release Hardening
Deliverables:
- Add typed options and startup validation.
- Add per-service health checks:
- Redis
- NATS
- relevant database contexts
- optional external services per enabled module
- Define readiness vs liveness behavior.
- Document process formations and release steps.
Acceptance:
- A missing required config value fails fast.
- `/health` remains cheap liveness.
- Readiness endpoint reflects backing service availability.
## Suggested Milestone Order
1. Create test project and golden tests for existing game behavior.
2. Split `GameMessages.cs` into contract groups.
3. Extract push/finalization/ranking from `GameHandlerBase`.
4. Introduce application services and repositories.
5. Split `GameEngine`.
6. Split `AbilitySystem`.
7. Redis-back runtime state currently held in singleton dictionaries.
8. Move startup cleanup into one-off admin jobs.
9. Add typed config, validation, and readiness checks.
10. Update architecture docs after implementation stabilizes.
## Risk Register
| Risk | Why It Matters | Mitigation |
|---|---|---|
| Ability regressions | `AbilitySystem` is large and likely encodes many card-specific edge cases. | Golden tests before splitting, small mechanical moves first. |
| Game state compatibility | Persisted `StateJson` must keep loading existing active sessions. | Serialization round-trip tests and version-tolerant DTO changes. |
| Multi-pod races | Multiple game workers can process commands for one session. | Add per-session command serialization or optimistic concurrency. |
| In-memory vote/suggestion loss | Current process-local state disappears on restart or cross-pod routing. | Move to Redis with TTL. |
| Startup repair side effects | Large cleanup during app boot can slow or destabilize deploys. | Move to idempotent admin jobs. |
| Static service references | Harder testing and hidden runtime coupling. | Replace with injected application services. |
## Definition of Done
The refactor is complete when:
- `SOR.Game` handlers are thin adapters.
- Core game and ability rules are testable without ASP.NET Core, EF Core, Redis, or NATS.
- Shared ephemeral state required for correctness is stored in Redis or another backing service.
- Runtime startup is fast and does not rely on implicit maintenance work.
- Maintenance tasks can be run as one-off admin processes.
- Config values are environment-driven, typed, and validated.
- Logs are structured event streams with no direct `Console.WriteLine` in game logic.
- Health/readiness checks reflect the backing services required by the enabled process type.
- The production process model can scale game workers without changing code.
+458
View File
@@ -0,0 +1,458 @@
# SOR.Gateway 12-Factor Refactor Plan
Date: 2026-06-08
Scope reviewed:
- `Server/src/SOR.Gateway`
- `Server/src/SOR.Networking.WebSocket`
- `Server/src/SOR.Networking.Nats`
- `Server/src/SOR.Networking.Redis`
- Gateway wiring in `Server/src/SOR.Host`
Reference: https://12factor.net/
## Executive Summary
`SOR.Gateway` is already shaped like a 12-Factor edge process in several important ways. It is a service module, it depends mostly on abstractions for transport and messaging, it accepts WebSocket connections through host-provided port binding, it uses Redis Pub/Sub as an attached service for push delivery, and it routes worker-owned messages through NATS request/reply.
The main gaps are around operational hardening and structure:
- `ConnectionLoop.cs` owns auth handshake parsing, authentication dispatch, connection registration, Redis push subscription, message receive, deserialization, dispatch, error mapping, send, and cleanup.
- `GatewayHostedService` accepts unlimited connections and starts one task per connection without an explicit connection limit or backpressure policy.
- `WebSocketTransport` uses an unbounded pending-connection channel.
- `GatewayOptions.MaxMessagesPerSecond` exists, but the comment says enforcement is not implemented.
- Redis push subscriber forwards messages using fire-and-forget tasks and `CancellationToken.None`, which makes shutdown and overload behavior harder to reason about.
- Gateway readiness is not dependency-aware; it needs Auth gRPC, Redis, NATS, and WebSocket transport checks when the gateway process is enabled.
- Service names and NATS RPC subjects are string-derived and should be centralized with validation.
- There is no visible gateway test project under `Server/tests`.
The plan is to keep the gateway stateless from a process-correctness perspective, but split the connection lifecycle into focused components and add explicit controls for config validation, limits, readiness, and shutdown.
## Current Structure Observations
### Strong Foundations
- `SOR.Gateway` is a library module registered by `AddGatewayService`.
- `SOR.Host` wires concrete implementations and only enables gateway when `ENABLED_SERVICES` includes `gateway`.
- Gateway depends on `ITransport`, `IMessageDispatcher`, `IMessageSerializer`, and `IGatewayAuthValidator`.
- Auth calls are hidden behind `IGatewayAuthValidator`.
- Message handlers are resolved locally when co-located and remotely through NATS when not co-located.
- Redis Pub/Sub is used as an attached service for cross-instance push delivery.
- `ConnectionManager` is explicitly documented as per-instance only, which is the correct model for a horizontally scaled gateway.
- WebSocket send path is serialized by a per-connection lock.
- Shutdown attempts to cancel the accept loop and wait for active connection tasks.
### Main Problems
- Gateway connection lifecycle is too concentrated in `ConnectionLoop`.
- Auth payload records are private to `ConnectionLoop`, which makes auth handshake behavior harder to test independently.
- Rate limiting is configured but not enforced.
- There is no max active connection limit, max unauthenticated connection limit, or bounded accept queue.
- Redis push subscription is created directly by `ConnectionLoop` instead of through an injected abstraction.
- Gateway has direct `StackExchange.Redis` dependency in connection handling because `RedisPushSubscriber` is directly constructed.
- Remote dispatch subject naming is duplicated with `NatsMessageRpcResponder`.
- Gateway does not expose operational metrics such as active connections, auth failures, dispatch timeouts, push failures, or pending accept queue length.
- Readiness is not separated from liveness.
## Target Gateway Shape
Keep `SOR.Gateway` as the edge service module, but split responsibilities:
```text
Server/src/SOR.Gateway/
ServiceRegistration.cs
Configuration/
GatewayOptions.cs
GatewayOptionsValidator.cs
GatewayLimitsOptions.cs
Connections/
GatewayHostedService.cs
ConnectionLoop.cs
ConnectionManager.cs
ConnectionLimiter.cs
ConnectionMetrics.cs
Auth/
IGatewayAuthValidator.cs
GatewayAuthValidator.cs
AuthHandshakeService.cs
AuthHandshakeMessages.cs
Dispatch/
MessageDispatcher.cs
RpcSubjectNames.cs
RemoteDispatchOptions.cs
Push/
IConnectionPushSubscriber.cs
RedisConnectionPushSubscriber.cs
ConnectionPushSubscription.cs
RateLimiting/
IMessageRateLimiter.cs
TokenBucketMessageRateLimiter.cs
Health/
GatewayHealthChecks.cs
```
`ConnectionLoop` should become orchestration only:
1. Wait for auth handshake.
2. Register authenticated connection.
3. Subscribe to push delivery.
4. Receive client messages.
5. Apply rate limit and validation.
6. Dispatch.
7. Send reply.
8. Dispose resources.
## 12-Factor Gap Map
### I. Codebase
Status: Mostly aligned.
Current state:
- Gateway lives in the same server codebase and is enabled through host process formation.
- Concrete transports are wired in `SOR.Host`.
Plan:
- Keep one codebase and one host binary.
- Document gateway as a process type: `ENABLED_SERVICES=gateway`.
- Keep gateway code free of game/chat/collection domain logic.
### II. Dependencies
Status: Partially aligned.
Current state:
- Gateway uses abstractions for transport and messaging.
- Gateway directly references Redis and NATS packages for push subscription and remote dispatch.
- Concrete WebSocket transport is outside the gateway project.
Plan:
- Keep `ITransport` abstraction for WebSocket replacement.
- Introduce `IConnectionPushSubscriber` so `ConnectionLoop` no longer directly constructs Redis subscribers.
- Centralize RPC subject naming in shared networking code.
- Keep NATS-specific code contained in dispatch or networking infrastructure, not spread through connection lifecycle code.
### III. Config
Status: Partially aligned.
Current state:
- `GatewayOptions` has auth timeout, max messages per second, and remote dispatch timeout.
- WebSocket options are configured separately.
- Options are bound but not validated.
Plan:
- Add typed validation for:
- `Gateway:AuthTimeoutMs`
- `Gateway:MaxMessagesPerSecond`
- `Gateway:RemoteDispatchTimeoutMs`
- `Gateway:MaxConnections`
- `Gateway:MaxPendingConnections`
- `Gateway:MaxUnauthenticatedConnections`
- `Gateway:PushSendTimeoutMs`
- `WebSocket:Path`
- `WebSocket:PingIntervalMs`
- `WebSocket:MaxMessageSizeBytes`
- `Services:Auth`
- Fail fast when gateway is enabled and required config is missing or invalid.
### IV. Backing Services
Status: Mostly aligned, with readiness gaps.
Current state:
- Auth is an attached service via gRPC.
- Redis is an attached service for push subscription.
- NATS is an attached service for remote dispatch.
- Gateway does not persist critical application state locally.
Plan:
- Treat Auth, Redis, and NATS as required gateway backing services.
- Add readiness checks for all required attached services.
- Keep connection registry in memory because it is per-instance socket state.
- Keep durable application state in worker services, not the gateway.
- Document Redis Pub/Sub push as best-effort delivery and require client sync for durable state.
### V. Build, Release, Run
Status: Mostly aligned.
Current state:
- Gateway is built as part of `SOR.Host`.
- Runtime behavior is selected by `ENABLED_SERVICES`.
Plan:
- Keep gateway deploy as host image plus gateway formation config.
- Add release checklist for gateway:
- build host image
- validate gateway config
- verify Auth, Redis, and NATS endpoints
- deploy `ENABLED_SERVICES=gateway`
- Keep gateway startup free of migrations or admin repair work.
### VI. Processes
Status: Mostly aligned conceptually, needs limits.
Current state:
- Gateway process is stateless across requests except live WebSocket connections.
- Each connection gets a task.
- Connection manager is process-local by design.
Plan:
- Add explicit process limits:
- max active connections
- max pending upgrades
- max unauthenticated connections
- per-connection message rate
- per-connection send queue or timeout
- Make limits configurable and validated.
- Ensure multiple gateway processes can run behind a load balancer without shared memory assumptions.
### VII. Port Binding
Status: Aligned through host.
Current state:
- `SOR.Host` binds HTTP/WebSocket port.
- Gateway uses `ITransport` and WebSocket middleware when enabled.
Plan:
- Keep port binding in `SOR.Host`.
- Keep gateway unaware of public port numbers.
- Document WebSocket path and load balancer requirements.
- Ensure `/health` and `/ready` remain available on gateway process deployments.
### VIII. Concurrency
Status: Partially aligned.
Current state:
- Accept loop runs continuously.
- Each connection runs independently.
- WebSocket transport queues pending connections without a bound.
- Send path is serialized per connection.
- Remote dispatch uses per-request NATS timeouts.
Plan:
- Replace unbounded pending connection channel with bounded capacity.
- Add backpressure behavior for pending WebSocket upgrades.
- Enforce `MaxMessagesPerSecond`.
- Add remote dispatch concurrency limits if needed.
- Track push forwarding tasks or move push forwarding through a bounded per-connection send queue.
- Add metrics for active tasks, pending connections, dispatch latency, and timeout rates.
### IX. Disposability
Status: Partially aligned.
Current state:
- Gateway cancels accept loop on shutdown and waits for tracked connection tasks.
- Connection cleanup unregisters, unsubscribes push, disposes socket.
- Push forwarding ignores cancellation.
Plan:
- Ensure connection loops respond quickly to shutdown.
- Add configurable graceful shutdown timeout and connection drain behavior.
- Avoid `CancellationToken.None` in push forwarding except where explicitly justified.
- Track or bound fire-and-forget push sends.
- Ensure Redis unsubscribe is attempted but does not block shutdown indefinitely.
- Add load balancer drain guidance for gateway deployments.
### X. Dev/Prod Parity
Status: Partially aligned.
Current state:
- Local config supports Redis, NATS, and Auth service URLs.
- Gateway can run co-located with auth or other services in `all` mode.
Plan:
- Support two local modes:
- `ENABLED_SERVICES=all` for convenience
- `ENABLED_SERVICES=gateway` plus separate Auth/worker processes for production-like testing
- Keep config keys identical across environments.
- Add local test instructions for Redis, NATS, Auth, and WebSocket client behavior.
### XI. Logs
Status: Mostly aligned.
Current state:
- Gateway uses structured logging.
- Important events are logged: accept loop start, auth success, dispatch route, remote dispatch errors, push failures.
Plan:
- Keep logs as stdout event streams.
- Add structured fields consistently:
- `ConnectionId`
- `UserId`
- `MessageType`
- `Seq`
- `RemoteAddress`
- `DispatchMode`
- `CloseReason`
- Avoid logging credentials, session tokens, passwords, or Keycloak tokens.
- Add startup summary for gateway limits and dependencies.
### XII. Admin Processes
Status: Mostly aligned.
Current state:
- Gateway has no migrations or persistent state to repair.
Plan:
- Keep gateway free of admin tasks.
- Add operational commands elsewhere if needed:
- inspect connected users through metrics
- validate gateway config
- smoke test Auth/Redis/NATS connectivity
- Do not embed maintenance behavior into gateway startup.
## Refactor Phases
### Phase 0: Baseline and Tests
Deliverables:
- Add `Server/tests/SOR.Gateway.Tests`.
- Add tests for:
- auth handshake success and failure paths
- malformed first message
- unauthenticated non-auth first message
- local dispatch
- remote dispatch timeout
- remote dispatch no responder
- connection registration and unregister behavior
- push subscription disposal
Acceptance:
- Current behavior is covered before extracting lifecycle components.
### Phase 1: Extract Auth Handshake
Deliverables:
- Add `AuthHandshakeService`.
- Move auth payload records out of `ConnectionLoop`.
- Return a structured result containing user ID, display name, session token, ack type, and starter-deck flag.
- Keep error response mapping explicit.
Acceptance:
- `ConnectionLoop` no longer switches directly over auth message types.
- Auth handshake can be unit tested without a WebSocket.
### Phase 2: Extract Push Subscription Abstraction
Deliverables:
- Add `IConnectionPushSubscriber`.
- Add `RedisConnectionPushSubscriber`.
- Inject the abstraction into `ConnectionLoop`.
- Add configurable send timeout and cancellation behavior.
Acceptance:
- `ConnectionLoop` no longer directly depends on `IConnectionMultiplexer`.
- Push behavior can be tested without Redis.
### Phase 3: Enforce Limits and Backpressure
Deliverables:
- Implement per-connection message rate limiting.
- Add `ConnectionLimiter`.
- Add bounded pending WebSocket connection channel.
- Add config for max active and pending connections.
- Define close/error reasons for limit failures.
Acceptance:
- Gateway can reject or close overload traffic predictably.
- `MaxMessagesPerSecond` is enforced or removed if intentionally unsupported.
### Phase 4: Centralize Dispatch Contracts
Deliverables:
- Move `sor.rpc.{messageType}` subject generation to one shared helper.
- Ensure `MessageDispatcher` and `NatsMessageRpcResponder` use the same helper.
- Add validation for message type to subject conversion.
- Add tests for local and remote dispatch routes.
Acceptance:
- RPC subject naming cannot drift between gateway and worker responders.
### Phase 5: Health, Readiness, and Metrics
Deliverables:
- Add gateway readiness checks for:
- Auth gRPC endpoint
- Redis
- NATS
- WebSocket transport registration
- Add metrics or health details for:
- active authenticated connections
- pending WebSocket upgrades
- auth failure counts
- dispatch timeout counts
- push forwarding failures
Acceptance:
- Gateway can be kept out of load balancer rotation until dependencies are reachable.
### Phase 6: Graceful Shutdown and Drain
Deliverables:
- Add shutdown/drain options.
- Stop accepting new WebSocket upgrades during shutdown.
- Close existing connections with a clear server shutdown reason after drain timeout.
- Bound Redis unsubscribe and push send waits.
Acceptance:
- Gateway shutdown is predictable under active client load.
- Load balancer drain behavior is documented.
### Phase 7: Documentation and Deployment Runbook
Deliverables:
- Document gateway process formation.
- Document required attached services.
- Document load balancer and WebSocket upgrade requirements.
- Document scaling guidance and capacity knobs.
- Document expected best-effort push semantics.
Acceptance:
- Gateway can be deployed and scaled independently with clear operational expectations.
## Suggested Milestone Order
1. Add gateway tests around current connection lifecycle.
2. Extract auth handshake service.
3. Extract push subscription abstraction.
4. Implement rate limiting and connection limits.
5. Bound WebSocket pending connection queue.
6. Centralize RPC subject names.
7. Add readiness checks and basic metrics.
8. Harden graceful shutdown and drain behavior.
9. Write gateway deployment runbook.
## Risk Register
| Risk | Why It Matters | Mitigation |
|---|---|---|
| Connection lifecycle regressions | Gateway is the client entry point. | Add tests before splitting `ConnectionLoop`. |
| Overload behavior changes | Bounding queues can reject clients that currently wait. | Roll out with conservative limits and clear close reasons. |
| Rate limiting false positives | Bursty legitimate game traffic may trip limits. | Use token bucket with burst capacity and tune in staging. |
| Push delivery assumptions | Redis Pub/Sub is best-effort. | Document semantics and keep durable state sync in worker services. |
| Shutdown disconnects active games | Gateway shutdown can drop sockets. | Add drain mode and client reconnect expectations. |
| RPC subject drift | Gateway and workers must agree on NATS subjects. | Centralize subject generation and test it. |
## Definition of Done
The gateway refactor is complete when:
- `ConnectionLoop` is small lifecycle orchestration, not auth/push/dispatch implementation.
- Auth handshake behavior is isolated and tested.
- Redis push subscription is behind an injected abstraction.
- Message rate limiting is enforced or deliberately removed from config.
- Active connections and pending upgrades have explicit limits.
- WebSocket pending connection queue is bounded.
- Gateway readiness checks cover Auth, Redis, NATS, and transport registration.
- Gateway logs are structured and never include credentials or tokens.
- Graceful shutdown drains or closes connections predictably.
- Gateway remains horizontally scalable with no cross-instance in-memory correctness dependency.
+459
View File
@@ -0,0 +1,459 @@
# 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:
```text
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:
```csharp
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.
+425
View File
@@ -0,0 +1,425 @@
# SOR.Matchmaking 12-Factor Refactor Plan
Date: 2026-06-10
Scope reviewed:
- `Server/src/SOR.Matchmaking`
- Matchmaking persistence in `Server/src/SOR.Database/Contexts/GameDbContext.cs`
- Identity rank reads in `Server/src/SOR.Database/Contexts/SorIdentityDbContext.cs`
- Matchmaking wiring in `Server/src/SOR.Host`
- Push and event dependencies through `IClientPush` and `IEventBus`
Reference: https://12factor.net/
## Executive Summary
`SOR.Matchmaking` is a service module registered by `SOR.Host` when `ENABLED_SERVICES` includes `matchmaking`. It exposes handlers for joining, leaving, and checking matchmaking queue status, and it starts `MatchmakerService`, a polling background worker that pairs players by rank range, creates `GameSession` rows, publishes `GameStartedEvent`, and pushes `matchmaking.match_found` notifications to both players.
The module already has useful foundations:
- Queue state is durable in the `game.matchmaking_entries` table.
- Queue join is idempotent in the common case where an active searching entry already exists.
- Match creation snapshots ranked rules and board template data into the game session.
- Match found delivery uses existing `IClientPush`.
- Game lifecycle notification uses existing `IEventBus`.
- The worker is cancellation-aware and logs tick failures.
The main 12-Factor gaps are around process formation, config, and concurrency:
- Request handlers and the matchmaking worker are always registered together.
- Poll interval, rank range, range expansion, max range, and expansion cadence are hardcoded constants.
- Multiple matchmaking worker processes can load and match the same queue entries unless there is only one instance operationally.
- Active queue uniqueness is application-level only; concurrent joins can create duplicate searching entries.
- Match creation, queue-entry updates, event publish, and push delivery are not modeled with an outbox/idempotent delivery boundary.
- Join does not visibly validate that the selected deck exists, belongs to the account, and is valid for ranked play.
- Queue cleanup, stale entry expiration, abandoned initializing sessions, and retry/reconciliation jobs are not explicit.
- Readiness is host-level only and does not account for Game DB, Identity DB, push, or event bus dependencies.
The plan is to keep `SOR.Matchmaking` as the ranked queue module, but split request handlers from worker registration, add typed config, harden queue invariants with database/lease semantics, introduce a transaction/outbox boundary for match creation, and add observability and operational jobs.
## Current Structure Observations
### Strong Foundations
- `AddMatchmakingService` registers `GameDbContext`, `SorIdentityDbContext`, all handlers, and `MatchmakerService`.
- `MatchmakingJoinHandler` returns the existing searching entry when found.
- `MatchmakingLeaveHandler` marks searching entries cancelled instead of deleting them.
- `MatchmakerService` orders queue entries by wait time.
- Rank range expands over time to reduce indefinite waits.
- Game sessions snapshot ranked rules, board dimensions, turn timer, rewards, and board template JSON.
- `GameStartedEvent` is published after game session creation.
- Both matched players receive a push payload with session ID and opponent info.
### Main Problems
- Matchmaking algorithm parameters are hardcoded in `MatchmakerService`.
- `MatchmakerService` starts whenever the matchmaking module is enabled, which couples API handlers and worker role.
- The worker loads all searching entries into memory each tick.
- There is no distributed lock, row claim, or queue-group style ownership for matching work.
- There is no database constraint guaranteeing one active searching entry per account.
- `JoinQueueRequest` accepts a deck ID but does not visibly validate deck ownership or deck validity.
- Publishing `GameStartedEvent` can fail after the game session and queue entries are committed.
- Push delivery can fail after the match is committed.
- There is no durable delivery state for match-found notifications.
- Stale searching entries and old cancelled/matched entries do not appear to have retention cleanup.
- No visible tests cover concurrent joins or multiple workers.
## Target Matchmaking Shape
Keep `SOR.Matchmaking` focused on ranked queue orchestration, but split responsibilities:
```text
Server/src/SOR.Matchmaking/
Configuration/
MatchmakingOptions.cs
MatchmakingWorkerOptions.cs
MatchmakingRankOptions.cs
MatchmakingOptionsValidator.cs
Bootstrap/
MatchmakingRegistration.cs
MatchmakingHandlersRegistration.cs
MatchmakingWorkerRegistration.cs
MatchmakingHealthChecks.cs
Contracts/
MatchmakingMessages.cs
MatchmakingErrors.cs
Application/
Queue/
MatchmakingQueueService.cs
QueueEntryValidator.cs
QueueStatusService.cs
Matching/
MatchmakerWorker.cs
MatchCandidateSelector.cs
MatchCreationService.cs
RankedRuleSnapshotBuilder.cs
Delivery/
MatchFoundNotificationService.cs
MatchmakingOutboxService.cs
Persistence/
IMatchmakingRepository.cs
IDeckEligibilityReader.cs
IRankReader.cs
IMatchmakingLeaseStore.cs
IMatchmakingUnitOfWork.cs
Jobs/
ExpireStaleQueueEntriesJob.cs
ReconcileUndeliveredMatchesJob.cs
CleanupOldMatchmakingEntriesJob.cs
```
Desired process roles:
- `matchmaking-api`: handles join, leave, and status requests.
- `matchmaking-worker`: runs matching ticks and owns match creation.
- `matchmaking-jobs`: runs cleanup and reconciliation jobs.
Small deployments can co-locate these roles, but registration should make the role boundary explicit.
## 12-Factor Gap Map
### 1. Codebase
Mostly aligned. Matchmaking is one small module, but handler and worker concerns are co-registered.
Plan:
- Keep one module.
- Split API handlers, worker, and maintenance jobs into explicit registration methods.
- Extract matching algorithm and match creation into testable services.
### 2. Dependencies
Mostly aligned. Dependencies are explicit: Game DB, Identity DB, event bus, and client push.
Plan:
- Add abstractions for rank reads, deck eligibility, queue repository, match creation, and notification delivery.
- Keep `IEventBus` and `IClientPush` behind a match delivery/outbox service.
- Avoid direct Identity queries in the worker where a rank reader service is sufficient.
### 3. Config
Weakly aligned. All matchmaking behavior is hardcoded.
Plan:
- Add typed `MatchmakingOptions`.
- Move poll interval, batch size, rank range, range expansion, max range, stale queue timeout, and worker enablement into config.
- Validate options at startup.
Candidate config shape:
```json
{
"Matchmaking": {
"ApiEnabled": true,
"WorkerEnabled": true,
"PollIntervalMs": 5000,
"MaxEntriesPerTick": 200,
"InitialRankRange": 100,
"RangeExpandStep": 100,
"MaxRankRange": 500,
"ExpandEverySeconds": 30,
"StaleQueueEntryMinutes": 15,
"RequireValidDeck": true
}
}
```
### 4. Backing Services
Partially aligned. Matchmaking uses PostgreSQL, NATS, Redis/client push, and Identity rank data, but readiness does not reflect those dependencies.
Plan:
- Treat Game DB, Identity DB, event bus, and push delivery as attached resources.
- Add role-specific readiness checks.
- Define degraded mode: API may accept queue operations only when worker/delivery dependencies are healthy, or explicitly reject joins if worker is unavailable.
### 5. Build, Release, Run
Mostly aligned. There are no build-time assets and no migrations run here.
Plan:
- Keep schema migrations outside matchmaking startup.
- Include deployment checks for worker replica count and queue ownership mode.
- Version algorithm changes through config/release notes because matching behavior is player-visible.
### 6. Processes
Partially aligned. API request handling and worker polling are one process role today.
Plan:
- Split registration into:
- `AddMatchmakingCore`
- `AddMatchmakingHandlers`
- `AddMatchmakingWorker`
- `AddMatchmakingJobs`
- Let `SOR.Host` decide which roles start.
- Validate unsafe combinations, such as multiple workers without leases.
### 7. Port Binding
Aligned through `SOR.Host`. Matchmaking does not bind ports directly.
Plan:
- Keep port binding in Host/Gateway.
- Expose matchmaking readiness through host health checks.
### 8. Concurrency
Weakly aligned. This is the main risk area.
Plan:
- Add a database-backed active queue uniqueness rule for one searching entry per account.
- Add row claiming with `FOR UPDATE SKIP LOCKED`, optimistic status transitions, or a worker lease model.
- Ensure game session creation and queue entry resolution happen in one transaction.
- Make match creation idempotent per entry pair.
- Add tests for two workers attempting to match the same entries.
### 9. Disposability
Partially aligned. The worker accepts cancellation, but tick duration and shutdown boundaries are not explicit.
Plan:
- Make ticks bounded by max entries and command timeout.
- Stop starting new match attempts on shutdown.
- Complete or rollback the current transaction before exit.
- Move push/event retry to outbox/reconciliation so shutdown does not lose delivery.
### 10. Dev/Prod Parity
Partially aligned. Same code runs locally and in production, but worker count and timing behavior are not config-driven.
Plan:
- Use the same worker code locally and in production.
- Configure local shorter poll intervals if useful.
- Document single-worker versus multi-worker deployment behavior.
- Add a local test profile for queue scenarios.
### 11. Logs
Partially aligned. Worker starts/stops, tick errors, and found matches are logged.
Plan:
- Add structured logs and metrics for joins, leaves, matches, candidate search, stale entries, event publish, push delivery, and worker claim conflicts.
- Avoid logging sensitive deck contents.
Suggested fields:
- `entryId`
- `accountId`
- `opponentAccountId`
- `gameSessionId`
- `rankScore`
- `opponentRankScore`
- `rankRange`
- `waitSeconds`
- `workerId`
- `deliveryState`
### 12. Admin Processes
Partially aligned. Cleanup/reconciliation are operational jobs but not explicit.
Plan:
- Add admin/job processes for stale queue expiration, delivery reconciliation, old entry cleanup, and queue health reports.
- Add dry-run reports for cleanup.
- Add Admin visibility for current queue depth, age, rank distribution, and worker status.
## Refactor Phases
### Phase 0: Baseline Tests
Goals:
- Preserve current behavior before restructuring.
Work:
- Add tests for join idempotency, leave idempotency, and status.
- Add tests for rank range expansion.
- Add tests for closest-opponent selection.
- Add tests for session rule snapshot generation.
- Add tests for event/push failure behavior as it works today.
Done when:
- Current behavior is covered before refactors.
### Phase 1: Typed Options
Goals:
- Make matchmaking behavior configurable.
Work:
- Add `MatchmakingOptions`.
- Replace hardcoded poll/range constants with options.
- Add startup validation.
- Preserve current defaults.
Done when:
- Operators can tune queue behavior per environment without code changes.
### Phase 2: Split API and Worker Registration
Goals:
- Make process formation explicit.
Work:
- Split `AddMatchmakingService` into core, handlers, worker, and jobs.
- Keep current host behavior initially by calling both handlers and worker registration.
- Add host-level role support later if desired.
Done when:
- A deployment can run API-only, worker-only, or combined matchmaking roles intentionally.
### Phase 3: Extract Queue and Matching Services
Goals:
- Make matching logic testable and smaller.
Work:
- Extract `MatchmakingQueueService` for join/leave/status.
- Extract `MatchCandidateSelector` for rank-window selection.
- Extract `MatchCreationService` for session creation and queue resolution.
- Extract `RankedRuleSnapshotBuilder`.
Done when:
- Handlers and worker are orchestration shells over tested services.
### Phase 4: Deck Eligibility Validation
Goals:
- Prevent invalid ranked queue entries.
Work:
- Add `IDeckEligibilityReader`.
- Validate deck ownership, deck validity, and ranked eligibility on join.
- Decide whether already queued entries should be revalidated before match creation.
Done when:
- Players cannot queue ranked matchmaking with invalid or unowned decks.
### Phase 5: Concurrency Hardening
Goals:
- Make matchmaking safe under concurrent joins and multiple workers.
Work:
- Add database uniqueness or conditional insert for one searching entry per account.
- Add queue row claiming or worker leases.
- Use transactions around claiming, session creation, and entry resolution.
- Add multi-worker concurrency tests.
Done when:
- Multiple API instances and worker instances cannot duplicate queue entries or matches.
### Phase 6: Outbox and Delivery Reconciliation
Goals:
- Avoid losing game-started events or match-found pushes after DB commit.
Work:
- Add an outbox record for `GameStartedEvent` and match-found notifications.
- Publish/push from outbox with retry.
- Add reconciliation job for undelivered match notifications.
- Make push delivery idempotent from the client perspective.
Done when:
- A committed match cannot silently miss lifecycle event or player notification delivery.
### Phase 7: Queue Maintenance Jobs
Goals:
- Keep queue data healthy.
Work:
- Add stale searching entry expiration.
- Add cleanup for old cancelled/matched entries.
- Add abandoned initializing session detection handoff or integration with game inactivity logic.
- Add admin queue reports.
Done when:
- Queue state does not grow unbounded or remain stuck indefinitely.
### Phase 8: Readiness and Observability
Goals:
- Make matchmaking operations diagnosable.
Work:
- Add readiness checks for Game DB, Identity DB, event bus, push, and worker lease.
- Add metrics for queue depth, oldest wait time, matches per minute, average rank delta, tick latency, delivery failures, and claim conflicts.
- Add runbooks for stuck queues, delivery failures, and worker scaling.
Done when:
- Operators can see whether players can join, be matched, and receive match notifications.
## Suggested Work Order
1. Add baseline tests for join/leave/status and candidate selection.
2. Add typed `MatchmakingOptions` with current defaults.
3. Split handler and worker registration.
4. Extract queue, selector, snapshot, and match creation services.
5. Add deck eligibility validation.
6. Add active-entry uniqueness and worker row claiming.
7. Add outbox/reconciliation for event and push delivery.
8. Add queue cleanup jobs.
9. Add readiness checks, metrics, dashboards, and runbooks.
## Completion Criteria
The refactor is complete when:
- Matchmaking API and worker roles are registered explicitly.
- Matchmaking behavior is controlled by typed config.
- Queue joins are concurrency-safe and idempotent.
- Multiple workers are either prevented or coordinated safely.
- Match creation is transactional and idempotent.
- Game-started events and match-found pushes are delivered through a retryable outbox.
- Deck eligibility is validated before ranked matchmaking.
- Stale queue and undelivered match states have maintenance jobs.
- Readiness and metrics show queue health, worker health, and delivery health.
## Immediate Low-Risk Next Steps
- Add `MatchmakingOptions` with defaults matching current constants.
- Extract `MatchCandidateSelector` and cover rank-window behavior with tests.
- Split `AddMatchmakingService` internally into handler and worker registration methods without changing host behavior.
- Add a database/model plan for one active searching entry per account.
- Document the current single-worker assumption until row claiming or leases are implemented.
+368
View File
@@ -0,0 +1,368 @@
# SOR.Networking 12-Factor Refactor Plan
Date: 2026-06-10
Scope reviewed:
- `Server/src/SOR.Networking.Abstractions`
- `Server/src/SOR.Networking.WebSocket`
- `Server/src/SOR.Networking.Nats`
- `Server/src/SOR.Networking.Redis`
- Networking wiring in `Server/src/SOR.Host`
- Gateway-facing usage in `Server/src/SOR.Gateway`
- Shared subject/channel contracts in `Server/src/SOR.Shared`
Reference: https://12factor.net/
## Executive Summary
`SOR.Networking` is the shared transport and messaging layer for the server. It defines the abstractions used by service modules and supplies concrete implementations for WebSocket client transport, NATS event/RPC messaging, and Redis Pub/Sub client push.
The module already has strong 12-factor foundations:
- Application code depends on abstractions: `ITransport`, `IClientConnection`, `IEventBus`, and `IClientPush`.
- Concrete providers are isolated in separate projects: WebSocket, NATS, and Redis.
- `SOR.Host` is the composition root that wires concrete infrastructure to abstractions.
- Redis and NATS are treated as attached backing services.
- WebSocket, NATS, and Redis lifetimes are mostly singleton/process-scoped.
- Event bus delivery semantics are documented as core NATS at-most-once.
- Redis push delivery semantics are documented as best-effort.
- NATS RPC responders use queue groups for handler request distribution.
The main 12-factor gaps are operational rather than architectural:
- WebSocket transport uses an unbounded accept queue, so overload can become memory pressure.
- WebSocket options are bound but not validated at startup.
- There is no explicit max connection, max pending accept, max send size, or outbound backpressure policy.
- NATS URL and Redis connection are configured in `SOR.Host`, but dependency health/readiness is still host-level and minimal.
- NATS fan-out subscriptions use no queue group by default, which is correct for broadcast but risky if consumers accidentally scale a singleton-style worker.
- NATS RPC subject and queue naming is duplicated with Gateway dispatch logic instead of centralized in shared contracts.
- Redis push ignores subscriber count by design, but metrics do not currently expose dropped/offline delivery volume.
- `RedisClientPush.PushAsync` accepts a cancellation token but does not pass it to `PublishAsync`, because StackExchange.Redis Pub/Sub does not use that token directly.
- `NatsMessageRpcResponder` starts listener tasks directly and logs unexpected listener termination, but does not restart failed listeners.
- Readiness, metrics, and integration smoke tests are not packaged with the networking modules.
The plan is to preserve the current abstraction split, then add typed provider options, validation, bounded queues, health checks, delivery-semantic documentation in interfaces, central subject/channel naming helpers, and contract/integration tests around the transport and broker boundaries.
## Current Structure Observations
### Strong Foundations
- `SOR.Networking.Abstractions` keeps service code decoupled from WebSocket, NATS, and Redis.
- `SOR.Networking.WebSocket` implements `ITransport` and `IClientConnection` without leaking ASP.NET Core WebSocket types through the abstraction boundary.
- `WebSocketClientConnection` serializes concurrent sends with `SemaphoreSlim`.
- `WebSocketClientConnection` enforces `MaxMessageSizeBytes` while assembling frames.
- `WebSocketTransport` uses a channel to hand accepted ASP.NET Core WebSocket connections to the Gateway accept loop.
- `SOR.Networking.Nats` wraps NATS behind `IEventBus`.
- `NatsEventBus` explicitly documents core NATS at-most-once semantics and reserves JetStream for durable delivery needs.
- `NatsMessageRpcResponder` exposes local `IMessageHandler` implementations over NATS request/reply so Gateway can relay client requests to worker processes.
- `NatsMessageRpcResponder` uses queue groups per message type for competing consumers.
- `SOR.Networking.Redis` keeps push publishing separate from Gateway's Redis subscription/read side.
- `IClientPush` and `RedisClientPush` both document best-effort/offline-drop behavior.
- `SOR.Shared.Nats.NatsSubjects` and `SOR.Shared.Redis.RedisKeys` already provide shared naming contracts for event subjects and Redis push channels.
### Main Problems
- `WebSocketTransport` uses `Channel.CreateUnbounded<IClientConnection>`, so the process has no configured accept backlog limit.
- `WebSocketTransportOptions` contains path, ping interval, and max message size, but no validator prevents invalid values.
- `appsettings.json` includes `WebSocket:AuthTimeoutMs` and `WebSocket:MaxMessagesPerSecond`, but `WebSocketTransportOptions` only defines path, ping interval, and max message size. That creates config drift between host settings and transport settings.
- WebSocket keep-alive is configured in `SOR.Host` separately from the application-level ping loop in `WebSocketClientConnection`.
- The ping loop is fire-and-forget; it catches/logs exceptions, but it is not represented as a hosted lifecycle primitive.
- There is no explicit per-connection outbound queue limit or send timeout policy.
- `NatsEventBus.SubscribeAsync` always uses `queueGroup: null`, which is good for true fan-out but should be hard to misuse for singleton worker workflows.
- NATS RPC subject/queue naming exists in both Gateway dispatch and `NatsMessageRpcResponder` as local helper methods.
- `NatsMessageRpcResponder` creates one listener task per handler type. If a listener exits unexpectedly, it is logged but not restarted.
- `NatsMessageRpcResponder` discovers duplicate handlers at startup, but there is no diagnostics endpoint or test that verifies the registered RPC surface.
- `RedisClientPush` publishes bytes and intentionally ignores subscriber count; this should be observable as `subscriber_count=0`, not invisible.
- `IClientPush` does not expose or record delivery hints such as subscriber count, offline drop, or publish latency.
- `SOR.Host` has only a minimal `/health` check and a TODO for Redis, NATS, and Postgres dependency checks.
- There are no visible contract tests proving message serialization, RPC relay behavior, WebSocket frame limits, cancellation, or shutdown semantics.
## Target Networking Shape
Keep the provider split, but make operational policy explicit:
```text
Server/src/SOR.Networking.Abstractions/
EventBus/
IEventBus.cs
EventSubscriptionOptions.cs
DeliverySemantics.cs
Messaging/
IMessageDispatcher.cs
IMessageHandler.cs
IMessageSerializer.cs
Push/
IClientPush.cs
ClientPushResult.cs
Rpc/
RpcSubjects.cs
RemoteDispatchOptions.cs
Transport/
ITransport.cs
IClientConnection.cs
TransportLimits.cs
Server/src/SOR.Networking.WebSocket/
Configuration/
WebSocketTransportOptions.cs
WebSocketTransportOptionsValidator.cs
Transport/
WebSocketTransport.cs
WebSocketClientConnection.cs
Health/
WebSocketTransportHealthCheck.cs
Metrics/
WebSocketMetrics.cs
Server/src/SOR.Networking.Nats/
Configuration/
NatsMessagingOptions.cs
NatsMessagingOptionsValidator.cs
EventBus/
NatsEventBus.cs
Rpc/
NatsMessageRpcResponder.cs
Health/
NatsHealthCheck.cs
Metrics/
NatsMetrics.cs
Server/src/SOR.Networking.Redis/
Configuration/
RedisPushOptions.cs
RedisPushOptionsValidator.cs
Push/
RedisClientPush.cs
Health/
RedisHealthCheck.cs
Metrics/
RedisPushMetrics.cs
```
## 12-Factor Assessment
### 1. Codebase
Status: mostly aligned.
Keep `SOR.Networking` as shared infrastructure code, not a deployable process. The process boundary remains `SOR.Host` and role selection remains driven by `ENABLED_SERVICES`.
Plan:
- Keep abstractions and provider implementations in separate projects.
- Move duplicated NATS RPC subject/queue naming into one shared helper.
- Keep Gateway-specific Redis subscription behavior in `SOR.Gateway`, but document the full push contract in Networking.
- Add networking contract tests that can run without service modules.
### 2. Dependencies
Status: mostly aligned.
Provider dependencies are isolated: NATS packages stay in `SOR.Networking.Nats`, Redis packages stay in `SOR.Networking.Redis`, and ASP.NET Core WebSocket types stay in `SOR.Networking.WebSocket`.
Plan:
- Keep provider packages out of `SOR.Networking.Abstractions`.
- Add test projects per provider where integration dependencies are needed.
- Avoid introducing direct references from service modules to provider-specific networking projects.
### 3. Config
Status: partially aligned.
Config is environment-compatible through `SOR.Host`, but provider options are incomplete and not validated.
Plan:
- Add validators for `WebSocketTransportOptions`, `NatsMessagingOptions`, and `RedisPushOptions`.
- Reconcile config drift around `AuthTimeoutMs` and `MaxMessagesPerSecond`; either move them to Gateway options or define them in transport options if transport owns them.
- Promote NATS RPC timeout, queue group prefix, subject prefix, and listener restart policy into typed options.
- Promote WebSocket accept backlog, max active connections, send timeout, ping interval, and max payload size into typed options.
- Promote Redis push channel prefix and metrics behavior into typed options.
- Fail fast on invalid or missing production config.
### 4. Backing Services
Status: aligned in concept, incomplete operationally.
Redis and NATS are attached backing services. They should be replaceable by changing config and provider registration, not changing business services.
Plan:
- Add Redis and NATS health checks that can be included in readiness.
- Separate liveness from readiness: liveness checks process health, readiness checks broker connectivity.
- Document Redis Pub/Sub as best-effort push, not durable state.
- Document core NATS as at-most-once eventing, and define when JetStream is required.
### 5. Build, Release, Run
Status: mostly aligned.
Networking projects are library code loaded by the host at runtime.
Plan:
- Keep build artifacts environment-neutral.
- Keep provider selection and provider URLs in config.
- Add startup validation so bad broker URLs, invalid WebSocket limits, or missing options fail during release/run startup rather than at first message.
### 6. Processes
Status: mostly aligned.
The networking modules keep connection/process state but do not own durable application state. WebSocket connections are inherently process-local; Redis and NATS externalize cross-process communication.
Plan:
- Treat WebSocket connections as disposable process state.
- Treat Redis/NATS as the only cross-process communication boundary.
- Keep user/game/session state outside Networking.
- Make offline reconnect behavior rely on persistent service state and client sync, not push replay.
### 7. Port Binding
Status: aligned through `SOR.Host`.
Networking libraries do not bind ports directly. `SOR.Host` owns Kestrel, HTTP, gRPC, and WebSocket upgrade configuration.
Plan:
- Keep WebSocket path and Kestrel behavior in host-level config.
- Keep transport registration behind `AddWebSocketTransport`.
- Ensure gateway-only WebSocket registration remains role-gated by `ENABLED_SERVICES`.
### 8. Concurrency
Status: partially aligned.
The code uses async APIs, channels, and cancellation, but overload behavior is not explicit.
Plan:
- Replace the unbounded WebSocket accept channel with a bounded channel and a configured full-mode policy.
- Add metrics for pending accepts, active connections, rejected upgrades, receive payload size, send latency, and disconnect reason.
- Add per-connection send timeout and max outbound message size.
- Make NATS subscription type explicit: fan-out subscription vs queue-group subscription.
- Add listener restart policy or process-fatal behavior for unexpected NATS RPC listener exits.
- Add tests for duplicate handler registration and RPC queue group distribution.
### 9. Disposability
Status: partially aligned.
Cancellation is present, but shutdown and drain behavior should be more explicit.
Plan:
- On shutdown, stop accepting new WebSocket upgrades before waiting for active connections.
- Add a configured graceful connection drain timeout.
- Ensure pending accepts are completed/cancelled cleanly.
- Ensure NATS RPC subscriptions stop cleanly and report listener shutdown.
- Ensure Redis push publishes fail fast when Redis is unavailable rather than blocking request paths indefinitely.
- Add integration tests for shutdown cancellation in WebSocket, NATS responder, and Redis push.
### 10. Dev/Prod Parity
Status: partially aligned.
The host uses local default Redis/NATS config, but parity depends on developers running equivalent backing services.
Plan:
- Provide a local compose profile for Redis and NATS.
- Keep local broker behavior close to production defaults.
- Add a smoke-test command that verifies WebSocket upgrade, NATS publish/subscribe, NATS RPC, and Redis push publish.
- Avoid hidden in-memory fallbacks in production service registration.
### 11. Logs
Status: partially aligned.
Logging exists, but operational signals need to be structured and measurable.
Plan:
- Add structured fields for transport name, connection ID, user ID, subject, queue group, channel, message type, subscriber count, payload size, latency, and failure reason.
- Add counters for WebSocket accepted/rejected/closed, NATS publish/subscribe failures, RPC requests/errors/timeouts, and Redis push subscriber counts.
- Keep logs on stdout/stderr through host logging.
- Avoid logging payload bodies unless a redaction policy exists.
### 12. Admin Processes
Status: early.
Networking has no explicit one-off diagnostics or repair commands.
Plan:
- Add broker diagnostics that can run as admin commands or smoke-test jobs.
- Add a handler registry dump for NATS RPC responder startup.
- Add an optional subject/channel inventory command for known `NatsSubjects`, RPC subjects, and Redis keys.
- If durable messaging is introduced later, add replay/dead-letter admin tooling at that time.
## Refactor Phases
### Phase 0: Baseline Contracts
- Add tests for `IMessageSerializer` wire compatibility across WebSocket, Redis push, and NATS RPC payloads.
- Add tests for WebSocket max message size handling.
- Add tests for duplicate `IMessageHandler` detection in `NatsMessageRpcResponder`.
- Add tests for Redis push channel naming.
- Add tests that Gateway and responder compute the same RPC subject/queue names.
### Phase 1: Configuration Cleanup
- Add typed option classes for NATS messaging and Redis push.
- Add `IValidateOptions<T>` validators for WebSocket, NATS, and Redis options.
- Resolve `WebSocket` config drift by moving auth/rate-limit options to Gateway or implementing them in transport.
- Add startup validation for required broker URLs and limits.
### Phase 2: Backpressure and Limits
- Replace unbounded pending WebSocket accepts with bounded channel config.
- Add `MaxActiveConnections`.
- Add explicit reject behavior for overload.
- Add send timeout and optional max outbound payload size.
- Add metrics for pending accepts and rejected upgrades.
### Phase 3: Subject and Channel Contracts
- Centralize NATS RPC subject and queue naming in shared code.
- Keep event subjects in `NatsSubjects`.
- Keep Redis push channel names in `RedisKeys`.
- Add tests that prevent accidental naming drift across Gateway, responder, and publishers.
### Phase 4: Broker Hardening
- Add NATS health check.
- Add Redis health check.
- Add NATS RPC listener restart/fatal policy.
- Add explicit subscription options for fan-out vs queue-group consumption.
- Define when core NATS is sufficient and when JetStream is required.
### Phase 5: Observability
- Add metrics wrappers around WebSocket accepts/sends/receives.
- Add NATS publish, subscribe, and RPC metrics.
- Add Redis push metrics including subscriber count.
- Add structured logging fields across transport, push, event bus, and RPC.
### Phase 6: Disposability
- Add graceful WebSocket drain behavior.
- Add tests for cancellation and shutdown paths.
- Ensure NATS and Redis dependencies fail quickly when unavailable.
- Add readiness checks that remove the process from traffic before shutdown drains active work.
### Phase 7: Dev/Prod Parity and Runbooks
- Add local broker startup instructions.
- Add smoke tests for WebSocket, Redis, NATS event bus, and NATS RPC.
- Document expected production env vars.
- Document operational delivery semantics for events, RPC, and push.
## Immediate Next Steps
1. Add `WebSocketTransportOptionsValidator` and reconcile unused WebSocket config keys.
2. Centralize RPC subject/queue naming used by Gateway and `NatsMessageRpcResponder`.
3. Add Redis/NATS readiness checks and wire them into host readiness.
4. Add metrics for Redis push subscriber count and NATS RPC handler latency.
5. Replace the WebSocket accept queue with a bounded, configurable channel.
## Definition of Done
- All networking provider options are typed, validated, and environment-overridable.
- WebSocket overload behavior is bounded and observable.
- Redis, NATS, and WebSocket readiness/health behavior is explicit.
- Event, push, and RPC delivery semantics are documented in interfaces and runbooks.
- NATS RPC naming cannot drift between Gateway and responder.
- Integration tests cover WebSocket frame limits, NATS event publish/subscribe, NATS RPC, Redis push publish, and shutdown cancellation.
- No service module directly depends on concrete provider implementations.
@@ -385,6 +385,16 @@
@bind="action.All" @bind:after="Compile" />
<label class="form-check-label small" for="all_@(idx)_@(actionIdx)">All</label>
</div>
@if (!action.All)
{
<div class="form-check">
<input type="checkbox" class="form-check-input"
id="upto_@(idx)_@(actionIdx)"
@bind="action.UpTo" @bind:after="Compile"
title="Player may select fewer than N targets" />
<label class="form-check-label small" for="upto_@(idx)_@(actionIdx)">Up&nbsp;to</label>
</div>
}
</div>
</div>
<!-- Target filter (optional, single filter, no-param types) -->
@@ -2164,7 +2174,9 @@
private static readonly string[] DirectionValues = ["North", "South", "East", "West", "NorthEast", "NorthWest", "SouthEast", "SouthWest"];
private static readonly string[] ComparatorValues = ["Equal", "NotEqual", "LessThan", "LessThanOrEqual", "GreaterThan", "GreaterThanOrEqual"];
private static readonly string[] DurationTypeValues = ["Instant", "UntilEndOfTurn", "UntilStartOfOwnerTurn", "UntilStartOfSourceOwnerTurn", "ForNTurns", "UntilEndOfSequence", "WhileSourceOnBattlefield", "PermanentInMatch"];
private static readonly string[] StatTargetValues = ["Current", "Base", "Max"];
// "Base" removed — the engine's StatTarget enum only has Current | Max, and an
// unknown value makes the whole card's AbilitiesJson fail deserialization.
private static readonly string[] StatTargetValues = ["Current", "Max"];
private static readonly string[] StatValues = ["Damage", "Defense", "Health", "MP"];
private static readonly string[] PositionValues = ["Top", "Bottom"];
private static readonly string[] PlayerValues = ["Owner", "Opponent", "Both", "Any"];
@@ -2197,19 +2209,23 @@
"DealDamageToOwnArchSpirit", "DealDamageToOwnSpirit",
];
// Only triggers the engine actually fires AND matches are listed here.
// NOT yet implemented server-side (do not re-add without engine support —
// see SOR.Abilities-Review-and-solutions.md §C3):
// OnUnitMPSpent, OnStatModified, OnAbilityAdded, OnAbilityRemoved, OnGenusChanged,
// OnTileAffinityChanged, OnCardDiscarded, OnCardReturnedToHand, OnCardReturnedToDeck,
// OnDeckShuffled, OnCardsRevealed, OnTargetedByAbility, OnEffectApplied
private static readonly string[] TriggerTypesList = [
"OnTurnStart", "OnTurnEnd",
"OnChanneled", "OnAscend", "OnTransition",
"OnUnitMove", "OnUnitAttack", "OnUnitAbilityActivated", "OnUnitMPSpent",
"OnUnitMove", "OnUnitAttack", "OnUnitAbilityActivated",
"OnDamageDealt", "OnDamagePrevented", "OnHealed", "BeforeDamageApplied", "BeforeUnitDeath",
"OnUnitEnterBattlefield", "OnUnitLeaveBattlefield", "OnUnitDeath",
"OnUnitSentToDiscard", "OnSpiritSacrificed", "OnTokenSummoned",
"OnStatModified", "OnAbilityAdded", "OnAbilityRemoved", "OnGenusChanged",
"OnRuinActivation", "OnUnitOccupyRuin", "OnTileAffinityChanged",
"OnRuinActivation", "OnUnitOccupyRuin",
"OnSPGained", "OnSPSpent", "OnSTGained", "OnSTSpent",
"OnCardDrawn", "OnCardDiscarded", "OnCardReturnedToHand", "OnCardReturnedToDeck",
"OnDeckShuffled", "OnCardsRevealed",
"OnTargetedByAbility", "OnEffectApplied", "OnEnterAuraRange", "OnLeaveAuraRange",
"OnCardDrawn",
"OnEnterAuraRange", "OnLeaveAuraRange",
];
// ── Effect groups ────────────────────────────────────────────────────────────
@@ -2219,10 +2235,11 @@
private static readonly EffectGroup[] EffectGroups =
[
new("Damage & Healing", ["DealDamage", "Heal", "DealDamageToSelf", "DOT", "HOT", "PreventDeath", "PreventNextDamage", "SetHealthMinimum"]),
// "SetStatModMultiplier" removed — no engine implementation (silent no-op).
new("Stat Modification", ["ModifyHealth", "ModifyDefense", "ModifyDamage", "ModifyMP",
"GrantAdditionalAttack", "SetAttackRange",
"ModifyMinAttackRange", "ModifyMaxAttackRange",
"SetMovementType", "ModifyCost", "SetStatModMultiplier"]),
"SetMovementType", "ModifyCost"]),
new("Player Resources", ["ModifySP", "ModifyST", "ModifyCardsDrawnPerTurn", "ModifySPAccumulation"]),
new("Unit Flags", ["SetCanMove", "SetCanAttack", "SetCanDefend", "SetCanBeAttacked",
"SetCanBeBlocked", "SetCanBeObstructed", "SetCanUseAbility", "SetCanBeSacrificed"]),
@@ -2230,15 +2247,17 @@
"SetCanSacrificeSpirit", "SetCanAscendArchSpirit", "SetCanTransitionArchSpirit",
"SetCanChannelRepentance", "SetCanChannelInstinct", "SetCanChannelRuin",
"SetCanChannelTerramorphaMono", "SetCanChannelTerramorphaDi", "SetCanChannelTerramorphaTri"]),
// "ChannelCard" removed — no engine implementation; use ChannelCardFromZone instead.
new("Zone Operations", ["DrawCards", "DiscardCards", "ReturnToHand", "ReturnToDeck", "SendToDiscard",
"ShuffleDeck", "ReturnToBattlefield", "SearchDeck", "RevealCards",
"PlaceOnDeck", "ChannelCard"]),
"PlaceOnDeck"]),
new("Genus & Affinity", ["AddGenus", "RemoveGenus", "SetAffinity",
"SetBaseAffinity1", "SetBaseAffinity2", "PushAffinity", "PushFinalAffinity"]),
new("Ability Mgmt", ["AddAbility", "RemoveAbility", "EnableAbility", "DisableAbility"]),
new("Displacement", ["PushUnit", "PullUnit", "DisplaceUnit", "RepositionUnit"]),
new("Control", ["TakeControl", "GrantMovementControl", "SetFixedSacrificeReturn", "SkipTurn"]),
new("Token & Deferred", ["SummonToken", "CloneSpiritAsToken", "DestroyToken", "ModifySacrificeTokenReturn", "ApplyOnEvent"]),
// "ModifySacrificeTokenReturn" removed — no engine implementation; use SetFixedSacrificeReturn.
new("Token & Deferred", ["SummonToken", "CloneSpiritAsToken", "DestroyToken", "ApplyOnEvent"]),
new("ArchSpirit Ops", ["AscendFromZone", "TransitionFromZone", "ModifyChannelRange"]),
new("Ruin Ops", ["RelocateRuin", "ActivateRuinAbility", "DisableRuinForDuration"]),
new("Channeling", ["ChannelCardFromZone"]),
@@ -2549,6 +2568,8 @@
else if (_amountStatTypes.Contains(typeKey))
{
ReadValueExpr("Amount"); d.StatTarget = ReadStr("StatTarget", "Current");
// Legacy "Base" doesn't exist in the engine enum — heal on load.
if (d.StatTarget == "Base") d.StatTarget = "Current";
}
else if (_amountOnlyTypes.Contains(typeKey))
{
@@ -2723,6 +2744,7 @@
Chooser = target?["Chooser"]?.GetValue<string>() ?? "Self",
Count = target?["Count"]?["N"]?.GetValue<int>() ?? 1,
All = target?["Count"]?["All"]?.GetValue<bool>() ?? false,
UpTo = target?["Count"]?["UpTo"]?.GetValue<bool>() ?? false,
FilterType = firstFilter?["$type"]?.GetValue<string>() ?? "",
};
if (actionNode["Duration"] is JsonObject actionDur)
@@ -2888,7 +2910,7 @@
["Count"] = new JsonObject
{
["N"] = action.All ? 1 : action.Count,
["UpTo"] = false,
["UpTo"] = !action.All && action.UpTo,
["All"] = action.All,
},
};
@@ -4562,6 +4584,8 @@
public string Chooser { get; set; } = "Self";
public int Count { get; set; } = 1;
public bool All { get; set; }
/// <summary>Player may select fewer than Count valid targets.</summary>
public bool UpTo { get; set; }
/// <summary>
/// Optional filter type applied to the target pool (single filter, no-param variant).
/// "" = no filter. Maps to Target.Filters[0] in the compiled JSON.
@@ -75,6 +75,9 @@ public sealed class TriggerEventData
public Coord? PreviousTile { get; init; }
/// <summary>For movement events: destination tile coordinate.</summary>
public Coord? DestinationTile { get; init; }
/// <summary>For damage events: "HP" | "Defense". Null = unspecified (matches "Any" only).</summary>
public string? DamageType { get; init; }
}
/// <summary>
@@ -92,6 +95,8 @@ public enum TriggerEventKind
UnitAttack,
UnitAbilityActivated,
DamageDealt,
Healed,
TokenSummoned,
DamagePrevented,
BeforeDamageApplied,
BeforeUnitDeath,
File diff suppressed because it is too large Load Diff
+79 -6
View File
@@ -238,6 +238,14 @@ public static class GameEngine
}
}
foreach (var card in drawn)
AbilitySystem.FireTrigger(state, new TriggerOccurrence
{
Kind = TriggerEventKind.CardDrawn,
ActorId = actorId,
Data = new TriggerEventData { TargetId = card.InstanceId },
});
if (state.Phase == GamePhase.Draw)
state.Phase = GamePhase.Main;
@@ -337,6 +345,7 @@ public static class GameEngine
player.Hand.Remove(card);
player.CurrentSp -= card.SpCost;
player.CurrentSt -= card.StCost;
FireResourceSpent(state, player, card.SpCost, card.StCost);
var field = ToFieldCard(card, coord);
player.Field.Add(field);
@@ -392,6 +401,7 @@ public static class GameEngine
player.Hand.Remove(card);
player.CurrentSp -= card.SpCost;
player.CurrentSt -= card.StCost;
FireResourceSpent(state, player, card.SpCost, card.StCost);
// Push card affinity to each targeted tile.
if (Enum.TryParse<Affinity>(card.Affinity, out var affinity))
@@ -425,6 +435,7 @@ public static class GameEngine
player.Hand.Remove(card);
player.CurrentSp -= card.SpCost;
player.CurrentSt -= card.StCost;
FireResourceSpent(state, player, card.SpCost, card.StCost);
var ruinField = ToFieldCard(card, ruinCoord);
player.Field.Add(ruinField);
@@ -440,20 +451,24 @@ public static class GameEngine
}
else
{
// Repentance, Instinct — pay cost, fire AbilitiesJson active abilities, then discard.
// Repentance, Instinct — pay cost, move to discard FIRST, then fire the
// AbilitiesJson active abilities. Discarding first keeps the card in a stable
// zone so any interactive pause (target pick, OR-group pick, StackDeck…) can
// re-find it as the ability source on resume (AbilitySystem.FindUnitAnywhere).
player.Hand.Remove(card);
player.CurrentSp -= card.SpCost;
player.CurrentSt -= card.StCost;
FireResourceSpent(state, player, card.SpCost, card.StCost);
player.Discard.Add(card);
AbilitySystem.FireCardEffects(state, actorId, card, cardTargets);
player.Discard.Add(card);
AbilitySystem.FireTrigger(state, new TriggerOccurrence
{
Kind = TriggerEventKind.Channeled,
ActorId = actorId,
CardType = card.CardType,
Data = new TriggerEventData { SourceId = card.InstanceId },
});
}
@@ -499,6 +514,7 @@ public static class GameEngine
if (player.CurrentSt < incoming.StCost) throw new GameException("INSUFFICIENT_ST");
player.CurrentSp -= incoming.SpCost;
player.CurrentSt -= incoming.StCost;
FireResourceSpent(state, player, incoming.SpCost, incoming.StCost);
// Remove incoming from its zone.
RemoveFromAnyZone(player, incoming);
@@ -561,6 +577,7 @@ public static class GameEngine
if (player.CurrentSt < incoming.StCost) throw new GameException("INSUFFICIENT_ST");
player.CurrentSp -= incoming.SpCost;
player.CurrentSt -= incoming.StCost;
FireResourceSpent(state, player, incoming.SpCost, incoming.StCost);
player.Hand.Remove(incoming);
@@ -779,7 +796,8 @@ public static class GameEngine
// Attacker hits target.
Console.WriteLine($"[GameEngine.Attack] attacker damage begin amount={attacker.Damage ?? 0} targetBefore={UnitSummary(target)}");
ApplyDamage(target, attacker.Damage ?? 0);
var hitHp = ApplyDamage(target, attacker.Damage ?? 0);
FireDamageDealt(state, actorId, attacker, target, attacker.Damage ?? 0, hitHp);
Console.WriteLine($"[GameEngine.Attack] attacker damage end targetAfter={UnitSummary(target)}");
// Target counter-attacks if able and still alive.
@@ -809,7 +827,8 @@ public static class GameEngine
if (canCounterAttack)
{
Console.WriteLine($"[GameEngine.Attack] counter damage begin amount={target.Damage ?? 0} attackerBefore={UnitSummary(attacker)}");
ApplyDamage(attacker, target.Damage ?? 0);
var counterHp = ApplyDamage(attacker, target.Damage ?? 0);
FireDamageDealt(state, opponentId, target, attacker, target.Damage ?? 0, counterHp);
Console.WriteLine($"[GameEngine.Attack] counter damage end attackerAfter={UnitSummary(attacker)}");
}
}
@@ -1048,9 +1067,17 @@ public static class GameEngine
if (next.ArchSpirit.MaxDefense.HasValue) next.ArchSpirit.CurrentDefense = next.ArchSpirit.MaxDefense;
}
int spBefore = next.CurrentSp;
next.CurrentSp += rules.SpAccumulationPerTurn + next.SpAccumulationBonus;
if (rules.SpHasCap && next.CurrentSp > rules.SpCap)
next.CurrentSp = rules.SpCap;
if (next.CurrentSp > spBefore)
AbilitySystem.FireTrigger(state, new TriggerOccurrence
{
Kind = TriggerEventKind.SPGained,
ActorId = next.AccountId,
Data = new TriggerEventData { Amount = next.CurrentSp - spBefore, TargetId = next.AccountId },
});
state.Phase = GamePhase.Draw;
@@ -1447,20 +1474,66 @@ public static class GameEngine
}
}
private static void ApplyDamage(CardInstance target, int damage)
/// <summary>Applies combat damage (defense soaks first). Returns the HP portion actually dealt.</summary>
private static int ApplyDamage(CardInstance target, int damage)
{
int hpDealt = 0;
if (target.CurrentDefense > 0)
{
var defVal = target.CurrentDefense.GetValueOrDefault();
var overflow = damage - defVal;
target.CurrentDefense = Math.Max(0, defVal - damage);
if (overflow > 0 && target.CurrentHealth.HasValue)
{
hpDealt = Math.Min(overflow, target.CurrentHealth.Value);
target.CurrentHealth = Math.Max(0, target.CurrentHealth.Value - overflow);
}
}
else if (target.CurrentHealth.HasValue)
{
hpDealt = Math.Min(damage, target.CurrentHealth.Value);
target.CurrentHealth = Math.Max(0, target.CurrentHealth.Value - damage);
}
return hpDealt;
}
/// <summary>Fires OnSPSpent / OnSTSpent for an engine-side resource payment.</summary>
private static void FireResourceSpent(GameState state, PlayerState player, int sp, int st)
{
if (sp > 0)
AbilitySystem.FireTrigger(state, new TriggerOccurrence
{
Kind = TriggerEventKind.SPSpent,
ActorId = player.AccountId,
Data = new TriggerEventData { Amount = sp, TargetId = player.AccountId },
});
if (st > 0)
AbilitySystem.FireTrigger(state, new TriggerOccurrence
{
Kind = TriggerEventKind.STSpent,
ActorId = player.AccountId,
Data = new TriggerEventData { Amount = st, TargetId = player.AccountId },
});
}
/// <summary>Fires the OnDamageDealt trigger for a combat hit.</summary>
private static void FireDamageDealt(
GameState state, string actorId, CardInstance source, CardInstance target, int amount, int hpDealt)
{
if (amount <= 0) return;
AbilitySystem.FireTrigger(state, new TriggerOccurrence
{
Kind = TriggerEventKind.DamageDealt,
ActorId = actorId,
UnitType = target.CardType,
Data = new TriggerEventData
{
SourceId = source.InstanceId,
TargetId = target.InstanceId,
Amount = amount,
DamageType = hpDealt > 0 ? "HP" : "Defense",
},
});
}
private static void MoveToDiscard(PlayerState player, FieldCard card)
+34
View File
@@ -55,6 +55,28 @@ public sealed class GameState
/// </summary>
public List<ActiveEffect> ActiveEffects { get; set; } = new();
// ── Ability runtime state ─────────────────────────────────────────────────
// Formerly static fields on AbilitySystem. Kept on the state so they are
// per-game, serialize with StateJson, and roll back when a handler fails.
/// <summary>Active PreventNextDamage shields: unit InstanceId → remaining absorb cap (null = unlimited).</summary>
public Dictionary<string, int?> PreventNextDamageByUnit { get; set; } = new();
/// <summary>Active PreventDeath markers, keyed by unit InstanceId.</summary>
public Dictionary<string, PreventDeathMarker> PreventDeathMarkers { get; set; } = new();
/// <summary>Triggered-ability uses this turn, keyed "instanceId:abilityKey:turnNumber". Pruned at turn start.</summary>
public Dictionary<string, int> TriggerUsesThisTurn { get; set; } = new();
/// <summary>Triggered-ability uses for the whole game, keyed "instanceId:abilityKey".</summary>
public Dictionary<string, int> TriggerUsesThisGame { get; set; } = new();
/// <summary>
/// Current top-level ability resolution depth (UntilEndOfSequence bookkeeping).
/// Always returns to 0 by the end of each handler invocation.
/// </summary>
public int SequenceDepth { get; set; }
// ── Multi-player helpers ──────────────────────────────────────────────────
/// <summary>Seat IDs in order, skipping eliminated players.</summary>
@@ -169,6 +191,18 @@ public sealed class GameState
PendingTargetPick is not null;
}
/// <summary>
/// Options captured from a <c>PreventDeathEffect</c> when it is applied to a unit.
/// Consumed the first time the unit would die (or take lethal damage, for DamageIgnored).
/// </summary>
public sealed class PreventDeathMarker
{
/// <summary>After preventing death, set the unit's HP to this value. Null = 1.</summary>
public int? DamageTakenSetToHp { get; set; }
/// <summary>When true, the lethal hit's damage is fully ignored (unit takes 0).</summary>
public bool DamageIgnored { get; set; }
}
public sealed class PlayerState
{
public string AccountId { get; set; } = string.Empty;
@@ -404,13 +404,12 @@ internal abstract class GameHandlerBase
{
if (state.PendingTriggeredTarget is { } pending)
{
var firstClientPickAction = JsonSerializer
.Deserialize<Abilities.Models.Action[]>(pending.ActionsJson, AbilityJsonOptions)
?.FirstOrDefault(AbilitySystem.ActionNeedsClientTargets_Public);
var actionJson = firstClientPickAction is not null
? JsonSerializer.Serialize(firstClientPickAction, AbilityJsonOptions)
: pending.ActionsJson;
// Send the FULL action array. ResumeTriggeredAbility replays the whole array
// with original action indices, so the client must walk every action
// (auto-skipping server-resolved ones) and submit targets with matching
// indices. Sending only the first pick action broke any triggered ability
// whose pick action was not at index 0.
var actionJson = pending.ActionsJson;
var targetPlayer = string.IsNullOrEmpty(pending.ChooserActorId)
? pending.ActorId
+137
View File
@@ -0,0 +1,137 @@
Implementation notes for repentance placeholder VFX.
Server Work
Add a visual-only broadcast when a Repentance successfully resolves.
Relevant files:
GameEngine.cs (line 260)
GamePlayCardHandler.cs (line 12)
GameMessages.cs (line 258)
AbilityDefinition.cs (line 125)
AbilityAnimationDefinition.cs (line 34)
Needed server pieces:
Add a new push DTO, for example RepentancePlaceholderVisualPush.
Payload should include:
eventId
sessionId
actorAccountId
sourceArchSpiritInstanceId
cardInstanceId
cardDefinitionId
cardName
affinity
targets
hasCustomAnimation
Detect successful Repentance resolution in game.play_card.
After GameEngine.PlayCard(...) succeeds and before/after state push, check:
card type was Repentance
card ability has no animation metadata, or animation metadata has no usable AssetUrl
Broadcast a visual-only push to all viewers.
Message type could be:
game.visual.repentance_placeholder
Send to:
acting player
opponent/all game players
spectators
Do not store this in GameState.
This is not gameplay state. It should be transient, like a sound or animation cue.
Target payload should reuse the same AbilityTarget shape where possible.
That keeps the client able to resolve:
unit target
tile target
player target fallback
targetless fallback
Client Work
Listen for the visual push and play a placeholder projectile from the acting player’s ArchSpirit to the target.
Relevant files:
Game.gd (line 796)
game_screen.gd (line 384)
game_screen.gd (line 1006)
board_controller.gd (line 321)
game_constants.gd (line 5)
Needed client pieces:
Add a signal in Game.gd.
Example:
signal repentance_placeholder_visual(payload: Dictionary)
Handle the new push message in Game.gd.
In the push router, add:
"game.visual.repentance_placeholder":
repentance_placeholder_visual.emit(payload as Dictionary)
Connect the signal in game_screen.gd.
The game screen should route the event to a dedicated VFX helper, not absorb a large amount of new effect code directly.
Add a focused VFX component.
Suggested path:
Client/origin-client/scenes/game/components/effects/repentance_placeholder_fx.gd
Responsibilities:
resolve ArchSpirit source world position
resolve target world position
spawn projectile
tween projectile to target
spawn impact particles
clean itself up
Color rules.
Use:
player/team color from state.teamColors
repentance affinity color from GameConstants.AFFINITY_COLORS
Suggested visual split:
projectile core: affinity color
trail/sparks: player color
impact ring: mix of both
Target resolution rules.
Resolve in this order:
target unit instance id to its current board position
target tile coordinate
target player ArchSpirit position
fallback to source ArchSpirit position
Animation timing.
Suggested defaults:
projectile duration: 0.35s to 0.8s, based on distance
impact duration: 0.5s to 0.8s
cleanup after around 1.2s
Future ability animation compatibility.
The client should ignore the placeholder if the server says hasCustomAnimation == true.
Later, active ability VFX can reuse the same visual event pattern with a broader message like:
game.visual.ability
Recommended Order
Add server DTO and push message.
Emit the push from successful Repentance channeling.
Add Game.gd signal and push routing.
Add placeholder VFX component.
Wire game_screen.gd to invoke it.
Test actor, opponent, and spectator views.
+26
View File
@@ -0,0 +1,26 @@
import io, sys
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")
path = 'C:/GameDev/SOR/Client/origin-client/scenes/game/components/units/unit_mesh_builder.gd'
src = open(path, "r", encoding="utf-8").read()
pairs = [
('var _active_tweens: Array[Tween] = [] # shader tweens tracked for kill-on-rebuild\n',
'var _active_tweens: Array[Tween] = [] # shader tweens tracked for kill-on-rebuild\n\nconst _MAX_POOL_PER_TYPE := 6 # overflow beyond this is freed immediately\nvar _unit_pool: Dictionary = {} # card_type (String) -> Array[StaticBody3D]\nvar _pool_root: Node3D = null\n'),
('# ── Incremental rebuild ───────────────────────────────────────────────────────\n\n## Incremental diff:',
'# ── Unit pool ───────────────────────────────────────────────────────────────────\n\nfunc _ready() -> void:\n\t_pool_root = Node3D.new()\n\t_pool_root.name = "UnitPool"\n\t_pool_root.visible = false\n\tadd_child(_pool_root)\n\n\n## Retire a unit body to the pool instead of freeing it.\n## MeshInstance3D children are freed immediately (releases mesh + material refs).\n## If the per-type pool is full the body is freed immediately to cap memory.\nfunc _pool_unit(body: StaticBody3D, card_type: String) -> void:\n\tif not is_instance_valid(body):\n\t\treturn\n\tfor child: Node in body.get_children():\n\t\tif child is MeshInstance3D:\n\t\t\tchild.free()\n\tbody.visible = false\n\tbody.reparent(_pool_root, false)\n\tif not _unit_pool.has(card_type):\n\t\t_unit_pool[card_type] = []\n\tvar pool: Array = _unit_pool[card_type]\n\tif pool.size() >= _MAX_POOL_PER_TYPE:\n\t\tbody.free()\n\telse:\n\t\tpool.append(body)\n\n\n## Pop a body from the per-type pool and fully reset it for reuse.\n## Returns null if the pool is empty (caller should allocate fresh).\nfunc _acquire_from_pool(card_type: String) -> StaticBody3D:\n\tif not _unit_pool.has(card_type):\n\t\treturn null\n\tvar pool: Array = _unit_pool[card_type]\n\tif pool.is_empty():\n\t\treturn null\n\tvar body: StaticBody3D = pool.pop_back()\n\tif not is_instance_valid(body):\n\t\treturn null\n\tbody.position = Vector3.ZERO\n\tbody.rotation = Vector3.ZERO\n\tbody.scale = Vector3.ONE\n\tbody.collision_layer = 1\n\tbody.collision_mask = 1\n\tfor group: String in body.get_groups():\n\t\tbody.remove_from_group(group)\n\tfor key: String in body.get_meta_list():\n\t\tif key not in ["unit_id", "owner_id", "card_type", "team_color", "above_tile"]:\n\t\t\tbody.remove_meta(key)\n\tbody.reparent(units_root, false)\n\tbody.visible = true\n\treturn body\n\n\n# ── Incremental rebuild ───────────────────────────────────────────────────────\n\n## Incremental diff:'),
('\t\t\telse:\n\t\t\t\tbody.queue_free()\n',
'\t\t\telse:\n\t\t\t\t_pool_unit(body, card_type)\n'),
('\tvar body: StaticBody3D = StaticBody3D.new()\n\tbody.set_meta("unit_id", iid)\n\tbody.set_meta("owner_id", owner_id)\n\tbody.set_meta("card_type", card_type)\n\tbody.set_meta("team_color", team_color)\n\tif not owner_id.is_empty():\n\t\tunit_owner_ids[iid] = owner_id\n\n\tvar shape: CollisionShape3D = CollisionShape3D.new()\n\tvar mi: MeshInstance3D = MeshInstance3D.new()\n',
'\tvar _pool_hit := false\n\tvar body: StaticBody3D = _acquire_from_pool(card_type)\n\tvar shape: CollisionShape3D\n\tif body == null:\n\t\tbody = StaticBody3D.new()\n\t\tshape = CollisionShape3D.new()\n\telse:\n\t\t_pool_hit = true\n\t\tfor child in body.get_children():\n\t\t\tif child is CollisionShape3D:\n\t\t\t\tshape = child\n\t\t\t\tbreak\n\tbody.set_meta("unit_id", iid)\n\tbody.set_meta("owner_id", owner_id)\n\tbody.set_meta("card_type", card_type)\n\tbody.set_meta("team_color", team_color)\n\tif not owner_id.is_empty():\n\t\tunit_owner_ids[iid] = owner_id\n\tif OS.is_debug_build():\n\t\tvar pool_sizes := {}\n\t\tfor ct: String in _unit_pool:\n\t\t\tpool_sizes[ct] = _unit_pool[ct].size()\n\t\tprint("UnitMeshBuilder: add_unit iid=%s pool_hit=%s pools=%s" % [iid, _pool_hit, pool_sizes])\n\n\tvar mi: MeshInstance3D = MeshInstance3D.new()\n'),
('\tbody.add_child(shape)\n\tbody.add_child(mi)\n\tbody.set_meta("above_tile", above_tile)\n\tbody.position = wp + Vector3(0, tile_base + tile_h + above_tile, 0)\n\tunits_root.add_child(body)\n',
'\tif not _pool_hit:\n\t\tbody.add_child(shape)\n\tbody.add_child(mi)\n\tbody.set_meta("above_tile", above_tile)\n\tbody.position = wp + Vector3(0, tile_base + tile_h + above_tile, 0)\n\tif not _pool_hit:\n\t\tunits_root.add_child(body)\n'),
('func _exit_tree() -> void:\n\tfor t: Tween in _active_tweens:\n\t\tif is_instance_valid(t):\n\t\t\tt.kill()\n\t_active_tweens.clear()\n',
'func _exit_tree() -> void:\n\tfor t: Tween in _active_tweens:\n\t\tif is_instance_valid(t):\n\t\t\tt.kill()\n\t_active_tweens.clear()\n\tif is_instance_valid(_pool_root):\n\t\t_pool_root.free()\n\t_unit_pool.clear()\n'),
]
for i, (old, new) in enumerate(pairs, 1):
assert old in src, f"anchor {i} not found"
src = src.replace(old, new, 1)
print(f"step {i} done")
open(path, "w", encoding="utf-8").write(src)
print("All done, line count:", src.count(chr(10)))
+3
View File
@@ -0,0 +1,3 @@
with open("C:/GameDev/SOR/ios_crash_fix_draft_v2.md", "a", encoding="utf-8") as f:
f.write("### Fix 3 PLACEHOLDER\n")
print("ok")