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 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-24 13:58:35 +09:00
co-authored by Claude Opus 5.5
parent e119eb667a
commit 40659de7ec
4 changed files with 152 additions and 26 deletions
@@ -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 };
}
@@ -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();
},
});
}
@@ -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<string, unknown>();
window.history.pushState({}, "", "/examples/reference-resources/new");
render(
<ApplicationProvider
application={createTestApplication({
preferences: {
read: (name) => ({
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: {
+56
View File
@@ -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"],