Files
DongHyeonka ac98facd16
frontend-quality-gates / merge / tests (pull_request) Canceled after 0s
frontend-quality-gates / merge / browser tests (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Canceled after 0s
frontend-quality-gates / merge / static checks (pull_request) Canceled after 42s
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Canceled after 0s
frontend-quality-gates / external-vulnerability-provider (pull_request) Canceled after 0s
frontend-quality-gates / external-provenance-provider (pull_request) Canceled after 0s
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Canceled after 0s
frontend-quality-gates / deploy-promoted-release (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Canceled after 0s
frontend-quality-gates / main / self-tests and removal drills (pull_request) Canceled after 0s
fix(cross-context-invalidation): 듣기 전에 localStorage를 읽어 pulse를 잃지 않는다
문제: Chromium은 탭의 첫 localStorage 읽기에서 그 탭의 캐시를 채우며
변경 observer를 새로 건다(Blink CachedStorageArea::EnsureLoaded). 이때
이미 도착했지만 아직 처리하지 않은 다른 탭의 변경 알림은 버려진다.
storage fallback의 pulse는 쓰자마자 지우므로 채운 캐시에도 흔적이 없어,
받는 탭은 그 무효화를 영영 받지 못한다. browser-capabilities 시험
「falls back to native localStorage events」가 runner run 371과 desktop
부하 20회 중 1회에서 이렇게 실패했다(받은 deliveries []). 받는 page가
바쁠 때 그 page의 첫 읽기(발행 직후의 snapshot, 또는 앱 부트의 설정
읽기)가 쌓인 알림보다 먼저 돌았다. 제품에서도 탭의 다른 코드가 처음
읽는 순간 같은 창이 열린다.

고친 방법: host가 잡은 localStorage를 storage 리스너를 걸기 전에 한 번
읽는다(getItem). 그 뒤의 읽기는 캐시를 다시 채우지 않으므로 observer가
바뀌지 않는다. 읽기가 거절되는 host에서도 리스너는 그대로 건다.
버린 대안:
- 시험만 고치기(발행 전에 받는 page에서 한 번 읽기): 제품의 같은 창을
  남긴다.
- poll 시한 늘리기: 늦는 것이 아니라 잃는 것이라 소용없다.

위험·한계: 런타임을 만들 때 그 origin의 localStorage 전체를 renderer로
한 번 읽는다(Chromium sync GetAll). 앱이 이미 localStorage를 쓰면 추가
비용이 없다. storage service가 다시 연결될 때(ResetConnection)의 손실은
다루지 않는다. 받는 page가 바쁜 동안 다른 탭의 cookie 변경을 보는 것은
Chromium뿐이라, 새 브라우저 시험은 Chromium에서만 받는 page를 붙잡는다.
새 시험은 앱 없는 같은 origin 빈 문서에서 돈다. 앱 부트가 먼저 읽어
받는 탭을 채우면 캐시 채우기를 빼도 통과하기 때문이다.

검증(desktop, scripts/verify.sh exec, 트리 ddda30a3):
- node scripts/run-vitest.ts run tests/unit/cross-tab-invalidation.test.ts
  21 통과
- playwright cross-context-invalidation.spec.ts --repeat-each 5,
  3엔진: 45 통과
- 변이(캐시 채우기 호출 제거, 트리 2f460282): 새 단위 시험 실패,
  새 브라우저 시험 chromium 5/5 실패, 나머지 40 통과
- 고치기 전 탐침(main f3de258d): 받는 page가 막힌 사이 발행하고 같은
  작업에서 첫 읽기 → chromium 5/5 실패, firefox·webkit 10/10 통과.
  리스너 전에 한 번 읽게 한 대조는 15/15 통과

Refs: runner run 371 merge / browser tests
2026-11-19 12:05:54 +09:00

1141 lines
35 KiB
TypeScript

import { describe, expect, it, vi } from "vitest";
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,
type CrossContextInvalidationDelivery,
type CrossContextInvalidationObservation,
type StorageEventTargetFacade,
type StoragePulseFacade,
type StoragePulseListener,
} from "../../src/adapters/cross-context-invalidation/index.ts";
const NOW = 1_000_000;
const CACHE_EPOCH = "cache-epoch-0001";
const TOPIC = "sample-topic-alpha";
const CHANNEL_NAME = "cache-invalidation-v1";
const STORAGE_PULSE_KEY = "ca-frontend:cache-invalidation:v1:pulse";
class FakeBroadcastNetwork {
readonly channels: FakeBroadcastChannel[] = [];
readonly messages: unknown[] = [];
createChannel = (name: string): FakeBroadcastChannel => {
const channel = new FakeBroadcastChannel(name, this);
this.channels.push(channel);
return channel;
};
emit(value: unknown): void {
this.messages.push(value);
for (const channel of this.channels) channel.emit(value);
}
}
class FakeBroadcastChannel implements BroadcastChannelFacade {
readonly listeners = new Set<BroadcastMessageListener>();
closed = false;
failPost = false;
closeCount = 0;
removeCount = 0;
constructor(
readonly name: string,
private readonly network: FakeBroadcastNetwork,
) {}
postMessage(value: unknown): void {
if (this.closed || this.failPost) {
throw new DOMException("Broadcast failed", "InvalidStateError");
}
// Deliberately includes the sender. Native BroadcastChannel can still
// deliver through another same-context channel, so the adapter must use
// source identity rather than relying on provider echo behavior.
this.network.emit(value);
}
addEventListener(
_type: "message",
listener: BroadcastMessageListener,
): void {
this.listeners.add(listener);
}
removeEventListener(
_type: "message",
listener: BroadcastMessageListener,
): void {
this.removeCount += 1;
this.listeners.delete(listener);
}
close(): void {
this.closeCount += 1;
this.closed = true;
this.listeners.clear();
}
emit(value: unknown): void {
if (this.closed) return;
for (const listener of [...this.listeners]) {
listener({ data: value });
}
}
}
class FakeStorageEventTarget implements StorageEventTargetFacade {
readonly listeners = new Set<StoragePulseListener>();
removeCount = 0;
addEventListener(
_type: "storage",
listener: StoragePulseListener,
): void {
this.listeners.add(listener);
}
removeEventListener(
_type: "storage",
listener: StoragePulseListener,
): void {
this.removeCount += 1;
this.listeners.delete(listener);
}
emit(
key: string | null,
newValue: string | null,
storageArea: "EXPECTED_LOCAL_STORAGE" | "OTHER_OR_UNKNOWN" =
"EXPECTED_LOCAL_STORAGE",
): void {
for (const listener of [...this.listeners]) {
listener({ key, newValue, storageArea });
}
}
}
class FakeStorageBus {
readonly values = new Map<string, string>();
readonly targets = new Set<FakeStorageEventTarget>();
createEndpoint(): Readonly<{
storage: FakeStorageEndpoint;
target: FakeStorageEventTarget;
}> {
const target = new FakeStorageEventTarget();
this.targets.add(target);
return Object.freeze({
storage: new FakeStorageEndpoint(this, target),
target,
});
}
/** Simulates the event arriving from a different Storage area. */
emitAsForeignArea = false;
set(
owner: FakeStorageEventTarget,
key: string,
value: string,
): void {
this.values.set(key, value);
for (const target of this.targets) {
if (target !== owner) {
target.emit(
key,
value,
this.emitAsForeignArea
? "OTHER_OR_UNKNOWN"
: "EXPECTED_LOCAL_STORAGE",
);
}
}
}
remove(owner: FakeStorageEventTarget, key: string): void {
this.values.delete(key);
for (const target of this.targets) {
if (target !== owner) target.emit(key, null);
}
}
}
class FakeStorageEndpoint implements StoragePulseFacade {
failSet = false;
failRemove = false;
setCount = 0;
removeCount = 0;
constructor(
private readonly bus: FakeStorageBus,
private readonly owner: FakeStorageEventTarget,
) {}
setItem(key: string, value: string): void {
this.setCount += 1;
if (this.failSet) {
throw new DOMException("Storage denied", "SecurityError");
}
this.bus.set(this.owner, key, value);
}
removeItem(key: string): void {
this.removeCount += 1;
if (this.failRemove) {
throw new DOMException("Storage denied", "SecurityError");
}
this.bus.remove(this.owner, key);
}
}
function dependencies(
id: string,
overrides: Partial<BrowserCrossContextInvalidationDependencies> = {},
): BrowserCrossContextInvalidationDependencies {
let eventNumber = 0;
return {
channelName: CHANNEL_NAME,
storagePulseKey: STORAGE_PULSE_KEY,
sourceId: `${id}-source`,
sourceEpoch: `${id}-epoch`,
cacheEpoch: CACHE_EPOCH,
topics: [{ topic: TOPIC, topicVersion: 1 }],
createEventId: () =>
`${id}-event-${String(++eventNumber).padStart(8, "0")}`,
nowEpochMilliseconds: () => NOW,
...overrides,
};
}
function wireEvent(
overrides: Partial<CacheInvalidationWireEvent> = {},
): CacheInvalidationWireEvent {
return {
protocolVersion: CACHE_INVALIDATION_PROTOCOL_VERSION,
eventId: "remote-event-00000001",
sourceId: "remote-source-0000001",
sourceEpoch: "remote-epoch-0000001",
sequence: 1,
cacheEpoch: CACHE_EPOCH,
topic: TOPIC,
topicVersion: 1,
emittedAt: NOW,
expiresAt: NOW + 60_000,
...overrides,
};
}
describe("cache invalidation wire contract", () => {
const policy = {
cacheEpoch: CACHE_EPOCH,
topicVersions: { [TOPIC]: 1 },
nowEpochMilliseconds: NOW,
} as const;
it("accepts only the exact payload-free, query-key-free envelope", () => {
const accepted = parseCacheInvalidationWireEvent(wireEvent(), policy);
expect(accepted).toMatchObject({ ok: true });
if (!accepted.ok) throw new Error("Expected a valid event");
expect(Object.keys(accepted.value).sort()).toEqual([
"cacheEpoch",
"emittedAt",
"eventId",
"expiresAt",
"protocolVersion",
"sequence",
"sourceEpoch",
"sourceId",
"topic",
"topicVersion",
]);
expect(accepted.value).not.toHaveProperty("payload");
expect(accepted.value).not.toHaveProperty("queryKey");
expect(
parseCacheInvalidationWireEvent(
{ ...wireEvent(), payload: { secret: "must-not-cross" } },
policy,
),
).toEqual({ ok: false, reason: "INVALID_ENVELOPE" });
expect(
parseCacheInvalidationWireEvent(
{ ...wireEvent(), queryKey: ["resource", "sensitive-id"] },
policy,
),
).toEqual({ ok: false, reason: "INVALID_ENVELOPE" });
});
it("bounds bytes, protocol, allowlist, cache epoch and event lifetime", () => {
expect(
decodeCacheInvalidationWireEvent("{not-json", policy),
).toEqual({ ok: false, reason: "MALFORMED_JSON" });
expect(
decodeCacheInvalidationWireEvent(
"x".repeat(
CACHE_INVALIDATION_WIRE_LIMITS.maxWireBytes + 1,
),
policy,
),
).toEqual({ ok: false, reason: "OVERSIZED" });
expect(
parseCacheInvalidationWireEvent(
{ ...wireEvent(), protocolVersion: 2 },
policy,
),
).toEqual({ ok: false, reason: "PROTOCOL_MISMATCH" });
expect(
parseCacheInvalidationWireEvent(
{ ...wireEvent(), topic: "unknown-topic" },
policy,
),
).toEqual({ ok: false, reason: "TOPIC_REJECTED" });
expect(
parseCacheInvalidationWireEvent(
{ ...wireEvent(), topicVersion: 2 },
policy,
),
).toEqual({ ok: false, reason: "TOPIC_REJECTED" });
expect(
parseCacheInvalidationWireEvent(
{ ...wireEvent(), cacheEpoch: "other-cache-epoch" },
policy,
),
).toEqual({
ok: false,
reason: "CACHE_EPOCH_MISMATCH",
});
expect(
parseCacheInvalidationWireEvent(
wireEvent({ emittedAt: NOW - 60_000, expiresAt: NOW }),
policy,
),
).toEqual({ ok: false, reason: "EXPIRED" });
});
});
describe("browser cross-context host", () => {
it("does not inspect browser capabilities when no topic is installed", () => {
const reads: string[] = [];
const host = new Proxy<Record<string, unknown>>(
{},
{
get(_target, property) {
reads.push(String(property));
throw new DOMException("Capability access denied", "SecurityError");
},
},
);
expect(
createBrowserCrossContextInvalidationFromHost({
host,
cacheEpoch: CACHE_EPOCH,
topics: [],
}),
).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",
},
]);
});
// 1101/02-04 (2), N38. sessionStorage and every other Storage area raise
// the same `storage` event, so the host trusts only the localStorage object
// it captured, compared by identity. The transport tests above hand the core
// a ready-made area verdict, so removing that comparison passed them all.
it("takes a storage pulse only from the localStorage object it captured", () => {
type Listener = (event: unknown) => void;
type Tab = {
listeners: Set<Listener>;
localStorage: Record<string, unknown>;
sessionStorage: Record<string, unknown>;
};
const tabs: Tab[] = [];
let arrivingFrom: "localStorage" | "sessionStorage" | "lookalike" =
"localStorage";
const storageArea = (tab: Tab) => {
const values = new Map<string, string>();
const notify = (key: string, newValue: string | null) => {
const from = arrivingFrom;
for (const other of tabs) {
if (other === tab) continue;
// Same shape, another object: identity, not shape, is the test.
const area =
from === "lookalike" ? { ...other.localStorage } : other[from];
for (const listener of [...other.listeners]) {
listener({ key, newValue, storageArea: area });
}
}
};
return {
getItem: (key: string) => values.get(key) ?? null,
setItem(key: string, value: string) {
values.set(key, value);
notify(key, value);
},
removeItem(key: string) {
values.delete(key);
notify(key, null);
},
};
};
const hostOfNewTab = (): Record<string, unknown> => {
const tab: Tab = {
listeners: new Set(),
localStorage: {},
sessionStorage: {},
};
tab.localStorage = storageArea(tab);
tab.sessionStorage = storageArea(tab);
tabs.push(tab);
// No BroadcastChannel, so the storage pulse is the only transport.
return {
crypto: globalThis.crypto,
localStorage: tab.localStorage,
sessionStorage: tab.sessionStorage,
addEventListener(type: string, listener: Listener) {
if (type === "storage") tab.listeners.add(listener);
},
removeEventListener(type: string, listener: Listener) {
if (type === "storage") tab.listeners.delete(listener);
},
};
};
const topics = [{ topic: TOPIC, topicVersion: 1 }];
const publisher = createBrowserCrossContextInvalidationFromHost({
host: hostOfNewTab(),
cacheEpoch: CACHE_EPOCH,
topics,
});
const receiver = createBrowserCrossContextInvalidationFromHost({
host: hostOfNewTab(),
cacheEpoch: CACHE_EPOCH,
topics,
});
if (!publisher || !receiver) throw new Error("host runtime not created");
const received = vi.fn();
receiver.subscribe(received);
for (const area of ["sessionStorage", "lookalike"] as const) {
arrivingFrom = area;
expect(
publisher.publish({ topic: TOPIC, topicVersion: 1 }),
).toMatchObject({ ok: true });
}
expect(received).not.toHaveBeenCalled();
arrivingFrom = "localStorage";
expect(
publisher.publish({ topic: TOPIC, topicVersion: 1 }),
).toMatchObject({ ok: true });
expect(received).toHaveBeenCalledOnce();
publisher.close();
receiver.close();
});
// 2026-11-19, runner run 371. Chromium loads a tab's localStorage cache on
// the tab's first read, and the load drops the change notifications from
// other tabs that have arrived but not run yet (Blink
// CachedStorageArea::EnsureLoaded). A pulse is removed as soon as it is
// written, so the loaded cache has no trace of it either. This model queues
// each tab's notifications until the tab runs them and drops the queue on
// the tab's first read.
describe("in a browser that drops queued notifications on a tab's first read", () => {
type Listener = (event: unknown) => void;
type Tab = {
listeners: Set<Listener>;
queued: unknown[];
loaded: boolean;
localStorage: Record<string, unknown>;
};
function chromiumLikeTabs(options: { refuseReads?: boolean } = {}) {
const tabs: Tab[] = [];
const values = new Map<string, string>();
const open = () => {
const tab: Tab = {
listeners: new Set(),
queued: [],
loaded: false,
localStorage: {},
};
const load = () => {
if (tab.loaded) return;
tab.loaded = true;
tab.queued.length = 0;
};
const notifyOthers = (key: string, newValue: string | null) => {
for (const other of tabs) {
if (other === tab) continue;
other.queued.push({
key,
newValue,
storageArea: other.localStorage,
});
}
};
tab.localStorage = {
getItem(key: string) {
if (options.refuseReads) {
throw new DOMException("Storage is disabled", "SecurityError");
}
load();
return values.get(key) ?? null;
},
setItem(key: string, value: string) {
load();
values.set(key, value);
notifyOthers(key, value);
},
removeItem(key: string) {
load();
values.delete(key);
notifyOthers(key, null);
},
};
tabs.push(tab);
const host: Record<string, unknown> = {
crypto: globalThis.crypto,
localStorage: tab.localStorage,
addEventListener(type: string, listener: Listener) {
if (type === "storage") tab.listeners.add(listener);
},
removeEventListener(type: string, listener: Listener) {
if (type === "storage") tab.listeners.delete(listener);
},
};
return { tab, host };
};
// The tab's event loop gets to the queued notifications.
const runQueued = (tab: Tab) => {
for (const event of tab.queued.splice(0)) {
for (const listener of [...tab.listeners]) listener(event);
}
};
return { open, runQueued };
}
it("reads its localStorage before it listens, so a later first read in the tab drops no pulse", () => {
const { open, runQueued } = chromiumLikeTabs();
const topics = [{ topic: TOPIC, topicVersion: 1 }];
const publisherTab = open();
const receiverTab = open();
const publisher = createBrowserCrossContextInvalidationFromHost({
host: publisherTab.host,
cacheEpoch: CACHE_EPOCH,
topics,
});
const receiver = createBrowserCrossContextInvalidationFromHost({
host: receiverTab.host,
cacheEpoch: CACHE_EPOCH,
topics,
});
if (!publisher || !receiver) throw new Error("host runtime not created");
const received = vi.fn();
receiver.subscribe(received);
expect(
publisher.publish({ topic: TOPIC, topicVersion: 1 }),
).toEqual({ ok: true, transport: "STORAGE" });
// The receiver tab is busy as the pulse arrives; then other code in it
// reads localStorage (a preference, another adapter) before the tab
// runs the queued notifications.
const otherCode = receiverTab.tab.localStorage as { getItem(key: string): unknown };
otherCode.getItem("another-adapter:preference");
runQueued(receiverTab.tab);
expect(received).toHaveBeenCalledOnce();
expect(received.mock.calls[0]?.[0]).toMatchObject({
ordering: "NEXT",
transport: "STORAGE",
event: { sequence: 1, topic: TOPIC },
});
publisher.close();
receiver.close();
});
it("still listens when the host refuses the priming read", () => {
const { open } = chromiumLikeTabs({ refuseReads: true });
const receiver = createBrowserCrossContextInvalidationFromHost({
host: open().host,
cacheEpoch: CACHE_EPOCH,
topics: [{ topic: TOPIC, topicVersion: 1 }],
});
expect(receiver?.getStatus()).toBe("ACTIVE_STORAGE_FALLBACK");
receiver?.close();
});
});
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", () => {
it("publishes one exact BroadcastChannel event and filters self echo", () => {
const network = new FakeBroadcastNetwork();
const first = createBrowserCrossContextInvalidation(
dependencies("tab-a", {
createBroadcastChannel: network.createChannel,
}),
);
const second = createBrowserCrossContextInvalidation(
dependencies("tab-b", {
createBroadcastChannel: network.createChannel,
}),
);
const local = vi.fn();
const remote = vi.fn();
first.subscribe(local);
second.subscribe(remote);
expect(first.getStatus()).toBe("ACTIVE_BROADCAST");
expect(first.publish({ topic: TOPIC, topicVersion: 1 })).toEqual({
ok: true,
transport: "BROADCAST",
});
expect(local).not.toHaveBeenCalled();
expect(remote).toHaveBeenCalledOnce();
expect(remote.mock.calls[0]?.[0]).toMatchObject({
ordering: "NEXT",
transport: "BROADCAST",
event: {
protocolVersion: 1,
sequence: 1,
cacheEpoch: CACHE_EPOCH,
topic: TOPIC,
topicVersion: 1,
},
});
expect(network.messages).toHaveLength(1);
expect(JSON.stringify(network.messages[0])).not.toMatch(
/payload|queryKey|sensitive/,
);
first.close();
second.close();
});
it("de-duplicates the same event delivered by both transports", () => {
const network = new FakeBroadcastNetwork();
const storage = new FakeStorageBus().createEndpoint();
const runtime = createBrowserCrossContextInvalidation(
dependencies("tab-b", {
createBroadcastChannel: network.createChannel,
storage: storage.storage,
storageEvents: storage.target,
}),
);
const received = vi.fn();
runtime.subscribe(received);
const event = wireEvent();
network.emit(event);
storage.target.emit(STORAGE_PULSE_KEY, JSON.stringify(event));
expect(received).toHaveBeenCalledOnce();
expect(received.mock.calls[0]?.[0]).toMatchObject({
transport: "BROADCAST",
ordering: "NEXT",
});
runtime.close();
});
it("reports per-source gaps and drops stale out-of-order events", () => {
const network = new FakeBroadcastNetwork();
const observations: CrossContextInvalidationObservation[] = [];
const runtime = createBrowserCrossContextInvalidation(
dependencies("tab-b", {
createBroadcastChannel: network.createChannel,
observe: (observation) => observations.push(observation),
}),
);
const delivered: CrossContextInvalidationDelivery[] = [];
runtime.subscribe((delivery) => delivered.push(delivery));
network.emit(wireEvent({ eventId: "remote-event-00000001", sequence: 1 }));
network.emit(wireEvent({ eventId: "remote-event-00000003", sequence: 3 }));
network.emit(wireEvent({ eventId: "remote-event-00000002", sequence: 2 }));
network.emit(
wireEvent({
eventId: "remote-new-epoch-event",
sourceEpoch: "remote-epoch-0000002",
sequence: 1,
}),
);
// 02-08. A source first seen mid-stream has already sent events this tab
// missed, so its first event is a gap on its own.
network.emit(
wireEvent({
eventId: "joined-event-00000004",
sourceId: "joined-source-0000001",
sequence: 4,
}),
);
expect(
delivered.map(({ event, ordering }) => [
event.sequence,
ordering,
]),
).toEqual([
[1, "NEXT"],
[3, "GAP"],
[1, "NEXT"],
[4, "GAP"],
]);
expect(observations).toContainEqual({
operation: "RECEIVE",
outcome: "DROPPED",
transport: "BROADCAST",
reason: "STALE",
});
runtime.close();
});
it("keeps the per-source sequence watermark past the event TTL", () => {
const network = new FakeBroadcastNetwork();
let currentTime = NOW;
const runtime = createBrowserCrossContextInvalidation(
dependencies("tab-b", {
createBroadcastChannel: network.createChannel,
nowEpochMilliseconds: () => currentTime,
}),
);
const delivered: CrossContextInvalidationDelivery[] = [];
runtime.subscribe((delivery) => delivered.push(delivery));
network.emit(wireEvent({ eventId: "remote-event-00000001", sequence: 1 }));
// The source stays quiet longer than the 60 s event TTL.
currentTime += 61_000;
network.emit(
wireEvent({
eventId: "remote-event-00000002",
sequence: 2,
emittedAt: currentTime,
expiresAt: currentTime + 60_000,
}),
);
expect(
delivered.map(({ event, ordering }) => [
event.sequence,
ordering,
]),
).toEqual([
[1, "NEXT"],
[2, "NEXT"],
]);
runtime.close();
});
it("falls back when BroadcastChannel open or publish fails", () => {
const storageBus = new FakeStorageBus();
const firstStorage = storageBus.createEndpoint();
const secondStorage = storageBus.createEndpoint();
const firstNetwork = new FakeBroadcastNetwork();
const secondNetwork = new FakeBroadcastNetwork();
const first = createBrowserCrossContextInvalidation(
dependencies("tab-a", {
createBroadcastChannel: firstNetwork.createChannel,
storage: firstStorage.storage,
storageEvents: firstStorage.target,
}),
);
const second = createBrowserCrossContextInvalidation(
dependencies("tab-b", {
createBroadcastChannel: () => {
throw new DOMException("Denied", "SecurityError");
},
storage: secondStorage.storage,
storageEvents: secondStorage.target,
}),
);
firstNetwork.channels[0]!.failPost = true;
const received = vi.fn();
second.subscribe(received);
// R-2.3. Other tabs publish on BroadcastChannel only, so a tab whose
// channel failed to open misses their events and must not look healthy.
expect(second.getStatus()).toBe("DEGRADED_STORAGE_FALLBACK");
expect(first.publish({ topic: TOPIC, topicVersion: 1 })).toEqual({
ok: true,
transport: "STORAGE",
});
expect(first.getStatus()).toBe("ACTIVE_STORAGE_FALLBACK");
expect(received).toHaveBeenCalledOnce();
expect(firstStorage.storage.setCount).toBe(1);
expect(firstStorage.storage.removeCount).toBe(1);
expect(storageBus.values.has(STORAGE_PULSE_KEY)).toBe(false);
expect(secondNetwork.channels).toHaveLength(0);
expect(second.publish({ topic: TOPIC, topicVersion: 1 })).toEqual({
ok: true,
transport: "STORAGE",
});
expect(second.getStatus()).toBe("DEGRADED_STORAGE_FALLBACK");
first.close();
second.close();
});
it("keeps receiving broadcasts after its own broadcast publish fails", () => {
const network = new FakeBroadcastNetwork();
const storageBus = new FakeStorageBus();
const senderStorage = storageBus.createEndpoint();
const receiverStorage = storageBus.createEndpoint();
const sender = createBrowserCrossContextInvalidation(
dependencies("tab-a", {
createBroadcastChannel: network.createChannel,
storage: senderStorage.storage,
storageEvents: senderStorage.target,
}),
);
const receiver = createBrowserCrossContextInvalidation(
dependencies("tab-b", {
createBroadcastChannel: network.createChannel,
storage: receiverStorage.storage,
storageEvents: receiverStorage.target,
}),
);
network.channels[1]!.failPost = true;
expect(
receiver.publish({ topic: TOPIC, topicVersion: 1 }),
).toEqual({ ok: true, transport: "STORAGE" });
const delivered: CrossContextInvalidationDelivery[] = [];
receiver.subscribe((delivery) => delivered.push(delivery));
expect(
sender.publish({ topic: TOPIC, topicVersion: 1 }),
).toEqual({ ok: true, transport: "BROADCAST" });
expect(delivered.map(({ transport }) => transport)).toEqual([
"BROADCAST",
]);
expect(receiver.getStatus()).toBe("ACTIVE_STORAGE_FALLBACK");
sender.close();
receiver.close();
});
it("rejects storage pulses from another or unknown storage area", () => {
const storageBus = new FakeStorageBus();
const publisherStorage = storageBus.createEndpoint();
const receiverStorage = storageBus.createEndpoint();
const storageOnly = {
createBroadcastChannel: () => {
throw new DOMException("Denied", "SecurityError");
},
};
const publisher = createBrowserCrossContextInvalidation(
dependencies("tab-a", {
...storageOnly,
storage: publisherStorage.storage,
storageEvents: publisherStorage.target,
}),
);
const receiver = createBrowserCrossContextInvalidation(
dependencies("tab-b", {
...storageOnly,
storage: receiverStorage.storage,
storageEvents: receiverStorage.target,
}),
);
const received = vi.fn();
receiver.subscribe(received);
// N-09. sessionStorage and every other Storage area raise the same event,
// so an identical key and value from a foreign area must be ignored.
storageBus.emitAsForeignArea = true;
expect(
publisher.publish({ topic: TOPIC, topicVersion: 1 }),
).toMatchObject({ ok: true });
expect(received).not.toHaveBeenCalled();
storageBus.emitAsForeignArea = false;
expect(
publisher.publish({ topic: TOPIC, topicVersion: 1 }),
).toMatchObject({ ok: true });
expect(received).toHaveBeenCalledOnce();
publisher.close();
receiver.close();
});
it("enters explicit local-only degradation when every transport fails", () => {
const storageBus = new FakeStorageBus();
const endpoint = storageBus.createEndpoint();
endpoint.storage.failSet = true;
const observations: CrossContextInvalidationObservation[] = [];
const runtime = createBrowserCrossContextInvalidation(
dependencies("tab-a", {
createBroadcastChannel: () => {
throw new DOMException("Denied", "SecurityError");
},
storage: endpoint.storage,
storageEvents: endpoint.target,
observe: (observation) => observations.push(observation),
}),
);
expect(runtime.getStatus()).toBe("DEGRADED_STORAGE_FALLBACK");
expect(runtime.publish({ topic: TOPIC, topicVersion: 1 })).toEqual({
ok: false,
reason: "TRANSPORT_UNAVAILABLE",
});
expect(runtime.getStatus()).toBe("DEGRADED_LOCAL_ONLY");
expect(observations).toContainEqual({
operation: "PUBLISH",
outcome: "DEGRADED",
transport: "STORAGE",
reason: "STORAGE_PUBLISH_FAILED",
});
runtime.close();
});
it("isolates handler and diagnostics failures without leaking identifiers", () => {
const network = new FakeBroadcastNetwork();
const observations: CrossContextInvalidationObservation[] = [];
const runtime = createBrowserCrossContextInvalidation(
dependencies("tab-b", {
createBroadcastChannel: network.createChannel,
observe(observation) {
observations.push(observation);
if (observation.reason === "HANDLER_FAILED") {
throw new Error("diagnostics unavailable");
}
},
}),
);
const healthy = vi.fn();
runtime.subscribe(() => {
throw new Error("listener secret");
});
runtime.subscribe(healthy);
network.emit(
wireEvent({
eventId: "sensitive-event-identifier",
topic: TOPIC,
}),
);
expect(healthy).toHaveBeenCalledOnce();
expect(observations.some(({ reason }) => reason === "HANDLER_FAILED")).toBe(
true,
);
expect(JSON.stringify(observations)).not.toMatch(
/sensitive-event-identifier|sample-topic-alpha|cache-epoch-0001/,
);
runtime.close();
});
it("bounds TTL and LRU tracking instead of growing with remote sources", () => {
const network = new FakeBroadcastNetwork();
let currentTime = NOW;
const observations: CrossContextInvalidationObservation[] = [];
const runtime = createBrowserCrossContextInvalidation(
dependencies("tab-b", {
createBroadcastChannel: network.createChannel,
nowEpochMilliseconds: () => currentTime,
dedupeCapacity: 2,
sourceCapacity: 2,
observe: (observation) => observations.push(observation),
}),
);
const received = vi.fn();
runtime.subscribe(received);
const distinctSource = (
index: number,
eventId: string,
emittedAt = currentTime,
) =>
wireEvent({
eventId,
sourceId: `remote-source-${index}`,
sourceEpoch: `remote-epoch-${index}`,
emittedAt,
expiresAt: emittedAt + 1_000,
});
network.emit(distinctSource(1, "bounded-event-1"));
network.emit(distinctSource(2, "bounded-event-2"));
network.emit(distinctSource(3, "bounded-event-3"));
network.emit(distinctSource(1, "bounded-event-1"));
expect(received).toHaveBeenCalledTimes(4);
currentTime += 1_001;
network.emit(
distinctSource(3, "bounded-event-3", currentTime),
);
// The dedupe entry expired with the event TTL, but the sequence watermark
// does not expire, so the replay is dropped as stale, not redelivered.
expect(received).toHaveBeenCalledTimes(4);
expect(observations.at(-1)).toMatchObject({
outcome: "DROPPED",
reason: "STALE",
});
runtime.close();
});
it("cleans up listeners once and rejects queued work after close", () => {
const network = new FakeBroadcastNetwork();
const storage = new FakeStorageBus().createEndpoint();
const runtime = createBrowserCrossContextInvalidation(
dependencies("tab-b", {
createBroadcastChannel: network.createChannel,
storage: storage.storage,
storageEvents: storage.target,
}),
);
const received = vi.fn();
const unsubscribe = runtime.subscribe(received);
unsubscribe();
unsubscribe();
runtime.subscribe(received);
runtime.close();
runtime.close();
network.emit(wireEvent());
storage.target.emit(
STORAGE_PULSE_KEY,
JSON.stringify(wireEvent()),
);
expect(runtime.getStatus()).toBe("CLOSED");
expect(runtime.publish({ topic: TOPIC, topicVersion: 1 })).toEqual({
ok: false,
reason: "CLOSED",
});
expect(received).not.toHaveBeenCalled();
expect(network.channels[0]?.closeCount).toBe(1);
expect(network.channels[0]?.removeCount).toBe(1);
expect(storage.target.removeCount).toBe(1);
expect(storage.target.listeners.size).toBe(0);
});
it("fails invalid publish inputs closed without touching a provider", () => {
const network = new FakeBroadcastNetwork();
const runtime = createBrowserCrossContextInvalidation(
dependencies("tab-a", {
createBroadcastChannel: network.createChannel,
}),
);
expect(
runtime.publish({ topic: "not-allowlisted", topicVersion: 1 }),
).toEqual({ ok: false, reason: "INVALID_EVENT" });
expect(
runtime.publish({ topic: TOPIC, topicVersion: 2 }),
).toEqual({ ok: false, reason: "INVALID_EVENT" });
expect(network.messages).toHaveLength(0);
runtime.close();
});
it("observes why a publish failed instead of one envelope reason (2026-11-01 02-05)", () => {
const failedReasons = (
overrides: Partial<BrowserCrossContextInvalidationDependencies>,
topicVersion: number,
) => {
const reasons: string[] = [];
const runtime = createBrowserCrossContextInvalidation(
dependencies("tab-a", {
createBroadcastChannel: new FakeBroadcastNetwork().createChannel,
observe: (observation) => {
if (observation.operation === "PUBLISH") {
reasons.push(observation.reason);
}
},
...overrides,
}),
);
expect(runtime.publish({ topic: TOPIC, topicVersion })).toEqual({
ok: false,
reason: "INVALID_EVENT",
});
runtime.close();
return reasons;
};
expect(
failedReasons(
{
createEventId: () => {
throw new Error("secure random unavailable");
},
},
1,
),
).toEqual(["SECURE_RANDOM_UNAVAILABLE"]);
expect(failedReasons({}, 2)).toEqual(["TOPIC_REJECTED"]);
});
});