diff --git a/Delta-Sync-flow.md b/Delta-Sync-flow.md index d065ea0..eb77b33 100644 --- a/Delta-Sync-flow.md +++ b/Delta-Sync-flow.md @@ -21,7 +21,7 @@ serialisation, transport, and final application on the client. 11. [Client -- Unit Merge (_merge_unit_delta)](#11-client----unit-merge-mergeunitdelta-) 12. [Fallback and Resync Paths](#12-fallback-and-resync-paths-) 13. [Design Invariants](#13-design-invariants-) -14. [Known Issues & Planned Fixes](#14-known-issues--planned-fixes) +14. [Fixes Applied](#14-fixes-applied) --- @@ -89,7 +89,7 @@ public sealed record GameStateDelta( |---|---|---| | `TileDelta` | 525-536 | Board coord + changed base1/base2/affinity/occupant/ruin. `OccupantCleared` and `RuinCleared` are explicit booleans to distinguish set-to-null from no-change. | | `UnitSnapshot` | 538-540 | Full `CardInstanceDto` with `OwnerAccountId` -- used for newly placed units. | -| `UnitDelta` | 542-561 | Partial unit update; nullable fields; `null` = unchanged. | +| `UnitDelta` | 542-561 | Partial unit update; nullable fields; `null` = unchanged. `Art2dUrl` and `ModelUrl` were removed — those fields belong only in `UnitSnapshot` (`CardInstanceDto`) and are stable for the lifetime of a card definition. | | `PublicCountsDelta` | 563-566 | Hand/deck/discard counts visible to opponents (not actual cards). | | `ArchSpiritUpdate` | 568-570 | Either a `Full` snapshot or a `Delta` -- server sends full on first sight, delta thereafter. | | `PrivateViewerDelta` | 572-575 | Own hand additions, removals by ID, discard additions. Never sent to opponents. | @@ -260,7 +260,9 @@ internal static async Task PushStateToPlayersAsync( ServerMessage.Push("game.state_delta", new GameStateDeltaPush(delta)), ct)); } - // Spectators always receive full public state, never a delta (lines 348-360) + // Spectators always receive full public state, never a delta (lines 348-360). + // Spectator IDs are fetched from a Redis Set (key: spectators:{sessionId}), + // so registration survives pod restarts and cross-pod load balancing. foreach (var specId in spectators) tasks.Add(clientPush.PushAsync(specId.ToString(), ServerMessage.Push("game.state_update", @@ -372,7 +374,7 @@ func _on_server_push(type: String, payload: Variant) -> void: if _state_version >= 0 and v > _state_version + 1: # line 747 print("[Game] WARN: missed delta (have %d, got %d) -- requesting full sync" % [_state_version, v]) - _fetch_state() # sends game.get_state request to server + _fetch_state() # guarded by _syncing flag; at most one in-flight request return _apply_delta(delta) # line 755 -- happy path ``` @@ -568,12 +570,11 @@ func _merge_unit_delta(unit: Dictionary, ud: Dictionary) -> void: unit["abilitiesJson"] = ud["abilitiesJson"] if ud.has("abilityUsesJson") and ud["abilityUsesJson"] != null: unit["abilityUsesJson"] = ud["abilityUsesJson"] - # art2dUrl / Art2dUrl and modelUrl / ModelUrl / modelurl all checked (capitalisation guard) - if ud.has("art2dUrl") and ud["art2dUrl"] != null: unit["art2dUrl"] = ud["art2dUrl"] - if ud.has("modelUrl") and ud["modelUrl"] != null: unit["modelUrl"] = ud["modelUrl"] ``` The `ud.has(k) and ud[k] != null` pattern distinguishes JSON `null` (no change) from a missing key. +`art2dUrl` and `modelUrl` are **not** merged here — they are stripped from `UnitDelta` on the server and only ever present in the initial `UnitSnapshot` (§2). They are applied once when the unit is added (§10 Section 2) and remain on the unit dict for the session. + --- ## 12. Fallback and Resync Paths @@ -583,9 +584,9 @@ The `ud.has(k) and ud[k] != null` pattern distinguishes JSON `null` (no change) | `prevStateJson == null` passed to handler | Full `game.state_update` pushed to all players (initial connect, reconnect, timer expiry). | | Any player's delta `IsEmpty()` | All players receive full `game.state_update` instead of deltas. In practice this should never fire: every turn-start regenerates MP for all units, meaning every player always has at least one stat change. If it does fire it indicates a diff bug, not a valid "no change" case. | | Spectator | Always receives full `game.state_update` (public DTO, no private data, no delta). | -| Client: `v <= _state_version` | Delta dropped -- acting player already received the new state in their ACK reply. | -| Client: `v > _state_version + 1` | Gap in sequence -- client calls `_fetch_state()` which sends `game.get_state`; server replies with full state. | -| Client: arch spirit `is_empty()` | Missing baseline -- client calls `request_sync()` for the same full-state recovery. | +| Client: `v <= _state_version` | Delta dropped — acting player already received the new state in their ACK reply. | +| Client: `v > _state_version + 1` | Gap in sequence — client calls `_fetch_state()`. A `_syncing` flag prevents multiple concurrent requests; subsequent gaps while a sync is in-flight are no-ops. `_apply_state_from_payload` validates the response `sessionId` before applying, discarding stale responses from a previous session. | +| Client: arch spirit `null` or missing baseline | `archSpirit` key may exist with a `null` value (player disconnect). An `is Dictionary` guard detects this; missing baseline triggers `request_sync()` for full-state recovery. | --- @@ -614,99 +615,115 @@ The `ud.has(k) and ud[k] != null` pattern distinguishes JSON `null` (no change) --- -## 14. Known Issues & Planned Fixes +## 14. Fixes Applied + +All six issues identified in the original audit have been implemented and committed. --- -### Issue 1 — Spectators miss updates: `SpectatorRegistryService` is in-memory per process (High) +### Fix 1 — Spectator registry moved to Redis (commit `14a467d`) -**Root cause:** `SpectatorRegistryService` (`SpectatorRegistryService.cs:11`) is registered as an in-memory singleton with a static `Instance` reference set in its constructor. Action handlers access it via `SpectatorRegistryService.Instance` (a static field). +**Was:** `SpectatorRegistryService` held an in-memory `ConcurrentDictionary` per server pod. +In a load-balanced deployment, `game.spectate` could land on pod A while the next action landed +on pod B — pod B's registry was empty, so spectator pushes were silently skipped. -In a horizontally scaled deployment (multiple server pods / load balancer), a spectator's `game.spectate` request is handled by pod A, which registers them in pod A's in-memory map. The next game action may be routed to pod B — pod B's `SpectatorRegistryService` has an empty map. `GetSpectators(sessionId)` returns empty, the spectator push is silently skipped. Only when the load balancer happens to route both the `game.spectate` and the subsequent action to the same pod does the spectator receive updates — explaining why leaving and rejoining several times eventually "works". +**Now:** `SpectatorRegistryService` uses Redis Sets (`spectators:{sessionId}`). +`RegisterAsync` → `SADD` with a 24-hour TTL; `UnregisterAsync` → `SREM`; +`GetSpectatorsAsync` → `SMEMBERS`; `RemoveSessionAsync` → `DEL`. +Spectator registration is now shared across all pods. -Additionally, even within a single pod: `Instance` is only set when the DI container first resolves `SpectatorRegistryService`, which happens lazily on the first request to `GameSpectateHandler`. If no spectator has ever called `game.spectate` since the pod started, `Instance` is null and `PushStateToPlayersAsync` silently skips the `if (registry != null)` guard. - -**Planned fix:** Move spectator registration into Redis (the same pub/sub layer already used for player pushes). Replace the in-memory `_map` with a Redis set keyed by `spectators:{sessionId}`. `Register`/`Unregister` become `SADD`/`SREM`; `GetSpectators` becomes `SMEMBERS`. This makes spectator state shared across all pods with no per-process affinity requirement. +**Files changed:** `SOR.Game/SpectatorRegistryService.cs`, `SOR.Shared/Redis/RedisKeys.cs`, +`SOR.Game/Handlers/GameHandlerBase.cs`, `GameSpectateHandler.cs`, `GameStopSpectatingHandler.cs` --- -### Issue 2 — `get_unit_by_id` crashes when a player's arch spirit is null on disconnect (High) +### Fix 2 — Null arch spirit guard in `get_unit_by_id` and `_apply_delta §7` (commit `e7bf257`) -**Root cause:** `Game.gd — get_unit_by_id` +**Was:** `p.get("archSpirit", {})` returns `null` (not `{}`) when the key exists with a +`null` value (server clears it on player disconnect). Calling `.get(...)` on `null` crashed: +`Invalid call. Nonexistent function 'get' in base 'Nil'`. -```gdscript -var arch: Dictionary = p.get("archSpirit", {}) -if arch.get("instanceId", "") == instance_id: - return arch -``` - -In GDScript, `Dictionary.get(key, default)` returns the default only when the **key is absent**. If the key exists with a `null` value — which happens when a player leaves and their arch spirit is cleared — `p.get("archSpirit", {})` returns `null`. The following `.get("instanceId", "")` call on `null` crashes: `Invalid call. Nonexistent function 'get' in base 'Nil'`. - -**Planned fix:** +**Now:** Both sites use the safe pattern: ```gdscript var arch_val: Variant = p.get("archSpirit") -if arch_val is Dictionary and not arch_val.is_empty(): - if arch_val.get("instanceId", "") == instance_id: - return arch_val +if arch_val is Dictionary and not (arch_val as Dictionary).is_empty(): + ... ``` -This pattern should be applied everywhere in the client that reads a dict value that could be null rather than absent (i.e. `dict.get(key)` followed by an `is Dictionary` guard, not `dict.get(key, {})`). +**File changed:** `Client/origin-client/autoloads/Game.gd` --- -### Issue 3 — `ChangedTiles` should only contain tiles that actually changed (Medium) +### Fix 3 — `DiffTiles` guard confirmed complete (commit `e7bf257`) -**Location:** `GameStateDiffer.cs — DiffTiles` +**Was:** Concern that `ChangedTiles` might include unchanged tiles in some paths. -The delta's `ChangedTiles` array must only include tiles where at least one field (`base1`, `base2`, `resolvedAffinity`, `occupantId`, `ruinId`, etc.) actually differs between `prev` and `next`. Sending unchanged tiles wastes bandwidth and forces the client to process unnecessary entries. - -Verify that `DiffTiles` performs a field-by-field equality check before emitting a `TileDelta`, and emits `null` (no entry) for unchanged tiles. If any path exists where all tiles are included unconditionally, that is the bug. The fix is entirely server-side — the client already applies only what it receives; no client changes are needed. +**Audit result:** The no-change guard at `GameStateDiffer.cs:159-161` is complete for all +fields present in `TileDelta`. `RuinDisabledUntilTurn` is intentionally absent from `TileDelta` +(it is a server-side scheduler value, not a client-visible state field). No code change needed. --- -### Issue 4 — `modelUrl` / `art2dUrl` sent in `UnitDelta` on every unit change (Low / Bandwidth) +### Fix 4 — `modelUrl` / `art2dUrl` stripped from `UnitDelta` (commit `93e3c8b`) -**Location:** `GameStateDiffer.cs — DiffUnit`, `_merge_unit_delta` lines 571-572 +**Was:** `UnitDelta` included `Art2dUrl` and `ModelUrl` on every unit update. These CDN +URLs are fixed for the lifetime of a card definition and were wasteful to repeat. The client +had a multi-casing fallback (`modelUrl`, `ModelUrl`, `modelurl`, etc.) as evidence of the +inconsistency. -`modelUrl` and `art2dUrl` are CDN URL strings that are fixed for the lifetime of a card definition. They are set once when the unit is first added (via `UnitSnapshot` in `UnitsAdded`). Sending them again in every subsequent `UnitDelta` is pure waste. The casing inconsistency (`art2dUrl`, `Art2dUrl`, `modelUrl`, `ModelUrl`, `modelurl` all checked on the client) also indicates the server is not emitting these consistently. +**Now:** +- `UnitDelta` record has no URL fields. URLs are only in `UnitSnapshot` (`CardInstanceDto`), + delivered once when the unit is first added. +- `DiffUnit` no longer compares or emits `Art2dUrl` / `ModelUrl`. +- `_merge_unit_delta` no longer applies URL fields from deltas. +- `modelUrl` and `art2dUrl` are set once on the unit dict in the `unitsAdded` path and + remain there for the session. -**Planned fix:** -- Strip `modelUrl` and `art2dUrl` from `UnitDelta` entirely. They should only ever appear in the initial `UnitSnapshot`. -- Longer term: derive asset URLs from the card definition stored on the client (each card's `definitionId` is already in the unit snapshot). The client card catalog holds the canonical URLs, so no URL transmission is needed at all. -- **iOS Safari exception:** because iOS Safari applies strict per-origin memory limits, asset URLs should be sent once on first sight (via `UnitSnapshot`) and held in a scoped cache keyed by `definitionId`. Subsequent units using the same definition reuse the cached URL rather than re-fetching. See Issue 5 for the broader iOS memory strategy. +**Files changed:** `SOR.Game/GameMessages.cs`, `SOR.Game/GameStateDiffer.cs`, +`Client/origin-client/autoloads/Game.gd` --- -### Issue 5 — iOS Safari crashes from unbounded asset cache (High / Mobile) +### Fix 5 — iOS Safari scoped asset loading (commit `c8c3666`) -iOS Safari enforces a hard per-tab memory ceiling (~300 MB). The client currently loads and retains all card art, 3D models, and assets as the game progresses, never evicting them. As more distinct cards are seen, memory climbs until the tab is killed. +**Was:** All 3D models were loaded and retained indefinitely. On iOS Safari (~300 MB per-tab +limit) this caused tab crashes as more distinct cards appeared over a game. -**Planned fix (layered):** +**Now:** +- **`Platform.gd`** (new autoload): `Platform.is_ios_safari()` detects iPhone/iPad Safari + via `JavaScriptBridge.eval("navigator.userAgent")`, excluding Chrome/CriOS. +- **`ModelCache.release_model(url, etag)`**: on iOS Safari, removes the `PackedScene` from + the in-memory `_mem` dict when a unit leaves the board. Disk cache is preserved for fast + reload if the same card type reappears. No-op on all other platforms. +- **`unit_mesh_builder.gd`**: stores the resolved `model_url`/`model_etag` per unit in + `_unit_model_urls` / `_unit_model_etags`. In the `to_remove` loop, calls + `ModelCache.release_model` before pooling or freeing each unit. +- **`ContentCache.get_model_url_for_definition(definition_id)`**: stub for looking up a + card's `Model3D` CDN URL from the definition cache without a live unit dict — foundation + for future eviction paths that do not require a fully loaded unit. -1. **Detect iOS Safari** via `OS.get_name() == "Web"` plus a user-agent check for Safari on iOS. Apply a separate asset management path for this client. - -2. **Scope asset loading to visible scene only.** Only load model/art assets for cards currently on the board or in the local player's hand. Unload assets when cards leave these zones (moved to discard, removed, etc.). - -3. **Lazy load on demand.** Trigger asset loads when a unit enters the viewport, not on game-state receipt. Cards in hand that are not being hovered or inspected do not need their 3D model resident. - -4. **Disk cache for non-iOS clients.** Desktop browsers and Android Chrome support the Cache API and IndexedDB with generous quotas — use these to persist card assets across sessions. Scope this to non-iOS Safari only; Safari's IndexedDB quota is small and unreliable. - -5. **Drop invisible assets.** When a unit is removed from the board (captured, discarded) and is not in hand, release its model and art resources immediately rather than waiting for scene transition. +**Files changed:** `Client/origin-client/autoloads/Platform.gd` (new), +`Client/origin-client/autoloads/ModelCache.gd`, +`Client/origin-client/autoloads/ContentCache.gd`, +`Client/origin-client/scenes/game/components/units/unit_mesh_builder.gd`, +`Client/origin-client/project.godot` --- -### Issue 6 — `_fetch_state()` race: multiple concurrent full-sync requests on version gap (Low) +### Fix 6 — `_fetch_state` race: `_syncing` guard and session-id validation (commit `7e22d87`) -**Location:** `Game.gd` — version gap handler +**Was:** `_fetch_state()` had no in-flight guard. On poor connections, multiple consecutive +deltas with gaps triggered concurrent `game.get_state` requests. `_apply_state_from_payload` +had no session-id check, so a stale response in-flight from a previous session could overwrite +state for a new game. -```gdscript -if _state_version >= 0 and v > _state_version + 1: - _fetch_state() - return -``` +**Now:** +- `var _syncing: bool = false` added to state vars; reset in `_clear_state()`. +- `_fetch_state()` returns immediately if `_syncing` is `true`; sets it to `true` before + the request; clears it in both the success and error callbacks. +- `_apply_state_from_payload()` validates `s.get("sessionId")` against the current + `session_id` before applying state. Mismatched responses are silently discarded. -There is no in-flight guard. On poor connections, multiple consecutive deltas can arrive with gaps, triggering multiple `_fetch_state()` calls simultaneously. Each causes a full state response; the last one wins, but the intermediate responses can briefly corrupt `_state_version`. - -**Planned fix:** Add `var _syncing: bool = false`. Check `if _syncing: return` at the top of the gap branch. Set `_syncing = true` before `_fetch_state()`. Reset to `false` in the `game.state_update` handler after applying the full state. +**File changed:** `Client/origin-client/autoloads/Game.gd`