From 63ce5f64865f61bd185032b8e0653e3aca42dff0 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 13:17:43 +0900 Subject: [PATCH] fix(cross-context): report an inactive host and hash the release epoch (Q-6.2-9) createBrowserCrossContextInvalidationFromHost returned undefined without any diagnostic when the cache epoch was invalid or secure random was missing, and bootstrap built the epoch as `release.${releaseId}`, so any release ID with `+`, `/`, `@` or over the length limit silently turned cross-tab invalidation off. - The host factory now reports OPEN/FAILED/NONE with the new reasons INVALID_CACHE_EPOCH or SECURE_RANDOM_UNAVAILABLE before returning undefined (the zero-topic build still probes nothing and reports nothing). - New crossContextCacheEpochForRelease() derives `release.` from the release ID; bootstrap uses it (one call-site change in src/bootstrap/runtime-adapters.ts). - The observation reason union gains two members (additive); the ops runbook lists them. Verified: two new unit tests failed before (no observation; missing epoch helper) and pass now. Lane gates, reference-feature and V3 integration tests, and check:diagnostics pass. Co-Authored-By: Claude Opus 5.5 --- .../client-cache-and-storage-recovery.md | 2 + .../browser-cross-context-host.ts | 41 +++++++++++- .../browser-cross-context-invalidation.ts | 2 + .../cross-context-invalidation/index.ts | 1 + src/bootstrap/runtime-adapters.ts | 9 ++- tests/unit/cross-tab-invalidation.test.ts | 62 +++++++++++++++++++ 6 files changed, 112 insertions(+), 5 deletions(-) diff --git a/docs/operations/client-cache-and-storage-recovery.md b/docs/operations/client-cache-and-storage-recovery.md index 4f606e2a..5780b9c5 100644 --- a/docs/operations/client-cache-and-storage-recovery.md +++ b/docs/operations/client-cache-and-storage-recovery.md @@ -78,6 +78,8 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle - `BROADCAST_PUBLISH_FAILED` - `STORAGE_LISTENER_FAILED` - `STORAGE_PUBLISH_FAILED` +- `INVALID_CACHE_EPOCH`, `SECURE_RANDOM_UNAVAILABLE`(OPEN FAILED): runtime을 + 만들지 못해 이 tab은 cross-tab 무효화 없이 `DEGRADED_LOCAL_ONLY`로 동작한다 - runtime status `DEGRADED_STORAGE_FALLBACK` 또는 `DEGRADED_LOCAL_ONLY` ### 확인 diff --git a/src/adapters/cross-context-invalidation/browser-cross-context-host.ts b/src/adapters/cross-context-invalidation/browser-cross-context-host.ts index b3d55a28..62f6f2d8 100644 --- a/src/adapters/cross-context-invalidation/browser-cross-context-host.ts +++ b/src/adapters/cross-context-invalidation/browser-cross-context-host.ts @@ -36,6 +36,20 @@ const CHANNEL_NAME = "ca-client-cache-invalidation-v1"; const STORAGE_PULSE_KEY = STORAGE_REGISTRY.CACHE_INVALIDATION_PULSE.physicalKey; +/** + * Q-6.2-9. A release ID may hold any character (`1.2.3+sha.abc`, `feature/x`, + * `app@1.2.3`) and any length, but a cache epoch is an opaque identifier. The + * epoch is a stable 64-bit FNV-1a digest of the ID, so every tab of one release + * agrees on it and it always passes the wire rule. + */ +export function crossContextCacheEpochForRelease(releaseId: string): string { + let hash = 0xcbf29ce484222325n; + for (const byte of new TextEncoder().encode(releaseId)) { + hash = ((hash ^ BigInt(byte)) * 0x100000001b3n) & 0xffffffffffffffffn; + } + return `release.${hash.toString(16).padStart(16, "0")}`; +} + /** * Captures native capabilities without allowing a SecurityError getter or a * missing random source to fail application boot. @@ -49,17 +63,38 @@ export function createBrowserCrossContextInvalidationFromHost( const host = dependencies.host ?? (globalThis as unknown as Record); + // Q-6.2-9. Ending inactive is reported, so cross-tab invalidation is never + // switched off without a diagnostic. + const inactive = ( + reason: "INVALID_CACHE_EPOCH" | "SECURE_RANDOM_UNAVAILABLE", + ): undefined => { + try { + dependencies.observe?.( + Object.freeze({ + operation: "OPEN" as const, + outcome: "FAILED" as const, + transport: "NONE" as const, + reason, + }), + ); + } catch { + // Diagnostics cannot change the capability decision. + } + return undefined; + }; if ( !isCacheInvalidationOpaqueIdentifier(dependencies.cacheEpoch) ) { - return undefined; + return inactive("INVALID_CACHE_EPOCH"); } const createOpaqueId = randomIdFactory(host); - if (!createOpaqueId) return undefined; + if (!createOpaqueId) return inactive("SECURE_RANDOM_UNAVAILABLE"); const sourceId = createOpaqueId("tab"); const sourceEpoch = createOpaqueId("page"); - if (!sourceId || !sourceEpoch) return undefined; + if (!sourceId || !sourceEpoch) { + return inactive("SECURE_RANDOM_UNAVAILABLE"); + } const capturedLocalStorage = captureLocalStorage(host); diff --git a/src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts b/src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts index 6872046a..027cadfa 100644 --- a/src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts +++ b/src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts @@ -43,9 +43,11 @@ export type CrossContextInvalidationObservationReason = | "DELIVERED" | "DUPLICATE" | "HANDLER_FAILED" + | "INVALID_CACHE_EPOCH" | "OPENED" | "PUBLISHED" | "SELF_ECHO" + | "SECURE_RANDOM_UNAVAILABLE" | "SEQUENCE_EXHAUSTED" | "STALE" | "STORAGE_CLEANUP_FAILED" diff --git a/src/adapters/cross-context-invalidation/index.ts b/src/adapters/cross-context-invalidation/index.ts index acaa9173..7d44c008 100644 --- a/src/adapters/cross-context-invalidation/index.ts +++ b/src/adapters/cross-context-invalidation/index.ts @@ -19,5 +19,6 @@ export { } from "./browser-cross-context-invalidation.ts"; export { createBrowserCrossContextInvalidationFromHost, + crossContextCacheEpochForRelease, type BrowserCrossContextHostDependencies, } from "./browser-cross-context-host.ts"; diff --git a/src/bootstrap/runtime-adapters.ts b/src/bootstrap/runtime-adapters.ts index dfa1e1da..84e3bba5 100644 --- a/src/bootstrap/runtime-adapters.ts +++ b/src/bootstrap/runtime-adapters.ts @@ -18,7 +18,10 @@ import { type DiagnosticRecordInput, } from "../contracts/diagnostics.ts"; import type { TelemetryEventName } from "../contracts/telemetry.ts"; -import { createBrowserCrossContextInvalidationFromHost } from "../adapters/cross-context-invalidation/index.ts"; +import { + createBrowserCrossContextInvalidationFromHost, + crossContextCacheEpochForRelease, +} from "../adapters/cross-context-invalidation/index.ts"; import { createConditionalValidatorStore, createQueryClient, @@ -327,7 +330,9 @@ export async function createRuntimeAdapters( const crossContextInvalidation = createBrowserCrossContextInvalidationFromHost({ ...(context.host === undefined ? {} : { host: context.host }), - cacheEpoch: `release.${context.release.releaseId}`, + cacheEpoch: crossContextCacheEpochForRelease( + context.release.releaseId, + ), topics: [...invalidationTopicVersions].map(([topic, topicVersion]) => Object.freeze({ topic, diff --git a/tests/unit/cross-tab-invalidation.test.ts b/tests/unit/cross-tab-invalidation.test.ts index 88df5162..5ab6d474 100644 --- a/tests/unit/cross-tab-invalidation.test.ts +++ b/tests/unit/cross-tab-invalidation.test.ts @@ -4,12 +4,14 @@ import { CACHE_INVALIDATION_PROTOCOL_VERSION, CACHE_INVALIDATION_WIRE_LIMITS, decodeCacheInvalidationWireEvent, + isCacheInvalidationOpaqueIdentifier, parseCacheInvalidationWireEvent, type CacheInvalidationWireEvent, } from "../../src/contracts/cache-invalidation.ts"; import { createBrowserCrossContextInvalidation, createBrowserCrossContextInvalidationFromHost, + crossContextCacheEpochForRelease, type BroadcastChannelFacade, type BroadcastMessageListener, type BrowserCrossContextInvalidationDependencies, @@ -346,6 +348,66 @@ describe("browser cross-context host", () => { ).toBeUndefined(); expect(reads).toEqual([]); }); + + it("reports an inactive host through observe instead of failing silently (Q-6.2-9)", () => { + const observations: CrossContextInvalidationObservation[] = []; + const topics = [{ topic: TOPIC, topicVersion: 1 }]; + + expect( + createBrowserCrossContextInvalidationFromHost({ + host: {}, + cacheEpoch: CACHE_EPOCH, + topics, + observe: (observation) => observations.push(observation), + }), + ).toBeUndefined(); + expect( + createBrowserCrossContextInvalidationFromHost({ + host: { crypto: globalThis.crypto }, + cacheEpoch: "release.1.2.3+sha.abc", + topics, + observe: (observation) => observations.push(observation), + }), + ).toBeUndefined(); + expect(observations).toEqual([ + { + operation: "OPEN", + outcome: "FAILED", + transport: "NONE", + reason: "SECURE_RANDOM_UNAVAILABLE", + }, + { + operation: "OPEN", + outcome: "FAILED", + transport: "NONE", + reason: "INVALID_CACHE_EPOCH", + }, + ]); + }); + + it("derives a valid, stable cache epoch from any release id (Q-6.2-9)", () => { + const releaseIds = [ + "1.2.3+sha.abc", + "feature/x", + "app@1.2.3", + "x".repeat(500), + "1.2.3", + ]; + const epochs = releaseIds.map(crossContextCacheEpochForRelease); + for (const epoch of epochs) { + expect(isCacheInvalidationOpaqueIdentifier(epoch)).toBe(true); + } + expect(new Set(epochs).size).toBe(releaseIds.length); + expect(crossContextCacheEpochForRelease("feature/x")).toBe(epochs[1]); + + const runtime = createBrowserCrossContextInvalidationFromHost({ + host: { crypto: globalThis.crypto }, + cacheEpoch: crossContextCacheEpochForRelease("app@1.2.3"), + topics: [{ topic: TOPIC, topicVersion: 1 }], + }); + expect(runtime).toBeDefined(); + runtime?.close(); + }); }); describe("browser cross-context invalidation transport", () => {