From 40659de7ec88c77d9ef1d854859e0ea57b05b4de Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 13:41:48 +0900 Subject: [PATCH] fix(release): share one reload-once guard between chunk and boot recovery (Q-6.9-9) Chunk recovery kept its own guard: marker keyed by the release pair, no TTL, trusted write().ok. Round 1 fixed the boot guard (key-independent marker within a TTL, read-back check) but the chunk copy still reloaded on every failure when replicas alternated A->B, B->A. platform/release gains createReloadOnceGuard (the round-1 boot rule, now with a refusal reason); createReleaseMismatchRecovery wraps it with unchanged boot semantics (marker within TTL blocks regardless of key, markCoherentBoot clears), and decideChunkRecovery uses it over its own CHUNK_RELOAD_GUARD key, keeping its reason vocabulary. Application -> platform is allowed by .dependency-cruiser.json; platform may not import application, so the guard lives in platform. Behavior change (chunk only): a second reload within the TTL is refused even for a different release pair, and a marker that does not read back is guard-write-failed. tests/component/context-route-gateway.test.tsx used a preferences stub that dropped writes; it now persists them. Verified: tests/unit/chunk-recovery.test.ts characterization (read/write failure, same pair, invariants) green before the change; alternating pair test RED before, green after. Boot tests unchanged and green; FE-RB-002 drill PASS; test:integration PASS; all gates PASS. Co-Authored-By: Claude Opus 5.5 --- .../use-cases/decide-chunk-recovery.ts | 35 +++++---- .../release/release-mismatch-recovery.ts | 71 +++++++++++++++---- .../component/context-route-gateway.test.tsx | 16 +++++ tests/unit/chunk-recovery.test.ts | 56 +++++++++++++++ 4 files changed, 152 insertions(+), 26 deletions(-) diff --git a/src/application/use-cases/decide-chunk-recovery.ts b/src/application/use-cases/decide-chunk-recovery.ts index dd51469c..6ca4326a 100644 --- a/src/application/use-cases/decide-chunk-recovery.ts +++ b/src/application/use-cases/decide-chunk-recovery.ts @@ -1,3 +1,4 @@ +import { createReloadOnceGuard } from "../../platform/release/release-mismatch-recovery.ts"; import type { StoragePort } from "../ports/storage-port.ts"; const RECOVERABLE_KINDS = new Set(["CHUNK_LOAD_FAILURE", "DEPLOY_MISMATCH"]); @@ -35,17 +36,25 @@ export function decideChunkRecovery( const releasePair = `${input.currentBuildId}/${input.currentReleaseId}` + `->${input.activeBuildId}/${input.activeReleaseId}`; - const guard = input.storage.read("CHUNK_RELOAD_GUARD"); - if (!guard.ok) { - return { action: "support", reason: "guard-read-failed" }; - } - if (guard.value === releasePair) { - return { action: "support", reason: "reload-already-attempted" }; - } - - const recorded = input.storage.write("CHUNK_RELOAD_GUARD", releasePair); - if (!recorded.ok) { - return { action: "support", reason: "guard-write-failed" }; - } - return { action: "reload-once", releasePair }; + // Q-6.9-9. The boot reload guard's rule: at most one automatic reload per + // marker TTL, whatever the pair. A pair-keyed marker let replicas that + // alternate A/B reload on every chunk failure. + const decision = createReloadOnceGuard({ + read() { + const guard = input.storage.read("CHUNK_RELOAD_GUARD"); + if (!guard.ok) throw new Error("chunk reload guard is unreadable"); + return typeof guard.value === "string" ? guard.value : null; + }, + write(value) { + if (!input.storage.write("CHUNK_RELOAD_GUARD", value).ok) { + throw new Error("chunk reload guard was not persisted"); + } + }, + clear() { + input.storage.remove("CHUNK_RELOAD_GUARD"); + }, + }).decide(releasePair); + return decision === "reload-once" + ? { action: "reload-once", releasePair } + : { action: "support", reason: decision }; } diff --git a/src/platform/release/release-mismatch-recovery.ts b/src/platform/release/release-mismatch-recovery.ts index 7a6e5853..69f466f0 100644 --- a/src/platform/release/release-mismatch-recovery.ts +++ b/src/platform/release/release-mismatch-recovery.ts @@ -29,15 +29,36 @@ export interface ReleaseMismatchRecovery { markCoherentBoot(): void; } +/** + * Q-6.9-9. Why a reload-once guard allowed or refused a reload. Every refusal + * fails closed: without a working marker there is no automatic reload. + */ +export type ReloadOnceDecision = + | "reload-once" + | "reload-already-attempted" + | "guard-read-failed" + | "guard-write-failed"; + +/** + * Q-6.9-9. The one "reload at most once" guard. Boot mismatch recovery and + * chunk recovery each keep their own marker (store) and key, but share this + * rule, so a fix to one cannot leave the other looping. + */ +export interface ReloadOnceGuard { + decide(key: string): ReloadOnceDecision; + /** Drops the marker, e.g. after a coherent boot. Never throws. */ + clear(): void; +} + const MAX_KEY_LENGTH = 256; -export function createReleaseMismatchRecovery( +export function createReloadOnceGuard( store: RecoveryMarkerStore | null, options: Readonly<{ now?: () => number; ttlMs?: number; }> = {}, -): ReleaseMismatchRecovery { +): ReloadOnceGuard { const now = options.now ?? (() => Date.now()); const ttlMs = options.ttlMs ?? 10 * 60_000; @@ -51,26 +72,30 @@ export function createReleaseMismatchRecovery( } return Object.freeze({ - decide(mismatchKey: string): ReleaseMismatchDecision { - const key = mismatchKey.slice(0, MAX_KEY_LENGTH); + decide(rawKey: string): ReloadOnceDecision { + const key = rawKey.slice(0, MAX_KEY_LENGTH); + if (!store) return "guard-read-failed"; + let current: number; try { - if (!store) return "show-failure"; const previous = read(); - const current = now(); - // Key-independent: alternating replicas change the key on every boot. + current = now(); + // Key-independent: alternating replicas change the key every time. if (previous && current - previous.at < ttlMs) { - return "show-failure"; + return "reload-already-attempted"; } + } catch { + return "guard-read-failed"; + } + try { store.write(`${key}@${current}`); // Only a marker that is really persisted may authorize a reload; - // otherwise the next boot could not know it already reloaded. - return read()?.key === key ? "reload-once" : "show-failure"; + // otherwise the next attempt could not know it already reloaded. + return read()?.key === key ? "reload-once" : "guard-write-failed"; } catch { - // Fail closed: without a working marker, never reload automatically. - return "show-failure"; + return "guard-write-failed"; } }, - markCoherentBoot(): void { + clear(): void { try { store?.clear(); } catch { @@ -79,3 +104,23 @@ export function createReleaseMismatchRecovery( }, }); } + +export function createReleaseMismatchRecovery( + store: RecoveryMarkerStore | null, + options: Readonly<{ + now?: () => number; + ttlMs?: number; + }> = {}, +): ReleaseMismatchRecovery { + const guard = createReloadOnceGuard(store, options); + return Object.freeze({ + decide(mismatchKey: string): ReleaseMismatchDecision { + return guard.decide(mismatchKey) === "reload-once" + ? "reload-once" + : "show-failure"; + }, + markCoherentBoot(): void { + guard.clear(); + }, + }); +} diff --git a/tests/component/context-route-gateway.test.tsx b/tests/component/context-route-gateway.test.tsx index cb5a5d23..9b9a0cf6 100644 --- a/tests/component/context-route-gateway.test.tsx +++ b/tests/component/context-route-gateway.test.tsx @@ -103,10 +103,26 @@ describe("context route gateway", () => { assetManifestHash: "hash", routeChunks: { "route-reference-resource-form": "assets/form.js" }, }); + // The reload-once guard only trusts a marker it can read back (Q-6.9-9). + const stored = new Map(); window.history.pushState({}, "", "/examples/reference-resources/new"); render( ({ + ok: true as const, + value: stored.has(name) ? stored.get(name) : "system", + }), + write: (name, value) => { + stored.set(name, value); + return { ok: true as const }; + }, + remove: (name) => { + stored.delete(name); + return { ok: true as const }; + }, + }, navigation: { reload }, // A deploy happened: the page runs build-a, the server has build-b. releaseInfo: { diff --git a/tests/unit/chunk-recovery.test.ts b/tests/unit/chunk-recovery.test.ts index 7d0c8a12..7e29d6e1 100644 --- a/tests/unit/chunk-recovery.test.ts +++ b/tests/unit/chunk-recovery.test.ts @@ -37,6 +37,62 @@ describe("controlled chunk recovery", () => { }); }); + const storageError = { + kind: "STORAGE_UNAVAILABLE" as const, + code: "STORAGE_UNAVAILABLE", + retryable: false, + operationId: "STORAGE", + attemptCount: 1, + userMessageKey: "error.storage_unavailable", + action: "none" as const, + }; + const mismatch = { + failureKind: "CHUNK_LOAD_FAILURE", + manifestLoaded: true, + currentBuildId: "build-a", + currentReleaseId: "release-a", + activeBuildId: "build-b", + activeReleaseId: "release-b", + } as const; + + it("fails closed when the guard cannot be read", () => { + const storage: StoragePort = { + ...memoryStorage(), + read: () => ({ ok: false, error: storageError }), + }; + expect(decideChunkRecovery({ ...mismatch, storage })).toEqual({ + action: "support", + reason: "guard-read-failed", + }); + }); + + it("fails closed when the guard cannot be written", () => { + const storage: StoragePort = { + ...memoryStorage(), + write: () => ({ ok: false, error: storageError }), + }; + expect(decideChunkRecovery({ ...mismatch, storage })).toEqual({ + action: "support", + reason: "guard-write-failed", + }); + }); + + it("allows no second reload when replicas alternate the release pair (Q-6.9-9)", () => { + const storage = memoryStorage(); + expect(decideChunkRecovery({ ...mismatch, storage }).action).toBe("reload-once"); + // After the reload the page is on build-b while a replica still serves A. + expect( + decideChunkRecovery({ + ...mismatch, + currentBuildId: "build-b", + currentReleaseId: "release-b", + activeBuildId: "build-a", + activeReleaseId: "release-a", + storage, + }), + ).toEqual({ action: "support", reason: "reload-already-attempted" }); + }); + it.each([ [{ failureKind: "SERVER_FAILURE" }, "not-recoverable"], [{ manifestLoaded: false }, "manifest-unavailable"],