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/feat/cache revision (#5923)

Sean Ayeefb54a47af4e
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 4dea3b61c6..725106c262 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
@@ -22,6 +22,7 @@ import {
ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,
type ClaimedMutation,
type EnqueueOptimisticMutationResult,
+ INITIAL_CACHE_REVISION,
type MutationClaim,
type ReadResult,
type WriteResult,
@@ -31,6 +32,7 @@ import {
HYDRATE_ONLY_CONTEXT_KEY,
type NormalizedCacheExchangeOptions,
normalizedCacheExchange,
+ normalizedCacheResultMetadata,
} from './normalized-cache-exchange';
import { optimisticMutationDispositionOf } from './optimistic';
@@ -251,6 +253,9 @@ function makeFakeHost(): FakeHost {
pushAffected: (opKeys) => {
for (const cb of subscribers) cb(opKeys);
},
+ async currentRevision() {
+ return INITIAL_CACHE_REVISION;
+ },
async readQuery(args) {
host.reads.push({
opKey: args.opKey,
@@ -262,7 +267,7 @@ function makeFakeHost(): FakeHost {
return readResult;
},
async readRecordsByKeys() {
- return [];
+ return { revision: INITIAL_CACHE_REVISION, records: [] };
},
async search() {
return { documents: [], nextCursor: null };
@@ -279,12 +284,21 @@ function makeFakeHost(): FakeHost {
entityResolvers: args.entityResolvers,
});
host.cacheActions.push({ kind: 'write', value: args.data });
- return { changed: [], affectedOps: [], reset: false };
+ return {
+ revision: INITIAL_CACHE_REVISION,
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ };
},
async hydrateQuery(args) {
host.writes.push({ data: args.data, identity: args.identity });
host.cacheActions.push({ kind: 'write', value: args.data });
- return { kind: 'data', data: args.data };
+ return {
+ kind: 'data',
+ data: args.data,
+ revision: INITIAL_CACHE_REVISION,
+ };
},
async enqueueOptimisticMutation(
args,
@@ -300,6 +314,7 @@ function makeFakeHost(): FakeHost {
const mutation = claimQueueHead(claim.nowMs);
return {
transactionId,
+ revision: INITIAL_CACHE_REVISION,
changed: [],
affectedOps: [],
reset: false,
@@ -340,25 +355,37 @@ function makeFakeHost(): FakeHost {
): Promise<WriteResult> {
host.commits.push({ transactionId, query: args.query, data: args.data });
if (queue[0]?.transactionId === transactionId) queue.shift();
- return { changed: [], affectedOps: [], reset: false };
+ return {
+ revision: INITIAL_CACHE_REVISION,
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ };
},
async rollbackOptimisticWrite(transactionId, _claim): Promise<WriteResult> {
host.rollbacks.push(transactionId);
if (queue[0]?.transactionId === transactionId) queue.shift();
- return { changed: [], affectedOps: [], reset: false };
+ return {
+ revision: INITIAL_CACHE_REVISION,
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ };
},
async invalidate() {
- return [];
+ return { revision: INITIAL_CACHE_REVISION, affectedOps: [] };
},
async deleteRecords(keys) {
host.invalidations.push(keys);
host.cacheActions.push({ kind: 'delete', value: keys });
- return [];
+ return { revision: INITIAL_CACHE_REVISION, affectedOps: [] };
},
async teardown(opKey) {
host.teardowns.push(opKey);
},
- async clear() {},
+ async clear() {
+ return INITIAL_CACHE_REVISION;
+ },
onOpsAffected(cb) {
subscribers.add(cb);
return () => subscribers.delete(cb);
@@ -366,6 +393,9 @@ function makeFakeHost(): FakeHost {
onCacheChanged() {
return () => undefined;
},
+ onCacheGenerationChanged() {
+ return () => undefined;
+ },
onMutationSettled() {
return () => undefined;
},
@@ -677,11 +707,16 @@ describe('normalizedCacheExchange', () => {
markWriteStarted();
await writeCanFinish;
cacheContainsDocument = true;
- return { changed: [], affectedOps: [], reset: false };
+ return {
+ revision: INITIAL_CACHE_REVISION,
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ };
});
vi.spyOn(host, 'deleteRecords').mockImplementation(async () => {
cacheContainsDocument = false;
- return [];
+ return { revision: INITIAL_CACHE_REVISION, affectedOps: [] };
});
const ops = makeSubject<Operation>();
@@ -879,6 +914,10 @@ describe('normalizedCacheExchange', () => {
[{ from: 'cache' }, true],
[{ from: 'network' }, false],
]);
+ expect(results.map(normalizedCacheResultMetadata)).toEqual([
+ { source: 'normalized-cache-hit' },
+ { source: 'live-network', revision: INITIAL_CACHE_REVISION },
+ ]);
expect(forwarded.map((op) => op.key)).toEqual([1]);
expect(host.writes).toHaveLength(1);
expect(host.reads).toHaveLength(1);
@@ -910,6 +949,7 @@ describe('normalizedCacheExchange', () => {
return {
kind: 'data' as const,
data: { soup: { nextCursor: 'cursor-2' } },
+ revision: INITIAL_CACHE_REVISION,
};
});
const { ops, network, forwarded, results } = controlledQueryHarness(host);
@@ -935,6 +975,10 @@ describe('normalizedCacheExchange', () => {
expect(results[0]?.data).toEqual({
soup: { nextCursor: 'cursor-2' },
});
+ expect(normalizedCacheResultMetadata(results[0]!)).toEqual({
+ source: 'live-network',
+ revision: INITIAL_CACHE_REVISION,
+ });
});
it('cache-only miss emits empty data and never touches the network', async () => {
@@ -1106,6 +1150,9 @@ describe('normalizedCacheExchange', () => {
[{ status: 'In Review' }, true],
[{ status: 'Completed' }, true],
]);
+ expect(normalizedCacheResultMetadata(results.at(-1)!)).toEqual({
+ source: 'affected-cache-reread',
+ });
});
it('registers a slow fallback write without a replacement reread', async () => {
@@ -1170,7 +1217,12 @@ describe('normalizedCacheExchange', () => {
.mockRejectedValueOnce(new Error('replacement init not ready'))
.mockImplementationOnce(async (args) => {
cached = args.data;
- return { changed: [], affectedOps: [], reset: false };
+ return {
+ revision: INITIAL_CACHE_REVISION,
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ };
});
const { ops, network, forwarded, results, client } = controlledQueryHarness(
host,
@@ -1235,7 +1287,12 @@ describe('normalizedCacheExchange', () => {
.fn()
.mockImplementationOnce(async () => await initialWrite)
.mockRejectedValueOnce(new Error('replacement failed while writing'))
- .mockResolvedValueOnce({ changed: [], affectedOps: [], reset: false });
+ .mockResolvedValueOnce({
+ revision: INITIAL_CACHE_REVISION,
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ });
const { ops, network, forwarded, client } = controlledQueryHarness(host);
ops.next(makeOp(43));
await tick();
@@ -1290,7 +1347,12 @@ describe('normalizedCacheExchange', () => {
if (writeCount === 1) throw new Error('initial A write failed');
if (writeCount === 2) throw new Error('replacement A write failed');
cached = args.data;
- return { changed: [], affectedOps: [], reset: false };
+ return {
+ revision: INITIAL_CACHE_REVISION,
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ };
});
const { ops, network, forwarded, client } = controlledQueryHarness(
host,
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 88d085d228..a488070413 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
@@ -62,9 +62,11 @@ import {
} from 'wonka';
import type { CacheHost } from '../host/types';
import {
+ type CacheRevision,
type ClaimedMutation,
type EnqueueOptimisticMutationResult,
isAdmittedEnqueueUncertainError,
+ isCacheRevision,
isOwnerEpochLostError,
type QueryRevalidationWire,
} from '../protocol';
@@ -98,6 +100,42 @@ const QUEUE_REQUEST_TIMEOUT_MS = 60_000;
const QUEUE_LEASE_MS = 5 * 60_000;
const EMPTY_QUEUE_POLL_MS = 30_000;
+const NORMALIZED_CACHE_RESULT_METADATA_KEY = '__macroNormalizedCache';
+
+/** Private authority metadata attached by the normalized-cache exchange. */
+export type NormalizedCacheResultMetadata =
+ | { source: 'live-network'; revision?: CacheRevision }
+ | { source: 'normalized-cache-hit' }
+ | { source: 'affected-cache-reread' };
+
+/** Reads normalized-cache authority metadata from an urql operation result. */
+export function normalizedCacheResultMetadata(
+ result: Pick<OperationResult, 'extensions'>
+): NormalizedCacheResultMetadata | undefined {
+ const metadata = result.extensions?.[NORMALIZED_CACHE_RESULT_METADATA_KEY];
+ if (metadata === null || typeof metadata !== 'object') return;
+ const source = (metadata as { source?: unknown }).source;
+ if (source === 'normalized-cache-hit' || source === 'affected-cache-reread') {
+ return { source };
+ }
+ if (source !== 'live-network') return;
+ const revision = (metadata as { revision?: unknown }).revision;
+ return isCacheRevision(revision) ? { source, revision } : { source };
+}
+
+function withResultMetadata(
+ result: OperationResult,
+ metadata: NormalizedCacheResultMetadata
+): OperationResult {
+ return {
+ ...result,
+ extensions: {
+ ...result.extensions,
+ [NORMALIZED_CACHE_RESULT_METADATA_KEY]: metadata,
+ },
+ };
+}
+
type QueueAttemptContext = {
transactionId: string;
leaseOwner: string;
@@ -227,16 +265,23 @@ function withQueueRequestTimeout(op: Operation): Operation {
function cacheResult(
op: Operation,
data: unknown,
- stale: boolean
+ stale: boolean,
+ source: Extract<
+ NormalizedCacheResultMetadata,
+ { source: 'normalized-cache-hit' | 'affected-cache-reread' }
+ >['source'] = 'normalized-cache-hit'
): OperationResult {
- return {
- operation: op,
- data,
- error: undefined,
- extensions: undefined,
- stale,
- hasNext: false,
- };
+ return withResultMetadata(
+ {
+ operation: op,
+ data,
+ error: undefined,
+ extensions: undefined,
+ stale,
+ hasNext: false,
+ },
+ { source }
+ );
}
type CacheEffect =
@@ -575,7 +620,9 @@ export function normalizedCacheExchange(
// Preserve the authoritative request while immediately surfacing the
// newer local view. Its eventual result still gets the deferred
// cache reread below when it could not register fresh dependencies.
- emitAffectedResult(cacheResult(active, read.data, true));
+ emitAffectedResult(
+ cacheResult(active, read.data, true, 'affected-cache-reread')
+ );
})
.catch((error) => options.onCacheError?.(error, operation));
};
@@ -993,6 +1040,10 @@ export function normalizedCacheExchange(
result: OperationResult
): Promise<OperationResult> {
const op = result.operation;
+ let output =
+ op.kind === 'query'
+ ? withResultMetadata(result, { source: 'live-network' })
+ : result;
if (op.kind === 'subscription' && result.data != null) {
// Serialize effects across every emission for this operation, as
// well as within buffered payloads, so a slower earlier write cannot
@@ -1022,10 +1073,13 @@ export function normalizedCacheExchange(
identity: options.extractIdentity?.(result.data),
entityResolvers,
});
- return {
- ...result,
- data: hydration.kind === 'data' ? hydration.data : undefined,
- };
+ return withResultMetadata(
+ {
+ ...result,
+ data: hydration.kind === 'data' ? hydration.data : undefined,
+ },
+ { source: 'live-network', revision: hydration.revision }
+ );
} catch (error) {
options.onCacheError?.(error, op);
return {
@@ -1079,7 +1133,11 @@ export function normalizedCacheExchange(
state.retainedReplacementFallback = retained;
}
try {
- await host.writeQuery(writeArgs);
+ const write = await host.writeQuery(writeArgs);
+ output = withResultMetadata(result, {
+ source: 'live-network',
+ revision: write.revision,
+ });
state.networkRegistrationSatisfied =
writeArgs.registerDependencies;
if (state.retainedReplacementFallback === retained) {
@@ -1195,7 +1253,7 @@ export function normalizedCacheExchange(
});
}
}
- return result;
+ return output;
}
const cacheResults$ = pipe(
diff --git a/apps/web/src/lib/graphql-cache/exchange/record-selection.test.ts b/apps/web/src/lib/graphql-cache/exchange/record-selection.test.ts
index 0b2cd3a969..75bb22c1d8 100644
--- a/apps/web/src/lib/graphql-cache/exchange/record-selection.test.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/record-selection.test.ts
@@ -5,16 +5,20 @@ import {
} from '@service-storage/graphql/generated/graphql';
import { describe, expect, expectTypeOf, it, vi } from 'vitest';
import type { CacheHost } from '../host/types';
+import { INITIAL_CACHE_REVISION } from '../protocol';
import { readRecordsByKeys, selectRecords } from './record-selection';
describe('typed record selection', () => {
it('projects explicit keys and infers generated result types', async () => {
- const readRecordsByKeysHost = vi.fn().mockResolvedValue([
- {
- recordKey: 'GraphqlSoupDocument:item-1',
- record: { id: 'item-1' },
- },
- ]);
+ const readRecordsByKeysHost = vi.fn().mockResolvedValue({
+ revision: INITIAL_CACHE_REVISION,
+ records: [
+ {
+ recordKey: 'GraphqlSoupDocument:item-1',
+ record: { id: 'item-1' },
+ },
+ ],
+ });
const host = {
readRecordsByKeys: readRecordsByKeysHost,
} as unknown as CacheHost;
@@ -28,11 +32,11 @@ describe('typed record selection', () => {
fragmentName: 'SoupItemFields',
keys: ['GraphqlSoupDocument:item-1'],
});
- expectTypeOf(records).toEqualTypeOf<
+ expectTypeOf(records.records).toEqualTypeOf<
Array<{ recordKey: string; record: SoupItemFieldsFragment }>
>();
// @ts-expect-error Generated fragment records have no arbitrary field.
- records[0]?.record.missing;
+ records.records[0]?.record.missing;
});
it('rejects operation documents and malformed host records', async () => {
@@ -46,7 +50,10 @@ describe('typed record selection', () => {
[{ recordKey: 'GraphqlSoupDocument:1', record: null }],
]) {
const host = {
- readRecordsByKeys: async () => result,
+ readRecordsByKeys: async () => ({
+ revision: INITIAL_CACHE_REVISION,
+ records: result,
+ }),
} as unknown as CacheHost;
await expect(
readRecordsByKeys(host, selection, ['GraphqlSoupDocument:1'])
diff --git a/apps/web/src/lib/graphql-cache/exchange/record-selection.ts b/apps/web/src/lib/graphql-cache/exchange/record-selection.ts
index 57c9b5f6fd..4749f1085b 100644
--- a/apps/web/src/lib/graphql-cache/exchange/record-selection.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/record-selection.ts
@@ -2,7 +2,7 @@ import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
import { stringifyDocument } from '@urql/core';
import { type FragmentDefinitionNode, Kind } from 'graphql';
import type { CacheHost } from '../host/types';
-import type { SelectedRecordByKeyWire } from '../protocol';
+import type { CacheRevision } from '../protocol';
const recordResultType: unique symbol = Symbol('recordResultType');
@@ -50,16 +50,22 @@ export async function readRecordsByKeys<TResult>(
host: Pick<CacheHost, 'readRecordsByKeys'>,
selection: RecordSelection<TResult>,
keys: string[]
-): Promise<Array<{ recordKey: string; record: TResult }>> {
- const records: SelectedRecordByKeyWire[] = await host.readRecordsByKeys({
+): Promise<{
+ revision: CacheRevision;
+ records: Array<{ recordKey: string; record: TResult }>;
+}> {
+ const result = await host.readRecordsByKeys({
document: selection.document,
fragmentName: selection.fragmentName,
keys,
});
- return records.map(({ recordKey, record }) => {
- if (!recordKey || !isRecord(record)) {
- throw new Error('invalid cache selected record by key');
- }
- return { recordKey, record: record as TResult };
- });
+ return {
+ revision: result.revision,
+ records: result.records.map(({ recordKey, record }) => {
+ if (!recordKey || !isRecord(record)) {
+ throw new Error('invalid cache selected record by key');
+ }
+ return { recordKey, record: record as TResult };
+ }),
+ };
}
diff --git a/apps/web/src/lib/graphql-cache/host/noop-host.ts b/apps/web/src/lib/graphql-cache/host/noop-host.ts
index c1599ebe4a..cbaa58d312 100644
--- a/apps/web/src/lib/graphql-cache/host/noop-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/noop-host.ts
@@ -3,9 +3,11 @@ import type {
ReadResult,
WriteResult,
} from '../protocol';
+import { INITIAL_CACHE_REVISION } from '../protocol';
import type { CacheHost } from './types';
const emptyWriteResult = (): WriteResult => ({
+ revision: INITIAL_CACHE_REVISION,
changed: [],
affectedOps: [],
reset: false,
@@ -22,11 +24,14 @@ export function createNoopCacheHost(reason: string): CacheHost {
return {
clientId: 'noop',
disabled: true,
+ async currentRevision() {
+ return INITIAL_CACHE_REVISION;
+ },
async readQuery(): Promise<ReadResult> {
return { kind: 'miss' };
},
async readRecordsByKeys() {
- return [];
+ return { revision: INITIAL_CACHE_REVISION, records: [] };
},
async search() {
return { documents: [], nextCursor: null };
@@ -59,20 +64,25 @@ export function createNoopCacheHost(reason: string): CacheHost {
async rollbackOptimisticWrite(): Promise<WriteResult> {
return emptyWriteResult();
},
- async invalidate(): Promise<string[]> {
- return [];
+ async invalidate() {
+ return { revision: INITIAL_CACHE_REVISION, affectedOps: [] };
},
- async deleteRecords(): Promise<string[]> {
- return [];
+ async deleteRecords() {
+ return { revision: INITIAL_CACHE_REVISION, affectedOps: [] };
},
async teardown(): Promise<void> {},
- async clear(): Promise<void> {},
+ async clear() {
+ return INITIAL_CACHE_REVISION;
+ },
onOpsAffected() {
return () => undefined;
},
onCacheChanged() {
return () => undefined;
},
+ onCacheGenerationChanged() {
+ return () => undefined;
+ },
onMutationSettled() {
return () => undefined;
},
diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts
index 392dd346e1..91047c5821 100644
--- a/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts
+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts
@@ -6,6 +6,7 @@ const listenMock = vi.hoisted(() => vi.fn());
vi.mock('@tauri-apps/api/core', () => ({ invoke: invokeMock }));
vi.mock('@tauri-apps/api/event', () => ({ listen: listenMock }));
+import { INITIAL_CACHE_REVISION } from '../protocol';
import { createTauriCacheHost } from './tauri-host';
type EventCallback = (event: { payload: Record<string, unknown> }) => void;
@@ -91,7 +92,9 @@ describe('createTauriCacheHost', () => {
];
invokeMock.mockImplementation((command: string) =>
Promise.resolve(
- command === 'graphql_cache_read_records_by_keys' ? records : null
+ command === 'graphql_cache_read_records_by_keys'
+ ? { revision: INITIAL_CACHE_REVISION, records }
+ : null
)
);
const host = createTauriCacheHost({ scope: 'scope-1' });
@@ -102,7 +105,7 @@ describe('createTauriCacheHost', () => {
fragmentName: 'Item',
keys: ['GraphqlSoupDocument:item-1'],
})
- ).resolves.toEqual(records);
+ ).resolves.toEqual({ revision: INITIAL_CACHE_REVISION, records });
expect(invokeMock).toHaveBeenCalledWith(
'graphql_cache_read_records_by_keys',
{
@@ -366,7 +369,9 @@ describe('createTauriCacheHost', () => {
host.onCacheChanged(() => calls++);
await Promise.resolve();
- eventCallbacks.get('graphql-cache://cache-changed')?.({ payload: {} });
+ eventCallbacks.get('graphql-cache://cache-changed')?.({
+ payload: { revision: INITIAL_CACHE_REVISION },
+ });
expect(calls).toBe(1);
});
diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.ts
index ced191945c..877b5e5e28 100644
--- a/apps/web/src/lib/graphql-cache/host/tauri-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.ts
@@ -9,22 +9,27 @@
import { invoke } from '@tauri-apps/api/core';
import { listen, type UnlistenFn } from '@tauri-apps/api/event';
+import type {
+ AffectedOperationsResult,
+ CachedQueryInstanceWire,
+ CachedQueryVariantWire,
+ CacheRevision,
+ ClaimedMutation,
+ EnqueueOptimisticMutationResult,
+ HydrationResult,
+ MutationClaim,
+ MutationSettlement,
+ ReadRecordsByKeysArgs,
+ ReadRecordsByKeysResult,
+ ReadResult,
+ SearchCacheArgs,
+ SearchCachePage,
+ WriteResult,
+} from '../protocol';
import {
- type CachedQueryInstanceWire,
- type CachedQueryVariantWire,
- type ClaimedMutation,
- type EnqueueOptimisticMutationResult,
- type HydrationResult,
- type MutationClaim,
- type MutationSettlement,
- type ReadRecordsByKeysArgs,
- type ReadResult,
- type SearchCacheArgs,
- type SearchCachePage,
- type SelectedRecordByKeyWire,
+ parseCacheRevision,
validateCacheSearchArgs,
validateRecordSelectionKeys,
- type WriteResult,
} from '../protocol';
import type {
CacheHost,
@@ -49,7 +54,7 @@ type OpsAffectedPayload = {
keys: string[];
};
-type CacheChangedPayload = Record<string, never>;
+type CacheChangedPayload = { revision: string };
export interface TauriHostOptions {
scope: string;
@@ -69,7 +74,7 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
const clientId = crypto.randomUUID();
const affectedSubscribers = new Set<(opKeys: number[]) => void>();
- const cacheChangeSubscribers = new Set<() => void>();
+ const cacheChangeSubscribers = new Set<(revision: CacheRevision) => void>();
const settlementSubscribers = new Set<
(settlement: MutationSettlement) => void
>();
@@ -127,8 +132,9 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
});
const unlistenCacheChanges: Promise<UnlistenFn | undefined> =
- listen<CacheChangedPayload>(CACHE_CHANGED_EVENT, () => {
- for (const cb of cacheChangeSubscribers) cb();
+ listen<CacheChangedPayload>(CACHE_CHANGED_EVENT, (event) => {
+ const revision = parseCacheRevision(event.payload.revision);
+ for (const cb of cacheChangeSubscribers) cb(revision);
}).catch((error) => {
console.warn('graphql cache change listener failed', error);
return undefined;
@@ -153,6 +159,13 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
return {
clientId,
+ async currentRevision(): Promise<CacheRevision> {
+ await ready;
+ return parseCacheRevision(
+ await request<string>('graphql_cache_current_revision', {})
+ );
+ },
+
async readQuery(args: CacheReadArgs): Promise<ReadResult> {
await ready;
return await request<ReadResult>('graphql_cache_read', {
@@ -166,10 +179,10 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
async readRecordsByKeys(
args: ReadRecordsByKeysArgs
- ): Promise<SelectedRecordByKeyWire[]> {
+ ): Promise<ReadRecordsByKeysResult> {
const keys = validateRecordSelectionKeys(args.keys);
await ready;
- return await request<SelectedRecordByKeyWire[]>(
+ const result = await request<ReadRecordsByKeysResult>(
'graphql_cache_read_records_by_keys',
{
document: args.document,
@@ -177,6 +190,7 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
keys,
}
);
+ return { ...result, revision: parseCacheRevision(result.revision) };
},
async search(args: SearchCacheArgs): Promise<SearchCachePage> {
@@ -342,14 +356,22 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
);
},
- async invalidate(keys: string[]): Promise<string[]> {
+ async invalidate(keys: string[]): Promise<AffectedOperationsResult> {
await ready;
- return await request<string[]>('graphql_cache_invalidate', { keys });
+ const result = await request<AffectedOperationsResult>(
+ 'graphql_cache_invalidate',
+ { keys }
+ );
+ return { ...result, revision: parseCacheRevision(result.revision) };
},
- async deleteRecords(keys: string[]): Promise<string[]> {
+ async deleteRecords(keys: string[]): Promise<AffectedOperationsResult> {
await ready;
- return await request<string[]>('graphql_cache_delete_records', { keys });
+ const result = await request<AffectedOperationsResult>(
+ 'graphql_cache_delete_records',
+ { keys }
+ );
+ return { ...result, revision: parseCacheRevision(result.revision) };
},
async teardown(opKey: number): Promise<void> {
@@ -357,9 +379,11 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
await request('graphql_cache_teardown', { opId: opId(opKey) });
},
- async clear(): Promise<void> {
+ async clear(): Promise<CacheRevision> {
await ready;
- await request('graphql_cache_clear', {});
+ return parseCacheRevision(
+ await request<string>('graphql_cache_clear', {})
+ );
},
onOpsAffected(cb: (opKeys: number[]) => void): () => void {
@@ -367,11 +391,16 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
return () => affectedSubscribers.delete(cb);
},
- onCacheChanged(cb: () => void): () => void {
+ onCacheChanged(cb: (revision: CacheRevision) => void): () => void {
cacheChangeSubscribers.add(cb);
return () => cacheChangeSubscribers.delete(cb);
},
+ onCacheGenerationChanged(): () => void {
+ // The native host process owns one engine generation for its lifetime.
+ return () => undefined;
+ },
+
onMutationSettled(
cb: (settlement: MutationSettlement) => void
): () => void {
diff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.ts
index 34edb45e31..2ab919cd11 100644
--- a/apps/web/src/lib/graphql-cache/host/types.ts
+++ b/apps/web/src/lib/graphql-cache/host/types.ts
@@ -8,9 +8,11 @@
import type { EntityResolverWire } from '../exchange/entity-resolvers';
import type {
+ AffectedOperationsResult,
CachedQueryInstanceWire,
CachedQueryVariantWire,
CacheReadPriority,
+ CacheRevision,
ClaimedMutation,
EnqueueOptimisticMutationResult,
EntityFilterCacheArgs,
@@ -22,10 +24,10 @@ import type {
QueryRevalidationWire,
QueryVariableFilter,
ReadRecordsByKeysArgs,
+ ReadRecordsByKeysResult,
ReadResult,
SearchCacheArgs,
SearchCachePage,
- SelectedRecordByKeyWire,
WriteResult,
} from '../protocol';
@@ -83,11 +85,13 @@ export interface CacheHost {
/** True for the storage-free fallback when browser cache APIs are unsupported. */
readonly disabled?: boolean;
+ /** Returns the current revision of the active cache-engine generation. */
+ currentRevision(): Promise<CacheRevision>;
readQuery(args: CacheReadArgs): Promise<ReadResult>;
/** Projects a bounded explicit set of normalized entity keys. */
readRecordsByKeys(
args: ReadRecordsByKeysArgs
- ): Promise<SelectedRecordByKeyWire[]>;
+ ): Promise<ReadRecordsByKeysResult>;
/** Searches the compact write-through materialized projection. */
search(args: SearchCacheArgs): Promise<SearchCachePage>;
/** Evaluates an exact initial Soup filter page over complete local projections. */
@@ -132,13 +136,13 @@ export interface CacheHost {
error: string
): Promise<WriteResult>;
/** Evict records by entity key (external/push updates); returns affected local op ids. */
- invalidate(keys: string[]): Promise<string[]>;
+ invalidate(keys: string[]): Promise<AffectedOperationsResult>;
/** Apply explicit server-provided cache-deletion effects. */
- deleteRecords(keys: string[]): Promise<string[]>;
+ deleteRecords(keys: string[]): Promise<AffectedOperationsResult>;
/** urql teardown for an operation key. */
teardown(opKey: number): Promise<void>;
/** Wipe all cached state (logout). */
- clear(): Promise<void>;
+ clear(): Promise<CacheRevision>;
/**
* Subscribes to "these urql operation keys must re-execute" pushes
@@ -148,7 +152,10 @@ export interface CacheHost {
onOpsAffected(cb: (opKeys: number[]) => void): () => void;
/** Subscribes whenever the effective normalized-cache view changes. */
- onCacheChanged(cb: () => void): () => void;
+ onCacheChanged(cb: (revision: CacheRevision) => void): () => void;
+
+ /** Invalidates revision watermarks before a replacement engine is used. */
+ onCacheGenerationChanged(cb: () => void): () => void;
/** Subscribes to final commit/rollback events for queued mutations. */
onMutationSettled(cb: (settlement: MutationSettlement) => void): () => void;
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 1653af502e..2a90cb5c0a 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
@@ -5,6 +5,7 @@ import type {
WorkerMessage,
WriteResult,
} from '../protocol';
+import { INITIAL_CACHE_REVISION } from '../protocol';
import type {
CacheCoordinatorPageAdapter,
CacheCoordinatorPageAdapterOptions,
@@ -21,6 +22,7 @@ import { createWorkerCacheHost } from './worker-host';
const CLIENT_ID = '00000000-0000-4000-8000-000000000007';
const EMPTY_WRITE: WriteResult = {
+ revision: INITIAL_CACHE_REVISION,
changed: [],
affectedOps: [],
reset: false,
@@ -28,14 +30,20 @@ const EMPTY_WRITE: WriteResult = {
function responseFor(request: CacheRequest): unknown {
switch (request.kind) {
+ case 'current-revision':
+ return INITIAL_CACHE_REVISION;
case 'read':
return { kind: 'miss' };
case 'read-records-by-keys':
- return [];
+ return { revision: INITIAL_CACHE_REVISION, records: [] };
case 'search':
return { documents: [], nextCursor: null };
case 'hydrate':
- return { kind: 'data', data: { cursor: 'next' } };
+ return {
+ kind: 'data',
+ data: { cursor: 'next' },
+ revision: INITIAL_CACHE_REVISION,
+ };
case 'write':
case 'commit-optimistic-write':
case 'rollback-optimistic-write':
@@ -53,12 +61,13 @@ function responseFor(request: CacheRequest): unknown {
return undefined;
case 'invalidate':
case 'delete-records':
- return request.keys;
+ return { revision: INITIAL_CACHE_REVISION, affectedOps: request.keys };
case 'init':
case 'defer-optimistic-write':
case 'teardown':
- case 'clear':
return null;
+ case 'clear':
+ return INITIAL_CACHE_REVISION;
}
}
@@ -208,7 +217,11 @@ describe('createWorkerCacheHost', () => {
data: { items: [{ id: '1' }], cursor: 'next' },
identity: 'user-1',
})
- ).resolves.toEqual({ kind: 'data', data: { cursor: 'next' } });
+ ).resolves.toEqual({
+ kind: 'data',
+ data: { cursor: 'next' },
+ revision: INITIAL_CACHE_REVISION,
+ });
expect(requireAdapter().requests).toContainEqual(
expect.objectContaining({
@@ -530,6 +543,29 @@ describe('createWorkerCacheHost', () => {
expect(vi.getTimerCount()).toBe(0);
});
+ it('times out a hung current-revision request', async () => {
+ vi.useFakeTimers();
+ configureAdapter = (fake) => fake.ignoredKinds.add('current-revision');
+ const host = createWorkerCacheHost({
+ scope: 'scope-1',
+ requestTimeoutMs: 10,
+ });
+
+ const revision = host.currentRevision();
+ const revisionRejected = expect(revision).rejects.toThrow(
+ 'cache worker timeout: current-revision'
+ );
+
+ await vi.advanceTimersByTimeAsync(11);
+ await revisionRejected;
+ expect(requireAdapter().requests.map(({ kind }) => kind)).toEqual([
+ 'init',
+ 'current-revision',
+ ]);
+ host.dispose();
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
it('recovers typed initial epoch loss with fresh init handshakes only', async () => {
configureAdapter = (fake) => fake.ignoredKinds.add('init');
const onInitializationError = vi.fn();
@@ -852,7 +888,10 @@ describe('createWorkerCacheHost', () => {
keys: ['User:1'],
});
adapter.push({ kind: 'ops-affected', opIds: [7], keys: [] });
- adapter.push({ kind: 'cache-changed' });
+ adapter.push({
+ kind: 'cache-changed',
+ revision: INITIAL_CACHE_REVISION,
+ });
adapter.push({
kind: 'mutation-settled',
settlement: { transactionId: '3', status: 'committed' },
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 1e8c32ebe4..9f10c32cb2 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts
@@ -7,10 +7,12 @@
import { deleteLegacyNormalizedCacheIdb } from '../legacy-idb-cleanup';
import {
ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,
+ type AffectedOperationsResult,
type CachedQueryInstanceWire,
type CachedQueryVariantWire,
type CacheRequest,
type CacheResponseErrorCode,
+ type CacheRevision,
type ClaimedMutation,
type EnqueueOptimisticMutationResult,
type EntityFilterCacheArgs,
@@ -22,10 +24,10 @@ import {
type MutationSettlement,
OWNER_EPOCH_LOST_ERROR_CODE,
type ReadRecordsByKeysArgs,
+ type ReadRecordsByKeysResult,
type ReadResult,
type SearchCacheArgs,
type SearchCachePage,
- type SelectedRecordByKeyWire,
validateCacheSearchArgs,
validateRecordSelectionKeys,
type WorkerMessage,
@@ -189,7 +191,8 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
const lostRegisteredOpKeys = new Set<number>();
const replacementReadOpKeys = new Set<number>();
const affectedSubscribers = new Set<(opKeys: number[]) => void>();
- const cacheChangeSubscribers = new Set<() => void>();
+ const cacheChangeSubscribers = new Set<(revision: CacheRevision) => void>();
+ const generationChangeSubscribers = new Set<() => void>();
const settlementSubscribers = new Set<
(settlement: MutationSettlement) => void
>();
@@ -247,7 +250,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
const msg = event.data;
if (isCachePush(msg)) {
if (msg.kind === 'cache-changed') {
- for (const cb of cacheChangeSubscribers) cb();
+ for (const cb of cacheChangeSubscribers) cb(msg.revision);
return;
}
if (msg.kind === 'mutation-settled') {
@@ -331,6 +334,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
latestReplacementEpoch = ownerEpoch;
// Initial readiness completes the already-running first handshake.
if (state === 'initializing' && !recoveryInProgress) return;
+ for (const cb of generationChangeSubscribers) cb();
if (state === 'ready') {
beginRecoveryGeneration();
// No old response put this host into recovery. Requests still pending at
@@ -457,6 +461,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
function clearSubscribers(): void {
affectedSubscribers.clear();
cacheChangeSubscribers.clear();
+ generationChangeSubscribers.clear();
settlementSubscribers.clear();
}
@@ -651,7 +656,8 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
const timeoutMs =
msg.kind === 'init'
? initializationTimeoutMs
- : msg.kind === 'read' ||
+ : msg.kind === 'current-revision' ||
+ msg.kind === 'read' ||
msg.kind === 'read-records-by-keys' ||
msg.kind === 'search' ||
msg.kind === 'entity-filter' ||
@@ -804,6 +810,11 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
return {
clientId,
+ async currentRevision(): Promise<CacheRevision> {
+ await ensureInitialized();
+ return (await request({ kind: 'current-revision' })) as CacheRevision;
+ },
+
async readQuery(args: CacheReadArgs): Promise<ReadResult> {
if (args.opKey !== undefined) {
activeOpKeys.add(args.opKey);
@@ -826,7 +837,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
async readRecordsByKeys(
args: ReadRecordsByKeysArgs
- ): Promise<SelectedRecordByKeyWire[]> {
+ ): Promise<ReadRecordsByKeysResult> {
const keys = validateRecordSelectionKeys(args.keys);
await ensureInitialized();
return (await request({
@@ -834,7 +845,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
document: args.document,
fragmentName: args.fragmentName,
keys,
- })) as SelectedRecordByKeyWire[];
+ })) as ReadRecordsByKeysResult;
},
async search(args: SearchCacheArgs): Promise<SearchCachePage> {
@@ -1007,14 +1018,20 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
})) as WriteResult;
},
- async invalidate(keys: string[]): Promise<string[]> {
+ async invalidate(keys: string[]): Promise<AffectedOperationsResult> {
await ensureInitialized();
- return (await request({ kind: 'invalidate', keys })) as string[];
+ return (await request({
+ kind: 'invalidate',
+ keys,
+ })) as AffectedOperationsResult;
},
- async deleteRecords(keys: string[]): Promise<string[]> {
+ async deleteRecords(keys: string[]): Promise<AffectedOperationsResult> {
await ensureInitialized();
- return (await request({ kind: 'delete-records', keys })) as string[];
+ return (await request({
+ kind: 'delete-records',
+ keys,
+ })) as AffectedOperationsResult;
},
async teardown(opKey: number): Promise<void> {
@@ -1038,9 +1055,9 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
await request({ kind: 'teardown', opId: opId(opKey) });
},
- async clear(): Promise<void> {
+ async clear(): Promise<CacheRevision> {
await ensureInitialized();
- await request({ kind: 'clear' });
+ const revision = (await request({ kind: 'clear' })) as CacheRevision;
telemetry?.record({
name: 'graphql_cache.logical_reset',
operationCategory: 'lifecycle',
@@ -1048,6 +1065,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
errorCode: 'none',
resetReason: 'explicit-clear',
});
+ return revision;
},
onOpsAffected(cb: (opKeys: number[]) => void): () => void {
@@ -1055,11 +1073,16 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
return () => affectedSubscribers.delete(cb);
},
- onCacheChanged(cb: () => void): () => void {
+ onCacheChanged(cb: (revision: CacheRevision) => void): () => void {
cacheChangeSubscribers.add(cb);
return () => cacheChangeSubscribers.delete(cb);
},
+ onCacheGenerationChanged(cb: () => void): () => void {
+ generationChangeSubscribers.add(cb);
+ return () => generationChangeSubscribers.delete(cb);
+ },
+
onMutationSettled(
cb: (settlement: MutationSettlement) => void
): () => void {
diff --git a/apps/web/src/lib/graphql-cache/index.ts b/apps/web/src/lib/graphql-cache/index.ts
index 9b0a39ce2a..ad7ae6a30b 100644
--- a/apps/web/src/lib/graphql-cache/index.ts
+++ b/apps/web/src/lib/graphql-cache/index.ts
@@ -18,6 +18,10 @@ export {
inspectVariants,
selectAll,
} from './exchange/inspection';
+export {
+ type NormalizedCacheResultMetadata,
+ normalizedCacheResultMetadata,
+} from './exchange/normalized-cache-exchange';
export {
executeOptimisticMutation,
type LinkDiff,
@@ -56,6 +60,7 @@ export type {
CacheReadPriority,
CacheRequest,
CacheResponse,
+ CacheRevision,
EnqueueOptimisticMutationResult,
EntityFilterCacheArgs,
EntityFilterCacheResult,
@@ -64,6 +69,7 @@ export type {
OptimisticWriteResult,
QueryVariableFilter,
ReadRecordsByKeysArgs,
+ ReadRecordsByKeysResult,
ReadResult,
SearchCacheArgs,
SearchCachePage,
@@ -74,6 +80,7 @@ export type {
WriteResult,
} from './protocol';
export {
+ INITIAL_CACHE_REVISION,
MAX_CACHE_SEARCH_QUERY_BYTES,
MAX_RECORD_SELECTION_PAGE_SIZE,
validateCacheSearchArgs,
diff --git a/apps/web/src/lib/graphql-cache/lifecycle.test.ts b/apps/web/src/lib/graphql-cache/lifecycle.test.ts
index 0f2664e866..1ab7803968 100644
--- a/apps/web/src/lib/graphql-cache/lifecycle.test.ts
+++ b/apps/web/src/lib/graphql-cache/lifecycle.test.ts
@@ -1,8 +1,8 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import type { CacheHost } from './host/types';
-function hostWithClear(clear: () => Promise<void>): CacheHost {
- return { clear } as CacheHost;
+function hostWithClear(clear: () => Promise<unknown>): CacheHost {
+ return { clear } as unknown as CacheHost;
}
describe('clearRegisteredCaches', () => {
diff --git a/apps/web/src/lib/graphql-cache/protocol.test.ts b/apps/web/src/lib/graphql-cache/protocol.test.ts
index 6814e7095d..cbcf668c43 100644
--- a/apps/web/src/lib/graphql-cache/protocol.test.ts
+++ b/apps/web/src/lib/graphql-cache/protocol.test.ts
@@ -1,14 +1,30 @@
import { describe, expect, it } from 'vitest';
import type { SearchCacheArgs } from './protocol';
import {
+ INITIAL_CACHE_REVISION,
isCachePush,
isCacheResponse,
isWorkerMessage,
MAX_RECORD_SELECTION_PAGE_SIZE,
+ parseCacheRevision,
validateCacheSearchArgs,
validateRecordSelectionKeys,
} from './protocol';
+describe('cache revisions', () => {
+ it('accepts canonical Rust u64 decimal strings beyond JS safe integers', () => {
+ expect(parseCacheRevision('9007199254740993')).toBe('9007199254740993');
+ expect(parseCacheRevision('18446744073709551615')).toBe(
+ '18446744073709551615'
+ );
+ });
+
+ it.each(['', '-1', '+1', '01', '1.0', '18446744073709551616'])(
+ 'rejects malformed revision %s',
+ (revision) => expect(() => parseCacheRevision(revision)).toThrow()
+ );
+});
+
describe('validateRecordSelectionKeys', () => {
it('accepts bounded canonical entity keys, including an empty set', () => {
expect(validateRecordSelectionKeys([])).toEqual([]);
@@ -128,7 +144,7 @@ describe('cache worker message validators', () => {
errorCode: 'admitted-enqueue-uncertain',
},
{ kind: 'ops-affected', opIds: ['client:7'], keys: ['User:1'] },
- { kind: 'cache-changed' },
+ { kind: 'cache-changed', revision: INITIAL_CACHE_REVISION },
{
kind: 'mutation-settled',
settlement: { transactionId: '3', status: 'committed' },
diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.ts
index 90f985f889..3616898fe0 100644
--- a/apps/web/src/lib/graphql-cache/protocol.ts
+++ b/apps/web/src/lib/graphql-cache/protocol.ts
@@ -14,6 +14,32 @@ import type { EntityResolverWire } from './exchange/entity-resolvers';
export type ReadResult = { kind: 'hit'; data: unknown } | { kind: 'miss' };
+/** Opaque in-memory revision of one live cache engine generation. */
+export type CacheRevision = string & {
+ readonly __cacheRevision: unique symbol;
+};
+
+const MAX_CACHE_REVISION = 18_446_744_073_709_551_615n;
+
+/** Validates the canonical unsigned-decimal Rust `u64` wire representation. */
+export function isCacheRevision(value: unknown): value is CacheRevision {
+ return (
+ typeof value === 'string' &&
+ /^(0|[1-9][0-9]*)$/.test(value) &&
+ BigInt(value) <= MAX_CACHE_REVISION
+ );
+}
+
+/** Parses an untrusted cache revision at protocol ingress. */
+export function parseCacheRevision(value: unknown): CacheRevision {
+ if (!isCacheRevision(value)) {
+ throw new TypeError('invalid cache revision');
+ }
+ return value;
+}
+
+export const INITIAL_CACHE_REVISION = '0' as CacheRevision;
+
/** Scheduling hint for latency-sensitive cache reads. */
export type CacheReadPriority = 'user-visible';
@@ -60,9 +86,14 @@ export type EntityFilterCacheArgs = {
};
export type EntityFilterCacheResult =
- | { kind: 'complete'; keys: string[]; optimistic: boolean }
+ | {
+ kind: 'complete';
+ revision: CacheRevision;
+ keys: string[];
+ optimistic: boolean;
+ }
| { kind: 'unsupported' }
- | { kind: 'incomplete' };
+ | { kind: 'incomplete'; revision: CacheRevision };
export type ReadRecordsByKeysArgs = {
/** Serialized generated fragment document. */
@@ -78,6 +109,20 @@ export type SelectedRecordByKeyWire = {
record: unknown;
};
+export type ReadRecordsByKeysResult = {
+ revision: CacheRevision;
+ records: SelectedRecordByKeyWire[];
+};
+
+export type AffectedOperationsResult = {
+ revision: CacheRevision;
+ affectedOps: string[];
+};
+
+export type CacheRevisionResult = {
+ revision: CacheRevision;
+};
+
export const MAX_RECORD_SELECTION_PAGE_SIZE = 500;
export const MAX_CACHE_SEARCH_QUERY_BYTES = 512;
export const MAX_NORMALIZED_RECORD_KEY_LENGTH = 1024;
@@ -254,10 +299,12 @@ export type CachedQueryInstanceWire = CachedQueryVariantWire & {
};
export type HydrationResult =
- | { kind: 'data'; data: unknown }
- | { kind: 'void' };
+ | { kind: 'data'; data: unknown; revision: CacheRevision }
+ | { kind: 'void'; revision: CacheRevision };
export type WriteResult = {
+ /** Effective-view revision installed by this logical mutation. */
+ revision: CacheRevision;
/** Entity keys whose records changed. */
changed: string[];
/** Registered operation ids affected by the change (origin excluded). */
@@ -322,6 +369,7 @@ export type MutationSettlement =
export type CacheRequest = { id: number } & (
| { kind: 'init'; scope: string; hotCapacity?: number }
+ | { kind: 'current-revision' }
| {
kind: 'read';
opId?: string;
@@ -479,7 +527,7 @@ export type CachePush =
/** Changed entity keys, for diagnostics/advanced consumers. */
keys: string[];
}
- | { kind: 'cache-changed' }
+ | { kind: 'cache-changed'; revision: CacheRevision }
| { kind: 'mutation-settled'; settlement: MutationSettlement };
export type WorkerMessage = CacheResponse | CachePush;
@@ -554,7 +602,10 @@ export function isCachePush(value: unknown): value is CachePush {
isWireStringArray(value.keys)
);
case 'cache-changed':
- return hasOnlyWireKeys(value, ['kind']);
+ return (
+ hasOnlyWireKeys(value, ['kind', 'revision']) &&
+ isCacheRevision(value.revision)
+ );
case 'mutation-settled': {
const settlement = value.settlement;
if (
diff --git a/apps/web/src/lib/graphql-cache/telemetry-otel.test.ts b/apps/web/src/lib/graphql-cache/telemetry-otel.test.ts
index 4420345ba6..de17d075ef 100644
--- a/apps/web/src/lib/graphql-cache/telemetry-otel.test.ts
+++ b/apps/web/src/lib/graphql-cache/telemetry-otel.test.ts
@@ -27,6 +27,7 @@ describe('cache OpenTelemetry sink', () => {
errorCode: 'opfs-quota',
openOutcome: 'reset-corrupt',
queueDiagnosticsAvailability: 'available',
+ revisionCategory: 'optimistic-commit',
resetAttempt: 'wipe-before-open',
queueDepth: 4,
oldestAgeMs: 25,
@@ -45,6 +46,7 @@ describe('cache OpenTelemetry sink', () => {
'cache.error_code': 'opfs-quota',
'cache.open_outcome': 'reset-corrupt',
'cache.queue_diagnostics_availability': 'available',
+ 'cache.revision_category': 'optimistic-commit',
'cache.reset_attempt': 'wipe-before-open',
'cache.duration_ms': 12,
'cache.queue_depth': 4,
diff --git a/apps/web/src/lib/graphql-cache/telemetry-otel.ts b/apps/web/src/lib/graphql-cache/telemetry-otel.ts
index 2c5ec32d01..996ccd440f 100644
--- a/apps/web/src/lib/graphql-cache/telemetry-otel.ts
+++ b/apps/web/src/lib/graphql-cache/telemetry-otel.ts
@@ -46,6 +46,9 @@ export function createOtelCacheTelemetrySink(): CacheTelemetrySink {
event.queueDiagnosticsAvailability
);
}
+ if (event.revisionCategory !== undefined) {
+ span.setAttr('cache.revision_category', event.revisionCategory);
+ }
if (event.resetAttempt !== undefined) {
span.setAttr('cache.reset_attempt', event.resetAttempt);
}
diff --git a/apps/web/src/lib/graphql-cache/telemetry.test.ts b/apps/web/src/lib/graphql-cache/telemetry.test.ts
index aa061702ad..b978b7e637 100644
--- a/apps/web/src/lib/graphql-cache/telemetry.test.ts
+++ b/apps/web/src/lib/graphql-cache/telemetry.test.ts
@@ -77,6 +77,7 @@ describe('cache telemetry privacy contract', () => {
errorCode: 'none',
openOutcome: 'reset-corrupt',
queueDiagnosticsAvailability: 'available',
+ revisionCategory: 'authoritative-write',
resetAttempt: 'wipe-before-open',
queueDepth: 3,
oldestAgeMs: 42,
@@ -90,6 +91,7 @@ describe('cache telemetry privacy contract', () => {
name: 'graphql_cache.queue_diagnostics',
openOutcome: 'reset-corrupt',
queueDiagnosticsAvailability: 'available',
+ revisionCategory: 'authoritative-write',
resetAttempt: 'wipe-before-open',
queueDepth: 3,
oldestAgeMs: 42,
diff --git a/apps/web/src/lib/graphql-cache/telemetry.ts b/apps/web/src/lib/graphql-cache/telemetry.ts
index 386ad31fbf..952021ce1f 100644
--- a/apps/web/src/lib/graphql-cache/telemetry.ts
+++ b/apps/web/src/lib/graphql-cache/telemetry.ts
@@ -19,6 +19,7 @@ export const CACHE_TELEMETRY_EVENT_NAMES = [
'graphql_cache.lock_wait',
'graphql_cache.storage_reset_required',
'graphql_cache.logical_reset',
+ 'graphql_cache.revision_advance',
'graphql_cache.reset_wipe',
'graphql_cache.origin_storage_pressure',
'graphql_cache.linear_memory',
@@ -75,6 +76,17 @@ export const CACHE_QUEUE_DIAGNOSTICS_AVAILABILITY = [
export type CacheQueueDiagnosticsAvailability =
(typeof CACHE_QUEUE_DIAGNOSTICS_AVAILABILITY)[number];
+export const CACHE_REVISION_CATEGORIES = [
+ 'authoritative-write',
+ 'optimistic-enqueue',
+ 'optimistic-commit',
+ 'optimistic-rollback',
+ 'external-invalidation',
+ 'deletion',
+ 'clear',
+] as const;
+export type CacheRevisionCategory = (typeof CACHE_REVISION_CATEGORIES)[number];
+
/** Payload-free, bounded error classes shared by all cache layers. */
export const CACHE_ERROR_CODES = [
'none',
@@ -143,6 +155,7 @@ export type CacheTelemetryObservation = {
persistence?: 'granted' | 'denied' | 'unknown';
openOutcome?: CacheOpenOutcome;
queueDiagnosticsAvailability?: CacheQueueDiagnosticsAvailability;
+ revisionCategory?: CacheRevisionCategory;
resetAttempt?: 'wipe-before-open';
durationMs?: number;
bytes?: number;
@@ -245,6 +258,10 @@ function sanitizeObservation(
queueDiagnosticsAvailability: input.queueDiagnosticsAvailability,
}
: {}),
+ ...(input.revisionCategory !== undefined &&
+ CACHE_REVISION_CATEGORIES.includes(input.revisionCategory)
+ ? { revisionCategory: input.revisionCategory }
+ : {}),
...(input.resetAttempt === 'wipe-before-open'
? { resetAttempt: input.resetAttempt }
: {}),
@@ -470,6 +487,7 @@ export function operationCategoryForRequest(
.with('init', () => 'initialization' as const)
.with(
'read',
+ 'current-revision',
'read-records-by-keys',
'search',
'entity-filter',
@@ -612,6 +630,7 @@ export function isCacheTelemetryObservation(
'persistence',
'openOutcome',
'queueDiagnosticsAvailability',
+ 'revisionCategory',
'resetAttempt',
'durationMs',
'bytes',
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 80087a8d1f..746e4a7f7b 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
@@ -1,6 +1,10 @@
/// <reference lib="webworker" />
-import type { CacheRequest, CacheResponse } from '../../protocol';
+import type {
+ CacheRequest,
+ CacheResponse,
+ INITIAL_CACHE_REVISION,
+} from '../../protocol';
import {
CACHE_COORDINATOR_PROTOCOL_VERSION,
type CoordinatorToEngineEnvelope,
@@ -92,9 +96,12 @@ const sendStaleResponse = (ownerEpoch: number, routeId: number): void => {
);
};
+type FakeEngineState = { revision: bigint };
+
const execute = async (
database: IDBDatabase,
- request: CacheRequest
+ request: CacheRequest,
+ state: FakeEngineState
): Promise<CacheResponse> => {
if (request.kind === 'read' && request.query.includes('Slow')) {
await delay(10_000);
@@ -102,12 +109,20 @@ const execute = async (
switch (request.kind) {
case 'init':
return { id: request.id, ok: true, result: null };
+ case 'current-revision':
+ return { id: request.id, ok: true, result: state.revision.toString() };
case 'write':
await put(database, request.data);
+ state.revision += 1n;
return {
id: request.id,
ok: true,
- result: { changed: ['ROOT_QUERY'], affectedOps: [], reset: false },
+ result: {
+ revision: state.revision.toString(),
+ changed: ['ROOT_QUERY'],
+ affectedOps: [],
+ reset: false,
+ },
};
case 'read': {
const value = await get(database);
@@ -120,7 +135,12 @@ const execute = async (
}
case 'clear':
await clear(database);
- return { id: request.id, ok: true, result: null };
+ state.revision += 1n;
+ return {
+ id: request.id,
+ ok: true,
+ result: state.revision.toString(),
+ };
default:
return {
id: request.id,
@@ -148,6 +168,7 @@ async function activate(
ownerEpoch: activation.ownerEpoch,
});
let database: IDBDatabase | undefined;
+ const engineState: FakeEngineState = { revision: 0n };
let queue = Promise.resolve();
let draining = false;
let requestShutdown: (() => void) | undefined;
@@ -214,7 +235,11 @@ async function activate(
queue = queue.then(async () => {
let response: CacheResponse;
try {
- response = await execute(activeDatabase, message.request);
+ response = await execute(
+ activeDatabase,
+ message.request,
+ engineState
+ );
} catch (error) {
response = {
id: message.request.id,
@@ -240,7 +265,11 @@ async function activate(
withVersion<EngineToCoordinatorEnvelope>({
kind: 'engine-push',
ownerEpoch: activation.ownerEpoch,
- push: { kind: 'cache-changed' },
+ push: {
+ kind: 'cache-changed',
+ revision:
+ engineState.revision.toString() as typeof INITIAL_CACHE_REVISION,
+ },
})
);
}
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 aca24db805..28c543fa52 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
@@ -1,5 +1,6 @@
import { describe, expect, it, vi } from 'vitest';
import type { CacheRequest } from '../protocol';
+import { INITIAL_CACHE_REVISION } from '../protocol';
import {
type CacheEngineRuntimeOptions,
installCacheEngineWorker,
@@ -587,7 +588,10 @@ describe('cache engine worker runtime', () => {
markEffectStarted();
await oldOutputBlocked;
port.postMessage({ id: request.id, ok: true, result: null });
- port.postMessage({ kind: 'cache-changed' });
+ port.postMessage({
+ kind: 'cache-changed',
+ revision: INITIAL_CACHE_REVISION,
+ });
markOldOutputPosted();
},
})
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 ad24cc8d0d..c624b82af1 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
@@ -1,4 +1,5 @@
import { describe, expect, it } from 'vitest';
+import { INITIAL_CACHE_REVISION } from '../protocol';
import { type CoordinatorAction, CoordinatorCore } from './coordinator-core';
import type { DatabaseActionProof } from './coordinator-protocol';
@@ -168,8 +169,16 @@ describe('CoordinatorCore', () => {
core.beginGracefulDeparture('tab-a', 1);
expect(core.request('tab-b', clear(5))).toEqual([]);
expect(core.snapshot().queuedRequestCount).toBe(1);
- expect(core.enginePush(1, { kind: 'cache-changed' })).toEqual([
- { kind: 'broadcast-push', push: { kind: 'cache-changed' } },
+ expect(
+ core.enginePush(1, {
+ kind: 'cache-changed',
+ revision: INITIAL_CACHE_REVISION,
+ })
+ ).toEqual([
+ {
+ kind: 'broadcast-push',
+ push: { kind: 'cache-changed', revision: INITIAL_CACHE_REVISION },
+ },
]);
expect(
core.engineResponse(1, routed.routeId, {
@@ -254,7 +263,12 @@ describe('CoordinatorCore', () => {
reason: 'unknown-route',
})
);
- expect(core.enginePush(0, { kind: 'cache-changed' })).toContainEqual(
+ expect(
+ core.enginePush(0, {
+ kind: 'cache-changed',
+ revision: INITIAL_CACHE_REVISION,
+ })
+ ).toContainEqual(
expect.objectContaining({
kind: 'drop-stale-engine-message',
reason: 'stale-epoch',
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 e3db174409..54ef7cec71 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
@@ -1,4 +1,5 @@
import { describe, expect, it } from 'vitest';
+import { INITIAL_CACHE_REVISION } from '../protocol';
import {
CACHE_COORDINATOR_PROTOCOL_VERSION,
databaseOwnerLockName,
@@ -25,6 +26,7 @@ const enginePort = {
describe('coordinator runtime protocol', () => {
it('validates cache RPCs and rejects unknown fields or kinds', () => {
expect(isCacheRequest({ id: 0, kind: 'clear' })).toBe(true);
+ expect(isCacheRequest({ id: 1, kind: 'current-revision' })).toBe(true);
expect(isCacheRequest({ id: 1, kind: 'read', query: '{ x }' })).toBe(true);
expect(
isCacheRequest({
@@ -114,7 +116,12 @@ describe('coordinator runtime protocol', () => {
})
).toBe(false);
expect(isCacheResponse({ id: 3, ok: false, error: 4 })).toBe(false);
- expect(isCachePush({ kind: 'cache-changed' })).toBe(true);
+ expect(
+ isCachePush({
+ kind: 'cache-changed',
+ revision: INITIAL_CACHE_REVISION,
+ })
+ ).toBe(true);
expect(
isCachePush({
kind: 'mutation-settled',
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 83dad846e2..2e1c2c8b37 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
@@ -365,6 +365,8 @@ export function isCacheRequest(value: unknown): value is CacheRequest {
isNonEmptyString(value.scope) &&
isOptionalPositiveInteger(value.hotCapacity)
);
+ case 'current-revision':
+ return hasOnlyKeys(value, ['id', 'kind']);
case 'read':
return (
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 be8c5a8ddd..bb62975579 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
@@ -1,4 +1,5 @@
import { afterEach, describe, expect, it, vi } from 'vitest';
+import { INITIAL_CACHE_REVISION } from '../protocol';
import {
CACHE_COORDINATOR_PROTOCOL_VERSION,
databaseOwnerLockName,
@@ -338,11 +339,19 @@ describe('CoordinatorRouter', () => {
...version,
kind: 'engine-push',
ownerEpoch: 1,
- push: { kind: 'cache-changed' },
+ push: {
+ kind: 'cache-changed',
+ revision: INITIAL_CACHE_REVISION,
+ },
});
for (const tab of [tabA, tabB, tabC]) {
expect(messagesOfKind(tab, 'cache-message')).toContainEqual(
- expect.objectContaining({ message: { kind: 'cache-changed' } })
+ expect.objectContaining({
+ message: {
+ kind: 'cache-changed',
+ revision: INITIAL_CACHE_REVISION,
+ },
+ })
);
}
});
diff --git a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
index df389e562c..73ceecb80a 100644
--- a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
+++ b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
@@ -10,18 +10,21 @@
import type { EntityResolverWire } from '../exchange/entity-resolvers';
import type {
+ AffectedOperationsResult,
CachedQueryInstanceWire,
CachedQueryVariantWire,
+ CacheRevision,
+ CacheRevisionResult,
ClaimedMutation,
EnqueueOptimisticMutationResult,
EntityFilterCacheArgs,
EntityFilterCacheResult,
OptimisticLinkPatchWire,
QueryRevalidationWire,
+ ReadRecordsByKeysResult,
ReadResult,
SearchCacheArgs,
SearchCachePage,
- SelectedRecordByKeyWire,
WriteResult,
} from '../protocol';
import { workerCacheTelemetry } from '../telemetry-relay';
@@ -62,6 +65,7 @@ export type CacheEngineHydrationResult = WriteResult & {
};
export interface CacheEngine {
+ currentRevision(): Promise<CacheRevision>;
boundIdentity(): Promise<string | null>;
/** Optional for compatibility engines; absence means unavailable. */
queueDiagnostics?(): Promise<CacheQueueDiagnostics>;
@@ -76,7 +80,7 @@ export interface CacheEngine {
document: string,
fragmentName: string,
keys: string[]
- ): Promise<SelectedRecordByKeyWire[]>;
+ ): Promise<ReadRecordsByKeysResult>;
search(
request: SearchCacheArgs & { nowMs: number }
): Promise<SearchCachePage>;
@@ -154,10 +158,10 @@ export interface CacheEngine {
leaseOwner: string,
leaseGeneration: string
): Promise<WriteResult>;
- invalidateKeys(keys: string[]): Promise<string[]>;
- deleteKeys(keys: string[]): Promise<string[]>;
+ invalidateKeys(keys: string[]): Promise<AffectedOperationsResult>;
+ deleteKeys(keys: string[]): Promise<AffectedOperationsResult>;
teardownOperation(opId: string): Promise<void>;
- clear(): Promise<void>;
+ clear(): Promise<CacheRevisionResult>;
/** Reset/recreate OPFS; concurrent calls wait for the fresh engine. */
physicalReset(): Promise<void>;
/** Gracefully close Turso/OPFS and release the owner lock. */
diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
index 4e01e2b67e..97d41364f0 100644
--- a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
@@ -1,4 +1,5 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { INITIAL_CACHE_REVISION } from '../protocol';
const loadCacheWasmMock = vi.hoisted(() => vi.fn());
@@ -22,7 +23,11 @@ describe('CacheWorkerCore', () => {
record: { id: 'item-1' },
},
];
- const readRecordsByKeys = vi.fn().mockResolvedValue(records);
+ const selectionResult = {
+ revision: INITIAL_CACHE_REVISION,
+ records,
+ };
+ const readRecordsByKeys = vi.fn().mockResolvedValue(selectionResult);
loadCacheWasmMock.mockResolvedValue({
openCache: vi.fn().mockResolvedValue({ readRecordsByKeys }),
});
@@ -48,7 +53,11 @@ describe('CacheWorkerCore', () => {
'Item',
['GraphqlSoupDocument:item-1']
);
- expect(messages.at(-1)).toEqual({ id: 2, ok: true, result: records });
+ expect(messages.at(-1)).toEqual({
+ id: 2,
+ ok: true,
+ result: selectionResult,
+ });
});
it('dispatches bounded search to the wasm compact projection', async () => {
@@ -95,6 +104,7 @@ describe('CacheWorkerCore', () => {
const order: string[] = [];
let resolveEnqueue!: (result: {
transactionId: string;
+ revision: typeof INITIAL_CACHE_REVISION;
changed: string[];
affectedOps: string[];
reset: false;
@@ -104,6 +114,7 @@ describe('CacheWorkerCore', () => {
order.push('enqueue:start');
return new Promise<{
transactionId: string;
+ revision: typeof INITIAL_CACHE_REVISION;
changed: string[];
affectedOps: string[];
reset: false;
@@ -165,6 +176,7 @@ describe('CacheWorkerCore', () => {
);
resolveEnqueue({
transactionId: '1',
+ revision: INITIAL_CACHE_REVISION,
changed: ['Thing:1'],
affectedOps: ['client:query'],
reset: false,
@@ -423,6 +435,7 @@ describe('CacheWorkerCore', () => {
order.push(`enqueue:${query}`);
return {
transactionId: query,
+ revision: INITIAL_CACHE_REVISION,
changed: [],
affectedOps: [],
reset: false,
@@ -644,6 +657,7 @@ describe('CacheWorkerCore', () => {
order.push('enqueue');
return {
transactionId: '1',
+ revision: INITIAL_CACHE_REVISION,
changed: [],
affectedOps: [],
reset: false,
@@ -754,6 +768,7 @@ describe('CacheWorkerCore', () => {
it('pushes cache changes even without affected operations', async () => {
const writeResult = {
+ revision: INITIAL_CACHE_REVISION,
changed: ['GraphqlSoupDocument:doc-1'],
affectedOps: [],
reset: false,
@@ -795,7 +810,10 @@ describe('CacheWorkerCore', () => {
{ user: { id: 'user-1' } },
undefined
);
- expect(messages).toContainEqual({ kind: 'cache-changed' });
+ expect(messages).toContainEqual({
+ kind: 'cache-changed',
+ revision: INITIAL_CACHE_REVISION,
+ });
});
it('drains earlier request responses before consuming close and rejects later admission', async () => {
@@ -953,6 +971,7 @@ describe('CacheWorkerCore', () => {
});
const close = vi.fn().mockResolvedValue(undefined);
const writeQuery = vi.fn().mockResolvedValue({
+ revision: INITIAL_CACHE_REVISION,
changed: [],
affectedOps: [],
reset: false,
@@ -1086,6 +1105,7 @@ describe('CacheWorkerCore', () => {
.mockImplementation(() => new Promise(() => {}));
const readQuery = vi.fn().mockResolvedValue({ kind: 'miss' });
const writeQuery = vi.fn().mockResolvedValue({
+ revision: INITIAL_CACHE_REVISION,
changed: [],
affectedOps: [],
reset: false,
@@ -1155,6 +1175,7 @@ describe('CacheWorkerCore', () => {
.mockRejectedValueOnce(resetError)
.mockImplementation(() => new Promise(() => {}));
const writeQuery = vi.fn().mockResolvedValue({
+ revision: INITIAL_CACHE_REVISION,
changed: [],
affectedOps: [],
reset: false,
@@ -1225,6 +1246,7 @@ describe('CacheWorkerCore', () => {
it('records an identity-changing hydration as a logical reset', async () => {
const hydrateQuery = vi.fn().mockResolvedValue({
+ revision: INITIAL_CACHE_REVISION,
changed: [],
affectedOps: [],
reset: true,
@@ -1260,7 +1282,12 @@ describe('CacheWorkerCore', () => {
expect(port.postMessage).toHaveBeenLastCalledWith({
id: 2,
ok: true,
- result: { kind: 'data', data: { cursor: 'next' }, reset: true },
+ result: {
+ kind: 'data',
+ data: { cursor: 'next' },
+ revision: INITIAL_CACHE_REVISION,
+ reset: true,
+ },
});
});
diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.ts
index 6961f33a50..4ff0f6ba3f 100644
--- a/apps/web/src/lib/graphql-cache/worker/worker-core.ts
+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.ts
@@ -5,17 +5,20 @@
import { match } from 'ts-pattern';
import type {
+ AffectedOperationsResult,
CachePush,
CacheRequest,
CacheResponse,
+ CacheRevisionResult,
EnqueueOptimisticMutationResult,
EntityFilterCacheResult,
HydrationResult,
+ ReadRecordsByKeysResult,
ReadResult,
SearchCachePage,
- SelectedRecordByKeyWire,
WriteResult,
} from '../protocol';
+import { parseCacheRevision } from '../protocol';
import {
type CacheTelemetryRecorderLike,
classifyCacheError,
@@ -81,6 +84,28 @@ function isQueryDataWrite(request: CacheRequest): boolean {
return request.kind === 'write' || request.kind === 'hydrate';
}
+function revisionAdvancementCategory(
+ request: CacheRequest
+):
+ | 'authoritative-write'
+ | 'optimistic-enqueue'
+ | 'optimistic-commit'
+ | 'optimistic-rollback'
+ | 'external-invalidation'
+ | 'deletion'
+ | 'clear'
+ | undefined {
+ return match(request.kind)
+ .with('write', 'hydrate', () => 'authoritative-write' as const)
+ .with('enqueue-optimistic-mutation', () => 'optimistic-enqueue' as const)
+ .with('commit-optimistic-write', () => 'optimistic-commit' as const)
+ .with('rollback-optimistic-write', () => 'optimistic-rollback' as const)
+ .with('invalidate', () => 'external-invalidation' as const)
+ .with('delete-records', () => 'deletion' as const)
+ .with('clear', () => 'clear' as const)
+ .otherwise(() => undefined);
+}
+
function requestPriority(request: CacheRequest): number {
if (request.kind === 'hydrate') return BACKGROUND_HYDRATION_PRIORITY;
if (request.kind === 'read') {
@@ -181,6 +206,16 @@ export class CacheWorkerCore {
try {
const result = await this.enqueue(request);
const durationMs = this.now() - startedAt;
+ const revisionCategory = revisionAdvancementCategory(request);
+ if (revisionCategory !== undefined) {
+ this.telemetry.record({
+ name: 'graphql_cache.revision_advance',
+ operationCategory: category,
+ outcome: 'success',
+ errorCode: 'none',
+ revisionCategory,
+ });
+ }
this.telemetry.record({
name: 'graphql_cache.engine_request',
operationCategory: category,
@@ -385,6 +420,9 @@ export class CacheWorkerCore {
await this.init(request.scope, request.hotCapacity);
return null;
})
+ .with({ kind: 'current-revision' }, async () => {
+ return parseCacheRevision(await this.requireEngine().currentRevision());
+ })
.with({ kind: 'read' }, async (request) => {
const engine = this.requireEngine();
const result: ReadResult = await engine.readQuery(
@@ -397,13 +435,16 @@ export class CacheWorkerCore {
return result;
})
.with({ kind: 'read-records-by-keys' }, async (request) => {
- const result: SelectedRecordByKeyWire[] =
+ const result: ReadRecordsByKeysResult =
await this.requireEngine().readRecordsByKeys(
request.document,
request.fragmentName,
request.keys
);
- return result;
+ return {
+ ...result,
+ revision: parseCacheRevision(result.revision),
+ };
})
.with({ kind: 'search' }, async (request) => {
const result: SearchCachePage = await this.requireEngine().search(
@@ -414,7 +455,9 @@ export class CacheWorkerCore {
.with({ kind: 'entity-filter' }, async (request) => {
const result: EntityFilterCacheResult =
await this.requireEngine().entityFilter(request.request);
- return result;
+ return result.kind === 'unsupported'
+ ? result
+ : { ...result, revision: parseCacheRevision(result.revision) };
})
.with({ kind: 'write' }, async (request) => {
const engine = this.requireEngine();
@@ -429,6 +472,7 @@ export class CacheWorkerCore {
request.data,
request.identity
);
+ result.revision = parseCacheRevision(result.revision);
this.fanOut(result, true);
return result;
})
@@ -440,11 +484,17 @@ export class CacheWorkerCore {
request.data,
request.identity
);
+ result.revision = parseCacheRevision(result.revision);
this.fanOut(result, true);
const hydration: HydrationResult & Pick<WriteResult, 'reset'> =
result.data === null
- ? { kind: 'void', reset: result.reset }
- : { kind: 'data', data: result.data, reset: result.reset };
+ ? { kind: 'void', revision: result.revision, reset: result.reset }
+ : {
+ kind: 'data',
+ data: result.data,
+ revision: result.revision,
+ reset: result.reset,
+ };
return hydration;
})
.with({ kind: 'enqueue-optimistic-mutation' }, async (request) => {
@@ -463,6 +513,7 @@ export class CacheWorkerCore {
request.nowMs,
request.leaseExpiresAtMs
);
+ result.revision = parseCacheRevision(result.revision);
this.fanOut(result, true);
return result;
})
@@ -512,6 +563,7 @@ export class CacheWorkerCore {
request.variables,
request.data
);
+ result.revision = parseCacheRevision(result.revision);
this.fanOut(result, true);
this.push({
kind: 'mutation-settled',
@@ -529,6 +581,7 @@ export class CacheWorkerCore {
request.leaseOwner,
request.leaseGeneration
);
+ result.revision = parseCacheRevision(result.revision);
this.fanOut(result, true);
this.push({
kind: 'mutation-settled',
@@ -542,40 +595,49 @@ export class CacheWorkerCore {
})
.with({ kind: 'invalidate' }, async (request) => {
const engine = this.requireEngine();
- const affectedOps = await engine.invalidateKeys(request.keys);
+ const result: AffectedOperationsResult = await engine.invalidateKeys(
+ request.keys
+ );
+ result.revision = parseCacheRevision(result.revision);
this.fanOut(
{
+ revision: result.revision,
changed: request.keys,
- affectedOps,
+ affectedOps: result.affectedOps,
reset: false,
revalidations: [],
},
true
);
- return affectedOps;
+ return result;
})
.with({ kind: 'delete-records' }, async (request) => {
const engine = this.requireEngine();
- const affectedOps = await engine.deleteKeys(request.keys);
+ const result: AffectedOperationsResult = await engine.deleteKeys(
+ request.keys
+ );
+ result.revision = parseCacheRevision(result.revision);
this.fanOut(
{
+ revision: result.revision,
changed: request.keys,
- affectedOps,
+ affectedOps: result.affectedOps,
reset: false,
revalidations: [],
},
true
);
- return affectedOps;
+ return result;
})
.with({ kind: 'teardown' }, async (request) => {
await this.requireEngine().teardownOperation(request.opId);
return null;
})
.with({ kind: 'clear' }, async () => {
- await this.requireEngine().clear();
- this.push({ kind: 'cache-changed' });
- return null;
+ const result: CacheRevisionResult = await this.requireEngine().clear();
+ const revision = parseCacheRevision(result.revision);
+ this.push({ kind: 'cache-changed', revision });
+ return revision;
})
.exhaustive();
}
@@ -820,7 +882,7 @@ export class CacheWorkerCore {
});
}
if (cacheChanged) {
- this.push({ kind: 'cache-changed' });
+ this.push({ kind: 'cache-changed', revision: result.revision });
}
}
diff --git a/apps/web/src/lib/queries/channel/graphql.ts b/apps/web/src/lib/queries/channel/graphql.ts
index b6b65e78b6..9cbf00fc9d 100644
--- a/apps/web/src/lib/queries/channel/graphql.ts
+++ b/apps/web/src/lib/queries/channel/graphql.ts
@@ -51,7 +51,7 @@ export async function materializeCachedGraphqlChannels(
channelDocuments.map((document) => document.recordKey)
);
- return records.flatMap(({ recordKey, record }) => {
+ return records.records.flatMap(({ recordKey, record }) => {
const channel = record as GraphqlChannelQuickAccessFieldsFragment;
if (channel.__typename !== 'GraphqlSoupChannel') return [];
const separator = recordKey.indexOf(':');
diff --git a/apps/web/src/lib/queries/channel/tests/graphql.test.ts b/apps/web/src/lib/queries/channel/tests/graphql.test.ts
index 23fbf893d3..a06ec7f196 100644
--- a/apps/web/src/lib/queries/channel/tests/graphql.test.ts
+++ b/apps/web/src/lib/queries/channel/tests/graphql.test.ts
@@ -4,6 +4,7 @@ import type {
SearchCacheArgs,
SearchCachePage,
} from '@graphql-cache/index';
+import { INITIAL_CACHE_REVISION } from '@graphql-cache/index';
import { expect, it, vi } from 'vitest';
import { readCachedGraphqlChannels } from '../graphql';
@@ -13,7 +14,13 @@ function cacheHost(
args: ReadRecordsByKeysArgs
) => Promise<Array<{ recordKey: string; record: unknown }>>
): Pick<CacheHost, 'search' | 'readRecordsByKeys'> {
- return { search, readRecordsByKeys };
+ return {
+ search,
+ readRecordsByKeys: async (args) => ({
+ revision: INITIAL_CACHE_REVISION,
+ records: await readRecordsByKeys(args),
+ }),
+ };
}
it('reads recent channels and DMs from the cache projection', async () => {
diff --git a/apps/web/src/lib/queries/history/graphql.ts b/apps/web/src/lib/queries/history/graphql.ts
index 95b76e1906..e29472db3b 100644
--- a/apps/web/src/lib/queries/history/graphql.ts
+++ b/apps/web/src/lib/queries/history/graphql.ts
@@ -120,7 +120,7 @@ export async function materializeCachedGraphqlHistoryItems(
nameSelection(typename),
keys
);
- for (const { recordKey, record } of records) {
+ for (const { recordKey, record } of records.records) {
recordsByKey.set(recordKey, record);
}
})
diff --git a/apps/web/src/lib/queries/history/tests/graphql.test.ts b/apps/web/src/lib/queries/history/tests/graphql.test.ts
index fd477a4cd7..142c771a07 100644
--- a/apps/web/src/lib/queries/history/tests/graphql.test.ts
+++ b/apps/web/src/lib/queries/history/tests/graphql.test.ts
@@ -4,6 +4,7 @@ import type {
SearchCacheArgs,
SearchCachePage,
} from '@graphql-cache/index';
+import { INITIAL_CACHE_REVISION } from '@graphql-cache/index';
import { describe, expect, it, vi } from 'vitest';
import { readCachedGraphqlHistoryItems } from '../graphql';
@@ -13,7 +14,13 @@ function cacheHost(
args: ReadRecordsByKeysArgs
) => Promise<Array<{ recordKey: string; record: unknown }>>
): Pick<CacheHost, 'search' | 'readRecordsByKeys'> {
- return { search, readRecordsByKeys };
+ return {
+ search,
+ readRecordsByKeys: async (args) => ({
+ revision: INITIAL_CACHE_REVISION,
+ records: await readRecordsByKeys(args),
+ }),
+ };
}
describe('cached GraphQL history', () => {
diff --git a/apps/web/src/lib/queries/soup/graphql/items.test.ts b/apps/web/src/lib/queries/soup/graphql/items.test.ts
index 619dd41570..2ceec4bac2 100644
--- a/apps/web/src/lib/queries/soup/graphql/items.test.ts
+++ b/apps/web/src/lib/queries/soup/graphql/items.test.ts
@@ -13,6 +13,9 @@ const getGraphqlSoupClientMock = vi.hoisted(() => vi.fn());
const getGraphqlSoupCacheHostMock = vi.hoisted(() => vi.fn());
const entityFilterMock = vi.hoisted(() => vi.fn());
const readRecordsByKeysMock = vi.hoisted(() => vi.fn());
+const REVISION_0 = '0';
+const REVISION_1 = '1';
+const REVISION_2 = '2';
const mapGraphqlSoupPageMock = vi.hoisted(() =>
vi.fn(
(data: {
@@ -29,7 +32,10 @@ const mapSoupPageToEntityListMock = vi.hoisted(() =>
const makeGraphqlSoupInputMock = vi.hoisted(() => vi.fn());
vi.mock('@macro-inc/observability', () => ({
- Telemetry: { error: vi.fn() },
+ Telemetry: {
+ error: vi.fn(),
+ span: vi.fn(() => ({ setAttr: vi.fn(), end: vi.fn() })),
+ },
}));
vi.mock('@queries/storage/instructions-md', () => ({
@@ -39,6 +45,8 @@ vi.mock('@queries/storage/instructions-md', () => ({
vi.mock('@app/lib/graphql-cache', () => ({
selectRecords: vi.fn(() => ({})),
readRecordsByKeys: readRecordsByKeysMock,
+ normalizedCacheResultMetadata: (result: OperationResult) =>
+ result.extensions?.__macroNormalizedCache,
}));
vi.mock('@service-storage/graphql-soup', () => ({
@@ -59,7 +67,13 @@ vi.mock('../transform-utils', () => ({
import { createGraphqlSoupAstItemsQuery } from './items';
type FakeExecution = {
- next(data: unknown): void;
+ next(
+ data: unknown,
+ metadata?: {
+ source: 'live-network' | 'normalized-cache-hit';
+ revision?: string;
+ }
+ ): void;
};
type SoupPageFixture = {
@@ -94,11 +108,17 @@ function makeFakeClient(): {
context,
} as Operation<unknown, Record<string, unknown>>;
executions.push({
- next: (data) =>
- subject.next({ operation, data } as OperationResult<
- unknown,
- Record<string, unknown>
- >),
+ next: (
+ data,
+ metadata = { source: 'live-network', revision: REVISION_1 }
+ ) =>
+ subject.next({
+ operation,
+ data,
+ extensions: { __macroNormalizedCache: metadata },
+ stale: false,
+ hasNext: false,
+ } as OperationResult<unknown, Record<string, unknown>>),
});
return subject.source;
};
@@ -124,8 +144,10 @@ describe('createGraphqlSoupAstItemsQuery', () => {
const fake = makeFakeClient();
getGraphqlSoupClientMock.mockReturnValue(fake.client);
getGraphqlSoupCacheHostMock.mockReturnValue({
+ currentRevision: async () => REVISION_0,
entityFilter: entityFilterMock,
onCacheChanged: () => () => undefined,
+ onCacheGenerationChanged: () => () => undefined,
});
makeGraphqlSoupInputMock.mockReturnValue({ initial: { limit: 50 } });
@@ -145,20 +167,26 @@ describe('createGraphqlSoupAstItemsQuery', () => {
const fake = makeFakeClient();
getGraphqlSoupClientMock.mockReturnValue(fake.client);
getGraphqlSoupCacheHostMock.mockReturnValue({
+ currentRevision: async () => REVISION_0,
entityFilter: entityFilterMock,
onCacheChanged: () => () => undefined,
+ onCacheGenerationChanged: () => () => undefined,
});
entityFilterMock.mockResolvedValue({
kind: 'complete',
+ revision: REVISION_0,
keys: ['GraphqlSoupDocument:task-1'],
optimistic: false,
});
- readRecordsByKeysMock.mockResolvedValue([
- {
- recordKey: 'GraphqlSoupDocument:task-1',
- record: { id: 'task-1', type: 'document', name: 'Local task' },
- },
- ]);
+ readRecordsByKeysMock.mockResolvedValue({
+ revision: REVISION_0,
+ records: [
+ {
+ recordKey: 'GraphqlSoupDocument:task-1',
+ record: { id: 'task-1', type: 'document', name: 'Local task' },
+ },
+ ],
+ });
await new Promise<void>((resolve) => {
createRoot((dispose) => {
@@ -192,34 +220,52 @@ describe('createGraphqlSoupAstItemsQuery', () => {
expect(entityFilterMock).toHaveBeenCalled();
});
- it('keeps an optimistic local page until cache settlement', async () => {
+ it('reevaluates exact local membership after optimistic settlement', async () => {
const fake = makeFakeClient();
getGraphqlSoupClientMock.mockReturnValue(fake.client);
- let notifyCacheChanged: () => void = () => undefined;
+ let currentRevision = REVISION_0;
+ let notifyCacheChanged: (revision: string) => void = () => undefined;
getGraphqlSoupCacheHostMock.mockReturnValue({
+ currentRevision: async () => currentRevision,
entityFilter: entityFilterMock,
- onCacheChanged: (callback: () => void) => {
+ onCacheChanged: (callback: (revision: string) => void) => {
notifyCacheChanged = callback;
return () => undefined;
},
+ onCacheGenerationChanged: () => () => undefined,
});
entityFilterMock
.mockResolvedValueOnce({
kind: 'complete',
+ revision: REVISION_0,
keys: ['GraphqlSoupDocument:task-1'],
optimistic: true,
})
.mockResolvedValueOnce({
kind: 'complete',
+ revision: REVISION_2,
keys: ['GraphqlSoupDocument:task-1'],
optimistic: false,
});
- readRecordsByKeysMock.mockResolvedValue([
- {
- recordKey: 'GraphqlSoupDocument:task-1',
- record: { id: 'task-1', type: 'document', name: 'Optimistic task' },
- },
- ]);
+ readRecordsByKeysMock
+ .mockResolvedValueOnce({
+ revision: REVISION_0,
+ records: [
+ {
+ recordKey: 'GraphqlSoupDocument:task-1',
+ record: { id: 'task-1', type: 'document', name: 'Optimistic task' },
+ },
+ ],
+ })
+ .mockResolvedValueOnce({
+ revision: REVISION_2,
+ records: [
+ {
+ recordKey: 'GraphqlSoupDocument:task-1',
+ record: { id: 'task-1', type: 'document', name: 'Network task' },
+ },
+ ],
+ });
await new Promise<void>((resolve) => {
createRoot((dispose) => {
@@ -242,9 +288,10 @@ describe('createGraphqlSoupAstItemsQuery', () => {
next_cursor: null,
})
);
- expect(query.data()?.entities[0]?.name).toBe('Optimistic task');
+ expect(query.data()?.entities[0]?.name).toBe('Network task');
- notifyCacheChanged();
+ currentRevision = REVISION_2;
+ notifyCacheChanged(REVISION_2);
await vi.waitFor(() => {
expect(entityFilterMock).toHaveBeenCalledTimes(2);
expect(query.data()?.entities[0]?.name).toBe('Network task');
@@ -257,6 +304,139 @@ describe('createGraphqlSoupAstItemsQuery', () => {
});
});
+ it('promotes realtime local revisions without a network rerun and fences stale generations', async () => {
+ const fake = makeFakeClient();
+ getGraphqlSoupClientMock.mockReturnValue(fake.client);
+ let currentRevision = REVISION_1;
+ let notifyCacheChanged: (revision: string) => void = () => undefined;
+ let notifyGenerationChanged: () => void = () => undefined;
+ let resolveRevision4!: (value: unknown) => void;
+ const revision4Filter = new Promise((resolve) => {
+ resolveRevision4 = resolve;
+ });
+ getGraphqlSoupCacheHostMock.mockReturnValue({
+ currentRevision: async () => currentRevision,
+ onCacheChanged: (callback: (revision: string) => void) => {
+ notifyCacheChanged = callback;
+ return () => undefined;
+ },
+ onCacheGenerationChanged: (callback: () => void) => {
+ notifyGenerationChanged = callback;
+ return () => undefined;
+ },
+ entityFilter: entityFilterMock,
+ });
+ entityFilterMock.mockImplementation(async () => {
+ if (currentRevision === '4') return await revision4Filter;
+ const names =
+ currentRevision === REVISION_2
+ ? ['Network item', 'Realtime item']
+ : currentRevision === '5'
+ ? ['Latest local item']
+ : ['Replacement durable item'];
+ return {
+ kind: 'complete',
+ revision: currentRevision,
+ keys: names.map((_, index) => `GraphqlSoupDocument:item-${index}`),
+ optimistic: false,
+ };
+ });
+ readRecordsByKeysMock.mockImplementation(
+ async (_host, _selection, keys: string[]) => {
+ const names =
+ currentRevision === REVISION_2
+ ? ['Network item', 'Realtime item']
+ : currentRevision === '5'
+ ? ['Latest local item']
+ : ['Replacement durable item'];
+ return {
+ revision: currentRevision,
+ records: keys.map((recordKey, index) => ({
+ recordKey,
+ record: {
+ id: `item-${index}`,
+ type: 'document',
+ name: names[index],
+ },
+ })),
+ };
+ }
+ );
+
+ let dispose!: () => void;
+ let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;
+ createRoot((rootDispose) => {
+ dispose = rootDispose;
+ query = createGraphqlSoupAstItemsQuery(
+ () => ({ params: {}, body: {} }) as never,
+ () => ({ enabled: true })
+ );
+ });
+
+ fake.executions[0]?.next(
+ graphqlSoupPage({
+ items: [{ id: 'item-0', type: 'document', name: 'Network item' }],
+ next_cursor: null,
+ }),
+ { source: 'live-network', revision: REVISION_1 }
+ );
+ expect(query.data()?.entities.map((item) => item.name)).toEqual([
+ 'Network item',
+ ]);
+
+ currentRevision = REVISION_2;
+ notifyCacheChanged(REVISION_2);
+ await vi.waitFor(() => {
+ expect(query.data()?.entities.map((item) => item.name)).toEqual([
+ 'Network item',
+ 'Realtime item',
+ ]);
+ });
+ expect(fake.executions).toHaveLength(1);
+
+ fake.executions[0]?.next(
+ graphqlSoupPage({
+ items: [{ id: 'item-0', type: 'document', name: 'New network item' }],
+ next_cursor: null,
+ }),
+ { source: 'live-network', revision: '3' }
+ );
+ expect(query.data()?.entities.map((item) => item.name)).toEqual([
+ 'New network item',
+ ]);
+
+ currentRevision = '4';
+ notifyCacheChanged('4');
+ await vi.waitFor(() => expect(entityFilterMock).toHaveBeenCalledTimes(2));
+ currentRevision = '5';
+ notifyCacheChanged('5');
+ await vi.waitFor(() => {
+ expect(query.data()?.entities.map((item) => item.name)).toEqual([
+ 'Latest local item',
+ ]);
+ });
+ resolveRevision4({
+ kind: 'complete',
+ revision: '4',
+ keys: ['GraphqlSoupDocument:stale'],
+ optimistic: false,
+ });
+ await Promise.resolve();
+ expect(query.data()?.entities.map((item) => item.name)).toEqual([
+ 'Latest local item',
+ ]);
+
+ currentRevision = REVISION_0;
+ notifyGenerationChanged();
+ await vi.waitFor(() => {
+ expect(query.data()?.entities.map((item) => item.name)).toEqual([
+ 'Replacement durable item',
+ ]);
+ });
+ expect(fake.executions).toHaveLength(1);
+ dispose();
+ });
+
it('retains identical page projections across cache re-executions', () => {
const firstPage = {
items: [{ id: 'task-1', type: 'document', name: 'Task' }],
diff --git a/apps/web/src/lib/queries/soup/graphql/items.ts b/apps/web/src/lib/queries/soup/graphql/items.ts
index cadf13acd9..c25c4d03c7 100644
--- a/apps/web/src/lib/queries/soup/graphql/items.ts
+++ b/apps/web/src/lib/queries/soup/graphql/items.ts
@@ -4,7 +4,12 @@
* directly. The public REST/GraphQL facade lives in ../items.ts.
*/
-import { readRecordsByKeys, selectRecords } from '@app/lib/graphql-cache';
+import {
+ type CacheRevision,
+ normalizedCacheResultMetadata,
+ readRecordsByKeys,
+ selectRecords,
+} from '@app/lib/graphql-cache';
import { createUrqlInfiniteQuery } from '@app/lib/urql-solid';
import { Telemetry } from '@macro-inc/observability';
import { useInstructionsMdIdQuery } from '@queries/storage/instructions-md';
@@ -24,6 +29,7 @@ import {
import type { CombinedError } from '@urql/core';
import {
type Accessor,
+ batch,
createComputed,
createEffect,
createMemo,
@@ -85,31 +91,110 @@ export function createGraphqlSoupAstItemsQuery(
const firstPageInput = createMemo(() => inputForCursor(null));
const isSupported = () => firstPageInput() !== undefined;
- const [localPlaceholder, setLocalPlaceholder] = createSignal<
- { data: SoupAstItemsData; optimistic: boolean } | undefined
+ type LocalProjection = {
+ revision: CacheRevision;
+ data: SoupAstItemsData;
+ optimistic: boolean;
+ };
+ const [currentCacheRevision, setCurrentCacheRevision] = createSignal<
+ CacheRevision | undefined
+ >();
+ const [networkAuthorityRevision, setNetworkAuthorityRevision] = createSignal<
+ CacheRevision | undefined
+ >();
+ const [localProjection, setLocalProjection] = createSignal<
+ LocalProjection | undefined
>();
- const [cacheRevision, setCacheRevision] = createSignal(0);
const soupItemSelection = selectRecords(SoupItemFieldsFragmentDoc);
let localRequest = 0;
+ let cacheGeneration = 0;
+ let resetContinuationPages: (() => void) | undefined;
+ let previousInitialInput: GraphqlSoupInput | undefined;
+ let staleFallbackSpan: ReturnType<typeof Telemetry.span> | undefined;
+
+ const recordAuthority = (source: 'network' | 'local' | 'stale-fallback') => {
+ const span = Telemetry.span('graphql_cache.soup_authority');
+ span.setAttr('authority.source', source);
+ span.end();
+ };
+ const finishStaleFallback = (source: 'network' | 'local') => {
+ staleFallbackSpan?.setAttr('authority.resumed_by', source);
+ staleFallbackSpan?.end();
+ staleFallbackSpan = undefined;
+ };
createEffect(() => {
const host = getGraphqlSoupCacheHost();
if (!host) return;
- const unsubscribe = host.onCacheChanged(() => {
- setCacheRevision((revision) => revision + 1);
+ cacheGeneration += 1;
+ const invalidateGeneration = () => {
+ localRequest += 1;
+ setCurrentCacheRevision(undefined);
+ setNetworkAuthorityRevision(undefined);
+ setLocalProjection(undefined);
+ };
+ const observeCurrentRevision = () => {
+ const observedGeneration = cacheGeneration;
+ void host
+ .currentRevision()
+ .then((revision) => {
+ if (
+ observedGeneration === cacheGeneration &&
+ currentCacheRevision() === undefined
+ ) {
+ setCurrentCacheRevision(revision);
+ }
+ })
+ .catch(() => undefined);
+ };
+ const unsubscribeChanges = host.onCacheChanged((revision) => {
+ if (
+ networkAuthorityRevision() !== undefined &&
+ networkAuthorityRevision() !== revision &&
+ staleFallbackSpan === undefined
+ ) {
+ staleFallbackSpan = Telemetry.span('graphql_cache.soup_stale_fallback');
+ recordAuthority('stale-fallback');
+ }
+ setCurrentCacheRevision(revision);
+ });
+ const unsubscribeGeneration = host.onCacheGenerationChanged(() => {
+ const span = Telemetry.span('graphql_cache.engine_generation_changed');
+ span.end();
+ cacheGeneration += 1;
+ invalidateGeneration();
+ observeCurrentRevision();
+ });
+ observeCurrentRevision();
+ onCleanup(() => {
+ staleFallbackSpan?.end();
+ staleFallbackSpan = undefined;
+ cacheGeneration += 1;
+ unsubscribeChanges();
+ unsubscribeGeneration();
});
- onCleanup(unsubscribe);
});
createEffect(() => {
- cacheRevision();
- const requestId = ++localRequest;
- setLocalPlaceholder(undefined);
+ const revision = currentCacheRevision();
const input = firstPageInput();
const queryOptions = options();
const host = getGraphqlSoupCacheHost();
- if (!queryOptions.enabled || !input || !host || !('initial' in input))
+ const requestId = ++localRequest;
+ if (input !== previousInitialInput) {
+ previousInitialInput = input;
+ setLocalProjection(undefined);
+ }
+ if (
+ revision === undefined ||
+ networkAuthorityRevision() === revision ||
+ !queryOptions.enabled ||
+ !input ||
+ !host ||
+ !('initial' in input)
+ ) {
return;
+ }
const initial = input.initial;
if (!initial) return;
const filters = initial.filters ?? {};
@@ -118,44 +203,84 @@ export function createGraphqlSoupAstItemsQuery(
const sortDirection = initial.sortDirection ?? 'DESC';
const limit = initial.limit ?? 20;
- void host
- .entityFilter({ filters, sortMethod, sortDirection, limit })
- .then(async (result) => {
- if (result.kind !== 'complete' || requestId !== localRequest) return;
- const selected = await readRecordsByKeys(
- host,
- soupItemSelection,
- result.keys
- );
- if (
- requestId !== localRequest ||
- selected.length !== result.keys.length
- )
+ void (async () => {
+ const span = Telemetry.span('graphql_cache.soup_local_evaluation');
+ let expectedRevision = revision;
+ let retryCount = 0;
+ let discarded = false;
+ let outcome: 'success' | 'incomplete' | 'error' = 'incomplete';
+ try {
+ for (let attempt = 0; attempt < 3; attempt += 1) {
+ const result = await host.entityFilter({
+ filters,
+ sortMethod,
+ sortDirection,
+ limit,
+ });
+ if (result.kind !== 'complete') return;
+ if (requestId !== localRequest) {
+ discarded = true;
+ return;
+ }
+ const selected = await readRecordsByKeys(
+ host,
+ soupItemSelection,
+ result.keys
+ );
+ const latestRevision = await host.currentRevision();
+ if (requestId !== localRequest) {
+ discarded = true;
+ return;
+ }
+ if (
+ result.revision !== selected.revision ||
+ result.revision !== latestRevision ||
+ result.revision !== expectedRevision
+ ) {
+ discarded = true;
+ retryCount += 1;
+ expectedRevision = latestRevision;
+ setCurrentCacheRevision(latestRevision);
+ continue;
+ }
+ if (selected.records.length !== result.keys.length) return;
+ const items = selected.records.flatMap(({ record }) => {
+ const item = mapGraphqlSoupItem(record);
+ return item ? [item] : [];
+ });
+ if (items.length !== result.keys.length) return;
+ setLocalProjection({
+ revision: latestRevision,
+ optimistic: result.optimistic,
+ data: {
+ entities: mapSoupPageToEntityList(
+ { items, next_cursor: undefined },
+ {
+ instructionsIdQuery,
+ showSupportedForeignEntities:
+ queryOptions.showSupportedForeignEntities,
+ }
+ ),
+ groups: undefined,
+ },
+ });
+ outcome = 'success';
+ recordAuthority('local');
+ finishStaleFallback('local');
+ resetContinuationPages?.();
return;
- const items = selected.flatMap(({ record }) => {
- const item = mapGraphqlSoupItem(record);
- return item ? [item] : [];
- });
- if (items.length !== result.keys.length) return;
- setLocalPlaceholder({
- optimistic: result.optimistic,
- data: {
- entities: mapSoupPageToEntityList(
- { items, next_cursor: undefined },
- {
- instructionsIdQuery,
- showSupportedForeignEntities:
- queryOptions.showSupportedForeignEntities,
- }
- ),
- groups: undefined,
- },
- });
- })
- .catch(() => {
- // Unsupported, incomplete, validation, and storage failures all use
- // the already-running authoritative network request.
- });
+ }
+ } catch {
+ outcome = 'error';
+ // Unsupported, incomplete, validation, and storage failures retain
+ // the stale network/normalized-cache fallback already on screen.
+ } finally {
+ span.setAttr('evaluation.outcome', outcome);
+ span.setAttr('evaluation.retry_count', retryCount);
+ span.setAttr('evaluation.discarded', discarded);
+ span.end();
+ }
+ })();
});
const query = createUrqlInfiniteQuery<
@@ -185,6 +310,18 @@ export function createGraphqlSoupAstItemsQuery(
enabled: queryOptions.enabled && firstInput !== undefined,
requestPolicy: 'cache-and-network',
keepPreviousData: false,
+ onResult: (result, page) => {
+ if (page.pageIndex !== 0) return;
+ const metadata = normalizedCacheResultMetadata(result);
+ if (metadata?.source !== 'live-network' || !metadata.revision) return;
+ batch(() => {
+ setCurrentCacheRevision(metadata.revision);
+ setNetworkAuthorityRevision(metadata.revision);
+ setLocalProjection(undefined);
+ });
+ recordAuthority('network');
+ finishStaleFallback('network');
+ },
select: ({ pages }) => ({
entities: pages.flatMap((page) =>
mapSoupPageToEntityList(mapGraphqlSoupPage(page), {
@@ -197,6 +334,17 @@ export function createGraphqlSoupAstItemsQuery(
};
});
+ resetContinuationPages = query.resetToInitialPage;
+
+ const authoritativeLocalProjection = (): LocalProjection | undefined => {
+ const local = localProjection();
+ const revision = currentCacheRevision();
+ return local?.revision === revision ? local : undefined;
+ };
+ const networkIsAuthoritative = (): boolean =>
+ networkAuthorityRevision() !== undefined &&
+ networkAuthorityRevision() === currentCacheRevision();
+
const error = (): CombinedError | undefined => query.error ?? undefined;
createComputed(
on(error, (queryError) => {
@@ -208,23 +356,24 @@ export function createGraphqlSoupAstItemsQuery(
return {
data: () => {
- const local = localPlaceholder();
- return local?.optimistic ? local.data : (query.data ?? local?.data);
+ if (networkIsAuthoritative()) return query.data;
+ const local = authoritativeLocalProjection();
+ return local?.data ?? query.data ?? localProjection()?.data;
},
error,
isSupported,
isEnabled: () => query.isEnabled,
- isLoading: () => query.isLoading && localPlaceholder() === undefined,
+ isLoading: () =>
+ query.isLoading && authoritativeLocalProjection() === undefined,
isFetching: () => query.isFetching,
isFetchingNextPage: () => query.isFetchingNextPage,
- isPlaceholderData: () => {
- const local = localPlaceholder();
- return (
- local !== undefined && (query.data === undefined || local.optimistic)
- );
- },
+ isPlaceholderData: () =>
+ !networkIsAuthoritative() && authoritativeLocalProjection() !== undefined,
hasNextPage: () => query.hasNextPage,
fetchNextPage: async () => {
+ // Local predicate pagination is not revision-safe yet. Return to the
+ // stale server page chain before requesting its continuation cursor.
+ setLocalProjection(undefined);
await query.fetchNextPage();
},
resetToInitialPage: query.resetToInitialPage,
diff --git a/apps/web/tauri/graphql_cache_plugin/src/commands.rs b/apps/web/tauri/graphql_cache_plugin/src/commands.rs
index 4e4c91e22f..fb50f9ce94 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/commands.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/commands.rs
@@ -10,7 +10,8 @@
//! worker's `{ok: false, error}` responses.
use crate::engine::{
- ClaimedMutationWire, EngineHandle, EnqueueOptimisticMutationResultWire, ReadResultWire,
+ AffectedOperationsResultWire, ClaimedMutationWire, EngineHandle,
+ EnqueueOptimisticMutationResultWire, ReadResultWire, RecordSelectionResultWire,
WriteRegistration, WriteRequest, WriteResultWire,
};
use crate::{
@@ -19,7 +20,6 @@ use crate::{
use cache_core::entity_resolver::EntityResolver;
use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};
use cache_core::query_inspection::{CachedQueryInstance, CachedQueryVariant};
-use cache_core::record_selection::SelectedRecord;
use cache_core::search::{SearchPage, SearchRequest};
use cache_turso::TursoFileDatabase;
use serde::{Deserialize, Serialize};
@@ -77,6 +77,14 @@ pub async fn graphql_cache_init<R: Runtime>(
Ok(())
}
+/// Returns the current in-memory cache revision as a decimal string.
+#[tauri::command]
+pub async fn graphql_cache_current_revision(
+ state: State<'_, CacheState>,
+) -> Result<String, String> {
+ Ok(engine_handle(&state)?.current_revision().await.to_string())
+}
+
/// Attempts a cache read; registers `op_id` as active when given.
#[tauri::command]
pub async fn graphql_cache_read(
@@ -105,7 +113,7 @@ pub async fn graphql_cache_read_records_by_keys(
document: String,
fragment_name: String,
keys: Vec<String>,
-) -> Result<Vec<SelectedRecord>, String> {
+) -> Result<RecordSelectionResultWire, String> {
engine_handle(&state)?
.read_records_by_keys(document, fragment_name, keys)
.await
@@ -160,7 +168,7 @@ pub async fn graphql_cache_write<R: Runtime>(
})
.await?;
emit_ops_affected(&app, &result.affected_ops, &result.changed);
- emit_cache_changed(&app);
+ emit_cache_changed(&app, &result.revision);
Ok(result)
}
@@ -172,9 +180,14 @@ pub enum HydrationResultWire {
Data {
/// Projected GraphQL response data.
data: serde_json::Value,
+ /// Revision installed by the hydration write.
+ revision: String,
},
/// Every response field was cache-only.
- Void,
+ Void {
+ /// Revision installed by the hydration write.
+ revision: String,
+ },
}
/// Normalizes and stores a network response, broadcasts affected operations,
@@ -203,10 +216,15 @@ pub async fn graphql_cache_hydrate<R: Runtime>(
&result.write_result.affected_ops,
&result.write_result.changed,
);
- emit_cache_changed(&app);
+ emit_cache_changed(&app, &result.write_result.revision);
Ok(match result.data {
- Some(data) => HydrationResultWire::Data { data },
- None => HydrationResultWire::Void,
+ Some(data) => HydrationResultWire::Data {
+ data,
+ revision: result.write_result.revision,
+ },
+ None => HydrationResultWire::Void {
+ revision: result.write_result.revision,
+ },
})
}
@@ -245,7 +263,7 @@ pub async fn graphql_cache_enqueue_optimistic_mutation<R: Runtime>(
)
.await?;
emit_ops_affected(&app, &result.result.affected_ops, &result.result.changed);
- emit_cache_changed(&app);
+ emit_cache_changed(&app, &result.result.revision);
Ok(result)
}
@@ -352,7 +370,7 @@ pub async fn graphql_cache_commit_optimistic_write<R: Runtime>(
)
.await?;
emit_ops_affected(&app, &result.affected_ops, &result.changed);
- emit_cache_changed(&app);
+ emit_cache_changed(&app, &result.revision);
emit_mutation_settled(&app, settlement_transaction_id, "committed", None);
Ok(result)
}
@@ -372,7 +390,7 @@ pub async fn graphql_cache_rollback_optimistic_write<R: Runtime>(
.rollback_optimistic_write(transaction_id, lease_owner, lease_generation)
.await?;
emit_ops_affected(&app, &result.affected_ops, &result.changed);
- emit_cache_changed(&app);
+ emit_cache_changed(&app, &result.revision);
emit_mutation_settled(
&app,
settlement_transaction_id,
@@ -389,10 +407,10 @@ pub async fn graphql_cache_invalidate<R: Runtime>(
app: AppHandle<R>,
state: State<'_, CacheState>,
keys: Vec<String>,
-) -> Result<Vec<String>, String> {
+) -> Result<AffectedOperationsResultWire, String> {
let affected = engine_handle(&state)?.invalidate(keys.clone()).await?;
- emit_ops_affected(&app, &affected, &keys);
- emit_cache_changed(&app);
+ emit_ops_affected(&app, &affected.affected_ops, &keys);
+ emit_cache_changed(&app, &affected.revision);
Ok(affected)
}
@@ -403,9 +421,10 @@ pub async fn graphql_cache_delete_records<R: Runtime>(
app: AppHandle<R>,
state: State<'_, CacheState>,
keys: Vec<String>,
-) -> Result<Vec<String>, String> {
+) -> Result<AffectedOperationsResultWire, String> {
let affected = engine_handle(&state)?.delete_records(keys.clone()).await?;
- emit_ops_affected(&app, &affected, &keys);
+ emit_ops_affected(&app, &affected.affected_ops, &keys);
+ emit_cache_changed(&app, &affected.revision);
Ok(affected)
}
@@ -423,8 +442,8 @@ pub async fn graphql_cache_teardown(
pub async fn graphql_cache_clear<R: Runtime>(
app: AppHandle<R>,
state: State<'_, CacheState>,
-) -> Result<(), String> {
- engine_handle(&state)?.clear().await?;
- emit_cache_changed(&app);
- Ok(())
+) -> Result<String, String> {
+ let revision = engine_handle(&state)?.clear().await?.to_string();
+ emit_cache_changed(&app, &revision);
+ Ok(revision)
}
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine.rs b/apps/web/tauri/graphql_cache_plugin/src/engine.rs
index 951be2e1d4..8c8923d249 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine.rs
@@ -20,7 +20,8 @@ use cache_core::entity_resolver::EntityResolver;
use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};
use cache_core::query_inspection::{CachedQueryInstance, CachedQueryVariant, QueryInspection};
use cache_core::queue::{ClaimedMutation, MutationClaimRequest, MutationClaimToken};
-use cache_core::record_selection::RecordSelection;
+use cache_core::record_selection::{RecordSelection, SelectedRecord};
+use cache_core::revision::CacheRevision;
use cache_core::search::{SearchPage, SearchRequest};
use cache_core::value::EntityKey;
use cache_turso::{TursoStorage, TursoStorageCloseOutcome};
@@ -46,6 +47,8 @@ pub enum ReadResultWire {
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct WriteResultWire {
+ /// Effective-view revision installed by this logical mutation.
+ pub revision: String,
/// Entity keys whose records changed.
pub changed: Vec<String>,
/// Registered operation ids affected by the change (origin excluded).
@@ -66,6 +69,26 @@ pub struct HydrationWriteResultWire {
pub data: Option<serde_json::Value>,
}
+/// Revision-qualified normalized record selection result.
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RecordSelectionResultWire {
+ /// Revision observed by record selection.
+ pub revision: String,
+ /// Selected normalized records.
+ pub records: Vec<SelectedRecord>,
+}
+
+/// Revision-qualified affected operation ids.
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AffectedOperationsResultWire {
+ /// Revision installed by the invalidation or deletion.
+ pub revision: String,
+ /// Registered operation ids affected by the change.
+ pub affected_ops: Vec<String>,
+}
+
/// Result of durably enqueueing an optimistic mutation and attempting to
/// claim the strict queue head.
#[derive(Debug, Serialize)]
@@ -213,6 +236,7 @@ pub struct EngineHandle {
fn wire_write_result(ops: &OpInterner, result: WriteResult) -> WriteResultWire {
WriteResultWire {
+ revision: result.revision.to_string(),
changed: result
.changed
.into_iter()
@@ -267,6 +291,11 @@ impl EngineHandle {
}
}
+ /// Returns the current in-memory cache revision.
+ pub async fn current_revision(&self) -> CacheRevision {
+ self.inner.lock().await.engine.current_revision()
+ }
+
/// Cache read; registers `op_id` as active when given.
pub async fn read(
&self,
@@ -301,7 +330,7 @@ impl EngineHandle {
document: String,
fragment_name: String,
keys: Vec<String>,
- ) -> Result<Vec<cache_core::record_selection::SelectedRecord>, String> {
+ ) -> Result<RecordSelectionResultWire, String> {
let selection =
RecordSelection::parse(&document, &fragment_name).map_err(|error| error.to_string())?;
let keys: Vec<_> = keys.into_iter().map(|key| EntityKey(key.into())).collect();
@@ -311,6 +340,10 @@ impl EngineHandle {
.engine
.read_records_by_keys(&selection, &keys)
.await
+ .map(|result| RecordSelectionResultWire {
+ revision: result.revision.to_string(),
+ records: result.value,
+ })
.map_err(|error| error.to_string())
}
@@ -590,24 +623,38 @@ impl EngineHandle {
}
/// Evicts records by entity key; returns the affected registered op ids.
- pub async fn invalidate(&self, keys: Vec<String>) -> Result<Vec<String>, String> {
+ pub async fn invalidate(
+ &self,
+ keys: Vec<String>,
+ ) -> Result<AffectedOperationsResultWire, String> {
let keys: Vec<EntityKey<'static>> =
keys.into_iter().map(|key| EntityKey(key.into())).collect();
let mut state = self.inner.lock().await;
let EngineState { engine, ops } = &mut *state;
- let affected = engine.invalidate_keys(keys.iter());
- Ok(ops.names(affected))
+ let affected = engine
+ .invalidate_keys(keys.iter())
+ .map_err(|error| error.to_string())?;
+ Ok(AffectedOperationsResultWire {
+ revision: affected.revision.to_string(),
+ affected_ops: ops.names(affected.value),
+ })
}
/// Deletes stale records from durable and hot storage and returns the
/// registered operations that traversed them.
- pub async fn delete_records(&self, keys: Vec<String>) -> Result<Vec<String>, String> {
+ pub async fn delete_records(
+ &self,
+ keys: Vec<String>,
+ ) -> Result<AffectedOperationsResultWire, String> {
let keys: Vec<EntityKey<'static>> =
keys.into_iter().map(|key| EntityKey(key.into())).collect();
let mut state = self.inner.lock().await;
let EngineState { engine, ops } = &mut *state;
let affected = engine.delete_keys(&keys).await.map_err(|e| e.to_string())?;
- Ok(ops.names(affected))
+ Ok(AffectedOperationsResultWire {
+ revision: affected.revision.to_string(),
+ affected_ops: ops.names(affected.value),
+ })
}
/// Unregisters an operation (urql teardown).
@@ -621,7 +668,7 @@ impl EngineHandle {
}
/// Drops all cached state (logout).
- pub async fn clear(&self) -> Result<(), String> {
+ pub async fn clear(&self) -> Result<CacheRevision, String> {
let mut state = self.inner.lock().await;
state.engine.clear().await.map_err(|e| e.to_string())
}
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
index 489a7d7b1a..27d138a99d 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
@@ -211,7 +211,7 @@ fn explicit_key_selection_returns_native_cache_entities() {
))
.unwrap();
assert_eq!(
- records[0].record,
+ records.records[0].record,
serde_json::json!({"id": "doc-1", "name": "A note"})
);
}
@@ -458,7 +458,7 @@ fn invalidate_reports_dependent_ops() {
read(&handle, Some("client:1"));
let affected = block_on(handle.invalidate(written.changed)).unwrap();
- assert_eq!(affected, vec!["client:1".to_string()]);
+ assert_eq!(affected.affected_ops, vec!["client:1".to_string()]);
}
#[test]
diff --git a/apps/web/tauri/graphql_cache_plugin/src/lib.rs b/apps/web/tauri/graphql_cache_plugin/src/lib.rs
index 89015a7724..4a68c11000 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/lib.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/lib.rs
@@ -23,8 +23,9 @@ pub mod commands;
mod engine;
pub use engine::{
- ClaimedMutationWire, EngineHandle, EnqueueOptimisticMutationResultWire,
- InitialMutationClaimWire, ReadResultWire, WriteResultWire,
+ AffectedOperationsResultWire, ClaimedMutationWire, EngineHandle,
+ EnqueueOptimisticMutationResultWire, InitialMutationClaimWire, ReadResultWire,
+ RecordSelectionResultWire, WriteResultWire,
};
/// Broadcast event carrying [`OpsAffectedEvent`]: operations whose
@@ -53,7 +54,10 @@ pub struct OpsAffectedEvent {
/// Payload of [`CACHE_CHANGED_EVENT`].
#[derive(Clone, Debug, Serialize)]
#[serde(rename_all = "camelCase")]
-pub struct CacheChangedEvent {}
+pub struct CacheChangedEvent {
+ /// Effective-view revision installed by the logical mutation.
+ pub revision: String,
+}
#[derive(Clone, Debug, Serialize)]
#[serde(rename_all = "camelCase")]
@@ -101,8 +105,13 @@ fn emit_ops_affected<R: Runtime>(app: &AppHandle<R>, op_ids: &[String], keys: &[
.ok();
}
-fn emit_cache_changed<R: Runtime>(app: &AppHandle<R>) {
- app.emit(CACHE_CHANGED_EVENT, CacheChangedEvent {})
+fn emit_cache_changed<R: Runtime>(app: &AppHandle<R>, revision: &str) {
+ app.emit(
+ CACHE_CHANGED_EVENT,
+ CacheChangedEvent {
+ revision: revision.to_owned(),
+ },
+ )
.inspect_err(|e| tracing::error!(error=?e, "failed to emit graphql cache change event"))
.ok();
}
diff --git a/apps/web/tauri/src-tauri/src/lib.rs b/apps/web/tauri/src-tauri/src/lib.rs
index 5a155aba72..c5d0327261 100644
--- a/apps/web/tauri/src-tauri/src/lib.rs
+++ b/apps/web/tauri/src-tauri/src/lib.rs
@@ -251,6 +251,7 @@ pub fn run() {
.manage(IsIpad(is_ipad_device))
.invoke_handler(tauri::generate_handler![
graphql_cache_plugin::commands::graphql_cache_init,
+ graphql_cache_plugin::commands::graphql_cache_current_revision,
graphql_cache_plugin::commands::graphql_cache_read,
graphql_cache_plugin::commands::graphql_cache_read_records_by_keys,
graphql_cache_plugin::commands::graphql_cache_search,
diff --git a/crates/client/cache-core/src/engine.rs b/crates/client/cache-core/src/engine.rs
index 839baa9a71..4195cb30b9 100644
--- a/crates/client/cache-core/src/engine.rs
+++ b/crates/client/cache-core/src/engine.rs
@@ -2,6 +2,9 @@
//! and dependency tracking together behind the API the hosts (wasm worker /
//! Tauri) expose over RPC.
+#[cfg(test)]
+mod test;
+
use crate::denormalize::{
DenormalizeError, ReadOutcome, RecordSource, denormalize_record,
denormalize_with_entity_resolvers,
@@ -31,6 +34,7 @@ use crate::queue::{
use crate::record_selection::{
MAX_RECORD_SELECTION_KEYS, RecordSelection, RecordSelectionError, SelectedRecord,
};
+use crate::revision::{CacheRevision, Revisioned};
use crate::search::{
SearchCursor, SearchDocument, SearchError, SearchPage, SearchProfile, SearchRequest,
compare_recent, fuzzy_freshness_score, project_search_documents, validate_search_request,
@@ -78,6 +82,8 @@ pub enum EngineError<S: std::error::Error + 'static> {
InvalidOptimisticProjection(String),
#[error("storage: {0}")]
Storage(#[source] S),
+ #[error("cache revision overflow")]
+ RevisionOverflow,
}
/// Result of a cache read.
@@ -116,6 +122,8 @@ pub struct QueryRegistration<'a> {
/// Result of writing a network response.
#[derive(Debug)]
pub struct WriteResult {
+ /// Revision installed after this logical cache mutation.
+ pub revision: CacheRevision,
/// Records whose contents changed.
pub changed: BTreeSet<EntityKey<'static>>,
/// Active operations depending on changed records (host re-executes
@@ -222,6 +230,7 @@ pub const DEFAULT_HOT_CAPACITY: usize = 10_000;
pub struct Engine<S: Storage> {
storage: S,
+ revision: CacheRevision,
hot: LruCache<EntityKey<'static>, Record>,
docs: HashMap<String, Document>,
deps: DepIndex,
@@ -242,6 +251,7 @@ impl<S: Storage> Engine<S> {
pub fn with_capacity(storage: S, hot_capacity: usize) -> Self {
Engine {
storage,
+ revision: CacheRevision::ZERO,
hot: LruCache::new(NonZeroUsize::new(hot_capacity).expect("capacity > 0")),
docs: HashMap::new(),
deps: DepIndex::new(),
@@ -252,6 +262,34 @@ impl<S: Storage> Engine<S> {
}
}
+ /// Returns the current effective-view revision of this engine generation.
+ pub fn current_revision(&self) -> CacheRevision {
+ self.revision
+ }
+
+ fn ensure_revision_can_advance(&self) -> Result<(), EngineError<S::Error>> {
+ self.revision
+ .checked_successor()
+ .map(|_| ())
+ .ok_or(EngineError::RevisionOverflow)
+ }
+
+ fn advance_revision(&mut self) -> Result<CacheRevision, EngineError<S::Error>> {
+ let next = self
+ .revision
+ .checked_successor()
+ .ok_or(EngineError::RevisionOverflow)?;
+ self.revision = next;
+ Ok(next)
+ }
+
+ fn revisioned<T>(&self, value: T) -> Revisioned<T> {
+ Revisioned {
+ revision: self.revision,
+ value,
+ }
+ }
+
/// Hydrates durable optimistic layers before the first operation. Queue
/// order is the optimistic composition order. Relation recipes are
/// reconstructed against the durable base and preceding layers.
@@ -273,6 +311,7 @@ impl<S: Storage> Engine<S> {
/// storage changes the queue. Returns operations whose effective view
/// changed.
pub async fn refresh_optimistic_queue(&mut self) -> Result<WriteResult, EngineError<S::Error>> {
+ self.ensure_revision_can_advance()?;
let queued = self
.storage
.load_mutation_queue()
@@ -295,7 +334,9 @@ impl<S: Storage> Engine<S> {
.filter(|key| before_all.get(key) != after.get(key))
.collect();
let affected_ops = self.deps.ops_for_keys(changed.iter());
+ let revision = self.advance_revision()?;
Ok(WriteResult {
+ revision,
changed,
affected_ops,
reset: false,
@@ -549,7 +590,7 @@ impl<S: Storage> Engine<S> {
&mut self,
selection: &RecordSelection,
keys: &[EntityKey<'static>],
- ) -> Result<Vec<SelectedRecord>, EngineError<S::Error>> {
+ ) -> Result<Revisioned<Vec<SelectedRecord>>, EngineError<S::Error>> {
if keys.len() > MAX_RECORD_SELECTION_KEYS {
return Err(RecordSelectionError::TooManyKeys {
count: keys.len(),
@@ -571,7 +612,7 @@ impl<S: Storage> Engine<S> {
return Err(RecordSelectionError::InvalidKey.into());
}
if keys.is_empty() {
- return Ok(Vec::new());
+ return Ok(self.revisioned(Vec::new()));
}
self.hydrate_optimistic().await?;
@@ -601,14 +642,15 @@ impl<S: Storage> Engine<S> {
.project_record_batch(selection, candidates, &optimistic)
.await?;
let mut projected: HashMap<_, _> = projected.into_iter().collect();
- Ok(ordered_keys
+ let records = ordered_keys
.into_iter()
.filter_map(|record_key| {
projected
.remove(&record_key)
.map(|record| SelectedRecord { record_key, record })
})
- .collect())
+ .collect();
+ Ok(self.revisioned(records))
}
async fn project_record_batch(
@@ -935,6 +977,7 @@ impl<S: Storage> Engine<S> {
input: NetworkWrite<'_>,
projections: Vec<ProjectionMutation>,
) -> Result<WriteResult, EngineError<S::Error>> {
+ self.ensure_revision_can_advance()?;
let NetworkWrite {
query,
operation_name,
@@ -983,7 +1026,7 @@ impl<S: Storage> Engine<S> {
candidates.extend(updates.keys().cloned());
let bases_before = self.load_bases(&candidates).await?;
let before = effective_records(&bases_before, &self.optimistic, &candidates);
- let changed = self.persist_updates(updates, projections).await?;
+ let (changed, revision) = self.persist_updates(updates, projections).await?;
if !self.optimistic.is_empty() {
let queued = self
@@ -1021,6 +1064,7 @@ impl<S: Storage> Engine<S> {
}
}
Ok(WriteResult {
+ revision,
changed,
affected_ops,
reset,
@@ -1100,7 +1144,7 @@ impl<S: Storage> Engine<S> {
&mut self,
updates: RecordUpdates,
projections: Vec<ProjectionMutation>,
- ) -> Result<BTreeSet<EntityKey<'static>>, EngineError<S::Error>> {
+ ) -> Result<(BTreeSet<EntityKey<'static>>, CacheRevision), EngineError<S::Error>> {
// Load current values (hot tier, then storage) so merges detect real
// changes. Merges are staged in a plain map, NOT the LRU: a batch
// larger than the hot capacity would otherwise evict its own
@@ -1156,8 +1200,9 @@ impl<S: Storage> Engine<S> {
.put_batch_with_projections(to_persist.clone(), projections)
.await
.map_err(EngineError::Storage)?;
+ let revision = self.advance_revision()?;
self.update_loaded_search_catalogs(&to_persist);
- Ok(changed)
+ Ok((changed, revision))
}
/// Atomically enqueues a mutation together with its optimistic layer.
@@ -1179,6 +1224,7 @@ impl<S: Storage> Engine<S> {
input: BeginOptimisticWrite<'_>,
projection_mutations: Vec<OptimisticProjectionMutation>,
) -> Result<(OptimisticTransactionId, WriteResult), EngineError<S::Error>> {
+ self.ensure_revision_can_advance()?;
let BeginOptimisticWrite {
query,
operation_name,
@@ -1263,9 +1309,11 @@ impl<S: Storage> Engine<S> {
if let Some(origin) = origin_op {
affected_ops.remove(&origin);
}
+ let revision = self.advance_revision()?;
Ok((
id,
WriteResult {
+ revision,
changed,
affected_ops,
reset: false,
@@ -1380,6 +1428,7 @@ impl<S: Storage> Engine<S> {
data: &Json,
projections: Vec<ProjectionMutation>,
) -> Result<WriteResult, EngineError<S::Error>> {
+ self.ensure_revision_can_advance()?;
self.hydrate_optimistic().await?;
let index = self
.optimistic
@@ -1414,6 +1463,7 @@ impl<S: Storage> Engine<S> {
{
return Err(EngineError::StaleMutationClaim(transaction));
}
+ let revision = self.advance_revision()?;
self.update_loaded_search_catalogs(&entries);
for (key, record) in entries {
self.hot.put(key, record);
@@ -1438,6 +1488,7 @@ impl<S: Storage> Engine<S> {
.collect();
let affected_ops = self.deps.ops_for_keys(visible_changed.iter());
Ok(WriteResult {
+ revision,
changed: durable_changed,
affected_ops,
reset: false,
@@ -1452,6 +1503,7 @@ impl<S: Storage> Engine<S> {
transaction: OptimisticTransactionId,
claim: MutationClaimToken,
) -> Result<WriteResult, EngineError<S::Error>> {
+ self.ensure_revision_can_advance()?;
self.hydrate_optimistic().await?;
self.optimistic
.iter()
@@ -1468,6 +1520,7 @@ impl<S: Storage> Engine<S> {
{
return Err(EngineError::StaleMutationClaim(transaction));
}
+ let revision = self.advance_revision()?;
let queued = self
.storage
.load_mutation_queue()
@@ -1484,6 +1537,7 @@ impl<S: Storage> Engine<S> {
.collect();
let affected_ops = self.deps.ops_for_keys(visible_changed.iter());
Ok(WriteResult {
+ revision,
changed: BTreeSet::new(),
affected_ops,
reset: false,
@@ -1627,7 +1681,8 @@ impl<S: Storage> Engine<S> {
/// Reacts to a reset performed by *another* engine instance sharing the
/// same storage (cross-tab broadcast): drops all local in-memory state
/// and returns every local active operation for re-execution.
- pub fn external_reset(&mut self) -> BTreeSet<OpId> {
+ pub fn external_reset(&mut self) -> Result<Revisioned<BTreeSet<OpId>>, EngineError<S::Error>> {
+ self.ensure_revision_can_advance()?;
self.hot.clear();
self.docs.clear();
self.optimistic.clear();
@@ -1636,7 +1691,9 @@ impl<S: Storage> Engine<S> {
// durable queue, so both identity and optimism must re-hydrate.
self.optimistic_hydrated = false;
self.identity = IdentityState::NotHydrated;
- self.deps.all_ops()
+ let affected = self.deps.all_ops();
+ self.advance_revision()?;
+ Ok(self.revisioned(affected))
}
/// Unregisters an active operation (urql teardown).
@@ -1651,6 +1708,16 @@ impl<S: Storage> Engine<S> {
pub fn invalidate_keys<'k>(
&mut self,
keys: impl IntoIterator<Item = &'k EntityKey<'static>>,
+ ) -> Result<Revisioned<BTreeSet<OpId>>, EngineError<S::Error>> {
+ self.ensure_revision_can_advance()?;
+ let affected = self.invalidate_keys_inner(keys);
+ self.advance_revision()?;
+ Ok(self.revisioned(affected))
+ }
+
+ fn invalidate_keys_inner<'k>(
+ &mut self,
+ keys: impl IntoIterator<Item = &'k EntityKey<'static>>,
) -> BTreeSet<OpId> {
let mut affected = BTreeSet::new();
for key in keys {
@@ -1673,7 +1740,8 @@ impl<S: Storage> Engine<S> {
pub async fn delete_keys(
&mut self,
keys: &[EntityKey<'static>],
- ) -> Result<BTreeSet<OpId>, EngineError<S::Error>> {
+ ) -> Result<Revisioned<BTreeSet<OpId>>, EngineError<S::Error>> {
+ self.ensure_revision_can_advance()?;
let affected = self.deps.ops_for_keys(keys.iter());
self.storage
.delete_batch(keys)
@@ -1685,12 +1753,14 @@ impl<S: Storage> Engine<S> {
catalog.remove(key);
}
}
- Ok(affected)
+ self.advance_revision()?;
+ Ok(self.revisioned(affected))
}
/// Drops all cached state (for example, on logout), including any pending
/// optimistic layers.
- pub async fn clear(&mut self) -> Result<(), EngineError<S::Error>> {
+ pub async fn clear(&mut self) -> Result<CacheRevision, EngineError<S::Error>> {
+ self.ensure_revision_can_advance()?;
self.hot.clear();
self.optimistic.clear();
self.optimistic_hydrated = true;
@@ -1698,7 +1768,8 @@ impl<S: Storage> Engine<S> {
self.deps = DepIndex::new();
// The wipe below removes the binding record too.
self.identity = IdentityState::Missing;
- self.storage.clear().await.map_err(EngineError::Storage)
+ self.storage.clear().await.map_err(EngineError::Storage)?;
+ self.advance_revision()
}
pub fn active_ops(&self) -> usize {
@@ -1749,16 +1820,18 @@ impl<S: PredicateIndexStorage> Engine<S> {
entries: Vec<(EntityKey<'static>, Record)>,
projections: Vec<ProjectionMutation>,
) -> Result<WriteResult, EngineError<S::Error>> {
+ self.ensure_revision_can_advance()?;
let mut updates = RecordUpdates::new();
for (key, record) in entries {
updates.entry(key).or_default().merge(record);
}
- let changed = self.persist_updates(updates, projections).await?;
+ let (changed, revision) = self.persist_updates(updates, projections).await?;
let mut affected_ops = self.deps.ops_for_keys(changed.iter());
if let Some(origin_op) = origin_op {
affected_ops.remove(&origin_op);
}
Ok(WriteResult {
+ revision,
changed,
affected_ops,
reset: false,
@@ -1770,11 +1843,30 @@ impl<S: PredicateIndexStorage> Engine<S> {
pub async fn mark_projections_incomplete(
&mut self,
projections: Vec<ProjectionMutation>,
- ) -> Result<(), EngineError<S::Error>> {
+ ) -> Result<CacheRevision, EngineError<S::Error>> {
+ self.ensure_revision_can_advance()?;
self.storage
.put_batch_with_projections(Vec::new(), projections)
.await
- .map_err(EngineError::Storage)
+ .map_err(EngineError::Storage)?;
+ self.advance_revision()
+ }
+
+ /// Marks generic projections incomplete and invalidates normalized hot-tier records
+ /// as one externally observed logical view mutation.
+ pub async fn invalidate_keys_with_projections(
+ &mut self,
+ keys: &[EntityKey<'static>],
+ projections: Vec<ProjectionMutation>,
+ ) -> Result<Revisioned<BTreeSet<OpId>>, EngineError<S::Error>> {
+ self.ensure_revision_can_advance()?;
+ self.storage
+ .put_batch_with_projections(Vec::new(), projections)
+ .await
+ .map_err(EngineError::Storage)?;
+ let affected = self.invalidate_keys_inner(keys.iter());
+ self.advance_revision()?;
+ Ok(self.revisioned(affected))
}
/// Delete normalized records and generic projections in one storage transaction.
@@ -1782,7 +1874,8 @@ impl<S: PredicateIndexStorage> Engine<S> {
&mut self,
keys: &[EntityKey<'static>],
projection_keys: &[PredicateRecordKey],
- ) -> Result<BTreeSet<OpId>, EngineError<S::Error>> {
+ ) -> Result<Revisioned<BTreeSet<OpId>>, EngineError<S::Error>> {
+ self.ensure_revision_can_advance()?;
let affected = self.deps.ops_for_keys(keys.iter());
self.storage
.delete_batch_with_projections(keys, projection_keys)
@@ -1794,13 +1887,22 @@ impl<S: PredicateIndexStorage> Engine<S> {
catalog.remove(key);
}
}
- Ok(affected)
+ self.advance_revision()?;
+ Ok(self.revisioned(affected))
}
/// Execute a complete generic exact-index query over authoritative and optimistic projections.
pub async fn query_predicate_index(
&mut self,
query: &ValidatedIndexQuery,
+ ) -> Result<Revisioned<PredicateQueryResult>, EngineError<S::Error>> {
+ let value = self.query_predicate_index_value(query).await?;
+ Ok(self.revisioned(value))
+ }
+
+ async fn query_predicate_index_value(
+ &mut self,
+ query: &ValidatedIndexQuery,
) -> Result<PredicateQueryResult, EngineError<S::Error>> {
self.hydrate_optimistic().await?;
let projection_mutations = self
diff --git a/crates/client/cache-core/src/engine/test.rs b/crates/client/cache-core/src/engine/test.rs
new file mode 100644
index 0000000000..69c89cc64e
--- /dev/null
+++ b/crates/client/cache-core/src/engine/test.rs
@@ -0,0 +1,15 @@
+use super::*;
+use crate::store::InMemoryStorage;
+
+#[test]
+fn revision_overflow_is_rejected_without_mutating_storage() {
+ pollster::block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ engine.revision = u64::MAX.to_string().parse().unwrap();
+
+ let result = engine.clear().await;
+ assert!(matches!(result, Err(EngineError::RevisionOverflow)));
+ assert_eq!(engine.current_revision().to_string(), u64::MAX.to_string());
+ assert!(engine.storage().is_empty());
+ });
+}
diff --git a/crates/client/cache-core/src/lib.rs b/crates/client/cache-core/src/lib.rs
index 947c8fd461..c7ae9dfa71 100644
--- a/crates/client/cache-core/src/lib.rs
+++ b/crates/client/cache-core/src/lib.rs
@@ -16,6 +16,7 @@ pub mod query_inspection;
mod query_path;
pub mod queue;
pub mod record_selection;
+pub mod revision;
pub mod search;
pub mod store;
pub mod value;
diff --git a/crates/client/cache-core/src/revision.rs b/crates/client/cache-core/src/revision.rs
new file mode 100644
index 0000000000..4efa8c8fd0
--- /dev/null
+++ b/crates/client/cache-core/src/revision.rs
@@ -0,0 +1,83 @@
+//! In-memory cache revision values and revision-qualified observations.
+
+#[cfg(test)]
+mod test;
+
+use std::fmt;
+use std::ops::Deref;
+use std::str::FromStr;
+use thiserror::Error;
+
+/// Opaque revision of one live cache engine's effective view.
+///
+/// Revisions are meaningful only within one engine generation. Consumers
+/// should compare them for equality and must discard them when the engine is
+/// replaced.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct CacheRevision(u64);
+
+impl CacheRevision {
+ /// The initial revision of every newly created engine.
+ pub const ZERO: Self = Self(0);
+
+ pub(crate) fn checked_successor(self) -> Option<Self> {
+ self.0.checked_add(1).map(Self)
+ }
+}
+
+impl fmt::Display for CacheRevision {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ self.0.fmt(formatter)
+ }
+}
+
+/// Error returned when parsing a cache revision from its wire representation.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
+pub enum ParseCacheRevisionError {
+ /// The input was not a canonical unsigned decimal integer.
+ #[error("cache revision must be a canonical unsigned decimal integer")]
+ Invalid,
+ /// The input exceeded the unsigned 64-bit revision range.
+ #[error("cache revision exceeds the unsigned 64-bit range")]
+ Overflow,
+}
+
+impl FromStr for CacheRevision {
+ type Err = ParseCacheRevisionError;
+
+ fn from_str(value: &str) -> Result<Self, Self::Err> {
+ if value.is_empty()
+ || (value.len() > 1 && value.starts_with('0'))
+ || !value.bytes().all(|byte| byte.is_ascii_digit())
+ {
+ return Err(ParseCacheRevisionError::Invalid);
+ }
+ value
+ .parse::<u64>()
+ .map(Self)
+ .map_err(|_| ParseCacheRevisionError::Overflow)
+ }
+}
+
+/// A value observed from one exact cache-engine revision.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Revisioned<T> {
+ /// Revision installed in the engine when `value` was observed.
+ pub revision: CacheRevision,
+ /// The observed value.
+ pub value: T,
+}
+
+impl<T> Deref for Revisioned<T> {
+ type Target = T;
+
+ fn deref(&self) -> &Self::Target {
+ &self.value
+ }
+}
+
+impl<T: PartialEq> PartialEq<T> for Revisioned<T> {
+ fn eq(&self, other: &T) -> bool {
+ self.value.eq(other)
+ }
+}
diff --git a/crates/client/cache-core/src/revision/test.rs b/crates/client/cache-core/src/revision/test.rs
new file mode 100644
index 0000000000..3f73a75384
--- /dev/null
+++ b/crates/client/cache-core/src/revision/test.rs
@@ -0,0 +1,20 @@
+use super::*;
+
+#[test]
+fn decimal_wire_format_is_canonical_and_bounded() {
+ assert_eq!(CacheRevision::ZERO.to_string(), "0");
+ assert_eq!(
+ "18446744073709551615"
+ .parse::<CacheRevision>()
+ .unwrap()
+ .to_string(),
+ u64::MAX.to_string()
+ );
+
+ for invalid in ["", "-1", "+1", "01", " 1", "1.0", "18446744073709551616"] {
+ assert!(
+ invalid.parse::<CacheRevision>().is_err(),
+ "accepted {invalid:?}"
+ );
+ }
+}
diff --git a/crates/client/cache-core/tests/engine.rs b/crates/client/cache-core/tests/engine.rs
index 8756a6d83d..dc97e76359 100644
--- a/crates/client/cache-core/tests/engine.rs
+++ b/crates/client/cache-core/tests/engine.rs
@@ -2,6 +2,7 @@
//! storage, dependency-driven re-execution, teardown, clear.
use cache_core::engine::{Engine, NetworkWrite, QueryRegistration, ReadResult};
+use cache_core::revision::CacheRevision;
use cache_core::store::InMemoryStorage;
use pollster::block_on;
use serde_json::{Value as Json, json};
@@ -130,6 +131,72 @@ fn consuming_engine_returns_exclusively_owned_storage() {
assert!(storage.is_empty());
}
+#[test]
+fn revision_tracks_logical_mutations_only_within_one_engine_generation() {
+ block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ assert_eq!(engine.current_revision(), CacheRevision::ZERO);
+
+ let data = page(&[("doc-1", "A")]);
+ let first = engine
+ .write_query(None, QUERY, Some("Soup"), &vars(10), &data, None)
+ .await
+ .unwrap();
+ assert_eq!(first.revision.to_string(), "1");
+ assert_eq!(engine.current_revision(), first.revision);
+
+ engine
+ .read_query(None, QUERY, Some("Soup"), &vars(10))
+ .await
+ .unwrap();
+ assert_eq!(engine.current_revision(), first.revision);
+
+ // Conservative advancement: an idempotent logical write still makes
+ // older observations stale.
+ let second = engine
+ .write_query(None, QUERY, Some("Soup"), &vars(10), &data, None)
+ .await
+ .unwrap();
+ assert!(second.changed.is_empty());
+ assert_eq!(second.revision.to_string(), "2");
+
+ let storage = engine.storage().clone();
+ let mut replacement = Engine::new(storage);
+ assert_eq!(replacement.current_revision(), CacheRevision::ZERO);
+ assert!(matches!(
+ replacement
+ .read_query(None, QUERY, Some("Soup"), &vars(10))
+ .await
+ .unwrap(),
+ ReadResult::Hit { .. }
+ ));
+ assert_eq!(replacement.current_revision(), CacheRevision::ZERO);
+
+ let cleared = replacement.clear().await.unwrap();
+ assert_eq!(cleared.to_string(), "1");
+ assert_eq!(replacement.current_revision(), cleared);
+ });
+}
+
+#[test]
+fn failed_commands_do_not_advance_revision() {
+ block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ let result = engine
+ .write_query(
+ None,
+ "query Broken {",
+ Some("Broken"),
+ &serde_json::Map::new(),
+ &json!({}),
+ None,
+ )
+ .await;
+ assert!(result.is_err());
+ assert_eq!(engine.current_revision(), CacheRevision::ZERO);
+ });
+}
+
#[test]
fn miss_then_write_then_hit() {
block_on(async {
@@ -658,7 +725,7 @@ fn identity_witness_wipes_on_user_change() {
assert_eq!(data["user"]["id"], serde_json::json!("user-2"));
// external_reset drops local state and reports all local ops.
- let ops = engine.external_reset();
+ let ops = engine.external_reset().unwrap();
assert!(ops.contains(&1) && ops.contains(&2));
});
}
diff --git a/crates/client/cache-core/tests/optimistic.rs b/crates/client/cache-core/tests/optimistic.rs
index e65fd95459..c0e1f32fda 100644
--- a/crates/client/cache-core/tests/optimistic.rs
+++ b/crates/client/cache-core/tests/optimistic.rs
@@ -13,6 +13,7 @@ use cache_core::store::{InMemoryStorage, Storage};
use cache_core::value::{CacheValue, EntityKey, Record};
use pollster::block_on;
use serde_json::{Value as Json, json};
+use std::sync::atomic::{AtomicBool, Ordering};
const QUERY: &str = r#"
query Soup($input: SoupInput!) {
@@ -58,6 +59,7 @@ const PROPERTY_KEY: &str = "GraphqlProperty:prop-1";
struct ClaimFailingStorage {
inner: InMemoryStorage,
fail_next_claim: bool,
+ fail_next_queue_load: AtomicBool,
}
impl ClaimFailingStorage {
@@ -65,8 +67,21 @@ impl ClaimFailingStorage {
Self {
inner: InMemoryStorage::new(),
fail_next_claim: true,
+ fail_next_queue_load: AtomicBool::new(false),
}
}
+
+ fn reconciliation_failing() -> Self {
+ Self {
+ inner: InMemoryStorage::new(),
+ fail_next_claim: false,
+ fail_next_queue_load: AtomicBool::new(false),
+ }
+ }
+
+ fn fail_next_queue_load(&self) {
+ self.fail_next_queue_load.store(true, Ordering::Relaxed);
+ }
}
impl Storage for ClaimFailingStorage {
@@ -109,6 +124,11 @@ impl Storage for ClaimFailingStorage {
}
async fn load_mutation_queue(&self) -> Result<Vec<QueuedMutation>, Self::Error> {
+ if self.fail_next_queue_load.swap(false, Ordering::Relaxed) {
+ return Err(std::io::Error::other(
+ "injected reconciliation queue load failure",
+ ));
+ }
Ok(self.inner.load_mutation_queue().await.unwrap())
}
@@ -254,6 +274,53 @@ async fn engine_with_base(display_name: &str, value: &str) -> Engine<InMemorySto
engine
}
+async fn reconciliation_engine() -> (Engine<ClaimFailingStorage>, MutationId) {
+ let mut engine = Engine::new(ClaimFailingStorage::reconciliation_failing());
+ engine
+ .write_query(
+ None,
+ QUERY,
+ Some("Soup"),
+ &query_vars(),
+ &soup_page("Status", "todo"),
+ None,
+ )
+ .await
+ .unwrap();
+ let (transaction, _) = engine
+ .begin_optimistic_write(
+ None,
+ BeginOptimisticWrite {
+ query: MUTATION,
+ operation_name: Some("SetEntityProperty"),
+ variables: &mutation_vars("doing"),
+ data: &mutation_response("Status", "doing"),
+ link_patches: &[],
+ revalidations: &[],
+ created_at_ms: 123,
+ },
+ )
+ .await
+ .unwrap();
+ (engine, transaction)
+}
+
+async fn claim_reconciliation_head(engine: &mut Engine<ClaimFailingStorage>) -> MutationClaimToken {
+ let claimed = engine
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner".into(),
+ now_ms: 123,
+ lease_expires_at_ms: 1_123,
+ })
+ .await
+ .unwrap()
+ .expect("queue head");
+ MutationClaimToken {
+ owner: "runner".into(),
+ generation: claimed.lease_generation,
+ }
+}
+
async fn read_hit(engine: &mut Engine<InMemoryStorage>, op: Option<u64>) -> Json {
match engine
.read_query(op, QUERY, Some("Soup"), &query_vars())
@@ -529,6 +596,11 @@ fn claim_failure_after_enqueue_preserves_one_durable_visible_mutation() {
.await
.unwrap();
+ assert_eq!(
+ result.write_result.revision,
+ engine.current_revision(),
+ "the failed lease claim must not add a second revision"
+ );
assert!(matches!(
result.initial_claim,
InitialClaimOutcome::Failed(EngineError::Storage(ref error))
@@ -550,6 +622,63 @@ fn claim_failure_after_enqueue_preserves_one_durable_visible_mutation() {
});
}
+#[test]
+fn durable_mutations_advance_revision_before_reconciliation() {
+ block_on(async {
+ let (mut write_engine, _) = reconciliation_engine().await;
+ write_engine.storage().fail_next_queue_load();
+ let write_result = write_engine
+ .write_query(
+ None,
+ QUERY,
+ Some("Soup"),
+ &query_vars(),
+ &soup_page("Status (server)", "done"),
+ None,
+ )
+ .await;
+ assert!(matches!(
+ write_result,
+ Err(EngineError::Storage(ref error))
+ if error.to_string() == "injected reconciliation queue load failure"
+ ));
+ assert_eq!(write_engine.current_revision().to_string(), "3");
+
+ let (mut commit_engine, transaction) = reconciliation_engine().await;
+ let claim = claim_reconciliation_head(&mut commit_engine).await;
+ commit_engine.storage().fail_next_queue_load();
+ let commit_result = commit_engine
+ .commit_optimistic_write(
+ transaction,
+ claim,
+ MUTATION,
+ Some("SetEntityProperty"),
+ &mutation_vars("done"),
+ &mutation_response("Status (server)", "done"),
+ )
+ .await;
+ assert!(matches!(
+ commit_result,
+ Err(EngineError::Storage(ref error))
+ if error.to_string() == "injected reconciliation queue load failure"
+ ));
+ assert_eq!(commit_engine.current_revision().to_string(), "3");
+
+ let (mut rollback_engine, transaction) = reconciliation_engine().await;
+ let claim = claim_reconciliation_head(&mut rollback_engine).await;
+ rollback_engine.storage().fail_next_queue_load();
+ let rollback_result = rollback_engine
+ .rollback_optimistic_write(transaction, claim)
+ .await;
+ assert!(matches!(
+ rollback_result,
+ Err(EngineError::Storage(ref error))
+ if error.to_string() == "injected reconciliation queue load failure"
+ ));
+ assert_eq!(rollback_engine.current_revision().to_string(), "3");
+ });
+}
+
#[test]
fn claimed_success_atomically_commits_real_response() {
block_on(async {
@@ -732,6 +861,7 @@ fn stale_claim_cannot_settle_mutation() {
)
.await
.unwrap();
+ let revision_before_stale_settlement = engine.current_revision();
let error = engine
.rollback_optimistic_write(
transaction,
@@ -743,6 +873,7 @@ fn stale_claim_cannot_settle_mutation() {
.await
.unwrap_err();
assert!(matches!(error, EngineError::StaleMutationClaim(id) if id == transaction));
+ assert_eq!(engine.current_revision(), revision_before_stale_settlement);
assert_eq!(
engine.storage().load_mutation_queue().await.unwrap().len(),
1
diff --git a/crates/client/cache-core/tests/predicate.rs b/crates/client/cache-core/tests/predicate.rs
index 37dda5dd9b..aaaff82ef9 100644
--- a/crates/client/cache-core/tests/predicate.rs
+++ b/crates/client/cache-core/tests/predicate.rs
@@ -147,13 +147,12 @@ fn replacement_removes_stale_facts_and_incomplete_states_fall_back() {
)
.await
.unwrap();
- assert_eq!(
- engine
- .query_predicate_index(&query("owner-1"))
- .await
- .unwrap(),
- PredicateQueryResult::Complete(vec![record_key()])
- );
+ let observed = engine
+ .query_predicate_index(&query("owner-1"))
+ .await
+ .unwrap();
+ assert_eq!(observed.revision, engine.current_revision());
+ assert_eq!(observed, PredicateQueryResult::Complete(vec![record_key()]));
engine
.put_records_with_projections(
diff --git a/crates/client/cache-core/tests/record_selection.rs b/crates/client/cache-core/tests/record_selection.rs
index 263a4e6fe6..fb4f287f04 100644
--- a/crates/client/cache-core/tests/record_selection.rs
+++ b/crates/client/cache-core/tests/record_selection.rs
@@ -101,6 +101,8 @@ fn projects_cold_links_and_skips_incomplete_explicit_keys() {
)
.await
.unwrap();
+ assert_eq!(selected.revision, engine.current_revision());
+ assert_eq!(selected.revision.to_string(), "0");
assert_eq!(selected.len(), 2);
assert_eq!(selected[0].record["documentId"], json!("a"));
assert_eq!(
diff --git a/crates/client/cache-wasm/src/shell.rs b/crates/client/cache-wasm/src/shell.rs
index 0bc7990978..f2b8854221 100644
--- a/crates/client/cache-wasm/src/shell.rs
+++ b/crates/client/cache-wasm/src/shell.rs
@@ -3,7 +3,7 @@ use cache_core::codec::cache_database_name;
use cache_core::deps::OpId;
use cache_core::engine::{
BeginOptimisticWrite, Engine, EngineError, InitialClaimOutcome, NetworkWrite,
- QueryRegistration, ReadResult,
+ QueryRegistration, ReadResult, WriteResult,
};
use cache_core::entity_resolver::EntityResolver;
use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};
@@ -140,6 +140,7 @@ struct JsQueryRegistration {
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct JsWriteResult {
+ revision: String,
changed: Vec<String>,
affected_ops: Vec<String>,
reset: bool,
@@ -149,6 +150,7 @@ struct JsWriteResult {
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct JsHydrationWriteResult {
+ revision: String,
changed: Vec<String>,
affected_ops: Vec<String>,
reset: bool,
@@ -165,6 +167,7 @@ struct JsInspectionPathSegment {
#[serde(rename_all = "camelCase")]
struct JsEnqueueOptimisticMutationResult {
transaction_id: String,
+ revision: String,
changed: Vec<String>,
affected_ops: Vec<String>,
reset: bool,
@@ -268,9 +271,48 @@ struct JsEntityFilterRequest {
#[derive(Serialize)]
#[serde(tag = "kind", rename_all = "kebab-case")]
enum JsEntityFilterResult {
- Complete { keys: Vec<String>, optimistic: bool },
+ Complete {
+ revision: String,
+ keys: Vec<String>,
+ optimistic: bool,
+ },
Unsupported,
- Incomplete,
+ Incomplete {
+ revision: String,
+ },
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct JsRecordSelectionResult {
+ revision: String,
+ records: Vec<cache_core::record_selection::SelectedRecord>,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct JsAffectedOperationsResult {
+ revision: String,
+ affected_ops: Vec<String>,
+}
+
+#[derive(Serialize)]
+struct JsRevisionResult {
+ revision: String,
+}
+
+fn js_write_result(result: WriteResult, ops: &OpInterner) -> JsWriteResult {
+ JsWriteResult {
+ revision: result.revision.to_string(),
+ changed: result
+ .changed
+ .into_iter()
+ .map(|key| key.0.into_owned())
+ .collect(),
+ affected_ops: ops.names(result.affected_ops),
+ reset: result.reset,
+ revalidations: result.revalidations,
+ }
}
struct CacheState {
@@ -737,6 +779,17 @@ impl CacheEngine {
})
}
+ /// Returns the current in-memory cache revision as an unsigned decimal string.
+ #[wasm_bindgen(js_name = currentRevision)]
+ pub fn current_revision(&self) -> js_sys::Promise {
+ let state = self.state.clone();
+ future_to_promise(async move {
+ let mut state = state.lock().await;
+ let revision = state.engine_mut()?.current_revision();
+ Ok(JsValue::from_str(&revision.to_string()))
+ })
+ }
+
/// Returns the opaque identity bound to this cache, or `null` when no
/// identity-bearing response has been stored yet.
#[wasm_bindgen(js_name = boundIdentity)]
@@ -809,7 +862,10 @@ impl CacheEngine {
.read_records_by_keys(&selection, &keys)
.await;
let records = state.engine_result(result)?;
- to_js(&records)
+ to_js(&JsRecordSelectionResult {
+ revision: records.revision.to_string(),
+ records: records.value,
+ })
})
}
@@ -848,8 +904,11 @@ impl CacheEngine {
SoupFilterCompileOutcome::Unsupported => JsEntityFilterResult::Unsupported,
SoupFilterCompileOutcome::Supported(query) => {
let result = state.engine_mut()?.query_predicate_index(&query).await;
- match state.engine_result(result)? {
+ let result = state.engine_result(result)?;
+ let revision = result.revision.to_string();
+ match result.value {
PredicateQueryResult::Complete(keys) => JsEntityFilterResult::Complete {
+ revision,
keys: keys
.into_iter()
.map(|key| key.as_str().to_owned())
@@ -857,13 +916,16 @@ impl CacheEngine {
optimistic: false,
},
PredicateQueryResult::Optimistic(keys) => JsEntityFilterResult::Complete {
+ revision,
keys: keys
.into_iter()
.map(|key| key.as_str().to_owned())
.collect(),
optimistic: true,
},
- PredicateQueryResult::Incomplete => JsEntityFilterResult::Incomplete,
+ PredicateQueryResult::Incomplete => {
+ JsEntityFilterResult::Incomplete { revision }
+ }
}
}
};
@@ -925,16 +987,7 @@ impl CacheEngine {
)
.await;
let result = state.engine_result(result)?;
- to_js(&JsWriteResult {
- changed: result
- .changed
- .into_iter()
- .map(|key| key.0.into_owned())
- .collect(),
- affected_ops: ops.borrow().names(result.affected_ops),
- reset: result.reset,
- revalidations: result.revalidations,
- })
+ to_js(&js_write_result(result, &ops.borrow()))
})
}
@@ -970,6 +1023,7 @@ impl CacheEngine {
.await;
let result = state.engine_result(result)?;
to_js(&JsHydrationWriteResult {
+ revision: result.write_result.revision.to_string(),
changed: result
.write_result
.changed
@@ -1055,6 +1109,7 @@ impl CacheEngine {
};
to_js(&JsEnqueueOptimisticMutationResult {
transaction_id: result.transaction_id.to_string(),
+ revision: result.write_result.revision.to_string(),
changed: result
.write_result
.changed
@@ -1207,16 +1262,7 @@ impl CacheEngine {
)
.await;
let result = state.engine_result(result)?;
- to_js(&JsWriteResult {
- changed: result
- .changed
- .into_iter()
- .map(|key| key.0.into_owned())
- .collect(),
- affected_ops: ops.borrow().names(result.affected_ops),
- reset: result.reset,
- revalidations: result.revalidations,
- })
+ to_js(&js_write_result(result, &ops.borrow()))
})
}
@@ -1244,16 +1290,7 @@ impl CacheEngine {
.rollback_optimistic_write(transaction, claim)
.await;
let result = state.engine_result(result)?;
- to_js(&JsWriteResult {
- changed: result
- .changed
- .into_iter()
- .map(|key| key.0.into_owned())
- .collect(),
- affected_ops: ops.borrow().names(result.affected_ops),
- reset: result.reset,
- revalidations: result.revalidations,
- })
+ to_js(&js_write_result(result, &ops.borrow()))
})
}
@@ -1268,17 +1305,17 @@ impl CacheEngine {
let mut state = state.lock().await;
state.ensure_callable()?;
let projections = dirty_projection_mutations(&keys);
- if !projections.is_empty() {
- let result = state
- .engine_mut()?
- .mark_projections_incomplete(projections)
- .await;
- state.engine_result(result)?;
- }
let keys: Vec<EntityKey<'static>> =
keys.into_iter().map(|key| EntityKey(key.into())).collect();
- let affected = state.engine_mut()?.invalidate_keys(keys.iter());
- to_js(&ops.borrow().names(affected))
+ let result = state
+ .engine_mut()?
+ .invalidate_keys_with_projections(&keys, projections)
+ .await;
+ let affected = state.engine_result(result)?;
+ to_js(&JsAffectedOperationsResult {
+ revision: affected.revision.to_string(),
+ affected_ops: ops.borrow().names(affected.value),
+ })
})
}
@@ -1302,7 +1339,10 @@ impl CacheEngine {
.delete_keys_with_projections(&keys, &projection_keys)
.await;
let affected = state.engine_result(result)?;
- to_js(&ops.borrow().names(affected))
+ to_js(&JsAffectedOperationsResult {
+ revision: affected.revision.to_string(),
+ affected_ops: ops.borrow().names(affected.value),
+ })
})
}
@@ -1316,16 +1356,7 @@ impl CacheEngine {
let mut state = state.lock().await;
let result = state.engine_mut()?.refresh_optimistic_queue().await;
let result = state.engine_result(result)?;
- to_js(&JsWriteResult {
- changed: result
- .changed
- .into_iter()
- .map(|key| key.0.into_owned())
- .collect(),
- affected_ops: ops.borrow().names(result.affected_ops),
- reset: result.reset,
- revalidations: result.revalidations,
- })
+ to_js(&js_write_result(result, &ops.borrow()))
})
}
@@ -1338,8 +1369,12 @@ impl CacheEngine {
let ops = self.ops.clone();
future_to_promise(async move {
let mut state = state.lock().await;
- let affected = state.engine_mut()?.external_reset();
- to_js(&ops.borrow().names(affected))
+ let result = state.engine_mut()?.external_reset();
+ let affected = state.engine_result(result)?;
+ to_js(&JsAffectedOperationsResult {
+ revision: affected.revision.to_string(),
+ affected_ops: ops.borrow().names(affected.value),
+ })
})
}
@@ -1364,8 +1399,10 @@ impl CacheEngine {
future_to_promise(async move {
let mut state = state.lock().await;
let result = state.engine_mut()?.clear().await;
- state.engine_result(result)?;
- Ok(JsValue::UNDEFINED)
+ let revision = state.engine_result(result)?;
+ to_js(&JsRevisionResult {
+ revision: revision.to_string(),
+ })
})
}
diff --git a/crates/client/cache-wasm/src/shell/test.rs b/crates/client/cache-wasm/src/shell/test.rs
index fef6a162b6..9bb47bfbe0 100644
--- a/crates/client/cache-wasm/src/shell/test.rs
+++ b/crates/client/cache-wasm/src/shell/test.rs
@@ -30,10 +30,36 @@ const PROPERTY_MUTATION: &str = r#"mutation SetEntityProperty($input: SetEntityP
setEntityProperty(input: $input) { id displayName }
}"#;
+const SOUP_UPDATES_SUBSCRIPTION: &str = r#"subscription SoupUpdates {
+ soupUpdates {
+ __typename
+ ... on SoupUpdated {
+ item {
+ __typename
+ id
+ displayName
+ ... on GraphqlSoupDocument {
+ ownerId
+ projectId
+ fileType
+ createdAt
+ updatedAt
+ }
+ }
+ }
+ }
+}"#;
+
const RECORD_FRAGMENT: &str = r#"fragment CachedDocument on GraphqlSoupDocument {
id
}"#;
+const REALTIME_DOCUMENT_FRAGMENT: &str = r#"fragment RealtimeDocument on GraphqlSoupDocument {
+ id
+ displayName
+ ownerId
+}"#;
+
fn js(json: serde_json::Value) -> JsValue {
use serde::Serialize;
json.serialize(&serde_wasm_bindgen::Serializer::json_compatible())
@@ -126,6 +152,45 @@ fn mutation_variables() -> serde_json::Value {
}})
}
+fn realtime_document_data(document_id: &str) -> serde_json::Value {
+ serde_json::json!({
+ "soupUpdates": [{
+ "__typename": "SoupUpdated",
+ "item": {
+ "__typename": "GraphqlSoupDocument",
+ "id": document_id,
+ "displayName": "Realtime document",
+ "ownerId": "macro|[email protected]",
+ "projectId": null,
+ "fileType": "md",
+ "createdAt": "2026-01-01T00:00:00.000Z",
+ "updatedAt": "2026-01-02T00:00:00.000Z"
+ }
+ }]
+ })
+}
+
+fn exact_document_filter(document_id: &str) -> serde_json::Value {
+ const NIL_ID: &str = "00000000-0000-0000-0000-000000000000";
+ serde_json::json!({
+ "filters": {
+ "calendarEventFilter": { "literal": { "id": NIL_ID } },
+ "documentFilter": { "literal": { "id": document_id } },
+ "projectFilter": { "literal": { "projectIdSelf": NIL_ID } },
+ "chatFilter": { "literal": { "chatId": NIL_ID } },
+ "emailFilter": { "tree": { "literal": { "threadId": NIL_ID } } },
+ "channelFilter": { "literal": { "channelId": NIL_ID } },
+ "channelThreadFilter": { "literal": { "threadId": NIL_ID } },
+ "callFilter": { "literal": { "callId": NIL_ID } },
+ "crmCompanyFilter": { "literal": { "id": NIL_ID } },
+ "foreignEntityFilter": { "literal": { "id": NIL_ID } }
+ },
+ "sortMethod": "UPDATED_AT",
+ "sortDirection": "DESC",
+ "limit": 20
+ })
+}
+
async fn fresh_engine(scope: &str) -> CacheEngine {
destroy_cache(scope.into())
.await
@@ -253,6 +318,54 @@ async fn operations_preserve_js_boundary_interner_and_ordering() {
close_and_destroy(&engine, SCOPE).await;
}
+#[wasm_bindgen_test(async)]
+async fn realtime_soup_items_are_locally_filterable_without_a_query_fetch() {
+ const SCOPE: &str = "cache-wasm-realtime-local-filter";
+ const DOCUMENT_ID: &str = "00000000-0000-0000-0000-000000000001";
+ let engine = fresh_engine(SCOPE).await;
+
+ resolved(engine.write_query(
+ write_context(None),
+ SOUP_UPDATES_SUBSCRIPTION.into(),
+ Some("SoupUpdates".into()),
+ js(serde_json::json!({})),
+ js(realtime_document_data(DOCUMENT_ID)),
+ None,
+ ))
+ .await;
+
+ // This asks only the local predicate index; no Soup query response has
+ // been fetched or written before the realtime item is returned.
+ let filtered: serde_json::Value =
+ from_js(resolved(engine.entity_filter(js(exact_document_filter(DOCUMENT_ID)))).await);
+ assert_eq!(
+ filtered,
+ serde_json::json!({
+ "kind": "complete",
+ "revision": "1",
+ "keys": [format!("GraphqlSoupDocument:{DOCUMENT_ID}")],
+ "optimistic": false
+ })
+ );
+
+ let selected: serde_json::Value = from_js(
+ resolved(engine.read_records_by_keys(
+ REALTIME_DOCUMENT_FRAGMENT.into(),
+ "RealtimeDocument".into(),
+ js(filtered["keys"].clone()),
+ ))
+ .await,
+ );
+ assert_eq!(selected["revision"], "1");
+ assert_eq!(selected["records"][0]["record"]["id"], DOCUMENT_ID);
+ assert_eq!(
+ selected["records"][0]["record"]["displayName"],
+ "Realtime document"
+ );
+
+ close_and_destroy(&engine, SCOPE).await;
+}
+
#[wasm_bindgen_test(async)]
async fn entity_resolvers_cross_the_js_boundary() {
const SCOPE: &str = "cache-wasm-wp07-entity-resolver";