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.<fnv1a-64 hex>`
  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 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-24 13:39:59 +09:00
co-authored by Claude Opus 5.5
parent 4c812a4213
commit 63ce5f6486
6 changed files with 112 additions and 5 deletions
@@ -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`
### 확인
@@ -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<string, unknown>);
// 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);
@@ -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"
@@ -19,5 +19,6 @@ export {
} from "./browser-cross-context-invalidation.ts";
export {
createBrowserCrossContextInvalidationFromHost,
crossContextCacheEpochForRelease,
type BrowserCrossContextHostDependencies,
} from "./browser-cross-context-host.ts";
+7 -2
View File
@@ -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,
+62
View File
@@ -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", () => {