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/cache disposed (#6885)

Sean Aye6fe24fc727dc
diff --git a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
index 70373f1d4d..3deeb17495 100644
--- a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
@@ -24,7 +24,8 @@ import {
type Source,
subscribe,
} from 'wonka';
-import type { CacheHost } from '../host/types';
+import { CacheNavigationError } from '../host/navigation-error';
+import type { CacheGenerationChange, CacheHost } from '../host/types';
import {
ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,
type ClaimedMutation,
@@ -202,11 +203,15 @@ type FakeHost = CacheHost & {
args: Parameters<CacheHost['enqueueOptimisticMutation']>[0]
) => void;
pushAffected: (opKeys: number[]) => void;
+ pushGeneration: (change: CacheGenerationChange) => void;
};
function makeFakeHost(): FakeHost {
let readResult: ReadResult = { kind: 'miss' };
const subscribers = new Set<(opKeys: number[]) => void>();
+ const generationSubscribers = new Set<
+ (change: CacheGenerationChange) => void
+ >();
const queue: Array<{
transactionId: string;
args: Parameters<CacheHost['enqueueOptimisticMutation']>[0];
@@ -266,6 +271,9 @@ function makeFakeHost(): FakeHost {
pushAffected: (opKeys) => {
for (const cb of subscribers) cb(opKeys);
},
+ pushGeneration: (change) => {
+ for (const cb of generationSubscribers) cb(change);
+ },
async currentRevision() {
return INITIAL_CACHE_REVISION;
},
@@ -416,8 +424,9 @@ function makeFakeHost(): FakeHost {
onCacheChanged() {
return () => undefined;
},
- onCacheGenerationChanged() {
- return () => undefined;
+ onCacheGenerationChanged(cb) {
+ generationSubscribers.add(cb);
+ return () => generationSubscribers.delete(cb);
},
onMutationSettled() {
return () => undefined;
@@ -836,6 +845,53 @@ describe('normalizedCacheExchange', () => {
expect(cacheContainsDocument).toBe(false);
});
+ it('cancels queued subscription effects on teardown even when the same key resubscribes', async () => {
+ const firstWrite = deferred<WriteResult>();
+ const write = vi
+ .spyOn(host, 'writeQuery')
+ .mockImplementationOnce(() => firstWrite.promise);
+ const remove = vi.spyOn(host, 'deleteRecords');
+ const { ops, network } = controlledQueryHarness(host);
+ const operation = makeSubscriptionOp(24);
+ ops.next(operation);
+ network.next(
+ queryResult(operation, {
+ soupUpdates: [
+ {
+ __typename: 'SoupUpdated',
+ item: { __typename: 'GraphqlSoupDocument', id: 'one' },
+ },
+ {
+ __typename: 'GraphqlCacheDeletion',
+ graphqlTypeName: 'GraphqlSoupDocument',
+ entityId: 'one',
+ },
+ ],
+ })
+ );
+ network.next(
+ queryResult(operation, {
+ soupUpdates: [{ id: 'queued-before-navigation' }],
+ })
+ );
+ await vi.waitFor(() => expect(write).toHaveBeenCalledOnce());
+
+ ops.next(makeOperation('teardown', operation, operation.context));
+ ops.next(operation);
+ const fresh = { soupUpdates: [{ id: 'after-restore' }] };
+ network.next(queryResult(operation, fresh));
+ firstWrite.resolve({
+ revision: INITIAL_CACHE_REVISION,
+ revisionAdvanced: true,
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ });
+ await vi.waitFor(() => expect(write).toHaveBeenCalledTimes(2));
+ expect(write.mock.calls[1]?.[0].data).toBe(fresh);
+ expect(remove).not.toHaveBeenCalled();
+ });
+
it('reports cache failures without dropping subscription results or later patches', async () => {
const error = new Error('subscription cache write failed');
vi.spyOn(host, 'writeQuery').mockRejectedValueOnce(error);
@@ -2450,6 +2506,192 @@ describe('normalizedCacheExchange', () => {
expect(host.commits[0]?.transactionId).toBe('restored-1');
});
+ describe('mutation drain after cache restoration', () => {
+ beforeEach(() => vi.useFakeTimers());
+ afterEach(() => {
+ vi.clearAllTimers();
+ vi.useRealTimers();
+ vi.restoreAllMocks();
+ });
+
+ it.each([
+ { wake: 'online', whileDeferring: false },
+ { wake: 'online', whileDeferring: true },
+ { wake: 'restore', whileDeferring: false },
+ { wake: 'restore', whileDeferring: true },
+ ])(
+ 'preserves short retry deadlines after $wake (while deferring: $whileDeferring)',
+ async ({ wake, whileDeferring }) => {
+ // Isolate the online listener from other exchanges in this suite.
+ const events = new EventTarget();
+ vi.spyOn(globalThis, 'addEventListener').mockImplementation(
+ events.addEventListener.bind(events)
+ );
+ const deferring = deferred<void>();
+ const defer = host.deferOptimisticWrite.bind(host);
+ const deferSpy = vi.spyOn(host, 'deferOptimisticWrite');
+ if (whileDeferring) {
+ deferSpy.mockImplementationOnce(async (...args) => {
+ const result = await defer(...args);
+ await deferring.promise;
+ return result;
+ });
+ }
+ const error = new CombinedError({
+ networkError: new Error('offline'),
+ });
+ let attempts = 0;
+ const { ops, forwarded } = harness(
+ host,
+ () =>
+ ++attempts <= 5
+ ? { error, data: undefined }
+ : { data: optimistic },
+ { shouldRetryMutation: () => true }
+ );
+ ops.next(makeMutationOp(1, optimistic));
+ await vi.advanceTimersByTimeAsync(0);
+
+ for (const delay of [1_000, 2_000, 4_000, 8_000, 16_000]) {
+ const retryAt = deferSpy.mock.calls.at(-1)![2];
+ expect(retryAt - Date.now()).toBe(delay);
+ const sendsBeforeWake = forwarded.length;
+ await vi.advanceTimersByTimeAsync(100);
+ if (wake === 'online') events.dispatchEvent(new Event('online'));
+ else host.pushGeneration({ storage: 'reset' });
+ await vi.advanceTimersByTimeAsync(1);
+ deferring.resolve();
+ await vi.advanceTimersByTimeAsync(1);
+ expect(forwarded).toHaveLength(sendsBeforeWake);
+
+ await vi.advanceTimersByTimeAsync(retryAt - Date.now() - 1);
+ expect(forwarded).toHaveLength(sendsBeforeWake);
+ await vi.advanceTimersByTimeAsync(1);
+ expect(forwarded).toHaveLength(sendsBeforeWake + 1);
+ }
+ expect(host.begins).toHaveLength(1);
+ expect(host.defers).toHaveLength(5);
+ expect(host.commits).toHaveLength(1);
+ expect(host.rollbacks).toHaveLength(0);
+ }
+ );
+
+ it('retires an expired retry hint if another runner owns the head', async () => {
+ const error = new CombinedError({ networkError: new Error('offline') });
+ const { ops, forwarded } = harness(
+ host,
+ () => ({ error, data: undefined }),
+ { shouldRetryMutation: () => true }
+ );
+ ops.next(makeMutationOp(1, optimistic));
+ await vi.advanceTimersByTimeAsync(0);
+ const claim = vi
+ .spyOn(host, 'claimNextMutation')
+ .mockResolvedValue(undefined);
+ await vi.advanceTimersByTimeAsync(100);
+ host.pushGeneration({ storage: 'reset' });
+ await vi.advanceTimersByTimeAsync(0);
+ expect(claim).toHaveBeenCalledOnce();
+ await vi.advanceTimersByTimeAsync(1_000);
+ expect(claim).toHaveBeenCalledTimes(2);
+ expect(forwarded).toHaveLength(1);
+ });
+
+ it.each([false, true])(
+ 'resumes an interrupted claim without waiting for the poll (restore while pending: %s)',
+ async (restoreWhilePending) => {
+ const pendingClaim = deferred<ClaimedMutation | undefined>();
+ const claim = vi.spyOn(host, 'claimNextMutation');
+ claim.mockImplementationOnce(() => pendingClaim.promise);
+ host.seedQueued({
+ uuid: crypto.randomUUID(),
+ query: stringifyDocument(MUTATION),
+ data: optimistic,
+ });
+ const { forwarded } = harness(host);
+ await vi.advanceTimersByTimeAsync(0);
+ expect(claim).toHaveBeenCalledOnce();
+
+ if (restoreWhilePending) {
+ host.pushGeneration({ storage: 'reset' });
+ await vi.advanceTimersByTimeAsync(1);
+ expect(claim).toHaveBeenCalledOnce();
+ }
+ pendingClaim.reject(new CacheNavigationError());
+ await vi.advanceTimersByTimeAsync(1);
+ if (!restoreWhilePending) {
+ expect(forwarded).toHaveLength(0);
+ host.pushGeneration({ storage: 'reset' });
+ await vi.advanceTimersByTimeAsync(1);
+ }
+
+ expect(host.claims).toEqual(['restored-1']);
+ expect(host.commits).toHaveLength(1);
+ expect(forwarded.map((op) => op.kind)).toEqual(['mutation']);
+ }
+ );
+
+ it.each([
+ { restoreWhilePending: false, committed: false },
+ { restoreWhilePending: false, committed: true },
+ { restoreWhilePending: true, committed: false },
+ { restoreWhilePending: true, committed: true },
+ ])(
+ 'rechecks an uncertain commit without bypassing leases ($restoreWhilePending, $committed)',
+ async ({ restoreWhilePending, committed }) => {
+ const pendingCommit = deferred<CommitOptimisticWriteResult>();
+ const commit = host.commitOptimisticWrite.bind(host);
+ vi.spyOn(host, 'commitOptimisticWrite').mockImplementationOnce(
+ async (...args) => {
+ // The worker may have committed even though its reply was lost.
+ if (committed) await commit(...args);
+ return await pendingCommit.promise;
+ }
+ );
+ const claim = vi.spyOn(host, 'claimNextMutation');
+ const { ops, forwarded, results } = harness(host);
+ await vi.advanceTimersByTimeAsync(0);
+ ops.next(makeMutationOp(1, optimistic));
+ await vi.advanceTimersByTimeAsync(1);
+ host.seedQueued({
+ uuid: crypto.randomUUID(),
+ query: stringifyDocument(MUTATION),
+ data: optimistic,
+ });
+ const claimsBeforeRestore = claim.mock.calls.length;
+
+ if (restoreWhilePending) {
+ host.pushGeneration({ storage: 'reset' });
+ await vi.advanceTimersByTimeAsync(1);
+ expect(claim).toHaveBeenCalledTimes(claimsBeforeRestore);
+ }
+ pendingCommit.reject(new CacheNavigationError());
+ await vi.advanceTimersByTimeAsync(1);
+ if (!restoreWhilePending) {
+ host.pushGeneration({ storage: 'reset' });
+ await vi.advanceTimersByTimeAsync(1);
+ }
+
+ expect(claim.mock.calls.length).toBeGreaterThan(claimsBeforeRestore);
+ expect(
+ optimisticMutationDispositionOf(
+ results.find((result) => result.operation.key === 1)!
+ )
+ ).toEqual({ kind: 'queued', transactionId: 'txn-1' });
+ // A runnable successor is sent immediately, but an unsettled head's
+ // existing lease must never be stolen or its network call duplicated.
+ expect(forwarded).toHaveLength(committed ? 2 : 1);
+ expect(host.commits).toHaveLength(committed ? 2 : 0);
+ const claimsAfterRestore = claim.mock.calls.length;
+ await vi.advanceTimersByTimeAsync(30_000);
+ // Forget the stale five-minute local backoff even if no head could
+ // be claimed on restore; the durable queue still controls eligibility.
+ expect(claim.mock.calls.length).toBeGreaterThan(claimsAfterRestore);
+ expect(forwarded).toHaveLength(committed ? 2 : 1);
+ }
+ );
+ });
+
it('rolls back when a persisted replay resolves with an urql error', async () => {
host.seedQueued({
uuid: '00000000-0000-4000-8000-000000000002',
diff --git a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts
index b2fac447bb..96707a1722 100644
--- a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts
@@ -767,17 +767,31 @@ export function normalizedCacheExchange(
}
>();
const subscriptionEffectChains = new Map<number, Promise<void>>();
+ // Teardown invalidates queued effects, including when the same operation
+ // is immediately resubscribed after a back/forward-cache restore.
+ const subscriptionGenerations = new Map<number, object>();
let attemptInFlight = false;
let drainRunning = false;
+ let drainRequested = false;
let deferredUntil: number | undefined;
let drainTimer: ReturnType<typeof setTimeout> | undefined;
function scheduleDrain(delayMs = 0): void {
if (drainTimer !== undefined) clearTimeout(drainTimer);
- drainTimer = setTimeout(() => {
- drainTimer = undefined;
- void drainQueue();
- }, delayMs);
+ drainTimer = setTimeout(
+ () => {
+ drainTimer = undefined;
+ void drainQueue();
+ },
+ drainRequested ? 0 : delayMs
+ );
+ }
+
+ function wakeDrain(): void {
+ // Keep the wakeup until the runner can claim again. An interrupted
+ // claim/settlement may still be unwinding and scheduling its backoff.
+ drainRequested = true;
+ scheduleDrain();
}
function resolveLiveOperationsAsQueued(): void {
@@ -880,8 +894,15 @@ export function normalizedCacheExchange(
}
if (drainRunning) return;
drainRunning = true;
+ drainRequested = false;
try {
const now = Date.now();
+ // A wakeup probes immediately, but must retain a future retry
+ // deadline if the durable head is not eligible yet. Consume expired
+ // hints so a head leased by another runner cannot cause a busy loop.
+ if (deferredUntil !== undefined && deferredUntil <= now) {
+ deferredUntil = undefined;
+ }
const claimed = await host.claimNextMutation(
queueOwner,
now,
@@ -889,10 +910,15 @@ export function normalizedCacheExchange(
);
if (!claimed) {
resolveLiveOperationsAsQueued();
+ // Short retries keep their deadline; uncertain five-minute lease
+ // backoffs must not prevent regular polling after a wakeup.
scheduleDrain(
deferredUntil === undefined
? EMPTY_QUEUE_POLL_MS
- : Math.max(0, deferredUntil - Date.now())
+ : Math.min(
+ EMPTY_QUEUE_POLL_MS,
+ Math.max(0, deferredUntil - Date.now())
+ )
);
return;
}
@@ -905,6 +931,7 @@ export function normalizedCacheExchange(
scheduleDrain(EMPTY_QUEUE_POLL_MS);
} finally {
drainRunning = false;
+ if (drainRequested) scheduleDrain();
}
}
@@ -1145,9 +1172,11 @@ export function normalizedCacheExchange(
/** Applies operation cache effects serially and isolates every failure. */
async function applyOperationCacheEffects(
op: Operation,
- effects: CacheEffect[]
+ effects: CacheEffect[],
+ isCurrent: () => boolean = () => true
): Promise<void> {
for (const effect of effects) {
+ if (!isCurrent()) return;
try {
if (effect.kind === 'write') {
await host.writeQuery({
@@ -1268,8 +1297,15 @@ export function normalizedCacheExchange(
// result after its effects settle.
const previousEffects =
subscriptionEffectChains.get(op.key) ?? Promise.resolve();
+ const generation = subscriptionGenerations.get(op.key);
const effects = previousEffects.then(() =>
- applyOperationCacheEffects(op, operationCacheEffects(result.data))
+ applyOperationCacheEffects(
+ op,
+ operationCacheEffects(result.data),
+ () =>
+ generation !== undefined &&
+ subscriptionGenerations.get(op.key) === generation
+ )
);
subscriptionEffectChains.set(op.key, effects);
try {
@@ -1492,7 +1528,11 @@ export function normalizedCacheExchange(
shared,
filter((op) => op.kind !== 'query' && op.kind !== 'mutation'),
tap((op) => {
+ if (op.kind === 'subscription') {
+ subscriptionGenerations.set(op.key, {});
+ }
if (op.kind === 'teardown') {
+ subscriptionGenerations.delete(op.key);
activeOps.delete(op.key);
queryStates.delete(op.key);
affectedRereads.forget(op.key);
@@ -1509,8 +1549,12 @@ export function normalizedCacheExchange(
if (!host.disabled) {
scheduleDrain();
+ // Includes BFCache restoration, even with no active query keys. The
+ // host gates claims on initialization; durable leases still decide
+ // which head is runnable after reconnecting.
+ host.onCacheGenerationChanged(wakeDrain);
if (typeof addEventListener === 'function') {
- addEventListener('online', () => scheduleDrain());
+ addEventListener('online', wakeDrain);
}
}
void unsubscribePush;
diff --git a/apps/web/src/lib/graphql-cache/host/navigation-error.ts b/apps/web/src/lib/graphql-cache/host/navigation-error.ts
new file mode 100644
index 0000000000..da34f6026e
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/host/navigation-error.ts
@@ -0,0 +1,7 @@
+/** Expected cancellation when a page releases its cache transport for navigation. */
+export class CacheNavigationError extends Error {
+ constructor() {
+ super('cache worker host was disposed for page navigation');
+ this.name = 'CacheNavigationError';
+ }
+}
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 13cb428559..e9265de39e 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
@@ -26,6 +26,7 @@ import {
CacheBootstrapExhaustedError,
COORDINATOR_CONNECT_TIMEOUT_MS,
} from '../worker/startup';
+import { CacheNavigationError } from './navigation-error';
import { createWorkerCacheHost } from './worker-host';
const CLIENT_ID = '00000000-0000-4000-8000-000000000007';
@@ -1557,6 +1558,235 @@ describe('createWorkerCacheHost', () => {
await draining;
});
+ it('classifies admitted and late navigation writes consistently', async () => {
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+ await host.currentRevision();
+ const adapter = requireAdapter();
+ adapter.ignoredKinds.add('write');
+ const args = {
+ query: 'subscription Updates { update }',
+ data: { update: 1 },
+ };
+ const admitted = host.writeQuery(args);
+ const rejected =
+ expect(admitted).rejects.toBeInstanceOf(CacheNavigationError);
+ await vi.waitFor(() => expect(adapter.requests.at(-1)?.kind).toBe('write'));
+ dispatchEvent(new PageTransitionEvent('pagehide'));
+ await rejected;
+ await expect(host.writeQuery(args)).rejects.toBeInstanceOf(
+ CacheNavigationError
+ );
+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+ await expect(host.currentRevision()).rejects.toBeInstanceOf(
+ CacheNavigationError
+ );
+ expect(adapterFactory).toHaveBeenCalledOnce();
+ });
+
+ it('reconnects the same host repeatedly and retains subscriptions and active query dependencies', async () => {
+ localStorage.setItem('graphql-cache:scope', 'scope-1');
+ const onInitializationError = vi.fn();
+ const host = createWorkerCacheHost({
+ scope: 'scope-1',
+ onInitializationError,
+ });
+ const affected = vi.fn();
+ const generations = vi.fn();
+ const changed = vi.fn();
+ const hydrated = vi.fn();
+ const settled = vi.fn();
+ host.onOpsAffected(affected);
+ host.onCacheGenerationChanged(generations);
+ host.onCacheChanged(changed);
+ host.onCacheChanged(hydrated, { includeHydration: true });
+ host.onMutationSettled(settled);
+
+ for (let cycle = 0; cycle < 2; cycle += 1) {
+ await host.readQuery({ opKey: 7, query: 'query Seven { seven }' });
+ await host.readQuery({ opKey: 9, query: 'query Nine { nine }' });
+ const old = requireAdapter();
+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
+ expect(old.dispose).toHaveBeenCalledWith({
+ graceful: false,
+ preserveDatabase: true,
+ });
+ await host.teardown(9);
+ await expect(host.currentRevision()).rejects.toBeInstanceOf(
+ CacheNavigationError
+ );
+ old.terminalError(new Error('late retired transport error'));
+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+ await host.currentRevision();
+ const replacement = requireAdapter();
+ expect(replacement).not.toBe(old);
+ expect(affected).toHaveBeenLastCalledWith([7]);
+ expect(generations).toHaveBeenLastCalledWith({ storage: 'reset' });
+ expect(host.clientId).toBe(CLIENT_ID);
+ expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
+ expect(replacement.options.scope).toBe('scope-1');
+ old.replace(100);
+ old.terminalError(new Error('late callback after restore'));
+ old.push({ kind: 'cache-changed', revision: INITIAL_CACHE_REVISION });
+ expect(changed).toHaveBeenCalledTimes(cycle);
+ replacement.push({
+ kind: 'cache-changed',
+ revision: INITIAL_CACHE_REVISION,
+ });
+ replacement.push({
+ kind: 'cache-hydrated',
+ revision: INITIAL_CACHE_REVISION,
+ });
+ replacement.push({
+ kind: 'mutation-settled',
+ settlement: { transactionId: '3', status: 'committed' },
+ });
+ expect(changed).toHaveBeenCalledTimes(cycle + 1);
+ expect(hydrated).toHaveBeenCalledTimes((cycle + 1) * 2);
+ expect(settled).toHaveBeenCalledTimes(cycle + 1);
+ }
+ expect(adapterFactory).toHaveBeenCalledTimes(3);
+ expect(onInitializationError).not.toHaveBeenCalled();
+ host.dispose();
+ });
+
+ it.each(['registration', 'init'] as const)(
+ 'restores when pagehide interrupts %s without resurrecting the old attempt',
+ async (phase) => {
+ configureAdapter = (fake) => {
+ if (phase === 'registration')
+ fake.start.mockImplementationOnce(() => new Promise(() => {}));
+ else fake.ignoredKinds.add('init');
+ };
+ const onInitializationError = vi.fn();
+ const host = createWorkerCacheHost({
+ scope: 'scope-1',
+ onInitializationError,
+ });
+ const affected = vi.fn();
+ host.onOpsAffected(affected);
+ const read = host.readQuery({ opKey: 7, query: 'query Seven { seven }' });
+ const rejected =
+ expect(read).rejects.toBeInstanceOf(CacheNavigationError);
+ const old = requireAdapter();
+ if (phase === 'init')
+ await vi.waitFor(() => expect(old.requests).toHaveLength(1));
+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
+ configureAdapter = () => undefined;
+ // No intervening microtask: exercise the old startup's catch/finally racing restore.
+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+ await rejected;
+ await expect(host.currentRevision()).resolves.toBe(
+ INITIAL_CACHE_REVISION
+ );
+ expect(requireAdapter()).not.toBe(old);
+ expect(affected).toHaveBeenCalledWith([7]);
+ expect(onInitializationError).not.toHaveBeenCalled();
+ expect(adapterFactory).toHaveBeenCalledTimes(2);
+ host.dispose();
+ }
+ );
+
+ it.each([false, true])(
+ 'does not resurrect an explicitly disposed host (restore started: %s)',
+ async (restoreStarted) => {
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+ await host.currentRevision();
+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
+ if (restoreStarted)
+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+ host.dispose();
+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+ await expect(host.currentRevision()).rejects.toThrow(
+ 'cache worker host was disposed'
+ );
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ expect(adapterFactory).toHaveBeenCalledOnce();
+ }
+ );
+
+ it('reports a failed restore through normal initialization fallback', async () => {
+ const onInitializationError = vi.fn();
+ const host = createWorkerCacheHost({
+ scope: 'scope-1',
+ onInitializationError,
+ });
+ await host.currentRevision();
+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
+ configureAdapter = (fake) => fake.errors.set('init', 'restore failed');
+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+ await expect(host.currentRevision()).rejects.toThrow('restore failed');
+ expect(onInitializationError).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({ message: 'restore failed' })
+ );
+ host.dispose();
+ });
+
+ it('revalidates reads attempted while suspended instead of counting them as replacement registrations', async () => {
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+ const affected = vi.fn();
+ host.onOpsAffected(affected);
+ await host.readQuery({ opKey: 7, query: 'query Seven { seven }' });
+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
+ for (const opKey of [7, 9]) {
+ await expect(
+ host.readQuery({ opKey, query: 'query Value { value }' })
+ ).rejects.toBeInstanceOf(CacheNavigationError);
+ }
+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+ await host.currentRevision();
+ expect(affected).toHaveBeenCalledWith([7, 9]);
+ host.dispose();
+ });
+
+ it('fences a pre-navigation write waiting to be admitted across immediate restoration', async () => {
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+ await host.currentRevision();
+ const stale = host.writeQuery({
+ query: 'query Value { value }',
+ data: { value: 'stale' },
+ });
+ const rejected = expect(stale).rejects.toBeInstanceOf(CacheNavigationError);
+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+ await rejected;
+ await host.currentRevision();
+ expect(requireAdapter().requests.some(({ kind }) => kind === 'write')).toBe(
+ false
+ );
+ host.dispose();
+ });
+
+ it('never replays an uncertain enqueue after restoration', async () => {
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+ await host.currentRevision();
+ const old = requireAdapter();
+ old.ignoredKinds.add('enqueue-optimistic-mutation');
+ const mutation = host.enqueueOptimisticMutation(
+ {
+ uuid: '00000000-0000-4000-8000-000000000100',
+ query: 'mutation Update { update }',
+ data: { update: true },
+ },
+ { owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
+ );
+ const rejected = expect(mutation).rejects.toMatchObject({
+ errorCode: 'admitted-enqueue-uncertain',
+ });
+ await vi.waitFor(() =>
+ expect(old.requests.at(-1)?.kind).toBe('enqueue-optimistic-mutation')
+ );
+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+ await rejected;
+ await host.currentRevision();
+ expect(requireAdapter().requests.map(({ kind }) => kind)).toEqual([
+ 'init',
+ 'current-revision',
+ ]);
+ host.dispose();
+ });
+
it('treats pagehide enqueue as uncertain without quarantining persistent storage', async () => {
configureAdapter = (fake) => {
fake.ignoredKinds.add('enqueue-optimistic-mutation');
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 b17ca76297..2c52f40999 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts
@@ -57,6 +57,7 @@ import {
COORDINATOR_CONNECT_TIMEOUT_MS,
STARTUP_RESPONSE_GRACE_MS,
} from '../worker/startup';
+import { CacheNavigationError } from './navigation-error';
import { createNoopCacheHost } from './noop-host';
import type {
CacheChangeOptions,
@@ -85,6 +86,7 @@ type HostState =
| 'initializing'
| 'awaiting-replacement'
| 'ready'
+ | 'suspended'
| 'disposing'
| 'failed'
| 'disposed';
@@ -175,13 +177,13 @@ const isOwnerEpochLoss = (error: unknown): error is CacheResponseError =>
error.errorCode === OWNER_EPOCH_LOST_ERROR_CODE;
export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
- const pageTelemetry = options.telemetry
+ let pageTelemetry = options.telemetry
? undefined
: createPageCacheTelemetry({
rolloutCohort: options.rolloutCohort ?? 'unknown',
sink: options.telemetrySink,
});
- const telemetry = isolateCacheTelemetry(
+ let telemetry = isolateCacheTelemetry(
options.telemetry ?? pageTelemetry?.recorder
);
const now = (): number => globalThis.performance?.now() ?? Date.now();
@@ -217,10 +219,13 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
let initializationTimeoutMs =
options.initializationTimeoutMs ?? COORDINATOR_CONNECT_TIMEOUT_MS;
let registrationInProgress = false;
- let cancelRegistration: (() => void) | undefined;
+ let cancelRegistration: ((error: Error) => void) | undefined;
let nextRequestId = 1;
let state: HostState = 'idle';
let initialization: Promise<void> | undefined;
+ let initializationAttempt = 0;
+ let navigationGeneration = 0;
+ let suspension: Promise<void> | undefined;
let initializationError: Error | undefined;
let replacementError: CacheResponseError | undefined;
let recoveryInProgress = false;
@@ -353,9 +358,13 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
ownerEpoch: number,
openOutcome: EngineOpenOutcome
): void {
- if (state === 'failed' || state === 'disposing' || state === 'disposed') {
+ if (
+ state === 'failed' ||
+ state === 'suspended' ||
+ state === 'disposing' ||
+ state === 'disposed'
+ )
return;
- }
if (ownerEpoch <= latestReplacementEpoch) return;
latestReplacementEpoch = ownerEpoch;
// Initial readiness completes the already-running first handshake.
@@ -376,9 +385,13 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
}
function observeOwnerEpochLoss(error: CacheResponseError): void {
- if (state === 'failed' || state === 'disposing' || state === 'disposed') {
+ if (
+ state === 'failed' ||
+ state === 'suspended' ||
+ state === 'disposing' ||
+ state === 'disposed'
+ )
return;
- }
beginRecoveryGeneration();
// A rejected old-epoch read may have registered dependencies before its
// response was lost. It belongs to the lost generation, not replacement.
@@ -393,13 +406,15 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
return;
}
removeEventListener('pagehide', onPagehide);
+ removeEventListener('pageshow', onPageshow);
pagehideRegistered = false;
}
function registerPagehide(): void {
if (pagehideRegistered || typeof addEventListener !== 'function') return;
pagehideRegistered = true;
- addEventListener('pagehide', onPagehide, { once: true });
+ addEventListener('pagehide', onPagehide);
+ addEventListener('pageshow', onPageshow);
}
function getAdapter(): CacheCoordinatorPageAdapter {
@@ -411,7 +426,9 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
const created = createCacheCoordinatorPageAdapter({
scope: options.scope,
hotCapacity: options.hotCapacity,
- onEngineReplaced,
+ onEngineReplaced: (epoch, outcome) => {
+ if (adapter === created) onEngineReplaced(epoch, outcome);
+ },
onStartupProgress: (progress) => {
if (adapter !== created) return;
initializationTimeoutMs =
@@ -425,18 +442,20 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
onTerminalError: (error) => {
// start() also rejects; let the bounded registration loop retry before
// reporting a terminal failure or quarantining any cache scope.
- if (adapter === created && !registrationInProgress)
+ if (adapter === created && !registrationInProgress && !suspension)
failTransport(error);
},
telemetry,
});
- created.onmessage = onMessage;
+ created.onmessage = (event) => {
+ if (adapter === created && state !== 'suspended') onMessage(event);
+ };
adapter = created;
registerPagehide();
return created;
}
- async function registerAdapter(): Promise<void> {
+ async function registerAdapter(initializationId: number): Promise<void> {
registrationInProgress = true;
try {
for (
@@ -450,10 +469,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
await Promise.race([
current.start(),
new Promise<never>((_resolve, reject) => {
- cancelRegistration = () =>
- reject(
- new Error('cache worker host was disposed during startup')
- );
+ cancelRegistration = reject;
timer = setTimeout(
() => reject(new Error('cache worker timeout: registration')),
options.initializationTimeoutMs ??
@@ -461,6 +477,8 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
);
}),
]);
+ if (initializationId !== initializationAttempt)
+ throw new CacheNavigationError();
if (state !== 'initializing')
throw new Error('cache worker host was disposed during startup');
registeredAdapter = current;
@@ -470,6 +488,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
await current.dispose({ graceful: false });
if (adapter === current) adapter = undefined;
if (
+ initializationId !== initializationAttempt ||
state !== 'initializing' ||
attempt + 1 === COORDINATOR_CONNECT_ATTEMPTS
)
@@ -567,6 +586,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
function failInitialization(error: Error): void {
if (
state === 'failed' ||
+ state === 'suspended' ||
state === 'disposing' ||
state === 'disposed' ||
state === 'ready'
@@ -597,7 +617,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
}
function failTransport(error: Error): void {
- if (terminalFailureHandled) return;
+ if (terminalFailureHandled || state === 'suspended') return;
const storageWasUntouched = error instanceof CacheBootstrapExhaustedError;
stopStorageHealthSampling();
const admittedWorkIsUncertain = [...pending.values()].some(
@@ -669,7 +689,11 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
}
function disposeHost(graceful: boolean, preserveDatabase = false): void {
- cancelRegistration?.();
+ cancelRegistration?.(
+ preserveDatabase
+ ? new CacheNavigationError()
+ : new Error('cache worker host was disposed during startup')
+ );
stopStorageHealthSampling();
if (state === 'disposed') return;
if (state === 'disposing') {
@@ -683,10 +707,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
if (preserveDatabase) {
disposalMode = 'navigation';
clearSubscribers();
- rejectPending(
- new Error('cache worker host was disposed for page navigation'),
- true
- );
+ rejectPending(new CacheNavigationError(), true);
startAdapterDisposal(false, true);
return;
}
@@ -715,10 +736,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
clearSubscribers();
if (preserveDatabase) {
disposalMode = 'navigation';
- rejectPending(
- new Error('cache worker host was disposed for page navigation'),
- true
- );
+ rejectPending(new CacheNavigationError(), true);
startAdapterDisposal(false, true);
return;
}
@@ -730,8 +748,65 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
startAdapterDisposal(false);
}
- function onPagehide(): void {
- disposeHost(false, true);
+ async function finishSuspension(
+ startup: Promise<void> | undefined,
+ retirement: Promise<void>
+ ): Promise<void> {
+ // A canceled registration must unwind before a replacement can publish its
+ // adapter. Never let the old startup's finally block clear the new one.
+ try {
+ await startup;
+ } catch {
+ // Navigation already settled startup callers.
+ }
+ await retirement;
+ }
+
+ function onPagehide(event: PageTransitionEvent): void {
+ if (
+ !event.persisted ||
+ state === 'failed' ||
+ state === 'disposing' ||
+ state === 'disposed'
+ ) {
+ disposeHost(false, true);
+ return;
+ }
+ if (state === 'suspended') return;
+ state = 'suspended';
+ navigationGeneration += 1;
+ initializationAttempt += 1;
+ beginRecoveryGeneration();
+ // All active operations need fresh dependencies after reconnect, including
+ // reads that never reached the old engine before the page was frozen.
+ for (const key of activeOpKeys) lostRegisteredOpKeys.add(key);
+ replacementReadOpKeys.clear();
+ cancelRegistration?.(new CacheNavigationError());
+ rejectPending(new CacheNavigationError(), true);
+ if (adapter) adapter.onmessage = null;
+ suspension = finishSuspension(initialization, disposeAdapter(false, true));
+ finishTelemetry();
+ }
+
+ async function resumeAfterNavigation(): Promise<void> {
+ try {
+ // Keep the host and all its subscribers alive; only the page transport is
+ // replaced. Initialization waits for the suspended startup to unwind.
+ await startInitialization();
+ } catch {
+ // Non-navigation failures already invoke the normal product fallback.
+ }
+ }
+
+ function onPageshow(event: PageTransitionEvent): void {
+ if (!event.persisted || state !== 'suspended') return;
+ void resumeAfterNavigation();
+ }
+
+ function navigationError(): CacheNavigationError | undefined {
+ if (state === 'suspended' || disposalMode === 'navigation') {
+ return new CacheNavigationError();
+ }
}
function armRequestTimeout(
@@ -759,6 +834,8 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
initializationError ?? new Error('cache worker initialization failed')
);
}
+ const canceled = navigationError();
+ if (canceled) return Promise.reject(canceled);
if (state === 'disposing' || state === 'disposed') {
return Promise.reject(new Error('cache worker host was disposed'));
}
@@ -862,18 +939,53 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
scope: options.scope,
hotCapacity: options.hotCapacity,
});
- const ready =
- adapter && registeredAdapter === adapter
- ? sendInit()
- : (async () => {
- await registerAdapter();
- return await sendInit();
- })();
+ const attempt = ++initializationAttempt;
+ const suspended = suspension;
+ const ready = (async () => {
+ if (suspended) {
+ await suspended;
+ if (attempt !== initializationAttempt) throw new CacheNavigationError();
+ if (state !== 'initializing')
+ throw new Error('cache worker host was disposed');
+ suspension = undefined;
+ adapter = undefined;
+ registeredAdapter = undefined;
+ adapterDisposePromise = undefined;
+ adapterDisposeWasGraceful = false;
+ adapterDisposalStarted = false;
+ latestReplacementEpoch = 0;
+ initializationTimeoutMs =
+ options.initializationTimeoutMs ?? COORDINATOR_CONNECT_TIMEOUT_MS;
+ telemetryFinished = false;
+ telemetryRelayStarted = false;
+ pageTelemetry = options.telemetry
+ ? undefined
+ : createPageCacheTelemetry({
+ rolloutCohort: options.rolloutCohort ?? 'unknown',
+ sink: options.telemetrySink,
+ });
+ telemetry = isolateCacheTelemetry(
+ options.telemetry ?? pageTelemetry?.recorder
+ );
+ }
+ if (!adapter || registeredAdapter !== adapter)
+ await registerAdapter(attempt);
+ if (attempt !== initializationAttempt) throw new CacheNavigationError();
+ return await sendInit();
+ })();
const handshake = ready.then(
() => {
- if (state !== 'initializing') return;
+ if (attempt !== initializationAttempt || state !== 'initializing')
+ return;
state = 'ready';
initialization = undefined;
+ if (suspended) {
+ // A surviving coordinator need not send engine-replaced to a late
+ // joiner. Resets while frozen are unknowable, so conservatively
+ // invalidate local checkpoints as well as revision/dependency state.
+ for (const cb of generationChangeSubscribers)
+ cb({ storage: 'reset' });
+ }
telemetry?.record({
name: 'graphql_cache.host_ready',
operationCategory: 'initialization',
@@ -895,6 +1007,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
},
(error: unknown) => {
const initializationFailure = asError(error);
+ if (attempt !== initializationAttempt) throw initializationFailure;
initialization = undefined;
if (isOwnerEpochLoss(initializationFailure)) {
observeOwnerEpochLoss(initializationFailure);
@@ -921,29 +1034,45 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
initializationError ?? new Error('cache worker initialization failed')
);
}
+ const canceled = navigationError();
+ if (canceled) return Promise.reject(canceled);
if (state === 'disposing' || state === 'disposed') {
return Promise.reject(new Error('cache worker host was disposed'));
}
return startInitialization();
}
+ async function initializedRequest(
+ msg: DistributiveOmit<CacheRequest, 'id'>,
+ opKey?: number
+ ): Promise<unknown> {
+ const generation = navigationGeneration;
+ await ensureInitialized();
+ // Do not admit an old-page operation to a newly restored transport.
+ if (generation !== navigationGeneration) throw new CacheNavigationError();
+ return await request(msg, opKey);
+ }
+
+ function trackActiveOperation(opKey: number): void {
+ activeOpKeys.add(opKey);
+ if (state === 'suspended') lostRegisteredOpKeys.add(opKey);
+ else if (recoveryInProgress) replacementReadOpKeys.add(opKey);
+ }
+
const opId = (opKey: number) => `${clientId}:${opKey}`;
return {
clientId,
async currentRevision(): Promise<CacheRevision> {
- await ensureInitialized();
- return (await request({ kind: 'current-revision' })) as CacheRevision;
+ return (await initializedRequest({
+ kind: 'current-revision',
+ })) as CacheRevision;
},
async readQuery(args: CacheReadArgs): Promise<ReadResult> {
- if (args.opKey !== undefined) {
- activeOpKeys.add(args.opKey);
- if (recoveryInProgress) replacementReadOpKeys.add(args.opKey);
- }
- await ensureInitialized();
- return (await request(
+ if (args.opKey !== undefined) trackActiveOperation(args.opKey);
+ return (await initializedRequest(
{
kind: 'read',
opId: args.opKey === undefined ? undefined : opId(args.opKey),
@@ -961,8 +1090,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
args: ReadRecordsByKeysArgs
): Promise<ReadRecordsByKeysResult> {
const keys = validateRecordSelectionKeys(args.keys);
- await ensureInitialized();
- return (await request({
+ return (await initializedRequest({
kind: 'read-records-by-keys',
document: args.document,
fragmentName: args.fragmentName,
@@ -972,8 +1100,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
async search(args: SearchCacheArgs): Promise<SearchCachePage> {
const requestArgs = validateCacheSearchArgs(args);
- await ensureInitialized();
- return (await request({
+ return (await initializedRequest({
kind: 'search',
request: requestArgs,
})) as SearchCachePage;
@@ -982,8 +1109,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
async entityFilter(
args: EntityFilterCacheArgs
): Promise<EntityFilterCacheResult> {
- await ensureInitialized();
- return (await request({
+ return (await initializedRequest({
kind: 'entity-filter',
request: args,
})) as EntityFilterCacheResult;
@@ -991,11 +1117,9 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
async writeQuery(args: CacheWriteArgs): Promise<WriteResult> {
if (args.registerDependencies && args.opKey !== undefined) {
- activeOpKeys.add(args.opKey);
- if (recoveryInProgress) replacementReadOpKeys.add(args.opKey);
+ trackActiveOperation(args.opKey);
}
- await ensureInitialized();
- return (await request(
+ return (await initializedRequest(
{
kind: 'write',
originOpId: args.opKey === undefined ? undefined : opId(args.opKey),
@@ -1019,8 +1143,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
async hydrateQuery(
args: Omit<CacheWriteArgs, 'opKey'>
): Promise<HydrationResult> {
- await ensureInitialized();
- return (await request({
+ return (await initializedRequest({
kind: 'hydrate',
query: args.query,
operationName: args.operationName,
@@ -1034,8 +1157,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
args: EnqueueOptimisticMutationArgs,
claim: InitialMutationClaimArgs
): Promise<EnqueueOptimisticMutationResult> {
- await ensureInitialized();
- return (await request({
+ return (await initializedRequest({
kind: 'enqueue-optimistic-mutation',
originOpId: args.opKey === undefined ? undefined : opId(args.opKey),
uuid: args.uuid,
@@ -1055,8 +1177,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
async inspectQueryVariants(
args: InspectQueryVariantsArgs
): Promise<CachedQueryVariantWire[]> {
- await ensureInitialized();
- return (await request({
+ return (await initializedRequest({
kind: 'inspect-query-variants',
query: args.query,
operationName: args.operationName,
@@ -1067,8 +1188,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
async inspectQuery(
args: InspectQueryArgs
): Promise<CachedQueryInstanceWire[]> {
- await ensureInitialized();
- return (await request({
+ return (await initializedRequest({
kind: 'inspect-query',
query: args.query,
operationName: args.operationName,
@@ -1082,8 +1202,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
nowMs: number,
leaseExpiresAtMs: number
): Promise<ClaimedMutation | undefined> {
- await ensureInitialized();
- return (await request({
+ return (await initializedRequest({
kind: 'claim-next-mutation',
owner,
nowMs,
@@ -1097,8 +1216,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
nextAttemptAtMs: number,
error: string
) {
- await ensureInitialized();
- return (await request({
+ return (await initializedRequest({
kind: 'defer-optimistic-write',
transactionId,
leaseOwner: claim.owner,
@@ -1113,8 +1231,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
claim: MutationClaim,
args: CacheWriteArgs
): Promise<CommitOptimisticWriteResult> {
- await ensureInitialized();
- return (await request({
+ return (await initializedRequest({
kind: 'commit-optimistic-write',
transactionId,
leaseOwner: claim.owner,
@@ -1131,8 +1248,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
claim: MutationClaim,
error: string
): Promise<RollbackOptimisticWriteResult> {
- await ensureInitialized();
- return (await request({
+ return (await initializedRequest({
kind: 'rollback-optimistic-write',
transactionId,
leaseOwner: claim.owner,
@@ -1142,16 +1258,14 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
},
async invalidate(keys: string[]): Promise<AffectedOperationsResult> {
- await ensureInitialized();
- return (await request({
+ return (await initializedRequest({
kind: 'invalidate',
keys,
})) as AffectedOperationsResult;
},
async deleteRecords(keys: string[]): Promise<AffectedOperationsResult> {
- await ensureInitialized();
- return (await request({
+ return (await initializedRequest({
kind: 'delete-records',
keys,
})) as AffectedOperationsResult;
@@ -1179,8 +1293,9 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
},
async clear(): Promise<CacheRevision> {
- await ensureInitialized();
- const revision = (await request({ kind: 'clear' })) as CacheRevision;
+ const revision = (await initializedRequest({
+ kind: 'clear',
+ })) as CacheRevision;
telemetry?.record({
name: 'graphql_cache.logical_reset',
operationCategory: 'lifecycle',
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle-harness.ts
index 2c21603da7..de6dee4dba 100644
--- a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle-harness.ts
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-lifecycle-harness.ts
@@ -1,3 +1,6 @@
+import { type Client, createClient, gql, stringifyDocument } from '@urql/core';
+import { filter, map, pipe } from 'wonka';
+import { normalizedCacheExchange } from '../../exchange/normalized-cache-exchange';
import type { CacheHost } from '../../host/types';
import { createWorkerCacheHost } from '../../host/worker-host';
import { clearRegisteredCaches, registerCacheHost } from '../../lifecycle';
@@ -33,6 +36,17 @@ let owner: CacheHost | undefined;
let standby: CacheHost | undefined;
let unregisterOwner: (() => void) | undefined;
let hostConstructionCount = 0;
+const restoredGenerations: string[] = [];
+const affectedOperations: number[][] = [];
+let cacheChanges = 0;
+let pageRestores = 0;
+let watchingNavigation = false;
+let mutationRunner: Client | undefined;
+let mutationReplays = 0;
+const settledMutations: string[] = [];
+addEventListener('pageshow', (event: PageTransitionEvent) => {
+ if (event.persisted) pageRestores += 1;
+});
const query = (
operationName: string
@@ -122,6 +136,108 @@ const api = {
async startSingle(): Promise<void> {
await startOwner();
},
+ async watchNavigation(): Promise<void> {
+ const host = requireOwner();
+ if (!watchingNavigation) {
+ watchingNavigation = true;
+ host.onCacheGenerationChanged(({ storage }) =>
+ restoredGenerations.push(storage)
+ );
+ host.onOpsAffected((keys) => affectedOperations.push(keys));
+ host.onCacheChanged(() => (cacheChanges += 1));
+ }
+ await host.readQuery({
+ opKey: 4242,
+ query: query('CacheLifecycleQuery'),
+ operationName: 'CacheLifecycleQuery',
+ variables: variables(1),
+ });
+ },
+ async queueMutationForRestore(): Promise<string> {
+ const host = requireOwner();
+ const mutation = gql`
+ mutation CacheLifecycleMutation($input: SetEntityPropertyInput!) {
+ setEntityProperty(input: $input) { id displayName }
+ }
+ `;
+ const response = {
+ setEntityProperty: { id: 'restored-property', displayName: 'Restored' },
+ };
+ if (!mutationRunner) {
+ const firstClaim = Promise.withResolvers<void>();
+ host.onMutationSettled(({ transactionId }) =>
+ settledMutations.push(transactionId)
+ );
+ mutationRunner = createClient({
+ url: 'http://cache-lifecycle.test/graphql',
+ exchanges: [
+ normalizedCacheExchange({
+ ...host,
+ async claimNextMutation(...args) {
+ const claimed = await host.claimNextMutation(...args);
+ firstClaim.resolve();
+ return claimed;
+ },
+ }),
+ () => (operations) =>
+ pipe(
+ operations,
+ filter((operation) => operation.kind === 'mutation'),
+ map((operation) => {
+ mutationReplays += 1;
+ return {
+ operation,
+ data: response,
+ stale: false,
+ hasNext: false,
+ };
+ })
+ ),
+ ],
+ });
+ // Let the initial empty-queue poll finish before inserting runnable work.
+ await firstClaim.promise;
+ }
+ const nowMs = Date.now();
+ const owner = 'browser-test-seed';
+ const queued = await host.enqueueOptimisticMutation(
+ {
+ uuid: crypto.randomUUID(),
+ query: stringifyDocument(mutation),
+ variables: {
+ input: {
+ entityType: 'DOCUMENT',
+ entityId: 'restored-document',
+ propertyDefinitionId: 'restored-definition',
+ value: { string: 'restored' },
+ },
+ },
+ data: response,
+ },
+ { owner, nowMs, leaseExpiresAtMs: nowMs + 300_000 }
+ );
+ if (queued.initialClaim.kind !== 'claimed') {
+ throw new Error('expected to claim the browser-test mutation');
+ }
+ await host.deferOptimisticWrite(
+ queued.transactionId,
+ { owner, generation: queued.initialClaim.mutation.leaseGeneration },
+ nowMs,
+ 'runnable on restore'
+ );
+ return queued.transactionId;
+ },
+ navigationState() {
+ return {
+ clientId: requireOwner().clientId,
+ restoredGenerations: [...restoredGenerations],
+ affectedOperations: [...affectedOperations],
+ cacheChanges,
+ pageRestores,
+ mutationReplays,
+ settledMutations: [...settledMutations],
+ };
+ },
async startLogoutHost(): Promise<void> {
await startOwner(true);
},
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 a8c8addf11..c148c594f8 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
@@ -36,6 +36,163 @@ const cacheResources = (urls: string[]) => ({
],
});
+test('Cache reconnects in place across persisted page lifecycle events', async ({
+ page,
+}, testInfo) => {
+ const scope = `cache-restore-${crypto.randomUUID()}`;
+ await page.goto(
+ `${harnessPath(testInfo.project.name)}?treatment=true&scope=${scope}`
+ );
+ await expect(page.locator('#result')).toHaveAttribute('data-status', 'ready');
+ await page.evaluate(async () => {
+ await window.cacheLifecycleHarness.startSingle();
+ await window.cacheLifecycleHarness.write('before-navigation');
+ await window.cacheLifecycleHarness.watchNavigation();
+ const editor = document.createElement('textarea');
+ editor.id = 'unsaved-editor';
+ editor.value = 'unsaved local text';
+ document.body.append(editor);
+ });
+ const original = await page.evaluate(() =>
+ window.cacheLifecycleHarness.navigationState()
+ );
+ for (let cycle = 0; cycle < 2; cycle += 1) {
+ const transactionId = await page.evaluate(() =>
+ window.cacheLifecycleHarness.queueMutationForRestore()
+ );
+ const result = await page.evaluate(async () => {
+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
+ let cancellation: string | undefined;
+ try {
+ await window.cacheLifecycleHarness.write('must-not-write');
+ } catch (error) {
+ cancellation = (error as Error).name;
+ }
+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+ return { cancellation, read: await window.cacheLifecycleHarness.read() };
+ });
+ expect(result.cancellation).toBe('CacheNavigationError');
+ expect(isHit(result.read)).toBe(true);
+ expect(JSON.stringify(result.read)).not.toContain('must-not-write');
+ await page.evaluate(
+ (cycle) => window.cacheLifecycleHarness.write(`after-restore-${cycle}`),
+ cycle
+ );
+ await expect
+ .poll(() =>
+ page.evaluate(
+ () => window.cacheLifecycleHarness.navigationState().cacheChanges
+ )
+ )
+ .toBeGreaterThan(original.cacheChanges + cycle);
+ await expect
+ .poll(() =>
+ page.evaluate(
+ () => window.cacheLifecycleHarness.navigationState().settledMutations
+ )
+ )
+ .toContain(transactionId);
+ const restored = await page.evaluate(() =>
+ window.cacheLifecycleHarness.navigationState()
+ );
+ expect(restored.mutationReplays).toBe(cycle + 1);
+ expect(restored.clientId).toBe(original.clientId);
+ expect(restored.affectedOperations).toContainEqual([4242]);
+ expect(restored.restoredGenerations).toContain('reset');
+ expect(await page.locator('#unsaved-editor').inputValue()).toBe(
+ 'unsaved local text'
+ );
+ // Re-register like the urql affected-query handler before the next cycle.
+ await page.evaluate(() => window.cacheLifecycleHarness.watchNavigation());
+ }
+ expect(
+ await page.evaluate(() =>
+ window.cacheLifecycleHarness.hostConstructionCount()
+ )
+ ).toBe(1);
+ await page.evaluate(() => window.cacheLifecycleHarness.dispose());
+});
+
+test('Cache preserves editor state and reconnects after a real back-forward-cache restore', async ({
+ browser,
+ baseURL,
+}, testInfo) => {
+ test.skip(
+ browser.browserType().name() !== 'chromium',
+ 'Chromium-specific BFCache launch configuration'
+ );
+ // Playwright disables BFCache by default. A separate browser enables an
+ // actual restore without changing assumptions of the other lifecycle tests.
+ const restoringBrowser = await browser.browserType().launch({
+ ...testInfo.project.use.launchOptions,
+ ignoreDefaultArgs: ['--disable-back-forward-cache'],
+ });
+ try {
+ const page = await restoringBrowser.newPage();
+ const path = new URL(harnessPath(testInfo.project.name), baseURL).href;
+ const scope = `cache-real-restore-${crypto.randomUUID()}`;
+ await page.goto(`${path}?treatment=true&scope=${scope}`);
+ await page.evaluate(async () => {
+ await window.cacheLifecycleHarness.startSingle();
+ await window.cacheLifecycleHarness.write('before-real-navigation');
+ await window.cacheLifecycleHarness.watchNavigation();
+ const editor = document.createElement('textarea');
+ editor.id = 'unsaved-editor';
+ editor.value = 'unsaved text across Back';
+ document.body.append(editor);
+ });
+ const before = await page.evaluate(() =>
+ window.cacheLifecycleHarness.navigationState()
+ );
+ const transactionId = await page.evaluate(() =>
+ window.cacheLifecycleHarness.queueMutationForRestore()
+ );
+ await page.goto(`${path}?treatment=false`);
+ await page.goBack({ waitUntil: 'commit' });
+ expect(await page.locator('#unsaved-editor').inputValue()).toBe(
+ 'unsaved text across Back'
+ );
+ const read = await page.evaluate(() => window.cacheLifecycleHarness.read());
+ expect(isHit(read)).toBe(true);
+ expect(JSON.stringify(read)).toContain('before-real-navigation');
+ const restored = await page.evaluate(() =>
+ window.cacheLifecycleHarness.navigationState()
+ );
+ expect(restored.pageRestores).toBe(1);
+ await expect
+ .poll(() =>
+ page.evaluate(
+ () => window.cacheLifecycleHarness.navigationState().settledMutations
+ )
+ )
+ .toContain(transactionId);
+ expect(
+ await page.evaluate(
+ () => window.cacheLifecycleHarness.navigationState().mutationReplays
+ )
+ ).toBe(1);
+ expect(restored.clientId).toBe(before.clientId);
+ expect(restored.affectedOperations).toContainEqual([4242]);
+ await page.evaluate(() =>
+ window.cacheLifecycleHarness.write('after-real-restore')
+ );
+ expect(
+ JSON.stringify(
+ await page.evaluate(() => window.cacheLifecycleHarness.read())
+ )
+ ).toContain('after-real-restore');
+ await expect
+ .poll(() =>
+ page.evaluate(
+ () => window.cacheLifecycleHarness.navigationState().cacheChanges
+ )
+ )
+ .toBeGreaterThan(before.cacheChanges);
+ } finally {
+ await restoringBrowser.close();
+ }
+});
+
test('Cache exact host stays navigation-lazy, preserves offline handoff, resets identity, and wipes abrupt loss', async ({
context,
page,
diff --git a/apps/web/src/lib/queries/preview/tests/graphql-reactivity.test.ts b/apps/web/src/lib/queries/preview/tests/graphql-reactivity.test.ts
index c6c3b5cde5..e2bbac2217 100644
--- a/apps/web/src/lib/queries/preview/tests/graphql-reactivity.test.ts
+++ b/apps/web/src/lib/queries/preview/tests/graphql-reactivity.test.ts
@@ -90,6 +90,7 @@ describe('GraphQL preview hover reactivity', () => {
const host = {
clientId: 'preview-test',
onOpsAffected: () => () => {},
+ onCacheGenerationChanged: () => () => {},
claimNextMutation: async () => undefined,
readQuery: async () =>
cachedData
@@ -110,6 +111,7 @@ describe('GraphQL preview hover reactivity', () => {
CacheHost,
| 'clientId'
| 'onOpsAffected'
+ | 'onCacheGenerationChanged'
| 'claimNextMutation'
| 'readQuery'
| 'writeQuery'
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.test.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.test.ts
index 977896c113..f11838d467 100644
--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.test.ts
+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.test.ts
@@ -125,6 +125,57 @@ describe('GraphQL Soup subscription lifecycle', () => {
for (const unsubscribe of unsubscribes)
expect(unsubscribe).toHaveBeenCalledOnce();
});
+ it('pauses subscriptions for navigation and reconnects in place exactly once per restore', () => {
+ const unsubscribes: Array<ReturnType<typeof vi.fn>> = [];
+ const client = {
+ query: vi.fn(),
+ subscription: vi.fn(() => ({
+ subscribe: vi.fn(() => {
+ const unsubscribe = vi.fn();
+ unsubscribes.push(unsubscribe);
+ return { unsubscribe };
+ }),
+ })),
+ };
+ const lifecycle = createGraphqlSoupSubscriptionsLifecycle({
+ suspendOnPagehide: true,
+ });
+ lifecycle.replace(client as never, { disabled: false } as never);
+ expect(client.subscription).toHaveBeenCalledTimes(3);
+ for (let cycle = 0; cycle < 2; cycle += 1) {
+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
+ for (const unsubscribe of unsubscribes)
+ expect(unsubscribe).toHaveBeenCalledOnce();
+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: false }));
+ expect(client.subscription).toHaveBeenCalledTimes((cycle + 1) * 3);
+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+ expect(client.subscription).toHaveBeenCalledTimes((cycle + 2) * 3);
+ }
+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
+ lifecycle.dispose();
+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+ expect(client.subscription).toHaveBeenCalledTimes(9);
+ for (const unsubscribe of unsubscribes)
+ expect(unsubscribe).toHaveBeenCalledOnce();
+ });
+
+ it('does not attach browser lifecycle behavior to the native client', () => {
+ const unsubscribe = vi.fn();
+ const client = {
+ subscription: vi.fn(() => ({ subscribe: () => ({ unsubscribe }) })),
+ };
+ const lifecycle = createGraphqlSoupSubscriptionsLifecycle({
+ suspendOnPagehide: false,
+ });
+ lifecycle.replace(client as never);
+ dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
+ dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+ expect(client.subscription).toHaveBeenCalledTimes(2);
+ expect(unsubscribe).not.toHaveBeenCalled();
+ lifecycle.dispose();
+ });
+
it('signals a terminal subscription failure once across both subscriptions', () => {
toastFailure.mockClear();
const receive: Array<(result: { error?: unknown }) => void> = [];
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.ts
index deb3fc88dd..bf67d2232f 100644
--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.ts
+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.ts
@@ -123,7 +123,9 @@ const LIVE_UPDATE_SUBSCRIPTIONS: readonly {
] as const;
/** Owns the realtime subscriptions served by the Soup GraphQL websocket. */
-export function createGraphqlSoupSubscriptionsLifecycle(): {
+export function createGraphqlSoupSubscriptionsLifecycle(
+ options: { suspendOnPagehide?: boolean } = {}
+): {
replace(
client?: Pick<Client, 'subscription' | 'query'>,
host?: CacheHost
@@ -131,6 +133,9 @@ export function createGraphqlSoupSubscriptionsLifecycle(): {
connected(): void;
dispose(): void;
} {
+ let currentClient: Pick<Client, 'subscription' | 'query'> | undefined;
+ let currentHost: CacheHost | undefined;
+ let suspended = false;
let unsubscribes: Array<() => void> = [];
let activity: ReturnType<typeof createActivityUpdatesHandler> | undefined;
let channels: ReturnType<typeof createChannelListUpdatesHandler> | undefined;
@@ -144,10 +149,28 @@ export function createGraphqlSoupSubscriptionsLifecycle(): {
channels = undefined;
};
- return {
- replace(client, host) {
+ const onPagehide = () => {
+ suspended = true;
+ // The graphql-ws client is lazy: removing all subscriptions closes the
+ // socket without permanently disposing it, so it can reconnect on restore.
+ unsubscribeAll();
+ };
+ const onPageshow = (event: PageTransitionEvent) => {
+ if (!event.persisted || !suspended) return;
+ suspended = false;
+ lifecycle.replace(currentClient, currentHost);
+ };
+ if (options.suspendOnPagehide) {
+ addEventListener('pagehide', onPagehide);
+ addEventListener('pageshow', onPageshow);
+ }
+
+ const lifecycle = {
+ replace(client?: Pick<Client, 'subscription' | 'query'>, host?: CacheHost) {
+ currentClient = client;
+ currentHost = host;
unsubscribeAll();
- if (!client) return;
+ if (!client || suspended) return;
activity = createActivityUpdatesHandler(client);
channels = createChannelListUpdatesHandler(client);
const activityHandler = activity;
@@ -195,6 +218,15 @@ export function createGraphqlSoupSubscriptionsLifecycle(): {
activity?.reconnect();
channels?.reconnect();
},
- dispose: unsubscribeAll,
+ dispose() {
+ if (options.suspendOnPagehide) {
+ removeEventListener('pagehide', onPagehide);
+ removeEventListener('pageshow', onPageshow);
+ }
+ currentClient = undefined;
+ currentHost = undefined;
+ unsubscribeAll();
+ },
};
+ return lifecycle;
}
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 58b249f2c6..447a044b9a 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
@@ -645,7 +645,7 @@ describe('GraphQL Soup browser cache session gate', () => {
expect(mocks.host.dispose).not.toHaveBeenCalled();
});
- it.each(['query', 'mutation'] as const)(
+ it.each(['query', 'mutation', 'subscription'] as const)(
'reports handled cache-disposed failures for %s without exporting operation payloads',
async (kind) => {
const soup = await import('./graphql-soup');
@@ -661,10 +661,10 @@ describe('GraphQL Soup browser cache session gate', () => {
const report =
mocks.normalizedCacheExchange.mock.calls[0]?.[1]?.onCacheError;
- report?.(
- new Error('cache worker host was disposed for page navigation'),
- operation
+ const { CacheNavigationError } = await import(
+ '@graphql-cache/host/navigation-error'
);
+ report?.(new CacheNavigationError(), operation);
expect(mocks.telemetryError).not.toHaveBeenCalled();
report?.(error, operation);
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 dfac98500c..57b69b8b55 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
@@ -12,6 +12,7 @@ import {
HYDRATE_ONLY_CONTEXT_KEY,
normalizedCacheExchange,
} from '@graphql-cache/exchange/normalized-cache-exchange';
+import { CacheNavigationError } from '@graphql-cache/host/navigation-error';
import type { CacheHost } from '@graphql-cache/host/types';
import {
createTauriCacheHost,
@@ -321,7 +322,9 @@ function disposeUncachedRealtimeClient(): void {
function getUncachedRealtimeClient(): Client {
if (uncachedRealtimeClient) return uncachedRealtimeClient;
- const subscriptionsLifecycle = createGraphqlSoupSubscriptionsLifecycle();
+ const subscriptionsLifecycle = createGraphqlSoupSubscriptionsLifecycle({
+ suspendOnPagehide: !isTauri(),
+ });
const websocketClient = createGraphqlSoupWebSocketClient(
subscriptionsLifecycle.connected
);
@@ -414,11 +417,7 @@ export function getGraphqlSoupClient(): Client {
try {
// Navigation deliberately rejects outstanding reads. Do not turn that
// expected shutdown into an error; unexpected disposal still reports.
- if (
- error instanceof Error &&
- error.message === 'cache worker host was disposed for page navigation'
- )
- return;
+ if (error instanceof CacheNavigationError) return;
// Caught cache failures never reach window.unhandledrejection. Report
// them through the Datadog-bound exporter without query/variable data.
Telemetry.error(error, {
@@ -434,7 +433,9 @@ export function getGraphqlSoupClient(): Client {
let host: CacheHost | undefined;
let websocketClient: GraphqlWsClient | undefined;
let unregisterHost: () => void = () => undefined;
- const subscriptionsLifecycle = createGraphqlSoupSubscriptionsLifecycle();
+ const subscriptionsLifecycle = createGraphqlSoupSubscriptionsLifecycle({
+ suspendOnPagehide: !native,
+ });
const cleanup = () => {
unregisterHost();
// Unsubscribing emits urql teardown operations; keep the cache host
diff --git a/docs/AGENT_GUIDE/navigation.md b/docs/AGENT_GUIDE/navigation.md
index feef34c4ba..2eb85c8f8d 100644
--- a/docs/AGENT_GUIDE/navigation.md
+++ b/docs/AGENT_GUIDE/navigation.md
@@ -1,5 +1,16 @@
# Navigation and App Structure
+## Returning from another page
+
+A browser back/forward-cache restore reconnects the GraphQL cache worker and
+live subscriptions in place; it must not reload the app or discard in-memory
+editor state. For lifecycle verification, navigate to another document and Back,
+confirm `pageshow.persisted` is true (otherwise this was a fresh load), then check
+that cached reads, live updates, and the existing editor still work. Runnable
+queued mutations should resume promptly, without waiting for the old poll or
+local retry timer; durable leases and server-retry deadlines still apply.
+Switching tabs or navigating an in-app route is not a back/forward-cache restore.
+
## Direct URLs (all under the frontend origin)
| Route | Surface |