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/persist optimitic records (#4826)

Sean Ayeeb4d49390267
diff --git a/apps/web/docs/graphql-normalized-cache-plan.md b/apps/web/docs/graphql-normalized-cache-plan.md
index cb5a72cefe..65fddc06b7 100644
--- a/apps/web/docs/graphql-normalized-cache-plan.md
+++ b/apps/web/docs/graphql-normalized-cache-plan.md
@@ -65,8 +65,8 @@ entire cache in browser memory. With 10s of thousands of cached objects
opaque session tag compared against the binding stored in the same
database (`__meta:identity`), so compare-and-wipe is atomic with the
triggering write (no stale-in-flight-write races). A mismatch wipes and
- rebinds (“silent restart”), all active operations re-execute, and other
- engine instances get a `reset` broadcast. Eager path: clear on logout.
+ rebinds (“silent restart”) and all active operations re-execute. Eager
+ path: clear on logout.
Discard on schema/format mismatch (cache is disposable, rebuild from
network).
@@ -78,9 +78,11 @@ entire cache in browser memory. With 10s of thousands of cached objects
`GraphqlSoupChannelMessage.id`); the build fails on malformed shapes.
12. **Native-testable core** — the Rust engine is a pure crate (`cargo test`,
no wasm) with storage/clock behind traits.
-13. **Future** — mutations don't exist in the schema yet; design leaves room
- for optimistic updates, mutation-driven invalidation, and an offline
- mutation queue, but none of that is in scope now.
+13. **Durable optimistic mutations** — optimistic GraphQL mutations are
+ persisted with their replay request, restored across restarts, and applied
+ strictly in enqueue order. Retryability is decided by an exchange callback;
+ retryable failures retain their optimistic layer. Each queued network
+ attempt has a one-minute timeout, comfortably inside its five-minute lease.
### Open questions
@@ -125,11 +127,11 @@ One Rust core engine, two hosts:
│ module in a worker; │ │ Tauri host process (Rust); │
│ IndexedDB via the `idb` crate │ │ no webview storage ever │
│ (storage entirely in Rust) │ │ • naturally shared across ALL │
-│ • SharedWorker where available│ │ webviews/windows │
-│ (single engine instance) │ │ • SQLite (or fs) storage │
-│ • fallback: worker-per-tab + │ │ • glue over invoke + channels/ │
-│ Web Locks write serializing │ │ events │
-│ + BroadcastChannel fanout │ │ │
+│ • SharedWorker: one engine │ │ webviews/windows │
+│ shared by every browser tab │ │ • SQLite (or fs) storage │
+│ • no SharedWorker: storage- │ │ • glue over invoke + channels/ │
+│ free no-op cache host │ │ events │
+│ │ │ │
└───────────────┬───────────────┘ └────────────────┬────────────────┘
└──────────────────┬──────────────────────┘
▼
@@ -156,8 +158,9 @@ One Rust core engine, two hosts:
### 4.2 Multi-consumer strategy (browser only)
**Decision: IndexedDB-backed persistence via the [`idb`
-crate](https://docs.rs/idb/latest/idb/), engine in a worker that may or may
-not be a SharedWorker. OPFS is dropped.**
+crate](https://docs.rs/idb/latest/idb/), with one engine in a SharedWorker.
+Browsers without SharedWorker support use a storage-free no-op cache host.
+OPFS is dropped.**
Rationale (see Appendix A):
@@ -167,32 +170,27 @@ Rationale (see Appendix A):
- IDB point-reads measured *faster* than OPFS sync 4 KiB reads in the probe
(0.35 ms vs 2 ms avg), and batched writes (119 ms / 1000 records / txn)
are fine for our write rates.
-- IDB is available in window, dedicated workers and SharedWorker, and
- tolerates concurrent instances — so the same backend works in every
- topology.
+- IDB is available in SharedWorker on supported browsers.
- Using the `idb` Rust crate keeps the entire storage layer inside the wasm
module (no JS-callback storage shim; JS glue is transport only).
Topology:
-- **Preferred: SharedWorker** hosting the wasm engine — single instance,
- no election, trivial routing. (Chromium probe: IDB, Web Locks and
- BroadcastChannel all available in SharedWorker.)
-- **Fallback (no SharedWorker): dedicated worker per tab**, each with its
- own engine instance over the same IDB database. Web Locks serialize
- writes/GC (single writer at a time); BroadcastChannel broadcasts
- changed-keys so every tab's exchange re-executes affected operations.
- Cost: N copies of the hot tier — acceptable.
+- **Browser: SharedWorker** hosting the wasm engine — one instance across
+ tabs, no election or cross-engine coordination.
+- **No SharedWorker:** return a no-op `CacheHost` that always misses, ignores
+ writes, and does not initialize wasm or persistent storage. Mutations pass
+ through the exchange without durable optimism.
- Selection at startup: Tauri detection (`isTauri`) → native transport;
- otherwise `typeof SharedWorker === 'function'` picks the worker kind. All
- paths sit behind the same `Storage` trait and `CacheHost` RPC interface.
+ otherwise SharedWorker support selects either the browser cache or no-op
+ host. All paths sit behind the same `CacheHost` interface.
### 4.3 Storage backends
| Backend | Host | Notes |
|------------|--------------|------------------------------------------------|
-| SQLite | Tauri native | records + links + meta tables; WAL mode |
-| IndexedDB | browser | via the `idb` crate inside the wasm module; one DB, object stores for records / operation roots / meta |
+| SQLite | Tauri native | records, mutation queue, optimistic layers, and meta; WAL mode |
+| IndexedDB | browser | via the `idb` crate; stable per-scope DB with object stores for records, mutation queue, optimistic layers, and meta |
`Storage` trait (async): `get_batch`, `put_batch`, `delete_batch`,
`scan_prefix`, `approx_size`. Records serialized with `postcard` (stored as
@@ -246,18 +244,16 @@ apps/web/tauri/graphql_cache_plugin/ # tauri commands + engine thread wrapping
apps/web/src/lib/graphql-cache/ # JS glue
host/ # CacheHost interface + worker & tauri transports
exchange/ # urql normalizedCacheExchange
- worker/ # SharedWorker/dedicated-worker entries
+ worker/ # SharedWorker entry + worker core
```
## 6. Phases
**Phase 0 — spike** *(closed)*
- Browser probe harness built; Chromium results in Appendix A. **Decision
- made: IDB-backed persistence via the `idb` crate, SharedWorker preferred
- with dedicated-worker fallback (§4.2).** Safari/Firefox probe runs and
- the Tauri IPC benchmark were deliberately skipped — the IDB + worker
- approach is the lowest common denominator and doesn't depend on their
- results.
+ made: IDB-backed persistence via the `idb` crate in a SharedWorker, with
+ caching disabled when SharedWorker is unavailable (§4.2).** Safari/Firefox
+ probe runs and the Tauri IPC benchmark were deliberately skipped.
- Wire protocol delivered in Phase 3 (`src/lib/graphql-cache/protocol.ts`).
- The probe harness (`spikes/graphql-cache-probe/`) and the soup payload
measurement script (`scripts/measure-soup-payloads.ts`) were removed
@@ -292,10 +288,9 @@ apps/web/src/lib/graphql-cache/ # JS glue
wasm-bindgen-test. Build: `just build-cache-wasm` →
`src/lib/graphql-cache/wasm/` (gitignored), ~460 KiB pre-gzip.
- ~~JS glue~~ (`apps/web/src/lib/graphql-cache/`, alias `@graphql-cache/*`):
- wire protocol (`protocol.ts`), `CacheWorkerCore` +
- SharedWorker/dedicated-worker entries (Web Locks write serialization +
- BroadcastChannel fanout in the fallback topology), `createWorkerCacheHost`
- implementing `CacheHost`. Type-checked; end-to-end browser exercise
+ wire protocol (`protocol.ts`), `CacheWorkerCore` + SharedWorker entry,
+ and `createWorkerCacheHost` implementing `CacheHost` (with a storage-free
+ no-op host when SharedWorker is unavailable). Type-checked; end-to-end browser exercise
happens with the Phase 4 exchange integration.
- ~~Tauri host~~ (`apps/web/tauri/graphql_cache_plugin`, in the *tauri*
workspace — it needs the patched tauri fork pinned there; path-deps on
@@ -346,8 +341,8 @@ apps/web/src/lib/graphql-cache/ # JS glue
- **Browser storage quirks** (Safari IDB edge cases/private mode, storage
eviction under pressure) — mitigated by the disposable-cache design
- (detect → discard → rebuild from network) and the dedicated-worker
- fallback topology. Tauri is unaffected (native host only).
+ (detect → discard → rebuild from network). Browsers without SharedWorker
+ use the storage-free no-op host. Tauri is unaffected (native host only).
- **`idb` crate dependency** — maintained third-party wasm bindings; if it
stalls, the `Storage` trait isolates us (swap for hand-rolled
`web-sys`-based bindings).
@@ -401,8 +396,7 @@ Takeaways:
3. RTT is a non-issue: ≤1 ms for 64 KiB payloads, well within the read
budget.
-These takeaways drove the §4.2 decision (IDB via the `idb` crate, engine in
-a worker that may or may not be a SharedWorker). Firefox/Safari probe runs
-and the Tauri IPC benchmark were **skipped by decision** — the chosen
-approach relies only on APIs universally available (IndexedDB, dedicated
-workers, Web Locks, BroadcastChannel).
+These takeaways originally drove the IDB decision. The current §4.2 topology
+requires SharedWorker for browser caching and deliberately falls back to no
+cache when it is unavailable. Firefox/Safari probe runs and the Tauri IPC
+benchmark were **skipped by decision**.
diff --git a/apps/web/src/lib/core/auth/logout.ts b/apps/web/src/lib/core/auth/logout.ts
index eeb1008011..a9be6d15ef 100644
--- a/apps/web/src/lib/core/auth/logout.ts
+++ b/apps/web/src/lib/core/auth/logout.ts
@@ -2,6 +2,7 @@ import { useAnalytics } from '@app/lib/analytics/analytics-context';
import { SERVER_HOSTS } from '@core/constant/servers';
import { isNativeMobilePlatform } from '@core/mobile/isNativeMobilePlatform';
import { syncLoginStorage } from '@core/util/cookies';
+import { clearRegisteredCaches } from '@graphql-cache/lifecycle';
import { authKeys } from '@queries/auth/user-info';
import { queryClient } from '@queries/client';
import { clearDocumentQueryCache } from '@queries/storage/document-cache';
@@ -33,6 +34,9 @@ export function useLogout() {
hasTrialed: false,
});
+ // Queued mutations are user intent; never allow them to replay under a
+ // subsequent account sharing this anonymous device cache scope.
+ await clearRegisteredCaches();
await authServiceClient.logout();
analytics.track('sign_out');
analytics.reset();
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 506333c2cc..9d068634e1 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
@@ -1,20 +1,27 @@
import {
type Client,
CombinedError,
+ createRequest,
gql,
makeOperation,
type Operation,
type OperationResult,
+ stringifyDocument,
} from '@urql/core';
import { beforeEach, describe, expect, it, vi } from 'vitest';
import { makeSubject, map, pipe, type Source, subscribe } from 'wonka';
import type { CacheHost } from '../host/types';
import type {
+ ClaimedMutation,
+ MutationClaim,
OptimisticWriteResult,
ReadResult,
WriteResult,
} from '../protocol';
-import { normalizedCacheExchange } from './normalized-cache-exchange';
+import {
+ type NormalizedCacheExchangeOptions,
+ normalizedCacheExchange,
+} from './normalized-cache-exchange';
const QUERY = gql`
query Soup($input: SoupInput!) {
@@ -39,14 +46,23 @@ type FakeHost = CacheHost & {
begins: Array<{ query: string; data: unknown }>;
commits: Array<{ transactionId: string; query: string; data: unknown }>;
rollbacks: string[];
+ defers: Array<{ transactionId: string; error: string }>;
+ claims: string[];
teardowns: number[];
scriptRead: (result: ReadResult) => void;
+ seedQueued: (args: Parameters<CacheHost['beginOptimisticWrite']>[0]) => void;
pushAffected: (opKeys: number[]) => void;
};
function makeFakeHost(): FakeHost {
let readResult: ReadResult = { kind: 'miss' };
const subscribers = new Set<(opKeys: number[]) => void>();
+ const queue: Array<{
+ transactionId: string;
+ args: Parameters<CacheHost['beginOptimisticWrite']>[0];
+ attemptCount: number;
+ leased: boolean;
+ }> = [];
const host: FakeHost = {
clientId: 'test-client',
reads: [],
@@ -54,10 +70,20 @@ function makeFakeHost(): FakeHost {
begins: [],
commits: [],
rollbacks: [],
+ defers: [],
+ claims: [],
teardowns: [],
scriptRead: (r) => {
readResult = r;
},
+ seedQueued: (args) => {
+ queue.push({
+ transactionId: `restored-${queue.length + 1}`,
+ args,
+ attemptCount: 0,
+ leased: false,
+ });
+ },
pushAffected: (opKeys) => {
for (const cb of subscribers) cb(opKeys);
},
@@ -79,19 +105,52 @@ function makeFakeHost(): FakeHost {
},
async beginOptimisticWrite(args): Promise<OptimisticWriteResult> {
host.begins.push({ query: args.query, data: args.data });
+ const transactionId = `txn-${host.begins.length}`;
+ queue.push({ transactionId, args, attemptCount: 0, leased: false });
return {
- transactionId: `txn-${host.begins.length}`,
+ transactionId,
changed: [],
affectedOps: [],
reset: false,
};
},
- async commitOptimisticWrite(transactionId, args): Promise<WriteResult> {
+ async claimNextMutation(_owner): Promise<ClaimedMutation | undefined> {
+ const head = queue[0];
+ if (!head || head.leased) return undefined;
+ head.leased = true;
+ head.attemptCount += 1;
+ host.claims.push(head.transactionId);
+ return {
+ transactionId: head.transactionId,
+ leaseGeneration: String(head.attemptCount),
+ query: head.args.query,
+ operationName: head.args.operationName,
+ variables: head.args.variables ?? {},
+ attemptCount: head.attemptCount,
+ };
+ },
+ async deferOptimisticWrite(
+ transactionId,
+ _claim: MutationClaim,
+ _nextAttemptAtMs,
+ error
+ ) {
+ host.defers.push({ transactionId, error });
+ const head = queue[0];
+ if (head?.transactionId === transactionId) head.leased = false;
+ },
+ async commitOptimisticWrite(
+ transactionId,
+ _claim,
+ args
+ ): Promise<WriteResult> {
host.commits.push({ transactionId, query: args.query, data: args.data });
+ if (queue[0]?.transactionId === transactionId) queue.shift();
return { changed: [], affectedOps: [], reset: false };
},
- async rollbackOptimisticWrite(transactionId): Promise<WriteResult> {
+ async rollbackOptimisticWrite(transactionId, _claim): Promise<WriteResult> {
host.rollbacks.push(transactionId);
+ if (queue[0]?.transactionId === transactionId) queue.shift();
return { changed: [], affectedOps: [], reset: false };
},
async invalidate() {
@@ -151,10 +210,27 @@ function makeMutationOp(key: number, optimisticResponse?: unknown): Operation {
/** Runs the exchange over a manual operation stream. */
function harness(
host: CacheHost,
- resultFor?: (op: Operation) => Partial<OperationResult>
+ resultFor?: (op: Operation) => Partial<OperationResult>,
+ options: NormalizedCacheExchangeOptions = {}
) {
- const client = { reexecuteOperation: vi.fn() } as unknown as Client;
const ops = makeSubject<Operation>();
+ const client = {
+ reexecuteOperation: vi.fn(),
+ mutation: vi.fn((query, variables, context) => ({
+ toPromise: () => {
+ const request = createRequest(query, variables);
+ ops.next(
+ makeOperation('mutation', request, {
+ requestPolicy: 'network-only',
+ url: 'http://test',
+ suspense: false,
+ ...context,
+ } as never)
+ );
+ return Promise.resolve(undefined);
+ },
+ })),
+ } as unknown as Client;
const forwarded: Operation[] = [];
const forward = (ops$: Source<Operation>): Source<OperationResult> =>
pipe(
@@ -177,7 +253,10 @@ function harness(
);
const results: OperationResult[] = [];
- const exchangeIo = normalizedCacheExchange(host)({
+ const exchangeIo = normalizedCacheExchange(
+ host,
+ options
+ )({
forward,
client,
dispatchDebug: () => undefined,
@@ -189,7 +268,7 @@ function harness(
return { ops, results, forwarded, client };
}
-const tick = () => new Promise((r) => setTimeout(r, 0));
+const tick = () => new Promise((resolve) => setTimeout(resolve, 10));
describe('normalizedCacheExchange', () => {
let host: FakeHost;
@@ -394,6 +473,34 @@ describe('normalizedCacheExchange', () => {
describe('mutations', () => {
const optimistic = { setEntityProperty: { id: 'prop-1' } };
+ it('replays a persisted mutation when the exchange starts', async () => {
+ host.seedQueued({
+ query: stringifyDocument(MUTATION),
+ operationName: 'SetEntityProperty',
+ variables: { input: {} },
+ data: optimistic,
+ });
+ const { forwarded } = harness(host);
+ await tick();
+
+ expect(host.begins).toHaveLength(0);
+ expect(host.claims).toEqual(['restored-1']);
+ expect(forwarded.map((op) => op.kind)).toEqual(['mutation']);
+ expect(forwarded[0]?.context.fetch).toBeTypeOf('function');
+ expect(host.commits[0]?.transactionId).toBe('restored-1');
+ });
+
+ it('forwards optimistic mutations without cache work when the host is disabled', async () => {
+ const disabledHost: CacheHost = { ...host, disabled: true };
+ const { ops, forwarded } = harness(disabledHost);
+ ops.next(makeMutationOp(1, optimistic));
+ await tick();
+
+ expect(host.begins).toHaveLength(0);
+ expect(host.claims).toHaveLength(0);
+ expect(forwarded.map((op) => op.kind)).toEqual(['mutation']);
+ });
+
it('installs the optimistic layer before forwarding to the network', async () => {
const { ops, results, forwarded } = harness(host);
const begin = host.beginOptimisticWrite.bind(host);
@@ -412,6 +519,44 @@ describe('normalizedCacheExchange', () => {
expect(results[0]?.data).toEqual({ from: 'network' });
});
+ it('bounds queued network attempts to one minute', async () => {
+ const timeoutSignal = new AbortController().signal;
+ const existingSignal = new AbortController().signal;
+ const combinedSignal = new AbortController().signal;
+ const timeout = vi
+ .spyOn(AbortSignal, 'timeout')
+ .mockReturnValue(timeoutSignal);
+ const any = vi.spyOn(AbortSignal, 'any').mockReturnValue(combinedSignal);
+ const operationFetch = vi.fn().mockResolvedValue(new Response());
+ try {
+ const mutation = makeMutationOp(1, optimistic);
+ const mutationWithFetch = makeOperation(mutation.kind, mutation, {
+ ...mutation.context,
+ fetch: operationFetch,
+ } as never);
+ const { ops } = harness(host, (op) => {
+ if (op.kind === 'mutation') {
+ void op.context.fetch?.('http://test', {
+ signal: existingSignal,
+ });
+ }
+ return {};
+ });
+ ops.next(mutationWithFetch);
+ await tick();
+
+ expect(timeout).toHaveBeenCalledWith(60_000);
+ expect(any).toHaveBeenCalledWith([existingSignal, timeoutSignal]);
+ expect(operationFetch).toHaveBeenCalledWith(
+ 'http://test',
+ expect.objectContaining({ signal: combinedSignal })
+ );
+ } finally {
+ timeout.mockRestore();
+ any.mockRestore();
+ }
+ });
+
it('commits with the network result on success and never emits a synthetic result', async () => {
const { ops, results } = harness(host);
ops.next(makeMutationOp(1, optimistic));
@@ -455,6 +600,41 @@ describe('normalizedCacheExchange', () => {
expect(host.commits).toHaveLength(0);
});
+ it('retains a retryable network failure and still returns the error', async () => {
+ const error = new CombinedError({
+ networkError: new Error('offline'),
+ });
+ const shouldRetryMutation = vi.fn(() => true);
+ const { ops, results } = harness(
+ host,
+ (op) => (op.kind === 'mutation' ? { error, data: undefined } : {}),
+ { shouldRetryMutation }
+ );
+ ops.next(makeMutationOp(1, optimistic));
+ await tick();
+
+ expect(shouldRetryMutation).toHaveBeenCalledWith(error);
+ expect(host.defers).toEqual([
+ { transactionId: 'txn-1', error: error.message },
+ ]);
+ expect(host.rollbacks).toHaveLength(0);
+ expect(results[0]?.error).toBe(error);
+ });
+
+ it('forwards queued optimistic mutations strictly in enqueue order', async () => {
+ const { ops, forwarded } = harness(host);
+ ops.next(makeMutationOp(1, optimistic));
+ ops.next(makeMutationOp(2, optimistic));
+ await tick();
+
+ expect(host.claims).toEqual(['txn-1', 'txn-2']);
+ expect(forwarded.map((op) => op.key)).toEqual([1, 2]);
+ expect(host.commits.map((entry) => entry.transactionId)).toEqual([
+ 'txn-1',
+ 'txn-2',
+ ]);
+ });
+
it('writes non-optimistic mutation responses through the standard path', async () => {
const { ops, results, forwarded } = harness(host);
ops.next(makeMutationOp(1));
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 d72d604395..b5a96a0eb0 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
@@ -18,12 +18,10 @@
* - `cache-only`: hit → emit; miss → emit `data: undefined`, no network.
*
* Mutations:
- * - With an optimistic response (see `executeOptimisticMutation`): an
- * in-memory optimistic layer is installed *before* the mutation is
- * forwarded; dependent queries re-execute immediately. The layer commits
- * with the real response on success and rolls back on error. No synthetic
- * result is emitted — the caller's mutation promise resolves only with
- * the network result.
+ * - With an optimistic response (see `executeOptimisticMutation`): the
+ * mutation and layer are durably queued before the ordered runner forwards
+ * it. Retryable failures retain optimism for background replay; permanent
+ * failures roll back. The caller still receives only its network result.
* - Without one: forwarded normally; successful responses are normalized
* through the standard write path so dependent cached queries update.
*
@@ -31,13 +29,19 @@
*/
import {
+ type CombinedError,
type Exchange,
makeOperation,
type Operation,
type OperationResult,
stringifyDocument,
} from '@urql/core';
-import { Kind, type OperationDefinitionNode } from 'graphql';
+import {
+ type DocumentNode,
+ Kind,
+ type OperationDefinitionNode,
+ parse,
+} from 'graphql';
import {
empty,
filter,
@@ -60,7 +64,31 @@ import { optimisticContextOf } from './optimistic';
* urql operation key): identical concurrent mutations share a key but each
* carries its own transaction.
*/
-const TRANSACTION_CONTEXT_KEY = 'normalizedCacheTransaction';
+const QUEUE_ATTEMPT_CONTEXT_KEY = 'normalizedCacheQueueAttempt';
+const QUEUE_REQUEST_TIMEOUT_MS = 60_000;
+const QUEUE_LEASE_MS = 5 * 60_000;
+const EMPTY_QUEUE_POLL_MS = 30_000;
+
+type QueueAttemptContext = {
+ transactionId: string;
+ leaseOwner: string;
+ leaseGeneration: string;
+ attemptCount: number;
+};
+
+function queueAttemptOf(op: Operation): QueueAttemptContext | undefined {
+ const value: unknown = op.context[QUEUE_ATTEMPT_CONTEXT_KEY];
+ if (
+ value !== null &&
+ typeof value === 'object' &&
+ 'transactionId' in value &&
+ 'leaseOwner' in value &&
+ 'leaseGeneration' in value
+ ) {
+ return value as QueueAttemptContext;
+ }
+ return undefined;
+}
const queryTextCache = new WeakMap<object, string>();
@@ -83,6 +111,45 @@ function operationName(op: Operation): string | undefined {
return undefined;
}
+function replayDocument(query: string, name?: string): DocumentNode {
+ const document = parse(query);
+ if (!name) return document;
+ const definitions = document.definitions.filter(
+ (definition) =>
+ definition.kind !== Kind.OPERATION_DEFINITION ||
+ definition.name?.value === name
+ );
+ if (
+ !definitions.some(
+ (definition) => definition.kind === Kind.OPERATION_DEFINITION
+ )
+ ) {
+ throw new Error(`queued GraphQL operation ${name} is missing`);
+ }
+ return { ...document, definitions };
+}
+
+function retryDelayMs(attemptCount: number): number {
+ return Math.min(1_000 * 2 ** Math.max(0, attemptCount - 1), 60_000);
+}
+
+/** Applies a hard network bound well inside the durable queue lease. */
+function withQueueRequestTimeout(op: Operation): Operation {
+ const operationFetch = op.context.fetch ?? globalThis.fetch;
+ return makeOperation(op.kind, op, {
+ ...op.context,
+ fetch: (input, init) => {
+ const timeoutSignal = AbortSignal.timeout(QUEUE_REQUEST_TIMEOUT_MS);
+ return operationFetch(input, {
+ ...init,
+ signal: init?.signal
+ ? AbortSignal.any([init.signal, timeoutSignal])
+ : timeoutSignal,
+ });
+ },
+ });
+}
+
function cacheResult(
op: Operation,
data: unknown,
@@ -110,6 +177,12 @@ export interface NormalizedCacheExchangeOptions {
* layer itself is identity-agnostic.
*/
extractIdentity?: (data: unknown) => string | undefined;
+ /**
+ * Decides whether a failed optimistic mutation remains queued. The caller
+ * still receives the current network error; `true` retains the optimistic
+ * layer for a later background attempt. Defaults to `false`.
+ */
+ shouldRetryMutation?: (error: CombinedError) => boolean | Promise<boolean>;
}
export function normalizedCacheExchange(
@@ -141,6 +214,84 @@ export function normalizedCacheExchange(
// Async cache reads re-inject network-bound operations here.
const { source: forwardQueue$, next: enqueueForward } =
makeSubject<Operation>();
+ const queueOwner = `exchange:${host.clientId}`;
+ const liveQueuedOps = new Map<string, Operation>();
+ let attemptInFlight = false;
+ let drainRunning = false;
+ let deferredUntil: number | undefined;
+ let drainTimer: ReturnType<typeof setTimeout> | undefined;
+
+ function scheduleDrain(delayMs = 0): void {
+ if (drainTimer !== undefined) clearTimeout(drainTimer);
+ drainTimer = setTimeout(() => {
+ drainTimer = undefined;
+ void drainQueue();
+ }, delayMs);
+ }
+
+ async function drainQueue(): Promise<void> {
+ if (attemptInFlight || drainRunning) return;
+ drainRunning = true;
+ try {
+ const now = Date.now();
+ const claimed = await host.claimNextMutation(
+ queueOwner,
+ now,
+ now + QUEUE_LEASE_MS
+ );
+ if (!claimed) {
+ scheduleDrain(
+ deferredUntil === undefined
+ ? EMPTY_QUEUE_POLL_MS
+ : Math.max(0, deferredUntil - Date.now())
+ );
+ return;
+ }
+
+ deferredUntil = undefined;
+ attemptInFlight = true;
+ const attempt: QueueAttemptContext = {
+ transactionId: claimed.transactionId,
+ leaseOwner: queueOwner,
+ leaseGeneration: claimed.leaseGeneration,
+ attemptCount: claimed.attemptCount,
+ };
+ const live = liveQueuedOps.get(claimed.transactionId);
+ if (live) {
+ enqueueForward(
+ withQueueRequestTimeout(
+ makeOperation(live.kind, live, {
+ ...live.context,
+ [QUEUE_ATTEMPT_CONTEXT_KEY]: attempt,
+ })
+ )
+ );
+ } else {
+ try {
+ const replay = client.mutation(
+ replayDocument(claimed.query, claimed.operationName),
+ claimed.variables,
+ {
+ requestPolicy: 'network-only',
+ [QUEUE_ATTEMPT_CONTEXT_KEY]: attempt,
+ }
+ );
+ void replay.toPromise();
+ } catch {
+ await host.rollbackOptimisticWrite(claimed.transactionId, {
+ owner: queueOwner,
+ generation: claimed.leaseGeneration,
+ });
+ attemptInFlight = false;
+ scheduleDrain();
+ }
+ }
+ } catch {
+ scheduleDrain(EMPTY_QUEUE_POLL_MS);
+ } finally {
+ drainRunning = false;
+ }
+ }
async function readThenRoute(
op: Operation
@@ -177,12 +328,17 @@ export function normalizedCacheExchange(
return undefined;
}
- /**
- * Installs the optimistic layer (when the mutation carries one) and
- * only then releases the mutation to the network. Cache failures
- * degrade to a plain, non-optimistic network mutation.
- */
+ /** Durably queues optimism before allowing the ordered runner to send. */
async function prepareMutation(op: Operation): Promise<void> {
+ if (host.disabled) {
+ enqueueForward(op);
+ return;
+ }
+ // Reconstructed startup retries already have a durable transaction.
+ if (queueAttemptOf(op)) {
+ enqueueForward(withQueueRequestTimeout(op));
+ return;
+ }
const optimistic = optimisticContextOf(op);
if (!optimistic) {
enqueueForward(op);
@@ -195,12 +351,8 @@ export function normalizedCacheExchange(
variables: op.variables as Record<string, unknown> | undefined,
data: optimistic.optimisticResponse,
});
- enqueueForward(
- makeOperation(op.kind, op, {
- ...op.context,
- [TRANSACTION_CONTEXT_KEY]: begin.transactionId,
- })
- );
+ liveQueuedOps.set(begin.transactionId, op);
+ scheduleDrain();
} catch (error) {
options.onCacheError?.(error, op);
enqueueForward(op);
@@ -225,16 +377,39 @@ export function normalizedCacheExchange(
options.onCacheError?.(error, op);
}
} else if (op.kind === 'mutation') {
- const transactionId: unknown = op.context[TRANSACTION_CONTEXT_KEY];
- try {
- if (typeof transactionId === 'string') {
+ const attempt = queueAttemptOf(op);
+ if (attempt) {
+ const claim = {
+ owner: attempt.leaseOwner,
+ generation: attempt.leaseGeneration,
+ };
+ let retryAt: number | undefined;
+ try {
if (result.error || result.data == null) {
- await host.rollbackOptimisticWrite(transactionId);
+ let retry = false;
+ if (result.error && options.shouldRetryMutation) {
+ try {
+ retry = await options.shouldRetryMutation(result.error);
+ } catch (error) {
+ options.onCacheError?.(error, op);
+ }
+ }
+ if (retry) {
+ retryAt = Date.now() + retryDelayMs(attempt.attemptCount);
+ await host.deferOptimisticWrite(
+ attempt.transactionId,
+ claim,
+ retryAt,
+ result.error?.message ?? 'mutation returned no data'
+ );
+ } else {
+ await host.rollbackOptimisticWrite(
+ attempt.transactionId,
+ claim
+ );
+ }
} else {
- // Atomic replace: dependents move straight from the
- // optimistic data to the real response, never flickering
- // back to the pre-mutation state.
- await host.commitOptimisticWrite(transactionId, {
+ await host.commitOptimisticWrite(attempt.transactionId, claim, {
query: queryText(op),
operationName: operationName(op),
variables: op.variables as
@@ -243,7 +418,19 @@ export function normalizedCacheExchange(
data: result.data,
});
}
- } else if (result.data != null && !result.error) {
+ } catch (error) {
+ options.onCacheError?.(error, op);
+ retryAt = Date.now() + QUEUE_LEASE_MS;
+ } finally {
+ liveQueuedOps.delete(attempt.transactionId);
+ attemptInFlight = false;
+ deferredUntil = retryAt;
+ scheduleDrain(
+ retryAt === undefined ? 0 : Math.max(0, retryAt - Date.now())
+ );
+ }
+ } else if (result.data != null && !result.error) {
+ try {
// Plain mutation write-through: normalized entities update
// dependent cached queries.
await host.writeQuery({
@@ -252,9 +439,9 @@ export function normalizedCacheExchange(
variables: op.variables as Record<string, unknown> | undefined,
data: result.data,
});
+ } catch (error) {
+ options.onCacheError?.(error, op);
}
- } catch (error) {
- options.onCacheError?.(error, op);
}
}
return result;
@@ -274,9 +461,9 @@ export function normalizedCacheExchange(
})
);
- // Mutations are held until their optimistic layer (if any) is
- // installed, then re-injected through the forward queue. Emits
- // nothing itself — the network result is the only mutation emission.
+ // Optimistic mutations are held after durable enqueue until the strict
+ // queue runner claims them. The network result remains the only
+ // mutation emission.
const mutationPrep$ = pipe(
shared,
filter((op) => op.kind === 'mutation'),
@@ -305,6 +492,12 @@ export function normalizedCacheExchange(
mergeMap((result) => fromPromise(writeThrough(result)))
);
+ if (!host.disabled) {
+ scheduleDrain();
+ if (typeof addEventListener === 'function') {
+ addEventListener('online', () => scheduleDrain());
+ }
+ }
void unsubscribePush;
return merge([cacheResults$, mutationPrep$, forwarded$]);
};
diff --git a/apps/web/src/lib/graphql-cache/host/noop-host.ts b/apps/web/src/lib/graphql-cache/host/noop-host.ts
new file mode 100644
index 0000000000..e3954cea56
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/host/noop-host.ts
@@ -0,0 +1,54 @@
+import type {
+ OptimisticWriteResult,
+ ReadResult,
+ WriteResult,
+} from '../protocol';
+import type { CacheHost } from './types';
+
+const emptyWriteResult = (): WriteResult => ({
+ changed: [],
+ affectedOps: [],
+ reset: false,
+});
+
+/**
+ * CacheHost used when the platform cannot run the shared cache engine.
+ * It never stores data. Its disabled marker makes the exchange bypass
+ * optimistic persistence and forward mutations directly.
+ */
+export function createNoopCacheHost(reason: string): CacheHost {
+ console.warn(`[graphql-cache] disabled: ${reason}`);
+
+ return {
+ clientId: 'noop',
+ disabled: true,
+ async readQuery(): Promise<ReadResult> {
+ return { kind: 'miss' };
+ },
+ async writeQuery(): Promise<WriteResult> {
+ return emptyWriteResult();
+ },
+ async beginOptimisticWrite(): Promise<OptimisticWriteResult> {
+ throw new Error('normalized GraphQL cache is unavailable');
+ },
+ async claimNextMutation() {
+ return undefined;
+ },
+ async deferOptimisticWrite(): Promise<void> {},
+ async commitOptimisticWrite(): Promise<WriteResult> {
+ return emptyWriteResult();
+ },
+ async rollbackOptimisticWrite(): Promise<WriteResult> {
+ return emptyWriteResult();
+ },
+ async invalidate(): Promise<string[]> {
+ return [];
+ },
+ async teardown(): Promise<void> {},
+ async clear(): Promise<void> {},
+ onOpsAffected() {
+ return () => undefined;
+ },
+ dispose() {},
+ };
+}
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 4a21fbe77b..f647075d6d 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
@@ -99,19 +99,29 @@ describe('createTauriCacheHost', () => {
});
expect(begun).toEqual(optimistic);
- await host.commitOptimisticWrite('1', {
+ const claim = { owner: 'runner', generation: '2' };
+ await host.commitOptimisticWrite('1', claim, {
query: 'mutation { m }',
data: { m: 2 },
});
expect(invokeMock).toHaveBeenCalledWith(
'graphql_cache_commit_optimistic_write',
- expect.objectContaining({ transactionId: '1', data: { m: 2 } })
+ expect.objectContaining({
+ transactionId: '1',
+ leaseOwner: 'runner',
+ leaseGeneration: '2',
+ data: { m: 2 },
+ })
);
- await host.rollbackOptimisticWrite('1');
+ await host.rollbackOptimisticWrite('1', claim);
expect(invokeMock).toHaveBeenCalledWith(
'graphql_cache_rollback_optimistic_write',
- { transactionId: '1' }
+ {
+ transactionId: '1',
+ leaseOwner: 'runner',
+ leaseGeneration: '2',
+ }
);
});
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 59cfe7e0fa..f164569e32 100644
--- a/apps/web/src/lib/graphql-cache/host/tauri-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.ts
@@ -10,6 +10,8 @@
import { invoke } from '@tauri-apps/api/core';
import { listen, type UnlistenFn } from '@tauri-apps/api/event';
import type {
+ ClaimedMutation,
+ MutationClaim,
OptimisticWriteResult,
ReadResult,
WriteResult,
@@ -129,12 +131,42 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
operationName: args.operationName,
variables: args.variables,
data: args.data,
+ createdAtMs: Date.now(),
}
);
},
+ async claimNextMutation(
+ owner: string,
+ nowMs: number,
+ leaseExpiresAtMs: number
+ ): Promise<ClaimedMutation | undefined> {
+ await ready;
+ return await request<ClaimedMutation | undefined>(
+ 'graphql_cache_claim_next_mutation',
+ { owner, nowMs, leaseExpiresAtMs }
+ );
+ },
+
+ async deferOptimisticWrite(
+ transactionId: string,
+ claim: MutationClaim,
+ nextAttemptAtMs: number,
+ error: string
+ ): Promise<void> {
+ await ready;
+ await request('graphql_cache_defer_optimistic_write', {
+ transactionId,
+ leaseOwner: claim.owner,
+ leaseGeneration: claim.generation,
+ nextAttemptAtMs,
+ error,
+ });
+ },
+
async commitOptimisticWrite(
transactionId: string,
+ claim: MutationClaim,
args: CacheWriteArgs
): Promise<WriteResult> {
await ready;
@@ -142,6 +174,8 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
'graphql_cache_commit_optimistic_write',
{
transactionId,
+ leaseOwner: claim.owner,
+ leaseGeneration: claim.generation,
query: args.query,
operationName: args.operationName,
variables: args.variables,
@@ -150,11 +184,18 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
);
},
- async rollbackOptimisticWrite(transactionId: string): Promise<WriteResult> {
+ async rollbackOptimisticWrite(
+ transactionId: string,
+ claim: MutationClaim
+ ): Promise<WriteResult> {
await ready;
return await request<WriteResult>(
'graphql_cache_rollback_optimistic_write',
- { transactionId }
+ {
+ transactionId,
+ leaseOwner: claim.owner,
+ leaseGeneration: claim.generation,
+ }
);
},
diff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.ts
index 627e1df72b..2d3af1ac75 100644
--- a/apps/web/src/lib/graphql-cache/host/types.ts
+++ b/apps/web/src/lib/graphql-cache/host/types.ts
@@ -1,11 +1,13 @@
/**
* Transport-agnostic cache host interface consumed by the urql exchange and
* imperative writers (websocket handlers). Implementations:
- * - worker-host.ts: browser (SharedWorker / dedicated worker + wasm engine)
+ * - worker-host.ts: browser (SharedWorker + wasm engine, or no-op fallback)
* - tauri-host.ts (Phase 3b): Tauri IPC to the native engine
*/
import type {
+ ClaimedMutation,
+ MutationClaim,
OptimisticWriteResult,
ReadResult,
WriteResult,
@@ -28,26 +30,37 @@ export interface CacheWriteArgs extends CacheReadArgs {
export interface CacheHost {
/** Stable id of this context; used to namespace operation ids. */
readonly clientId: string;
+ /** True for the storage-free fallback used without SharedWorker support. */
+ readonly disabled?: boolean;
readQuery(args: CacheReadArgs): Promise<ReadResult>;
writeQuery(args: CacheWriteArgs): Promise<WriteResult>;
- /**
- * Installs an in-memory optimistic layer from a mutation's optimistic
- * response (`args.data`). Persists nothing; the returned transaction id
- * must be settled with `commitOptimisticWrite` or
- * `rollbackOptimisticWrite`.
- */
+ /** Durably queues a mutation and its optimistic response. */
beginOptimisticWrite(args: CacheWriteArgs): Promise<OptimisticWriteResult>;
- /**
- * Replaces a pending optimistic layer with the real network response
- * (`args.data`) atomically and flushes settled layers durably.
- */
+ /** Claims the oldest runnable mutation; later entries are never skipped. */
+ claimNextMutation(
+ owner: string,
+ nowMs: number,
+ leaseExpiresAtMs: number
+ ): Promise<ClaimedMutation | undefined>;
+ /** Retains a retryable mutation and releases its lease. */
+ deferOptimisticWrite(
+ transactionId: string,
+ claim: MutationClaim,
+ nextAttemptAtMs: number,
+ error: string
+ ): Promise<void>;
+ /** Atomically commits a claimed mutation's real network response. */
commitOptimisticWrite(
transactionId: string,
+ claim: MutationClaim,
args: CacheWriteArgs
): Promise<WriteResult>;
- /** Drops a pending optimistic layer's contribution (mutation failed). */
- rollbackOptimisticWrite(transactionId: string): Promise<WriteResult>;
+ /** Permanently fails a claimed mutation and drops its optimistic layer. */
+ rollbackOptimisticWrite(
+ transactionId: string,
+ claim: MutationClaim
+ ): Promise<WriteResult>;
/** Evict records by entity key (external/push updates); returns affected local op ids. */
invalidate(keys: string[]): Promise<string[]>;
/** urql teardown for an operation key. */
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
new file mode 100644
index 0000000000..8bb7ab1d0a
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts
@@ -0,0 +1,47 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createWorkerCacheHost } from './worker-host';
+
+describe('createWorkerCacheHost', () => {
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+ });
+
+ it('uses a storage-free no-op host when SharedWorker is unavailable', async () => {
+ const worker = vi.fn();
+ vi.stubGlobal('SharedWorker', undefined);
+ vi.stubGlobal('Worker', worker);
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+
+ expect(warn).toHaveBeenCalledWith(
+ '[graphql-cache] disabled: SharedWorker is not supported by this browser'
+ );
+ expect(worker).not.toHaveBeenCalled();
+ expect(host.disabled).toBe(true);
+ await expect(host.readQuery({ query: '{ x }' })).resolves.toEqual({
+ kind: 'miss',
+ });
+ await expect(
+ host.writeQuery({ query: '{ x }', data: { x: 1 } })
+ ).resolves.toEqual({ changed: [], affectedOps: [], reset: false });
+ });
+
+ it('falls back to no-op when SharedWorker initialization throws', () => {
+ vi.stubGlobal(
+ 'SharedWorker',
+ vi.fn(function () {
+ throw new Error('blocked');
+ })
+ );
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+
+ expect(host.disabled).toBe(true);
+ expect(warn).toHaveBeenCalledWith(
+ '[graphql-cache] disabled: SharedWorker could not be initialized'
+ );
+ });
+});
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 8f6a1ea9e7..ba72c4e57a 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts
@@ -1,19 +1,20 @@
/**
- * Browser CacheHost: talks the RPC protocol to the cache worker.
- * Prefers SharedWorker (single engine across tabs); falls back to a
- * dedicated worker per tab (engines converge via IndexedDB + Web Locks +
- * BroadcastChannel — see worker-core.ts).
+ * Browser CacheHost: talks to the single cache engine in a SharedWorker.
+ * Platforms without SharedWorker support receive a storage-free no-op host.
*/
import {
type CacheNotice,
type CacheRequest,
+ type ClaimedMutation,
isCachePush,
+ type MutationClaim,
type OptimisticWriteResult,
type ReadResult,
type WorkerMessage,
type WriteResult,
} from '../protocol';
+import { createNoopCacheHost } from './noop-host';
import type { CacheHost, CacheReadArgs, CacheWriteArgs } from './types';
type Pending = {
@@ -29,8 +30,6 @@ type DistributiveOmit<T, K extends PropertyKey> = T extends unknown
export interface WorkerHostOptions {
scope: string;
hotCapacity?: number;
- /** Force a topology (tests/diagnostics). */
- forceDedicatedWorker?: boolean;
/**
* Per-request timeout in ms (default 10s). A hung worker rejects the
* pending call; the exchange degrades rejected reads to the network.
@@ -41,6 +40,10 @@ export interface WorkerHostOptions {
const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
+ if (typeof SharedWorker !== 'function') {
+ return createNoopCacheHost('SharedWorker is not supported by this browser');
+ }
+
const clientId = crypto.randomUUID();
const pending = new Map<
number,
@@ -51,9 +54,6 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
let nextRequestId = 1;
- const useShared =
- typeof SharedWorker === 'function' && !options.forceDedicatedWorker;
-
let post: (msg: CacheRequest) => void;
let dispose: () => void;
@@ -81,30 +81,25 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
}
};
- if (useShared) {
- const worker = new SharedWorker(
+ let worker: SharedWorker;
+ try {
+ worker = new SharedWorker(
new URL('../worker/cache.shared-worker.ts', import.meta.url),
{ type: 'module', name: `graphql-cache:${options.scope}` }
);
worker.port.onmessage = onMessage;
worker.port.start();
- post = (msg) => worker.port.postMessage(msg);
- dispose = () => {
- // Tell the SharedWorker to drop our port — there is no platform
- // disconnect event, and stale ports would otherwise accumulate.
- const notice: CacheNotice = { kind: 'disconnect' };
- worker.port.postMessage(notice);
- worker.port.close();
- };
- } else {
- const worker = new Worker(
- new URL('../worker/cache.worker.ts', import.meta.url),
- { type: 'module', name: `graphql-cache:${options.scope}` }
- );
- worker.onmessage = onMessage;
- post = (msg) => worker.postMessage(msg);
- dispose = () => worker.terminate();
+ } catch {
+ return createNoopCacheHost('SharedWorker could not be initialized');
}
+ post = (msg) => worker.port.postMessage(msg);
+ dispose = () => {
+ // Tell the SharedWorker to drop our port — there is no platform
+ // disconnect event, and stale ports would otherwise accumulate.
+ const notice: CacheNotice = { kind: 'disconnect' };
+ worker.port.postMessage(notice);
+ worker.port.close();
+ };
// Best-effort cleanup when the page goes away (bfcache-safe: a restored
// page gets a fresh host on next use anyway).
@@ -173,17 +168,52 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
operationName: args.operationName,
variables: args.variables,
data: args.data,
+ createdAtMs: Date.now(),
})) as OptimisticWriteResult;
},
+ async claimNextMutation(
+ owner: string,
+ nowMs: number,
+ leaseExpiresAtMs: number
+ ): Promise<ClaimedMutation | undefined> {
+ await ready;
+ return (await request({
+ kind: 'claim-next-mutation',
+ owner,
+ nowMs,
+ leaseExpiresAtMs,
+ })) as ClaimedMutation | undefined;
+ },
+
+ async deferOptimisticWrite(
+ transactionId: string,
+ claim: MutationClaim,
+ nextAttemptAtMs: number,
+ error: string
+ ): Promise<void> {
+ await ready;
+ await request({
+ kind: 'defer-optimistic-write',
+ transactionId,
+ leaseOwner: claim.owner,
+ leaseGeneration: claim.generation,
+ nextAttemptAtMs,
+ error,
+ });
+ },
+
async commitOptimisticWrite(
transactionId: string,
+ claim: MutationClaim,
args: CacheWriteArgs
): Promise<WriteResult> {
await ready;
return (await request({
kind: 'commit-optimistic-write',
transactionId,
+ leaseOwner: claim.owner,
+ leaseGeneration: claim.generation,
query: args.query,
operationName: args.operationName,
variables: args.variables,
@@ -191,11 +221,16 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
})) as WriteResult;
},
- async rollbackOptimisticWrite(transactionId: string): Promise<WriteResult> {
+ async rollbackOptimisticWrite(
+ transactionId: string,
+ claim: MutationClaim
+ ): Promise<WriteResult> {
await ready;
return (await request({
kind: 'rollback-optimistic-write',
transactionId,
+ leaseOwner: claim.owner,
+ leaseGeneration: claim.generation,
})) as WriteResult;
},
diff --git a/apps/web/src/lib/graphql-cache/index.ts b/apps/web/src/lib/graphql-cache/index.ts
index 5abe5876cf..3b4ed9585e 100644
--- a/apps/web/src/lib/graphql-cache/index.ts
+++ b/apps/web/src/lib/graphql-cache/index.ts
@@ -15,7 +15,6 @@ export type {
} from './host/types';
export { createWorkerCacheHost } from './host/worker-host';
export type {
- CacheBroadcast,
CachePush,
CacheRequest,
CacheResponse,
diff --git a/apps/web/src/lib/graphql-cache/lifecycle.test.ts b/apps/web/src/lib/graphql-cache/lifecycle.test.ts
new file mode 100644
index 0000000000..f25180ddf5
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/lifecycle.test.ts
@@ -0,0 +1,52 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { CacheHost } from './host/types';
+
+function hostWithClear(clear: () => Promise<void>): CacheHost {
+ return { clear } as CacheHost;
+}
+
+describe('clearRegisteredCaches', () => {
+ beforeEach(() => {
+ localStorage.clear();
+ vi.restoreAllMocks();
+ vi.resetModules();
+ });
+
+ it('preserves the scope when every cache clears', async () => {
+ localStorage.setItem('graphql-cache:scope', 'current-scope');
+ const clear = vi.fn().mockResolvedValue(undefined);
+ const { clearRegisteredCaches, registerCacheHost } = await import(
+ './lifecycle'
+ );
+ registerCacheHost(hostWithClear(clear));
+
+ await clearRegisteredCaches();
+
+ expect(clear).toHaveBeenCalledOnce();
+ expect(localStorage.getItem('graphql-cache:scope')).toBe('current-scope');
+ });
+
+ it('rotates the scope after attempting every clear when one fails', async () => {
+ localStorage.setItem('graphql-cache:scope', 'current-scope');
+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(
+ '00000000-0000-4000-8000-000000000001'
+ );
+ const successfulClear = vi.fn().mockResolvedValue(undefined);
+ const failedClear = vi
+ .fn()
+ .mockRejectedValue(new Error('durable wipe failed'));
+ const { clearRegisteredCaches, registerCacheHost } = await import(
+ './lifecycle'
+ );
+ registerCacheHost(hostWithClear(successfulClear));
+ registerCacheHost(hostWithClear(failedClear));
+
+ await clearRegisteredCaches();
+
+ expect(successfulClear).toHaveBeenCalledOnce();
+ expect(failedClear).toHaveBeenCalledOnce();
+ expect(localStorage.getItem('graphql-cache:scope')).toBe(
+ '00000000-0000-4000-8000-000000000001'
+ );
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/lifecycle.ts b/apps/web/src/lib/graphql-cache/lifecycle.ts
new file mode 100644
index 0000000000..7cdca28f53
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/lifecycle.ts
@@ -0,0 +1,19 @@
+import type { CacheHost } from './host/types';
+import { rotateCacheScope } from './scope';
+
+const hosts = new Set<CacheHost>();
+
+/** Registers a cache host for account-lifecycle clearing. */
+export function registerCacheHost(host: CacheHost): void {
+ hosts.add(host);
+}
+
+/** Best-effort wipe of records and queued user intent during logout. */
+export async function clearRegisteredCaches(): Promise<void> {
+ const results = await Promise.allSettled(
+ [...hosts].map((host) => host.clear())
+ );
+ if (results.some((result) => result.status === 'rejected')) {
+ rotateCacheScope();
+ }
+}
diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.ts
index 603d06292d..956512fe92 100644
--- a/apps/web/src/lib/graphql-cache/protocol.ts
+++ b/apps/web/src/lib/graphql-cache/protocol.ts
@@ -2,13 +2,8 @@
* Wire protocol between page contexts and the cache worker (the `CacheHost`
* RPC from the design doc, apps/web/docs/graphql-normalized-cache-plan.md §4).
*
- * Topologies:
- * - SharedWorker: one engine, many ports. Invalidations fan out over the
- * ports directly.
- * - Dedicated worker per tab (fallback): one engine per tab over the same
- * IndexedDB database. Writes are serialized with Web Locks; changed keys
- * fan out across tabs via BroadcastChannel, and each tab's worker
- * translates them into locally-affected operation ids.
+ * The browser topology is one SharedWorker engine serving many page ports.
+ * Platforms without SharedWorker support use a storage-free no-op host.
*
* Operation ids are strings of the form `"{clientId}:{urqlOperationKey}"` so
* one shared engine can track operations from many tabs without collisions.
@@ -35,10 +30,28 @@ export type WriteResult = {
* transaction commits.
*/
export type OptimisticWriteResult = WriteResult & {
- /** Engine-assigned id; settle with commit/rollback-optimistic-write. */
+ /** Engine-assigned id; settle after claiming the queue head. */
transactionId: string;
};
+/** Claimed strict queue head, ready to be forwarded through urql. */
+export type ClaimedMutation = {
+ transactionId: string;
+ leaseGeneration: string;
+ query: string;
+ operationName?: string;
+ variables: Record<string, unknown>;
+ /** Identity witness captured at enqueue time. */
+ identity?: string;
+ attemptCount: number;
+};
+
+/** Identifies the queue attempt allowed to settle a transaction. */
+export type MutationClaim = {
+ owner: string;
+ generation: string;
+};
+
export type CacheRequest = { id: number } & (
| { kind: 'init'; scope: string; hotCapacity?: number }
| {
@@ -62,10 +75,7 @@ export type CacheRequest = { id: number } & (
*/
identity?: string;
}
- /**
- * Install an in-memory optimistic layer from a mutation's optimistic
- * response. Persists nothing; settle with commit/rollback.
- */
+ /** Durably enqueue a mutation together with its optimistic response. */
| {
kind: 'begin-optimistic-write';
originOpId?: string;
@@ -73,21 +83,40 @@ export type CacheRequest = { id: number } & (
operationName?: string;
variables?: Record<string, unknown>;
data: unknown;
+ createdAtMs: number;
+ }
+ | {
+ kind: 'claim-next-mutation';
+ owner: string;
+ nowMs: number;
+ leaseExpiresAtMs: number;
}
- /**
- * Atomically replace a pending layer with the real network response and
- * flush contiguous settled layers durably.
- */
+ | {
+ kind: 'defer-optimistic-write';
+ transactionId: string;
+ leaseOwner: string;
+ leaseGeneration: string;
+ nextAttemptAtMs: number;
+ error: string;
+ }
+ /** Atomically replace a claimed layer with the real network response. */
| {
kind: 'commit-optimistic-write';
transactionId: string;
+ leaseOwner: string;
+ leaseGeneration: string;
query: string;
operationName?: string;
variables?: Record<string, unknown>;
data: unknown;
}
- /** Drop a pending layer's contribution (mutation failed). */
- | { kind: 'rollback-optimistic-write'; transactionId: string }
+ /** Drop a claimed layer's contribution (permanent mutation failure). */
+ | {
+ kind: 'rollback-optimistic-write';
+ transactionId: string;
+ leaseOwner: string;
+ leaseGeneration: string;
+ }
| { kind: 'teardown'; opId: string }
/** External invalidation (e.g. websocket push): evict + report ops. */
| { kind: 'invalidate'; keys: string[] }
@@ -126,28 +155,6 @@ export type CachePush = {
export type WorkerMessage = CacheResponse | CachePush;
-/** Cross-tab broadcast (fallback topology), channel `graphql-cache:{scope}`. */
-export type CacheBroadcast =
- | {
- kind: 'changed';
- keys: string[];
- /** Random id of the emitting worker, to ignore own broadcasts. */
- source: string;
- }
- | {
- /** The shared storage was wiped (identity change silent restart). */
- kind: 'reset';
- source: string;
- };
-
-export function broadcastChannelName(scope: string): string {
- return `graphql-cache:${scope}`;
-}
-
-export function writeLockName(scope: string): string {
- return `graphql-cache:write:${scope}`;
-}
-
export function isCachePush(msg: WorkerMessage): msg is CachePush {
return 'kind' in msg && msg.kind === 'ops-affected';
}
diff --git a/apps/web/src/lib/graphql-cache/scope.ts b/apps/web/src/lib/graphql-cache/scope.ts
index 1c246d1d7c..8a901cd7a8 100644
--- a/apps/web/src/lib/graphql-cache/scope.ts
+++ b/apps/web/src/lib/graphql-cache/scope.ts
@@ -9,12 +9,26 @@
* different user than the one bound to the cache wipes and rebinds it
* (silent restart). See the design doc and cache-core `identity_witness`.
*
- * The uuid is stable for the browser profile; identity changes rotate the
- * cache *contents*, not the scope.
+ * The uuid is stable for the browser profile; identity changes normally rotate
+ * the cache *contents*. A failed logout wipe rotates the scope as a quarantine.
*/
const SCOPE_STORAGE_KEY = 'graphql-cache:scope';
+/** Quarantines a cache whose durable logout wipe could not be confirmed. */
+export function rotateCacheScope(): void {
+ const scope = crypto.randomUUID();
+ try {
+ localStorage.setItem(SCOPE_STORAGE_KEY, scope);
+ } catch {
+ try {
+ localStorage.removeItem(SCOPE_STORAGE_KEY);
+ } catch {
+ // Inaccessible storage already makes the current scope session-only.
+ }
+ }
+}
+
export function getOrCreateCacheScope(): string {
let scope: string | null = null;
try {
diff --git a/apps/web/src/lib/graphql-cache/worker/cache.shared-worker.ts b/apps/web/src/lib/graphql-cache/worker/cache.shared-worker.ts
index f99bcfe0a1..214c08f031 100644
--- a/apps/web/src/lib/graphql-cache/worker/cache.shared-worker.ts
+++ b/apps/web/src/lib/graphql-cache/worker/cache.shared-worker.ts
@@ -11,7 +11,7 @@ import { CacheWorkerCore } from './worker-core';
declare const self: SharedWorkerGlobalScope;
-const core = new CacheWorkerCore({ multiEngine: false });
+const core = new CacheWorkerCore();
self.onconnect = (event: MessageEvent) => {
const port = event.ports[0];
diff --git a/apps/web/src/lib/graphql-cache/worker/cache.worker.ts b/apps/web/src/lib/graphql-cache/worker/cache.worker.ts
deleted file mode 100644
index a9f1025a9d..0000000000
--- a/apps/web/src/lib/graphql-cache/worker/cache.worker.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-/**
- * Dedicated-worker entry: fallback topology when SharedWorker is
- * unavailable. One engine per tab over the shared IndexedDB database;
- * writes serialized via Web Locks; cross-tab invalidation over
- * BroadcastChannel (handled inside CacheWorkerCore).
- */
-
-import type { CacheRequest } from '../protocol';
-import { CacheWorkerCore } from './worker-core';
-
-declare const self: DedicatedWorkerGlobalScope;
-
-const core = new CacheWorkerCore({ multiEngine: true });
-core.addPort(self);
-
-self.onmessage = (msg: MessageEvent<CacheRequest>) => {
- void core.handleRequest(self, msg.data);
-};
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 54633c40a9..a3184a349b 100644
--- a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
+++ b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
@@ -9,6 +9,7 @@
*/
import type {
+ ClaimedMutation,
OptimisticWriteResult,
ReadResult,
WriteResult,
@@ -34,18 +35,36 @@ export interface CacheEngine {
query: string,
operationName: string | undefined,
variables: Record<string, unknown> | undefined,
- data: unknown
+ data: unknown,
+ createdAtMs: number
): Promise<OptimisticWriteResult>;
+ claimNextMutation(
+ owner: string,
+ nowMs: number,
+ leaseExpiresAtMs: number
+ ): Promise<ClaimedMutation | undefined>;
+ deferOptimisticWrite(
+ transactionId: string,
+ leaseOwner: string,
+ leaseGeneration: string,
+ nextAttemptAtMs: number,
+ error: string
+ ): Promise<void>;
commitOptimisticWrite(
transactionId: string,
+ leaseOwner: string,
+ leaseGeneration: string,
query: string,
operationName: string | undefined,
variables: Record<string, unknown> | undefined,
data: unknown
): Promise<WriteResult>;
- rollbackOptimisticWrite(transactionId: string): Promise<WriteResult>;
+ rollbackOptimisticWrite(
+ transactionId: string,
+ leaseOwner: string,
+ leaseGeneration: string
+ ): Promise<WriteResult>;
invalidateKeys(keys: string[]): Promise<string[]>;
- externalReset(): Promise<string[]>;
teardownOperation(opId: string): Promise<void>;
clear(): Promise<void>;
/** Close the IndexedDB connection; call before destroyCache. */
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 14ff9bed16..d07521c783 100644
--- a/apps/web/src/lib/graphql-cache/worker/worker-core.ts
+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.ts
@@ -1,22 +1,15 @@
/**
- * Topology-agnostic worker core: owns the wasm engine, serves the RPC
- * protocol on one or more ports, and fans out invalidations.
- *
- * Used by both entries:
- * - cache.shared-worker.ts (SharedWorker, many ports, one engine)
- * - cache.worker.ts (dedicated worker per tab + BroadcastChannel + Web Locks)
+ * SharedWorker core: owns the browser's single wasm engine, serves the RPC
+ * protocol to page ports, and fans out invalidations.
*/
-import {
- broadcastChannelName,
- type CacheBroadcast,
- type CachePush,
- type CacheRequest,
- type CacheResponse,
- type OptimisticWriteResult,
- type ReadResult,
- type WriteResult,
- writeLockName,
+import type {
+ CachePush,
+ CacheRequest,
+ CacheResponse,
+ OptimisticWriteResult,
+ ReadResult,
+ WriteResult,
} from '../protocol';
import { type CacheEngine, loadCacheWasm } from './wasm-module';
@@ -31,18 +24,6 @@ export class CacheWorkerCore {
/** Serializes engine calls (defense in depth; the engine also locks). */
private queue: Promise<unknown> = Promise.resolve();
private readonly ports = new Set<PortLike>();
- private broadcast: BroadcastChannel | undefined;
- private readonly workerId = crypto.randomUUID();
-
- constructor(
- private readonly options: {
- /**
- * Fallback topology (dedicated worker per tab): serialize writes via
- * Web Locks and exchange changed keys over BroadcastChannel.
- */
- multiEngine: boolean;
- }
- ) {}
addPort(port: PortLike): void {
this.ports.add(port);
@@ -90,57 +71,70 @@ export class CacheWorkerCore {
}
case 'write': {
const engine = this.requireEngine();
- const result = await this.durableWrite(
- async () =>
- await engine.writeQuery(
- request.originOpId,
- request.query,
- request.operationName,
- request.variables,
- request.data,
- request.identity
- )
+ const result = await engine.writeQuery(
+ request.originOpId,
+ request.query,
+ request.operationName,
+ request.variables,
+ request.data,
+ request.identity
);
this.fanOut(result);
return result;
}
case 'begin-optimistic-write': {
const engine = this.requireEngine();
- // Memory-only: no write lock needed, and never broadcast — the
- // layer is local to this engine (per tab in the fallback topology;
- // shared by all attached clients under a SharedWorker).
const result: OptimisticWriteResult = await engine.beginOptimisticWrite(
request.originOpId,
request.query,
request.operationName,
request.variables,
- request.data
+ request.data,
+ request.createdAtMs
);
- this.fanOut(result, { broadcast: false });
+ this.fanOut(result);
return result;
}
+ case 'claim-next-mutation': {
+ const engine = this.requireEngine();
+ return await engine.claimNextMutation(
+ request.owner,
+ request.nowMs,
+ request.leaseExpiresAtMs
+ );
+ }
+ case 'defer-optimistic-write': {
+ const engine = this.requireEngine();
+ await engine.deferOptimisticWrite(
+ request.transactionId,
+ request.leaseOwner,
+ request.leaseGeneration,
+ request.nextAttemptAtMs,
+ request.error
+ );
+ return null;
+ }
case 'commit-optimistic-write': {
const engine = this.requireEngine();
// Committing can flush settled layers into durable storage.
- const result = await this.durableWrite(
- async () =>
- await engine.commitOptimisticWrite(
- request.transactionId,
- request.query,
- request.operationName,
- request.variables,
- request.data
- )
+ const result = await engine.commitOptimisticWrite(
+ request.transactionId,
+ request.leaseOwner,
+ request.leaseGeneration,
+ request.query,
+ request.operationName,
+ request.variables,
+ request.data
);
this.fanOut(result);
return result;
}
case 'rollback-optimistic-write': {
const engine = this.requireEngine();
- // Rolling back can unblock a settled suffix and flush it durably.
- const result = await this.durableWrite(
- async () =>
- await engine.rollbackOptimisticWrite(request.transactionId)
+ const result = await engine.rollbackOptimisticWrite(
+ request.transactionId,
+ request.leaseOwner,
+ request.leaseGeneration
);
this.fanOut(result);
return result;
@@ -181,50 +175,12 @@ export class CacheWorkerCore {
this.initPromise = (async () => {
const wasm = await loadCacheWasm();
this.engine = await wasm.openCache(scope, hotCapacity);
- if (this.options.multiEngine) {
- this.broadcast = new BroadcastChannel(broadcastChannelName(scope));
- this.broadcast.onmessage = (event: MessageEvent<CacheBroadcast>) => {
- void this.onBroadcast(event.data);
- };
- }
})();
await this.initPromise;
}
- /** Broadcasts from other tabs' engines sharing our storage. */
- private async onBroadcast(msg: CacheBroadcast): Promise<void> {
- if (msg.source === this.workerId) return;
- const engine = this.engine;
- if (!engine) return;
- if (msg.kind === 'reset') {
- // Another engine wiped the shared storage (identity change): drop
- // local in-memory state and re-execute everything we track.
- const affectedOps = await this.enqueue(() => engine.externalReset());
- this.push({ kind: 'ops-affected', opIds: affectedOps, keys: [] });
- return;
- }
- const affectedOps = await this.enqueue(() =>
- engine.invalidateKeys(msg.keys)
- );
- this.push({ kind: 'ops-affected', opIds: affectedOps, keys: msg.keys });
- }
-
- /**
- * Runs a durable engine write, serialized via Web Locks in the
- * multi-engine (dedicated worker per tab) topology.
- */
- private async durableWrite<T>(write: () => Promise<T>): Promise<T> {
- return this.options.multiEngine && this.scope
- ? await navigator.locks.request(writeLockName(this.scope), write)
- : await write();
- }
-
- /**
- * After a local change: notify connected clients + other tabs. Optimistic
- * begins pass `broadcast: false` — their changes are visible only through
- * this engine, so other instances must not be told to invalidate.
- */
- private fanOut(result: WriteResult, opts?: { broadcast?: boolean }): void {
+ /** Notifies every page connected to this shared engine. */
+ private fanOut(result: WriteResult): void {
if (result.affectedOps.length > 0) {
this.push({
kind: 'ops-affected',
@@ -232,17 +188,6 @@ export class CacheWorkerCore {
keys: result.changed,
});
}
- if (
- opts?.broadcast !== false &&
- this.options.multiEngine &&
- this.broadcast &&
- (result.changed.length > 0 || result.reset)
- ) {
- const msg: CacheBroadcast = result.reset
- ? { kind: 'reset', source: this.workerId }
- : { kind: 'changed', keys: result.changed, source: this.workerId };
- this.broadcast.postMessage(msg);
- }
}
private push(msg: CachePush): void {
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts
index ff4cecc00c..ecad9e746b 100644
--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts
+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts
@@ -11,6 +11,7 @@ import {
createTauriCacheHost,
createWorkerCacheHost,
} from '@graphql-cache/index';
+import { registerCacheHost } from '@graphql-cache/lifecycle';
import { getOrCreateCacheScope } from '@graphql-cache/scope';
import { getMacroApiToken } from '@service-auth/fetch';
import { type Client, createClient, fetchExchange } from '@urql/core';
@@ -94,6 +95,7 @@ export function getGraphqlSoupClient(): Client {
const host = isTauri()
? createTauriCacheHost({ scope })
: createWorkerCacheHost({ scope });
+ registerCacheHost(host);
return createClient({
url: `${dssHost}/items/soup/graphql`,
exchanges: [
@@ -103,6 +105,9 @@ export function getGraphqlSoupClient(): Client {
// rebinds the cache (see @graphql-cache/scope).
extractIdentity: (data) =>
(data as Partial<SoupQuery> | undefined)?.user?.id,
+ // Transport failures remain queued with their optimistic layer;
+ // GraphQL application errors are permanent and roll back.
+ shouldRetryMutation: (error) => error.networkError != null,
}),
fetchExchange,
],
diff --git a/apps/web/tauri/graphql_cache_plugin/src/commands.rs b/apps/web/tauri/graphql_cache_plugin/src/commands.rs
index 1c0cfd22e1..808bd8fc20 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/commands.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/commands.rs
@@ -9,7 +9,9 @@
//! the exchange degrades to the network) — same contract as the browser
//! worker's `{ok: false, error}` responses.
-use crate::engine::{EngineHandle, OptimisticWriteResultWire, ReadResultWire, WriteResultWire};
+use crate::engine::{
+ ClaimedMutationWire, EngineHandle, OptimisticWriteResultWire, ReadResultWire, WriteResultWire,
+};
use crate::{CacheState, InitializedCache, emit_ops_affected};
use cache_sqlite::SqliteStorage;
use tauri::{AppHandle, Manager, Runtime, State};
@@ -105,9 +107,8 @@ pub async fn graphql_cache_write<R: Runtime>(
Ok(result)
}
-/// Installs an in-memory optimistic layer from a mutation's optimistic
-/// response. The one engine is shared by all webviews (SharedWorker
-/// semantics), so visible changes are broadcast too.
+/// Durably queues a mutation and its optimistic response. The one engine is
+/// shared by all webviews, so visible changes are broadcast too.
#[tauri::command]
pub async fn graphql_cache_begin_optimistic_write<R: Runtime>(
app: AppHandle<R>,
@@ -117,6 +118,7 @@ pub async fn graphql_cache_begin_optimistic_write<R: Runtime>(
operation_name: Option<String>,
variables: Option<Variables>,
data: serde_json::Value,
+ created_at_ms: i64,
) -> Result<OptimisticWriteResultWire, String> {
let result = engine_handle(&state)?
.begin_optimistic_write(
@@ -125,19 +127,55 @@ pub async fn graphql_cache_begin_optimistic_write<R: Runtime>(
operation_name,
variables.unwrap_or_default(),
data,
+ created_at_ms,
)
.await?;
emit_ops_affected(&app, &result.result.affected_ops, &result.result.changed);
Ok(result)
}
-/// Atomically replaces a pending optimistic layer with the real network
-/// response and flushes contiguous settled layers durably.
+/// Claims the oldest runnable queued mutation.
+#[tauri::command]
+pub async fn graphql_cache_claim_next_mutation(
+ state: State<'_, CacheState>,
+ owner: String,
+ now_ms: i64,
+ lease_expires_at_ms: i64,
+) -> Result<Option<ClaimedMutationWire>, String> {
+ engine_handle(&state)?
+ .claim_next_mutation(owner, now_ms, lease_expires_at_ms)
+ .await
+}
+
+/// Retains a retryable queued mutation and releases its lease.
+#[tauri::command]
+pub async fn graphql_cache_defer_optimistic_write(
+ state: State<'_, CacheState>,
+ transaction_id: String,
+ lease_owner: String,
+ lease_generation: String,
+ next_attempt_at_ms: i64,
+ error: String,
+) -> Result<(), String> {
+ engine_handle(&state)?
+ .defer_optimistic_write(
+ transaction_id,
+ lease_owner,
+ lease_generation,
+ next_attempt_at_ms,
+ error,
+ )
+ .await
+}
+
+/// Atomically replaces a claimed optimistic layer with the real response.
#[tauri::command]
pub async fn graphql_cache_commit_optimistic_write<R: Runtime>(
app: AppHandle<R>,
state: State<'_, CacheState>,
transaction_id: String,
+ lease_owner: String,
+ lease_generation: String,
query: String,
operation_name: Option<String>,
variables: Option<Variables>,
@@ -146,6 +184,8 @@ pub async fn graphql_cache_commit_optimistic_write<R: Runtime>(
let result = engine_handle(&state)?
.commit_optimistic_write(
transaction_id,
+ lease_owner,
+ lease_generation,
query,
operation_name,
variables.unwrap_or_default(),
@@ -156,15 +196,17 @@ pub async fn graphql_cache_commit_optimistic_write<R: Runtime>(
Ok(result)
}
-/// Drops a pending optimistic layer's contribution (mutation failed).
+/// Permanently fails a claimed mutation and drops its optimistic layer.
#[tauri::command]
pub async fn graphql_cache_rollback_optimistic_write<R: Runtime>(
app: AppHandle<R>,
state: State<'_, CacheState>,
transaction_id: String,
+ lease_owner: String,
+ lease_generation: String,
) -> Result<WriteResultWire, String> {
let result = engine_handle(&state)?
- .rollback_optimistic_write(transaction_id)
+ .rollback_optimistic_write(transaction_id, lease_owner, lease_generation)
.await?;
emit_ops_affected(&app, &result.affected_ops, &result.changed);
Ok(result)
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine.rs b/apps/web/tauri/graphql_cache_plugin/src/engine.rs
index c32baa0e41..c9632e8691 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine.rs
@@ -13,6 +13,7 @@
use cache_core::deps::OpId;
use cache_core::engine::{Engine, ReadResult, WriteResult};
+use cache_core::queue::{ClaimedMutation, MutationClaimRequest, MutationClaimToken};
use cache_core::value::EntityKey;
use cache_sqlite::SqliteStorage;
use serde::Serialize;
@@ -59,6 +60,43 @@ pub struct OptimisticWriteResultWire {
pub result: WriteResultWire,
}
+/// Claimed queue head returned to the JavaScript mutation runner.
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ClaimedMutationWire {
+ /// Durable mutation id.
+ pub transaction_id: String,
+ /// Claim generation required for settlement.
+ pub lease_generation: String,
+ /// GraphQL mutation document.
+ pub query: String,
+ /// Selected operation name.
+ pub operation_name: Option<String>,
+ /// Variables parsed from their durable canonical JSON representation.
+ pub variables: serde_json::Value,
+ /// Identity witness captured when the mutation was enqueued.
+ pub identity: Option<String>,
+ /// Number of network attempts including this claim.
+ pub attempt_count: u32,
+}
+
+impl TryFrom<ClaimedMutation> for ClaimedMutationWire {
+ type Error = String;
+
+ fn try_from(claimed: ClaimedMutation) -> Result<Self, Self::Error> {
+ let request = claimed.queued.mutation.request;
+ Ok(Self {
+ transaction_id: claimed.queued.id.to_string(),
+ lease_generation: claimed.lease_generation.to_string(),
+ query: request.query,
+ operation_name: request.operation_name,
+ variables: serde_json::from_str(&request.variables_json).map_err(|e| e.to_string())?,
+ identity: request.identity,
+ attempt_count: claimed.queued.mutation.attempt_count,
+ })
+ }
+}
+
/// Interns host-side string operation ids to engine `u64` ids.
#[derive(Default)]
struct OpInterner {
@@ -116,9 +154,14 @@ fn wire_write_result(ops: &OpInterner, result: WriteResult) -> WriteResultWire {
}
}
+fn parse_u64(value: &str, label: &str) -> Result<u64, String> {
+ value
+ .parse::<u64>()
+ .map_err(|_| format!("invalid {label} `{value}`"))
+}
+
fn parse_transaction_id(id: &str) -> Result<u64, String> {
- id.parse::<u64>()
- .map_err(|_| format!("invalid optimistic transaction id `{id}`"))
+ parse_u64(id, "optimistic transaction id")
}
impl EngineHandle {
@@ -185,7 +228,7 @@ impl EngineHandle {
.map_err(|e| e.to_string())
}
- /// Installs an in-memory optimistic layer (persists nothing).
+ /// Durably queues a mutation and its optimistic layer.
pub async fn begin_optimistic_write(
&self,
origin_op_id: Option<String>,
@@ -193,12 +236,20 @@ impl EngineHandle {
operation_name: Option<String>,
variables: Variables,
data: serde_json::Value,
+ created_at_ms: i64,
) -> Result<OptimisticWriteResultWire, String> {
let mut state = self.inner.lock().await;
let EngineState { engine, ops } = &mut *state;
let origin = origin_op_id.map(|name| ops.intern(&name));
engine
- .begin_optimistic_write(origin, &query, operation_name.as_deref(), &variables, &data)
+ .begin_optimistic_write(
+ origin,
+ &query,
+ operation_name.as_deref(),
+ &variables,
+ &data,
+ created_at_ms,
+ )
.await
.map(|(transaction, result)| OptimisticWriteResultWire {
transaction_id: transaction.to_string(),
@@ -207,21 +258,72 @@ impl EngineHandle {
.map_err(|e| e.to_string())
}
- /// Replaces a pending optimistic layer with the real network response.
+ /// Claims the strict mutation queue head when it is runnable.
+ pub async fn claim_next_mutation(
+ &self,
+ owner: String,
+ now_ms: i64,
+ lease_expires_at_ms: i64,
+ ) -> Result<Option<ClaimedMutationWire>, String> {
+ let mut state = self.inner.lock().await;
+ state
+ .engine
+ .claim_next_mutation(MutationClaimRequest {
+ owner,
+ now_ms,
+ lease_expires_at_ms,
+ })
+ .await
+ .map_err(|e| e.to_string())?
+ .map(ClaimedMutationWire::try_from)
+ .transpose()
+ }
+
+ /// Retains a retryable mutation and releases its claim.
+ pub async fn defer_optimistic_write(
+ &self,
+ transaction_id: String,
+ lease_owner: String,
+ lease_generation: String,
+ next_attempt_at_ms: i64,
+ error: String,
+ ) -> Result<(), String> {
+ let transaction = parse_transaction_id(&transaction_id)?;
+ let claim = MutationClaimToken {
+ owner: lease_owner,
+ generation: parse_u64(&lease_generation, "lease generation")?,
+ };
+ self.inner
+ .lock()
+ .await
+ .engine
+ .defer_optimistic_write(transaction, claim, next_attempt_at_ms, error)
+ .await
+ .map_err(|e| e.to_string())
+ }
+
+ /// Replaces a claimed optimistic layer with the real network response.
pub async fn commit_optimistic_write(
&self,
transaction_id: String,
+ lease_owner: String,
+ lease_generation: String,
query: String,
operation_name: Option<String>,
variables: Variables,
data: serde_json::Value,
) -> Result<WriteResultWire, String> {
let transaction = parse_transaction_id(&transaction_id)?;
+ let claim = MutationClaimToken {
+ owner: lease_owner,
+ generation: parse_u64(&lease_generation, "lease generation")?,
+ };
let mut state = self.inner.lock().await;
let EngineState { engine, ops } = &mut *state;
engine
.commit_optimistic_write(
transaction,
+ claim,
&query,
operation_name.as_deref(),
&variables,
@@ -232,16 +334,22 @@ impl EngineHandle {
.map_err(|e| e.to_string())
}
- /// Drops a pending optimistic layer's contribution (mutation failed).
+ /// Permanently fails a claimed mutation and drops its optimistic layer.
pub async fn rollback_optimistic_write(
&self,
transaction_id: String,
+ lease_owner: String,
+ lease_generation: String,
) -> Result<WriteResultWire, String> {
let transaction = parse_transaction_id(&transaction_id)?;
+ let claim = MutationClaimToken {
+ owner: lease_owner,
+ generation: parse_u64(&lease_generation, "lease generation")?,
+ };
let mut state = self.inner.lock().await;
let EngineState { engine, ops } = &mut *state;
engine
- .rollback_optimistic_write(transaction)
+ .rollback_optimistic_write(transaction, claim)
.await
.map(|result| wire_write_result(ops, result))
.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 b5020c2e5e..715953ac9b 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
@@ -57,6 +57,12 @@ fn read(handle: &EngineHandle, op_id: Option<&str>) -> ReadResultWire {
.unwrap()
}
+fn claim(handle: &EngineHandle) -> ClaimedMutationWire {
+ block_on(handle.claim_next_mutation("runner".to_string(), 10, 1_000))
+ .unwrap()
+ .expect("queue head")
+}
+
#[test]
fn write_then_read_round_trips() {
let handle = spawn_handle();
@@ -112,6 +118,7 @@ fn optimistic_layer_commits_durably() {
Some("Soup".to_string()),
variables(),
soup_data(true),
+ 0,
))
.unwrap();
assert_eq!(optimistic.result.affected_ops, vec!["client:1".to_string()]);
@@ -122,8 +129,11 @@ fn optimistic_layer_commits_durably() {
};
assert_eq!(data, soup_data(true));
+ let claimed = claim(&handle);
let committed = block_on(handle.commit_optimistic_write(
optimistic.transaction_id,
+ "runner".to_string(),
+ claimed.lease_generation,
QUERY.to_string(),
Some("Soup".to_string()),
variables(),
@@ -149,10 +159,17 @@ fn rollback_drops_optimistic_contribution() {
Some("Soup".to_string()),
variables(),
soup_data(true),
+ 0,
))
.unwrap();
- block_on(handle.rollback_optimistic_write(optimistic.transaction_id)).unwrap();
+ let claimed = claim(&handle);
+ block_on(handle.rollback_optimistic_write(
+ optimistic.transaction_id,
+ "runner".to_string(),
+ claimed.lease_generation,
+ ))
+ .unwrap();
let ReadResultWire::Hit { data } = read(&handle, None) else {
panic!("expected hit");
};
@@ -180,6 +197,11 @@ fn clear_wipes_everything() {
#[test]
fn bad_transaction_id_is_an_error() {
let handle = spawn_handle();
- let error = block_on(handle.rollback_optimistic_write("not-a-number".to_string())).unwrap_err();
+ let error = block_on(handle.rollback_optimistic_write(
+ "not-a-number".to_string(),
+ "runner".to_string(),
+ "1".to_string(),
+ ))
+ .unwrap_err();
assert!(error.contains("invalid optimistic transaction id"));
}
diff --git a/apps/web/tauri/graphql_cache_plugin/src/lib.rs b/apps/web/tauri/graphql_cache_plugin/src/lib.rs
index 8a84213820..8e719d34e3 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/lib.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/lib.rs
@@ -22,7 +22,9 @@ use tauri::{AppHandle, Emitter, Runtime};
pub mod commands;
mod engine;
-pub use engine::{EngineHandle, OptimisticWriteResultWire, ReadResultWire, WriteResultWire};
+pub use engine::{
+ ClaimedMutationWire, EngineHandle, OptimisticWriteResultWire, ReadResultWire, WriteResultWire,
+};
/// Broadcast event carrying [`OpsAffectedEvent`]: operations whose
/// underlying records changed. Emitted to every webview; hosts filter by
diff --git a/apps/web/tauri/src-tauri/src/lib.rs b/apps/web/tauri/src-tauri/src/lib.rs
index 42d5710201..e870565c63 100644
--- a/apps/web/tauri/src-tauri/src/lib.rs
+++ b/apps/web/tauri/src-tauri/src/lib.rs
@@ -230,6 +230,8 @@ pub fn run() {
graphql_cache_plugin::commands::graphql_cache_read,
graphql_cache_plugin::commands::graphql_cache_write,
graphql_cache_plugin::commands::graphql_cache_begin_optimistic_write,
+ graphql_cache_plugin::commands::graphql_cache_claim_next_mutation,
+ graphql_cache_plugin::commands::graphql_cache_defer_optimistic_write,
graphql_cache_plugin::commands::graphql_cache_commit_optimistic_write,
graphql_cache_plugin::commands::graphql_cache_rollback_optimistic_write,
graphql_cache_plugin::commands::graphql_cache_invalidate,
diff --git a/crates/client/README.md b/crates/client/README.md
index 87cea93753..1ed08e6790 100644
--- a/crates/client/README.md
+++ b/crates/client/README.md
@@ -7,7 +7,7 @@ Normalized GraphQL cache with disk-backed persistence for urql. Design doc:
| Crate | Purpose |
|---|---|
-| `cache-core` | Pure engine: schema-metadata codegen (build.rs from `static_assets/schema.graphql`), normalize/denormalize, LRU hot tier, dependency index, async `Storage` trait |
+| `cache-core` | Pure engine: normalize/denormalize, LRU hot tier, dependency index, durable ordered optimistic-mutation queue, async `Storage` trait |
| `cache-sqlite` | `Storage` over SQLite — Tauri native host |
| `cache-idb` | `Storage` over IndexedDB via the `idb` crate — browser wasm host (wasm32-only; empty shell elsewhere) |
| `cache-wasm` | wasm-bindgen shell exposing the engine to the browser worker glue (`apps/web/src/lib/graphql-cache/`) |
@@ -53,3 +53,8 @@ because a property instance's value is per-entity).
Identity is not the cache's concern: the engine accepts an opaque session
tag on writes (extracted by the urql exchange from `data.user.id`) and
wipes + rebinds atomically when the tag changes (silent restart).
+
+Optimistic GraphQL mutations are persisted with their replay request before
+becoming visible. The exchange claims and applies them strictly in enqueue
+order; a configurable callback decides whether an error remains queued or
+permanently rolls back.
diff --git a/crates/client/cache-core/src/codec.rs b/crates/client/cache-core/src/codec.rs
index 46ed91a52a..3cea1db9f7 100644
--- a/crates/client/cache-core/src/codec.rs
+++ b/crates/client/cache-core/src/codec.rs
@@ -4,7 +4,10 @@
//! format or schema change starts a fresh cache instead of attempting
//! migration (the cache is disposable by design).
+use crate::normalize::RecordUpdates;
+use crate::queue::{PersistedOptimisticLayer, StoredMutation};
use crate::value::Record;
+use serde::{Serialize, de::DeserializeOwned};
use thiserror::Error;
/// Bump when the stored representation of [`Record`]/[`CacheValue`]
@@ -13,17 +16,55 @@ pub const CACHE_FORMAT_VERSION: u32 = 1;
#[derive(Debug, Error)]
pub enum CodecError {
- #[error("corrupt record: {0}")]
+ #[error("corrupt cache payload: {0}")]
Corrupt(#[from] postcard::Error),
}
+fn encode<T: Serialize>(value: &T) -> Vec<u8> {
+ // Serialization of an in-memory cache value cannot fail.
+ postcard::to_allocvec(value).expect("cache value serializes")
+}
+
+fn decode<T: DeserializeOwned>(bytes: &[u8]) -> Result<T, CodecError> {
+ Ok(postcard::from_bytes(bytes)?)
+}
+
pub fn encode_record(record: &Record) -> Vec<u8> {
- // Serialization of an in-memory record cannot fail.
- postcard::to_allocvec(record).expect("record serializes")
+ encode(record)
}
pub fn decode_record(bytes: &[u8]) -> Result<Record, CodecError> {
- Ok(postcard::from_bytes(bytes)?)
+ decode(bytes)
+}
+
+/// Encodes one queued mutation's request and retry metadata.
+pub fn encode_stored_mutation(mutation: &StoredMutation) -> Vec<u8> {
+ encode(mutation)
+}
+
+/// Decodes one queued mutation's request and retry metadata.
+pub fn decode_stored_mutation(bytes: &[u8]) -> Result<StoredMutation, CodecError> {
+ decode(bytes)
+}
+
+/// Encodes one persisted optimistic layer.
+pub fn encode_optimistic_layer(layer: &PersistedOptimisticLayer) -> Vec<u8> {
+ encode(layer)
+}
+
+/// Decodes one persisted optimistic layer.
+pub fn decode_optimistic_layer(bytes: &[u8]) -> Result<PersistedOptimisticLayer, CodecError> {
+ decode(bytes)
+}
+
+/// Encodes normalized updates independently for relational backends.
+pub fn encode_record_updates(updates: &RecordUpdates) -> Vec<u8> {
+ encode(updates)
+}
+
+/// Decodes normalized updates independently for relational backends.
+pub fn decode_record_updates(bytes: &[u8]) -> Result<RecordUpdates, CodecError> {
+ decode(bytes)
}
/// Canonical database/namespace name for a cache instance.
@@ -35,6 +76,15 @@ pub fn cache_namespace(scope: &str) -> String {
)
}
+/// Stable physical database name for a cache scope.
+///
+/// Unlike [`cache_namespace`], this deliberately excludes the record schema
+/// and format versions. Normalized records are disposable on version changes,
+/// while queued mutations represent user intent and must remain discoverable.
+pub fn cache_database_name(scope: &str) -> String {
+ format!("graphql-cache:{scope}")
+}
+
#[cfg(test)]
mod tests {
use super::*;
diff --git a/crates/client/cache-core/src/engine.rs b/crates/client/cache-core/src/engine.rs
index cee1bcd6ae..8a7b528a8d 100644
--- a/crates/client/cache-core/src/engine.rs
+++ b/crates/client/cache-core/src/engine.rs
@@ -6,8 +6,12 @@ use crate::denormalize::{DenormalizeError, ReadOutcome, RecordSource, denormaliz
use crate::deps::{DepIndex, OpId};
use crate::document::{Document, DocumentError, OperationKind};
use crate::normalize::{NormalizeError, RecordUpdates, normalize};
+use crate::queue::{
+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationRequest,
+ NewQueuedMutation, PersistedOptimisticLayer, QueuedMutation, StoredMutation,
+};
use crate::store::Storage;
-use crate::value::{EntityKey, Record};
+use crate::value::{EntityKey, Record, canonical_json};
use lru::LruCache;
use serde_json::Value as Json;
use std::collections::{BTreeMap, BTreeSet, HashMap};
@@ -24,6 +28,13 @@ pub enum EngineError<S: std::error::Error + 'static> {
Denormalize(#[from] DenormalizeError),
#[error("unknown or already-settled optimistic transaction {0}")]
UnknownTransaction(OptimisticTransactionId),
+ #[error("stale claim for optimistic transaction {0}")]
+ StaleMutationClaim(OptimisticTransactionId),
+ #[error("invalid queued mutation {id}: {detail}")]
+ InvalidQueuedMutation {
+ id: OptimisticTransactionId,
+ detail: String,
+ },
#[error("storage: {0}")]
Storage(#[source] S),
}
@@ -56,46 +67,15 @@ pub struct WriteResult {
/// Engine-assigned id of one optimistic mutation transaction. Never reuse
/// host operation keys: identical concurrent mutations share an urql key,
/// but each needs its own layer.
-pub type OptimisticTransactionId = u64;
+pub type OptimisticTransactionId = MutationId;
-/// One optimistic mutation's contribution to the cache view. Layers are
-/// ordered by creation; later layers override earlier ones field-by-field,
-/// all of them override the durable base. Nothing in a layer is persisted
-/// until the layer settles *and* every earlier layer has settled too
-/// (contiguous-prefix flushing keeps out-of-order settlement correct).
+/// One queued optimistic mutation's contribution to the cache view. Layers
+/// are persisted and ordered by their mutation ids; only the strict queue
+/// head can be claimed and settled.
+#[derive(Clone)]
struct OptimisticLayer {
id: OptimisticTransactionId,
- state: OptimisticLayerState,
-}
-
-enum OptimisticLayerState {
- /// Awaiting the network result; `updates` normalized from the
- /// optimistic response.
- Pending { updates: RecordUpdates },
- /// Network result arrived; `updates` replaced by the real response.
- /// Held in-memory until the layer reaches the settled prefix.
- Succeeded { updates: RecordUpdates },
- /// Rolled back. Kept as an ordered tombstone (contributing nothing)
- /// until earlier layers settle, then dropped by the prefix flush.
- Failed,
-}
-
-impl OptimisticLayer {
- /// The record updates this layer currently contributes to reads.
- fn updates(&self) -> Option<&RecordUpdates> {
- match &self.state {
- OptimisticLayerState::Pending { updates }
- | OptimisticLayerState::Succeeded { updates } => Some(updates),
- OptimisticLayerState::Failed => None,
- }
- }
-
- fn settled(&self) -> bool {
- matches!(
- self.state,
- OptimisticLayerState::Succeeded { .. } | OptimisticLayerState::Failed
- )
- }
+ updates: RecordUpdates,
}
/// Reserved storage key holding the identity bound to this cache. The
@@ -126,10 +106,9 @@ pub struct Engine<S: Storage> {
docs: HashMap<String, Document>,
deps: DepIndex,
identity: IdentityState,
- /// Ordered optimistic mutation layers (memory-only; see
- /// [`OptimisticLayer`]).
+ /// Ordered optimistic mutation layers hydrated from durable storage.
optimistic: Vec<OptimisticLayer>,
- next_transaction: OptimisticTransactionId,
+ optimistic_hydrated: bool,
}
impl<S: Storage> Engine<S> {
@@ -145,8 +124,91 @@ impl<S: Storage> Engine<S> {
deps: DepIndex::new(),
identity: IdentityState::NotHydrated,
optimistic: Vec::new(),
- next_transaction: 0,
+ optimistic_hydrated: false,
+ }
+ }
+
+ /// Hydrates durable optimistic layers before the first operation. Queue
+ /// order is the optimistic composition order.
+ async fn hydrate_optimistic(&mut self) -> Result<(), EngineError<S::Error>> {
+ if self.optimistic_hydrated {
+ return Ok(());
}
+ let queued = self
+ .storage
+ .load_mutation_queue()
+ .await
+ .map_err(EngineError::Storage)?;
+ self.optimistic = Self::normalize_queued_layers(&mut self.docs, queued)?;
+ self.optimistic_hydrated = true;
+ Ok(())
+ }
+
+ /// Reloads durable optimistic layers after another engine sharing this
+ /// storage changes the queue. Returns operations whose effective view
+ /// changed.
+ pub async fn refresh_optimistic_queue(&mut self) -> Result<WriteResult, EngineError<S::Error>> {
+ let queued = self
+ .storage
+ .load_mutation_queue()
+ .await
+ .map_err(EngineError::Storage)?;
+ let replacement = Self::normalize_queued_layers(&mut self.docs, queued)?;
+ let candidates: BTreeSet<EntityKey> = self
+ .optimistic
+ .iter()
+ .chain(&replacement)
+ .flat_map(|layer| layer.updates.keys().cloned())
+ .collect();
+ let bases = self.load_bases(&candidates).await?;
+ let before = effective_records(&bases, &self.optimistic, &candidates);
+ self.optimistic = replacement;
+ self.optimistic_hydrated = true;
+ let after = effective_records(&bases, &self.optimistic, &candidates);
+ let changed: BTreeSet<EntityKey> = candidates
+ .into_iter()
+ .filter(|key| before.get(key) != after.get(key))
+ .collect();
+ let affected_ops = self.deps.ops_for_keys(changed.iter());
+ Ok(WriteResult {
+ changed,
+ affected_ops,
+ reset: false,
+ })
+ }
+
+ fn normalize_queued_layers(
+ docs: &mut HashMap<String, Document>,
+ queued: Vec<QueuedMutation>,
+ ) -> Result<Vec<OptimisticLayer>, EngineError<S::Error>> {
+ queued
+ .into_iter()
+ .map(|queued| {
+ let variables: Json = serde_json::from_str(&queued.mutation.request.variables_json)
+ .map_err(|error| EngineError::InvalidQueuedMutation {
+ id: queued.id,
+ detail: format!("invalid variables: {error}"),
+ })?;
+ let Json::Object(variables) = variables else {
+ return Err(EngineError::InvalidQueuedMutation {
+ id: queued.id,
+ detail: "variables are not an object".to_string(),
+ });
+ };
+ let data: Json = serde_json::from_str(&queued.optimistic.optimistic_data_json)
+ .map_err(|error| EngineError::InvalidQueuedMutation {
+ id: queued.id,
+ detail: format!("invalid optimistic response: {error}"),
+ })?;
+ let document = Self::document(docs, &queued.mutation.request.query)?;
+ let operation =
+ document.operation(queued.mutation.request.operation_name.as_deref())?;
+ Ok(OptimisticLayer {
+ id: queued.id,
+ updates: normalize(operation, &variables, &data)?,
+ })
+ })
+ .collect()
}
/// The identity binding of this cache, hydrating it from storage on
@@ -197,6 +259,7 @@ impl<S: Storage> Engine<S> {
operation_name: Option<&str>,
variables: &serde_json::Map<String, Json>,
) -> Result<ReadResult, EngineError<S::Error>> {
+ self.hydrate_optimistic().await?;
let doc = Self::document(&mut self.docs, query)?;
let op = doc.operation(operation_name)?;
if op.kind != OperationKind::Query {
@@ -308,6 +371,7 @@ impl<S: Storage> Engine<S> {
data: &Json,
identity: Option<&str>,
) -> Result<WriteResult, EngineError<S::Error>> {
+ self.hydrate_optimistic().await?;
let doc = Self::document(&mut self.docs, query)?;
let op = doc.operation(operation_name)?;
let updates = normalize(op, variables, data)?;
@@ -323,6 +387,7 @@ impl<S: Storage> Engine<S> {
// A different user's session: in-flight optimistic
// mutations belong to the old identity — discard them.
self.optimistic.clear();
+ self.optimistic_hydrated = true;
self.storage.clear().await.map_err(EngineError::Storage)?;
self.bind_identity(observed).await?;
reset = true;
@@ -412,13 +477,9 @@ impl<S: Storage> Engine<S> {
Ok(changed)
}
- /// Installs a new optimistic layer from a mutation's optimistic
- /// response. Persists nothing. Returns the transaction id plus a
- /// [`WriteResult`] whose `changed` keys are the entities whose
- /// *effective visible* data changed (`affected_ops` excludes
- /// `origin_op`). The layer stays in memory until
- /// [`commit_optimistic_write`](Self::commit_optimistic_write) or
- /// [`rollback_optimistic_write`](Self::rollback_optimistic_write).
+ /// Atomically enqueues a mutation together with its optimistic layer.
+ /// The layer is durable before it becomes visible or the caller is
+ /// allowed to forward the mutation to the network.
pub async fn begin_optimistic_write(
&mut self,
origin_op: Option<OpId>,
@@ -426,7 +487,9 @@ impl<S: Storage> Engine<S> {
operation_name: Option<&str>,
variables: &serde_json::Map<String, Json>,
data: &Json,
+ created_at_ms: i64,
) -> Result<(OptimisticTransactionId, WriteResult), EngineError<S::Error>> {
+ self.hydrate_optimistic().await?;
let doc = Self::document(&mut self.docs, query)?;
let op = doc.operation(operation_name)?;
let updates = normalize(op, variables, data)?;
@@ -434,18 +497,35 @@ impl<S: Storage> Engine<S> {
let candidates: BTreeSet<EntityKey> = updates.keys().cloned().collect();
let bases = self.load_bases(&candidates).await?;
let before = effective_records(&bases, &self.optimistic, &candidates);
-
- self.next_transaction += 1;
- let id = self.next_transaction;
- self.optimistic.push(OptimisticLayer {
- id,
- state: OptimisticLayerState::Pending { updates },
- });
+ let identity = match self.bound_identity().await? {
+ IdentityState::Bound(identity) => Some(identity),
+ IdentityState::NotHydrated | IdentityState::Missing => None,
+ };
+ let id = self
+ .storage
+ .enqueue_mutation(NewQueuedMutation {
+ mutation: StoredMutation::new(
+ MutationRequest {
+ query: query.to_string(),
+ operation_name: operation_name.map(str::to_string),
+ variables_json: canonical_json(&Json::Object(variables.clone())),
+ identity,
+ },
+ created_at_ms,
+ ),
+ optimistic: PersistedOptimisticLayer {
+ optimistic_data_json: canonical_json(data),
+ normalized_updates: updates.clone(),
+ },
+ })
+ .await
+ .map_err(EngineError::Storage)?;
+ self.optimistic.push(OptimisticLayer { id, updates });
let after = effective_records(&bases, &self.optimistic, &candidates);
let changed: BTreeSet<EntityKey> = candidates
.into_iter()
- .filter(|k| before.get(k) != after.get(k))
+ .filter(|key| before.get(key) != after.get(key))
.collect();
let mut affected_ops = self.deps.ops_for_keys(changed.iter());
if let Some(origin) = origin_op {
@@ -461,116 +541,134 @@ impl<S: Storage> Engine<S> {
))
}
- /// Replaces a pending layer's optimistic updates with the normalized
- /// real network response and marks it succeeded — atomically, so
- /// dependents never flicker back to pre-optimistic data. Flushes the
- /// contiguous settled prefix of layers into durable storage.
- ///
- /// The returned `changed` keys are the *durably* changed records (for
- /// cross-instance broadcast); `affected_ops` are the operations whose
- /// effective visible data changed (for local re-execution).
+ /// Claims the oldest runnable mutation. A leased or backed-off head
+ /// blocks every later mutation.
+ pub async fn claim_next_mutation(
+ &mut self,
+ request: MutationClaimRequest,
+ ) -> Result<Option<ClaimedMutation>, EngineError<S::Error>> {
+ self.hydrate_optimistic().await?;
+ self.storage
+ .claim_next_mutation(request)
+ .await
+ .map_err(EngineError::Storage)
+ }
+
+ /// Releases a retryable mutation while retaining its optimistic layer.
+ pub async fn defer_optimistic_write(
+ &mut self,
+ transaction: OptimisticTransactionId,
+ claim: MutationClaimToken,
+ next_attempt_at_ms: i64,
+ error: String,
+ ) -> Result<(), EngineError<S::Error>> {
+ self.hydrate_optimistic().await?;
+ if !self
+ .storage
+ .defer_mutation(transaction, claim, next_attempt_at_ms, error)
+ .await
+ .map_err(EngineError::Storage)?
+ {
+ return Err(EngineError::StaleMutationClaim(transaction));
+ }
+ Ok(())
+ }
+
+ /// Replaces the claimed head's optimistic contribution with the real
+ /// network response without flickering through the pre-mutation value.
+ /// Real records and queue deletion commit in one storage transaction.
pub async fn commit_optimistic_write(
&mut self,
transaction: OptimisticTransactionId,
+ claim: MutationClaimToken,
query: &str,
operation_name: Option<&str>,
variables: &serde_json::Map<String, Json>,
data: &Json,
) -> Result<WriteResult, EngineError<S::Error>> {
+ self.hydrate_optimistic().await?;
+ let index = self
+ .optimistic
+ .iter()
+ .position(|layer| layer.id == transaction)
+ .ok_or(EngineError::UnknownTransaction(transaction))?;
let doc = Self::document(&mut self.docs, query)?;
let op = doc.operation(operation_name)?;
let updates = normalize(op, variables, data)?;
- self.settle_layer(transaction, OptimisticLayerState::Succeeded { updates })
- .await
- }
- /// Marks a pending layer failed, removing its contribution from the
- /// effective view, and flushes any now-contiguous settled prefix. The
- /// failed layer remains an ordered tombstone until all earlier layers
- /// settle. Result semantics match
- /// [`commit_optimistic_write`](Self::commit_optimistic_write).
- pub async fn rollback_optimistic_write(
- &mut self,
- transaction: OptimisticTransactionId,
- ) -> Result<WriteResult, EngineError<S::Error>> {
- self.settle_layer(transaction, OptimisticLayerState::Failed)
+ let mut candidates: BTreeSet<EntityKey> =
+ self.optimistic[index].updates.keys().cloned().collect();
+ candidates.extend(updates.keys().cloned());
+ let bases = self.load_bases(&candidates).await?;
+ let before = effective_records(&bases, &self.optimistic, &candidates);
+ let (durable_changed, entries) = stage_updates(&bases, updates);
+ if !self
+ .storage
+ .complete_mutation(transaction, claim, entries.clone())
.await
+ .map_err(EngineError::Storage)?
+ {
+ return Err(EngineError::StaleMutationClaim(transaction));
+ }
+
+ let mut settled_bases = bases;
+ for (key, record) in entries {
+ settled_bases.insert(key.clone(), record.clone());
+ self.hot.put(key, record);
+ }
+ self.optimistic.remove(index);
+ let after = effective_records(&settled_bases, &self.optimistic, &candidates);
+ let visible_changed: BTreeSet<EntityKey> = candidates
+ .into_iter()
+ .filter(|key| before.get(key) != after.get(key))
+ .collect();
+ let affected_ops = self.deps.ops_for_keys(visible_changed.iter());
+ Ok(WriteResult {
+ changed: durable_changed,
+ affected_ops,
+ reset: false,
+ })
}
- async fn settle_layer(
+ /// Permanently fails the claimed head, atomically removing its queue row
+ /// and optimistic layer.
+ pub async fn rollback_optimistic_write(
&mut self,
transaction: OptimisticTransactionId,
- new_state: OptimisticLayerState,
+ claim: MutationClaimToken,
) -> Result<WriteResult, EngineError<S::Error>> {
+ self.hydrate_optimistic().await?;
let index = self
.optimistic
.iter()
- .position(|l| l.id == transaction && !l.settled())
+ .position(|layer| layer.id == transaction)
.ok_or(EngineError::UnknownTransaction(transaction))?;
-
- // Keys whose effective value may change: everything the old
- // (optimistic) or new (real) updates touch.
- let mut candidates: BTreeSet<EntityKey> = self.optimistic[index]
- .updates()
- .map(|u| u.keys().cloned().collect())
- .unwrap_or_default();
- if let OptimisticLayerState::Succeeded { updates } = &new_state {
- candidates.extend(updates.keys().cloned());
- }
-
+ let candidates: BTreeSet<EntityKey> =
+ self.optimistic[index].updates.keys().cloned().collect();
let bases = self.load_bases(&candidates).await?;
let before = effective_records(&bases, &self.optimistic, &candidates);
- self.optimistic[index].state = new_state;
+ if !self
+ .storage
+ .discard_mutation(transaction, claim)
+ .await
+ .map_err(EngineError::Storage)?
+ {
+ return Err(EngineError::StaleMutationClaim(transaction));
+ }
+ self.optimistic.remove(index);
let after = effective_records(&bases, &self.optimistic, &candidates);
let visible_changed: BTreeSet<EntityKey> = candidates
.into_iter()
- .filter(|k| before.get(k) != after.get(k))
+ .filter(|key| before.get(key) != after.get(key))
.collect();
-
- // Flush the contiguous settled prefix into durable storage. The
- // flushed data was already visible through the layers, so this does
- // not change the effective view and adds no local notifications;
- // the durably changed keys it returns drive cross-instance
- // broadcasts.
- let durable_changed = self.flush_settled_prefix().await?;
-
let affected_ops = self.deps.ops_for_keys(visible_changed.iter());
Ok(WriteResult {
- changed: durable_changed,
+ changed: BTreeSet::new(),
affected_ops,
reset: false,
})
}
- /// Persists and drops the leading run of settled layers. Succeeded
- /// layers' updates merge into durable storage (in layer order); failed
- /// layers are dropped. Later pending layers keep overriding the newly
- /// committed base, preserving order under out-of-order settlement.
- async fn flush_settled_prefix(&mut self) -> Result<BTreeSet<EntityKey>, EngineError<S::Error>> {
- let mut merged = RecordUpdates::new();
- let mut count = 0;
- for layer in &self.optimistic {
- if !layer.settled() {
- break;
- }
- if let Some(updates) = layer.updates() {
- for (key, record) in updates {
- merged.entry(key.clone()).or_default().merge(record.clone());
- }
- }
- count += 1;
- }
- if count == 0 {
- return Ok(BTreeSet::new());
- }
- self.optimistic.drain(..count);
- if merged.is_empty() {
- // Prefix was all tombstones.
- return Ok(BTreeSet::new());
- }
- self.persist_updates(merged).await
- }
-
/// Loads current durable records (hot tier, then storage) for `keys`
/// without touching LRU recency or persisting anything.
async fn load_bases(
@@ -608,9 +706,10 @@ impl<S: Storage> Engine<S> {
pub fn external_reset(&mut self) -> BTreeSet<OpId> {
self.hot.clear();
self.docs.clear();
- // Optimistic layers were normalized against the wiped base.
self.optimistic.clear();
- // Another engine may have rebound the shared storage → re-hydrate.
+ // Another engine may have rebound the shared storage and changed the
+ // durable queue, so both identity and optimism must re-hydrate.
+ self.optimistic_hydrated = false;
self.identity = IdentityState::NotHydrated;
self.deps.all_ops()
}
@@ -641,6 +740,7 @@ impl<S: Storage> Engine<S> {
pub async fn clear(&mut self) -> Result<(), EngineError<S::Error>> {
self.hot.clear();
self.optimistic.clear();
+ self.optimistic_hydrated = true;
self.deps = DepIndex::new();
// The wipe below removes the binding record too.
self.identity = IdentityState::Missing;
@@ -697,15 +797,41 @@ impl RecordSource for EngineSource<'_> {
fn merged_optimistic(layers: &[OptimisticLayer]) -> BTreeMap<EntityKey, Record> {
let mut out: BTreeMap<EntityKey, Record> = BTreeMap::new();
for layer in layers {
- if let Some(updates) = layer.updates() {
- for (key, record) in updates {
- out.entry(key.clone()).or_default().merge(record.clone());
- }
+ for (key, record) in &layer.updates {
+ out.entry(key.clone()).or_default().merge(record.clone());
}
}
out
}
+/// Merges partial response updates into already-loaded durable bases without
+/// mutating the hot tier or storage. The caller can then atomically settle a
+/// queued mutation before publishing the staged records in memory.
+fn stage_updates(
+ bases: &HashMap<EntityKey, Record>,
+ updates: RecordUpdates,
+) -> (BTreeSet<EntityKey>, Vec<(EntityKey, Record)>) {
+ let mut changed = BTreeSet::new();
+ let mut entries = Vec::with_capacity(updates.len());
+ for (key, update) in updates {
+ let merged = match bases.get(&key) {
+ Some(existing) => {
+ let mut merged = existing.clone();
+ if merged.merge(update) {
+ changed.insert(key.clone());
+ }
+ merged
+ }
+ None => {
+ changed.insert(key.clone());
+ update
+ }
+ };
+ entries.push((key, merged));
+ }
+ (changed, entries)
+}
+
/// Effective visible records for `keys`: durable base + every active layer
/// merged in order. `None` when the key exists nowhere.
fn effective_records(
@@ -717,7 +843,7 @@ fn effective_records(
.map(|key| {
let mut record: Option<Record> = bases.get(key).cloned();
for layer in layers {
- if let Some(update) = layer.updates().and_then(|u| u.get(key)) {
+ if let Some(update) = layer.updates.get(key) {
record
.get_or_insert_with(Record::default)
.merge(update.clone());
diff --git a/crates/client/cache-core/src/lib.rs b/crates/client/cache-core/src/lib.rs
index 73dbd9fb03..64bda7a914 100644
--- a/crates/client/cache-core/src/lib.rs
+++ b/crates/client/cache-core/src/lib.rs
@@ -9,5 +9,6 @@ pub mod document;
pub mod engine;
pub mod meta;
pub mod normalize;
+pub mod queue;
pub mod store;
pub mod value;
diff --git a/crates/client/cache-core/src/queue.rs b/crates/client/cache-core/src/queue.rs
new file mode 100644
index 0000000000..aec8f3c5be
--- /dev/null
+++ b/crates/client/cache-core/src/queue.rs
@@ -0,0 +1,121 @@
+//! Durable optimistic-mutation queue models.
+//!
+//! The cache engine owns mutation ordering and optimistic composition; storage
+//! backends persist these transport-neutral values atomically. Authentication
+//! credentials and urql operation context are deliberately excluded: replay
+//! reconstructs an operation using the current client configuration.
+
+use crate::normalize::RecordUpdates;
+use serde::{Deserialize, Serialize};
+
+/// Durable, monotonically increasing mutation identifier and queue position.
+pub type MutationId = u64;
+
+/// The serializable portion of a GraphQL mutation needed for replay.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct MutationRequest {
+ /// GraphQL mutation document text.
+ pub query: String,
+ /// Selected operation when the document contains named operations.
+ pub operation_name: Option<String>,
+ /// Canonical JSON object containing the mutation variables.
+ pub variables_json: String,
+ /// Opaque identity witness bound when the mutation was enqueued.
+ pub identity: Option<String>,
+}
+
+/// Persisted retry and lease state for one queued mutation.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct StoredMutation {
+ /// Replayable GraphQL request.
+ pub request: MutationRequest,
+ /// Number of times this mutation has been claimed for a network attempt.
+ pub attempt_count: u32,
+ /// Earliest wall-clock time at which the head may be claimed again.
+ pub next_attempt_at_ms: Option<i64>,
+ /// Owner of the current claim, if any.
+ pub lease_owner: Option<String>,
+ /// Monotonic generation used to reject stale attempt results.
+ pub lease_generation: u64,
+ /// Time at which the current claim becomes available to another owner.
+ pub lease_expires_at_ms: Option<i64>,
+ /// Last retryable network error, for diagnostics.
+ pub last_error: Option<String>,
+ /// Wall-clock enqueue time, for diagnostics.
+ pub created_at_ms: i64,
+}
+
+impl StoredMutation {
+ /// Creates an unclaimed queue row for `request`.
+ pub fn new(request: MutationRequest, created_at_ms: i64) -> Self {
+ Self {
+ request,
+ attempt_count: 0,
+ next_attempt_at_ms: None,
+ lease_owner: None,
+ lease_generation: 0,
+ lease_expires_at_ms: None,
+ last_error: None,
+ created_at_ms,
+ }
+ }
+}
+
+/// One durable optimistic layer paired one-to-one with a queued mutation.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct PersistedOptimisticLayer {
+ /// Canonical JSON optimistic response, retained for re-normalization after
+ /// a record-schema change.
+ pub optimistic_data_json: String,
+ /// Normalized contribution used to hydrate the effective cache view.
+ pub normalized_updates: RecordUpdates,
+}
+
+/// A mutation and optimistic layer before storage assigns its queue id.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct NewQueuedMutation {
+ /// Mutation request plus initial retry metadata.
+ pub mutation: StoredMutation,
+ /// Optimistic contribution paired with the mutation.
+ pub optimistic: PersistedOptimisticLayer,
+}
+
+/// One complete durable queue entry.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct QueuedMutation {
+ /// Durable queue id and ordering key.
+ pub id: MutationId,
+ /// Mutation request and retry metadata.
+ pub mutation: StoredMutation,
+ /// Optimistic contribution paired with the mutation.
+ pub optimistic: PersistedOptimisticLayer,
+}
+
+/// Successful claim of the oldest runnable mutation.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ClaimedMutation {
+ /// Claimed queue entry, including updated attempt and lease metadata.
+ pub queued: QueuedMutation,
+ /// Generation that settlement calls must present.
+ pub lease_generation: u64,
+}
+
+/// Parameters for claiming the strict queue head.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MutationClaimRequest {
+ /// Stable owner id for one queue runner.
+ pub owner: String,
+ /// Current wall-clock time.
+ pub now_ms: i64,
+ /// Absolute expiration time for the new lease.
+ pub lease_expires_at_ms: i64,
+}
+
+/// Identifies the attempt allowed to settle or defer a mutation.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MutationClaimToken {
+ /// Stable owner id supplied at claim time.
+ pub owner: String,
+ /// Lease generation returned by the successful claim.
+ pub generation: u64,
+}
diff --git a/crates/client/cache-core/src/store.rs b/crates/client/cache-core/src/store.rs
index 4606ccfc65..e9c7148108 100644
--- a/crates/client/cache-core/src/store.rs
+++ b/crates/client/cache-core/src/store.rs
@@ -6,9 +6,13 @@
//! from a multi-threaded runtime), unbounded on wasm — wasm futures aren't
//! `Send`.
+use crate::queue::{
+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,
+ QueuedMutation,
+};
use crate::value::{EntityKey, Record};
use maybe_send::MaybeSend;
-use std::collections::HashMap;
+use std::collections::{BTreeMap, HashMap};
use std::convert::Infallible;
/// Async KV over normalized records. Batch-oriented by design: the engine
@@ -34,7 +38,54 @@ pub trait Storage: MaybeSend {
keys: &[EntityKey],
) -> impl Future<Output = Result<(), Self::Error>> + MaybeSend;
- /// Drops everything (logout / corruption rebuild).
+ /// Atomically appends a mutation and its optimistic layer to the queue.
+ fn enqueue_mutation(
+ &mut self,
+ entry: NewQueuedMutation,
+ ) -> impl Future<Output = Result<MutationId, Self::Error>> + MaybeSend;
+
+ /// Loads the complete mutation queue in ascending id order.
+ fn load_mutation_queue(
+ &self,
+ ) -> impl Future<Output = Result<Vec<QueuedMutation>, Self::Error>> + MaybeSend;
+
+ /// Claims the oldest mutation when it is runnable and not actively leased.
+ /// Later mutations are never skipped.
+ fn claim_next_mutation(
+ &mut self,
+ request: MutationClaimRequest,
+ ) -> impl Future<Output = Result<Option<ClaimedMutation>, Self::Error>> + MaybeSend;
+
+ /// Retains a retryable mutation and its optimistic layer, releases its
+ /// lease, and records the next eligible attempt time. Returns `false`
+ /// when the claim is stale.
+ fn defer_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ next_attempt_at_ms: i64,
+ error: String,
+ ) -> impl Future<Output = Result<bool, Self::Error>> + MaybeSend;
+
+ /// Atomically writes the real response records and removes the mutation
+ /// plus optimistic layer. Returns `false` when the claim is stale.
+ fn complete_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ entries: Vec<(EntityKey, Record)>,
+ ) -> impl Future<Output = Result<bool, Self::Error>> + MaybeSend;
+
+ /// Atomically removes a permanently failed mutation and its optimistic
+ /// layer. Returns `false` when the claim is stale.
+ fn discard_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ ) -> impl Future<Output = Result<bool, Self::Error>> + MaybeSend;
+
+ /// Drops records, queued mutations, and optimistic layers (logout or
+ /// identity mismatch).
fn clear(&mut self) -> impl Future<Output = Result<(), Self::Error>> + MaybeSend;
}
@@ -42,6 +93,14 @@ pub trait Storage: MaybeSend {
#[derive(Debug, Default)]
pub struct InMemoryStorage {
records: HashMap<EntityKey, Record>,
+ mutations: BTreeMap<
+ MutationId,
+ (
+ crate::queue::StoredMutation,
+ crate::queue::PersistedOptimisticLayer,
+ ),
+ >,
+ next_mutation_id: MutationId,
}
impl InMemoryStorage {
@@ -79,8 +138,124 @@ impl Storage for InMemoryStorage {
Ok(())
}
+ async fn enqueue_mutation(
+ &mut self,
+ entry: NewQueuedMutation,
+ ) -> Result<MutationId, Self::Error> {
+ self.next_mutation_id += 1;
+ let id = self.next_mutation_id;
+ self.mutations
+ .insert(id, (entry.mutation, entry.optimistic));
+ Ok(id)
+ }
+
+ async fn load_mutation_queue(&self) -> Result<Vec<QueuedMutation>, Self::Error> {
+ Ok(self
+ .mutations
+ .iter()
+ .map(|(id, (mutation, optimistic))| QueuedMutation {
+ id: *id,
+ mutation: mutation.clone(),
+ optimistic: optimistic.clone(),
+ })
+ .collect())
+ }
+
+ async fn claim_next_mutation(
+ &mut self,
+ request: MutationClaimRequest,
+ ) -> Result<Option<ClaimedMutation>, Self::Error> {
+ let Some((&id, (mutation, optimistic))) = self.mutations.iter_mut().next() else {
+ return Ok(None);
+ };
+ if mutation
+ .next_attempt_at_ms
+ .is_some_and(|next| next > request.now_ms)
+ || mutation
+ .lease_expires_at_ms
+ .is_some_and(|expiry| expiry > request.now_ms)
+ {
+ return Ok(None);
+ }
+
+ mutation.attempt_count = mutation.attempt_count.saturating_add(1);
+ mutation.lease_generation = mutation.lease_generation.saturating_add(1);
+ mutation.lease_owner = Some(request.owner);
+ mutation.lease_expires_at_ms = Some(request.lease_expires_at_ms);
+ mutation.next_attempt_at_ms = None;
+ let generation = mutation.lease_generation;
+ Ok(Some(ClaimedMutation {
+ queued: QueuedMutation {
+ id,
+ mutation: mutation.clone(),
+ optimistic: optimistic.clone(),
+ },
+ lease_generation: generation,
+ }))
+ }
+
+ async fn defer_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ next_attempt_at_ms: i64,
+ error: String,
+ ) -> Result<bool, Self::Error> {
+ let Some((mutation, _)) = self.mutations.get_mut(&id) else {
+ return Ok(false);
+ };
+ if !claim_matches(mutation, &claim) {
+ return Ok(false);
+ }
+ mutation.next_attempt_at_ms = Some(next_attempt_at_ms);
+ mutation.last_error = Some(error);
+ mutation.lease_owner = None;
+ mutation.lease_expires_at_ms = None;
+ Ok(true)
+ }
+
+ async fn complete_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ entries: Vec<(EntityKey, Record)>,
+ ) -> Result<bool, Self::Error> {
+ let Some((mutation, _)) = self.mutations.get(&id) else {
+ return Ok(false);
+ };
+ if !claim_matches(mutation, &claim) {
+ return Ok(false);
+ }
+ for (key, record) in entries {
+ self.records.insert(key, record);
+ }
+ self.mutations.remove(&id);
+ Ok(true)
+ }
+
+ async fn discard_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ ) -> Result<bool, Self::Error> {
+ let Some((mutation, _)) = self.mutations.get(&id) else {
+ return Ok(false);
+ };
+ if !claim_matches(mutation, &claim) {
+ return Ok(false);
+ }
+ self.mutations.remove(&id);
+ Ok(true)
+ }
+
async fn clear(&mut self) -> Result<(), Self::Error> {
self.records.clear();
+ self.mutations.clear();
Ok(())
}
}
+
+fn claim_matches(mutation: &crate::queue::StoredMutation, claim: &MutationClaimToken) -> bool {
+ mutation.lease_owner.as_deref() == Some(&claim.owner)
+ && mutation.lease_generation == claim.generation
+}
diff --git a/crates/client/cache-core/tests/mutation_queue.rs b/crates/client/cache-core/tests/mutation_queue.rs
new file mode 100644
index 0000000000..1a98ab68cc
--- /dev/null
+++ b/crates/client/cache-core/tests/mutation_queue.rs
@@ -0,0 +1,133 @@
+use cache_core::queue::{
+ MutationClaimRequest, MutationClaimToken, MutationRequest, NewQueuedMutation,
+ PersistedOptimisticLayer, StoredMutation,
+};
+use cache_core::store::{InMemoryStorage, Storage};
+use cache_core::value::{CacheValue, EntityKey, Record};
+use pollster::block_on;
+
+fn queued(value: &str, created_at_ms: i64) -> NewQueuedMutation {
+ let mut update = Record::default();
+ update
+ .fields
+ .insert("name".into(), CacheValue::String(value.into()));
+ NewQueuedMutation {
+ mutation: StoredMutation::new(
+ MutationRequest {
+ query: "mutation Rename { rename { id } }".into(),
+ operation_name: Some("Rename".into()),
+ variables_json: format!(r#"{{"name":"{value}"}}"#),
+ identity: Some("user-1".into()),
+ },
+ created_at_ms,
+ ),
+ optimistic: PersistedOptimisticLayer {
+ optimistic_data_json: format!(r#"{{"rename":{{"name":"{value}"}}}}"#),
+ normalized_updates: [(EntityKey("Thing:1".into()), update)].into(),
+ },
+ }
+}
+
+#[test]
+fn queue_claim_retry_and_settlement_are_ordered() {
+ block_on(async {
+ let mut storage = InMemoryStorage::new();
+ let first = storage.enqueue_mutation(queued("a", 1)).await.unwrap();
+ let second = storage.enqueue_mutation(queued("b", 2)).await.unwrap();
+ assert!(first < second);
+
+ let loaded = storage.load_mutation_queue().await.unwrap();
+ assert_eq!(
+ loaded.iter().map(|entry| entry.id).collect::<Vec<_>>(),
+ [first, second]
+ );
+
+ let claimed = storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner-1".into(),
+ now_ms: 10,
+ lease_expires_at_ms: 100,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(claimed.queued.id, first);
+ assert_eq!(claimed.queued.mutation.attempt_count, 1);
+
+ // The leased head blocks every later mutation.
+ assert!(
+ storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner-2".into(),
+ now_ms: 20,
+ lease_expires_at_ms: 120,
+ })
+ .await
+ .unwrap()
+ .is_none()
+ );
+
+ assert!(
+ storage
+ .defer_mutation(
+ first,
+ MutationClaimToken {
+ owner: "runner-1".into(),
+ generation: claimed.lease_generation,
+ },
+ 200,
+ "offline".into(),
+ )
+ .await
+ .unwrap()
+ );
+ assert!(
+ storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner-2".into(),
+ now_ms: 199,
+ lease_expires_at_ms: 300,
+ })
+ .await
+ .unwrap()
+ .is_none()
+ );
+
+ let retried = storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner-2".into(),
+ now_ms: 200,
+ lease_expires_at_ms: 300,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(retried.queued.id, first);
+ assert_eq!(retried.queued.mutation.attempt_count, 2);
+
+ let mut real = Record::default();
+ real.fields
+ .insert("name".into(), CacheValue::String("server".into()));
+ assert!(
+ storage
+ .complete_mutation(
+ first,
+ MutationClaimToken {
+ owner: "runner-2".into(),
+ generation: retried.lease_generation,
+ },
+ vec![(EntityKey("Thing:1".into()), real.clone())],
+ )
+ .await
+ .unwrap()
+ );
+ assert_eq!(
+ storage
+ .get_batch(&[EntityKey("Thing:1".into())])
+ .await
+ .unwrap()[0],
+ Some(real)
+ );
+ assert_eq!(storage.load_mutation_queue().await.unwrap()[0].id, second);
+ });
+}
diff --git a/crates/client/cache-core/tests/optimistic.rs b/crates/client/cache-core/tests/optimistic.rs
index 6d67a7614f..488e0266de 100644
--- a/crates/client/cache-core/tests/optimistic.rs
+++ b/crates/client/cache-core/tests/optimistic.rs
@@ -1,9 +1,10 @@
-//! Optimistic mutation layer tests: begin/read/commit/rollback, out-of-order
-//! settlement, layer composition, durable isolation, and lifecycle resets.
+//! Durable optimistic mutation tests: enqueue/read/claim/retry/commit/fail,
+//! strict ordering, and lifecycle resets.
use cache_core::engine::{Engine, EngineError, ReadResult};
-use cache_core::store::InMemoryStorage;
-use cache_core::value::EntityKey;
+use cache_core::queue::{MutationClaimRequest, MutationClaimToken};
+use cache_core::store::{InMemoryStorage, Storage};
+use cache_core::value::{CacheValue, EntityKey};
use pollster::block_on;
use serde_json::{Value as Json, json};
@@ -110,7 +111,6 @@ fn mutation_response(display_name: &str, value: &str) -> Json {
})
}
-/// Reads the property object out of a soup query hit.
fn property_of(data: &Json) -> &Json {
&data["user"]["soup"]["items"][0]["entity"]["properties"][0]
}
@@ -142,494 +142,257 @@ async fn read_hit(engine: &mut Engine<InMemoryStorage>, op: Option<u64>) -> Json
}
}
-/// The durable (storage) value of the property record's displayName, read
-/// directly from the underlying store — bypassing optimistic layers.
-async fn durable_display_name(engine: &Engine<InMemoryStorage>) -> Option<String> {
- use cache_core::store::Storage;
- use cache_core::value::CacheValue;
+async fn claim_head(
+ engine: &mut Engine<InMemoryStorage>,
+ owner: &str,
+ now_ms: i64,
+) -> (u64, MutationClaimToken) {
+ let claimed = engine
+ .claim_next_mutation(MutationClaimRequest {
+ owner: owner.into(),
+ now_ms,
+ lease_expires_at_ms: now_ms + 1_000,
+ })
+ .await
+ .unwrap()
+ .expect("queue head");
+ let id = claimed.queued.id;
+ (
+ id,
+ MutationClaimToken {
+ owner: owner.into(),
+ generation: claimed.lease_generation,
+ },
+ )
+}
+
+async fn durable_value(engine: &Engine<InMemoryStorage>) -> Option<String> {
let records = engine
.storage()
.get_batch(&[EntityKey(PROPERTY_KEY.to_string())])
.await
.unwrap();
- records
- .into_iter()
- .next()
- .flatten()
- .and_then(|record| match record.fields.get("displayName") {
- Some(CacheValue::String(s)) => Some(s.clone()),
- _ => None,
- })
-}
-
-#[test]
-fn network_mutation_without_layer_writes_through() {
- block_on(async {
- let mut engine = engine_with_base("Status", "todo").await;
- // Register op 1 on the soup query.
- read_hit(&mut engine, Some(1)).await;
-
- // A plain (non-optimistic) mutation response normalizes into the
- // same records and notifies dependents.
- let write = engine
- .write_query(
- None,
- MUTATION,
- Some("SetEntityProperty"),
- &mutation_vars("done"),
- &mutation_response("Status", "done"),
- None,
- )
- .await
- .unwrap();
- assert!(write.changed.contains(&EntityKey(PROPERTY_KEY.to_string())));
- assert!(write.affected_ops.contains(&1));
- // Mutation root fields are transient: nothing lands on ROOT_QUERY.
- assert!(!write.changed.iter().any(|k| k.is_root()));
-
- let data = read_hit(&mut engine, Some(1)).await;
- assert_eq!(property_of(&data)["value"]["stringValue"], json!("done"));
- assert_eq!(
- durable_display_name(&engine).await.as_deref(),
- Some("Status")
- );
- });
-}
-
-#[test]
-fn reads_reject_mutation_documents() {
- block_on(async {
- let mut engine = Engine::new(InMemoryStorage::new());
- let err = engine
- .read_query(
- None,
- MUTATION,
- Some("SetEntityProperty"),
- &mutation_vars("x"),
- )
- .await
- .unwrap_err();
- assert!(matches!(err, EngineError::Document(_)));
- });
-}
-
-#[test]
-fn begin_composes_over_base_without_persisting() {
- block_on(async {
- let mut engine = engine_with_base("Status", "todo").await;
- read_hit(&mut engine, Some(1)).await;
-
- let (txn, begin) = engine
- .begin_optimistic_write(
- None,
- MUTATION,
- Some("SetEntityProperty"),
- &mutation_vars("doing"),
- &mutation_response("Status", "doing"),
- )
- .await
- .unwrap();
- assert!(txn > 0);
- assert!(begin.changed.contains(&EntityKey(PROPERTY_KEY.to_string())));
- assert!(begin.affected_ops.contains(&1));
- assert!(!begin.reset);
-
- // Reads see the optimistic value; durable state is untouched.
- let data = read_hit(&mut engine, Some(1)).await;
- assert_eq!(property_of(&data)["value"]["stringValue"], json!("doing"));
- use cache_core::store::Storage;
- use cache_core::value::CacheValue;
- let stored = engine
- .storage()
- .get_batch(&[EntityKey(PROPERTY_KEY.to_string())])
- .await
- .unwrap();
- let stored = stored.into_iter().next().flatten().unwrap();
- let Some(CacheValue::Object(value)) = stored.fields.get("value") else {
- panic!("stored value shape");
- };
- assert_eq!(value.get("value"), Some(&CacheValue::String("todo".into())));
- });
-}
-
-#[test]
-fn begin_with_identical_data_notifies_nobody() {
- block_on(async {
- let mut engine = engine_with_base("Status", "todo").await;
- read_hit(&mut engine, Some(1)).await;
-
- // Optimistic response identical to the cached data → the effective
- // view is unchanged, nobody re-executes.
- let (_, begin) = engine
- .begin_optimistic_write(
- None,
- MUTATION,
- Some("SetEntityProperty"),
- &mutation_vars("todo"),
- &mutation_response("Status", "todo"),
- )
- .await
- .unwrap();
- assert!(begin.changed.is_empty());
- assert!(begin.affected_ops.is_empty());
- });
+ let record = records.into_iter().next().flatten()?;
+ let CacheValue::Object(value) = record.fields.get("value")? else {
+ return None;
+ };
+ match value.get("value") {
+ Some(CacheValue::String(value)) => Some(value.clone()),
+ _ => None,
+ }
}
#[test]
-fn commit_replaces_layer_and_flushes_durably() {
+fn begin_persists_mutation_and_optimistic_layer() {
block_on(async {
let mut engine = engine_with_base("Status", "todo").await;
read_hit(&mut engine, Some(1)).await;
-
- let (txn, _) = engine
+ let (transaction, result) = engine
.begin_optimistic_write(
None,
MUTATION,
Some("SetEntityProperty"),
&mutation_vars("doing"),
&mutation_response("Status", "doing"),
+ 123,
)
.await
.unwrap();
- // The network result differs from the optimistic response.
- let commit = engine
- .commit_optimistic_write(
- txn,
- MUTATION,
- Some("SetEntityProperty"),
- &mutation_vars("doing"),
- &mutation_response("Status (renamed)", "doing"),
- )
- .await
- .unwrap();
- // Durable flush happened (single layer = contiguous prefix).
- assert!(
- commit
- .changed
- .contains(&EntityKey(PROPERTY_KEY.to_string()))
- );
- // displayName's visible value changed with the real response.
- assert!(commit.affected_ops.contains(&1));
-
- let data = read_hit(&mut engine, Some(1)).await;
- assert_eq!(property_of(&data)["displayName"], json!("Status (renamed)"));
- assert_eq!(property_of(&data)["value"]["stringValue"], json!("doing"));
+ assert!(result.affected_ops.contains(&1));
+ let queued = engine.storage().load_mutation_queue().await.unwrap();
+ assert_eq!(queued.len(), 1);
+ assert_eq!(queued[0].id, transaction);
+ assert_eq!(queued[0].mutation.created_at_ms, 123);
assert_eq!(
- durable_display_name(&engine).await.as_deref(),
- Some("Status (renamed)")
+ queued[0].mutation.request.operation_name.as_deref(),
+ Some("SetEntityProperty")
);
- // Settled transactions are gone: settling again is an error.
- assert!(matches!(
- engine.rollback_optimistic_write(txn).await,
- Err(EngineError::UnknownTransaction(_))
- ));
+ let data = read_hit(&mut engine, None).await;
+ assert_eq!(property_of(&data)["value"]["stringValue"], json!("doing"));
+ assert_eq!(durable_value(&engine).await.as_deref(), Some("todo"));
});
}
#[test]
-fn commit_matching_optimistic_response_is_silent() {
+fn claimed_success_atomically_commits_real_response() {
block_on(async {
let mut engine = engine_with_base("Status", "todo").await;
read_hit(&mut engine, Some(1)).await;
-
- let (txn, _) = engine
+ let (transaction, _) = engine
.begin_optimistic_write(
None,
MUTATION,
Some("SetEntityProperty"),
&mutation_vars("doing"),
&mutation_response("Status", "doing"),
+ 0,
)
.await
.unwrap();
- let commit = engine
+ let (claimed_id, claim) = claim_head(&mut engine, "runner", 10).await;
+ assert_eq!(claimed_id, transaction);
+
+ let result = engine
.commit_optimistic_write(
- txn,
+ transaction,
+ claim,
MUTATION,
Some("SetEntityProperty"),
&mutation_vars("doing"),
- &mutation_response("Status", "doing"),
+ &mutation_response("Status (server)", "done"),
)
.await
.unwrap();
- // Visible data did not change (real == optimistic) → no local
- // notifications; durable keys still broadcast for other instances.
- assert!(commit.affected_ops.is_empty());
+ assert!(result.changed.contains(&EntityKey(PROPERTY_KEY.into())));
+ assert!(result.affected_ops.contains(&1));
assert!(
- commit
- .changed
- .contains(&EntityKey(PROPERTY_KEY.to_string()))
+ engine
+ .storage()
+ .load_mutation_queue()
+ .await
+ .unwrap()
+ .is_empty()
);
- });
-}
-
-#[test]
-fn rollback_restores_base_view() {
- block_on(async {
- let mut engine = engine_with_base("Status", "todo").await;
- read_hit(&mut engine, Some(1)).await;
+ assert_eq!(durable_value(&engine).await.as_deref(), Some("done"));
- let (txn, _) = engine
- .begin_optimistic_write(
- None,
- MUTATION,
- Some("SetEntityProperty"),
- &mutation_vars("doing"),
- &mutation_response("Status", "doing"),
- )
- .await
- .unwrap();
- let rollback = engine.rollback_optimistic_write(txn).await.unwrap();
- assert!(rollback.affected_ops.contains(&1));
- // Nothing was ever durable, nothing flushed.
- assert!(rollback.changed.is_empty());
-
- let data = read_hit(&mut engine, Some(1)).await;
- assert_eq!(property_of(&data)["value"]["stringValue"], json!("todo"));
- assert_eq!(
- durable_display_name(&engine).await.as_deref(),
- Some("Status")
- );
+ let data = read_hit(&mut engine, None).await;
+ assert_eq!(property_of(&data)["displayName"], json!("Status (server)"));
+ assert_eq!(property_of(&data)["value"]["stringValue"], json!("done"));
});
}
#[test]
-fn out_of_order_settlement_preserves_later_layer() {
+fn retryable_failure_keeps_optimistic_layer_and_blocks_later_mutations() {
block_on(async {
let mut engine = engine_with_base("Status", "todo").await;
- read_hit(&mut engine, Some(1)).await;
-
- // A then B target the same field.
- let (txn_a, _) = engine
+ let (first, _) = engine
.begin_optimistic_write(
None,
MUTATION,
Some("SetEntityProperty"),
&mutation_vars("a"),
&mutation_response("Status", "a"),
+ 0,
)
.await
.unwrap();
- let (txn_b, _) = engine
+ let (second, _) = engine
.begin_optimistic_write(
None,
MUTATION,
Some("SetEntityProperty"),
&mutation_vars("b"),
&mutation_response("Status", "b"),
+ 1,
)
.await
.unwrap();
- assert_ne!(txn_a, txn_b);
+ assert!(first < second);
- // B settles first: nothing flushes (A still pending ahead of it),
- // and B's real value stays visible over A's pending layer.
- let commit_b = engine
- .commit_optimistic_write(
- txn_b,
- MUTATION,
- Some("SetEntityProperty"),
- &mutation_vars("b"),
- &mutation_response("Status", "b!"),
- )
- .await
- .unwrap();
- assert!(commit_b.changed.is_empty(), "no durable flush yet");
- let data = read_hit(&mut engine, Some(1)).await;
- assert_eq!(property_of(&data)["value"]["stringValue"], json!("b!"));
- assert_eq!(
- durable_display_name(&engine).await.as_deref(),
- Some("Status")
- );
-
- // A settles second: settling the earlier layer must not clobber the
- // later one. The visible value stays B's; the flush persists both in
- // order (B's response wins the shared field).
- let commit_a = engine
- .commit_optimistic_write(
- txn_a,
- MUTATION,
- Some("SetEntityProperty"),
- &mutation_vars("a"),
- &mutation_response("Status", "a!"),
- )
+ let (_, claim) = claim_head(&mut engine, "runner", 10).await;
+ engine
+ .defer_optimistic_write(first, claim, 100, "offline".into())
.await
.unwrap();
- assert!(commit_a.affected_ops.is_empty(), "visible data unchanged");
assert!(
- commit_a
- .changed
- .contains(&EntityKey(PROPERTY_KEY.to_string()))
+ engine
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner".into(),
+ now_ms: 99,
+ lease_expires_at_ms: 200,
+ })
+ .await
+ .unwrap()
+ .is_none()
+ );
+ let data = read_hit(&mut engine, None).await;
+ assert_eq!(property_of(&data)["value"]["stringValue"], json!("b"));
+ assert_eq!(
+ engine.storage().load_mutation_queue().await.unwrap().len(),
+ 2
);
-
- let data = read_hit(&mut engine, Some(1)).await;
- assert_eq!(property_of(&data)["value"]["stringValue"], json!("b!"));
});
}
#[test]
-fn rollback_of_earlier_layer_keeps_later_success() {
+fn permanent_failure_rolls_back_only_the_claimed_head() {
block_on(async {
let mut engine = engine_with_base("Status", "todo").await;
- read_hit(&mut engine, Some(1)).await;
-
- let (txn_a, _) = engine
+ let (first, _) = engine
.begin_optimistic_write(
None,
MUTATION,
Some("SetEntityProperty"),
&mutation_vars("a"),
&mutation_response("Status", "a"),
+ 0,
)
.await
.unwrap();
- let (txn_b, _) = engine
+ engine
.begin_optimistic_write(
None,
MUTATION,
Some("SetEntityProperty"),
&mutation_vars("b"),
&mutation_response("Status", "b"),
+ 1,
)
.await
.unwrap();
-
- // B succeeds first; A then fails. The failed tombstone unblocks the
- // prefix and B's real response is what persists.
- engine
- .commit_optimistic_write(
- txn_b,
- MUTATION,
- Some("SetEntityProperty"),
- &mutation_vars("b"),
- &mutation_response("Status", "b!"),
- )
+ let (_, claim) = claim_head(&mut engine, "runner", 10).await;
+ let result = engine
+ .rollback_optimistic_write(first, claim)
.await
.unwrap();
- let rollback = engine.rollback_optimistic_write(txn_a).await.unwrap();
- // A's contribution was masked by B → visible data unchanged.
- assert!(rollback.affected_ops.is_empty());
- // The flush persisted B's committed layer.
- assert!(
- rollback
- .changed
- .contains(&EntityKey(PROPERTY_KEY.to_string()))
+ // The later layer masks the failed head, so the visible view is stable.
+ assert!(result.affected_ops.is_empty());
+ let data = read_hit(&mut engine, None).await;
+ assert_eq!(property_of(&data)["value"]["stringValue"], json!("b"));
+ assert_eq!(
+ engine.storage().load_mutation_queue().await.unwrap().len(),
+ 1
);
-
- let data = read_hit(&mut engine, Some(1)).await;
- assert_eq!(property_of(&data)["value"]["stringValue"], json!("b!"));
});
}
#[test]
-fn different_fields_on_same_record_compose() {
+fn stale_claim_cannot_settle_mutation() {
block_on(async {
let mut engine = engine_with_base("Status", "todo").await;
- read_hit(&mut engine, Some(1)).await;
-
- // Layer A renames; layer B (pending) changes the value.
- let (txn_a, _) = engine
- .begin_optimistic_write(
- None,
- MUTATION,
- Some("SetEntityProperty"),
- &mutation_vars("todo"),
- &mutation_response("Stage", "todo"),
- )
- .await
- .unwrap();
- let (_txn_b, _) = engine
+ let (transaction, _) = engine
.begin_optimistic_write(
None,
MUTATION,
Some("SetEntityProperty"),
&mutation_vars("doing"),
- &mutation_response("Stage", "doing"),
+ &mutation_response("Status", "doing"),
+ 0,
)
.await
.unwrap();
-
- let data = read_hit(&mut engine, Some(1)).await;
- assert_eq!(property_of(&data)["displayName"], json!("Stage"));
- assert_eq!(property_of(&data)["value"]["stringValue"], json!("doing"));
-
- // A commits while B remains pending: B's pending layer stays
- // visible over the committed base.
- engine
- .commit_optimistic_write(
- txn_a,
- MUTATION,
- Some("SetEntityProperty"),
- &mutation_vars("todo"),
- &mutation_response("Stage", "todo"),
+ let error = engine
+ .rollback_optimistic_write(
+ transaction,
+ MutationClaimToken {
+ owner: "wrong".into(),
+ generation: 1,
+ },
)
.await
- .unwrap();
- let data = read_hit(&mut engine, Some(1)).await;
- assert_eq!(property_of(&data)["value"]["stringValue"], json!("doing"));
+ .unwrap_err();
+ assert!(matches!(error, EngineError::StaleMutationClaim(id) if id == transaction));
assert_eq!(
- durable_display_name(&engine).await.as_deref(),
- Some("Stage")
+ engine.storage().load_mutation_queue().await.unwrap().len(),
+ 1
);
});
}
#[test]
-fn unknown_transaction_ids_error() {
- block_on(async {
- let mut engine = Engine::new(InMemoryStorage::new());
- assert!(matches!(
- engine.rollback_optimistic_write(42).await,
- Err(EngineError::UnknownTransaction(42))
- ));
- assert!(matches!(
- engine
- .commit_optimistic_write(
- 7,
- MUTATION,
- Some("SetEntityProperty"),
- &mutation_vars("x"),
- &mutation_response("Status", "x"),
- )
- .await,
- Err(EngineError::UnknownTransaction(7))
- ));
- });
-}
-
-#[test]
-fn clear_discards_pending_layers() {
- block_on(async {
- let mut engine = engine_with_base("Status", "todo").await;
- let (txn, _) = engine
- .begin_optimistic_write(
- None,
- MUTATION,
- Some("SetEntityProperty"),
- &mutation_vars("doing"),
- &mutation_response("Status", "doing"),
- )
- .await
- .unwrap();
-
- engine.clear().await.unwrap();
- let read = engine
- .read_query(None, QUERY, Some("Soup"), &query_vars())
- .await
- .unwrap();
- assert!(matches!(read, ReadResult::Miss));
- // The layer is gone; settling it later is an error, never a write.
- assert!(matches!(
- engine.rollback_optimistic_write(txn).await,
- Err(EngineError::UnknownTransaction(_))
- ));
- });
-}
-
-#[test]
-fn identity_reset_discards_pending_layers() {
+fn clear_and_identity_reset_drop_durable_queue() {
block_on(async {
let mut engine = engine_with_base("Status", "todo").await;
engine
@@ -643,21 +406,19 @@ fn identity_reset_discards_pending_layers() {
)
.await
.unwrap();
-
- let (txn, _) = engine
+ engine
.begin_optimistic_write(
None,
MUTATION,
Some("SetEntityProperty"),
&mutation_vars("doing"),
&mutation_response("Status", "doing"),
+ 0,
)
.await
.unwrap();
- // A response for another user silently wipes the cache — including
- // the pending optimistic layer.
- let write = engine
+ let reset = engine
.write_query(
None,
QUERY,
@@ -673,18 +434,24 @@ fn identity_reset_discards_pending_layers() {
)
.await
.unwrap();
- assert!(write.reset);
- assert!(matches!(
+ assert!(reset.reset);
+ assert!(
engine
- .commit_optimistic_write(
- txn,
- MUTATION,
- Some("SetEntityProperty"),
- &mutation_vars("doing"),
- &mutation_response("Status", "doing"),
- )
- .await,
- Err(EngineError::UnknownTransaction(_))
- ));
+ .storage()
+ .load_mutation_queue()
+ .await
+ .unwrap()
+ .is_empty()
+ );
+
+ engine.clear().await.unwrap();
+ assert!(
+ engine
+ .storage()
+ .load_mutation_queue()
+ .await
+ .unwrap()
+ .is_empty()
+ );
});
}
diff --git a/crates/client/cache-idb/src/idb_storage.rs b/crates/client/cache-idb/src/idb_storage.rs
index 1098cfcb2e..de712bc44e 100644
--- a/crates/client/cache-idb/src/idb_storage.rs
+++ b/crates/client/cache-idb/src/idb_storage.rs
@@ -1,12 +1,24 @@
-use cache_core::codec::{CodecError, cache_namespace, decode_record, encode_record};
+use cache_core::codec::{
+ CodecError, cache_database_name, cache_namespace, decode_optimistic_layer, decode_record,
+ decode_stored_mutation, encode_optimistic_layer, encode_record, encode_stored_mutation,
+};
+use cache_core::queue::{
+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,
+ QueuedMutation,
+};
use cache_core::store::Storage;
use cache_core::value::{EntityKey, Record};
use idb::{Database, DatabaseEvent, Factory, ObjectStoreParams, TransactionMode};
use thiserror::Error;
use wasm_bindgen::{JsCast, JsValue};
+const META_STORE: &str = "meta";
const RECORDS_STORE: &str = "records";
+const MUTATION_QUEUE_STORE: &str = "mutation_queue";
+const OPTIMISTIC_LAYERS_STORE: &str = "optimistic_layers";
const DB_VERSION: u32 = 1;
+const SCOPE_META_KEY: &str = "scope";
+const NAMESPACE_META_KEY: &str = "namespace";
#[derive(Debug, Error)]
pub enum IdbStorageError {
@@ -16,29 +28,78 @@ pub enum IdbStorageError {
Codec(#[from] CodecError),
#[error("stored value is not a Uint8Array")]
NotBytes,
+ #[error("stored metadata is not a string")]
+ NotString,
+ #[error("mutation queue key is not a safe positive integer")]
+ InvalidMutationId,
+ #[error("mutation queue and optimistic layer stores are inconsistent")]
+ InconsistentQueue,
}
pub struct IdbStorage {
db: Database,
}
+fn bytes_to_js(bytes: &[u8]) -> JsValue {
+ js_sys::Uint8Array::from(bytes).into()
+}
+
+fn bytes_from_js(value: JsValue) -> Result<Vec<u8>, IdbStorageError> {
+ let bytes: js_sys::Uint8Array = value.dyn_into().map_err(|_| IdbStorageError::NotBytes)?;
+ Ok(bytes.to_vec())
+}
+
+fn mutation_id_from_js(value: &JsValue) -> Result<MutationId, IdbStorageError> {
+ const MAX_SAFE_INTEGER: f64 = 9_007_199_254_740_991.0;
+ let Some(number) = value.as_f64() else {
+ return Err(IdbStorageError::InvalidMutationId);
+ };
+ if !(1.0..=MAX_SAFE_INTEGER).contains(&number) || number.fract() != 0.0 {
+ return Err(IdbStorageError::InvalidMutationId);
+ }
+ Ok(number as MutationId)
+}
+
+fn mutation_id_to_js(id: MutationId) -> Result<JsValue, IdbStorageError> {
+ const MAX_SAFE_INTEGER: MutationId = 9_007_199_254_740_991;
+ if id == 0 || id > MAX_SAFE_INTEGER {
+ return Err(IdbStorageError::InvalidMutationId);
+ }
+ Ok(JsValue::from_f64(id as f64))
+}
+
+fn claim_matches(mutation: &cache_core::queue::StoredMutation, claim: &MutationClaimToken) -> bool {
+ mutation.lease_owner.as_deref() == Some(&claim.owner)
+ && mutation.lease_generation == claim.generation
+}
+
impl IdbStorage {
- /// Opens the cache database for `scope`. A schema or format change
- /// yields a different database name, i.e. an implicitly fresh cache
- /// (stale namespaces are garbage-collected via [`Self::destroy`] by the
- /// host, or eventually by the browser under storage pressure).
+ /// Opens the cache database for `scope` and initializes all stores.
+ /// Record namespace changes clear only disposable records; a scope change
+ /// also clears queued user intent.
pub async fn open(scope: &str) -> Result<Self, IdbStorageError> {
- let name = cache_namespace(scope);
+ let name = cache_database_name(scope);
let factory = Factory::new()?;
let mut request = factory.open(&name, Some(DB_VERSION))?;
request.on_upgrade_needed(|event| {
let database = event.database().expect("upgrade event has database");
- // Out-of-line string keys (the entity key), Uint8Array values.
- // Surface setup failures immediately rather than as misleading
- // "store not found" errors on later transactions.
- database
- .create_object_store(RECORDS_STORE, ObjectStoreParams::new())
- .expect("create records object store");
+ let existing = database.store_names();
+ for (name, params) in [
+ (META_STORE, ObjectStoreParams::new()),
+ (RECORDS_STORE, ObjectStoreParams::new()),
+ (MUTATION_QUEUE_STORE, {
+ let mut params = ObjectStoreParams::new();
+ params.auto_increment(true);
+ params
+ }),
+ (OPTIMISTIC_LAYERS_STORE, ObjectStoreParams::new()),
+ ] {
+ if !existing.iter().any(|store| store == name) {
+ database
+ .create_object_store(name, params)
+ .unwrap_or_else(|_| panic!("create {name} object store"));
+ }
+ }
});
let mut db = request.await?;
// Close immediately when another context needs this database gone or
@@ -51,7 +112,51 @@ impl IdbStorage {
}
}
});
- Ok(IdbStorage { db })
+ let mut storage = IdbStorage { db };
+ storage.initialize_namespace(scope).await?;
+ Ok(storage)
+ }
+
+ async fn initialize_namespace(&mut self, scope: &str) -> Result<(), IdbStorageError> {
+ let tx = self.db.transaction(
+ &[
+ META_STORE,
+ RECORDS_STORE,
+ MUTATION_QUEUE_STORE,
+ OPTIMISTIC_LAYERS_STORE,
+ ],
+ TransactionMode::ReadWrite,
+ )?;
+ let meta = tx.object_store(META_STORE)?;
+ let scope_request = meta.get(JsValue::from_str(SCOPE_META_KEY))?;
+ let namespace_request = meta.get(JsValue::from_str(NAMESPACE_META_KEY))?;
+ let stored_scope = scope_request
+ .await?
+ .map(|value| value.as_string().ok_or(IdbStorageError::NotString))
+ .transpose()?;
+ let stored_namespace = namespace_request
+ .await?
+ .map(|value| value.as_string().ok_or(IdbStorageError::NotString))
+ .transpose()?;
+ let expected_namespace = cache_namespace(scope);
+
+ if stored_scope.as_deref() != Some(scope) {
+ tx.object_store(OPTIMISTIC_LAYERS_STORE)?.clear()?;
+ tx.object_store(MUTATION_QUEUE_STORE)?.clear()?;
+ tx.object_store(RECORDS_STORE)?.clear()?;
+ } else if stored_namespace.as_deref() != Some(expected_namespace.as_str()) {
+ tx.object_store(RECORDS_STORE)?.clear()?;
+ }
+ meta.put(
+ &JsValue::from_str(scope),
+ Some(&JsValue::from_str(SCOPE_META_KEY)),
+ )?;
+ meta.put(
+ &JsValue::from_str(&expected_namespace),
+ Some(&JsValue::from_str(NAMESPACE_META_KEY)),
+ )?;
+ tx.commit()?.await?;
+ Ok(())
}
/// Deletes the database for `scope` (logout / stale-namespace cleanup).
@@ -62,7 +167,7 @@ impl IdbStorage {
/// instead of hanging silently.
pub async fn destroy(scope: &str) -> Result<(), IdbStorageError> {
let factory = Factory::new()?;
- let mut request = factory.delete(&cache_namespace(scope))?;
+ let mut request = factory.delete(&cache_database_name(scope))?;
request.on_blocked(|_| {
web_sys::console::warn_1(
&"graphql-cache: database deletion blocked by an open connection".into(),
@@ -99,11 +204,7 @@ impl Storage for IdbStorage {
let value = request.await?;
out.push(match value {
None => None,
- Some(js) => {
- let bytes: js_sys::Uint8Array =
- js.dyn_into().map_err(|_| IdbStorageError::NotBytes)?;
- Some(decode_record(&bytes.to_vec())?)
- }
+ Some(js) => Some(decode_record(&bytes_from_js(js)?)?),
});
}
Ok(out)
@@ -116,8 +217,7 @@ impl Storage for IdbStorage {
let store = tx.object_store(RECORDS_STORE)?;
for (key, record) in &entries {
let bytes = encode_record(record);
- let value: JsValue = js_sys::Uint8Array::from(bytes.as_slice()).into();
- store.put(&value, Some(&JsValue::from_str(&key.0)))?;
+ store.put(&bytes_to_js(&bytes), Some(&JsValue::from_str(&key.0)))?;
}
// Committing the transaction is what makes the batch atomic.
tx.commit()?.await?;
@@ -136,10 +236,237 @@ impl Storage for IdbStorage {
Ok(())
}
- async fn clear(&mut self) -> Result<(), Self::Error> {
+ async fn enqueue_mutation(
+ &mut self,
+ entry: NewQueuedMutation,
+ ) -> Result<MutationId, Self::Error> {
+ let tx = self.db.transaction(
+ &[MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],
+ TransactionMode::ReadWrite,
+ )?;
+ let queue = tx.object_store(MUTATION_QUEUE_STORE)?;
+ let mutation_bytes = encode_stored_mutation(&entry.mutation);
+ let generated_key = queue.add(&bytes_to_js(&mutation_bytes), None)?.await?;
+ let id = mutation_id_from_js(&generated_key)?;
+ let optimistic_bytes = encode_optimistic_layer(&entry.optimistic);
+ tx.object_store(OPTIMISTIC_LAYERS_STORE)?
+ .put(&bytes_to_js(&optimistic_bytes), Some(&generated_key))?;
+ tx.commit()?.await?;
+ Ok(id)
+ }
+
+ async fn load_mutation_queue(&self) -> Result<Vec<QueuedMutation>, Self::Error> {
+ let tx = self.db.transaction(
+ &[MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],
+ TransactionMode::ReadOnly,
+ )?;
+ let queue = tx.object_store(MUTATION_QUEUE_STORE)?;
+ let optimistic = tx.object_store(OPTIMISTIC_LAYERS_STORE)?;
+ let queue_keys_request = queue.get_all_keys(None, None)?;
+ let queue_values_request = queue.get_all(None, None)?;
+ let optimistic_keys_request = optimistic.get_all_keys(None, None)?;
+ let optimistic_values_request = optimistic.get_all(None, None)?;
+
+ let queue_keys = queue_keys_request.await?;
+ let queue_values = queue_values_request.await?;
+ let optimistic_keys = optimistic_keys_request.await?;
+ let optimistic_values = optimistic_values_request.await?;
+ if queue_keys.len() != queue_values.len()
+ || queue_keys.len() != optimistic_keys.len()
+ || queue_keys.len() != optimistic_values.len()
+ {
+ return Err(IdbStorageError::InconsistentQueue);
+ }
+
+ let mut out = Vec::with_capacity(queue_keys.len());
+ for (((queue_key, mutation), optimistic_key), layer) in queue_keys
+ .into_iter()
+ .zip(queue_values)
+ .zip(optimistic_keys)
+ .zip(optimistic_values)
+ {
+ let id = mutation_id_from_js(&queue_key)?;
+ if mutation_id_from_js(&optimistic_key)? != id {
+ return Err(IdbStorageError::InconsistentQueue);
+ }
+ out.push(QueuedMutation {
+ id,
+ mutation: decode_stored_mutation(&bytes_from_js(mutation)?)?,
+ optimistic: decode_optimistic_layer(&bytes_from_js(layer)?)?,
+ });
+ }
+ Ok(out)
+ }
+
+ async fn claim_next_mutation(
+ &mut self,
+ request: MutationClaimRequest,
+ ) -> Result<Option<ClaimedMutation>, Self::Error> {
+ let tx = self.db.transaction(
+ &[MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],
+ TransactionMode::ReadWrite,
+ )?;
+ let queue = tx.object_store(MUTATION_QUEUE_STORE)?;
+ let optimistic = tx.object_store(OPTIMISTIC_LAYERS_STORE)?;
+ let queue_keys_request = queue.get_all_keys(None, Some(1))?;
+ let queue_values_request = queue.get_all(None, Some(1))?;
+ let optimistic_keys_request = optimistic.get_all_keys(None, Some(1))?;
+ let optimistic_values_request = optimistic.get_all(None, Some(1))?;
+ let queue_keys = queue_keys_request.await?;
+ let queue_values = queue_values_request.await?;
+ let optimistic_keys = optimistic_keys_request.await?;
+ let optimistic_values = optimistic_values_request.await?;
+
+ if queue_keys.is_empty() {
+ if !queue_values.is_empty()
+ || !optimistic_keys.is_empty()
+ || !optimistic_values.is_empty()
+ {
+ return Err(IdbStorageError::InconsistentQueue);
+ }
+ tx.commit()?.await?;
+ return Ok(None);
+ }
+ if queue_keys.len() != 1
+ || queue_values.len() != 1
+ || optimistic_keys.len() != 1
+ || optimistic_values.len() != 1
+ {
+ return Err(IdbStorageError::InconsistentQueue);
+ }
+ let key = &queue_keys[0];
+ let id = mutation_id_from_js(key)?;
+ if mutation_id_from_js(&optimistic_keys[0])? != id {
+ return Err(IdbStorageError::InconsistentQueue);
+ }
+ let mut mutation = decode_stored_mutation(&bytes_from_js(queue_values[0].clone())?)?;
+ if mutation
+ .next_attempt_at_ms
+ .is_some_and(|next| next > request.now_ms)
+ || mutation
+ .lease_expires_at_ms
+ .is_some_and(|expiry| expiry > request.now_ms)
+ {
+ tx.commit()?.await?;
+ return Ok(None);
+ }
+
+ mutation.attempt_count = mutation.attempt_count.saturating_add(1);
+ mutation.lease_generation = mutation.lease_generation.saturating_add(1);
+ mutation.lease_owner = Some(request.owner);
+ mutation.lease_expires_at_ms = Some(request.lease_expires_at_ms);
+ mutation.next_attempt_at_ms = None;
+ let generation = mutation.lease_generation;
+ queue.put(&bytes_to_js(&encode_stored_mutation(&mutation)), Some(key))?;
+ let layer = decode_optimistic_layer(&bytes_from_js(optimistic_values[0].clone())?)?;
+ tx.commit()?.await?;
+ Ok(Some(ClaimedMutation {
+ queued: QueuedMutation {
+ id,
+ mutation,
+ optimistic: layer,
+ },
+ lease_generation: generation,
+ }))
+ }
+
+ async fn defer_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ next_attempt_at_ms: i64,
+ error: String,
+ ) -> Result<bool, Self::Error> {
+ let key = mutation_id_to_js(id)?;
let tx = self
.db
- .transaction(&[RECORDS_STORE], TransactionMode::ReadWrite)?;
+ .transaction(&[MUTATION_QUEUE_STORE], TransactionMode::ReadWrite)?;
+ let queue = tx.object_store(MUTATION_QUEUE_STORE)?;
+ let Some(value) = queue.get(key.clone())?.await? else {
+ tx.commit()?.await?;
+ return Ok(false);
+ };
+ let mut mutation = decode_stored_mutation(&bytes_from_js(value)?)?;
+ if !claim_matches(&mutation, &claim) {
+ tx.commit()?.await?;
+ return Ok(false);
+ }
+ mutation.next_attempt_at_ms = Some(next_attempt_at_ms);
+ mutation.last_error = Some(error);
+ mutation.lease_owner = None;
+ mutation.lease_expires_at_ms = None;
+ queue.put(&bytes_to_js(&encode_stored_mutation(&mutation)), Some(&key))?;
+ tx.commit()?.await?;
+ Ok(true)
+ }
+
+ async fn complete_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ entries: Vec<(EntityKey, Record)>,
+ ) -> Result<bool, Self::Error> {
+ let key = mutation_id_to_js(id)?;
+ let tx = self.db.transaction(
+ &[RECORDS_STORE, MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],
+ TransactionMode::ReadWrite,
+ )?;
+ let queue = tx.object_store(MUTATION_QUEUE_STORE)?;
+ let Some(value) = queue.get(key.clone())?.await? else {
+ tx.commit()?.await?;
+ return Ok(false);
+ };
+ let mutation = decode_stored_mutation(&bytes_from_js(value)?)?;
+ if !claim_matches(&mutation, &claim) {
+ tx.commit()?.await?;
+ return Ok(false);
+ }
+ let records = tx.object_store(RECORDS_STORE)?;
+ for (record_key, record) in &entries {
+ records.put(
+ &bytes_to_js(&encode_record(record)),
+ Some(&JsValue::from_str(&record_key.0)),
+ )?;
+ }
+ queue.delete(key.clone())?;
+ tx.object_store(OPTIMISTIC_LAYERS_STORE)?.delete(key)?;
+ tx.commit()?.await?;
+ Ok(true)
+ }
+
+ async fn discard_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ ) -> Result<bool, Self::Error> {
+ let key = mutation_id_to_js(id)?;
+ let tx = self.db.transaction(
+ &[MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],
+ TransactionMode::ReadWrite,
+ )?;
+ let queue = tx.object_store(MUTATION_QUEUE_STORE)?;
+ let Some(value) = queue.get(key.clone())?.await? else {
+ tx.commit()?.await?;
+ return Ok(false);
+ };
+ let mutation = decode_stored_mutation(&bytes_from_js(value)?)?;
+ if !claim_matches(&mutation, &claim) {
+ tx.commit()?.await?;
+ return Ok(false);
+ }
+ queue.delete(key.clone())?;
+ tx.object_store(OPTIMISTIC_LAYERS_STORE)?.delete(key)?;
+ tx.commit()?.await?;
+ Ok(true)
+ }
+
+ async fn clear(&mut self) -> Result<(), Self::Error> {
+ let tx = self.db.transaction(
+ &[RECORDS_STORE, MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],
+ TransactionMode::ReadWrite,
+ )?;
+ tx.object_store(OPTIMISTIC_LAYERS_STORE)?.clear()?;
+ tx.object_store(MUTATION_QUEUE_STORE)?.clear()?;
tx.object_store(RECORDS_STORE)?.clear()?;
tx.commit()?.await?;
Ok(())
diff --git a/crates/client/cache-idb/src/lib.rs b/crates/client/cache-idb/src/lib.rs
index 0097d55907..38c595e083 100644
--- a/crates/client/cache-idb/src/lib.rs
+++ b/crates/client/cache-idb/src/lib.rs
@@ -1,11 +1,10 @@
//! IndexedDB [`Storage`](cache_core::store::Storage) backend for the browser
//! host (wasm module in a SharedWorker / dedicated worker).
//!
-//! One IndexedDB database per cache namespace — the database *name* embeds
-//! scope + schema hash + format version
-//! ([`cache_core::codec::cache_namespace`]), so a schema/format change simply
-//! opens a fresh database. Records live in a single `records` object store
-//! as postcard bytes (`Uint8Array`) under their entity-key string.
+//! One stable IndexedDB database per cache scope. Disposable normalized
+//! records are versioned through metadata, while queued mutations and their
+//! optimistic layers remain discoverable across record-schema changes.
+//! Postcard payloads are stored as `Uint8Array` values.
//!
//! wasm32-only; on other targets this crate is an empty shell so workspace
//! `cargo test` stays green.
diff --git a/crates/client/cache-idb/tests/web.rs b/crates/client/cache-idb/tests/web.rs
index 533cce74e0..150d948db0 100644
--- a/crates/client/cache-idb/tests/web.rs
+++ b/crates/client/cache-idb/tests/web.rs
@@ -5,6 +5,10 @@
#![cfg(target_arch = "wasm32")]
use cache_core::engine::{Engine, ReadResult};
+use cache_core::queue::{
+ MutationClaimRequest, MutationClaimToken, MutationRequest, NewQueuedMutation,
+ PersistedOptimisticLayer, StoredMutation,
+};
use cache_core::store::Storage;
use cache_core::value::{CacheValue, EntityKey, Record};
use cache_idb::IdbStorage;
@@ -23,6 +27,24 @@ fn key(s: &str) -> EntityKey {
EntityKey(s.to_string())
}
+fn queued(name: &str) -> NewQueuedMutation {
+ NewQueuedMutation {
+ mutation: StoredMutation::new(
+ MutationRequest {
+ query: "mutation Rename { rename { id } }".into(),
+ operation_name: Some("Rename".into()),
+ variables_json: format!(r#"{{"name":"{name}"}}"#),
+ identity: Some("user-1".into()),
+ },
+ 10,
+ ),
+ optimistic: PersistedOptimisticLayer {
+ optimistic_data_json: format!(r#"{{"rename":{{"name":"{name}"}}}}"#),
+ normalized_updates: [(key("A:1"), record(name))].into(),
+ },
+ }
+}
+
#[wasm_bindgen_test]
async fn put_get_delete_roundtrip() {
IdbStorage::destroy("test-rt").await.unwrap();
@@ -63,6 +85,49 @@ async fn persists_across_reopen() {
assert_eq!(got[0].as_ref().unwrap(), &record("a"));
}
+#[wasm_bindgen_test]
+async fn mutation_queue_persists_and_settles_atomically() {
+ IdbStorage::destroy("test-queue").await.unwrap();
+ let mut storage = IdbStorage::open("test-queue").await.unwrap();
+ let id = storage
+ .enqueue_mutation(queued("optimistic"))
+ .await
+ .unwrap();
+ storage.close();
+
+ let mut storage = IdbStorage::open("test-queue").await.unwrap();
+ let loaded = storage.load_mutation_queue().await.unwrap();
+ assert_eq!(loaded.len(), 1);
+ assert_eq!(loaded[0].id, id);
+ let claimed = storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner".into(),
+ now_ms: 20,
+ lease_expires_at_ms: 100,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ assert!(
+ storage
+ .complete_mutation(
+ id,
+ MutationClaimToken {
+ owner: "runner".into(),
+ generation: claimed.lease_generation,
+ },
+ vec![(key("A:1"), record("server"))],
+ )
+ .await
+ .unwrap()
+ );
+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());
+ assert_eq!(
+ storage.get_batch(&[key("A:1")]).await.unwrap()[0],
+ Some(record("server"))
+ );
+}
+
#[wasm_bindgen_test]
async fn engine_over_idb() {
IdbStorage::destroy("test-engine").await.unwrap();
diff --git a/crates/client/cache-sqlite/src/lib.rs b/crates/client/cache-sqlite/src/lib.rs
index 56a8c00cae..9e26dbbdec 100644
--- a/crates/client/cache-sqlite/src/lib.rs
+++ b/crates/client/cache-sqlite/src/lib.rs
@@ -13,10 +13,16 @@
#![deny(missing_docs)]
-use cache_core::codec::{cache_namespace, decode_record, encode_record};
+use cache_core::codec::{
+ cache_namespace, decode_record, decode_record_updates, encode_record, encode_record_updates,
+};
+use cache_core::queue::{
+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationRequest,
+ NewQueuedMutation, PersistedOptimisticLayer, QueuedMutation, StoredMutation,
+};
use cache_core::store::Storage;
use cache_core::value::{EntityKey, Record};
-use rusqlite::{Connection, OptionalExtension, params};
+use rusqlite::{Connection, OptionalExtension, Transaction, params};
use std::path::Path;
use std::sync::{Mutex, MutexGuard};
use thiserror::Error;
@@ -27,9 +33,12 @@ pub enum SqliteStorageError {
/// Underlying SQLite failure.
#[error("sqlite: {0}")]
Sqlite(#[from] rusqlite::Error),
- /// A stored record failed to decode (corruption → discard & rebuild).
+ /// A stored cache value failed to decode.
#[error(transparent)]
Codec(#[from] cache_core::codec::CodecError),
+ /// Durable queue metadata violated an invariant.
+ #[error("invalid mutation queue state: {0}")]
+ QueueInvariant(String),
}
/// [`Storage`] backend over a SQLite database (Tauri native host).
@@ -53,29 +62,77 @@ impl SqliteStorage {
Self::init(Connection::open_in_memory()?, scope)
}
- fn init(conn: Connection, scope: &str) -> Result<Self, SqliteStorageError> {
+ fn init(mut conn: Connection, scope: &str) -> Result<Self, SqliteStorageError> {
conn.pragma_update(None, "journal_mode", "WAL")?;
conn.pragma_update(None, "synchronous", "NORMAL")?;
+ conn.pragma_update(None, "foreign_keys", "ON")?;
conn.execute_batch(
- "CREATE TABLE IF NOT EXISTS meta (k TEXT PRIMARY KEY, v TEXT NOT NULL);
- CREATE TABLE IF NOT EXISTS records (key TEXT PRIMARY KEY, value BLOB NOT NULL);",
+ "CREATE TABLE IF NOT EXISTS meta (
+ k TEXT PRIMARY KEY,
+ v TEXT NOT NULL
+ );
+ CREATE TABLE IF NOT EXISTS records (
+ key TEXT PRIMARY KEY,
+ value BLOB NOT NULL
+ );
+ CREATE TABLE IF NOT EXISTS mutation_queue (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ query TEXT NOT NULL,
+ operation_name TEXT,
+ variables_json TEXT NOT NULL,
+ identity TEXT,
+ attempt_count INTEGER NOT NULL DEFAULT 0,
+ next_attempt_at_ms INTEGER,
+ lease_owner TEXT,
+ lease_generation INTEGER NOT NULL DEFAULT 0,
+ lease_expires_at_ms INTEGER,
+ last_error TEXT,
+ created_at_ms INTEGER NOT NULL
+ );
+ CREATE TABLE IF NOT EXISTS optimistic_layers (
+ mutation_id INTEGER PRIMARY KEY,
+ optimistic_data_json TEXT NOT NULL,
+ normalized_updates BLOB NOT NULL,
+ FOREIGN KEY(mutation_id) REFERENCES mutation_queue(id) ON DELETE CASCADE
+ );",
)?;
- let expected = cache_namespace(scope);
- let stored: Option<String> = conn
+ let expected_namespace = cache_namespace(scope);
+ let stored_scope: Option<String> = conn
+ .query_row("SELECT v FROM meta WHERE k = 'scope'", [], |row| row.get(0))
+ .optional()?;
+ let stored_namespace: Option<String> = conn
.query_row("SELECT v FROM meta WHERE k = 'namespace'", [], |row| {
row.get(0)
})
.optional()?;
- if stored.as_deref() != Some(expected.as_str()) {
- // Different user, schema or format → disposable rebuild.
- conn.execute("DELETE FROM records", [])?;
- conn.execute(
- "INSERT INTO meta (k, v) VALUES ('namespace', ?1)
- ON CONFLICT(k) DO UPDATE SET v = excluded.v",
- params![expected],
- )?;
+
+ let tx = conn.transaction()?;
+ if stored_scope.as_deref() != Some(scope) {
+ // Scope changes are identity changes: queued user intent must not
+ // cross the boundary. `None` is the one-time upgrade from the
+ // pre-queue schema, where no durable mutations existed.
+ tx.execute("DELETE FROM optimistic_layers", [])?;
+ tx.execute("DELETE FROM mutation_queue", [])?;
+ tx.execute("DELETE FROM records", [])?;
+ } else if stored_namespace.as_deref() != Some(expected_namespace.as_str()) {
+ // Record schema/format changes only invalidate disposable records.
+ // The queue retains source GraphQL + optimistic JSON so the engine
+ // can re-normalize it against the current schema.
+ tx.execute("DELETE FROM records", [])?;
}
+ tx.execute(
+ "INSERT INTO meta (k, v) VALUES ('scope', ?1)
+ ON CONFLICT(k) DO UPDATE SET v = excluded.v",
+ params![scope],
+ )?;
+ tx.execute(
+ "INSERT INTO meta (k, v) VALUES ('namespace', ?1)
+ ON CONFLICT(k) DO UPDATE SET v = excluded.v",
+ params![expected_namespace],
+ )?;
+ tx.commit()?;
+
Ok(SqliteStorage {
conn: Mutex::new(conn),
})
@@ -93,6 +150,74 @@ impl SqliteStorage {
.conn()
.query_row("SELECT COUNT(*) FROM records", [], |row| row.get(0))?)
}
+
+ /// Number of mutations waiting for settlement.
+ pub fn mutation_count(&self) -> Result<u64, SqliteStorageError> {
+ Ok(self
+ .conn()
+ .query_row("SELECT COUNT(*) FROM mutation_queue", [], |row| row.get(0))?)
+ }
+}
+
+fn mutation_id_from_sql(id: i64) -> Result<MutationId, SqliteStorageError> {
+ id.try_into()
+ .map_err(|_| SqliteStorageError::QueueInvariant(format!("negative mutation id {id}")))
+}
+
+fn mutation_id_to_sql(id: MutationId) -> Result<i64, SqliteStorageError> {
+ id.try_into().map_err(|_| {
+ SqliteStorageError::QueueInvariant(format!("mutation id {id} exceeds SQLite INTEGER"))
+ })
+}
+
+fn row_stored_mutation(row: &rusqlite::Row<'_>, offset: usize) -> rusqlite::Result<StoredMutation> {
+ let attempt_count: i64 = row.get(offset + 4)?;
+ let lease_generation: i64 = row.get(offset + 7)?;
+ Ok(StoredMutation {
+ request: MutationRequest {
+ query: row.get(offset)?,
+ operation_name: row.get(offset + 1)?,
+ variables_json: row.get(offset + 2)?,
+ identity: row.get(offset + 3)?,
+ },
+ attempt_count: attempt_count.try_into().map_err(|e| {
+ rusqlite::Error::FromSqlConversionFailure(
+ offset + 4,
+ rusqlite::types::Type::Integer,
+ Box::new(e),
+ )
+ })?,
+ next_attempt_at_ms: row.get(offset + 5)?,
+ lease_owner: row.get(offset + 6)?,
+ lease_generation: lease_generation.try_into().map_err(|e| {
+ rusqlite::Error::FromSqlConversionFailure(
+ offset + 7,
+ rusqlite::types::Type::Integer,
+ Box::new(e),
+ )
+ })?,
+ lease_expires_at_ms: row.get(offset + 8)?,
+ last_error: row.get(offset + 9)?,
+ created_at_ms: row.get(offset + 10)?,
+ })
+}
+
+fn claim_is_current(
+ tx: &Transaction<'_>,
+ id: i64,
+ claim: &MutationClaimToken,
+) -> Result<bool, rusqlite::Error> {
+ let current: Option<(Option<String>, i64)> = tx
+ .query_row(
+ "SELECT lease_owner, lease_generation FROM mutation_queue WHERE id = ?1",
+ params![id],
+ |row| Ok((row.get(0)?, row.get(1)?)),
+ )
+ .optional()?;
+ Ok(current.is_some_and(|(owner, generation)| {
+ owner.as_deref() == Some(&claim.owner)
+ && u64::try_from(generation).ok() == Some(claim.generation)
+ }))
}
impl Storage for SqliteStorage {
@@ -143,8 +268,241 @@ impl Storage for SqliteStorage {
Ok(())
}
+ async fn enqueue_mutation(
+ &mut self,
+ entry: NewQueuedMutation,
+ ) -> Result<MutationId, Self::Error> {
+ let mut conn = self.conn();
+ let tx = conn.transaction()?;
+ let mutation = &entry.mutation;
+ tx.execute(
+ "INSERT INTO mutation_queue (
+ query, operation_name, variables_json, identity,
+ attempt_count, next_attempt_at_ms, lease_owner,
+ lease_generation, lease_expires_at_ms, last_error, created_at_ms
+ ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)",
+ params![
+ mutation.request.query,
+ mutation.request.operation_name,
+ mutation.request.variables_json,
+ mutation.request.identity,
+ i64::from(mutation.attempt_count),
+ mutation.next_attempt_at_ms,
+ mutation.lease_owner,
+ i64::try_from(mutation.lease_generation).map_err(|_| {
+ SqliteStorageError::QueueInvariant(
+ "lease generation exceeds SQLite INTEGER".to_string(),
+ )
+ })?,
+ mutation.lease_expires_at_ms,
+ mutation.last_error,
+ mutation.created_at_ms,
+ ],
+ )?;
+ let sql_id = tx.last_insert_rowid();
+ tx.execute(
+ "INSERT INTO optimistic_layers (
+ mutation_id, optimistic_data_json, normalized_updates
+ ) VALUES (?1, ?2, ?3)",
+ params![
+ sql_id,
+ entry.optimistic.optimistic_data_json,
+ encode_record_updates(&entry.optimistic.normalized_updates),
+ ],
+ )?;
+ tx.commit()?;
+ mutation_id_from_sql(sql_id)
+ }
+
+ async fn load_mutation_queue(&self) -> Result<Vec<QueuedMutation>, Self::Error> {
+ let conn = self.conn();
+ let mut stmt = conn.prepare_cached(
+ "SELECT
+ m.id, m.query, m.operation_name, m.variables_json, m.identity,
+ m.attempt_count, m.next_attempt_at_ms, m.lease_owner,
+ m.lease_generation, m.lease_expires_at_ms, m.last_error,
+ m.created_at_ms, o.optimistic_data_json, o.normalized_updates
+ FROM mutation_queue m
+ INNER JOIN optimistic_layers o ON o.mutation_id = m.id
+ ORDER BY m.id ASC",
+ )?;
+ let mut rows = stmt.query([])?;
+ let mut out = Vec::new();
+ while let Some(row) = rows.next()? {
+ let id: i64 = row.get(0)?;
+ let updates: Vec<u8> = row.get(13)?;
+ out.push(QueuedMutation {
+ id: mutation_id_from_sql(id)?,
+ mutation: row_stored_mutation(row, 1)?,
+ optimistic: PersistedOptimisticLayer {
+ optimistic_data_json: row.get(12)?,
+ normalized_updates: decode_record_updates(&updates)?,
+ },
+ });
+ }
+ Ok(out)
+ }
+
+ async fn claim_next_mutation(
+ &mut self,
+ request: MutationClaimRequest,
+ ) -> Result<Option<ClaimedMutation>, Self::Error> {
+ let mut conn = self.conn();
+ let tx = conn.transaction()?;
+ let head: Option<(i64, StoredMutation)> = tx
+ .query_row(
+ "SELECT
+ id, query, operation_name, variables_json, identity,
+ attempt_count, next_attempt_at_ms, lease_owner,
+ lease_generation, lease_expires_at_ms, last_error,
+ created_at_ms
+ FROM mutation_queue
+ ORDER BY id ASC
+ LIMIT 1",
+ [],
+ |row| Ok((row.get(0)?, row_stored_mutation(row, 1)?)),
+ )
+ .optional()?;
+ let Some((sql_id, mut mutation)) = head else {
+ tx.commit()?;
+ return Ok(None);
+ };
+ if mutation
+ .next_attempt_at_ms
+ .is_some_and(|next| next > request.now_ms)
+ || mutation
+ .lease_expires_at_ms
+ .is_some_and(|expiry| expiry > request.now_ms)
+ {
+ tx.commit()?;
+ return Ok(None);
+ }
+
+ mutation.attempt_count = mutation.attempt_count.saturating_add(1);
+ mutation.lease_generation = mutation.lease_generation.saturating_add(1);
+ mutation.lease_owner = Some(request.owner.clone());
+ mutation.lease_expires_at_ms = Some(request.lease_expires_at_ms);
+ mutation.next_attempt_at_ms = None;
+ tx.execute(
+ "UPDATE mutation_queue SET
+ attempt_count = ?2,
+ next_attempt_at_ms = NULL,
+ lease_owner = ?3,
+ lease_generation = ?4,
+ lease_expires_at_ms = ?5
+ WHERE id = ?1",
+ params![
+ sql_id,
+ i64::from(mutation.attempt_count),
+ mutation.lease_owner,
+ i64::try_from(mutation.lease_generation).map_err(|_| {
+ SqliteStorageError::QueueInvariant(
+ "lease generation exceeds SQLite INTEGER".to_string(),
+ )
+ })?,
+ mutation.lease_expires_at_ms,
+ ],
+ )?;
+ let (optimistic_data_json, updates): (String, Vec<u8>) = tx.query_row(
+ "SELECT optimistic_data_json, normalized_updates
+ FROM optimistic_layers WHERE mutation_id = ?1",
+ params![sql_id],
+ |row| Ok((row.get(0)?, row.get(1)?)),
+ )?;
+ let generation = mutation.lease_generation;
+ let queued = QueuedMutation {
+ id: mutation_id_from_sql(sql_id)?,
+ mutation,
+ optimistic: PersistedOptimisticLayer {
+ optimistic_data_json,
+ normalized_updates: decode_record_updates(&updates)?,
+ },
+ };
+ tx.commit()?;
+ Ok(Some(ClaimedMutation {
+ queued,
+ lease_generation: generation,
+ }))
+ }
+
+ async fn defer_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ next_attempt_at_ms: i64,
+ error: String,
+ ) -> Result<bool, Self::Error> {
+ let sql_id = mutation_id_to_sql(id)?;
+ let mut conn = self.conn();
+ let tx = conn.transaction()?;
+ if !claim_is_current(&tx, sql_id, &claim)? {
+ tx.commit()?;
+ return Ok(false);
+ }
+ tx.execute(
+ "UPDATE mutation_queue SET
+ next_attempt_at_ms = ?2,
+ lease_owner = NULL,
+ lease_expires_at_ms = NULL,
+ last_error = ?3
+ WHERE id = ?1",
+ params![sql_id, next_attempt_at_ms, error],
+ )?;
+ tx.commit()?;
+ Ok(true)
+ }
+
+ async fn complete_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ entries: Vec<(EntityKey, Record)>,
+ ) -> Result<bool, Self::Error> {
+ let sql_id = mutation_id_to_sql(id)?;
+ let mut conn = self.conn();
+ let tx = conn.transaction()?;
+ if !claim_is_current(&tx, sql_id, &claim)? {
+ tx.commit()?;
+ return Ok(false);
+ }
+ {
+ let mut stmt = tx.prepare_cached(
+ "INSERT INTO records (key, value) VALUES (?1, ?2)
+ ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+ )?;
+ for (key, record) in &entries {
+ stmt.execute(params![key.0, encode_record(record)])?;
+ }
+ }
+ tx.execute("DELETE FROM mutation_queue WHERE id = ?1", params![sql_id])?;
+ tx.commit()?;
+ Ok(true)
+ }
+
+ async fn discard_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ ) -> Result<bool, Self::Error> {
+ let sql_id = mutation_id_to_sql(id)?;
+ let mut conn = self.conn();
+ let tx = conn.transaction()?;
+ if !claim_is_current(&tx, sql_id, &claim)? {
+ tx.commit()?;
+ return Ok(false);
+ }
+ tx.execute("DELETE FROM mutation_queue WHERE id = ?1", params![sql_id])?;
+ tx.commit()?;
+ Ok(true)
+ }
+
async fn clear(&mut self) -> Result<(), Self::Error> {
- self.conn().execute("DELETE FROM records", [])?;
+ let mut conn = self.conn();
+ let tx = conn.transaction()?;
+ tx.execute("DELETE FROM optimistic_layers", [])?;
+ tx.execute("DELETE FROM mutation_queue", [])?;
+ tx.execute("DELETE FROM records", [])?;
+ tx.commit()?;
Ok(())
}
}
diff --git a/crates/client/cache-sqlite/tests/mutation_queue.rs b/crates/client/cache-sqlite/tests/mutation_queue.rs
new file mode 100644
index 0000000000..1abe4d10cc
--- /dev/null
+++ b/crates/client/cache-sqlite/tests/mutation_queue.rs
@@ -0,0 +1,203 @@
+use cache_core::queue::{
+ MutationClaimRequest, MutationClaimToken, MutationRequest, NewQueuedMutation,
+ PersistedOptimisticLayer, StoredMutation,
+};
+use cache_core::store::Storage;
+use cache_core::value::{CacheValue, EntityKey, Record};
+use cache_sqlite::SqliteStorage;
+use pollster::block_on;
+
+const CACHE_QUERY: &str = r#"
+query Soup($input: SoupInput!) {
+ user {
+ id
+ soup(input: $input) {
+ items {
+ id
+ entity {
+ __typename
+ ... on GraphqlSoupDocument {
+ id
+ properties { id displayName }
+ }
+ }
+ }
+ hasMore
+ }
+ }
+}
+"#;
+
+const CACHE_MUTATION: &str = r#"
+mutation SetEntityProperty($input: SetEntityPropertyInput!) {
+ setEntityProperty(input: $input) { id displayName }
+}
+"#;
+
+fn queued(value: &str) -> NewQueuedMutation {
+ let mut update = Record::default();
+ update
+ .fields
+ .insert("name".into(), CacheValue::String(value.into()));
+ NewQueuedMutation {
+ mutation: StoredMutation::new(
+ MutationRequest {
+ query: "mutation Rename { rename { id } }".into(),
+ operation_name: Some("Rename".into()),
+ variables_json: format!(r#"{{"name":"{value}"}}"#),
+ identity: Some("user-1".into()),
+ },
+ 10,
+ ),
+ optimistic: PersistedOptimisticLayer {
+ optimistic_data_json: format!(r#"{{"rename":{{"name":"{value}"}}}}"#),
+ normalized_updates: [(EntityKey("Thing:1".into()), update)].into(),
+ },
+ }
+}
+
+#[test]
+fn queue_and_optimistic_layer_survive_reopen() {
+ block_on(async {
+ let dir = tempfile::tempdir().unwrap();
+ let path = dir.path().join("cache.db");
+ let mut storage = SqliteStorage::open(&path, "scope-1").unwrap();
+ let id = storage
+ .enqueue_mutation(queued("optimistic"))
+ .await
+ .unwrap();
+ drop(storage);
+
+ let mut storage = SqliteStorage::open(&path, "scope-1").unwrap();
+ let loaded = storage.load_mutation_queue().await.unwrap();
+ assert_eq!(loaded.len(), 1);
+ assert_eq!(loaded[0].id, id);
+ assert_eq!(
+ loaded[0].optimistic.optimistic_data_json,
+ r#"{"rename":{"name":"optimistic"}}"#
+ );
+
+ let claimed = storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner".into(),
+ now_ms: 20,
+ lease_expires_at_ms: 100,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ let mut real = Record::default();
+ real.fields
+ .insert("name".into(), CacheValue::String("server".into()));
+ assert!(
+ storage
+ .complete_mutation(
+ id,
+ MutationClaimToken {
+ owner: "runner".into(),
+ generation: claimed.lease_generation,
+ },
+ vec![(EntityKey("Thing:1".into()), real.clone())],
+ )
+ .await
+ .unwrap()
+ );
+ drop(storage);
+
+ let storage = SqliteStorage::open(&path, "scope-1").unwrap();
+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());
+ assert_eq!(
+ storage
+ .get_batch(&[EntityKey("Thing:1".into())])
+ .await
+ .unwrap()[0],
+ Some(real)
+ );
+ });
+}
+
+#[test]
+fn engine_hydrates_optimistic_layer_after_restart() {
+ use cache_core::engine::{Engine, ReadResult};
+ use serde_json::json;
+
+ block_on(async {
+ let dir = tempfile::tempdir().unwrap();
+ let path = dir.path().join("cache.db");
+ let serde_json::Value::Object(query_vars) = json!({"input": {"limit": 1}}) else {
+ unreachable!()
+ };
+ let serde_json::Value::Object(mutation_vars) = json!({"input": {
+ "entityType": "DOCUMENT",
+ "entityId": "doc-1",
+ "propertyDefinitionId": "def-1",
+ "value": {"string": "x"}
+ }}) else {
+ unreachable!()
+ };
+ let base = json!({"user": {"id": "user-1", "soup": {
+ "items": [{"id": "item-1", "entity": {
+ "__typename": "GraphqlSoupDocument",
+ "id": "doc-1",
+ "properties": [{"id": "prop-1", "displayName": "Status"}]
+ }}],
+ "hasMore": false
+ }}});
+ let optimistic = json!({"setEntityProperty": {
+ "id": "prop-1",
+ "displayName": "Stage"
+ }});
+
+ let mut engine = Engine::new(SqliteStorage::open(&path, "scope-1").unwrap());
+ engine
+ .write_query(
+ None,
+ CACHE_QUERY,
+ Some("Soup"),
+ &query_vars,
+ &base,
+ Some("user-1"),
+ )
+ .await
+ .unwrap();
+ engine
+ .begin_optimistic_write(
+ None,
+ CACHE_MUTATION,
+ Some("SetEntityProperty"),
+ &mutation_vars,
+ &optimistic,
+ 10,
+ )
+ .await
+ .unwrap();
+ drop(engine);
+
+ let mut reopened = Engine::new(SqliteStorage::open(&path, "scope-1").unwrap());
+ let ReadResult::Hit { data } = reopened
+ .read_query(None, CACHE_QUERY, Some("Soup"), &query_vars)
+ .await
+ .unwrap()
+ else {
+ panic!("expected hydrated hit");
+ };
+ assert_eq!(
+ data["user"]["soup"]["items"][0]["entity"]["properties"][0]["displayName"],
+ json!("Stage")
+ );
+ });
+}
+
+#[test]
+fn scope_change_clears_queued_user_intent() {
+ block_on(async {
+ let dir = tempfile::tempdir().unwrap();
+ let path = dir.path().join("cache.db");
+ let mut storage = SqliteStorage::open(&path, "scope-1").unwrap();
+ storage.enqueue_mutation(queued("a")).await.unwrap();
+ drop(storage);
+
+ let storage = SqliteStorage::open(&path, "scope-2").unwrap();
+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());
+ });
+}
diff --git a/crates/client/cache-wasm/src/shell.rs b/crates/client/cache-wasm/src/shell.rs
index bbb6e82049..22f53422d1 100644
--- a/crates/client/cache-wasm/src/shell.rs
+++ b/crates/client/cache-wasm/src/shell.rs
@@ -1,6 +1,7 @@
use async_lock::Mutex;
use cache_core::deps::OpId;
use cache_core::engine::{Engine, ReadResult};
+use cache_core::queue::{ClaimedMutation, MutationClaimRequest, MutationClaimToken};
use cache_core::value::EntityKey;
use cache_idb::IdbStorage;
use serde::Serialize;
@@ -67,11 +68,56 @@ struct JsOptimisticWriteResult {
reset: bool,
}
-/// Transaction ids cross the boundary as strings (JS numbers lose precision
-/// past 2^53; ids are opaque to the host anyway).
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct JsClaimedMutation {
+ transaction_id: String,
+ lease_generation: String,
+ query: String,
+ operation_name: Option<String>,
+ variables: serde_json::Value,
+ identity: Option<String>,
+ attempt_count: u32,
+}
+
+impl TryFrom<ClaimedMutation> for JsClaimedMutation {
+ type Error = JsValue;
+
+ fn try_from(claimed: ClaimedMutation) -> Result<Self, Self::Error> {
+ let request = claimed.queued.mutation.request;
+ Ok(Self {
+ transaction_id: claimed.queued.id.to_string(),
+ lease_generation: claimed.lease_generation.to_string(),
+ query: request.query,
+ operation_name: request.operation_name,
+ variables: serde_json::from_str(&request.variables_json).map_err(err_js)?,
+ identity: request.identity,
+ attempt_count: claimed.queued.mutation.attempt_count,
+ })
+ }
+}
+
+/// Queue ids and lease generations cross the boundary as strings because JS
+/// numbers lose precision past 2^53.
+fn parse_u64(value: &str, label: &str) -> Result<u64, JsValue> {
+ value
+ .parse::<u64>()
+ .map_err(|_| err_js(format!("invalid {label} `{value}`")))
+}
+
fn parse_transaction_id(id: &str) -> Result<u64, JsValue> {
- id.parse::<u64>()
- .map_err(|_| err_js(format!("invalid optimistic transaction id `{id}`")))
+ parse_u64(id, "optimistic transaction id")
+}
+
+fn parse_timestamp(value: f64, label: &str) -> Result<i64, JsValue> {
+ if !value.is_finite()
+ || value.fract() != 0.0
+ || value < i64::MIN as f64
+ || value >= i64::MAX as f64
+ {
+ return Err(err_js(format!("invalid {label} `{value}`")));
+ }
+ Ok(value as i64)
}
#[wasm_bindgen]
@@ -206,10 +252,9 @@ impl CacheEngine {
})
}
- /// Installs an in-memory optimistic layer from a mutation's optimistic
- /// response; persists nothing. Resolves to `{transactionId: string,
- /// changed: string[], affectedOps: string[], reset: false}` where
- /// `changed`/`affectedOps` reflect *visible* (composed-view) changes.
+ /// Durably queues a mutation and its optimistic response. Resolves to
+ /// `{transactionId: string, changed: string[], affectedOps: string[],
+ /// reset: false}` where changes reflect the composed view.
#[wasm_bindgen(js_name = beginOptimisticWrite)]
pub fn begin_optimistic_write(
&self,
@@ -218,16 +263,25 @@ impl CacheEngine {
operation_name: Option<String>,
variables: JsValue,
data: JsValue,
+ created_at_ms: f64,
) -> js_sys::Promise {
let engine = self.engine.clone();
let ops = self.ops.clone();
future_to_promise(async move {
let vars = parse_variables(variables)?;
let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;
+ let created_at_ms = parse_timestamp(created_at_ms, "enqueue timestamp")?;
let origin = origin_op_id.map(|name| ops.borrow_mut().intern(&name));
let mut engine = engine.lock().await;
let (transaction, result) = engine
- .begin_optimistic_write(origin, &query, operation_name.as_deref(), &vars, &data)
+ .begin_optimistic_write(
+ origin,
+ &query,
+ operation_name.as_deref(),
+ &vars,
+ &data,
+ created_at_ms,
+ )
.await
.map_err(err_js)?;
to_js(&JsOptimisticWriteResult {
@@ -239,15 +293,74 @@ impl CacheEngine {
})
}
- /// Atomically replaces a pending optimistic layer with the real network
- /// response and flushes any contiguous settled layers durably. Resolves
- /// to a write result whose `changed` keys are the *durably* changed
- /// records (cross-instance broadcast) and whose `affectedOps` reflect
- /// visible changes. Rejects on unknown/settled transaction ids.
+ /// Claims the oldest runnable queued mutation.
+ #[wasm_bindgen(js_name = claimNextMutation)]
+ pub fn claim_next_mutation(
+ &self,
+ owner: String,
+ now_ms: f64,
+ lease_expires_at_ms: f64,
+ ) -> js_sys::Promise {
+ let engine = self.engine.clone();
+ future_to_promise(async move {
+ let request = MutationClaimRequest {
+ owner,
+ now_ms: parse_timestamp(now_ms, "claim timestamp")?,
+ lease_expires_at_ms: parse_timestamp(
+ lease_expires_at_ms,
+ "lease expiration timestamp",
+ )?,
+ };
+ let claimed = engine
+ .lock()
+ .await
+ .claim_next_mutation(request)
+ .await
+ .map_err(err_js)?;
+ to_js(&claimed.map(JsClaimedMutation::try_from).transpose()?)
+ })
+ }
+
+ /// Retains a retryable mutation and releases its queue lease.
+ #[wasm_bindgen(js_name = deferOptimisticWrite)]
+ pub fn defer_optimistic_write(
+ &self,
+ transaction_id: String,
+ lease_owner: String,
+ lease_generation: String,
+ next_attempt_at_ms: f64,
+ error: String,
+ ) -> js_sys::Promise {
+ let engine = self.engine.clone();
+ future_to_promise(async move {
+ let transaction = parse_transaction_id(&transaction_id)?;
+ let claim = MutationClaimToken {
+ owner: lease_owner,
+ generation: parse_u64(&lease_generation, "lease generation")?,
+ };
+ engine
+ .lock()
+ .await
+ .defer_optimistic_write(
+ transaction,
+ claim,
+ parse_timestamp(next_attempt_at_ms, "next attempt timestamp")?,
+ error,
+ )
+ .await
+ .map_err(err_js)?;
+ Ok(JsValue::UNDEFINED)
+ })
+ }
+
+ /// Atomically replaces a claimed optimistic layer with the real network
+ /// response and removes it from the durable queue.
#[wasm_bindgen(js_name = commitOptimisticWrite)]
pub fn commit_optimistic_write(
&self,
transaction_id: String,
+ lease_owner: String,
+ lease_generation: String,
query: String,
operation_name: Option<String>,
variables: JsValue,
@@ -257,12 +370,17 @@ impl CacheEngine {
let ops = self.ops.clone();
future_to_promise(async move {
let transaction = parse_transaction_id(&transaction_id)?;
+ let claim = MutationClaimToken {
+ owner: lease_owner,
+ generation: parse_u64(&lease_generation, "lease generation")?,
+ };
let vars = parse_variables(variables)?;
let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;
let mut engine = engine.lock().await;
let result = engine
.commit_optimistic_write(
transaction,
+ claim,
&query,
operation_name.as_deref(),
&vars,
@@ -278,18 +396,26 @@ impl CacheEngine {
})
}
- /// Removes a pending optimistic layer's contribution (mutation failed)
- /// and flushes any now-contiguous settled layers. Result semantics match
- /// [`commitOptimisticWrite`](Self::commit_optimistic_write).
+ /// Permanently fails a claimed mutation and removes its optimistic
+ /// contribution.
#[wasm_bindgen(js_name = rollbackOptimisticWrite)]
- pub fn rollback_optimistic_write(&self, transaction_id: String) -> js_sys::Promise {
+ pub fn rollback_optimistic_write(
+ &self,
+ transaction_id: String,
+ lease_owner: String,
+ lease_generation: String,
+ ) -> js_sys::Promise {
let engine = self.engine.clone();
let ops = self.ops.clone();
future_to_promise(async move {
let transaction = parse_transaction_id(&transaction_id)?;
+ let claim = MutationClaimToken {
+ owner: lease_owner,
+ generation: parse_u64(&lease_generation, "lease generation")?,
+ };
let mut engine = engine.lock().await;
let result = engine
- .rollback_optimistic_write(transaction)
+ .rollback_optimistic_write(transaction, claim)
.await
.map_err(err_js)?;
to_js(&JsWriteResult {
@@ -315,6 +441,27 @@ impl CacheEngine {
})
}
+ /// Reloads optimistic layers after another engine changes the durable
+ /// queue and returns locally affected operations.
+ #[wasm_bindgen(js_name = refreshOptimisticQueue)]
+ pub fn refresh_optimistic_queue(&self) -> js_sys::Promise {
+ let engine = self.engine.clone();
+ let ops = self.ops.clone();
+ future_to_promise(async move {
+ let result = engine
+ .lock()
+ .await
+ .refresh_optimistic_queue()
+ .await
+ .map_err(err_js)?;
+ to_js(&JsWriteResult {
+ changed: result.changed.into_iter().map(|key| key.0).collect(),
+ affected_ops: ops.borrow().names(result.affected_ops),
+ reset: result.reset,
+ })
+ })
+ }
+
/// Reacts to a cache reset performed by another engine instance sharing
/// the same storage (cross-tab broadcast). Drops local in-memory state
/// and resolves to every local operation id (all must re-execute).
diff --git a/crates/client/cache-wasm/tests/web.rs b/crates/client/cache-wasm/tests/web.rs
index c7d14b5dba..3109be200e 100644
--- a/crates/client/cache-wasm/tests/web.rs
+++ b/crates/client/cache-wasm/tests/web.rs
@@ -151,6 +151,7 @@ async fn optimistic_write_round_trip() {
Some("SetEntityProperty".into()),
js(mutation_vars.clone()),
js(serde_json::json!({ "setEntityProperty": { "id": "prop-1", "displayName": "Stage" } })),
+ 123.0,
))
.await
.unwrap();
@@ -177,9 +178,18 @@ async fn optimistic_write_round_trip() {
serde_json::json!("Stage")
);
+ let claimed = JsFuture::from(engine.claim_next_mutation("runner".into(), 10.0, 1_000.0))
+ .await
+ .unwrap();
+ let claimed: serde_json::Value = serde_wasm_bindgen::from_value(claimed).unwrap();
+ assert_eq!(claimed["transactionId"], txn);
+ let generation = claimed["leaseGeneration"].as_str().unwrap().to_string();
+
// Commit with the real response; the layer flushes durably.
let commit = JsFuture::from(engine.commit_optimistic_write(
txn.clone(),
+ "runner".into(),
+ generation.clone(),
PROPERTY_MUTATION.into(),
Some("SetEntityProperty".into()),
js(mutation_vars.clone()),
@@ -195,10 +205,16 @@ async fn optimistic_write_round_trip() {
assert_eq!(commit["affectedOps"], serde_json::json!(["tab1:1"]));
// Settled transactions reject further commits/rollbacks.
- let err = JsFuture::from(engine.rollback_optimistic_write(txn)).await;
+ let err =
+ JsFuture::from(engine.rollback_optimistic_write(txn, "runner".into(), generation)).await;
assert!(err.is_err());
// Malformed ids reject too.
- let err = JsFuture::from(engine.rollback_optimistic_write("not-a-number".into())).await;
+ let err = JsFuture::from(engine.rollback_optimistic_write(
+ "not-a-number".into(),
+ "runner".into(),
+ "1".into(),
+ ))
+ .await;
assert!(err.is_err());
JsFuture::from(engine.close()).await.unwrap();