Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

Seanaye/fix/overeager opfs discard (#5828)

Sean Aye40dc208d2c18
diff --git a/apps/web/docs/graphql-normalized-cache-plan.md b/apps/web/docs/graphql-normalized-cache-plan.md
index 1e6745a7f1..c0435e7121 100644
--- a/apps/web/docs/graphql-normalized-cache-plan.md
+++ b/apps/web/docs/graphql-normalized-cache-plan.md
@@ -179,10 +179,21 @@ One Rust core engine, two hosts:
**Decision: Turso-backed persistence over OPFS, with one coordinated engine
owner across tabs.** The coordinator routes every request to the current
-engine worker and replaces that owner after abrupt loss. Browsers missing the
-required worker, lock, or OPFS capabilities use a storage-free no-op cache
-host. Tauri detection selects the native transport before browser capability
-checks. All paths remain behind the same `CacheHost` interface.
+engine worker and replaces that owner after abrupt loss. Browser worker links
+use Effect's scoped worker transport (`Worker` plus the
+`@effect/platform-browser` parent/runner adapters): Effect owns readiness,
+message-loop fibers, typed transport failures, and close framing. The elected
+engine also tracks every admitted request in a scoped `FiberSet`; graceful
+drain waits for that set to empty before closing the core, runner, and worker.
+The cache's validated envelopes, request ids, Web Locks, owner epochs,
+heartbeats, and replay policy remain application-owned. A normal `pagehide`
+uses a fenced navigation-departure message: the page terminates its dedicated
+worker, but the next owner opens the existing OPFS database. Only an
+unannounced liveness, heartbeat, transport, or engine failure selects
+`wipe-before-open`. Browsers missing the required worker, lock, or OPFS
+capabilities use a storage-free no-op cache host. Tauri
+detection selects the native transport before browser capability checks. All
+paths remain behind the same `CacheHost` interface.
### 4.3 Storage backends
@@ -294,8 +305,11 @@ apps/web/src/lib/graphql-cache/ # JS glue
- ~~JS glue~~ (`apps/web/src/lib/graphql-cache/`, alias `@graphql-cache/*`):
wire protocol (`protocol.ts`), `CacheWorkerCore` + SharedWorker entry,
and `createWorkerCacheHost` implementing `CacheHost` (with a storage-free
- no-op host when SharedWorker is unavailable). Type-checked; end-to-end browser exercise
- happens with the Phase 4 exchange integration.
+ no-op host when SharedWorker is unavailable). The page↔coordinator and
+ coordinator↔engine links run through Effect's browser Worker/WorkerRunner
+ protocol; cache-specific routing, fencing, and validation stay above that
+ transport. Type-checked; end-to-end browser exercise happens with the Phase
+ 4 exchange integration.
- ~~Tauri host~~ (`apps/web/tauri/graphql_cache_plugin`, in the *tauri*
workspace — it needs the patched tauri fork pinned there; path-deps on
`crates/client/{cache-core,cache-turso}`): engine behind an async mutex
diff --git a/apps/web/package.json b/apps/web/package.json
index f92f68588f..12c5a01eba 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -46,6 +46,7 @@
"@corvu/drawer": "^0.2.4",
"@date-fns/tz": "^1.4.1",
"@dinero.js/currencies": "2.0.0-alpha.8",
+ "@effect/platform-browser": "4.0.0-rc.111",
"@floating-ui/dom": "^1.7.4",
"@fontsource-variable/inter": "^5.2.8",
"@fontsource-variable/playfair-display": "^5.2.8",
diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts b/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts
index ce2a6a4e4a..5ec9ee9756 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts
@@ -9,11 +9,9 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { makeSubject, pipe, type Source, subscribe } from 'wonka';
import { normalizedCacheExchange } from '../exchange/normalized-cache-exchange';
import type { CacheRequest, CacheResponse } from '../protocol';
+import { installCacheCoordinatorWorker } from '../worker/cache-coordinator-runtime';
import { installCacheEngineWorker } from '../worker/cache-engine-runtime';
-import {
- type CoordinatorMessagePort,
- CoordinatorRouter,
-} from '../worker/coordinator-router';
+import { CoordinatorRouter } from '../worker/coordinator-router';
import type { CacheHost } from './types';
import { createWorkerCacheHost } from './worker-host';
@@ -69,21 +67,28 @@ function optimisticMutation(key: number, query: Operation['query']): Operation {
} as never);
}
-class LinkedMessagePort {
+class LinkedMessagePort extends EventTarget {
peer: LinkedMessagePort | undefined;
onmessage: ((event: MessageEvent<unknown>) => void) | null = null;
onmessageerror: (() => void) | null = null;
closed = false;
- postMessage(message: unknown, transfer: Transferable[] = []): void {
+ postMessage(
+ message: unknown,
+ transfer: Transferable[] | StructuredSerializeOptions = []
+ ): void {
const peer = this.peer;
if (this.closed || !peer || peer.closed) return;
+ const ports = (
+ Array.isArray(transfer) ? transfer : (transfer.transfer ?? [])
+ ) as MessagePort[];
queueMicrotask(() => {
if (peer.closed) return;
peer.onmessage?.({
data: message,
- ports: transfer,
+ ports,
} as unknown as MessageEvent);
+ peer.dispatchEvent(new MessageEvent('message', { data: message, ports }));
});
}
@@ -239,7 +244,10 @@ class IntegrationSharedWorker {
constructor(router: CoordinatorRouter) {
const channel = new LinkedMessageChannel();
this.port = channel.port1;
- router.connect(channel.port2 as unknown as CoordinatorMessagePort);
+ installCacheCoordinatorWorker({
+ endpoint: channel.port2 as unknown as MessagePort,
+ router,
+ });
}
fail(message: string): void {
@@ -502,7 +510,7 @@ describe('worker CacheHost coordinator integration', () => {
host.dispose();
});
- it('keeps API forwarding at zero when pagehide abandons an admitted enqueue', async () => {
+ it('keeps API forwarding at zero and preserves scope when pagehide abandons an admitted enqueue', async () => {
const gate = deferred();
enqueueGates.set('HoldPagehide', gate.promise);
localStorage.setItem('graphql-cache:scope', 'integration-scope');
@@ -528,10 +536,8 @@ describe('worker CacheHost coordinator integration', () => {
expect(results[0]?.error?.networkError).toMatchObject({
errorCode: 'admitted-enqueue-uncertain',
});
- await vi.waitFor(() =>
- expect(localStorage.getItem('graphql-cache:scope')).toBe(
- 'quarantine:integration-scope'
- )
+ expect(localStorage.getItem('graphql-cache:scope')).toBe(
+ 'integration-scope'
);
});
diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts
index f3a8c8be63..1653af502e 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts
@@ -256,6 +256,23 @@ describe('createWorkerCacheHost', () => {
expect(onInitializationError).toHaveBeenCalledOnce();
});
+ it('treats teardown as local cleanup after initialization failure and disposal', async () => {
+ configureAdapter = (fake) => {
+ fake.errors.set('init', 'injected initialization failure');
+ };
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+
+ await expect(host.clear()).rejects.toThrow(
+ 'injected initialization failure'
+ );
+ host.dispose();
+ await expect(host.teardown(7)).resolves.toBeUndefined();
+
+ expect(
+ requireAdapter().requests.filter((request) => request.kind === 'teardown')
+ ).toEqual([]);
+ });
+
it('samples origin storage pressure periodically and clears the timer on dispose', async () => {
vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
const estimate = vi.fn(async () => ({ usage: 25, quota: 100 }));
@@ -1131,7 +1148,10 @@ describe('createWorkerCacheHost', () => {
expect(adapter.dispose).toHaveBeenCalledWith({ graceful: true });
dispatchEvent(new Event('pagehide'));
- expect(adapter.dispose).toHaveBeenNthCalledWith(2, { graceful: false });
+ expect(adapter.dispose).toHaveBeenNthCalledWith(2, {
+ graceful: false,
+ preserveDatabase: true,
+ });
finishRetirement();
await retirement;
await expect(host.clear()).rejects.toThrow(
@@ -1241,7 +1261,7 @@ describe('createWorkerCacheHost', () => {
await draining;
});
- it('treats pagehide as uncertain for an admitted enqueue and quarantines its scope', async () => {
+ it('treats pagehide enqueue as uncertain without quarantining persistent storage', async () => {
configureAdapter = (fake) => {
fake.ignoredKinds.add('enqueue-optimistic-mutation');
};
@@ -1254,7 +1274,7 @@ describe('createWorkerCacheHost', () => {
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
const rejected = expect(mutation).rejects.toMatchObject({
- message: expect.stringContaining('abruptly disposed'),
+ message: expect.stringContaining('disposed for page navigation'),
errorCode: 'admitted-enqueue-uncertain',
});
await vi.waitFor(() =>
@@ -1271,11 +1291,10 @@ describe('createWorkerCacheHost', () => {
await rejected;
expect(adapter.dispose).toHaveBeenCalledOnce();
- expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });
- await vi.waitFor(() =>
- expect(localStorage.getItem('graphql-cache:scope')).toBe(
- 'quarantine:scope-1'
- )
- );
+ expect(adapter.dispose).toHaveBeenCalledWith({
+ graceful: false,
+ preserveDatabase: true,
+ });
+ expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
});
});
diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.ts
index 6d7c1c839c..1e8c32ebe4 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts
@@ -210,7 +210,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
let adapterDisposePromise: Promise<void> | undefined;
let adapterDisposeWasGraceful = false;
let adapterDisposalStarted = false;
- let disposalMode: 'graceful' | 'abrupt' | undefined;
+ let disposalMode: 'graceful' | 'navigation' | 'abrupt' | undefined;
let pagehideRegistered = false;
let legacyIdbDeletionStarted = false;
let telemetryRelayStarted = false;
@@ -418,14 +418,21 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
}
}
- function disposeAdapter(graceful: boolean): Promise<void> {
+ function disposeAdapter(
+ graceful: boolean,
+ preserveDatabase = false
+ ): Promise<void> {
if (adapterDisposePromise) {
if (!graceful && adapterDisposeWasGraceful && adapter) {
adapterDisposeWasGraceful = false;
try {
// A pagehide during graceful retirement must reach the adapter so it
- // can terminate and close instead of memoizing the old mode.
- void adapter.dispose({ graceful: false });
+ // can terminate immediately without classifying navigation as loss.
+ void adapter.dispose(
+ preserveDatabase
+ ? { graceful: false, preserveDatabase: true }
+ : { graceful: false }
+ );
} catch {
// The original disposal promise still owns final settlement.
}
@@ -436,7 +443,9 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
adapterDisposeWasGraceful = graceful;
try {
adapterDisposePromise = adapter
- .dispose({ graceful })
+ .dispose(
+ preserveDatabase ? { graceful, preserveDatabase: true } : { graceful }
+ )
.catch(() => undefined);
} catch {
// The host is already closed and cannot safely retry disposal.
@@ -523,13 +532,16 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
pageTelemetry?.relay.dispose();
}
- function startAdapterDisposal(graceful: boolean): void {
+ function startAdapterDisposal(
+ graceful: boolean,
+ preserveDatabase = false
+ ): void {
if (adapterDisposalStarted) {
- if (!graceful) void disposeAdapter(false);
+ if (!graceful) void disposeAdapter(false, preserveDatabase);
return;
}
adapterDisposalStarted = true;
- void disposeAdapter(graceful).then(() => {
+ void disposeAdapter(graceful, preserveDatabase).then(() => {
if (state !== 'disposing') return;
state = 'disposed';
unregisterPagehide();
@@ -548,11 +560,27 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
startAdapterDisposal(true);
}
- function disposeHost(graceful: boolean): void {
+ function disposeHost(graceful: boolean, preserveDatabase = false): void {
stopStorageHealthSampling();
if (state === 'disposed') return;
if (state === 'disposing') {
- if (graceful || disposalMode === 'abrupt') return;
+ if (
+ graceful ||
+ disposalMode === 'abrupt' ||
+ (preserveDatabase && disposalMode === 'navigation')
+ ) {
+ return;
+ }
+ if (preserveDatabase) {
+ disposalMode = 'navigation';
+ clearSubscribers();
+ rejectPending(
+ new Error('cache worker host was disposed for page navigation'),
+ true
+ );
+ startAdapterDisposal(false, true);
+ return;
+ }
disposalMode = 'abrupt';
const quarantine = hasAdmittedEnqueue();
clearSubscribers();
@@ -568,23 +596,33 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
state = 'disposing';
disposalMode = 'graceful';
clearSubscribers();
- // Keep pagehide armed through coordinator retirement so an abrupt close
- // can still terminate the adapter's in-progress graceful drain.
+ // Keep pagehide armed through coordinator retirement so navigation can
+ // terminate the worker without converting the handoff into a wipe.
finishGracefulDisposeIfDrained();
return;
}
- const quarantine = hasAdmittedEnqueue();
state = 'disposing';
- disposalMode = 'abrupt';
clearSubscribers();
+ if (preserveDatabase) {
+ disposalMode = 'navigation';
+ rejectPending(
+ new Error('cache worker host was disposed for page navigation'),
+ true
+ );
+ startAdapterDisposal(false, true);
+ return;
+ }
+
+ const quarantine = hasAdmittedEnqueue();
+ disposalMode = 'abrupt';
if (quarantine) void quarantineCacheScope(options.scope);
rejectPending(new Error('cache worker host was abruptly disposed'), true);
startAdapterDisposal(false);
}
function onPagehide(): void {
- disposeHost(false);
+ disposeHost(false, true);
}
function request(
@@ -984,7 +1022,19 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
registeredOpKeys.delete(opKey);
lostRegisteredOpKeys.delete(opKey);
replacementReadOpKeys.delete(opKey);
- await ensureInitialized();
+ // urql emits teardown while initialization-failure fallback is
+ // unsubscribing operations. Local registration cleanup is sufficient
+ // when no usable engine generation remains.
+ if (state !== 'ready' && state !== 'initializing') return;
+ if (state === 'initializing') {
+ try {
+ await ensureInitialized();
+ } catch {
+ return;
+ }
+ }
+ // Disposal or owner loss can win while an initialization await yields.
+ if (state !== 'ready') return;
await request({ kind: 'teardown', opId: opId(opKey) });
},
diff --git a/apps/web/src/lib/graphql-cache/telemetry.ts b/apps/web/src/lib/graphql-cache/telemetry.ts
index ec40b78630..386ad31fbf 100644
--- a/apps/web/src/lib/graphql-cache/telemetry.ts
+++ b/apps/web/src/lib/graphql-cache/telemetry.ts
@@ -116,6 +116,7 @@ export const CACHE_OWNER_EVENTS = [
'activated',
'graceful-drain-started',
'graceful-drain-completed',
+ 'navigation-departure',
'abrupt-loss',
'replacement',
'multiple-owner-detected',
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.browser.e2e.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.browser.e2e.ts
index 9e123d941b..a8c8addf11 100644
--- a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.browser.e2e.ts
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle.browser.e2e.ts
@@ -189,6 +189,54 @@ test('Cache exact host stays navigation-lazy, preserves offline handoff, resets
await page.evaluate(() => window.cacheLifecycleHarness.dispose());
});
+test('Cache normal offline reload reopens the existing OPFS cache', async ({
+ context,
+ page,
+ request,
+}, testInfo) => {
+ const scope = `cache-lifecycle-offline-reload-${crypto.randomUUID()}`;
+ const path = harnessPath(testInfo.project.name);
+ await page.goto(`${path}?treatment=true&scope=${encodeURIComponent(scope)}`);
+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');
+ await page.evaluate(() => window.cacheLifecycleHarness.startSingle());
+ await page.evaluate(() =>
+ window.cacheLifecycleHarness.write(
+ 'offline-reload-preserved',
+ 'cache-lifecycle-offline-reload-user'
+ )
+ );
+ expect(
+ isHit(await page.evaluate(() => window.cacheLifecycleHarness.read()))
+ ).toBe(true);
+
+ // Keep only the already-known test app shell reachable while Chromium's
+ // browser context is offline. Any product API request remains unavailable.
+ const origin = new URL(page.url()).origin;
+ await context.route(`${origin}/**`, async (route) => {
+ const browserRequest = route.request();
+ if (browserRequest.method() !== 'GET') {
+ await route.abort('internetdisconnected');
+ return;
+ }
+ const response = await request.get(browserRequest.url(), {
+ headers: browserRequest.headers(),
+ });
+ await route.fulfill({ response });
+ });
+ await context.setOffline(true);
+ await page.reload();
+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');
+
+ await page.evaluate(() => window.cacheLifecycleHarness.startSingle());
+ const reloaded = await page.evaluate(() =>
+ window.cacheLifecycleHarness.read()
+ );
+ expect(isHit(reloaded)).toBe(true);
+
+ await context.setOffline(false);
+ await page.evaluate(() => window.cacheLifecycleHarness.dispose());
+});
+
test('Cache real standby tab close preserves the same active engine', async ({
context,
page,
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts
index 75ecb37ef3..80087a8d1f 100644
--- a/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts
@@ -77,8 +77,12 @@ let activationValue: PageToEngineEnvelope | undefined;
let telemetry: BroadcastChannel | undefined;
let ignoreHeartbeats = false;
+const sendEngine = (message: EngineToCoordinatorEnvelope): void => {
+ controlPort?.postMessage([1, message]);
+};
+
const sendStaleResponse = (ownerEpoch: number, routeId: number): void => {
- controlPort?.postMessage(
+ sendEngine(
withVersion<EngineToCoordinatorEnvelope>({
kind: 'engine-response',
ownerEpoch,
@@ -165,14 +169,22 @@ async function activate(
database = await openDatabase(activation.scope);
const activeDatabase = database;
port.onmessage = (event: MessageEvent<unknown>) => {
- const parsed = validateCoordinatorToEngineEnvelope(event.data);
+ if (Array.isArray(event.data) && event.data[0] === 1) {
+ requestShutdown?.();
+ return;
+ }
+ const payload =
+ Array.isArray(event.data) && event.data[0] === 0
+ ? event.data[1]
+ : event.data;
+ const parsed = validateCoordinatorToEngineEnvelope(payload);
if (!parsed.ok) return;
const message: CoordinatorToEngineEnvelope = parsed.value;
if (message.ownerEpoch !== activation.ownerEpoch) return;
switch (message.kind) {
case 'heartbeat':
if (!ignoreHeartbeats) {
- port.postMessage(
+ sendEngine(
withVersion<EngineToCoordinatorEnvelope>({
kind: 'heartbeat-ack',
ownerEpoch: activation.ownerEpoch,
@@ -211,7 +223,7 @@ async function activate(
error instanceof Error ? error.message : String(error),
};
}
- port.postMessage(
+ sendEngine(
withVersion<EngineToCoordinatorEnvelope>({
kind: 'engine-response',
ownerEpoch: activation.ownerEpoch,
@@ -224,7 +236,7 @@ async function activate(
(message.request.kind === 'write' ||
message.request.kind === 'clear')
) {
- port.postMessage(
+ sendEngine(
withVersion<EngineToCoordinatorEnvelope>({
kind: 'engine-push',
ownerEpoch: activation.ownerEpoch,
@@ -237,7 +249,8 @@ async function activate(
}
};
port.start();
- port.postMessage(
+ port.postMessage([0]);
+ sendEngine(
withVersion<EngineToCoordinatorEnvelope>({
kind: 'engine-ready',
tabId: activation.tabId,
@@ -264,7 +277,7 @@ async function activate(
await queue;
database.close();
database = undefined;
- port.postMessage(
+ sendEngine(
withVersion<EngineToCoordinatorEnvelope>({
kind: 'engine-drained',
tabId: activation.tabId,
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/fake-coordinator.shared-worker.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-coordinator.shared-worker.ts
index 1c54c1c56d..163ceb4dd1 100644
--- a/apps/web/src/lib/graphql-cache/worker/browser-test/fake-coordinator.shared-worker.ts
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-coordinator.shared-worker.ts
@@ -1,17 +1,12 @@
/// <reference lib="webworker" />
+import { installCacheCoordinatorWorker } from '../cache-coordinator-runtime';
import { CoordinatorRouter } from '../coordinator-router';
-declare const self: SharedWorkerGlobalScope;
-
const router = new CoordinatorRouter();
+installCacheCoordinatorWorker({ router });
let telemetry: BroadcastChannel | undefined;
-self.onconnect = (event: MessageEvent) => {
- const port = event.ports[0];
- if (port) router.connect(port);
-};
-
setInterval(() => {
const snapshot = router.snapshot();
if (!snapshot) return;
diff --git a/apps/web/src/lib/graphql-cache/worker/cache-coordinator-runtime.test.ts b/apps/web/src/lib/graphql-cache/worker/cache-coordinator-runtime.test.ts
new file mode 100644
index 0000000000..3626dd4347
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/cache-coordinator-runtime.test.ts
@@ -0,0 +1,105 @@
+import * as Effect from 'effect/Effect';
+import { describe, expect, it, vi } from 'vitest';
+import { installCacheCoordinatorWorker } from './cache-coordinator-runtime';
+import type { CoordinatorToTabEnvelope } from './coordinator-protocol';
+import type {
+ CoordinatorMessagePort,
+ CoordinatorRouter,
+} from './coordinator-router';
+import {
+ EFFECT_WORKER_REQUEST_TAG,
+ EFFECT_WORKER_RESPONSE_TAG,
+} from './effect-worker-transport';
+
+class FakeEndpoint extends EventTarget {
+ readonly sent: unknown[] = [];
+ failOutbound = false;
+ closed = false;
+
+ postMessage(message: unknown): void {
+ if (
+ this.failOutbound &&
+ Array.isArray(message) &&
+ message[0] === EFFECT_WORKER_RESPONSE_TAG &&
+ message.length > 1
+ ) {
+ throw new Error('outbound send failed');
+ }
+ this.sent.push(message);
+ }
+
+ start(): void {}
+
+ close(): void {
+ this.closed = true;
+ }
+
+ receive(message: unknown): void {
+ this.dispatchEvent(
+ new MessageEvent('message', {
+ data: [EFFECT_WORKER_REQUEST_TAG, message],
+ })
+ );
+ }
+}
+
+const message = {
+ coordinatorVersion: 2,
+ kind: 'disconnect-tab',
+ tabId: 'tab-a',
+ reason: 'test',
+} as const;
+
+const setup = () => {
+ const endpoint = new FakeEndpoint();
+ const ports: CoordinatorMessagePort[] = [];
+ const connect = vi.fn((port: CoordinatorMessagePort) => {
+ ports.push(port);
+ });
+ const runner = installCacheCoordinatorWorker({
+ endpoint: endpoint as unknown as MessagePort,
+ router: { connect } as unknown as CoordinatorRouter,
+ });
+ return { connect, endpoint, ports, runner };
+};
+
+describe('cache coordinator runtime', () => {
+ it('does not recreate a port after the router closes it', async () => {
+ const { connect, endpoint, ports, runner } = setup();
+ endpoint.receive(message);
+ await vi.waitFor(() => expect(connect).toHaveBeenCalledOnce());
+
+ ports[0]?.close();
+ endpoint.receive(message);
+ await Promise.resolve();
+
+ expect(connect).toHaveBeenCalledOnce();
+ await Effect.runPromise(runner.close());
+ });
+
+ it('contains failed sends and leaves the closed port terminal', async () => {
+ const { connect, endpoint, ports, runner } = setup();
+ const onmessageerror = vi.fn();
+ connect.mockImplementation((port: CoordinatorMessagePort) => {
+ ports.push(port);
+ port.onmessageerror = onmessageerror;
+ });
+ endpoint.receive(message);
+ await vi.waitFor(() => expect(connect).toHaveBeenCalledOnce());
+ endpoint.failOutbound = true;
+
+ expect(() =>
+ ports[0]?.postMessage({
+ coordinatorVersion: 2,
+ kind: 'protocol-error',
+ error: 'test',
+ } satisfies CoordinatorToTabEnvelope)
+ ).not.toThrow();
+ expect(onmessageerror).toHaveBeenCalledOnce();
+
+ endpoint.receive(message);
+ await Promise.resolve();
+ expect(connect).toHaveBeenCalledOnce();
+ await Effect.runPromise(runner.close());
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/worker/cache-coordinator-runtime.ts b/apps/web/src/lib/graphql-cache/worker/cache-coordinator-runtime.ts
new file mode 100644
index 0000000000..5527ef5758
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/cache-coordinator-runtime.ts
@@ -0,0 +1,89 @@
+/// <reference lib="webworker" />
+
+import * as Effect from 'effect/Effect';
+import type {
+ CoordinatorToTabEnvelope,
+ TabToCoordinatorEnvelope,
+} from './coordinator-protocol';
+import {
+ type CoordinatorMessagePort,
+ CoordinatorRouter,
+} from './coordinator-router';
+import {
+ createEffectWorkerRunnerTransport,
+ type EffectWorkerRunnerTransport,
+} from './effect-worker-transport';
+
+export interface CacheCoordinatorRuntimeOptions {
+ endpoint?: MessagePort | Window;
+ router?: CoordinatorRouter;
+}
+
+/** Installs the SharedWorker-side Effect runner around CoordinatorRouter. */
+export function installCacheCoordinatorWorker(
+ options: CacheCoordinatorRuntimeOptions = {}
+): EffectWorkerRunnerTransport<CoordinatorToTabEnvelope> {
+ const router = options.router ?? new CoordinatorRouter();
+ const ports = new Map<number, CoordinatorMessagePort>();
+ const closedPortIds = new Set<number>();
+ let runner!: EffectWorkerRunnerTransport<CoordinatorToTabEnvelope>;
+
+ const portFor = (portId: number): CoordinatorMessagePort => {
+ const existing = ports.get(portId);
+ if (existing) return existing;
+ const port: CoordinatorMessagePort = {
+ onmessage: null,
+ onmessageerror: null,
+ postMessage(message: unknown, transfers?: Transferable[]): void {
+ try {
+ Effect.runSync(
+ runner.send(portId, message as CoordinatorToTabEnvelope, transfers)
+ );
+ } catch (error) {
+ if (ports.get(portId) !== port) return;
+ ports.delete(portId);
+ closedPortIds.add(portId);
+ port.onmessageerror?.({ data: error } as MessageEvent);
+ }
+ },
+ start(): void {},
+ close(): void {
+ if (ports.get(portId) === port) ports.delete(portId);
+ closedPortIds.add(portId);
+ },
+ };
+ closedPortIds.delete(portId);
+ ports.set(portId, port);
+ router.connect(port);
+ return port;
+ };
+
+ runner = createEffectWorkerRunnerTransport<
+ TabToCoordinatorEnvelope,
+ CoordinatorToTabEnvelope
+ >({
+ endpoint: options.endpoint ?? (self as unknown as Window),
+ onMessage(portId, message) {
+ if (closedPortIds.has(portId)) return;
+ portFor(portId).onmessage?.({
+ data: message,
+ ports: [],
+ } as unknown as MessageEvent<unknown>);
+ },
+ onDisconnect(portId) {
+ const port = ports.get(portId);
+ ports.delete(portId);
+ closedPortIds.add(portId);
+ port?.onmessageerror?.({} as MessageEvent);
+ },
+ onError(error) {
+ for (const [portId, port] of ports) {
+ ports.delete(portId);
+ closedPortIds.add(portId);
+ port.onmessageerror?.({ data: error } as MessageEvent);
+ }
+ },
+ });
+
+ return runner;
+}
diff --git a/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.ts b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.ts
index 90ad4b5b4b..aca24db805 100644
--- a/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.ts
+++ b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.ts
@@ -13,9 +13,13 @@ import {
type CoordinatorMessagePort,
CoordinatorRouter,
} from './coordinator-router';
+import {
+ EFFECT_WORKER_REQUEST_TAG,
+ EFFECT_WORKER_RESPONSE_TAG,
+} from './effect-worker-transport';
import type { CacheWorkerCoreOptions } from './worker-core';
-class FakePort {
+class FakePort extends EventTarget {
readonly messages: unknown[] = [];
closed = false;
started = false;
@@ -35,7 +39,10 @@ class FakePort {
}
receive(message: unknown): void {
- this.onmessage?.({ data: message, ports: [] } as unknown as MessageEvent);
+ const event = new MessageEvent('message', {
+ data: [EFFECT_WORKER_REQUEST_TAG, message],
+ });
+ this.dispatchEvent(event);
}
}
@@ -75,13 +82,20 @@ const activation = (
hotCapacity: 11,
});
+const effectPayload = (message: unknown): unknown =>
+ Array.isArray(message) && message[0] === EFFECT_WORKER_RESPONSE_TAG
+ ? message[1]
+ : message;
+
const messagesOfKind = <T extends string>(port: FakePort, kind: T) =>
- port.messages.filter(
- (message): message is Record<string, unknown> & { kind: T } =>
- typeof message === 'object' &&
- message !== null &&
- (message as { kind?: unknown }).kind === kind
- );
+ port.messages
+ .map(effectPayload)
+ .filter(
+ (message): message is Record<string, unknown> & { kind: T } =>
+ typeof message === 'object' &&
+ message !== null &&
+ (message as { kind?: unknown }).kind === kind
+ );
const registerTab = async (
router: CoordinatorRouter,
@@ -110,20 +124,18 @@ const attachRuntime = async (
if (outbound) {
const postMessage = channel.port2.postMessage.bind(channel.port2);
channel.port2.postMessage = ((message: unknown) => {
- outbound.push(message);
+ const payload = effectPayload(message);
+ if (payload !== undefined) outbound.push(payload);
postMessage(message);
}) as MessagePort['postMessage'];
}
- await router.handleTabMessage(
- tabPort as CoordinatorMessagePort,
- {
- ...version,
- kind: 'attach-engine-port',
- tabId,
- ownerEpoch,
- },
- [channel.port1]
- );
+ await router.handleTabMessage(tabPort as CoordinatorMessagePort, {
+ ...version,
+ kind: 'attach-engine-port',
+ tabId,
+ ownerEpoch,
+ enginePort: channel.port1,
+ });
const scope = new FakeWorkerScope();
installCacheEngineWorker({
scope,
@@ -380,6 +392,7 @@ describe('cache engine worker runtime', () => {
expect(order).toEqual(['request', 'drain']);
expect(
direct.messages
+ .map(effectPayload)
.filter(
(message) =>
typeof message === 'object' &&
@@ -394,6 +407,144 @@ describe('cache engine worker runtime', () => {
expect(scope.closed).toBe(true);
});
+ it('drops core messages after the runner closes during drain', async () => {
+ const scope = new FakeWorkerScope();
+ const direct = new FakePort();
+ let corePort: { postMessage(message: unknown): void } | undefined;
+ installCacheEngineWorker({
+ scope,
+ ownerLockIsHeld: async () => true,
+ createCore: () => ({
+ addPort: (port) => {
+ corePort = port;
+ },
+ handleRequest: async (port, request) => {
+ port.postMessage({ id: request.id, ok: true, result: null });
+ },
+ drain: vi.fn(),
+ }),
+ });
+ scope.activate(activation(), direct);
+ await vi.waitFor(() => expect(corePort).toBeDefined());
+
+ direct.receive({
+ ...version,
+ kind: 'drain-engine',
+ ownerEpoch: 7,
+ });
+ await vi.waitFor(() => expect(scope.closed).toBe(true));
+
+ expect(() =>
+ corePort?.postMessage({ id: 99, ok: true, result: null })
+ ).not.toThrow();
+ expect(messagesOfKind(direct, 'engine-response')).toHaveLength(0);
+ });
+
+ it('joins every admitted request fiber before draining the core', async () => {
+ const scope = new FakeWorkerScope();
+ const direct = new FakePort();
+ const order: string[] = [];
+ let markRequestStarted!: () => void;
+ const requestStarted = new Promise<void>((resolve) => {
+ markRequestStarted = resolve;
+ });
+ let releaseRequest!: () => void;
+ const requestBlocked = new Promise<void>((resolve) => {
+ releaseRequest = resolve;
+ });
+ installCacheEngineWorker({
+ scope,
+ ownerLockIsHeld: async () => true,
+ createCore: () => ({
+ addPort: vi.fn(),
+ handleRequest: async (port, request) => {
+ if (request.kind === 'init') {
+ port.postMessage({ id: request.id, ok: true, result: null });
+ return;
+ }
+ order.push('request-started');
+ markRequestStarted();
+ await requestBlocked;
+ order.push('request-finished');
+ port.postMessage({ id: request.id, ok: true, result: null });
+ },
+ drain: async () => {
+ order.push('drain');
+ },
+ }),
+ });
+ scope.activate(activation(), direct);
+ await vi.waitFor(() =>
+ expect(messagesOfKind(direct, 'engine-ready')).toHaveLength(1)
+ );
+
+ direct.receive({
+ ...version,
+ kind: 'engine-request',
+ ownerEpoch: 7,
+ routeId: 24,
+ request: { id: 24, kind: 'clear' },
+ });
+ await requestStarted;
+ direct.receive({
+ ...version,
+ kind: 'drain-engine',
+ ownerEpoch: 7,
+ });
+ await Promise.resolve();
+ expect(order).toEqual(['request-started']);
+
+ releaseRequest();
+ await vi.waitFor(() =>
+ expect(messagesOfKind(direct, 'engine-drained')).toHaveLength(1)
+ );
+
+ expect(order).toEqual(['request-started', 'request-finished', 'drain']);
+ expect(scope.closed).toBe(true);
+ });
+
+ it('turns an admission fiber failure into one engine fatal', async () => {
+ const scope = new FakeWorkerScope();
+ const direct = new FakePort();
+ const handleRequest = vi.fn(async (port, request: CacheRequest) => {
+ if (request.kind === 'init') {
+ port.postMessage({ id: request.id, ok: true, result: null });
+ return;
+ }
+ throw new Error('injected admission failure');
+ });
+ installCacheEngineWorker({
+ scope,
+ ownerLockIsHeld: async () => true,
+ createCore: () => ({
+ addPort: vi.fn(),
+ handleRequest,
+ drain: vi.fn(),
+ }),
+ });
+ scope.activate(activation(), direct);
+ await vi.waitFor(() =>
+ expect(messagesOfKind(direct, 'engine-ready')).toHaveLength(1)
+ );
+
+ direct.receive({
+ ...version,
+ kind: 'engine-request',
+ ownerEpoch: 7,
+ routeId: 25,
+ request: { id: 25, kind: 'clear' },
+ });
+ await vi.waitFor(() =>
+ expect(messagesOfKind(direct, 'engine-fatal')).toHaveLength(1)
+ );
+
+ expect(messagesOfKind(direct, 'engine-fatal')[0]).toMatchObject({
+ reason: expect.stringContaining('injected admission failure'),
+ fatalCode: 'runtime-failure',
+ });
+ expect(messagesOfKind(direct, 'engine-response')).toHaveLength(0);
+ });
+
it('does not replay a completed mutation or leak its stale response and push after owner loss', async () => {
const router = new CoordinatorRouter({
verifyTabLockHeld: async () => true,
diff --git a/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.ts b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.ts
index d7b5ee1ceb..1c22c13300 100644
--- a/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.ts
+++ b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.ts
@@ -1,5 +1,11 @@
/// <reference lib="webworker" />
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as FiberSet from 'effect/FiberSet';
+import * as Scope from 'effect/Scope';
+import { match } from 'ts-pattern';
import type { CacheRequest, CacheResponse } from '../protocol';
import {
type CacheTelemetryRecorderLike,
@@ -19,6 +25,10 @@ import {
validateCoordinatorToEngineEnvelope,
validatePageToEngineEnvelope,
} from './coordinator-protocol';
+import {
+ createEffectWorkerRunnerTransport,
+ type EffectWorkerRunnerTransport,
+} from './effect-worker-transport';
import { cacheWasmLinearMemoryBytes } from './wasm-module';
import { CacheWorkerCore, type CacheWorkerCoreOptions } from './worker-core';
@@ -175,9 +185,34 @@ async function activate(
? 'reset-storage-uncertain'
: 'opened-existing';
let draining = false;
- const pendingAdmissions = new Set<Promise<void>>();
+ // Keep every admitted handler and graceful drain in one explicit scope.
+ // Abrupt owner loss still relies on DedicatedWorker termination; graceful
+ // retirement closes this scope only after all admission fibers are empty.
+ const lifecycleScope = Effect.runSync(Scope.make());
+ const admissions = Effect.runSync(
+ Scope.provide(lifecycleScope)(FiberSet.make<void, never>())
+ );
+ const lifecycleFibers = Effect.runSync(
+ Scope.provide(lifecycleScope)(FiberSet.make<void, never>())
+ );
+ const runAdmission = Effect.runSync(FiberSet.runtime(admissions)());
+ const runLifecycle = Effect.runSync(FiberSet.runtime(lifecycleFibers)());
+ let closeLifecyclePromise: Promise<void> | undefined;
+ const closeLifecycle = (): Promise<void> => {
+ closeLifecyclePromise ??= Effect.runPromise(
+ Scope.close(lifecycleScope, Exit.void)
+ );
+ return closeLifecyclePromise;
+ };
+ let runnerFailed = false;
+ let runner!: EffectWorkerRunnerTransport<EngineToCoordinatorEnvelope>;
const post = (message: EngineToCoordinatorEnvelope): void => {
- directPort.postMessage(message);
+ try {
+ Effect.runSync(runner.send(0, message));
+ } catch (error) {
+ if (runnerFailed || runner.isClosed()) return;
+ throw error;
+ }
};
const fatal = (
reason: string,
@@ -186,6 +221,7 @@ async function activate(
if (failed) return;
failed = true;
emitEvent({ kind: 'fatal', activation, reason, fatalCode });
+ if (runnerFailed) return;
post(
withVersion<EngineToCoordinatorEnvelope>({
kind: 'engine-fatal',
@@ -243,80 +279,104 @@ async function activate(
const admitRequest = (request: CacheRequest): void => {
emitEvent({ kind: 'request-admitted', activation, request });
- if (!hooks?.beforeRequest) {
- void core.handleRequest(enginePort, request);
- return;
- }
- const admission = Promise.resolve(hooks.beforeRequest(request, activation))
- .then(async () => {
+ runAdmission(
+ Effect.promise(async () => {
+ await hooks?.beforeRequest?.(request, activation);
if (!failed) await core.handleRequest(enginePort, request);
- })
- .catch((error: unknown) => {
- fatal(`engine request hook failed: ${errorMessage(error)}`);
- });
- pendingAdmissions.add(admission);
- void admission.finally(() => pendingAdmissions.delete(admission));
+ }).pipe(
+ Effect.catchCause((cause) =>
+ Effect.sync(() => {
+ fatal(
+ `engine request admission failed: ${errorMessage(Cause.squash(cause))}`
+ );
+ })
+ )
+ )
+ );
};
- directPort.onmessage = (event: MessageEvent<unknown>) => {
- const parsed = validateCoordinatorToEngineEnvelope(event.data);
- if (!parsed.ok) {
- fatal(`invalid coordinator envelope: ${parsed.error}`);
- return;
- }
- const message: CoordinatorToEngineEnvelope = parsed.value;
- if (failed) return;
- if (message.ownerEpoch !== activation.ownerEpoch) {
- fatal('coordinator envelope owner epoch does not match activation');
- return;
- }
- switch (message.kind) {
- case 'engine-request':
- if (draining) {
- fatal('coordinator routed a request after drain began');
- return;
- }
- admitRequest(message.request);
- break;
- case 'drain-engine':
- if (draining) return;
- draining = true;
- void (async () => {
- await Promise.all(pendingAdmissions);
- await core.drain();
- recordLinearMemory(true);
- emitEvent({ kind: 'drained', activation });
- telemetry.flush();
+ runner = createEffectWorkerRunnerTransport<
+ CoordinatorToEngineEnvelope,
+ EngineToCoordinatorEnvelope
+ >({
+ endpoint: directPort,
+ onMessage: (_portId, rawMessage) => {
+ const parsed = validateCoordinatorToEngineEnvelope(rawMessage);
+ if (!parsed.ok) {
+ fatal(`invalid coordinator envelope: ${parsed.error}`);
+ return;
+ }
+ const message: CoordinatorToEngineEnvelope = parsed.value;
+ if (failed) return;
+ if (message.ownerEpoch !== activation.ownerEpoch) {
+ fatal('coordinator envelope owner epoch does not match activation');
+ return;
+ }
+ match(message)
+ .with({ kind: 'engine-request' }, ({ request }) => {
+ if (draining) {
+ fatal('coordinator routed a request after drain began');
+ return;
+ }
+ admitRequest(request);
+ })
+ .with({ kind: 'drain-engine' }, () => {
+ if (draining) return;
+ draining = true;
+ const drainFiber = runLifecycle(
+ Effect.gen(function* () {
+ yield* FiberSet.awaitEmpty(admissions);
+ yield* Effect.promise(() => Promise.resolve(core.drain()));
+ recordLinearMemory(true);
+ emitEvent({ kind: 'drained', activation });
+ telemetry.flush();
+ post(
+ withVersion<EngineToCoordinatorEnvelope>({
+ kind: 'engine-drained',
+ tabId: activation.tabId,
+ ownerEpoch: activation.ownerEpoch,
+ })
+ );
+ yield* runner.close();
+ workerScope.close();
+ }).pipe(
+ Effect.catchCause((cause) =>
+ Effect.sync(() => {
+ fatal(
+ `engine drain failed: ${errorMessage(Cause.squash(cause))}`
+ );
+ })
+ )
+ )
+ );
+ drainFiber.addObserver(() => {
+ void closeLifecycle().catch(() => undefined);
+ });
+ })
+ .with({ kind: 'heartbeat' }, ({ heartbeatId }) => {
+ recordLinearMemory(false);
+ core.recordCachedQueueDiagnostics?.();
post(
withVersion<EngineToCoordinatorEnvelope>({
- kind: 'engine-drained',
- tabId: activation.tabId,
+ kind: 'heartbeat-ack',
ownerEpoch: activation.ownerEpoch,
+ heartbeatId,
})
);
- directPort.close();
- workerScope.close();
- })().catch((error: unknown) =>
- fatal(`engine drain failed: ${errorMessage(error)}`)
- );
- break;
- case 'heartbeat':
- recordLinearMemory(false);
- core.recordCachedQueueDiagnostics?.();
- post(
- withVersion<EngineToCoordinatorEnvelope>({
- kind: 'heartbeat-ack',
- ownerEpoch: activation.ownerEpoch,
- heartbeatId: message.heartbeatId,
- })
- );
- break;
- }
- };
- directPort.onmessageerror = () => {
- fatal('coordinator direct MessagePort messageerror');
- };
- directPort.start();
+ })
+ .exhaustive();
+ },
+ onError: (error) => {
+ runnerFailed = true;
+ fatal(`coordinator Effect runner failed: ${error.message}`);
+ },
+ });
+ Effect.runSync(
+ Scope.addFinalizer(
+ lifecycleScope,
+ runner.close().pipe(Effect.catchCause(() => Effect.void))
+ )
+ );
try {
await initializeCore(core, activation);
@@ -369,6 +429,7 @@ async function activate(
: 'initialization-failed',
})
);
+ await closeLifecycle();
}
}
diff --git a/apps/web/src/lib/graphql-cache/worker/cache.coordinator.shared-worker.ts b/apps/web/src/lib/graphql-cache/worker/cache.coordinator.shared-worker.ts
index 05dbcb7816..440b9bd949 100644
--- a/apps/web/src/lib/graphql-cache/worker/cache.coordinator.shared-worker.ts
+++ b/apps/web/src/lib/graphql-cache/worker/cache.coordinator.shared-worker.ts
@@ -1,12 +1,5 @@
/// <reference lib="webworker" />
-import { CoordinatorRouter } from './coordinator-router';
+import { installCacheCoordinatorWorker } from './cache-coordinator-runtime';
-declare const self: SharedWorkerGlobalScope;
-
-const router = new CoordinatorRouter();
-
-self.onconnect = (event: MessageEvent) => {
- const port = event.ports[0];
- if (port) router.connect(port);
-};
+installCacheCoordinatorWorker();
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.ts
index 6124feb29d..ad24cc8d0d 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.ts
@@ -262,6 +262,77 @@ describe('CoordinatorCore', () => {
);
});
+ it('preserves storage across an intentional navigation departure', () => {
+ const core = new CoordinatorCore('scope');
+ core.registerTab('tab-a');
+ core.registerTab('tab-b');
+ ready(core, 'tab-a', 1, 'opened-existing');
+ core.request('tab-b', clear(9));
+
+ const departure = core.departForNavigation('tab-a', 1, 'page navigation');
+ expect(departure).toContainEqual({
+ kind: 'reject-request',
+ tabId: 'tab-b',
+ requestId: 9,
+ error: 'owner epoch 1 departed for navigation: page navigation',
+ errorCode: 'owner-epoch-lost',
+ });
+ expect(action(departure, 'elect-owner')).toEqual({
+ kind: 'elect-owner',
+ tabId: 'tab-b',
+ ownerEpoch: 2,
+ databaseAction: 'open-existing',
+ });
+ });
+
+ it('does not downgrade an interrupted recovery activation to open-existing', () => {
+ const core = new CoordinatorCore('scope');
+ core.registerTab('tab-a');
+ core.registerTab('tab-b');
+ ready(core, 'tab-a', 1, 'opened-existing');
+ core.ownerLost('tab-a', 1, 'engine failed');
+ expect(action(core.resumeAfterLoss(), 'elect-owner')).toMatchObject({
+ tabId: 'tab-b',
+ ownerEpoch: 2,
+ databaseAction: 'wipe-before-open',
+ });
+
+ expect(
+ action(
+ core.departForNavigation('tab-b', 2, 'recovery owner navigated'),
+ 'elect-owner'
+ )
+ ).toEqual({
+ kind: 'elect-owner',
+ tabId: 'tab-a',
+ ownerEpoch: 3,
+ databaseAction: 'wipe-before-open',
+ });
+ });
+
+ it('retains open-existing when a navigating owner has no standby', () => {
+ const core = new CoordinatorCore('scope');
+ core.registerTab('tab-a');
+ ready(core, 'tab-a', 1, 'opened-existing');
+
+ expect(core.departForNavigation('tab-a', 1, 'refresh')).toEqual([
+ { kind: 'close-engine-route', tabId: 'tab-a', ownerEpoch: 1 },
+ { kind: 'drop-tab', tabId: 'tab-a' },
+ ]);
+ expect(core.state).toEqual({
+ kind: 'waiting-for-tab',
+ nextDatabaseAction: 'open-existing',
+ });
+ expect(core.registerTab('tab-b')).toEqual([
+ {
+ kind: 'elect-owner',
+ tabId: 'tab-b',
+ ownerEpoch: 2,
+ databaseAction: 'open-existing',
+ },
+ ]);
+ });
+
it('uses standby liveness loss without failover and owner liveness loss with wipe', () => {
const core = new CoordinatorCore('scope');
core.registerTab('tab-a');
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-core.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-core.ts
index 317d97064b..7e118eb584 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-core.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-core.ts
@@ -303,6 +303,46 @@ export class CoordinatorCore {
return this.transitionToAbruptLoss(tabId, ownerEpoch, reason);
}
+ departForNavigation(
+ tabId: string,
+ ownerEpoch: OwnerEpoch,
+ reason: string
+ ): CoordinatorAction[] {
+ const state = this.stateValue;
+ if (
+ (state.kind !== 'active' &&
+ state.kind !== 'activating' &&
+ state.kind !== 'draining') ||
+ state.tabId !== tabId ||
+ state.ownerEpoch !== ownerEpoch
+ ) {
+ return this.recordProtocolViolation(
+ `unexpected navigation departure from ${tabId} at epoch ${ownerEpoch}`
+ );
+ }
+
+ const nextDatabaseAction: DatabaseAction =
+ state.kind === 'activating' ? state.databaseAction : 'open-existing';
+ const actions = this.rejectEpochRequests(
+ ownerEpoch,
+ `owner epoch ${ownerEpoch} departed for navigation: ${reason}`,
+ OWNER_EPOCH_LOST_ERROR_CODE
+ );
+ this.removeTabRecord(tabId);
+ this.retiringTabs.delete(tabId);
+ actions.push(
+ { kind: 'close-engine-route', tabId, ownerEpoch },
+ { kind: 'drop-tab', tabId }
+ );
+ this.stateValue = {
+ kind: 'waiting-for-tab',
+ nextDatabaseAction,
+ };
+ actions.push(...this.activateNext(nextDatabaseAction));
+ this.assertInvariants();
+ return actions;
+ }
+
tabLost(
tabId: string,
reason = 'tab liveness lock was released'
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.test.ts
index e2ab0ca6c4..1cce85333a 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.test.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.test.ts
@@ -6,22 +6,32 @@ import {
} from './coordinator-page-adapter';
import { CACHE_COORDINATOR_PROTOCOL_VERSION } from './coordinator-protocol';
-class FakeCoordinatorPort {
+class FakeCoordinatorPort extends EventTarget {
readonly messages: Array<{ message: unknown; transfer: Transferable[] }> = [];
onmessage: ((event: MessageEvent<unknown>) => void) | null = null;
- onmessageerror: (() => void) | null = null;
+ onmessageerror: (() => void) | null = () => {
+ this.dispatchEvent(new MessageEvent('messageerror'));
+ };
closed = false;
readonly events: string[] = [];
readonly throwKinds = new Set<string>();
postMessage(message: unknown, transfer: Transferable[] = []): void {
- const kind = String((message as { kind?: unknown }).kind);
+ if (Array.isArray(message) && message[0] === 1) {
+ this.events.push('post:effect-close');
+ return;
+ }
+ const payload =
+ Array.isArray(message) && message[0] === 0 ? message[1] : message;
+ const kind = String((payload as { kind?: unknown }).kind);
this.events.push(`post:${kind}`);
if (this.throwKinds.has(kind)) throw new Error(`${kind} send failed`);
- this.messages.push({ message, transfer });
+ this.messages.push({ message: payload, transfer });
}
- start(): void {}
+ start(): void {
+ this.dispatchEvent(new MessageEvent('message', { data: [0] }));
+ }
close(): void {
this.closed = true;
@@ -29,7 +39,7 @@ class FakeCoordinatorPort {
}
receive(message: unknown): void {
- this.onmessage?.({ data: message } as MessageEvent);
+ this.dispatchEvent(new MessageEvent('message', { data: [1, message] }));
}
}
@@ -171,8 +181,10 @@ describe('CacheCoordinatorPageAdapter', () => {
order.push('terminated');
};
coordinatorPort.postMessage = (message, transfer = []) => {
- coordinatorPort.messages.push({ message, transfer });
- if ((message as { kind?: string }).kind === 'engine-lost') {
+ const payload =
+ Array.isArray(message) && message[0] === 0 ? message[1] : message;
+ coordinatorPort.messages.push({ message: payload, transfer });
+ if ((payload as { kind?: string }).kind === 'engine-lost') {
order.push('loss-reported');
}
};
@@ -308,6 +320,45 @@ describe('CacheCoordinatorPageAdapter', () => {
expect(terminalErrors).toEqual(['coordinator construction failed']);
});
+ it('closes an unpublished SharedWorker when Effect transport setup fails', async () => {
+ const coordinatorPort = new FakeCoordinatorPort();
+ const addEventListener =
+ coordinatorPort.addEventListener.bind(coordinatorPort);
+ vi.spyOn(coordinatorPort, 'addEventListener').mockImplementation(
+ (type, listener, options) => {
+ if (type === 'messageerror') {
+ throw new Error('transport listener setup failed');
+ }
+ addEventListener(type, listener, options);
+ }
+ );
+ const terminalErrors: string[] = [];
+ const messages: unknown[] = [];
+ const adapter = createCacheCoordinatorPageAdapter({
+ scope: 'scope',
+ tabId: 'tab-a',
+ lockManager: heldLockManager(),
+ createSharedWorker: () => ({
+ port: coordinatorPort as unknown as MessagePort,
+ }),
+ createDedicatedWorker: () => new FakeWorker(),
+ onTerminalError: (error) => terminalErrors.push(error.message),
+ });
+ adapter.onmessage = (event) => messages.push(event.data);
+
+ adapter.postMessage({ id: 1, kind: 'clear' });
+ await vi.waitFor(() => expect(messages).toHaveLength(1));
+
+ expect(coordinatorPort.closed).toBe(true);
+ expect(coordinatorPort.events.filter((event) => event === 'close')).toEqual(
+ ['close']
+ );
+ expect(messages).toEqual([
+ { id: 1, ok: false, error: 'transport listener setup failed' },
+ ]);
+ expect(terminalErrors).toEqual(['transport listener setup failed']);
+ });
+
it('keeps registered coordinator protocol diagnostics advisory', async () => {
const coordinatorPort = new FakeCoordinatorPort();
const protocolErrors: string[] = [];
@@ -428,7 +479,9 @@ describe('CacheCoordinatorPageAdapter', () => {
expect(dedicatedFactory).not.toHaveBeenCalled();
expect(coordinatorPort.closed).toBe(true);
- expect(terminalErrors).toEqual(['coordinator MessagePort messageerror']);
+ expect(terminalErrors).toEqual([
+ 'coordinator Effect transport failed: Effect worker transport messageerror',
+ ]);
});
it.each(['register-tab', 'cache-request'] as const)(
@@ -556,11 +609,24 @@ describe('CacheCoordinatorPageAdapter', () => {
});
it.each([
- { graceful: true, throwKind: 'graceful-departure' },
- { graceful: false, throwKind: 'disconnect-tab' },
+ {
+ graceful: true,
+ preserveDatabase: false,
+ throwKind: 'graceful-departure',
+ },
+ {
+ graceful: false,
+ preserveDatabase: false,
+ throwKind: 'disconnect-tab',
+ },
+ {
+ graceful: false,
+ preserveDatabase: true,
+ throwKind: 'navigation-departure',
+ },
])(
- 'settles $graceful disposal when $throwKind send throws',
- async ({ graceful, throwKind }) => {
+ 'settles disposal when $throwKind send throws',
+ async ({ graceful, preserveDatabase, throwKind }) => {
const coordinatorPort = new FakeCoordinatorPort();
const worker = new FakeWorker();
const terminalErrors: string[] = [];
@@ -585,7 +651,7 @@ describe('CacheCoordinatorPageAdapter', () => {
coordinatorPort.receive(election(1));
coordinatorPort.throwKinds.add(throwKind);
- await adapter.dispose({ graceful });
+ await adapter.dispose({ graceful, preserveDatabase });
expect(worker.terminated).toBe(true);
expect(coordinatorPort.closed).toBe(true);
@@ -732,7 +798,7 @@ describe('CacheCoordinatorPageAdapter', () => {
]);
});
- it('escalates an owner graceful drain to abrupt disposal on pagehide', async () => {
+ it('escalates an owner graceful drain to storage-preserving navigation disposal', async () => {
const coordinatorPort = new FakeCoordinatorPort();
const worker = new FakeWorker();
const adapter = createCacheCoordinatorPageAdapter({
@@ -752,15 +818,23 @@ describe('CacheCoordinatorPageAdapter', () => {
const graceful = adapter.dispose({ graceful: true });
expect(worker.terminated).toBe(false);
- const abrupt = adapter.dispose({ graceful: false });
- expect(abrupt).toBe(graceful);
- await abrupt;
+ const navigation = adapter.dispose({
+ graceful: false,
+ preserveDatabase: true,
+ });
+ expect(navigation).toBe(graceful);
+ await navigation;
expect(worker.terminated).toBe(true);
expect(coordinatorPort.closed).toBe(true);
expect(
- coordinatorPort.events.filter((event) => event === 'post:disconnect-tab')
+ coordinatorPort.events.filter(
+ (event) => event === 'post:navigation-departure'
+ )
).toHaveLength(1);
+ expect(
+ coordinatorPort.events.filter((event) => event === 'post:disconnect-tab')
+ ).toHaveLength(0);
});
it('terminal-fails when the owned engine crashes during graceful drain', async () => {
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts
index b395f67d58..e165f8ada3 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-page-adapter.ts
@@ -1,3 +1,4 @@
+import * as Effect from 'effect/Effect';
import type { CacheRequest, WorkerMessage } from '../protocol';
import {
type CacheTelemetryRecorderLike,
@@ -13,6 +14,10 @@ import {
tabLivenessLockName,
validateCoordinatorToTabEnvelope,
} from './coordinator-protocol';
+import {
+ createEffectWorkerTransport,
+ type EffectWorkerTransport,
+} from './effect-worker-transport';
export interface SharedWorkerLike {
readonly port: MessagePort;
@@ -51,6 +56,13 @@ export interface CacheCoordinatorPageAdapterOptions {
export interface PageAdapterDisposeOptions {
graceful?: boolean;
+ /** Preserve OPFS when a normal page navigation cannot await a drain. */
+ preserveDatabase?: boolean;
+}
+
+interface CoordinatorConnection {
+ worker: SharedWorkerLike;
+ transport: EffectWorkerTransport<TabToCoordinatorEnvelope>;
}
const DEFAULT_GRACEFUL_TIMEOUT_MS = 10_000;
@@ -94,7 +106,7 @@ export class CacheCoordinatorPageAdapter {
) => DedicatedWorkerLike;
private readonly lockManager: Pick<LockManager, 'request'> | undefined;
private readonly gracefulTimeoutMs: number;
- private sharedWorker: SharedWorkerLike | undefined;
+ private coordinatorConnection: CoordinatorConnection | undefined;
private engineWorker: DedicatedWorkerLike | undefined;
private ownerEpoch: number | undefined;
private registered = false;
@@ -106,7 +118,7 @@ export class CacheCoordinatorPageAdapter {
private disposePromise: Promise<void> | undefined;
private resolveDispose: (() => void) | undefined;
private gracefulTimeout: ReturnType<typeof setTimeout> | undefined;
- private disposeMode: 'graceful' | 'abrupt' | undefined;
+ private disposeMode: 'graceful' | 'navigation' | 'abrupt' | undefined;
private pagehideRegistered = false;
private terminalErrorReported = false;
private readonly terminatedOwnerEpochs = new Set<number>();
@@ -190,13 +202,21 @@ export class CacheCoordinatorPageAdapter {
);
}
- /** Gracefully drains an owned engine, or immediately drops a standby tab. */
+ /** Drains gracefully, preserves storage for navigation, or drops abruptly. */
dispose(options: PageAdapterDisposeOptions = {}): Promise<void> {
const graceful = options.graceful === true;
+ const preserveDatabase = !graceful && options.preserveDatabase === true;
if (this.disposePromise) {
if (!graceful && this.disposeMode === 'graceful' && !this.closed) {
- this.disposeMode = 'abrupt';
- this.abortDispose('pagehide interrupted graceful page disposal');
+ if (preserveDatabase) {
+ this.disposeMode = 'navigation';
+ this.departForNavigation(
+ 'page navigation interrupted graceful page disposal'
+ );
+ } else {
+ this.disposeMode = 'abrupt';
+ this.abortDispose('pagehide interrupted graceful page disposal');
+ }
}
return this.disposePromise;
}
@@ -207,7 +227,7 @@ export class CacheCoordinatorPageAdapter {
this.settleDispose();
return this.disposePromise;
}
- if (!this.sharedWorker) {
+ if (!this.coordinatorConnection) {
this.disposeMode = 'abrupt';
this.closed = true;
this.registered = false;
@@ -218,7 +238,10 @@ export class CacheCoordinatorPageAdapter {
return this.disposePromise;
}
- if (graceful && this.ownerEpoch !== undefined) {
+ if (preserveDatabase) {
+ this.disposeMode = 'navigation';
+ this.departForNavigation('page navigation');
+ } else if (graceful && this.ownerEpoch !== undefined) {
this.disposeMode = 'graceful';
const ownerEpoch = this.ownerEpoch;
if (
@@ -255,6 +278,33 @@ export class CacheCoordinatorPageAdapter {
return this.disposePromise;
}
+ private departForNavigation(reason: string): void {
+ this.clearGracefulTimeout();
+ const ownerEpoch = this.ownerEpoch;
+ if (ownerEpoch !== undefined) {
+ this.terminateEngine(ownerEpoch, reason, false);
+ if (!this.closed) {
+ this.postCoordinator(
+ withVersion<TabToCoordinatorEnvelope>({
+ kind: 'navigation-departure',
+ tabId: this.tabId,
+ ownerEpoch,
+ reason,
+ })
+ );
+ }
+ } else if (!this.closed) {
+ this.postCoordinator(
+ withVersion<TabToCoordinatorEnvelope>({
+ kind: 'disconnect-tab',
+ tabId: this.tabId,
+ reason,
+ })
+ );
+ }
+ this.finishDispose();
+ }
+
private abortDispose(reason: string): void {
this.clearGracefulTimeout();
if (this.ownerEpoch !== undefined) {
@@ -341,34 +391,58 @@ export class CacheCoordinatorPageAdapter {
if (this.closed) return;
const worker = this.createSharedWorker(this.options.scope);
- this.sharedWorker = worker;
- worker.onerror = (event) => {
- event.preventDefault();
- this.failTerminal(
- new Error(event.message || 'SharedWorker transport error')
- );
+ const closeUnpublishedWorker = (): void => {
+ try {
+ worker.onerror = null;
+ } catch {
+ // Raw endpoint closure remains authoritative during failed setup.
+ }
+ this.closePort(worker.port);
};
- worker.port.onmessage = (event: MessageEvent<unknown>) => {
- const transferredPorts = event.ports ?? [];
- if (transferredPorts.length > 0) {
- for (const port of transferredPorts) this.closePort(port);
+ let transport: EffectWorkerTransport<TabToCoordinatorEnvelope>;
+ try {
+ worker.onerror = (event) => {
+ event.preventDefault();
this.failTerminal(
- new Error('coordinator envelope transferred an unexpected port')
+ new Error(event.message || 'SharedWorker transport error')
);
- return;
- }
+ };
+ transport = createEffectWorkerTransport<
+ CoordinatorToTabEnvelope,
+ TabToCoordinatorEnvelope
+ >({
+ endpoint: worker as SharedWorker,
+ onMessage: (message) => {
+ try {
+ this.handleCoordinatorMessage(message);
+ } catch (error) {
+ this.failTerminal(
+ error instanceof Error ? error : new Error(String(error))
+ );
+ }
+ },
+ onError: (error) => {
+ this.failTerminal(
+ new Error(`coordinator Effect transport failed: ${error.message}`)
+ );
+ },
+ closeEndpoint: () => this.closePort(worker.port),
+ });
+ } catch (error) {
+ closeUnpublishedWorker();
+ throw error;
+ }
+ if (this.closed) {
try {
- this.handleCoordinatorMessage(event.data);
- } catch (error) {
- this.failTerminal(
- error instanceof Error ? error : new Error(String(error))
- );
+ worker.onerror = null;
+ } catch {
+ // The transport still owns endpoint closure below.
}
- };
- worker.port.onmessageerror = () => {
- this.failTerminal(new Error('coordinator MessagePort messageerror'));
- };
- worker.port.start();
+ void Effect.runPromise(transport.close()).catch(() => undefined);
+ return;
+ }
+ this.coordinatorConnection = { worker, transport };
+ void transport.ready.catch(() => undefined);
this.postCoordinator(
withVersion<TabToCoordinatorEnvelope>({
kind: 'register-tab',
@@ -522,6 +596,7 @@ export class CacheCoordinatorPageAdapter {
kind: 'attach-engine-port',
tabId: this.tabId,
ownerEpoch: election.ownerEpoch,
+ enginePort: directChannel.port1,
}),
[directChannel.port1],
[directChannel.port1]
@@ -588,7 +663,7 @@ export class CacheCoordinatorPageAdapter {
}
if (cleanupError) {
this.failTerminal(cleanupError);
- } else if (reportLoss && this.sharedWorker && !this.closed) {
+ } else if (reportLoss && this.coordinatorConnection && !this.closed) {
this.postCoordinator(
withVersion<TabToCoordinatorEnvelope>({
kind: 'engine-lost',
@@ -610,8 +685,8 @@ export class CacheCoordinatorPageAdapter {
transfer: Transferable[] = [],
untransferredPorts: MessagePort[] = []
): boolean {
- const port = this.sharedWorker?.port;
- if (!port) {
+ const connection = this.coordinatorConnection;
+ if (!connection) {
for (const untransferredPort of untransferredPorts) {
this.closePort(untransferredPort);
}
@@ -621,7 +696,7 @@ export class CacheCoordinatorPageAdapter {
return false;
}
try {
- port.postMessage(message, transfer);
+ Effect.runSync(connection.transport.send(message, transfer));
return true;
} catch (error) {
for (const untransferredPort of untransferredPorts) {
@@ -642,7 +717,7 @@ export class CacheCoordinatorPageAdapter {
addEventListener(
'pagehide',
() => {
- void this.dispose({ graceful: false });
+ void this.dispose({ graceful: false, preserveDatabase: true });
},
{ once: true }
);
@@ -692,21 +767,15 @@ export class CacheCoordinatorPageAdapter {
}
private closeCoordinatorPort(): void {
- const worker = this.sharedWorker;
- this.sharedWorker = undefined;
- if (!worker) return;
- try {
- worker.onerror = null;
- } catch {
- // Continue closing the port even if a test double rejects detachment.
- }
+ const connection = this.coordinatorConnection;
+ this.coordinatorConnection = undefined;
+ if (!connection) return;
try {
- worker.port.onmessage = null;
- worker.port.onmessageerror = null;
+ connection.worker.onerror = null;
} catch {
- // Continue closing even if a test double rejects handler detachment.
+ // Continue closing even if a test double rejects detachment.
}
- this.closePort(worker.port);
+ void Effect.runPromise(connection.transport.close()).catch(() => undefined);
}
private closePort(port: Pick<MessagePort, 'close'>): void {
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts
index 16c745b015..e3db174409 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts
@@ -16,6 +16,12 @@ const version = {
coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,
} as const;
+const enginePort = {
+ postMessage() {},
+ close() {},
+ start() {},
+} as unknown as MessagePort;
+
describe('coordinator runtime protocol', () => {
it('validates cache RPCs and rejects unknown fields or kinds', () => {
expect(isCacheRequest({ id: 0, kind: 'clear' })).toBe(true);
@@ -172,6 +178,7 @@ describe('coordinator runtime protocol', () => {
kind: 'attach-engine-port',
tabId: 'tab',
ownerEpoch: 1,
+ enginePort,
},
{
...version,
@@ -179,6 +186,13 @@ describe('coordinator runtime protocol', () => {
tabId: 'tab',
ownerEpoch: 1,
},
+ {
+ ...version,
+ kind: 'navigation-departure',
+ tabId: 'tab',
+ ownerEpoch: 1,
+ reason: 'pagehide',
+ },
{
...version,
kind: 'engine-lost',
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
index e7813bf73b..83dad846e2 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
@@ -56,6 +56,7 @@ export type TabToCoordinatorEnvelope =
kind: 'attach-engine-port';
tabId: string;
ownerEpoch: OwnerEpoch;
+ enginePort: MessagePort;
}
| {
coordinatorVersion: 2;
@@ -63,6 +64,13 @@ export type TabToCoordinatorEnvelope =
tabId: string;
ownerEpoch: OwnerEpoch;
}
+ | {
+ coordinatorVersion: 2;
+ kind: 'navigation-departure';
+ tabId: string;
+ ownerEpoch: OwnerEpoch;
+ reason: string;
+ }
| {
coordinatorVersion: 2;
kind: 'engine-lost';
@@ -285,6 +293,16 @@ const isOptionalRecord = (
): value is Record<string, unknown> | undefined =>
value === undefined || isRecord(value);
+const isMessagePort = (value: unknown): value is MessagePort =>
+ typeof value === 'object' &&
+ value !== null &&
+ 'postMessage' in value &&
+ typeof value.postMessage === 'function' &&
+ 'close' in value &&
+ typeof value.close === 'function' &&
+ 'start' in value &&
+ typeof value.start === 'function';
+
const isPath = (value: unknown): boolean =>
Array.isArray(value) &&
value.every(
@@ -621,6 +639,20 @@ export function validateTabToCoordinatorEnvelope(
}
break;
case 'attach-engine-port':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'tabId',
+ 'ownerEpoch',
+ 'enginePort',
+ ]) &&
+ isPositiveInteger(value.ownerEpoch) &&
+ isMessagePort(value.enginePort)
+ ) {
+ return pass(value as TabToCoordinatorEnvelope);
+ }
+ break;
case 'graceful-departure':
if (
hasOnlyKeys(value, [
@@ -634,6 +666,21 @@ export function validateTabToCoordinatorEnvelope(
return pass(value as TabToCoordinatorEnvelope);
}
break;
+ case 'navigation-departure':
+ if (
+ hasOnlyKeys(value, [
+ 'coordinatorVersion',
+ 'kind',
+ 'tabId',
+ 'ownerEpoch',
+ 'reason',
+ ]) &&
+ isPositiveInteger(value.ownerEpoch) &&
+ isNonEmptyString(value.reason)
+ ) {
+ return pass(value as TabToCoordinatorEnvelope);
+ }
+ break;
case 'engine-lost':
if (
hasOnlyKeys(value, [
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.ts
index bb7bd6cf54..be8c5a8ddd 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.ts
@@ -8,19 +8,22 @@ import {
CoordinatorRouter,
} from './coordinator-router';
-class FakePort {
+class FakePort extends EventTarget {
readonly messages: unknown[] = [];
readonly events: string[] = [];
closed = false;
started = false;
onmessage: ((event: MessageEvent<unknown>) => void) | null = null;
onmessageerror: (() => void) | null = null;
+ effectProtocol = false;
+ readonly throwKinds = new Set<string>();
postMessage(message: unknown): void {
+ const payload = effectPayload(message);
+ const kind = String((payload as { kind?: unknown })?.kind ?? 'unknown');
+ if (this.throwKinds.has(kind)) throw new Error(`${kind} send failed`);
this.messages.push(message);
- this.events.push(
- `post:${String((message as { kind?: unknown })?.kind ?? 'unknown')}`
- );
+ this.events.push(`post:${kind}`);
}
close(): void {
@@ -30,13 +33,25 @@ class FakePort {
start(): void {
this.started = true;
+ if (this.effectProtocol) this.effectReady();
}
receive(message: unknown): void {
+ if (this.effectProtocol) {
+ this.dispatchEvent(new MessageEvent('message', { data: [1, message] }));
+ return;
+ }
this.onmessage?.({ data: message, ports: [] } as unknown as MessageEvent);
}
+
+ effectReady(): void {
+ this.dispatchEvent(new MessageEvent('message', { data: [0] }));
+ }
}
+const effectPayload = (message: unknown): unknown =>
+ Array.isArray(message) && message[0] === 0 ? message[1] : message;
+
const version = {
coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,
} as const;
@@ -62,16 +77,14 @@ const attach = async (
ownerEpoch: number,
enginePort: FakePort
): Promise<void> => {
- await router.handleTabMessage(
- tabPort as CoordinatorMessagePort,
- {
- ...version,
- kind: 'attach-engine-port',
- tabId,
- ownerEpoch,
- },
- [enginePort as unknown as MessagePort]
- );
+ enginePort.effectProtocol = true;
+ await router.handleTabMessage(tabPort as CoordinatorMessagePort, {
+ ...version,
+ kind: 'attach-engine-port',
+ tabId,
+ ownerEpoch,
+ enginePort: enginePort as unknown as MessagePort,
+ });
};
const ready = (
@@ -96,12 +109,14 @@ const ready = (
};
const messagesOfKind = <T extends string>(port: FakePort, kind: T) =>
- port.messages.filter(
- (message): message is Record<string, unknown> & { kind: T } =>
- typeof message === 'object' &&
- message !== null &&
- (message as { kind?: unknown }).kind === kind
- );
+ port.messages
+ .map(effectPayload)
+ .filter(
+ (message): message is Record<string, unknown> & { kind: T } =>
+ typeof message === 'object' &&
+ message !== null &&
+ (message as { kind?: unknown }).kind === kind
+ );
describe('CoordinatorRouter', () => {
afterEach(() => {
@@ -359,6 +374,11 @@ describe('CoordinatorRouter', () => {
expect(
engine.messages
+ .map(effectPayload)
+ .filter(
+ (message) =>
+ typeof message === 'object' && message !== null && 'kind' in message
+ )
.slice(-2)
.map((message) => (message as { kind: string }).kind)
).toEqual(['engine-request', 'drain-engine']);
@@ -389,6 +409,96 @@ describe('CoordinatorRouter', () => {
expect(tabA.closed).toBe(true);
});
+ it('elects open-existing after an owner navigation departure', async () => {
+ const observations: Array<Record<string, unknown>> = [];
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ telemetry: {
+ record: (observation) => observations.push(observation),
+ flush: vi.fn(),
+ },
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ await register(router, tabA, 'tab-a');
+ await register(router, tabB, 'tab-b');
+ const engine = new FakePort();
+ await attach(router, tabA, 'tab-a', 1, engine);
+ ready(engine, 'tab-a', 1, 'opened-existing');
+
+ await router.handleTabMessage(tabA as CoordinatorMessagePort, {
+ ...version,
+ kind: 'navigation-departure',
+ tabId: 'tab-a',
+ ownerEpoch: 1,
+ reason: 'pagehide',
+ });
+
+ expect(messagesOfKind(tabB, 'become-owner')).toContainEqual(
+ expect.objectContaining({
+ ownerEpoch: 2,
+ databaseAction: 'open-existing',
+ })
+ );
+ expect(messagesOfKind(tabA, 'terminate-engine')).toHaveLength(0);
+ expect(tabA.closed).toBe(true);
+ expect(observations).toContainEqual(
+ expect.objectContaining({
+ name: 'graphql_cache.owner',
+ outcome: 'graceful',
+ ownerEvent: 'navigation-departure',
+ })
+ );
+ expect(observations).not.toContainEqual(
+ expect.objectContaining({
+ name: 'graphql_cache.storage_reset_required',
+ })
+ );
+ });
+
+ it('retains wipe-before-open when a recovery owner navigates during activation', async () => {
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ await register(router, tabA, 'tab-a');
+ await register(router, tabB, 'tab-b');
+ const engine = new FakePort();
+ await attach(router, tabA, 'tab-a', 1, engine);
+ ready(engine, 'tab-a', 1, 'opened-existing');
+ await router.handleTabMessage(tabA as CoordinatorMessagePort, {
+ ...version,
+ kind: 'engine-lost',
+ tabId: 'tab-a',
+ ownerEpoch: 1,
+ reason: 'engine failed',
+ });
+ expect(messagesOfKind(tabB, 'become-owner')).toContainEqual(
+ expect.objectContaining({
+ ownerEpoch: 2,
+ databaseAction: 'wipe-before-open',
+ })
+ );
+
+ await router.handleTabMessage(tabB as CoordinatorMessagePort, {
+ ...version,
+ kind: 'navigation-departure',
+ tabId: 'tab-b',
+ ownerEpoch: 2,
+ reason: 'pagehide during recovery',
+ });
+
+ expect(messagesOfKind(tabA, 'become-owner')).toContainEqual(
+ expect.objectContaining({
+ ownerEpoch: 3,
+ databaseAction: 'wipe-before-open',
+ })
+ );
+ });
+
it('counts an unknown response with the current direct-route tuple as stale', async () => {
const router = new CoordinatorRouter({
verifyTabLockHeld: async () => true,
@@ -416,6 +526,68 @@ describe('CoordinatorRouter', () => {
expect(messagesOfKind(tabA, 'terminate-engine')).toHaveLength(0);
});
+ it('closes the engine port and fails its owner when transport construction throws', async () => {
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ });
+ const tabA = new FakePort();
+ await register(router, tabA, 'tab-a');
+ const engine = new FakePort();
+ const addEventListener = engine.addEventListener.bind(engine);
+ vi.spyOn(engine, 'addEventListener').mockImplementation(
+ (type, listener, options) => {
+ if (type === 'messageerror') {
+ throw new Error('listener setup failed');
+ }
+ addEventListener(type, listener, options);
+ }
+ );
+
+ await expect(attach(router, tabA, 'tab-a', 1, engine)).resolves.toBe(
+ undefined
+ );
+
+ expect(engine.closed).toBe(true);
+ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(
+ expect.objectContaining({
+ ownerEpoch: 1,
+ reason: expect.stringContaining('listener setup failed'),
+ })
+ );
+ });
+
+ it('fails its owner instead of propagating an engine request send failure', async () => {
+ const router = new CoordinatorRouter({
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ await register(router, tabA, 'tab-a');
+ await register(router, tabB, 'tab-b');
+ const engine = new FakePort();
+ await attach(router, tabA, 'tab-a', 1, engine);
+ ready(engine, 'tab-a', 1, 'opened-existing');
+ engine.throwKinds.add('engine-request');
+
+ await expect(
+ router.handleTabMessage(tabB as CoordinatorMessagePort, {
+ ...version,
+ kind: 'cache-request',
+ tabId: 'tab-b',
+ request: { id: 20, kind: 'clear' },
+ })
+ ).resolves.toBeUndefined();
+
+ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(
+ expect.objectContaining({
+ ownerEpoch: 1,
+ reason: expect.stringContaining('engine-request send failed'),
+ })
+ );
+ });
+
it('uses activation and heartbeat watchdogs to terminate and wipe', async () => {
vi.useFakeTimers();
const router = new CoordinatorRouter({
@@ -460,6 +632,35 @@ describe('CoordinatorRouter', () => {
expect(router.snapshot()?.ownerEpoch).toBe(3);
});
+ it('fails its owner without arming a watchdog when heartbeat send fails', async () => {
+ vi.useFakeTimers();
+ const router = new CoordinatorRouter({
+ heartbeatIntervalMs: 5,
+ heartbeatTimeoutMs: 7,
+ verifyTabLockHeld: async () => true,
+ watchTabLock: () => () => {},
+ });
+ const tabA = new FakePort();
+ const tabB = new FakePort();
+ await register(router, tabA, 'tab-a');
+ await register(router, tabB, 'tab-b');
+ const engine = new FakePort();
+ await attach(router, tabA, 'tab-a', 1, engine);
+ ready(engine, 'tab-a', 1, 'opened-existing');
+ engine.throwKinds.add('heartbeat');
+
+ await vi.advanceTimersByTimeAsync(5);
+
+ expect(messagesOfKind(tabA, 'terminate-engine')).toContainEqual(
+ expect.objectContaining({
+ ownerEpoch: 1,
+ reason: expect.stringContaining('heartbeat send failed'),
+ })
+ );
+ expect(messagesOfKind(engine, 'heartbeat')).toHaveLength(0);
+ expect(vi.getTimerCount()).toBe(1);
+ });
+
it('accepts heartbeat acknowledgements and rearms the watchdog', async () => {
vi.useFakeTimers();
const router = new CoordinatorRouter({
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts
index 4a6f5241e1..5af2a9862a 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-router.ts
@@ -1,3 +1,5 @@
+import * as Effect from 'effect/Effect';
+import { match } from 'ts-pattern';
import type { CacheResponse } from '../protocol';
import {
type CacheResetReason,
@@ -21,16 +23,24 @@ import {
databaseOwnerLockName,
type EngineFatalCode,
type EngineOpenOutcome,
+ type EngineToCoordinatorEnvelope,
type TabToCoordinatorEnvelope,
tabLivenessLockName,
validateEngineToCoordinatorEnvelope,
validateTabToCoordinatorEnvelope,
} from './coordinator-protocol';
+import {
+ createEffectWorkerTransport,
+ type EffectWorkerTransport,
+} from './effect-worker-transport';
-export type CoordinatorMessagePort = Pick<
- MessagePort,
- 'postMessage' | 'close' | 'start' | 'onmessage' | 'onmessageerror'
->;
+export interface CoordinatorMessagePort {
+ onmessage: ((event: MessageEvent<unknown>) => void) | null;
+ onmessageerror: ((event: MessageEvent<unknown>) => void) | null;
+ postMessage(message: unknown, transfers?: Transferable[]): void;
+ close(): void;
+ start(): void;
+}
export type CancelLivenessWatch = () => void;
@@ -59,13 +69,16 @@ type PendingRegistration = { cancelled: boolean };
type EngineRoute = {
tabId: string;
ownerEpoch: number;
- port: CoordinatorMessagePort;
+ transport: EffectWorkerTransport<CoordinatorToEngineEnvelope>;
};
const DEFAULT_ACTIVATION_TIMEOUT_MS = 20_000;
const DEFAULT_HEARTBEAT_INTERVAL_MS = 2_000;
const DEFAULT_HEARTBEAT_TIMEOUT_MS = 5_000;
+const errorMessage = (error: unknown): string =>
+ error instanceof Error ? error.message : String(error);
+
const resetReasonForOpenOutcome = (
outcome: EngineOpenOutcome
): CacheResetReason => {
@@ -244,22 +257,12 @@ export class CoordinatorRouter {
return;
}
const message = parsed.value;
- const expectedPortCount = message.kind === 'attach-engine-port' ? 1 : 0;
- if (transferredPorts.length !== expectedPortCount) {
+ if (transferredPorts.length !== 0) {
for (const transferredPort of transferredPorts) transferredPort.close();
- const tabId = this.portTabs.get(port);
- if (message.kind === 'attach-engine-port' && tabId) {
- this.failOwner(
- tabId,
- message.ownerEpoch,
- 'engine attachment transferred the wrong number of ports'
- );
- } else {
- this.postProtocolError(
- port,
- 'coordinator envelope transferred unexpected ports'
- );
- }
+ this.postProtocolError(
+ port,
+ 'coordinator envelope transferred unexpected event ports'
+ );
return;
}
if (message.kind === 'register-tab') {
@@ -285,25 +288,26 @@ export class CoordinatorRouter {
return;
}
- switch (message.kind) {
- case 'cache-request':
- this.applyActions(core.request(tabId, message.request));
- break;
- case 'attach-engine-port':
- this.attachEnginePort(tabId, message.ownerEpoch, transferredPorts[0]);
- break;
- case 'graceful-departure':
- this.applyActions(
- core.beginGracefulDeparture(tabId, message.ownerEpoch)
- );
- break;
- case 'engine-lost':
- this.failOwner(tabId, message.ownerEpoch, message.reason);
- break;
- case 'disconnect-tab':
- this.loseTab(tabId, message.reason);
- break;
- }
+ match(message)
+ .with({ kind: 'cache-request' }, ({ request }) => {
+ this.applyActions(core.request(tabId, request));
+ })
+ .with({ kind: 'attach-engine-port' }, ({ ownerEpoch, enginePort }) => {
+ this.attachEnginePort(tabId, ownerEpoch, enginePort);
+ })
+ .with({ kind: 'graceful-departure' }, ({ ownerEpoch }) => {
+ this.applyActions(core.beginGracefulDeparture(tabId, ownerEpoch));
+ })
+ .with({ kind: 'navigation-departure' }, ({ ownerEpoch, reason }) => {
+ this.departForNavigation(tabId, ownerEpoch, reason);
+ })
+ .with({ kind: 'engine-lost' }, ({ ownerEpoch, reason }) => {
+ this.failOwner(tabId, ownerEpoch, reason);
+ })
+ .with({ kind: 'disconnect-tab' }, ({ reason }) => {
+ this.loseTab(tabId, reason);
+ })
+ .exhaustive();
}
private async register(
@@ -438,31 +442,42 @@ export class CoordinatorRouter {
return;
}
- const route: EngineRoute = {
- tabId,
- ownerEpoch,
- port: transferredPort,
- };
+ let route: EngineRoute | undefined;
+ let transport: EffectWorkerTransport<CoordinatorToEngineEnvelope>;
+ try {
+ transport = createEffectWorkerTransport<
+ EngineToCoordinatorEnvelope,
+ CoordinatorToEngineEnvelope
+ >({
+ endpoint: transferredPort,
+ onMessage: (message) => {
+ if (route && this.engineRoute === route) {
+ this.handleEngineMessage(route, message);
+ }
+ },
+ onError: (error) => {
+ if (route && this.engineRoute === route) {
+ this.failOwner(
+ tabId,
+ ownerEpoch,
+ `engine Effect transport failed: ${error.message}`
+ );
+ }
+ },
+ closeEndpoint: () => transferredPort.close(),
+ });
+ } catch (error) {
+ transferredPort.close();
+ this.failOwner(
+ tabId,
+ ownerEpoch,
+ `engine Effect transport failed: ${errorMessage(error)}`
+ );
+ return;
+ }
+ route = { tabId, ownerEpoch, transport };
this.engineRoute = route;
- transferredPort.onmessage = (event: MessageEvent<unknown>) => {
- if (this.engineRoute !== route) return;
- if (event.ports.length > 0) {
- for (const port of event.ports) port.close();
- this.failOwner(
- tabId,
- ownerEpoch,
- 'engine envelope transferred an unexpected port'
- );
- return;
- }
- this.handleEngineMessage(route, event.data);
- };
- transferredPort.onmessageerror = () => {
- if (this.engineRoute === route) {
- this.failOwner(tabId, ownerEpoch, 'engine MessagePort messageerror');
- }
- };
- transferredPort.start();
+ void transport.ready.catch(() => undefined);
}
private handleEngineMessage(route: EngineRoute, rawMessage: unknown): void {
@@ -686,7 +701,8 @@ export class CoordinatorRouter {
);
break;
}
- route.port.postMessage(
+ this.sendToEngine(
+ route,
envelope<CoordinatorToEngineEnvelope>({
kind: 'engine-request',
ownerEpoch: action.ownerEpoch,
@@ -738,7 +754,8 @@ export class CoordinatorRouter {
);
break;
}
- route.port.postMessage(
+ this.sendToEngine(
+ route,
envelope<CoordinatorToEngineEnvelope>({
kind: 'drain-engine',
ownerEpoch: action.ownerEpoch,
@@ -752,8 +769,11 @@ export class CoordinatorRouter {
this.engineRoute?.tabId === action.tabId &&
this.engineRoute.ownerEpoch === action.ownerEpoch
) {
- this.engineRoute.port.close();
+ const route = this.engineRoute;
this.engineRoute = undefined;
+ void Effect.runPromise(route.transport.close()).catch(
+ () => undefined
+ );
}
break;
case 'drop-tab':
@@ -875,6 +895,55 @@ export class CoordinatorRouter {
this.applyActions(actions);
}
+ private departForNavigation(
+ tabId: string,
+ ownerEpoch: number,
+ reason: string
+ ): void {
+ const core = this.coreValue;
+ if (!core) return;
+ const state = core.state;
+ const isCurrentOwner =
+ state.kind !== 'waiting-for-tab' &&
+ state.kind !== 'resetting-after-loss' &&
+ state.tabId === tabId &&
+ state.ownerEpoch === ownerEpoch;
+ const actions = core.departForNavigation(tabId, ownerEpoch, reason);
+ if (!isCurrentOwner) {
+ this.applyActions(actions);
+ return;
+ }
+
+ this.activationStarted.delete(ownerEpoch);
+ const interruptedResetReason =
+ state.kind === 'activating' && state.databaseAction === 'wipe-before-open'
+ ? this.pendingRecoveryResetEpochs.get(ownerEpoch)
+ : undefined;
+ if (interruptedResetReason !== undefined) {
+ this.pendingRecoveryResetEpochs.delete(ownerEpoch);
+ this.nextRecoveryResetReason = interruptedResetReason;
+ }
+ this.telemetry.record({
+ name: 'graphql_cache.owner',
+ operationCategory: 'lifecycle',
+ outcome: 'graceful',
+ ownerEvent: 'navigation-departure',
+ });
+ for (const [routeId, timing] of this.routeStarted) {
+ if (timing.ownerEpoch !== ownerEpoch) continue;
+ this.routeStarted.delete(routeId);
+ this.telemetry.record({
+ name: 'graphql_cache.coordinator_request',
+ operationCategory: timing.category,
+ outcome: 'error',
+ errorCode: 'owner-lost',
+ durationMs: this.now() - timing.startedAt,
+ });
+ }
+ this.clearEngineWatchdogs();
+ this.applyActions(actions);
+ }
+
private loseTab(tabId: string, reason: string): void {
const core = this.coreValue;
if (!core) return;
@@ -1053,6 +1122,23 @@ export class CoordinatorRouter {
connection.port.close();
}
+ private sendToEngine(
+ route: EngineRoute,
+ message: CoordinatorToEngineEnvelope
+ ): boolean {
+ try {
+ Effect.runSync(route.transport.send(message));
+ return true;
+ } catch (error) {
+ this.failOwner(
+ route.tabId,
+ route.ownerEpoch,
+ `engine Effect transport send failed: ${errorMessage(error)}`
+ );
+ return false;
+ }
+ }
+
private scheduleHeartbeat(ownerEpoch: number): void {
this.clearHeartbeatTimers();
this.heartbeatIntervalTimer = this.setTimeoutFn(() => {
@@ -1067,13 +1153,18 @@ export class CoordinatorRouter {
}
const heartbeatId = this.nextHeartbeatId++;
this.pendingHeartbeat = { ownerEpoch, heartbeatId };
- route.port.postMessage(
- envelope<CoordinatorToEngineEnvelope>({
- kind: 'heartbeat',
- ownerEpoch,
- heartbeatId,
- })
- );
+ if (
+ !this.sendToEngine(
+ route,
+ envelope<CoordinatorToEngineEnvelope>({
+ kind: 'heartbeat',
+ ownerEpoch,
+ heartbeatId,
+ })
+ )
+ ) {
+ return;
+ }
this.heartbeatTimeoutTimer = this.setTimeoutFn(() => {
if (
this.pendingHeartbeat?.ownerEpoch === ownerEpoch &&
diff --git a/apps/web/src/lib/graphql-cache/worker/effect-worker-transport.test.ts b/apps/web/src/lib/graphql-cache/worker/effect-worker-transport.test.ts
new file mode 100644
index 0000000000..c9a606712f
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/effect-worker-transport.test.ts
@@ -0,0 +1,208 @@
+import * as Effect from 'effect/Effect';
+import { describe, expect, it, vi } from 'vitest';
+import {
+ createEffectWorkerRunnerTransport,
+ createEffectWorkerTransport,
+ EFFECT_WORKER_CLOSE_FRAME,
+ EFFECT_WORKER_READY_FRAME,
+ EFFECT_WORKER_REQUEST_TAG,
+ EFFECT_WORKER_RESPONSE_TAG,
+} from './effect-worker-transport';
+
+class FakeMessagePort extends EventTarget {
+ readonly sent: Array<{
+ message: unknown;
+ transfers: readonly Transferable[] | undefined;
+ }> = [];
+ closed = false;
+
+ postMessage(
+ message: unknown,
+ transfers?: readonly Transferable[] | StructuredSerializeOptions
+ ): void {
+ if (this.closed) return;
+ this.sent.push({
+ message,
+ transfers: Array.isArray(transfers)
+ ? transfers
+ : (transfers as StructuredSerializeOptions | undefined)?.transfer,
+ });
+ }
+
+ start(): void {}
+
+ close(): void {
+ this.closed = true;
+ }
+
+ ready(): void {
+ this.dispatchEvent(
+ new MessageEvent('message', { data: EFFECT_WORKER_READY_FRAME })
+ );
+ }
+
+ emit(message: unknown): void {
+ this.dispatchEvent(
+ new MessageEvent('message', {
+ data: [EFFECT_WORKER_RESPONSE_TAG, message],
+ })
+ );
+ }
+}
+
+const flush = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+describe('Effect worker transport', () => {
+ it('buffers sends until ready and preserves their order', async () => {
+ const endpoint = new FakeMessagePort();
+ const received: unknown[] = [];
+ const transport = createEffectWorkerTransport<unknown, string>({
+ endpoint: endpoint as unknown as MessagePort,
+ onMessage: (message) => received.push(message),
+ onError: vi.fn(),
+ });
+
+ await Effect.runPromise(transport.send('first'));
+ await Effect.runPromise(transport.send('second'));
+ expect(endpoint.sent).toEqual([]);
+
+ endpoint.ready();
+ await transport.ready;
+ expect(endpoint.sent.map(({ message }) => message)).toEqual([
+ [EFFECT_WORKER_REQUEST_TAG, 'first'],
+ [EFFECT_WORKER_REQUEST_TAG, 'second'],
+ ]);
+
+ endpoint.emit({ kind: 'response' });
+ await flush();
+ expect(received).toEqual([{ kind: 'response' }]);
+
+ await Effect.runPromise(transport.close());
+ });
+
+ it('does not start its protocol fiber when listener setup fails', () => {
+ const endpoint = new FakeMessagePort();
+ const addEventListener = endpoint.addEventListener.bind(endpoint);
+ vi.spyOn(endpoint, 'addEventListener').mockImplementation(
+ (type, listener, options) => {
+ if (type === 'messageerror') {
+ throw new Error('listener setup failed');
+ }
+ addEventListener(type, listener, options);
+ }
+ );
+ const onError = vi.fn();
+
+ expect(() =>
+ createEffectWorkerTransport({
+ endpoint: endpoint as unknown as MessagePort,
+ onMessage: vi.fn(),
+ onError,
+ })
+ ).toThrow('listener setup failed');
+ endpoint.ready();
+ expect(onError).not.toHaveBeenCalled();
+ });
+
+ it('passes transferables and emits the Effect close frame once', async () => {
+ const endpoint = new FakeMessagePort();
+ const closeEndpoint = vi.fn();
+ const transport = createEffectWorkerTransport<unknown, unknown>({
+ endpoint: endpoint as unknown as MessagePort,
+ onMessage: vi.fn(),
+ onError: vi.fn(),
+ closeEndpoint: () => {
+ closeEndpoint();
+ endpoint.close();
+ },
+ });
+ endpoint.ready();
+ await transport.ready;
+
+ const channel = new MessageChannel();
+ await Effect.runPromise(
+ transport.send({ port: channel.port1 }, [channel.port1])
+ );
+ const framed = endpoint.sent[0]?.message as
+ | [number, { port: MessagePort }]
+ | undefined;
+ expect(framed?.[0]).toBe(EFFECT_WORKER_REQUEST_TAG);
+ expect(framed?.[1].port).toBe(channel.port1);
+ expect(endpoint.sent[0]?.transfers).toHaveLength(1);
+ expect(endpoint.sent[0]?.transfers?.[0]).toBe(channel.port1);
+
+ await Effect.runPromise(
+ Effect.all([transport.close(), transport.close()], { discard: true })
+ );
+ expect(endpoint.sent.at(-1)?.message).toEqual(EFFECT_WORKER_CLOSE_FRAME);
+ expect(
+ endpoint.sent.filter(({ message }) =>
+ Array.isArray(message)
+ ? message[0] === EFFECT_WORKER_RESPONSE_TAG
+ : false
+ )
+ ).toHaveLength(1);
+ expect(closeEndpoint).toHaveBeenCalledOnce();
+ channel.port2.close();
+ });
+
+ it('communicates with the Effect runner over a MessagePort', async () => {
+ const channel = new MessageChannel();
+ const parentMessages: unknown[] = [];
+ let runnerPortId: number | undefined;
+ let runnerMessage: unknown;
+ const runner = createEffectWorkerRunnerTransport<unknown, unknown>({
+ endpoint: channel.port2,
+ onMessage(portId, message) {
+ runnerPortId = portId;
+ runnerMessage = message;
+ },
+ onError: vi.fn(),
+ });
+ const parent = createEffectWorkerTransport<unknown, unknown>({
+ endpoint: channel.port1,
+ onMessage: (message) => parentMessages.push(message),
+ onError: vi.fn(),
+ });
+
+ await parent.ready;
+ Effect.runSync(parent.send({ kind: 'request' }));
+ await flush();
+ expect(runnerMessage).toEqual({ kind: 'request' });
+ expect(runnerPortId).toBe(0);
+
+ Effect.runSync(runner.send(0, { kind: 'response' }));
+ await flush();
+ expect(parentMessages).toEqual([{ kind: 'response' }]);
+
+ await Effect.runPromise(
+ Effect.all([parent.close(), runner.close()], { discard: true })
+ );
+ });
+
+ it('reports message decoding failures and rejects sends after close', async () => {
+ const endpoint = new FakeMessagePort();
+ const onError = vi.fn();
+ const transport = createEffectWorkerTransport<unknown, unknown>({
+ endpoint: endpoint as unknown as MessagePort,
+ onMessage: vi.fn(),
+ onError,
+ });
+ endpoint.ready();
+ await transport.ready;
+
+ endpoint.dispatchEvent(
+ new MessageEvent('messageerror', { data: 'uncloneable response' })
+ );
+ expect(onError).toHaveBeenCalledWith(
+ expect.objectContaining({
+ message: 'Effect worker transport messageerror',
+ })
+ );
+
+ await Effect.runPromise(transport.close());
+ await expect(
+ Effect.runPromise(transport.send({ kind: 'late' }))
+ ).rejects.toThrow('Effect worker transport is closed');
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/worker/effect-worker-transport.ts b/apps/web/src/lib/graphql-cache/worker/effect-worker-transport.ts
new file mode 100644
index 0000000000..647a4073d4
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/worker/effect-worker-transport.ts
@@ -0,0 +1,262 @@
+import * as BrowserWorker from '@effect/platform-browser/BrowserWorker';
+import * as BrowserWorkerRunner from '@effect/platform-browser/BrowserWorkerRunner';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+import * as Queue from 'effect/Queue';
+import * as WorkerApi from 'effect/unstable/workers/Worker';
+import type { WorkerError } from 'effect/unstable/workers/WorkerError';
+
+export type BrowserWorkerEndpoint = Worker | SharedWorker | MessagePort;
+
+/** Effect's parent-to-runner request frame tag. */
+export const EFFECT_WORKER_REQUEST_TAG = 0 as const;
+/** Effect's runner-to-parent ready frame. */
+export const EFFECT_WORKER_READY_FRAME = [EFFECT_WORKER_REQUEST_TAG] as const;
+/** Effect's runner-to-parent response frame tag. */
+export const EFFECT_WORKER_RESPONSE_TAG = 1 as const;
+/** Effect's parent-to-runner close frame. */
+export const EFFECT_WORKER_CLOSE_FRAME = [EFFECT_WORKER_RESPONSE_TAG] as const;
+
+export interface EffectWorkerTransportOptions<Inbound> {
+ /** Existing browser endpoint. Its lifetime remains owned by the caller. */
+ endpoint: BrowserWorkerEndpoint;
+ onMessage(message: Inbound): void;
+ onError(error: Error): void;
+ /** Synchronously closes the caller-owned browser endpoint. */
+ closeEndpoint?: () => void;
+}
+
+export interface EffectWorkerTransport<Outbound> {
+ /** Resolves after the runner has installed its receive loop. */
+ readonly ready: Promise<void>;
+ /** Sends through Effect's worker protocol, including optional transferables. */
+ send(
+ message: Outbound,
+ transfers?: readonly Transferable[]
+ ): Effect.Effect<void, Error>;
+ /** Closes the Effect scope and then the caller-owned browser endpoint. */
+ close(): Effect.Effect<void>;
+}
+
+const asError = (cause: unknown): Error =>
+ cause instanceof Error ? cause : new Error(String(cause));
+
+const originalWorkerError = (error: WorkerError): Error =>
+ error.reason.cause instanceof Error ? error.reason.cause : error;
+
+/**
+ * Starts Effect's parent-side browser worker protocol over an existing worker
+ * endpoint while keeping endpoint construction and termination with the cache
+ * ownership topology.
+ */
+export function createEffectWorkerTransport<Inbound, Outbound>(
+ options: EffectWorkerTransportOptions<Inbound>
+): EffectWorkerTransport<Outbound> {
+ const backing = Effect.runSync(
+ Effect.gen(function* () {
+ const platform = yield* WorkerApi.WorkerPlatform;
+ return yield* platform.spawn<Inbound, Outbound>(0);
+ }).pipe(Effect.provide(BrowserWorker.layer(() => options.endpoint)))
+ );
+
+ let readySettled = false;
+ let closed = false;
+ let resolveReady!: () => void;
+ let rejectReady!: (error: Error) => void;
+ const ready = new Promise<void>((resolve, reject) => {
+ resolveReady = resolve;
+ rejectReady = reject;
+ });
+
+ const reportFailure = (error: Error): void => {
+ if (!readySettled) {
+ readySettled = true;
+ rejectReady(error);
+ }
+ options.onError(error);
+ };
+
+ const run = backing
+ .run(
+ (message) =>
+ Effect.sync(() => {
+ options.onMessage(message);
+ }),
+ {
+ onSpawn: Effect.sync(() => {
+ if (readySettled) return;
+ // Effect invokes `onSpawn` before opening its private ready latch.
+ // Resolving synchronously here lets awaiters run before buffered sends
+ // flush (covered by the transport ordering test), so defer one task.
+ setTimeout(() => {
+ if (readySettled) return;
+ readySettled = true;
+ resolveReady();
+ }, 0);
+ }),
+ }
+ )
+ .pipe(
+ Effect.catchCause((cause) =>
+ Effect.sync(() => {
+ if (!closed) reportFailure(asError(Cause.squash(cause)));
+ })
+ )
+ );
+ const messageTarget =
+ 'port' in options.endpoint ? options.endpoint.port : options.endpoint;
+ const onMessageError: EventListener = (event): void => {
+ reportFailure(
+ new Error('Effect worker transport messageerror', {
+ cause: (event as MessageEvent).data,
+ })
+ );
+ };
+ messageTarget.addEventListener('messageerror', onMessageError);
+ const fiber = Effect.runFork(run);
+
+ return {
+ ready,
+
+ send(message, transfers): Effect.Effect<void, Error> {
+ return Effect.suspend(() => {
+ if (closed) {
+ return Effect.fail(new Error('Effect worker transport is closed'));
+ }
+ return backing
+ .send(message, transfers)
+ .pipe(Effect.mapError(originalWorkerError));
+ });
+ },
+
+ close(): Effect.Effect<void> {
+ return Effect.suspend(() => {
+ if (!closed) {
+ closed = true;
+ if (!readySettled) {
+ readySettled = true;
+ rejectReady(
+ new Error('Effect worker transport closed before ready')
+ );
+ }
+ messageTarget.removeEventListener('messageerror', onMessageError);
+ // Preserve the browser adapter's synchronous endpoint teardown while
+ // still speaking Effect's explicit close protocol to the runner.
+ try {
+ messageTarget.postMessage(EFFECT_WORKER_CLOSE_FRAME);
+ } catch {
+ // Endpoint teardown remains authoritative if close framing fails.
+ } finally {
+ options.closeEndpoint?.();
+ }
+ }
+ return Fiber.interrupt(fiber);
+ });
+ },
+ };
+}
+
+export interface EffectWorkerRunnerOptions<Inbound> {
+ endpoint: MessagePort | Window;
+ onMessage(portId: number, message: Inbound): void | Promise<void>;
+ onDisconnect?: (portId: number) => void;
+ onError(error: Error): void;
+}
+
+export interface EffectWorkerRunnerTransport<Outbound> {
+ send(
+ portId: number,
+ message: Outbound,
+ transfers?: readonly Transferable[]
+ ): Effect.Effect<void, Error>;
+ isClosed(): boolean;
+ close(): Effect.Effect<void>;
+}
+
+/** Runs Effect's worker-side protocol over a worker global or explicit port. */
+export function createEffectWorkerRunnerTransport<Inbound, Outbound>(
+ options: EffectWorkerRunnerOptions<Inbound>
+): EffectWorkerRunnerTransport<Outbound> {
+ const platform = BrowserWorkerRunner.make(options.endpoint);
+ const runner = Effect.runSync(platform.start<Outbound, Inbound>());
+ let closed = false;
+ const run = runner
+ .run((portId, message) => {
+ const handled = options.onMessage(portId, message);
+ return handled instanceof Promise
+ ? Effect.promise(() => handled)
+ : undefined;
+ })
+ .pipe(
+ Effect.catchCause((cause) =>
+ Effect.sync(() => {
+ if (!closed) options.onError(asError(Cause.squash(cause)));
+ })
+ )
+ );
+ const fiber = Effect.runFork(run);
+ const disconnectFiber = runner.disconnects
+ ? Effect.runFork(
+ Queue.take(runner.disconnects).pipe(
+ Effect.tap((portId) =>
+ Effect.sync(() => options.onDisconnect?.(portId))
+ ),
+ Effect.forever
+ )
+ )
+ : undefined;
+
+ return {
+ send(portId, message, transfers): Effect.Effect<void, Error> {
+ return Effect.suspend(() => {
+ if (closed) {
+ return Effect.fail(
+ new Error('Effect worker runner transport is closed')
+ );
+ }
+ return runner.send(portId, message, transfers);
+ });
+ },
+
+ isClosed(): boolean {
+ return closed;
+ },
+
+ close(): Effect.Effect<void> {
+ return Effect.suspend(() => {
+ closed = true;
+ return Effect.all(
+ [
+ Fiber.interrupt(fiber),
+ ...(disconnectFiber ? [Fiber.interrupt(disconnectFiber)] : []),
+ ],
+ { discard: true }
+ );
+ });
+ },
+ };
+}
+
+/** Extracts Effect's typed worker failure for telemetry without exposing Effect. */
+export function effectWorkerErrorTag(
+ error: unknown
+): WorkerError['reason']['_tag'] | undefined {
+ if (
+ typeof error !== 'object' ||
+ error === null ||
+ !('reason' in error) ||
+ typeof error.reason !== 'object' ||
+ error.reason === null ||
+ !('_tag' in error.reason)
+ ) {
+ return undefined;
+ }
+ const tag = error.reason._tag;
+ return tag === 'WorkerSpawnError' ||
+ tag === 'WorkerSendError' ||
+ tag === 'WorkerReceiveError' ||
+ tag === 'WorkerUnknownError'
+ ? tag
+ : undefined;
+}
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.ts
index b5e1d6af49..53f3473fea 100644
--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.ts
+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.ts
@@ -12,9 +12,11 @@ const mocks = vi.hoisted(() => {
markApiStarted = resolve;
});
let queuedMutationCount = 0;
+ let initializationErrorHandler: ((error: Error) => void) | undefined;
+ const cleanupOrder: string[] = [];
const host = {
disabled: false,
- dispose: vi.fn(),
+ dispose: vi.fn(() => cleanupOrder.push('host')),
enqueueOptimisticMutation: vi.fn(async () => {
queuedMutationCount += 1;
return { transactionId: 'tx-1' };
@@ -62,10 +64,23 @@ const mocks = vi.hoisted(() => {
releaseApi: () => releaseApi?.(),
resetQueue: () => {
queuedMutationCount = 0;
+ cleanupOrder.length = 0;
+ initializationErrorHandler = undefined;
},
queueDepth: () => queuedMutationCount,
+ recordSubscriptionDisposal: () => cleanupOrder.push('subscriptions'),
+ cleanupOrder: () => [...cleanupOrder],
+ failInitialization: () =>
+ initializationErrorHandler?.(
+ new Error('injected initialization failure')
+ ),
plainClient,
- createWorkerCacheHost: vi.fn(() => host),
+ createWorkerCacheHost: vi.fn(
+ (options: { onInitializationError?: (error: Error) => void }) => {
+ initializationErrorHandler = options.onInitializationError;
+ return host;
+ }
+ ),
createTauriCacheHost: vi.fn(() => host),
};
});
@@ -123,7 +138,7 @@ vi.mock('./graphql-soup-websocket', () => ({
createGraphqlSoupWebSocketUrlResolver: () => () => 'ws://dss.test',
createGraphqlSoupSubscriptionsLifecycle: () => ({
replace: vi.fn(),
- dispose: vi.fn(),
+ dispose: vi.fn(() => mocks.recordSubscriptionDisposal()),
}),
}));
vi.mock('@urql/core', () => ({
@@ -189,6 +204,22 @@ describe('GraphQL Soup browser cache session gate', () => {
expect(mocks.host.dispose).not.toHaveBeenCalled();
});
+ it('unsubscribes cache operations before disposing a failed host', async () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const soup = await import('./graphql-soup');
+ const cachedClient = soup.getGraphqlSoupClient();
+
+ mocks.failInitialization();
+
+ expect(cachedClient).not.toBe(mocks.plainClient);
+ expect(soup.getGraphqlSoupClient()).toBe(mocks.plainClient);
+ expect(mocks.cleanupOrder()).toEqual(['subscriptions', 'host']);
+ expect(warn).toHaveBeenCalledWith(
+ 'graphql cache async init failed; using uncached client',
+ expect.objectContaining({ message: 'injected initialization failure' })
+ );
+ });
+
it('imports and uses the native path without constructing browser workers', async () => {
const WorkerConstructor = vi.fn(() => {
throw new Error('browser worker must not be constructed on Tauri');
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts
index ac05ba8dd9..8c4aee29dc 100644
--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts
+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts
@@ -175,8 +175,10 @@ export function getGraphqlSoupClient(): Client {
const subscriptionsLifecycle = createGraphqlSoupSubscriptionsLifecycle();
const cleanup = () => {
unregisterHost();
- host?.dispose();
+ // Unsubscribing emits urql teardown operations; keep the cache host
+ // available until those best-effort registration removals are issued.
subscriptionsLifecycle.dispose();
+ host?.dispose();
if (websocketClient) void websocketClient.dispose();
};
const onInitializationError = (error: Error) => {
diff --git a/bun.lock b/bun.lock
index 7b8b12e598..3318bae185 100644
--- a/bun.lock
+++ b/bun.lock
@@ -21,6 +21,7 @@
"@corvu/drawer": "^0.2.4",
"@date-fns/tz": "^1.4.1",
"@dinero.js/currencies": "2.0.0-alpha.8",
+ "@effect/platform-browser": "4.0.0-rc.111",
"@floating-ui/dom": "^1.7.4",
"@fontsource-variable/inter": "^5.2.8",
"@fontsource-variable/playfair-display": "^5.2.8",
@@ -712,6 +713,8 @@
"@dinero.js/currencies": ["@dinero.js/[email protected]", "", {}, "sha512-zApiqtuuPwjiM9LJA5/kNcT48VSHRiz2/mktkXjIpfxrJKzthXybUAgEenExIH6dYhLDgVmsLQZtZFOsdYl0Ag=="],
+ "@effect/platform-browser": ["@effect/[email protected]", "", { "peerDependencies": { "effect": "^4.0.0-rc.111" } }, "sha512-4SmaYB4zWsmuM82V8Dgida2yupzEWlv6/QoDL2Ogj1jOPq65KUx3VjQKcNn2NenOR6SFRWaWsUWrnxwA2IPFzg=="],
+
"@emnapi/core": ["@emnapi/[email protected]", "", { "dependencies": { "@emnapi/wasi-threads": "1.2.2", "tslib": "^2.4.0" } }, "sha512-TC8MkTuZUtcTSiFeuC0ksCh9QIJ5+F21MvZ4Wn4ORfYaFJ/0dsiudv5tVkejgwZlwQ39jL9WWDe2lz8x0WglOA=="],
"@emnapi/runtime": ["@emnapi/[email protected]", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-kyOl3X0DuTiT1h2ft8r2fYO8JYtU9a9Xis/zBSiGArNaagCOWx90N1k2wxp18czFDH+OgcWGb5ZP/XMt3dcyPA=="],
diff --git a/nix-support/node_modules-hashes.json b/nix-support/node_modules-hashes.json
index 6d38f0b1d8..75870beb4f 100644
--- a/nix-support/node_modules-hashes.json
+++ b/nix-support/node_modules-hashes.json
@@ -1,6 +1,6 @@
{
"nodeModules": {
- "aarch64-darwin": "sha256-ZFrp1AgZTEZtsLqELRlOLVswbL13Bs/QvCsO+tTlrpU=",
- "x86_64-linux": "sha256-JE+HJpEnW7Hjk+PH360Ca1DNuGNfwQi0GCYecuVOBaM="
+ "aarch64-darwin": "sha256-G+0YuImb+ULJX59bZdUICCQiewNQ4N5csROrt6VmuI4=",
+ "x86_64-linux": "sha256-pm/7bLHzRNqi4Qw0axp3TIAf9SKfSVBnvJYPVC+dnPA="
}
}
\ No newline at end of file