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/upsert optimistic queue (#6078)

Sean Aye80c17dc4aaeb
diff --git a/Cargo.lock b/Cargo.lock
index 021d44b57e..25a044d6b5 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2935,6 +2935,7 @@ dependencies = [
"serde_json",
"sha2 0.10.9",
"thiserror 2.0.18",
+ "uuid",
]
[[package]]
@@ -2950,12 +2951,13 @@ dependencies = [
"thiserror 2.0.18",
"turso-opfs",
"turso_core",
+ "uuid",
"wasm-bindgen-test",
]
[[package]]
name = "cache-wasm"
-version = "0.6.3"
+version = "0.6.4"
dependencies = [
"async-lock",
"cache-core",
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 725106c262..c66debf635 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
@@ -21,6 +21,7 @@ import type { CacheHost } from '../host/types';
import {
ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,
type ClaimedMutation,
+ type CommitOptimisticWriteResult,
type EnqueueOptimisticMutationResult,
INITIAL_CACHE_REVISION,
type MutationClaim,
@@ -219,6 +220,8 @@ function makeFakeHost(): FakeHost {
host.claims.push(head.transactionId);
return {
transactionId: head.transactionId,
+ uuid: head.args.uuid,
+ superseded: false,
leaseGeneration: String(head.attemptCount),
query: head.args.query,
operationName: head.args.operationName,
@@ -318,6 +321,7 @@ function makeFakeHost(): FakeHost {
changed: [],
affectedOps: [],
reset: false,
+ upsertKind: { kind: 'inserted' },
initialClaim: mutation
? { kind: 'claimed', mutation }
: { kind: 'not-runnable' },
@@ -347,25 +351,28 @@ function makeFakeHost(): FakeHost {
head.leased = false;
head.nextAttemptAtMs = nextAttemptAtMs;
}
+ return { kind: 'deferred' };
},
async commitOptimisticWrite(
transactionId,
_claim,
args
- ): Promise<WriteResult> {
+ ): Promise<CommitOptimisticWriteResult> {
host.commits.push({ transactionId, query: args.query, data: args.data });
if (queue[0]?.transactionId === transactionId) queue.shift();
return {
+ kind: 'committed',
revision: INITIAL_CACHE_REVISION,
changed: [],
affectedOps: [],
reset: false,
};
},
- async rollbackOptimisticWrite(transactionId, _claim): Promise<WriteResult> {
+ async rollbackOptimisticWrite(transactionId, _claim) {
host.rollbacks.push(transactionId);
if (queue[0]?.transactionId === transactionId) queue.shift();
return {
+ kind: 'rolled-back' as const,
revision: INITIAL_CACHE_REVISION,
changed: [],
affectedOps: [],
@@ -466,7 +473,12 @@ function makeMutationOp(key: number, optimisticResponse?: unknown): Operation {
suspense: false,
...(optimisticResponse === undefined
? {}
- : { normalizedCacheOptimistic: { optimisticResponse } }),
+ : {
+ normalizedCacheOptimistic: {
+ uuid: crypto.randomUUID(),
+ optimisticResponse,
+ },
+ }),
} as never
);
}
@@ -1539,6 +1551,7 @@ describe('normalizedCacheExchange', () => {
it('replays a persisted mutation when the exchange starts', async () => {
host.seedQueued({
+ uuid: '00000000-0000-4000-8000-000000000001',
query: stringifyDocument(MUTATION),
operationName: 'SetEntityProperty',
variables: { input: {} },
@@ -1556,6 +1569,7 @@ describe('normalizedCacheExchange', () => {
it('rolls back when a persisted replay resolves with an urql error', async () => {
host.seedQueued({
+ uuid: '00000000-0000-4000-8000-000000000002',
query: stringifyDocument(MUTATION),
operationName: 'SetEntityProperty',
variables: { input: {} },
@@ -1704,6 +1718,7 @@ describe('normalizedCacheExchange', () => {
const operation = makeOperation(base.kind, base, {
...base.context,
normalizedCacheOptimistic: {
+ uuid: crypto.randomUUID(),
optimisticResponse: optimistic,
linkPatches: [
{
@@ -1734,6 +1749,7 @@ describe('normalizedCacheExchange', () => {
it('replays an older returned claim and reports the new caller as queued', async () => {
host.seedQueued({
+ uuid: '00000000-0000-4000-8000-000000000003',
query: stringifyDocument(MUTATION),
operationName: 'SetEntityProperty',
variables: { input: { restored: true } },
@@ -1819,6 +1835,7 @@ describe('normalizedCacheExchange', () => {
const op = makeOperation(base.kind, base, {
...base.context,
normalizedCacheOptimistic: {
+ uuid: crypto.randomUUID(),
optimisticResponse: optimistic,
linkPatches: [patch],
revalidations: [],
@@ -1836,6 +1853,7 @@ describe('normalizedCacheExchange', () => {
const op = makeOperation(base.kind, base, {
...base.context,
normalizedCacheOptimistic: {
+ uuid: crypto.randomUUID(),
optimisticResponse: optimistic,
linkPatches: [
{
@@ -1930,6 +1948,26 @@ describe('normalizedCacheExchange', () => {
expect(host.writes).toHaveLength(0);
});
+ it('does not expose a stale response when commit lands beneath a replacement', async () => {
+ const commit = host.commitOptimisticWrite.bind(host);
+ host.commitOptimisticWrite = async (transactionId, claim, args) => ({
+ ...(await commit(transactionId, claim, args)),
+ kind: 'committed-superseded',
+ replacementTransactionId: 'txn-2',
+ });
+ const { ops, results } = harness(host);
+
+ ops.next(makeMutationOp(1, optimistic));
+ await tick();
+
+ expect(host.commits[0]?.data).toEqual({ from: 'network' });
+ expect(results[0]?.data).toBeUndefined();
+ expect(optimisticMutationDispositionOf(results[0])).toEqual({
+ kind: 'queued',
+ transactionId: 'txn-2',
+ });
+ });
+
it('replays mixed explicit cache effects in order after an optimistic commit', async () => {
const deletion = {
__typename: 'GraphqlCacheDeletion',
@@ -1958,6 +1996,7 @@ describe('normalizedCacheExchange', () => {
const operation = makeOperation(base.kind, base, {
...base.context,
normalizedCacheOptimistic: {
+ uuid: crypto.randomUUID(),
optimisticResponse: {
renameEntities: { results: [] },
},
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 a488070413..e7ad69735f 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
@@ -732,6 +732,27 @@ export function normalizedCacheExchange(
claimed: ClaimedMutation
): Promise<void> {
deferredUntil = undefined;
+ if (claimed.superseded) {
+ const discarded = await host.deferOptimisticWrite(
+ claimed.transactionId,
+ { owner: queueOwner, generation: claimed.leaseGeneration },
+ Date.now(),
+ 'superseded before network replay'
+ );
+ if (discarded.kind !== 'discarded-superseded') {
+ throw new Error('superseded mutation was unexpectedly deferred');
+ }
+ const live = liveQueuedOps.get(claimed.transactionId);
+ if (live) {
+ liveQueuedOps.delete(claimed.transactionId);
+ live.resolveRoute(
+ queuedMutationResult(live.operation, claimed.transactionId)
+ );
+ }
+ resolveLiveOperationsAsQueued();
+ scheduleDrain();
+ return;
+ }
attemptInFlight = true;
const attempt: QueueAttemptContext = {
transactionId: claimed.transactionId,
@@ -925,6 +946,7 @@ export function normalizedCacheExchange(
return undefined;
}
const args = {
+ uuid: optimistic.uuid,
query: queryText(op),
operationName: operationName(op),
variables: op.variables as Record<string, unknown> | undefined,
@@ -980,6 +1002,20 @@ export function normalizedCacheExchange(
return undefined;
}
}
+ if (enqueue.upsertKind.kind === 'replaced-pending') {
+ const superseded = liveQueuedOps.get(
+ enqueue.upsertKind.removedTransactionId
+ );
+ if (superseded) {
+ liveQueuedOps.delete(enqueue.upsertKind.removedTransactionId);
+ superseded.resolveRoute(
+ queuedMutationResult(
+ superseded.operation,
+ enqueue.upsertKind.removedTransactionId
+ )
+ );
+ }
+ }
const routed = new Promise<OperationResult | undefined>((resolve) => {
liveQueuedOps.set(enqueue.transactionId, {
operation: op,
@@ -1164,8 +1200,12 @@ export function normalizedCacheExchange(
generation: attempt.leaseGeneration,
};
let retryAt: number | undefined;
- let disposition: 'committed' | 'queued' | 'permanently-failed' =
- 'queued';
+ let replacementTransactionId: string | undefined;
+ let disposition:
+ | 'committed'
+ | 'queued'
+ | 'superseded'
+ | 'permanently-failed' = 'queued';
try {
if (result.error || result.data == null) {
let retry = false;
@@ -1178,20 +1218,33 @@ export function normalizedCacheExchange(
}
if (retry) {
retryAt = Date.now() + retryDelayMs(attempt.attemptCount);
- await host.deferOptimisticWrite(
+ const deferred = await host.deferOptimisticWrite(
attempt.transactionId,
claim,
retryAt,
result.error?.message ?? 'mutation returned no data'
);
- disposition = 'queued';
+ if (deferred.kind === 'discarded-superseded') {
+ retryAt = undefined;
+ replacementTransactionId =
+ deferred.replacementTransactionId;
+ disposition = 'superseded';
+ } else {
+ disposition = 'queued';
+ }
} else {
- await host.rollbackOptimisticWrite(
+ const rolledBack = await host.rollbackOptimisticWrite(
attempt.transactionId,
claim,
result.error?.message ?? 'mutation returned no data'
);
- disposition = 'permanently-failed';
+ if (rolledBack.kind === 'discarded-superseded') {
+ replacementTransactionId =
+ rolledBack.replacementTransactionId;
+ disposition = 'superseded';
+ } else {
+ disposition = 'permanently-failed';
+ }
}
} else {
const committed = await host.commitOptimisticWrite(
@@ -1214,7 +1267,12 @@ export function normalizedCacheExchange(
await applyOperationCacheEffects(op, effects);
}
revalidateAfterCommit(committed.revalidations ?? [], op);
- disposition = 'committed';
+ if (committed.kind === 'committed-superseded') {
+ replacementTransactionId = committed.replacementTransactionId;
+ disposition = 'superseded';
+ } else {
+ disposition = 'committed';
+ }
}
} catch (error) {
options.onCacheError?.(error, op);
@@ -1231,10 +1289,20 @@ export function normalizedCacheExchange(
retryAt === undefined ? 0 : Math.max(0, retryAt - Date.now())
);
}
- return withOptimisticMutationDisposition(result, {
- kind: disposition,
- transactionId: attempt.transactionId,
- });
+ return withOptimisticMutationDisposition(
+ result,
+ disposition === 'superseded'
+ ? {
+ kind: 'superseded',
+ transactionId: attempt.transactionId,
+ replacementTransactionId:
+ replacementTransactionId ?? attempt.transactionId,
+ }
+ : {
+ kind: disposition,
+ transactionId: attempt.transactionId,
+ }
+ );
}
const optimistic = optimisticContextOf(op);
diff --git a/apps/web/src/lib/graphql-cache/exchange/optimistic.test.ts b/apps/web/src/lib/graphql-cache/exchange/optimistic.test.ts
index fc5dee5fb9..cd972a0c44 100644
--- a/apps/web/src/lib/graphql-cache/exchange/optimistic.test.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/optimistic.test.ts
@@ -1,6 +1,9 @@
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
import { GroupSoupMembershipDocument } from '@service-storage/graphql/generated/graphql';
+import type { Client } from '@urql/core';
import { describe, expect, it } from 'vitest';
import {
+ executeOptimisticMutation,
prependUnique,
remove,
removeEmbeddedLink,
@@ -147,3 +150,27 @@ describe('typed optimistic graph updates', () => {
expect(typeAssertions).toBeTypeOf('function');
});
});
+
+describe('executeOptimisticMutation UUID validation', () => {
+ const client = {} as Client;
+ const document = {} as TypedDocumentNode<unknown, Record<string, never>>;
+
+ it('rejects an invalid caller UUID before invoking the client', () => {
+ expect(() =>
+ executeOptimisticMutation(client, document, {}, {}, { uuid: 'invalid' })
+ ).toThrow(TypeError);
+ });
+
+ it('rejects missing options at runtime', () => {
+ expect(() =>
+ (
+ executeOptimisticMutation as unknown as (
+ client: Client,
+ document: TypedDocumentNode<unknown, Record<string, never>>,
+ variables: Record<string, never>,
+ data: unknown
+ ) => unknown
+ )(client, document, {}, {})
+ ).toThrow(TypeError);
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/exchange/optimistic.ts b/apps/web/src/lib/graphql-cache/exchange/optimistic.ts
index df623fef62..29185fb98e 100644
--- a/apps/web/src/lib/graphql-cache/exchange/optimistic.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/optimistic.ts
@@ -17,6 +17,7 @@ import {
stringifyDocument,
} from '@urql/core';
import type { DocumentNode } from 'graphql';
+import { validate as validateUuid } from 'uuid';
import type {
EmbeddedLinkPathSegment,
OptimisticLinkPatchWire,
@@ -108,12 +109,15 @@ export type QueryRevalidation = {
};
export type OptimisticMutationOptions = {
+ /** Required RFC UUID; reuse only when the newer intent safely replaces the older one. */
+ uuid: string;
updates?: readonly OptimisticUpdate[];
/** Relevant queries that cannot safely be updated still revalidate on success. */
revalidations?: readonly QueryRevalidation[];
};
export type OptimisticMutationContext<TData = unknown> = {
+ uuid: string;
optimisticResponse: TData;
linkPatches: OptimisticLinkPatchWire[];
revalidations: QueryRevalidationWire[];
@@ -129,6 +133,11 @@ export type OptimisticMutationDisposition<TData> =
export type OptimisticMutationDispositionMetadata =
| { kind: 'committed'; transactionId?: string }
| { kind: 'queued'; transactionId: string }
+ | {
+ kind: 'superseded';
+ transactionId: string;
+ replacementTransactionId: string;
+ }
| { kind: 'permanently-failed'; transactionId?: string };
/** Returns a copy of an operation result carrying its queue disposition. */
@@ -150,7 +159,14 @@ export function withOptimisticMutationDisposition(
// that would roll back UI state or block the next edit.
error: undefined,
}
- : {}),
+ : disposition.kind === 'superseded'
+ ? {
+ // The replacement's optimistic payload is already visible in the
+ // cache. Never expose this older operation's stale response.
+ data: undefined,
+ error: undefined,
+ }
+ : {}),
extensions: {
...result.extensions,
[OPTIMISTIC_MUTATION_DISPOSITION_KEY]: disposition,
@@ -175,6 +191,12 @@ export function optimisticMutationDispositionOf<
if (metadata.kind === 'queued' && metadata.transactionId) {
return { kind: 'queued', transactionId: metadata.transactionId };
}
+ if (metadata.kind === 'superseded' && metadata.replacementTransactionId) {
+ return {
+ kind: 'queued',
+ transactionId: metadata.replacementTransactionId,
+ };
+ }
if (metadata.kind === 'committed' && result.data != null) {
return { kind: 'committed', data: result.data };
}
@@ -371,9 +393,13 @@ export function executeOptimisticMutation<
document: TypedDocumentNode<TData, TVariables>,
variables: TVariables,
optimisticData: TData,
- options: OptimisticMutationOptions = {}
+ options: OptimisticMutationOptions
): OperationResultSource<OperationResult<TData, TVariables>> {
+ if (!validateUuid(options.uuid)) {
+ throw new TypeError(`invalid optimistic mutation UUID: ${options.uuid}`);
+ }
const context: OptimisticMutationContext<TData> = {
+ uuid: options.uuid,
optimisticResponse: optimisticData,
linkPatches: [...(options.updates ?? [])],
revalidations: (options.revalidations ?? []).map(serializeRevalidation),
@@ -396,7 +422,13 @@ export function optimisticContextOf(
const context = value as Partial<OptimisticMutationContext> & {
optimisticResponse: unknown;
};
+ if (typeof context.uuid !== 'string' || !validateUuid(context.uuid)) {
+ throw new TypeError(
+ 'invalid optimistic mutation UUID in operation context'
+ );
+ }
return {
+ uuid: context.uuid,
optimisticResponse: context.optimisticResponse,
linkPatches: Array.isArray(context.linkPatches)
? context.linkPatches
diff --git a/apps/web/src/lib/graphql-cache/host/noop-host.ts b/apps/web/src/lib/graphql-cache/host/noop-host.ts
index cbaa58d312..48c0e1c86e 100644
--- a/apps/web/src/lib/graphql-cache/host/noop-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/noop-host.ts
@@ -1,4 +1,5 @@
import type {
+ CommitOptimisticWriteResult,
EnqueueOptimisticMutationResult,
ReadResult,
WriteResult,
@@ -57,12 +58,14 @@ export function createNoopCacheHost(reason: string): CacheHost {
async claimNextMutation() {
return undefined;
},
- async deferOptimisticWrite(): Promise<void> {},
- async commitOptimisticWrite(): Promise<WriteResult> {
- return emptyWriteResult();
+ async deferOptimisticWrite() {
+ return { kind: 'deferred' } as const;
},
- async rollbackOptimisticWrite(): Promise<WriteResult> {
- return emptyWriteResult();
+ async commitOptimisticWrite(): Promise<CommitOptimisticWriteResult> {
+ return { kind: 'committed', ...emptyWriteResult() };
+ },
+ async rollbackOptimisticWrite() {
+ return { kind: 'rolled-back' as const, ...emptyWriteResult() };
},
async invalidate() {
return { revision: INITIAL_CACHE_REVISION, affectedOps: [] };
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 91047c5821..e631621455 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
@@ -217,18 +217,24 @@ describe('createTauriCacheHost', () => {
changed: ['A:1'],
affectedOps: [],
reset: false,
+ upsertKind: { kind: 'inserted' as const },
initialClaim: { kind: 'not-runnable' as const },
};
invokeMock.mockImplementation((command: string) => {
if (command === 'graphql_cache_enqueue_optimistic_mutation') {
return Promise.resolve(optimistic);
}
- if (
- command === 'graphql_cache_commit_optimistic_write' ||
- command === 'graphql_cache_rollback_optimistic_write'
- ) {
+ if (command === 'graphql_cache_commit_optimistic_write') {
return Promise.resolve({ changed: [], affectedOps: [], reset: false });
}
+ if (command === 'graphql_cache_rollback_optimistic_write') {
+ return Promise.resolve({
+ kind: 'rolled-back',
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ });
+ }
return Promise.resolve(null);
});
@@ -245,6 +251,7 @@ describe('createTauriCacheHost', () => {
};
const begun = await host.enqueueOptimisticMutation(
{
+ uuid: '00000000-0000-4000-8000-000000000004',
query: 'mutation { m }',
data: { m: 1 },
linkPatches: [patch],
@@ -259,6 +266,7 @@ describe('createTauriCacheHost', () => {
expect(invokeMock).toHaveBeenCalledWith(
'graphql_cache_enqueue_optimistic_mutation',
expect.objectContaining({
+ uuid: '00000000-0000-4000-8000-000000000004',
linkPatches: [patch],
createdAtMs: 123,
owner: 'runner',
@@ -446,7 +454,11 @@ describe('createTauriCacheHost', () => {
let settled = false;
void host
.enqueueOptimisticMutation(
- { query: 'mutation Rename { rename { id } }', data: {} },
+ {
+ uuid: '00000000-0000-4000-8000-000000000101',
+ query: 'mutation Rename { rename { id } }',
+ data: {},
+ },
{ owner: 'runner', nowMs: 10, leaseExpiresAtMs: 1_010 }
)
.then(
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 877b5e5e28..ea4a05fc12 100644
--- a/apps/web/src/lib/graphql-cache/host/tauri-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.ts
@@ -15,6 +15,8 @@ import type {
CachedQueryVariantWire,
CacheRevision,
ClaimedMutation,
+ CommitOptimisticWriteResult,
+ DeferOptimisticWriteResult,
EnqueueOptimisticMutationResult,
HydrationResult,
MutationClaim,
@@ -22,6 +24,7 @@ import type {
ReadRecordsByKeysArgs,
ReadRecordsByKeysResult,
ReadResult,
+ RollbackOptimisticWriteResult,
SearchCacheArgs,
SearchCachePage,
WriteResult,
@@ -247,6 +250,7 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
'graphql_cache_enqueue_optimistic_mutation',
{
originOpId: args.opKey === undefined ? undefined : opId(args.opKey),
+ uuid: args.uuid,
query: args.query,
operationName: args.operationName,
variables: args.variables,
@@ -308,24 +312,27 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
claim: MutationClaim,
nextAttemptAtMs: number,
error: string
- ): Promise<void> {
+ ): Promise<DeferOptimisticWriteResult> {
await ready;
- await request('graphql_cache_defer_optimistic_write', {
- transactionId,
- leaseOwner: claim.owner,
- leaseGeneration: claim.generation,
- nextAttemptAtMs,
- error,
- });
+ return await request<DeferOptimisticWriteResult>(
+ 'graphql_cache_defer_optimistic_write',
+ {
+ transactionId,
+ leaseOwner: claim.owner,
+ leaseGeneration: claim.generation,
+ nextAttemptAtMs,
+ error,
+ }
+ );
},
async commitOptimisticWrite(
transactionId: string,
claim: MutationClaim,
args: CacheWriteArgs
- ): Promise<WriteResult> {
+ ): Promise<CommitOptimisticWriteResult> {
await ready;
- return await request<WriteResult>(
+ return await request<CommitOptimisticWriteResult>(
'graphql_cache_commit_optimistic_write',
{
transactionId,
@@ -343,9 +350,9 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
transactionId: string,
claim: MutationClaim,
error: string
- ): Promise<WriteResult> {
+ ): Promise<RollbackOptimisticWriteResult> {
await ready;
- return await request<WriteResult>(
+ return await request<RollbackOptimisticWriteResult>(
'graphql_cache_rollback_optimistic_write',
{
transactionId,
diff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.ts
index 2ab919cd11..3e5e79a3db 100644
--- a/apps/web/src/lib/graphql-cache/host/types.ts
+++ b/apps/web/src/lib/graphql-cache/host/types.ts
@@ -14,6 +14,8 @@ import type {
CacheReadPriority,
CacheRevision,
ClaimedMutation,
+ CommitOptimisticWriteResult,
+ DeferOptimisticWriteResult,
EnqueueOptimisticMutationResult,
EntityFilterCacheArgs,
EntityFilterCacheResult,
@@ -26,6 +28,7 @@ import type {
ReadRecordsByKeysArgs,
ReadRecordsByKeysResult,
ReadResult,
+ RollbackOptimisticWriteResult,
SearchCacheArgs,
SearchCachePage,
WriteResult,
@@ -67,6 +70,8 @@ export interface CacheWriteArgs extends Omit<CacheReadArgs, 'priority'> {
}
export interface EnqueueOptimisticMutationArgs extends CacheWriteArgs {
+ /** Caller-supplied RFC UUID used for explicit safe coalescing. */
+ uuid: string;
linkPatches?: OptimisticLinkPatchWire[];
/** Revalidations for relevant cached fields that could not be patched. */
revalidations?: QueryRevalidationWire[];
@@ -122,19 +127,19 @@ export interface CacheHost {
claim: MutationClaim,
nextAttemptAtMs: number,
error: string
- ): Promise<void>;
+ ): Promise<DeferOptimisticWriteResult>;
/** Atomically commits a claimed mutation's real network response. */
commitOptimisticWrite(
transactionId: string,
claim: MutationClaim,
args: CacheWriteArgs
- ): Promise<WriteResult>;
+ ): Promise<CommitOptimisticWriteResult>;
/** Permanently fails a claimed mutation and drops its optimistic layer. */
rollbackOptimisticWrite(
transactionId: string,
claim: MutationClaim,
error: string
- ): Promise<WriteResult>;
+ ): Promise<RollbackOptimisticWriteResult>;
/** Evict records by entity key (external/push updates); returns affected local op ids. */
invalidate(keys: string[]): Promise<AffectedOperationsResult>;
/** Apply explicit server-provided cache-deletion effects. */
@@ -157,7 +162,7 @@ export interface CacheHost {
/** Invalidates revision watermarks before a replacement engine is used. */
onCacheGenerationChanged(cb: () => void): () => void;
- /** Subscribes to final commit/rollback events for queued mutations. */
+ /** Subscribes to final commit, rollback, or supersession events. */
onMutationSettled(cb: (settlement: MutationSettlement) => void): () => void;
dispose(): void;
diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts b/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts
index 5ec9ee9756..efab6bed68 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts
@@ -62,6 +62,7 @@ function optimisticMutation(key: number, query: Operation['query']): Operation {
url: 'http://integration.test',
suspense: false,
normalizedCacheOptimistic: {
+ uuid: '00000000-0000-4000-8000-000000000001',
optimisticResponse: { held: true },
},
} as never);
@@ -169,6 +170,7 @@ class IntegrationCore {
changed: [],
affectedOps: [],
reset: false,
+ upsertKind: { kind: 'inserted' },
initialClaim: { kind: 'not-runnable' },
};
}
diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts
index 2a90cb5c0a..c7e3dee1d5 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts
@@ -398,6 +398,7 @@ describe('createWorkerCacheHost', () => {
}),
host.enqueueOptimisticMutation(
{
+ uuid: '00000000-0000-4000-8000-000000000005',
opKey: 9,
query: 'mutation Rename { rename { id } }',
data: { rename: { id: 'doc-1' } },
@@ -474,6 +475,11 @@ describe('createWorkerCacheHost', () => {
nowMs: 123,
},
});
+ expect(requests[5]).toEqual(
+ expect.objectContaining({
+ uuid: '00000000-0000-4000-8000-000000000005',
+ })
+ );
expect(requests[4]).toEqual(
expect.objectContaining({
originOpId: `${CLIENT_ID}:8`,
@@ -521,7 +527,11 @@ describe('createWorkerCacheHost', () => {
const read = host.readQuery({ opKey: 4, query: 'query Read { user }' });
const mutation = host.enqueueOptimisticMutation(
- { query: 'mutation Update { update }', data: { update: true } },
+ {
+ uuid: '00000000-0000-4000-8000-000000000100',
+ query: 'mutation Update { update }',
+ data: { update: true },
+ },
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
const readRejected = expect(read).rejects.toThrow(
@@ -578,7 +588,11 @@ describe('createWorkerCacheHost', () => {
const read = host.readQuery({ opKey: 44, query: 'query Read { user }' });
const mutation = host.enqueueOptimisticMutation(
- { query: 'mutation Update { update }', data: { update: true } },
+ {
+ uuid: '00000000-0000-4000-8000-000000000100',
+ query: 'mutation Update { update }',
+ data: { update: true },
+ },
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
const readRejected = expect(read).rejects.toMatchObject({
@@ -662,6 +676,7 @@ describe('createWorkerCacheHost', () => {
const read = host.readQuery({ query: 'query Read { user { id } }' });
const mutation = host.enqueueOptimisticMutation(
{
+ uuid: '00000000-0000-4000-8000-000000000006',
query: 'mutation Rename { rename { id } }',
data: { rename: { id: 'doc-1' } },
},
@@ -721,7 +736,11 @@ describe('createWorkerCacheHost', () => {
const read = host.readQuery({ opKey: 44, query: 'query Read { user }' });
const mutation = host.enqueueOptimisticMutation(
- { query: 'mutation Update { update }', data: { update: true } },
+ {
+ uuid: '00000000-0000-4000-8000-000000000100',
+ query: 'mutation Update { update }',
+ data: { update: true },
+ },
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
const readRejected = expect(read).rejects.toThrow('owner epoch 1 was lost');
@@ -959,7 +978,11 @@ describe('createWorkerCacheHost', () => {
await host.clear();
const adapter = requireAdapter();
const mutation = host.enqueueOptimisticMutation(
- { query: 'mutation Update { update }', data: { update: true } },
+ {
+ uuid: '00000000-0000-4000-8000-000000000100',
+ query: 'mutation Update { update }',
+ data: { update: true },
+ },
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
const mutationRejected = expect(mutation).rejects.toMatchObject({
@@ -1138,7 +1161,11 @@ describe('createWorkerCacheHost', () => {
});
adapter.dispose.mockImplementationOnce(async () => await draining);
const mutation = host.enqueueOptimisticMutation(
- { query: 'mutation Update { update }', data: { update: true } },
+ {
+ uuid: '00000000-0000-4000-8000-000000000100',
+ query: 'mutation Update { update }',
+ data: { update: true },
+ },
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
await vi.waitFor(() =>
@@ -1275,7 +1302,11 @@ describe('createWorkerCacheHost', () => {
});
adapter.dispose.mockImplementationOnce(async () => await draining);
const mutation = host.enqueueOptimisticMutation(
- { query: 'mutation Update { update }', data: { update: true } },
+ {
+ uuid: '00000000-0000-4000-8000-000000000100',
+ query: 'mutation Update { update }',
+ data: { update: true },
+ },
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
await vi.waitFor(() =>
@@ -1309,7 +1340,11 @@ describe('createWorkerCacheHost', () => {
await host.clear();
const adapter = requireAdapter();
const mutation = host.enqueueOptimisticMutation(
- { query: 'mutation Update { update }', data: { update: true } },
+ {
+ uuid: '00000000-0000-4000-8000-000000000100',
+ query: 'mutation Update { update }',
+ data: { update: true },
+ },
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
const rejected = expect(mutation).rejects.toMatchObject({
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 9f10c32cb2..0053a1a098 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts
@@ -14,6 +14,8 @@ import {
type CacheResponseErrorCode,
type CacheRevision,
type ClaimedMutation,
+ type CommitOptimisticWriteResult,
+ type DeferOptimisticWriteResult,
type EnqueueOptimisticMutationResult,
type EntityFilterCacheArgs,
type EntityFilterCacheResult,
@@ -26,6 +28,7 @@ import {
type ReadRecordsByKeysArgs,
type ReadRecordsByKeysResult,
type ReadResult,
+ type RollbackOptimisticWriteResult,
type SearchCacheArgs,
type SearchCachePage,
validateCacheSearchArgs,
@@ -916,6 +919,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
return (await request({
kind: 'enqueue-optimistic-mutation',
originOpId: args.opKey === undefined ? undefined : opId(args.opKey),
+ uuid: args.uuid,
query: args.query,
operationName: args.operationName,
variables: args.variables,
@@ -973,23 +977,23 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
claim: MutationClaim,
nextAttemptAtMs: number,
error: string
- ): Promise<void> {
+ ) {
await ensureInitialized();
- await request({
+ return (await request({
kind: 'defer-optimistic-write',
transactionId,
leaseOwner: claim.owner,
leaseGeneration: claim.generation,
nextAttemptAtMs,
error,
- });
+ })) as DeferOptimisticWriteResult;
},
async commitOptimisticWrite(
transactionId: string,
claim: MutationClaim,
args: CacheWriteArgs
- ): Promise<WriteResult> {
+ ): Promise<CommitOptimisticWriteResult> {
await ensureInitialized();
return (await request({
kind: 'commit-optimistic-write',
@@ -1000,14 +1004,14 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
operationName: args.operationName,
variables: args.variables,
data: args.data,
- })) as WriteResult;
+ })) as CommitOptimisticWriteResult;
},
async rollbackOptimisticWrite(
transactionId: string,
claim: MutationClaim,
error: string
- ): Promise<WriteResult> {
+ ): Promise<RollbackOptimisticWriteResult> {
await ensureInitialized();
return (await request({
kind: 'rollback-optimistic-write',
@@ -1015,7 +1019,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
leaseOwner: claim.owner,
leaseGeneration: claim.generation,
error,
- })) as WriteResult;
+ })) as RollbackOptimisticWriteResult;
},
async invalidate(keys: string[]): Promise<AffectedOperationsResult> {
diff --git a/apps/web/src/lib/graphql-cache/protocol.test.ts b/apps/web/src/lib/graphql-cache/protocol.test.ts
index cbcf668c43..afbcb39ad5 100644
--- a/apps/web/src/lib/graphql-cache/protocol.test.ts
+++ b/apps/web/src/lib/graphql-cache/protocol.test.ts
@@ -153,6 +153,14 @@ describe('cache worker message validators', () => {
kind: 'mutation-settled',
settlement: {
transactionId: '4',
+ status: 'superseded',
+ replacementTransactionId: '5',
+ },
+ },
+ {
+ kind: 'mutation-settled',
+ settlement: {
+ transactionId: '6',
status: 'permanently-failed',
error: 'denied',
},
@@ -184,6 +192,10 @@ describe('cache worker message validators', () => {
kind: 'mutation-settled',
settlement: { transactionId: '4', status: 'permanently-failed' },
},
+ {
+ kind: 'mutation-settled',
+ settlement: { transactionId: '5', status: 'superseded' },
+ },
])('rejects malformed or extended worker message %#', (value) => {
expect(isWorkerMessage(value)).toBe(false);
});
diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.ts
index 3616898fe0..9b88dde21f 100644
--- a/apps/web/src/lib/graphql-cache/protocol.ts
+++ b/apps/web/src/lib/graphql-cache/protocol.ts
@@ -329,9 +329,17 @@ export type OptimisticWriteResult = WriteResult & {
transactionId: string;
};
+/** How a caller UUID changed the durable queue. */
+export type MutationUpsertKind =
+ | { kind: 'inserted' }
+ | { kind: 'replaced-pending'; removedTransactionId: string }
+ | { kind: 'appended-after-active'; activeTransactionId: string };
+
/** Claimed strict queue head, ready to be forwarded through urql. */
export type ClaimedMutation = {
transactionId: string;
+ uuid: string;
+ superseded: boolean;
leaseGeneration: string;
query: string;
operationName?: string;
@@ -349,6 +357,7 @@ export type InitialMutationClaim =
/** Result returned after enqueue and the initial claim attempt complete. */
export type EnqueueOptimisticMutationResult = OptimisticWriteResult & {
+ upsertKind: MutationUpsertKind;
initialClaim: InitialMutationClaim;
};
@@ -358,9 +367,38 @@ export type MutationClaim = {
generation: string;
};
+/** Result of deferring a retryable attempt. */
+export type DeferOptimisticWriteResult =
+ | { kind: 'deferred' }
+ | (WriteResult & {
+ kind: 'discarded-superseded';
+ replacementTransactionId: string;
+ });
+
+/** Result of committing a current or superseded attempt. */
+export type CommitOptimisticWriteResult =
+ | (WriteResult & { kind: 'committed' })
+ | (WriteResult & {
+ kind: 'committed-superseded';
+ replacementTransactionId: string;
+ });
+
+/** Result of rolling back a failed attempt. */
+export type RollbackOptimisticWriteResult =
+ | (WriteResult & { kind: 'rolled-back' })
+ | (WriteResult & {
+ kind: 'discarded-superseded';
+ replacementTransactionId: string;
+ });
+
/** Final settlement of a previously queued optimistic mutation. */
export type MutationSettlement =
| { transactionId: string; status: 'committed' }
+ | {
+ transactionId: string;
+ status: 'superseded';
+ replacementTransactionId: string;
+ }
| {
transactionId: string;
status: 'permanently-failed';
@@ -411,6 +449,7 @@ export type CacheRequest = { id: number } & (
| {
kind: 'enqueue-optimistic-mutation';
originOpId?: string;
+ uuid: string;
query: string;
operationName?: string;
variables?: Record<string, unknown>;
@@ -618,6 +657,15 @@ export function isCachePush(value: unknown): value is CachePush {
if (settlement.status === 'committed') {
return hasOnlyWireKeys(settlement, ['transactionId', 'status']);
}
+ if (settlement.status === 'superseded') {
+ return (
+ hasOnlyWireKeys(settlement, [
+ 'transactionId',
+ 'status',
+ 'replacementTransactionId',
+ ]) && typeof settlement.replacementTransactionId === 'string'
+ );
+ }
return (
settlement.status === 'permanently-failed' &&
hasOnlyWireKeys(settlement, ['transactionId', 'status', 'error']) &&
diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery-harness.ts
index a954dc7a78..fd37d89163 100644
--- a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery-harness.ts
+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery-harness.ts
@@ -238,6 +238,7 @@ const enqueueRequest = (
createdAtMs: number
): ProductionCacheRequestWithoutId => ({
kind: 'enqueue-optimistic-mutation',
+ uuid: '00000000-0000-4000-8000-000000000011',
query: MUTATION,
operationName: 'SetEntityProperty',
variables: MUTATION_VARIABLES,
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts
index 54ef7cec71..b26eec73ca 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts
@@ -57,6 +57,19 @@ describe('coordinator runtime protocol', () => {
data: { user: { id: 'user-1' } },
})
).toBe(false);
+ const enqueue = {
+ id: 2,
+ kind: 'enqueue-optimistic-mutation',
+ uuid: '00000000-0000-4000-8000-000000000001',
+ query: 'mutation Update { update }',
+ data: { update: true },
+ createdAtMs: 1,
+ owner: 'runner',
+ nowMs: 1,
+ leaseExpiresAtMs: 1_001,
+ };
+ expect(isCacheRequest(enqueue)).toBe(true);
+ expect(isCacheRequest({ ...enqueue, uuid: undefined })).toBe(false);
expect(
isCacheRequest({
id: 2,
diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
index 2e1c2c8b37..38339fcf84 100644
--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts
@@ -430,6 +430,7 @@ export function isCacheRequest(value: unknown): value is CacheRequest {
'id',
'kind',
'originOpId',
+ 'uuid',
'query',
'operationName',
'variables',
@@ -442,6 +443,7 @@ export function isCacheRequest(value: unknown): value is CacheRequest {
'leaseExpiresAtMs',
]) &&
isOptionalString(value.originOpId) &&
+ isString(value.uuid) &&
isString(value.query) &&
isOptionalString(value.operationName) &&
isOptionalRecord(value.variables) &&
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 73ceecb80a..7f52b0886d 100644
--- a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
+++ b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
@@ -16,6 +16,8 @@ import type {
CacheRevision,
CacheRevisionResult,
ClaimedMutation,
+ CommitOptimisticWriteResult,
+ DeferOptimisticWriteResult,
EnqueueOptimisticMutationResult,
EntityFilterCacheArgs,
EntityFilterCacheResult,
@@ -23,6 +25,7 @@ import type {
QueryRevalidationWire,
ReadRecordsByKeysResult,
ReadResult,
+ RollbackOptimisticWriteResult,
SearchCacheArgs,
SearchCachePage,
WriteResult,
@@ -110,6 +113,7 @@ export interface CacheEngine {
): Promise<CacheEngineHydrationResult>;
enqueueOptimisticMutation(
originOpId: string | undefined,
+ uuid: string,
query: string,
operationName: string | undefined,
variables: Record<string, unknown> | undefined,
@@ -143,7 +147,7 @@ export interface CacheEngine {
leaseGeneration: string,
nextAttemptAtMs: number,
error: string
- ): Promise<void>;
+ ): Promise<DeferOptimisticWriteResult>;
commitOptimisticWrite(
transactionId: string,
leaseOwner: string,
@@ -152,12 +156,12 @@ export interface CacheEngine {
operationName: string | undefined,
variables: Record<string, unknown> | undefined,
data: unknown
- ): Promise<WriteResult>;
+ ): Promise<CommitOptimisticWriteResult>;
rollbackOptimisticWrite(
transactionId: string,
leaseOwner: string,
leaseGeneration: string
- ): Promise<WriteResult>;
+ ): Promise<RollbackOptimisticWriteResult>;
invalidateKeys(keys: string[]): Promise<AffectedOperationsResult>;
deleteKeys(keys: string[]): Promise<AffectedOperationsResult>;
teardownOperation(opId: string): Promise<void>;
diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
index 97d41364f0..7066345db6 100644
--- a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
@@ -100,6 +100,50 @@ describe('CacheWorkerCore', () => {
expect(messages.at(-1)).toEqual({ id: 2, ok: true, result: page });
});
+ it('reports a successful stale commit as superseded', async () => {
+ const commitOptimisticWrite = vi.fn().mockResolvedValue({
+ kind: 'committed-superseded',
+ replacementTransactionId: '2',
+ revision: INITIAL_CACHE_REVISION,
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ revalidations: [],
+ });
+ loadCacheWasmMock.mockResolvedValue({
+ openCache: vi.fn().mockResolvedValue({ commitOptimisticWrite }),
+ });
+ const messages: unknown[] = [];
+ const port = { postMessage: (message: unknown) => messages.push(message) };
+ const core = new CacheWorkerCore();
+ core.addPort(port);
+ await core.handleRequest(port, {
+ id: 1,
+ kind: 'init',
+ scope: 'scope-1',
+ });
+ messages.length = 0;
+
+ await core.handleRequest(port, {
+ id: 2,
+ kind: 'commit-optimistic-write',
+ transactionId: '1',
+ leaseOwner: 'runner',
+ leaseGeneration: '1',
+ query: 'mutation Update { update }',
+ data: { update: true },
+ });
+
+ expect(messages).toContainEqual({
+ kind: 'mutation-settled',
+ settlement: {
+ transactionId: '1',
+ status: 'superseded',
+ replacementTransactionId: '2',
+ },
+ });
+ });
+
it('finishes the initial claim before pushes or queued reads run', async () => {
const order: string[] = [];
let resolveEnqueue!: (result: {
@@ -108,6 +152,10 @@ describe('CacheWorkerCore', () => {
changed: string[];
affectedOps: string[];
reset: false;
+ upsertKind: {
+ kind: 'replaced-pending';
+ removedTransactionId: string;
+ };
initialClaim: { kind: 'not-runnable' };
}) => void;
const enqueueOptimisticMutation = vi.fn(() => {
@@ -118,6 +166,10 @@ describe('CacheWorkerCore', () => {
changed: string[];
affectedOps: string[];
reset: false;
+ upsertKind: {
+ kind: 'replaced-pending';
+ removedTransactionId: string;
+ };
initialClaim: { kind: 'not-runnable' };
}>((resolve) => {
resolveEnqueue = (result) => {
@@ -150,6 +202,7 @@ describe('CacheWorkerCore', () => {
const enqueue = core.handleRequest(port, {
id: 2,
kind: 'enqueue-optimistic-mutation',
+ uuid: '00000000-0000-4000-8000-000000000007',
query: 'mutation Update { update }',
data: { update: true },
createdAtMs: 10,
@@ -180,6 +233,10 @@ describe('CacheWorkerCore', () => {
changed: ['Thing:1'],
affectedOps: ['client:query'],
reset: false,
+ upsertKind: {
+ kind: 'replaced-pending',
+ removedTransactionId: '0',
+ },
initialClaim: { kind: 'not-runnable' },
});
await Promise.all([enqueue, read]);
@@ -190,6 +247,14 @@ describe('CacheWorkerCore', () => {
opIds: ['client:query'],
keys: ['Thing:1'],
});
+ expect(messages).toContainEqual({
+ kind: 'mutation-settled',
+ settlement: {
+ transactionId: '0',
+ status: 'superseded',
+ replacementTransactionId: '1',
+ },
+ });
});
it('runs standalone claims ahead of queued observational reads', async () => {
@@ -431,7 +496,7 @@ describe('CacheWorkerCore', () => {
return { kind: 'hit' as const, data: { opId } };
});
const enqueueOptimisticMutation = vi.fn(
- async (_originOpId: string | undefined, query: string) => {
+ async (_originOpId: string | undefined, _uuid: string, query: string) => {
order.push(`enqueue:${query}`);
return {
transactionId: query,
@@ -439,6 +504,7 @@ describe('CacheWorkerCore', () => {
changed: [],
affectedOps: [],
reset: false,
+ upsertKind: { kind: 'inserted' as const },
initialClaim: { kind: 'not-runnable' as const },
};
}
@@ -481,6 +547,7 @@ describe('CacheWorkerCore', () => {
const firstEnqueue = core.handleRequest(port, {
id: 5,
kind: 'enqueue-optimistic-mutation',
+ uuid: '00000000-0000-4000-8000-000000000008',
query: 'mutation First { first }',
data: { first: true },
createdAtMs: 1,
@@ -491,6 +558,7 @@ describe('CacheWorkerCore', () => {
const secondEnqueue = core.handleRequest(port, {
id: 6,
kind: 'enqueue-optimistic-mutation',
+ uuid: '00000000-0000-4000-8000-000000000009',
query: 'mutation Second { second }',
data: { second: true },
createdAtMs: 2,
@@ -661,6 +729,7 @@ describe('CacheWorkerCore', () => {
changed: [],
affectedOps: [],
reset: false,
+ upsertKind: { kind: 'inserted' as const },
initialClaim: { kind: 'not-runnable' as const },
};
});
@@ -700,6 +769,7 @@ describe('CacheWorkerCore', () => {
const enqueue = core.handleRequest(port, {
id: 5,
kind: 'enqueue-optimistic-mutation',
+ uuid: '00000000-0000-4000-8000-000000000010',
query: 'mutation Update { update }',
data: { update: true },
createdAtMs: 1,
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 4ff0f6ba3f..b3f9ebaf49 100644
--- a/apps/web/src/lib/graphql-cache/worker/worker-core.ts
+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.ts
@@ -502,6 +502,7 @@ export class CacheWorkerCore {
const result: EnqueueOptimisticMutationResult =
await engine.enqueueOptimisticMutation(
request.originOpId,
+ request.uuid,
request.query,
request.operationName,
request.variables,
@@ -515,6 +516,16 @@ export class CacheWorkerCore {
);
result.revision = parseCacheRevision(result.revision);
this.fanOut(result, true);
+ if (result.upsertKind.kind === 'replaced-pending') {
+ this.push({
+ kind: 'mutation-settled',
+ settlement: {
+ transactionId: result.upsertKind.removedTransactionId,
+ status: 'superseded',
+ replacementTransactionId: result.transactionId,
+ },
+ });
+ }
return result;
})
.with({ kind: 'inspect-query-variants' }, async (request) => {
@@ -542,14 +553,26 @@ export class CacheWorkerCore {
})
.with({ kind: 'defer-optimistic-write' }, async (request) => {
const engine = this.requireEngine();
- await engine.deferOptimisticWrite(
+ const result = await engine.deferOptimisticWrite(
request.transactionId,
request.leaseOwner,
request.leaseGeneration,
request.nextAttemptAtMs,
request.error
);
- return null;
+ if (result.kind === 'discarded-superseded') {
+ result.revision = parseCacheRevision(result.revision);
+ this.fanOut(result, true);
+ this.push({
+ kind: 'mutation-settled',
+ settlement: {
+ transactionId: request.transactionId,
+ status: 'superseded',
+ replacementTransactionId: result.replacementTransactionId,
+ },
+ });
+ }
+ return result;
})
.with({ kind: 'commit-optimistic-write' }, async (request) => {
const engine = this.requireEngine();
@@ -567,10 +590,17 @@ export class CacheWorkerCore {
this.fanOut(result, true);
this.push({
kind: 'mutation-settled',
- settlement: {
- transactionId: request.transactionId,
- status: 'committed',
- },
+ settlement:
+ result.kind === 'committed-superseded'
+ ? {
+ transactionId: request.transactionId,
+ status: 'superseded',
+ replacementTransactionId: result.replacementTransactionId,
+ }
+ : {
+ transactionId: request.transactionId,
+ status: 'committed',
+ },
});
return result;
})
@@ -585,11 +615,18 @@ export class CacheWorkerCore {
this.fanOut(result, true);
this.push({
kind: 'mutation-settled',
- settlement: {
- transactionId: request.transactionId,
- status: 'permanently-failed',
- error: request.error,
- },
+ settlement:
+ result.kind === 'discarded-superseded'
+ ? {
+ transactionId: request.transactionId,
+ status: 'superseded',
+ replacementTransactionId: result.replacementTransactionId,
+ }
+ : {
+ transactionId: request.transactionId,
+ status: 'permanently-failed',
+ error: request.error,
+ },
});
return result;
})
diff --git a/apps/web/src/lib/queries/properties/graphql/entity-options.test.ts b/apps/web/src/lib/queries/properties/graphql/entity-options.test.ts
index d0ced0bb75..e914eb0ac3 100644
--- a/apps/web/src/lib/queries/properties/graphql/entity-options.test.ts
+++ b/apps/web/src/lib/queries/properties/graphql/entity-options.test.ts
@@ -1,4 +1,5 @@
import type { Property, PropertyDefinitionDomain } from '@property/types';
+import { validate as validateUuid } from 'uuid';
import { beforeEach, describe, expect, it, vi } from 'vitest';
const executeOptimisticMutationMock = vi.hoisted(() => vi.fn());
@@ -126,9 +127,33 @@ describe('updateGraphqlEntityPropertyOptions', () => {
]);
// The record already exists, so the entity's property link list is intact.
expect(options.revalidations).toEqual([]);
+ expect(validateUuid(options.uuid)).toBe(true);
expect(inspectMock).not.toHaveBeenCalled();
});
+ it('uses a fresh UUID for each non-coalescible delta batch', async () => {
+ const input = {
+ entityType: 'DOCUMENT' as const,
+ entityId: 'doc-1',
+ properties: [
+ {
+ property: tagProperty,
+ currentOptionIds: ['stale'],
+ nextOptionIds: ['spotlight'],
+ },
+ ],
+ };
+
+ await updateGraphqlEntityPropertyOptions(input);
+ await updateGraphqlEntityPropertyOptions(input);
+
+ const uuids = executeOptimisticMutationMock.mock.calls.map(
+ (call) => call[4].uuid
+ );
+ expect(uuids.every(validateUuid)).toBe(true);
+ expect(new Set(uuids).size).toBe(2);
+ });
+
it('revalidates only the cached queries holding the entity when it has no record for the definition', async () => {
inspectMock
.mockResolvedValueOnce([
diff --git a/apps/web/src/lib/queries/properties/graphql/entity-options.ts b/apps/web/src/lib/queries/properties/graphql/entity-options.ts
index 3d81977e66..61ce596209 100644
--- a/apps/web/src/lib/queries/properties/graphql/entity-options.ts
+++ b/apps/web/src/lib/queries/properties/graphql/entity-options.ts
@@ -154,7 +154,7 @@ export async function updateGraphqlEntityPropertyOptions(
UpdateEntityPropertyOptionsDocument,
variables,
{ updateEntityPropertyOptions: optimisticProperties },
- { revalidations }
+ { uuid: crypto.randomUUID(), revalidations }
).toPromise();
const disposition = optimisticMutationDispositionOf<
diff --git a/apps/web/src/lib/queries/properties/graphql/entity.test.ts b/apps/web/src/lib/queries/properties/graphql/entity.test.ts
index 71d0f68748..73b5b6eb20 100644
--- a/apps/web/src/lib/queries/properties/graphql/entity.test.ts
+++ b/apps/web/src/lib/queries/properties/graphql/entity.test.ts
@@ -9,6 +9,7 @@ import {
type OperationResult,
} from '@urql/core';
import { createRoot, createSignal } from 'solid-js';
+import { validate as validateUuid } from 'uuid';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { filter, makeSubject, mergeMap, pipe } from 'wonka';
@@ -31,6 +32,7 @@ import {
createGraphqlAddEntityPropertyMutation,
createGraphqlBulkSaveEntityPropertiesMutation,
createGraphqlEntityPropertiesQuery,
+ entityPropertyOptimisticMutationUuid,
mapGraphqlEntityProperties,
} from './entity';
@@ -172,6 +174,39 @@ describe('mapGraphqlEntityProperties', () => {
});
});
+describe('entityPropertyOptimisticMutationUuid', () => {
+ it('is stable per property slot and distinct across slots', () => {
+ const args = {
+ entityType: 'DOCUMENT' as const,
+ entityId: 'document-1',
+ propertyDefinitionId: 'property-1',
+ };
+ const uuid = entityPropertyOptimisticMutationUuid(args);
+
+ expect(validateUuid(uuid)).toBe(true);
+ expect(entityPropertyOptimisticMutationUuid(args)).toBe(uuid);
+ expect(
+ entityPropertyOptimisticMutationUuid({
+ ...args,
+ propertyDefinitionId: 'property-2',
+ })
+ ).not.toBe(uuid);
+ expect(
+ entityPropertyOptimisticMutationUuid({
+ ...args,
+ entityId: 'document-1:property',
+ propertyDefinitionId: '1',
+ })
+ ).not.toBe(
+ entityPropertyOptimisticMutationUuid({
+ ...args,
+ entityId: 'document-1',
+ propertyDefinitionId: 'property:1',
+ })
+ );
+ });
+});
+
describe('GraphQL entity property mutations', () => {
let dispose: (() => void) | undefined;
diff --git a/apps/web/src/lib/queries/properties/graphql/entity.ts b/apps/web/src/lib/queries/properties/graphql/entity.ts
index 88de495fbc..3821082cfa 100644
--- a/apps/web/src/lib/queries/properties/graphql/entity.ts
+++ b/apps/web/src/lib/queries/properties/graphql/entity.ts
@@ -39,6 +39,7 @@ import {
import { CombinedError, type OperationResult } from '@urql/core';
import { type Accessor, createMemo } from 'solid-js';
import { match } from 'ts-pattern';
+import { v5 as uuidv5 } from 'uuid';
import {
buildOptimisticGroupedPropertyUpdates,
groupedPropertyKeys,
@@ -335,6 +336,26 @@ function mutationDisposition(
return { kind: 'committed', property: result.data.setEntityProperty };
}
+const ENTITY_PROPERTY_OPTIMISTIC_UUID_NAMESPACE =
+ '1697e6bc-0d9a-4dd2-bc3f-bd33bcb6f607';
+
+/** Stable coalescing UUID for one absolute entity-property value slot. */
+export function entityPropertyOptimisticMutationUuid(args: {
+ entityType: GraphqlPropertyTargetEntityType;
+ entityId: string;
+ propertyDefinitionId: string;
+}): string {
+ return uuidv5(
+ JSON.stringify([
+ 'setEntityProperty',
+ args.entityType,
+ args.entityId,
+ args.propertyDefinitionId,
+ ]),
+ ENTITY_PROPERTY_OPTIMISTIC_UUID_NAMESPACE
+ );
+}
+
const executeGraphqlEntityPropertyMutation: UrqlMutationExecutor<
SetEntityPropertyMutation,
SetEntityPropertyMutationVariables,
@@ -356,7 +377,10 @@ const executeGraphqlEntityPropertyMutation: UrqlMutationExecutor<
mutation,
variables,
{ setEntityProperty: args.optimisticProperty },
- args.optimisticCache
+ {
+ ...args.optimisticCache,
+ uuid: entityPropertyOptimisticMutationUuid(args),
+ }
).toPromise()
: client.mutation(mutation, variables, context).toPromise());
const disposition = mutationDisposition(mutationResult);
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-activity-notifications.test.ts b/apps/web/src/lib/service-clients/service-storage/graphql-activity-notifications.test.ts
index f6461eb258..c7ea71eb5d 100644
--- a/apps/web/src/lib/service-clients/service-storage/graphql-activity-notifications.test.ts
+++ b/apps/web/src/lib/service-clients/service-storage/graphql-activity-notifications.test.ts
@@ -144,6 +144,7 @@ describe('channel activity and notification GraphQL cache separation', () => {
},
{
normalizedCacheOptimistic: {
+ uuid: expect.any(String),
optimisticResponse: {
updateNotifications: [
{
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-update-notifications.ts b/apps/web/src/lib/service-clients/service-storage/graphql-update-notifications.ts
index 3d46eb88c8..b6e2c35b3f 100644
--- a/apps/web/src/lib/service-clients/service-storage/graphql-update-notifications.ts
+++ b/apps/web/src/lib/service-clients/service-storage/graphql-update-notifications.ts
@@ -101,7 +101,8 @@ export async function executeGraphqlUpdateNotifications(
client,
UpdateNotificationsDocument,
variables,
- optimisticData
+ optimisticData,
+ { uuid: crypto.randomUUID() }
).toPromise();
// A retryable transport failure keeps the normalized optimistic layer in
diff --git a/apps/web/tauri/Cargo.lock b/apps/web/tauri/Cargo.lock
index f7dda666b5..3715440532 100644
--- a/apps/web/tauri/Cargo.lock
+++ b/apps/web/tauri/Cargo.lock
@@ -36,7 +36,7 @@ checksum = "b169f7a6d4742236a0a00c541b845991d0ac43e546831af1249753ab4c3aa3a0"
dependencies = [
"cfg-if",
"cipher",
- "cpufeatures",
+ "cpufeatures 0.2.17",
]
[[package]]
@@ -777,6 +777,7 @@ dependencies = [
"serde_json",
"sha2",
"thiserror 2.0.18",
+ "uuid",
]
[[package]]
@@ -789,6 +790,7 @@ dependencies = [
"thiserror 2.0.18",
"turso-opfs",
"turso_core",
+ "uuid",
]
[[package]]
@@ -915,6 +917,17 @@ version = "0.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "18758054972164c3264f7c8386f5fc6da6114cb46b619fd365d4e3b2dc3ae487"
+[[package]]
+name = "chacha20"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d524456ba66e72eb8b115ff89e01e497f8e6d11d78b70b1aa13c0fbd97540a81"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.3.0",
+ "rand_core 0.10.1",
+]
+
[[package]]
name = "chrono"
version = "0.4.44"
@@ -1138,6 +1151,15 @@ dependencies = [
"libc",
]
+[[package]]
+name = "cpufeatures"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b2a41393f66f16b0823bb79094d54ac5fbd34ab292ddafb9a0456ac9f87d201"
+dependencies = [
+ "libc",
+]
+
[[package]]
name = "crc"
version = "3.4.0"
@@ -2225,6 +2247,7 @@ dependencies = [
"js-sys",
"libc",
"r-efi 6.0.0",
+ "rand_core 0.10.1",
"wasip2",
"wasip3",
"wasm-bindgen",
@@ -4518,7 +4541,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9d1fe60d06143b2430aa532c94cfe9e29783047f06c0d7fd359a9a51b729fa25"
dependencies = [
"cfg-if",
- "cpufeatures",
+ "cpufeatures 0.2.17",
"opaque-debug",
"universal-hash",
]
@@ -4855,6 +4878,17 @@ dependencies = [
"rand_core 0.9.5",
]
+[[package]]
+name = "rand"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c7f5fa3a058cd35567ef9bfa5e75732bee0f9e4c55fa90477bef2dfcdbc4be80"
+dependencies = [
+ "chacha20",
+ "getrandom 0.4.2",
+ "rand_core 0.10.1",
+]
+
[[package]]
name = "rand_chacha"
version = "0.2.2"
@@ -4912,6 +4946,12 @@ dependencies = [
"getrandom 0.3.4",
]
+[[package]]
+name = "rand_core"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
+
[[package]]
name = "rand_hc"
version = "0.2.0"
@@ -5680,7 +5720,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba"
dependencies = [
"cfg-if",
- "cpufeatures",
+ "cpufeatures 0.2.17",
"digest",
]
@@ -5697,7 +5737,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
dependencies = [
"cfg-if",
- "cpufeatures",
+ "cpufeatures 0.2.17",
"digest",
]
@@ -7581,6 +7621,7 @@ checksum = "ddd74a9687298c6858e9b88ec8935ec45d22e8fd5e6394fa1bd4e99a87789c76"
dependencies = [
"getrandom 0.4.2",
"js-sys",
+ "rand 0.10.2",
"serde_core",
"sha1_smol",
"wasm-bindgen",
diff --git a/apps/web/tauri/graphql_cache_plugin/src/commands.rs b/apps/web/tauri/graphql_cache_plugin/src/commands.rs
index fb50f9ce94..95a8ada902 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/commands.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/commands.rs
@@ -10,9 +10,10 @@
//! worker's `{ok: false, error}` responses.
use crate::engine::{
- AffectedOperationsResultWire, ClaimedMutationWire, EngineHandle,
- EnqueueOptimisticMutationResultWire, ReadResultWire, RecordSelectionResultWire,
- WriteRegistration, WriteRequest, WriteResultWire,
+ AffectedOperationsResultWire, ClaimedMutationWire, CommitOptimisticWriteResultWire,
+ DeferOptimisticWriteResultWire, EngineHandle, EnqueueOptimisticMutationResultWire,
+ MutationUpsertKindWire, ReadResultWire, RecordSelectionResultWire,
+ RollbackOptimisticWriteResultWire, WriteRegistration, WriteRequest, WriteResultWire,
};
use crate::{
CacheState, InitializedCache, emit_cache_changed, emit_mutation_settled, emit_ops_affected,
@@ -236,6 +237,7 @@ pub async fn graphql_cache_enqueue_optimistic_mutation<R: Runtime>(
app: AppHandle<R>,
state: State<'_, CacheState>,
origin_op_id: Option<String>,
+ uuid: String,
query: String,
operation_name: Option<String>,
variables: Option<Variables>,
@@ -250,6 +252,7 @@ pub async fn graphql_cache_enqueue_optimistic_mutation<R: Runtime>(
let result = engine_handle(&state)?
.enqueue_optimistic_mutation(
origin_op_id,
+ uuid,
query,
operation_name,
variables.unwrap_or_default(),
@@ -264,6 +267,18 @@ pub async fn graphql_cache_enqueue_optimistic_mutation<R: Runtime>(
.await?;
emit_ops_affected(&app, &result.result.affected_ops, &result.result.changed);
emit_cache_changed(&app, &result.result.revision);
+ if let MutationUpsertKindWire::ReplacedPending {
+ removed_transaction_id,
+ } = &result.upsert_kind
+ {
+ emit_mutation_settled(
+ &app,
+ removed_transaction_id.clone(),
+ "superseded",
+ None,
+ Some(result.transaction_id.clone()),
+ );
+ }
Ok(result)
}
@@ -325,15 +340,17 @@ pub async fn graphql_cache_claim_next_mutation(
/// Retains a retryable queued mutation and releases its lease.
#[tauri::command]
-pub async fn graphql_cache_defer_optimistic_write(
+pub async fn graphql_cache_defer_optimistic_write<R: Runtime>(
+ app: AppHandle<R>,
state: State<'_, CacheState>,
transaction_id: String,
lease_owner: String,
lease_generation: String,
next_attempt_at_ms: i64,
error: String,
-) -> Result<(), String> {
- engine_handle(&state)?
+) -> Result<DeferOptimisticWriteResultWire, String> {
+ let settlement_transaction_id = transaction_id.clone();
+ let result = engine_handle(&state)?
.defer_optimistic_write(
transaction_id,
lease_owner,
@@ -341,7 +358,23 @@ pub async fn graphql_cache_defer_optimistic_write(
next_attempt_at_ms,
error,
)
- .await
+ .await?;
+ if let DeferOptimisticWriteResultWire::DiscardedSuperseded {
+ replacement_transaction_id,
+ result: write_result,
+ } = &result
+ {
+ emit_ops_affected(&app, &write_result.affected_ops, &write_result.changed);
+ emit_cache_changed(&app, &write_result.revision);
+ emit_mutation_settled(
+ &app,
+ settlement_transaction_id,
+ "superseded",
+ None,
+ Some(replacement_transaction_id.clone()),
+ );
+ }
+ Ok(result)
}
/// Atomically replaces a claimed optimistic layer with the real response.
@@ -356,7 +389,7 @@ pub async fn graphql_cache_commit_optimistic_write<R: Runtime>(
operation_name: Option<String>,
variables: Option<Variables>,
data: serde_json::Value,
-) -> Result<WriteResultWire, String> {
+) -> Result<CommitOptimisticWriteResultWire, String> {
let settlement_transaction_id = transaction_id.clone();
let result = engine_handle(&state)?
.commit_optimistic_write(
@@ -369,9 +402,30 @@ pub async fn graphql_cache_commit_optimistic_write<R: Runtime>(
data,
)
.await?;
- emit_ops_affected(&app, &result.affected_ops, &result.changed);
- emit_cache_changed(&app, &result.revision);
- emit_mutation_settled(&app, settlement_transaction_id, "committed", None);
+ let (write_result, replacement_transaction_id) = match &result {
+ CommitOptimisticWriteResultWire::Committed { result } => (result, None),
+ CommitOptimisticWriteResultWire::CommittedSuperseded {
+ replacement_transaction_id,
+ result,
+ } => (result, Some(replacement_transaction_id.clone())),
+ };
+ emit_ops_affected(
+ &app,
+ &write_result.affected_ops,
+ &write_result.changed,
+ );
+ emit_cache_changed(&app, &write_result.revision);
+ emit_mutation_settled(
+ &app,
+ settlement_transaction_id,
+ if replacement_transaction_id.is_some() {
+ "superseded"
+ } else {
+ "committed"
+ },
+ None,
+ replacement_transaction_id,
+ );
Ok(result)
}
@@ -384,19 +438,40 @@ pub async fn graphql_cache_rollback_optimistic_write<R: Runtime>(
lease_owner: String,
lease_generation: String,
error: String,
-) -> Result<WriteResultWire, String> {
+) -> Result<RollbackOptimisticWriteResultWire, String> {
let settlement_transaction_id = transaction_id.clone();
let result = engine_handle(&state)?
.rollback_optimistic_write(transaction_id, lease_owner, lease_generation)
.await?;
- emit_ops_affected(&app, &result.affected_ops, &result.changed);
- emit_cache_changed(&app, &result.revision);
- emit_mutation_settled(
- &app,
- settlement_transaction_id,
- "permanently-failed",
- Some(error),
- );
+ match &result {
+ RollbackOptimisticWriteResultWire::RolledBack {
+ result: write_result,
+ } => {
+ emit_ops_affected(&app, &write_result.affected_ops, &write_result.changed);
+ emit_cache_changed(&app, &write_result.revision);
+ emit_mutation_settled(
+ &app,
+ settlement_transaction_id,
+ "permanently-failed",
+ Some(error),
+ None,
+ );
+ }
+ RollbackOptimisticWriteResultWire::DiscardedSuperseded {
+ replacement_transaction_id,
+ result: write_result,
+ } => {
+ emit_ops_affected(&app, &write_result.affected_ops, &write_result.changed);
+ emit_cache_changed(&app, &write_result.revision);
+ emit_mutation_settled(
+ &app,
+ settlement_transaction_id,
+ "superseded",
+ None,
+ Some(replacement_transaction_id.clone()),
+ );
+ }
+ }
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 8c8923d249..e7f22c3d0d 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine.rs
@@ -13,13 +13,16 @@
use cache_core::deps::OpId;
use cache_core::engine::{
- BeginOptimisticWrite, Engine, InitialClaimOutcome, NetworkWrite, QueryRegistration, ReadResult,
- WriteResult,
+ BeginOptimisticWrite, CommitOptimisticWriteResult, DeferOptimisticWriteResult, Engine,
+ InitialClaimOutcome, NetworkWrite, QueryRegistration, ReadResult,
+ RollbackOptimisticWriteResult, WriteResult,
};
use cache_core::entity_resolver::EntityResolver;
use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};
use cache_core::query_inspection::{CachedQueryInstance, CachedQueryVariant, QueryInspection};
-use cache_core::queue::{ClaimedMutation, MutationClaimRequest, MutationClaimToken};
+use cache_core::queue::{
+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationUpsertKind,
+};
use cache_core::record_selection::{RecordSelection, SelectedRecord};
use cache_core::revision::CacheRevision;
use cache_core::search::{SearchPage, SearchRequest};
@@ -97,6 +100,8 @@ pub struct EnqueueOptimisticMutationResultWire {
/// Engine-assigned id; settle with commit/rollback. A string because JS
/// numbers lose precision past 2^53 (same as the wasm shell).
pub transaction_id: String,
+ /// How the caller UUID changed the queue.
+ pub upsert_kind: MutationUpsertKindWire,
/// Visible composed-view changes caused by the new optimistic layer.
#[serde(flatten)]
pub result: WriteResultWire,
@@ -104,6 +109,42 @@ pub struct EnqueueOptimisticMutationResultWire {
pub initial_claim: InitialMutationClaimWire,
}
+/// Queue collision outcome serialized for the webview.
+#[derive(Debug, Serialize)]
+#[serde(
+ tag = "kind",
+ rename_all = "kebab-case",
+ rename_all_fields = "camelCase"
+)]
+pub enum MutationUpsertKindWire {
+ /// A new UUID was appended.
+ Inserted,
+ /// A pending row was removed and replaced at the tail.
+ ReplacedPending {
+ /// Removed queue transaction.
+ removed_transaction_id: String,
+ },
+ /// A live row was retained and superseded.
+ AppendedAfterActive {
+ /// Still-active queue transaction.
+ active_transaction_id: String,
+ },
+}
+
+impl From<MutationUpsertKind> for MutationUpsertKindWire {
+ fn from(kind: MutationUpsertKind) -> Self {
+ match kind {
+ MutationUpsertKind::Inserted => Self::Inserted,
+ MutationUpsertKind::ReplacedPending { removed_id } => Self::ReplacedPending {
+ removed_transaction_id: removed_id.to_string(),
+ },
+ MutationUpsertKind::AppendedAfterActive { active_id } => Self::AppendedAfterActive {
+ active_transaction_id: active_id.to_string(),
+ },
+ }
+ }
+}
+
/// Tagged outcome of the initial strict-head claim attempt.
#[derive(Debug, Serialize)]
#[serde(tag = "kind", rename_all = "kebab-case")]
@@ -128,6 +169,10 @@ pub enum InitialMutationClaimWire {
pub struct ClaimedMutationWire {
/// Durable mutation id.
pub transaction_id: String,
+ /// Caller coalescing UUID.
+ pub uuid: String,
+ /// Whether a newer current row superseded this request.
+ pub superseded: bool,
/// Claim generation required for settlement.
pub lease_generation: String,
/// GraphQL mutation document.
@@ -142,6 +187,74 @@ pub struct ClaimedMutationWire {
pub attempt_count: u32,
}
+/// Tagged result of deferring or discarding a failed queue attempt.
+#[derive(Debug, Serialize)]
+#[serde(
+ tag = "kind",
+ rename_all = "kebab-case",
+ rename_all_fields = "camelCase"
+)]
+pub enum DeferOptimisticWriteResultWire {
+ /// Retry state was retained normally.
+ Deferred,
+ /// A superseded row was discarded instead of retried.
+ DiscardedSuperseded {
+ /// Current transaction carrying the newer intent.
+ replacement_transaction_id: String,
+ /// Cache changes caused by discarding the old layer.
+ #[serde(flatten)]
+ result: WriteResultWire,
+ },
+}
+
+/// Tagged result of committing a current or superseded queue attempt.
+#[derive(Debug, Serialize)]
+#[serde(
+ tag = "kind",
+ rename_all = "kebab-case",
+ rename_all_fields = "camelCase"
+)]
+pub enum CommitOptimisticWriteResultWire {
+ /// The current mutation committed normally.
+ Committed {
+ /// Cache changes caused by commit.
+ #[serde(flatten)]
+ result: WriteResultWire,
+ },
+ /// The response committed beneath a newer optimistic replacement.
+ CommittedSuperseded {
+ /// Current transaction carrying the newer intent.
+ replacement_transaction_id: String,
+ /// Cache changes caused by commit.
+ #[serde(flatten)]
+ result: WriteResultWire,
+ },
+}
+
+/// Tagged result of permanently failing or superseding a queue attempt.
+#[derive(Debug, Serialize)]
+#[serde(
+ tag = "kind",
+ rename_all = "kebab-case",
+ rename_all_fields = "camelCase"
+)]
+pub enum RollbackOptimisticWriteResultWire {
+ /// The current mutation permanently failed.
+ RolledBack {
+ /// Cache changes caused by rollback.
+ #[serde(flatten)]
+ result: WriteResultWire,
+ },
+ /// A superseded attempt was accepted and discarded.
+ DiscardedSuperseded {
+ /// Current transaction carrying the newer intent.
+ replacement_transaction_id: String,
+ /// Cache changes caused by discarding the old layer.
+ #[serde(flatten)]
+ result: WriteResultWire,
+ },
+}
+
impl TryFrom<ClaimedMutation> for ClaimedMutationWire {
type Error = String;
@@ -149,6 +262,8 @@ impl TryFrom<ClaimedMutation> for ClaimedMutationWire {
let request = claimed.queued.mutation.request;
Ok(Self {
transaction_id: claimed.queued.id.to_string(),
+ uuid: claimed.queued.uuid.to_string(),
+ superseded: claimed.queued.superseded,
lease_generation: claimed.lease_generation.to_string(),
query: request.query,
operation_name: request.operation_name,
@@ -475,6 +590,7 @@ impl EngineHandle {
pub async fn enqueue_optimistic_mutation(
&self,
origin_op_id: Option<String>,
+ uuid: String,
query: String,
operation_name: Option<String>,
variables: Variables,
@@ -493,6 +609,7 @@ impl EngineHandle {
.enqueue_optimistic_mutation(
origin,
BeginOptimisticWrite {
+ uuid: &uuid,
query: &query,
operation_name: operation_name.as_deref(),
variables: &variables,
@@ -520,6 +637,7 @@ impl EngineHandle {
};
Ok(EnqueueOptimisticMutationResultWire {
transaction_id: result.transaction_id.to_string(),
+ upsert_kind: result.upsert_kind.into(),
result: wire_write_result(ops, result.write_result),
initial_claim,
})
@@ -554,19 +672,27 @@ impl EngineHandle {
lease_generation: String,
next_attempt_at_ms: i64,
error: String,
- ) -> Result<(), String> {
+ ) -> Result<DeferOptimisticWriteResultWire, 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
+ let mut state = self.inner.lock().await;
+ let EngineState { engine, ops } = &mut *state;
+ match engine
.defer_optimistic_write(transaction, claim, next_attempt_at_ms, error)
.await
- .map_err(|e| e.to_string())
+ .map_err(|e| e.to_string())?
+ {
+ DeferOptimisticWriteResult::Deferred => Ok(DeferOptimisticWriteResultWire::Deferred),
+ DeferOptimisticWriteResult::DiscardedSuperseded(result) => {
+ Ok(DeferOptimisticWriteResultWire::DiscardedSuperseded {
+ replacement_transaction_id: result.replacement_transaction_id.to_string(),
+ result: wire_write_result(ops, result.write_result),
+ })
+ }
+ }
}
/// Replaces a claimed optimistic layer with the real network response.
@@ -579,7 +705,7 @@ impl EngineHandle {
operation_name: Option<String>,
variables: Variables,
data: serde_json::Value,
- ) -> Result<WriteResultWire, String> {
+ ) -> Result<CommitOptimisticWriteResultWire, String> {
let transaction = parse_transaction_id(&transaction_id)?;
let claim = MutationClaimToken {
owner: lease_owner,
@@ -587,8 +713,8 @@ impl EngineHandle {
};
let mut state = self.inner.lock().await;
let EngineState { engine, ops } = &mut *state;
- engine
- .commit_optimistic_write(
+ match engine
+ .commit_optimistic_write_with_outcome(
transaction,
claim,
&query,
@@ -597,8 +723,20 @@ impl EngineHandle {
&data,
)
.await
- .map(|result| wire_write_result(ops, result))
- .map_err(|e| e.to_string())
+ .map_err(|e| e.to_string())?
+ {
+ CommitOptimisticWriteResult::Committed(result) => {
+ Ok(CommitOptimisticWriteResultWire::Committed {
+ result: wire_write_result(ops, result),
+ })
+ }
+ CommitOptimisticWriteResult::CommittedSuperseded(result) => {
+ Ok(CommitOptimisticWriteResultWire::CommittedSuperseded {
+ replacement_transaction_id: result.replacement_transaction_id.to_string(),
+ result: wire_write_result(ops, result.write_result),
+ })
+ }
+ }
}
/// Permanently fails a claimed mutation and drops its optimistic layer.
@@ -607,7 +745,7 @@ impl EngineHandle {
transaction_id: String,
lease_owner: String,
lease_generation: String,
- ) -> Result<WriteResultWire, String> {
+ ) -> Result<RollbackOptimisticWriteResultWire, String> {
let transaction = parse_transaction_id(&transaction_id)?;
let claim = MutationClaimToken {
owner: lease_owner,
@@ -615,11 +753,23 @@ impl EngineHandle {
};
let mut state = self.inner.lock().await;
let EngineState { engine, ops } = &mut *state;
- engine
- .rollback_optimistic_write(transaction, claim)
+ match engine
+ .rollback_optimistic_write_with_outcome(transaction, claim)
.await
- .map(|result| wire_write_result(ops, result))
- .map_err(|e| e.to_string())
+ .map_err(|e| e.to_string())?
+ {
+ RollbackOptimisticWriteResult::RolledBack(result) => {
+ Ok(RollbackOptimisticWriteResultWire::RolledBack {
+ result: wire_write_result(ops, result),
+ })
+ }
+ RollbackOptimisticWriteResult::DiscardedSuperseded(result) => {
+ Ok(RollbackOptimisticWriteResultWire::DiscardedSuperseded {
+ replacement_transaction_id: result.replacement_transaction_id.to_string(),
+ result: wire_write_result(ops, result.write_result),
+ })
+ }
+ }
}
/// Evicts records by entity key; returns the affected registered op ids.
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 27d138a99d..4c346e3826 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
@@ -68,6 +68,58 @@ fn read(handle: &EngineHandle, op_id: Option<&str>) -> ReadResultWire {
.unwrap()
}
+fn empty_write_result() -> WriteResultWire {
+ WriteResultWire {
+ revision: "0".to_string(),
+ changed: Vec::new(),
+ affected_ops: Vec::new(),
+ reset: false,
+ revalidations: Vec::new(),
+ }
+}
+
+#[test]
+fn tagged_wire_enum_fields_are_camel_case() {
+ assert_eq!(
+ serde_json::to_value(MutationUpsertKindWire::ReplacedPending {
+ removed_transaction_id: "1".to_string(),
+ })
+ .unwrap(),
+ serde_json::json!({"kind": "replaced-pending", "removedTransactionId": "1"})
+ );
+ assert_eq!(
+ serde_json::to_value(MutationUpsertKindWire::AppendedAfterActive {
+ active_transaction_id: "2".to_string(),
+ })
+ .unwrap(),
+ serde_json::json!({"kind": "appended-after-active", "activeTransactionId": "2"})
+ );
+ assert_eq!(
+ serde_json::to_value(DeferOptimisticWriteResultWire::DiscardedSuperseded {
+ replacement_transaction_id: "3".to_string(),
+ result: empty_write_result(),
+ })
+ .unwrap()["replacementTransactionId"],
+ "3"
+ );
+ assert_eq!(
+ serde_json::to_value(CommitOptimisticWriteResultWire::CommittedSuperseded {
+ replacement_transaction_id: "4".to_string(),
+ result: empty_write_result(),
+ })
+ .unwrap()["replacementTransactionId"],
+ "4"
+ );
+ assert_eq!(
+ serde_json::to_value(RollbackOptimisticWriteResultWire::DiscardedSuperseded {
+ replacement_transaction_id: "5".to_string(),
+ result: empty_write_result(),
+ })
+ .unwrap()["replacementTransactionId"],
+ "5"
+ );
+}
+
#[test]
fn write_then_read_round_trips() {
let handle = spawn_handle();
@@ -368,6 +420,7 @@ fn optimistic_layer_commits_durably() {
let optimistic = block_on(handle.enqueue_optimistic_mutation(
Some("client:2".to_string()),
+ "00000000-0000-4000-8000-000000000001".to_string(),
QUERY.to_string(),
Some("Soup".to_string()),
variables(),
@@ -382,6 +435,7 @@ fn optimistic_layer_commits_durably() {
.unwrap();
assert_eq!(optimistic.result.affected_ops, vec!["client:1".to_string()]);
let serialized = serde_json::to_value(&optimistic).unwrap();
+ assert_eq!(serialized["upsertKind"]["kind"], "inserted");
assert_eq!(serialized["initialClaim"]["kind"], "claimed");
assert_eq!(
serialized["initialClaim"]["mutation"]["transactionId"],
@@ -391,6 +445,8 @@ fn optimistic_layer_commits_durably() {
panic!("new queue head should be claimed")
};
assert_eq!(claimed.transaction_id, optimistic.transaction_id);
+ assert_eq!(claimed.uuid, "00000000-0000-4000-8000-000000000001");
+ assert!(!claimed.superseded);
// The optimistic view answers reads.
let ReadResultWire::Hit { data } = read(&handle, None) else {
@@ -408,6 +464,9 @@ fn optimistic_layer_commits_durably() {
soup_data(true),
))
.unwrap();
+ let CommitOptimisticWriteResultWire::Committed { result: committed } = committed else {
+ panic!("current transaction was reported as superseded")
+ };
assert!(!committed.changed.is_empty());
let ReadResultWire::Hit { data } = read(&handle, None) else {
@@ -423,6 +482,7 @@ fn rollback_drops_optimistic_contribution() {
let optimistic = block_on(handle.enqueue_optimistic_mutation(
None,
+ "00000000-0000-4000-8000-000000000002".to_string(),
QUERY.to_string(),
Some("Soup".to_string()),
variables(),
diff --git a/apps/web/tauri/graphql_cache_plugin/src/lib.rs b/apps/web/tauri/graphql_cache_plugin/src/lib.rs
index 4a68c11000..1b5519070f 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/lib.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/lib.rs
@@ -23,9 +23,10 @@ pub mod commands;
mod engine;
pub use engine::{
- AffectedOperationsResultWire, ClaimedMutationWire, EngineHandle,
- EnqueueOptimisticMutationResultWire, InitialMutationClaimWire, ReadResultWire,
- RecordSelectionResultWire, WriteResultWire,
+ AffectedOperationsResultWire, ClaimedMutationWire, CommitOptimisticWriteResultWire,
+ DeferOptimisticWriteResultWire, EngineHandle, EnqueueOptimisticMutationResultWire,
+ InitialMutationClaimWire, ReadResultWire, RecordSelectionResultWire,
+ RollbackOptimisticWriteResultWire, WriteResultWire,
};
/// Broadcast event carrying [`OpsAffectedEvent`]: operations whose
@@ -66,6 +67,8 @@ struct MutationSettledEvent {
status: &'static str,
#[serde(skip_serializing_if = "Option::is_none")]
error: Option<String>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ replacement_transaction_id: Option<String>,
}
struct InitializedCache {
@@ -112,8 +115,8 @@ fn emit_cache_changed<R: Runtime>(app: &AppHandle<R>, revision: &str) {
revision: revision.to_owned(),
},
)
- .inspect_err(|e| tracing::error!(error=?e, "failed to emit graphql cache change event"))
- .ok();
+ .inspect_err(|e| tracing::error!(error=?e, "failed to emit graphql cache change event"))
+ .ok();
}
fn emit_mutation_settled<R: Runtime>(
@@ -121,6 +124,7 @@ fn emit_mutation_settled<R: Runtime>(
transaction_id: String,
status: &'static str,
error: Option<String>,
+ replacement_transaction_id: Option<String>,
) {
app.emit(
MUTATION_SETTLED_EVENT,
@@ -128,6 +132,7 @@ fn emit_mutation_settled<R: Runtime>(
transaction_id,
status,
error,
+ replacement_transaction_id,
},
)
.inspect_err(|e| tracing::error!(error=?e, "failed to emit graphql mutation settlement"))
diff --git a/crates/client/cache-core/Cargo.toml b/crates/client/cache-core/Cargo.toml
index 4fdf86cd26..7263e00d87 100644
--- a/crates/client/cache-core/Cargo.toml
+++ b/crates/client/cache-core/Cargo.toml
@@ -15,6 +15,7 @@ serde = { workspace = true }
serde_json = { workspace = true }
sha2 = { workspace = true }
thiserror = { workspace = true }
+uuid = { workspace = true }
[build-dependencies]
apollo-compiler = { workspace = true }
diff --git a/crates/client/cache-core/src/engine.rs b/crates/client/cache-core/src/engine.rs
index 2492113ed1..40e3e4e2b3 100644
--- a/crates/client/cache-core/src/engine.rs
+++ b/crates/client/cache-core/src/engine.rs
@@ -21,10 +21,10 @@ use crate::normalize::{
project_hydration_response,
};
use crate::predicate::{
- OptimisticShadowReconciliation, PredicateIndexStorage, PredicateQueryResult,
- ProjectionMutation, ProjectionMutationLayer, ProjectionState,
+ OptimisticShadowReconciliation, OptimisticUpsertReconciliation, PredicateIndexStorage,
+ PredicateQueryResult, ProjectionMutation, ProjectionMutationLayer, ProjectionState,
+ StagedOptimisticProjection, StagedOptimisticProjectionOwner,
apply_authoritative_projection_patch, compose_effective_optimistic_projection,
- compose_pending_optimistic_projection,
};
use crate::query_inspection::{
CachedQueryInstance, CachedQueryVariant, OwnerResolution, QueryInspection,
@@ -32,9 +32,10 @@ use crate::query_inspection::{
selected_result_value,
};
use crate::queue::{
- ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationRequest,
- NewQueuedMutation, OptimisticSource, PersistedOptimisticLayer, QueuedMutation, StoredMutation,
- decode_optimistic_source, encode_optimistic_source,
+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationQueueSnapshot,
+ MutationRequest, MutationUpsertKind, NewQueuedMutation, OptimisticSource,
+ PersistedOptimisticLayer, QueuedMutation, StoredMutation, decode_optimistic_source,
+ encode_optimistic_source,
};
use crate::record_selection::{
MAX_RECORD_SELECTION_KEYS, RecordSelection, RecordSelectionError, SelectedRecord,
@@ -54,6 +55,7 @@ use serde_json::Value as Json;
use std::collections::{BTreeMap, BTreeSet, HashMap};
use std::num::NonZeroUsize;
use thiserror::Error;
+use uuid::Uuid;
#[derive(Debug, Error)]
pub enum EngineError<S: std::error::Error + 'static> {
@@ -84,6 +86,10 @@ pub enum EngineError<S: std::error::Error + 'static> {
},
#[error("invalid optimistic projection: {0}")]
InvalidOptimisticProjection(String),
+ #[error("invalid optimistic mutation UUID `{0}`")]
+ InvalidMutationUuid(String),
+ #[error("durable optimistic queue changed while staging UUID upsert")]
+ StaleOptimisticUpsert,
#[error("storage: {0}")]
Storage(#[source] S),
#[error("cache revision overflow")]
@@ -169,14 +175,54 @@ pub enum InitialClaimOutcome<E> {
pub struct EnqueueOptimisticMutationResult<E> {
/// Engine-assigned id of the newly enqueued optimistic mutation.
pub transaction_id: OptimisticTransactionId,
+ /// How the caller UUID changed the queue.
+ pub upsert_kind: MutationUpsertKind,
/// Visible cache changes caused by the newly published optimistic layer.
pub write_result: WriteResult,
/// Outcome of the claim attempt made before hosts publish cache changes.
pub initial_claim: InitialClaimOutcome<E>,
}
+/// Cache change and replacement identity produced by settling superseded work.
+#[derive(Debug)]
+pub struct SupersededMutationResult {
+ /// Cache changes caused by settling the superseded layer.
+ pub write_result: WriteResult,
+ /// Current transaction carrying the caller's newer intent.
+ pub replacement_transaction_id: OptimisticTransactionId,
+}
+
+/// Tagged commit result used by transport adapters for settlement fanout.
+#[derive(Debug)]
+pub enum CommitOptimisticWriteResult {
+ /// A current mutation committed normally.
+ Committed(WriteResult),
+ /// The response committed beneath a newer optimistic replacement.
+ CommittedSuperseded(SupersededMutationResult),
+}
+
+/// Result of attempting to defer a failed queue attempt.
+#[derive(Debug)]
+pub enum DeferOptimisticWriteResult {
+ /// The current mutation retained its optimistic layer and retry state.
+ Deferred,
+ /// The attempt was superseded, so it was discarded instead of retried.
+ DiscardedSuperseded(SupersededMutationResult),
+}
+
+/// Tagged rollback result used by transport adapters for settlement fanout.
+#[derive(Debug)]
+pub enum RollbackOptimisticWriteResult {
+ /// A current mutation permanently failed normally.
+ RolledBack(WriteResult),
+ /// A superseded attempt was accepted and discarded.
+ DiscardedSuperseded(SupersededMutationResult),
+}
+
/// Borrowed inputs for atomically beginning one optimistic mutation.
pub struct BeginOptimisticWrite<'a> {
+ /// Caller-supplied RFC UUID used only for safe coalescing.
+ pub uuid: &'a str,
/// GraphQL mutation document.
pub query: &'a str,
/// Selected operation name.
@@ -204,12 +250,20 @@ pub type OptimisticTransactionId = MutationId;
#[derive(Clone)]
struct OptimisticLayer {
id: OptimisticTransactionId,
+ uuid: Uuid,
+ superseded: bool,
updates: RecordUpdates,
link_patches: Vec<OptimisticLinkPatch>,
revalidations: Vec<QueryRevalidation>,
projection_mutations: Vec<OptimisticProjectionMutation>,
}
+struct BegunOptimisticWrite {
+ transaction_id: OptimisticTransactionId,
+ upsert_kind: MutationUpsertKind,
+ write_result: WriteResult,
+}
+
/// Reserved storage key holding the identity bound to this cache. The
/// `__meta:` prefix can never collide with entity keys (typenames can't
/// contain `:`).
@@ -351,6 +405,15 @@ impl<S: Storage> Engine<S> {
async fn rebuild_queued_layers(
&mut self,
queued: Vec<QueuedMutation>,
+ ) -> Result<Vec<OptimisticLayer>, EngineError<S::Error>> {
+ self.rebuild_queued_layers_with_strict_tail(queued, None)
+ .await
+ }
+
+ async fn rebuild_queued_layers_with_strict_tail(
+ &mut self,
+ queued: Vec<QueuedMutation>,
+ strict_tail: Option<MutationId>,
) -> Result<Vec<OptimisticLayer>, EngineError<S::Error>> {
let mut layers = Vec::with_capacity(queued.len());
for queued in queued {
@@ -388,8 +451,14 @@ impl<S: Storage> Engine<S> {
let mut effective = present_records(composed);
merge_updates_into_effective(&mut effective, &updates);
// Missing query fields after a format wipe are intentionally not
- // recreated from stale recipes during hydration.
- apply_link_patches(&mut effective, &mut updates, &patches, true)?;
+ // recreated from stale recipes during hydration. A newly submitted
+ // tail remains strict so invalid caller patches cannot be persisted.
+ apply_link_patches(
+ &mut effective,
+ &mut updates,
+ &patches,
+ strict_tail != Some(queued.id),
+ )?;
let revalidations = deduplicate_revalidations(
source.revalidations.iter().cloned().chain(
source
@@ -400,6 +469,8 @@ impl<S: Storage> Engine<S> {
);
layers.push(OptimisticLayer {
id: queued.id,
+ uuid: queued.uuid,
+ superseded: queued.superseded,
updates,
link_patches: patches,
revalidations,
@@ -1228,8 +1299,23 @@ impl<S: Storage> Engine<S> {
input: BeginOptimisticWrite<'_>,
projection_mutations: Vec<OptimisticProjectionMutation>,
) -> Result<(OptimisticTransactionId, WriteResult), EngineError<S::Error>> {
+ let begun = self
+ .upsert_optimistic_write(origin_op, input, projection_mutations)
+ .await?;
+ Ok((begun.transaction_id, begun.write_result))
+ }
+
+ async fn upsert_optimistic_write(
+ &mut self,
+ origin_op: Option<OpId>,
+ input: BeginOptimisticWrite<'_>,
+ projection_mutations: Vec<OptimisticProjectionMutation>,
+ ) -> Result<BegunOptimisticWrite, EngineError<S::Error>> {
+ let uuid = Uuid::parse_str(input.uuid)
+ .map_err(|_| EngineError::InvalidMutationUuid(input.uuid.to_owned()))?;
self.ensure_revision_can_advance()?;
let BeginOptimisticWrite {
+ uuid: _,
query,
operation_name,
variables,
@@ -1239,9 +1325,35 @@ impl<S: Storage> Engine<S> {
created_at_ms,
} = input;
self.hydrate_optimistic().await?;
- let doc = Self::document(&mut self.docs, query)?;
- let op = doc.operation(operation_name)?;
- let mut updates = normalize(op, variables, data)?;
+
+ let queued = self
+ .storage
+ .load_mutation_queue()
+ .await
+ .map_err(EngineError::Storage)?;
+ let expected_queue = queued
+ .iter()
+ .map(MutationQueueSnapshot::from)
+ .collect::<Vec<_>>();
+ let old_layers = self.rebuild_queued_layers(queued.clone()).await?;
+ let collision = queued
+ .iter()
+ .find(|queued| queued.uuid == uuid && !queued.superseded)
+ .map(|queued| {
+ (
+ queued.id,
+ queued
+ .mutation
+ .lease_expires_at_ms
+ .is_some_and(|expiry| expiry > created_at_ms),
+ )
+ });
+ let expected_kind = match collision {
+ None => MutationUpsertKind::Inserted,
+ Some((active_id, true)) => MutationUpsertKind::AppendedAfterActive { active_id },
+ Some((removed_id, false)) => MutationUpsertKind::ReplacedPending { removed_id },
+ };
+
let patches = deduplicate_patches(link_patches)?;
let revalidations = deduplicate_revalidations(
revalidations
@@ -1249,127 +1361,165 @@ impl<S: Storage> Engine<S> {
.cloned()
.chain(patches.iter().map(OptimisticLinkPatch::revalidation)),
);
-
- let candidates: BTreeSet<EntityKey<'static>> = updates.keys().cloned().collect();
- let optimistic = self.optimistic.clone();
- let (candidates, bases) = self
- .load_link_patch_bases(candidates, &optimistic, &updates, &patches)
- .await?;
- let before = effective_records(&bases, &self.optimistic, &candidates);
- let mut effective = present_records(before.clone());
- merge_updates_into_effective(&mut effective, &updates);
- // This stages on clones internally, so no part of an invalid patch
- // set can become visible or durable.
- apply_link_patches(&mut effective, &mut updates, &patches, false)?;
-
- let identity = match self.bound_identity().await? {
- IdentityState::Bound(identity) => Some(identity),
- IdentityState::NotHydrated | IdentityState::Missing => None,
- };
for mutation in &projection_mutations {
mutation
.validate()
.map_err(|error| EngineError::InvalidOptimisticProjection(error.to_string()))?;
}
- let shadow_replacements = if projection_mutations.is_empty() {
- Vec::new()
- } else {
- let keys = projection_mutations
- .iter()
- .map(|mutation| mutation.record_key().clone())
- .collect::<BTreeSet<_>>()
- .into_iter()
- .collect::<Vec<_>>();
- let authoritative = self
- .storage
- .load_projection_states(&keys)
- .await
- .map_err(EngineError::Storage)?;
- let current = self
- .storage
- .load_optimistic_projections(&keys)
- .await
- .map_err(EngineError::Storage)?;
- if authoritative.len() != keys.len() || current.len() != keys.len() {
- return Err(EngineError::InvalidOptimisticProjection(
- "storage returned misaligned optimistic projection bases".to_owned(),
- ));
- }
- keys.iter()
- .zip(authoritative.iter())
- .zip(current.iter())
- .map(|((key, authoritative), current)| {
- compose_pending_optimistic_projection(
- key,
- authoritative.as_ref(),
- current.as_ref(),
- &projection_mutations,
- )
- .map_err(|error| EngineError::InvalidOptimisticProjection(error.to_string()))?
- .ok_or_else(|| {
- EngineError::InvalidOptimisticProjection(
- "touched optimistic projection key was not composed".to_owned(),
- )
- })
- })
- .collect::<Result<Vec<_>, _>>()?
+ let identity = match self.bound_identity().await? {
+ IdentityState::Bound(identity) => Some(identity),
+ IdentityState::NotHydrated | IdentityState::Missing => None,
};
let source = OptimisticSource {
mutation_data: data.clone(),
- link_patches: patches.clone(),
- revalidations: revalidations.clone(),
- projection_mutations: projection_mutations.clone(),
+ link_patches: patches,
+ revalidations,
+ projection_mutations,
+ };
+ let mut entry = NewQueuedMutation {
+ uuid,
+ 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: encode_optimistic_source(&source),
+ normalized_updates: RecordUpdates::default(),
+ },
};
- let id = self
+
+ let mut proposed_queue = queued.clone();
+ match expected_kind {
+ MutationUpsertKind::Inserted => {}
+ MutationUpsertKind::ReplacedPending { removed_id } => {
+ proposed_queue.retain(|queued| queued.id != removed_id);
+ }
+ MutationUpsertKind::AppendedAfterActive { active_id } => {
+ proposed_queue
+ .iter_mut()
+ .find(|queued| queued.id == active_id)
+ .expect("collision was loaded")
+ .superseded = true;
+ }
+ }
+ proposed_queue.push(QueuedMutation {
+ id: MutationId::MAX,
+ uuid,
+ superseded: false,
+ mutation: entry.mutation.clone(),
+ optimistic: entry.optimistic.clone(),
+ });
+ let mut proposed_layers = self
+ .rebuild_queued_layers_with_strict_tail(proposed_queue, Some(MutationId::MAX))
+ .await?;
+ entry.optimistic.normalized_updates = proposed_layers
+ .last()
+ .expect("proposed queue contains the new tail")
+ .updates
+ .clone();
+
+ let mut candidates = layer_keys(&old_layers);
+ candidates.extend(layer_keys(&proposed_layers));
+ let bases = self.load_bases(&candidates).await?;
+ let before = effective_records(&bases, &old_layers, &candidates);
+ let after = effective_records(&bases, &proposed_layers, &candidates);
+
+ let affected_projection_keys = old_layers
+ .iter()
+ .chain(&proposed_layers)
+ .flat_map(|layer| &layer.projection_mutations)
+ .map(|mutation| mutation.record_key().clone())
+ .collect::<BTreeSet<_>>()
+ .into_iter()
+ .collect::<Vec<_>>();
+ let authoritative = self
.storage
- .enqueue_mutation_with_shadow(
- 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: encode_optimistic_source(&source),
- normalized_updates: updates.clone(),
- },
+ .load_projection_states(&affected_projection_keys)
+ .await
+ .map_err(EngineError::Storage)?;
+ if authoritative.len() != affected_projection_keys.len() {
+ return Err(EngineError::InvalidOptimisticProjection(
+ "storage returned misaligned authoritative projection states".to_owned(),
+ ));
+ }
+ let projection_layers = proposed_layers
+ .iter()
+ .map(|layer| ProjectionMutationLayer {
+ owner: layer.id,
+ mutations: &layer.projection_mutations,
+ })
+ .collect::<Vec<_>>();
+ let replacements = affected_projection_keys
+ .iter()
+ .zip(authoritative.iter())
+ .filter_map(|(key, authoritative)| {
+ compose_effective_optimistic_projection(
+ key,
+ authoritative.as_ref(),
+ &projection_layers,
+ )
+ .transpose()
+ })
+ .collect::<Result<Vec<_>, _>>()
+ .map_err(|error| EngineError::InvalidOptimisticProjection(error.to_string()))?
+ .into_iter()
+ .map(|projection| StagedOptimisticProjection {
+ owner: if projection.owner == MutationId::MAX {
+ StagedOptimisticProjectionOwner::Enqueued
+ } else {
+ StagedOptimisticProjectionOwner::Existing(projection.owner)
+ },
+ state: projection.state,
+ uncertainty: projection.uncertainty,
+ })
+ .collect();
+ let upsert = self
+ .storage
+ .upsert_mutation_with_shadow(
+ entry,
+ created_at_ms,
+ OptimisticUpsertReconciliation {
+ expected_queue: Some(expected_queue),
+ affected_keys: affected_projection_keys,
+ replacements,
},
- shadow_replacements,
)
.await
.map_err(EngineError::Storage)?;
- self.optimistic.push(OptimisticLayer {
- id,
- updates,
- link_patches: patches,
- revalidations,
- projection_mutations,
- });
+ if upsert.kind != expected_kind {
+ return Err(EngineError::StaleOptimisticUpsert);
+ }
+ proposed_layers
+ .last_mut()
+ .expect("proposed queue contains the new tail")
+ .id = upsert.id;
+ self.optimistic = proposed_layers;
- let after = effective_records(&bases, &self.optimistic, &candidates);
- let changed: BTreeSet<EntityKey<'static>> = candidates
+ let changed = candidates
.into_iter()
.filter(|key| before.get(key) != after.get(key))
- .collect();
+ .collect::<BTreeSet<_>>();
let mut affected_ops = self.deps.ops_for_keys(changed.iter());
if let Some(origin) = origin_op {
affected_ops.remove(&origin);
}
let revision = self.advance_revision()?;
- Ok((
- id,
- WriteResult {
+ Ok(BegunOptimisticWrite {
+ transaction_id: upsert.id,
+ upsert_kind: upsert.kind,
+ write_result: WriteResult {
revision,
changed,
affected_ops,
reset: false,
revalidations: Vec::new(),
},
- ))
+ })
}
/// Durably enqueues a mutation and publishes its optimistic layer, then
@@ -1394,8 +1544,8 @@ impl<S: Storage> Engine<S> {
claim: MutationClaimRequest,
projection_mutations: Vec<OptimisticProjectionMutation>,
) -> Result<EnqueueOptimisticMutationResult<EngineError<S::Error>>, EngineError<S::Error>> {
- let (transaction_id, write_result) = self
- .begin_optimistic_write_with_projections(origin_op, input, projection_mutations)
+ let begun = self
+ .upsert_optimistic_write(origin_op, input, projection_mutations)
.await?;
let initial_claim = match self.claim_next_mutation(claim).await {
Ok(Some(claimed)) => InitialClaimOutcome::Claimed(Box::new(claimed)),
@@ -1403,8 +1553,9 @@ impl<S: Storage> Engine<S> {
Err(error) => InitialClaimOutcome::Failed(error),
};
Ok(EnqueueOptimisticMutationResult {
- transaction_id,
- write_result,
+ transaction_id: begun.transaction_id,
+ upsert_kind: begun.upsert_kind,
+ write_result: begun.write_result,
initial_claim,
})
}
@@ -1422,15 +1573,35 @@ impl<S: Storage> Engine<S> {
.map_err(EngineError::Storage)
}
- /// Releases a retryable mutation while retaining its optimistic layer.
+ /// Releases a retryable mutation, or discards it when a newer UUID match exists.
pub async fn defer_optimistic_write(
&mut self,
transaction: OptimisticTransactionId,
claim: MutationClaimToken,
next_attempt_at_ms: i64,
error: String,
- ) -> Result<(), EngineError<S::Error>> {
+ ) -> Result<DeferOptimisticWriteResult, EngineError<S::Error>> {
self.hydrate_optimistic().await?;
+ let layer = self
+ .optimistic
+ .iter()
+ .find(|layer| layer.id == transaction)
+ .ok_or(EngineError::UnknownTransaction(transaction))?;
+ if layer.superseded {
+ let replacement_transaction_id = self
+ .optimistic
+ .iter()
+ .find(|candidate| candidate.uuid == layer.uuid && !candidate.superseded)
+ .map(|candidate| candidate.id)
+ .ok_or(EngineError::UnknownTransaction(transaction))?;
+ let write_result = self.rollback_optimistic_write(transaction, claim).await?;
+ return Ok(DeferOptimisticWriteResult::DiscardedSuperseded(
+ SupersededMutationResult {
+ write_result,
+ replacement_transaction_id,
+ },
+ ));
+ }
if !self
.storage
.defer_mutation(transaction, claim, next_attempt_at_ms, error)
@@ -1439,7 +1610,7 @@ impl<S: Storage> Engine<S> {
{
return Err(EngineError::StaleMutationClaim(transaction));
}
- Ok(())
+ Ok(DeferOptimisticWriteResult::Deferred)
}
async fn stage_shadow_reconciliation(
@@ -1596,6 +1767,80 @@ impl<S: Storage> Engine<S> {
.await
}
+ /// Commits an optimistic write and reports whether a newer UUID match superseded it.
+ #[allow(clippy::too_many_arguments)]
+ pub async fn commit_optimistic_write_with_outcome(
+ &mut self,
+ transaction: OptimisticTransactionId,
+ claim: MutationClaimToken,
+ query: &str,
+ operation_name: Option<&str>,
+ variables: &serde_json::Map<String, Json>,
+ data: &Json,
+ ) -> Result<CommitOptimisticWriteResult, EngineError<S::Error>> {
+ self.commit_optimistic_write_with_projections_outcome(
+ transaction,
+ claim,
+ query,
+ operation_name,
+ variables,
+ data,
+ Vec::new(),
+ )
+ .await
+ }
+
+ /// Commits an optimistic write with projections and reports supersession.
+ #[allow(clippy::too_many_arguments)]
+ pub async fn commit_optimistic_write_with_projections_outcome(
+ &mut self,
+ transaction: OptimisticTransactionId,
+ claim: MutationClaimToken,
+ query: &str,
+ operation_name: Option<&str>,
+ variables: &serde_json::Map<String, Json>,
+ data: &Json,
+ projections: Vec<ProjectionMutation>,
+ ) -> Result<CommitOptimisticWriteResult, EngineError<S::Error>> {
+ self.hydrate_optimistic().await?;
+ let layer = self
+ .optimistic
+ .iter()
+ .find(|layer| layer.id == transaction)
+ .ok_or(EngineError::UnknownTransaction(transaction))?;
+ let replacement_transaction_id = if layer.superseded {
+ Some(
+ self.optimistic
+ .iter()
+ .find(|candidate| candidate.uuid == layer.uuid && !candidate.superseded)
+ .map(|candidate| candidate.id)
+ .ok_or(EngineError::UnknownTransaction(transaction))?,
+ )
+ } else {
+ None
+ };
+ let write_result = self
+ .commit_optimistic_write_with_projections(
+ transaction,
+ claim,
+ query,
+ operation_name,
+ variables,
+ data,
+ projections,
+ )
+ .await?;
+ match replacement_transaction_id {
+ Some(replacement_transaction_id) => Ok(
+ CommitOptimisticWriteResult::CommittedSuperseded(SupersededMutationResult {
+ write_result,
+ replacement_transaction_id,
+ }),
+ ),
+ None => Ok(CommitOptimisticWriteResult::Committed(write_result)),
+ }
+ }
+
/// Settles an optimistic write with atomic generic projection replacement.
#[allow(clippy::too_many_arguments)]
pub async fn commit_optimistic_write_with_projections(
@@ -1685,6 +1930,41 @@ impl<S: Storage> Engine<S> {
})
}
+ /// Permanently fails the claimed head with an explicit supersession outcome.
+ pub async fn rollback_optimistic_write_with_outcome(
+ &mut self,
+ transaction: OptimisticTransactionId,
+ claim: MutationClaimToken,
+ ) -> Result<RollbackOptimisticWriteResult, EngineError<S::Error>> {
+ self.hydrate_optimistic().await?;
+ let layer = self
+ .optimistic
+ .iter()
+ .find(|layer| layer.id == transaction)
+ .ok_or(EngineError::UnknownTransaction(transaction))?;
+ let replacement_transaction_id = if layer.superseded {
+ Some(
+ self.optimistic
+ .iter()
+ .find(|candidate| candidate.uuid == layer.uuid && !candidate.superseded)
+ .map(|candidate| candidate.id)
+ .ok_or(EngineError::UnknownTransaction(transaction))?,
+ )
+ } else {
+ None
+ };
+ let write_result = self.rollback_optimistic_write(transaction, claim).await?;
+ match replacement_transaction_id {
+ Some(replacement_transaction_id) => Ok(
+ RollbackOptimisticWriteResult::DiscardedSuperseded(SupersededMutationResult {
+ write_result,
+ replacement_transaction_id,
+ }),
+ ),
+ None => Ok(RollbackOptimisticWriteResult::RolledBack(write_result)),
+ }
+ }
+
/// Permanently fails the claimed head, atomically removing its queue row
/// and optimistic layer.
pub async fn rollback_optimistic_write(
diff --git a/crates/client/cache-core/src/predicate.rs b/crates/client/cache-core/src/predicate.rs
index cfff39d968..b0af321309 100644
--- a/crates/client/cache-core/src/predicate.rs
+++ b/crates/client/cache-core/src/predicate.rs
@@ -1,6 +1,10 @@
//! Generic predicate-projection lifecycle and exact-query storage port.
-use crate::{store::Storage, value::EntityKey};
+use crate::{
+ queue::{MutationId, MutationQueueSnapshot},
+ store::Storage,
+ value::EntityKey,
+};
use maybe_send::MaybeSend;
pub use predicate_index::ProjectionIncompleteKind;
use predicate_index::{
@@ -82,6 +86,81 @@ pub enum ProjectionCompositionError {
InvalidReconciliation,
}
+/// Owner of a projection shadow staged before storage assigns the new queue id.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum StagedOptimisticProjectionOwner {
+ /// An existing durable mutation remains the final owner.
+ Existing(MutationId),
+ /// The newly inserted tail mutation is the final owner.
+ Enqueued,
+}
+
+/// Effective projection shadow staged for a UUID-aware queue upsert.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct StagedOptimisticProjection {
+ /// Existing or transaction-local final owner.
+ pub owner: StagedOptimisticProjectionOwner,
+ /// Effective optimistic state.
+ pub state: OptimisticProjectionState,
+ /// Attributes whose effective value remains uncertain.
+ pub uncertainty: OptimisticUncertainty,
+}
+
+/// Atomic optimistic-shadow replacement staged against exact queue lifecycle state.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct OptimisticUpsertReconciliation {
+ /// Exact queue state observed while rebuilding optimistic layers. `None`
+ /// is reserved for direct storage callers that do not stage shadows.
+ pub expected_queue: Option<Vec<MutationQueueSnapshot>>,
+ /// Keys to remove or replace, in deterministic key order.
+ pub affected_keys: Vec<RecordKey>,
+ /// Effective replacements for keys still touched by proposed layers.
+ pub replacements: Vec<StagedOptimisticProjection>,
+}
+
+impl OptimisticUpsertReconciliation {
+ /// Validates deterministic keys, replacement ownership, and projection bounds.
+ pub fn validate(&self) -> Result<(), ProjectionCompositionError> {
+ if self.affected_keys.windows(2).any(|keys| keys[0] >= keys[1]) {
+ return Err(ProjectionCompositionError::InvalidReconciliation);
+ }
+ if let Some(queue) = &self.expected_queue
+ && (queue.iter().any(|row| row.id == 0)
+ || queue.windows(2).any(|rows| rows[0].id >= rows[1].id))
+ {
+ return Err(ProjectionCompositionError::LayerOrder);
+ }
+ let existing = self
+ .expected_queue
+ .iter()
+ .flatten()
+ .map(|row| row.id)
+ .collect::<BTreeSet<_>>();
+ let affected = self.affected_keys.iter().collect::<BTreeSet<_>>();
+ let mut replacement_keys = BTreeSet::new();
+ for replacement in &self.replacements {
+ let projection = EffectiveOptimisticProjection {
+ owner: match replacement.owner {
+ StagedOptimisticProjectionOwner::Existing(owner) => owner,
+ StagedOptimisticProjectionOwner::Enqueued => u64::MAX,
+ },
+ state: replacement.state.clone(),
+ uncertainty: replacement.uncertainty.clone(),
+ };
+ projection.validate()?;
+ if matches!(
+ replacement.owner,
+ StagedOptimisticProjectionOwner::Existing(owner) if !existing.contains(&owner)
+ ) || !affected.contains(replacement.state.record_key())
+ || !replacement_keys.insert(replacement.state.record_key())
+ {
+ return Err(ProjectionCompositionError::InvalidReconciliation);
+ }
+ }
+ Ok(())
+ }
+}
+
/// Atomic shadow replacement staged against one exact durable queue identity.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OptimisticShadowReconciliation {
diff --git a/crates/client/cache-core/src/queue.rs b/crates/client/cache-core/src/queue.rs
index 6215deb501..7e691e87a2 100644
--- a/crates/client/cache-core/src/queue.rs
+++ b/crates/client/cache-core/src/queue.rs
@@ -11,6 +11,7 @@ use crate::value::canonical_json;
use predicate_index::OptimisticProjectionMutation;
use serde::{Deserialize, Serialize};
use serde_json::Value as Json;
+use uuid::Uuid;
/// Durable, monotonically increasing mutation identifier and queue position.
pub type MutationId = u64;
@@ -180,6 +181,8 @@ pub struct PersistedOptimisticLayer {
/// A mutation and optimistic layer before storage assigns its queue id.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct NewQueuedMutation {
+ /// Caller-supplied coalescing key.
+ pub uuid: Uuid,
/// Mutation request plus initial retry metadata.
pub mutation: StoredMutation,
/// Optimistic contribution paired with the mutation.
@@ -191,12 +194,75 @@ pub struct NewQueuedMutation {
pub struct QueuedMutation {
/// Durable queue id and ordering key.
pub id: MutationId,
+ /// Caller-supplied coalescing key.
+ pub uuid: Uuid,
+ /// Whether a newer mutation superseded this still-active row.
+ pub superseded: bool,
/// Mutation request and retry metadata.
pub mutation: StoredMutation,
/// Optimistic contribution paired with the mutation.
pub optimistic: PersistedOptimisticLayer,
}
+/// Queue and lifecycle state used to fence a staged UUID upsert.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MutationQueueSnapshot {
+ /// Durable queue id.
+ pub id: MutationId,
+ /// Caller coalescing key.
+ pub uuid: Uuid,
+ /// Whether this row has been superseded.
+ pub superseded: bool,
+ /// Current lease owner.
+ pub lease_owner: Option<String>,
+ /// Current lease generation.
+ pub lease_generation: u64,
+ /// Current lease expiry.
+ pub lease_expires_at_ms: Option<i64>,
+ /// Current retry eligibility time.
+ pub next_attempt_at_ms: Option<i64>,
+}
+
+impl From<&QueuedMutation> for MutationQueueSnapshot {
+ fn from(queued: &QueuedMutation) -> Self {
+ Self {
+ id: queued.id,
+ uuid: queued.uuid,
+ superseded: queued.superseded,
+ lease_owner: queued.mutation.lease_owner.clone(),
+ lease_generation: queued.mutation.lease_generation,
+ lease_expires_at_ms: queued.mutation.lease_expires_at_ms,
+ next_attempt_at_ms: queued.mutation.next_attempt_at_ms,
+ }
+ }
+}
+
+/// How a UUID-aware enqueue changed the existing queue.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum MutationUpsertKind {
+ /// No current row used this UUID.
+ Inserted,
+ /// A non-active current row was removed.
+ ReplacedPending {
+ /// Transaction removed by the replacement.
+ removed_id: MutationId,
+ },
+ /// A live row was retained and marked superseded.
+ AppendedAfterActive {
+ /// Still-active transaction retained ahead of the replacement.
+ active_id: MutationId,
+ },
+}
+
+/// Result of atomically inserting or replacing a queued mutation.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct MutationUpsertResult {
+ /// Fresh queue id assigned to the inserted tail row.
+ pub id: MutationId,
+ /// Queue collision outcome.
+ pub kind: MutationUpsertKind,
+}
+
/// Successful claim of the oldest runnable mutation.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ClaimedMutation {
diff --git a/crates/client/cache-core/src/store.rs b/crates/client/cache-core/src/store.rs
index 4e0861513c..86db233f01 100644
--- a/crates/client/cache-core/src/store.rs
+++ b/crates/client/cache-core/src/store.rs
@@ -7,12 +7,13 @@
//! `Send`.
use crate::predicate::{
- OptimisticShadowReconciliation, PredicateIndexStorage, PredicateQueryResult,
- ProjectionMutation, ProjectionState, apply_authoritative_projection_patch,
+ OptimisticShadowReconciliation, OptimisticUpsertReconciliation, PredicateIndexStorage,
+ PredicateQueryResult, ProjectionMutation, ProjectionState, StagedOptimisticProjection,
+ StagedOptimisticProjectionOwner, apply_authoritative_projection_patch,
};
use crate::queue::{
- ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,
- QueuedMutation,
+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationQueueSnapshot,
+ MutationUpsertKind, MutationUpsertResult, NewQueuedMutation, QueuedMutation,
};
use crate::search::{SearchCursor, SearchDocument, SearchProfile, project_search_documents};
use crate::value::{EntityKey, Record};
@@ -97,24 +98,68 @@ pub trait Storage: MaybeSend {
async { Ok(Vec::new()) }
}
- /// Atomically appends a mutation and its optimistic layer to the queue.
+ /// Atomically inserts or replaces a mutation by its caller UUID.
fn enqueue_mutation(
&mut self,
entry: NewQueuedMutation,
) -> impl Future<Output = Result<MutationId, Self::Error>> + MaybeSend {
- self.enqueue_mutation_with_shadow(entry, Vec::new())
+ let now_ms = entry.mutation.created_at_ms;
+ async move {
+ self.upsert_mutation_with_shadow(
+ entry,
+ now_ms,
+ OptimisticUpsertReconciliation::default(),
+ )
+ .await
+ .map(|result| result.id)
+ }
}
- /// Atomically appends a mutation, its layer, and effective shadow replacements.
- ///
- /// Storage binds every pending projection to the mutation ID assigned in
- /// this transaction. Existing shadows for the pending record keys are
- /// replaced; all other shadows remain byte-for-byte unchanged.
+ /// Convenience upsert that assigns all supplied shadows to the new tail row.
fn enqueue_mutation_with_shadow(
&mut self,
entry: NewQueuedMutation,
projections: Vec<PendingOptimisticProjection>,
- ) -> impl Future<Output = Result<MutationId, Self::Error>> + MaybeSend;
+ ) -> impl Future<Output = Result<MutationId, Self::Error>> + MaybeSend {
+ let now_ms = entry.mutation.created_at_ms;
+ let mut affected_keys = projections
+ .iter()
+ .map(|projection| projection.state.record_key().clone())
+ .collect::<Vec<_>>();
+ affected_keys.sort();
+ let mut replacements = projections
+ .into_iter()
+ .map(|projection| StagedOptimisticProjection {
+ owner: StagedOptimisticProjectionOwner::Enqueued,
+ state: projection.state,
+ uncertainty: projection.uncertainty,
+ })
+ .collect::<Vec<_>>();
+ replacements.sort_by(|left, right| left.state.record_key().cmp(right.state.record_key()));
+ let reconciliation = OptimisticUpsertReconciliation {
+ expected_queue: None,
+ affected_keys,
+ replacements,
+ };
+ async move {
+ self.upsert_mutation_with_shadow(entry, now_ms, reconciliation)
+ .await
+ .map(|result| result.id)
+ }
+ }
+
+ /// Atomically inserts or replaces a mutation, its layer, and effective shadows.
+ ///
+ /// A live UUID collision retains and supersedes the old row. Any other
+ /// collision removes the old row. Storage resolves `Enqueued` projection
+ /// owners to the fresh ID assigned inside the same transaction and rejects
+ /// an expected queue snapshot that no longer matches.
+ fn upsert_mutation_with_shadow(
+ &mut self,
+ entry: NewQueuedMutation,
+ now_ms: i64,
+ reconciliation: OptimisticUpsertReconciliation,
+ ) -> impl Future<Output = Result<MutationUpsertResult, Self::Error>> + MaybeSend;
/// Loads authoritative projection states aligned with `keys`.
fn load_projection_states(
@@ -229,19 +274,21 @@ pub struct InMemoryStorage {
search_documents: HashMap<(SearchProfile, EntityKey<'static>), SearchDocument>,
projections: HashMap<PredicateRecordKey, ProjectionState>,
optimistic_projections: HashMap<PredicateRecordKey, EffectiveOptimisticProjection>,
- mutations: BTreeMap<
- MutationId,
- (
- crate::queue::StoredMutation,
- crate::queue::PersistedOptimisticLayer,
- ),
- >,
+ mutations: BTreeMap<MutationId, InMemoryQueuedMutation>,
next_mutation_id: MutationId,
record_get_count: Arc<AtomicUsize>,
search_catalog_load_count: Arc<AtomicUsize>,
mutation_queue_load_count: Arc<AtomicUsize>,
}
+#[derive(Clone, Debug)]
+struct InMemoryQueuedMutation {
+ uuid: uuid::Uuid,
+ superseded: bool,
+ mutation: crate::queue::StoredMutation,
+ optimistic: crate::queue::PersistedOptimisticLayer,
+}
+
impl InMemoryStorage {
pub fn new() -> Self {
Self::default()
@@ -357,27 +404,88 @@ impl Storage for InMemoryStorage {
Ok(documents)
}
- async fn enqueue_mutation_with_shadow(
+ async fn upsert_mutation_with_shadow(
&mut self,
entry: NewQueuedMutation,
- projections: Vec<PendingOptimisticProjection>,
- ) -> Result<MutationId, Self::Error> {
+ now_ms: i64,
+ reconciliation: OptimisticUpsertReconciliation,
+ ) -> Result<MutationUpsertResult, Self::Error> {
+ debug_assert!(reconciliation.validate().is_ok());
+ if let Some(expected) = &reconciliation.expected_queue {
+ let actual = self
+ .mutations
+ .iter()
+ .map(|(id, queued)| MutationQueueSnapshot {
+ id: *id,
+ uuid: queued.uuid,
+ superseded: queued.superseded,
+ lease_owner: queued.mutation.lease_owner.clone(),
+ lease_generation: queued.mutation.lease_generation,
+ lease_expires_at_ms: queued.mutation.lease_expires_at_ms,
+ next_attempt_at_ms: queued.mutation.next_attempt_at_ms,
+ })
+ .collect::<Vec<_>>();
+ assert_eq!(&actual, expected, "stale in-memory mutation upsert plan");
+ }
+
+ let collision = self
+ .mutations
+ .iter()
+ .find(|(_, queued)| queued.uuid == entry.uuid && !queued.superseded)
+ .map(|(id, queued)| {
+ (
+ *id,
+ queued
+ .mutation
+ .lease_expires_at_ms
+ .is_some_and(|expiry| expiry > now_ms),
+ )
+ });
+ let kind = match collision {
+ None => MutationUpsertKind::Inserted,
+ Some((id, true)) => {
+ self.mutations
+ .get_mut(&id)
+ .expect("collision exists")
+ .superseded = true;
+ MutationUpsertKind::AppendedAfterActive { active_id: id }
+ }
+ Some((id, false)) => {
+ self.mutations.remove(&id);
+ MutationUpsertKind::ReplacedPending { removed_id: id }
+ }
+ };
+
self.next_mutation_id += 1;
let id = self.next_mutation_id;
- self.mutations
- .insert(id, (entry.mutation, entry.optimistic));
- for projection in projections {
- let record_key = projection.state.record_key().clone();
+ self.mutations.insert(
+ id,
+ InMemoryQueuedMutation {
+ uuid: entry.uuid,
+ superseded: false,
+ mutation: entry.mutation,
+ optimistic: entry.optimistic,
+ },
+ );
+ for key in reconciliation.affected_keys {
+ self.optimistic_projections.remove(&key);
+ }
+ for replacement in reconciliation.replacements {
+ let owner = match replacement.owner {
+ StagedOptimisticProjectionOwner::Existing(owner) => owner,
+ StagedOptimisticProjectionOwner::Enqueued => id,
+ };
+ debug_assert!(self.mutations.contains_key(&owner));
self.optimistic_projections.insert(
- record_key,
+ replacement.state.record_key().clone(),
EffectiveOptimisticProjection {
- owner: id,
- state: projection.state,
- uncertainty: projection.uncertainty,
+ owner,
+ state: replacement.state,
+ uncertainty: replacement.uncertainty,
},
);
}
- Ok(id)
+ Ok(MutationUpsertResult { id, kind })
}
async fn load_projection_states(
@@ -406,10 +514,12 @@ impl Storage for InMemoryStorage {
Ok(self
.mutations
.iter()
- .map(|(id, (mutation, optimistic))| QueuedMutation {
+ .map(|(id, queued)| QueuedMutation {
id: *id,
- mutation: mutation.clone(),
- optimistic: optimistic.clone(),
+ uuid: queued.uuid,
+ superseded: queued.superseded,
+ mutation: queued.mutation.clone(),
+ optimistic: queued.optimistic.clone(),
})
.collect())
}
@@ -421,7 +531,7 @@ impl Storage for InMemoryStorage {
oldest_created_at_ms: self
.mutations
.values()
- .map(|(mutation, _)| mutation.created_at_ms)
+ .map(|queued| queued.mutation.created_at_ms)
.min(),
})
}
@@ -430,9 +540,10 @@ impl Storage for InMemoryStorage {
&mut self,
request: MutationClaimRequest,
) -> Result<Option<ClaimedMutation>, Self::Error> {
- let Some((&id, (mutation, optimistic))) = self.mutations.iter_mut().next() else {
+ let Some((&id, queued)) = self.mutations.iter_mut().next() else {
return Ok(None);
};
+ let mutation = &mut queued.mutation;
if mutation
.next_attempt_at_ms
.is_some_and(|next| next > request.now_ms)
@@ -452,8 +563,10 @@ impl Storage for InMemoryStorage {
Ok(Some(ClaimedMutation {
queued: QueuedMutation {
id,
+ uuid: queued.uuid,
+ superseded: queued.superseded,
mutation: mutation.clone(),
- optimistic: optimistic.clone(),
+ optimistic: queued.optimistic.clone(),
},
lease_generation: generation,
}))
@@ -466,12 +579,13 @@ impl Storage for InMemoryStorage {
next_attempt_at_ms: i64,
error: String,
) -> Result<bool, Self::Error> {
- let Some((mutation, _)) = self.mutations.get_mut(&id) else {
+ let Some(queued) = self.mutations.get_mut(&id) else {
return Ok(false);
};
- if !claim_matches(mutation, &claim) {
+ if !claim_matches(&queued.mutation, &claim) {
return Ok(false);
}
+ let mutation = &mut queued.mutation;
mutation.next_attempt_at_ms = Some(next_attempt_at_ms);
mutation.last_error = Some(error);
mutation.lease_owner = None;
@@ -496,10 +610,10 @@ impl Storage for InMemoryStorage {
entries: Vec<(EntityKey<'static>, Record)>,
projections: Vec<ProjectionMutation>,
) -> Result<bool, Self::Error> {
- let Some((mutation, _)) = self.mutations.get(&id) else {
+ let Some(queued) = self.mutations.get(&id) else {
return Ok(false);
};
- if !claim_matches(mutation, &claim) {
+ if !claim_matches(&queued.mutation, &claim) {
return Ok(false);
}
for (key, record) in entries {
@@ -531,10 +645,10 @@ impl Storage for InMemoryStorage {
{
return Ok(false);
}
- let Some((mutation, _)) = self.mutations.get(&id) else {
+ let Some(queued) = self.mutations.get(&id) else {
return Ok(false);
};
- if !claim_matches(mutation, &claim) {
+ if !claim_matches(&queued.mutation, &claim) {
return Ok(false);
}
for replacement in &reconciliation.replacements {
@@ -568,10 +682,10 @@ impl Storage for InMemoryStorage {
id: MutationId,
claim: MutationClaimToken,
) -> Result<bool, Self::Error> {
- let Some((mutation, _)) = self.mutations.get(&id) else {
+ let Some(queued) = self.mutations.get(&id) else {
return Ok(false);
};
- if !claim_matches(mutation, &claim) {
+ if !claim_matches(&queued.mutation, &claim) {
return Ok(false);
}
self.mutations.remove(&id);
@@ -591,10 +705,10 @@ impl Storage for InMemoryStorage {
{
return Ok(false);
}
- let Some((mutation, _)) = self.mutations.get(&id) else {
+ let Some(queued) = self.mutations.get(&id) else {
return Ok(false);
};
- if !claim_matches(mutation, &claim) {
+ if !claim_matches(&queued.mutation, &claim) {
return Ok(false);
}
for replacement in &reconciliation.replacements {
diff --git a/crates/client/cache-core/tests/grouped_optimistic.rs b/crates/client/cache-core/tests/grouped_optimistic.rs
index f0b275fb23..cee2dee756 100644
--- a/crates/client/cache-core/tests/grouped_optimistic.rs
+++ b/crates/client/cache-core/tests/grouped_optimistic.rs
@@ -293,6 +293,7 @@ fn cache_only_read_observes_move_and_rollback_restores_it() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000021",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_variables("completed"),
@@ -376,6 +377,7 @@ fn success_reapplies_recipe_and_returns_deduplicated_revalidation() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000022",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_variables("completed"),
@@ -455,6 +457,7 @@ fn missing_destination_is_created_with_the_updated_item() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000023",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_variables("completed"),
@@ -532,6 +535,7 @@ fn missing_destination_rejects_the_whole_patch_set_without_enqueueing() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000024",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_variables("completed"),
diff --git a/crates/client/cache-core/tests/mutation_queue.rs b/crates/client/cache-core/tests/mutation_queue.rs
index ea273da7b2..5d74513ab1 100644
--- a/crates/client/cache-core/tests/mutation_queue.rs
+++ b/crates/client/cache-core/tests/mutation_queue.rs
@@ -1,6 +1,8 @@
+use cache_core::predicate::OptimisticUpsertReconciliation;
use cache_core::queue::{
- MutationClaimRequest, MutationClaimToken, MutationRequest, NewQueuedMutation, OptimisticSource,
- PersistedOptimisticLayer, StoredMutation, decode_optimistic_source, encode_optimistic_source,
+ MutationClaimRequest, MutationClaimToken, MutationRequest, MutationUpsertKind,
+ NewQueuedMutation, OptimisticSource, PersistedOptimisticLayer, StoredMutation,
+ decode_optimistic_source, encode_optimistic_source,
};
use cache_core::store::{InMemoryStorage, Storage};
use cache_core::value::{CacheValue, EntityKey, Record};
@@ -89,6 +91,7 @@ fn queued(value: &str, created_at_ms: i64) -> NewQueuedMutation {
.fields
.insert("name".into(), CacheValue::String(value.into()));
NewQueuedMutation {
+ uuid: uuid::Uuid::new_v5(&uuid::Uuid::NAMESPACE_OID, value.as_bytes()),
mutation: StoredMutation::new(
MutationRequest {
query: "mutation Rename { rename { id } }".into(),
@@ -163,6 +166,61 @@ fn queue_diagnostics_are_payload_free_and_track_oldest() {
});
}
+#[test]
+fn storage_upsert_reports_pending_and_active_uuid_collisions() {
+ block_on(async {
+ let mut storage = InMemoryStorage::new();
+ let uuid = uuid::Uuid::new_v4();
+ let mut first = queued("a", 1);
+ first.uuid = uuid;
+ let first = storage
+ .upsert_mutation_with_shadow(first, 1, OptimisticUpsertReconciliation::default())
+ .await
+ .unwrap();
+ assert_eq!(first.kind, MutationUpsertKind::Inserted);
+
+ let mut pending = queued("b", 2);
+ pending.uuid = uuid;
+ let pending = storage
+ .upsert_mutation_with_shadow(pending, 2, OptimisticUpsertReconciliation::default())
+ .await
+ .unwrap();
+ assert_eq!(
+ pending.kind,
+ MutationUpsertKind::ReplacedPending {
+ removed_id: first.id
+ }
+ );
+ let claimed = storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner".into(),
+ now_ms: 3,
+ lease_expires_at_ms: 100,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(claimed.queued.id, pending.id);
+
+ let mut active = queued("c", 4);
+ active.uuid = uuid;
+ let active = storage
+ .upsert_mutation_with_shadow(active, 4, OptimisticUpsertReconciliation::default())
+ .await
+ .unwrap();
+ assert_eq!(
+ active.kind,
+ MutationUpsertKind::AppendedAfterActive {
+ active_id: pending.id
+ }
+ );
+ let queue = storage.load_mutation_queue().await.unwrap();
+ assert_eq!(queue.len(), 2);
+ assert!(queue[0].superseded);
+ assert_eq!(queue[1].id, active.id);
+ });
+}
+
#[test]
fn queue_claim_retry_and_settlement_are_ordered() {
block_on(async {
diff --git a/crates/client/cache-core/tests/optimistic.rs b/crates/client/cache-core/tests/optimistic.rs
index 384e252949..7e7cc5e237 100644
--- a/crates/client/cache-core/tests/optimistic.rs
+++ b/crates/client/cache-core/tests/optimistic.rs
@@ -2,17 +2,17 @@
//! strict ordering, and lifecycle resets.
use cache_core::engine::{
- BeginOptimisticWrite, Engine, EngineError, InitialClaimOutcome, ReadResult,
+ BeginOptimisticWrite, CommitOptimisticWriteResult, DeferOptimisticWriteResult, Engine,
+ EngineError, InitialClaimOutcome, ReadResult,
};
-use cache_core::predicate::ProjectionMutation;
+use cache_core::predicate::{OptimisticUpsertReconciliation, ProjectionMutation};
use cache_core::queue::{
- ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,
- QueuedMutation,
+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationUpsertResult,
+ NewQueuedMutation, QueuedMutation,
};
use cache_core::store::{InMemoryStorage, Storage};
use cache_core::value::{CacheValue, EntityKey, Record};
use pollster::block_on;
-use predicate_index::PendingOptimisticProjection;
use serde_json::{Value as Json, json};
use std::sync::atomic::{AtomicBool, Ordering};
@@ -117,14 +117,15 @@ impl Storage for ClaimFailingStorage {
Ok(())
}
- async fn enqueue_mutation_with_shadow(
+ async fn upsert_mutation_with_shadow(
&mut self,
entry: NewQueuedMutation,
- projections: Vec<PendingOptimisticProjection>,
- ) -> Result<MutationId, Self::Error> {
+ now_ms: i64,
+ reconciliation: OptimisticUpsertReconciliation,
+ ) -> Result<MutationUpsertResult, Self::Error> {
Ok(self
.inner
- .enqueue_mutation_with_shadow(entry, projections)
+ .upsert_mutation_with_shadow(entry, now_ms, reconciliation)
.await
.unwrap())
}
@@ -297,6 +298,7 @@ async fn reconciliation_engine() -> (Engine<ClaimFailingStorage>, MutationId) {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000005",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("doing"),
@@ -362,6 +364,33 @@ async fn claim_head(
)
}
+async fn begin_value(
+ engine: &mut Engine<InMemoryStorage>,
+ uuid: &str,
+ value: &str,
+ created_at_ms: i64,
+) -> MutationId {
+ let variables = mutation_vars(value);
+ let data = mutation_response("Status", value);
+ engine
+ .begin_optimistic_write(
+ None,
+ BeginOptimisticWrite {
+ uuid,
+ query: MUTATION,
+ operation_name: Some("SetEntityProperty"),
+ variables: &variables,
+ data: &data,
+ link_patches: &[],
+ revalidations: &[],
+ created_at_ms,
+ },
+ )
+ .await
+ .unwrap()
+ .0
+}
+
async fn durable_value(engine: &Engine<InMemoryStorage>) -> Option<String> {
let records = engine
.storage()
@@ -387,6 +416,7 @@ fn begin_persists_mutation_and_optimistic_layer() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000006",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("doing"),
@@ -423,6 +453,7 @@ fn enqueue_claims_new_mutation_when_queue_was_empty() {
.enqueue_optimistic_mutation(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000007",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("doing"),
@@ -456,6 +487,7 @@ fn enqueue_claims_older_strict_head() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000008",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("older"),
@@ -471,6 +503,7 @@ fn enqueue_claims_older_strict_head() {
.enqueue_optimistic_mutation(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000009",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("new"),
@@ -505,6 +538,7 @@ fn enqueue_does_not_skip_a_leased_or_deferred_head() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000010",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("older"),
@@ -528,6 +562,7 @@ fn enqueue_does_not_skip_a_leased_or_deferred_head() {
.enqueue_optimistic_mutation(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000011",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("new"),
@@ -585,6 +620,7 @@ fn claim_failure_after_enqueue_preserves_one_durable_visible_mutation() {
.enqueue_optimistic_mutation(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000012",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("doing"),
@@ -694,6 +730,7 @@ fn claimed_success_atomically_commits_real_response() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000013",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("doing"),
@@ -745,6 +782,7 @@ fn retryable_failure_keeps_optimistic_layer_and_blocks_later_mutations() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000014",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("a"),
@@ -760,6 +798,7 @@ fn retryable_failure_keeps_optimistic_layer_and_blocks_later_mutations() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000015",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("b"),
@@ -806,6 +845,7 @@ fn permanent_failure_rolls_back_only_the_claimed_head() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000016",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("a"),
@@ -821,6 +861,7 @@ fn permanent_failure_rolls_back_only_the_claimed_head() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000017",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("b"),
@@ -856,6 +897,7 @@ fn stale_claim_cannot_settle_mutation() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000018",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("doing"),
@@ -887,6 +929,222 @@ fn stale_claim_cannot_settle_mutation() {
});
}
+#[test]
+fn pending_uuid_replacement_moves_to_tail_and_keeps_only_latest_layer() {
+ block_on(async {
+ const X: &str = "13e0b56d-772d-4cc6-920d-358de3235849";
+ const Y: &str = "34736e0a-cd21-418b-9f34-67362bc213cd";
+ let mut engine = engine_with_base("Status", "todo").await;
+ let first = begin_value(&mut engine, X, "a", 1).await;
+ let intervening = begin_value(&mut engine, Y, "c", 2).await;
+ let replacement = begin_value(&mut engine, X, "b", 3).await;
+
+ assert!(replacement > intervening && intervening > first);
+ let queued = engine.storage().load_mutation_queue().await.unwrap();
+ assert_eq!(
+ queued.iter().map(|row| row.id).collect::<Vec<_>>(),
+ [intervening, replacement]
+ );
+ assert_eq!(
+ queued.iter().map(|row| row.uuid).collect::<Vec<_>>(),
+ [
+ uuid::Uuid::parse_str(Y).unwrap(),
+ uuid::Uuid::parse_str(X).unwrap(),
+ ]
+ );
+ let data = read_hit(&mut engine, None).await;
+ assert_eq!(property_of(&data)["value"]["stringValue"], json!("b"));
+ });
+}
+
+#[test]
+fn pending_replacement_restores_fields_omitted_by_the_new_intent() {
+ block_on(async {
+ const X: &str = "5470d1c4-e5d8-45d7-a165-afca1331954c";
+ let mut engine = engine_with_base("Status", "todo").await;
+ let variables = mutation_vars("a");
+ let first_data = mutation_response("Transient", "a");
+ engine
+ .begin_optimistic_write(
+ None,
+ BeginOptimisticWrite {
+ uuid: X,
+ query: MUTATION,
+ operation_name: Some("SetEntityProperty"),
+ variables: &variables,
+ data: &first_data,
+ link_patches: &[],
+ revalidations: &[],
+ created_at_ms: 1,
+ },
+ )
+ .await
+ .unwrap();
+ let variables = mutation_vars("b");
+ let replacement_data = json!({
+ "setEntityProperty": {
+ "id": "prop-1",
+ "value": {
+ "__typename": "GraphqlStringPropertyValue",
+ "stringValue": "b"
+ }
+ }
+ });
+ engine
+ .begin_optimistic_write(
+ None,
+ BeginOptimisticWrite {
+ uuid: X,
+ query: MUTATION,
+ operation_name: Some("SetEntityProperty"),
+ variables: &variables,
+ data: &replacement_data,
+ link_patches: &[],
+ revalidations: &[],
+ created_at_ms: 2,
+ },
+ )
+ .await
+ .unwrap();
+
+ let data = read_hit(&mut engine, None).await;
+ assert_eq!(property_of(&data)["displayName"], json!("Status"));
+ assert_eq!(property_of(&data)["value"]["stringValue"], json!("b"));
+ });
+}
+
+#[test]
+fn active_uuid_replacement_is_superseded_and_failed_attempt_is_discarded() {
+ block_on(async {
+ const X: &str = "6483ff81-262e-47cc-a56b-3c6bed971fbe";
+ let mut engine = engine_with_base("Status", "todo").await;
+ let active = begin_value(&mut engine, X, "a", 1).await;
+ let claimed = engine
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner".into(),
+ now_ms: 10,
+ lease_expires_at_ms: 20,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(claimed.queued.id, active);
+ let replacement = begin_value(&mut engine, X, "b", 11).await;
+
+ let queued = engine.storage().load_mutation_queue().await.unwrap();
+ assert_eq!(queued.len(), 2);
+ assert!(queued[0].superseded);
+ assert!(!queued[1].superseded);
+ assert_eq!(queued[1].id, replacement);
+ assert!(
+ engine
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "other".into(),
+ now_ms: 12,
+ lease_expires_at_ms: 100,
+ })
+ .await
+ .unwrap()
+ .is_none()
+ );
+
+ let recovered = engine
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "recovery".into(),
+ now_ms: 20,
+ lease_expires_at_ms: 100,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ assert!(recovered.queued.superseded);
+ let deferred = engine
+ .defer_optimistic_write(
+ active,
+ MutationClaimToken {
+ owner: "recovery".into(),
+ generation: recovered.lease_generation,
+ },
+ 500,
+ "superseded".into(),
+ )
+ .await
+ .unwrap();
+ let DeferOptimisticWriteResult::DiscardedSuperseded(discarded) = deferred else {
+ panic!("superseded attempt was retained")
+ };
+ assert_eq!(discarded.replacement_transaction_id, replacement);
+ let queued = engine.storage().load_mutation_queue().await.unwrap();
+ assert_eq!(queued.len(), 1);
+ assert_eq!(queued[0].id, replacement);
+ let data = read_hit(&mut engine, None).await;
+ assert_eq!(property_of(&data)["value"]["stringValue"], json!("b"));
+ });
+}
+
+#[test]
+fn successful_superseded_attempt_commits_beneath_the_replacement_without_flicker() {
+ block_on(async {
+ const X: &str = "e1fe0a96-37f7-4534-a8fe-613bba700c13";
+ let mut engine = engine_with_base("Status", "todo").await;
+ let active = begin_value(&mut engine, X, "a", 1).await;
+ let (claimed, claim) = claim_head(&mut engine, "runner", 10).await;
+ assert_eq!(claimed, active);
+ let replacement = begin_value(&mut engine, X, "b", 11).await;
+
+ let outcome = engine
+ .commit_optimistic_write_with_outcome(
+ active,
+ claim,
+ MUTATION,
+ Some("SetEntityProperty"),
+ &mutation_vars("a"),
+ &mutation_response("Status", "server-a"),
+ )
+ .await
+ .unwrap();
+ let CommitOptimisticWriteResult::CommittedSuperseded(outcome) = outcome else {
+ panic!("stale response was reported as a current commit")
+ };
+ assert_eq!(outcome.replacement_transaction_id, replacement);
+
+ let queue = engine.storage().load_mutation_queue().await.unwrap();
+ assert_eq!(queue.len(), 1);
+ assert_eq!(queue[0].id, replacement);
+ let data = read_hit(&mut engine, None).await;
+ assert_eq!(property_of(&data)["value"]["stringValue"], json!("b"));
+ assert_eq!(durable_value(&engine).await.as_deref(), Some("server-a"));
+ });
+}
+
+#[test]
+fn invalid_uuid_is_rejected_before_queue_hydration() {
+ block_on(async {
+ let mut engine = engine_with_base("Status", "todo").await;
+ let variables = mutation_vars("doing");
+ let data = mutation_response("Status", "doing");
+ let queue_loads = engine.storage().mutation_queue_load_count();
+ let error = engine
+ .begin_optimistic_write(
+ None,
+ BeginOptimisticWrite {
+ uuid: "not-a-uuid",
+ query: MUTATION,
+ operation_name: Some("SetEntityProperty"),
+ variables: &variables,
+ data: &data,
+ link_patches: &[],
+ revalidations: &[],
+ created_at_ms: 1,
+ },
+ )
+ .await
+ .unwrap_err();
+ assert!(matches!(error, EngineError::InvalidMutationUuid(_)));
+ assert_eq!(engine.storage().mutation_queue_load_count(), queue_loads);
+ });
+}
+
#[test]
fn clear_and_identity_reset_drop_durable_queue() {
block_on(async {
@@ -906,6 +1164,7 @@ fn clear_and_identity_reset_drop_durable_queue() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000019",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("doing"),
diff --git a/crates/client/cache-core/tests/predicate.rs b/crates/client/cache-core/tests/predicate.rs
index 418209c97e..018944d9b7 100644
--- a/crates/client/cache-core/tests/predicate.rs
+++ b/crates/client/cache-core/tests/predicate.rs
@@ -111,11 +111,21 @@ fn optimistic_variables() -> serde_json::Map<String, serde_json::Value> {
async fn try_begin_with_projection(
engine: &mut Engine<InMemoryStorage>,
projection_mutations: Vec<OptimisticProjectionMutation>,
+) -> Result<MutationId, EngineError<std::convert::Infallible>> {
+ let uuid = uuid::Uuid::new_v4().to_string();
+ try_begin_with_projection_uuid(engine, &uuid, projection_mutations).await
+}
+
+async fn try_begin_with_projection_uuid(
+ engine: &mut Engine<InMemoryStorage>,
+ uuid: &str,
+ projection_mutations: Vec<OptimisticProjectionMutation>,
) -> Result<MutationId, EngineError<std::convert::Infallible>> {
engine
.begin_optimistic_write_with_projections(
None,
BeginOptimisticWrite {
+ uuid,
query: OPTIMISTIC_MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &optimistic_variables(),
@@ -929,6 +939,69 @@ fn optimistic_settlement_applies_authoritative_patch_before_shadow_reconciliatio
});
}
+#[test]
+fn pending_uuid_replacement_reassigns_projection_shadow_to_the_new_tail() {
+ pollster::block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ engine
+ .put_records_with_projections(
+ None,
+ vec![(
+ EntityKey::entity("GraphqlSoupDocument", &["doc-1"]),
+ Record::default(),
+ )],
+ vec![ProjectionMutation::Replace(projection("authority"))],
+ )
+ .await
+ .unwrap();
+ let uuid = "e3ac0a53-8789-4925-8664-744630448ebe";
+ let first = try_begin_with_projection_uuid(
+ &mut engine,
+ uuid,
+ vec![OptimisticProjectionMutation::Replace(projection("owner-1"))],
+ )
+ .await
+ .unwrap();
+ let replacement = try_begin_with_projection_uuid(
+ &mut engine,
+ uuid,
+ vec![OptimisticProjectionMutation::Replace(projection("owner-2"))],
+ )
+ .await
+ .unwrap();
+
+ assert!(replacement > first);
+ let queue = engine.storage().load_mutation_queue().await.unwrap();
+ assert_eq!(
+ queue.iter().map(|row| row.id).collect::<Vec<_>>(),
+ [replacement]
+ );
+ let shadow = engine
+ .storage()
+ .load_optimistic_projections(&[record_key()])
+ .await
+ .unwrap()
+ .pop()
+ .flatten()
+ .unwrap();
+ assert_eq!(shadow.owner, replacement);
+ assert_eq!(
+ engine
+ .query_predicate_index(&query("owner-2"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Optimistic(vec![record_key()])
+ );
+ assert_eq!(
+ engine
+ .query_predicate_index(&query("owner-1"))
+ .await
+ .unwrap(),
+ PredicateQueryResult::Optimistic(Vec::new())
+ );
+ });
+}
+
#[test]
fn optimistic_deletion_overfetches_authoritative_replacement_candidates() {
pollster::block_on(async {
diff --git a/crates/client/cache-core/tests/query_inspection.rs b/crates/client/cache-core/tests/query_inspection.rs
index ed318404ad..fe52308e1d 100644
--- a/crates/client/cache-core/tests/query_inspection.rs
+++ b/crates/client/cache-core/tests/query_inspection.rs
@@ -4,16 +4,15 @@ use cache_core::engine::{BeginOptimisticWrite, Engine};
use cache_core::link_patch::{
LinkOperation, LinkPathSegment, ListItemByScalar, OptimisticLinkPatch,
};
-use cache_core::predicate::ProjectionMutation;
+use cache_core::predicate::{OptimisticUpsertReconciliation, ProjectionMutation};
use cache_core::query_inspection::{MAX_INSPECTED_VARIANTS, QueryInspection, QueryInspectionError};
use cache_core::queue::{
- ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,
- QueuedMutation,
+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationUpsertResult,
+ NewQueuedMutation, QueuedMutation,
};
use cache_core::store::{InMemoryStorage, Storage};
use cache_core::value::{EntityKey, Record};
use pollster::block_on;
-use predicate_index::PendingOptimisticProjection;
use serde_json::{Value as Json, json};
const GROUP_QUERY: &str = r#"
@@ -120,13 +119,14 @@ impl Storage for OwnerOnlyStorage {
self.0.delete_batch(keys).await
}
- async fn enqueue_mutation_with_shadow(
+ async fn upsert_mutation_with_shadow(
&mut self,
entry: NewQueuedMutation,
- projections: Vec<PendingOptimisticProjection>,
- ) -> Result<MutationId, Self::Error> {
+ now_ms: i64,
+ reconciliation: OptimisticUpsertReconciliation,
+ ) -> Result<MutationUpsertResult, Self::Error> {
self.0
- .enqueue_mutation_with_shadow(entry, projections)
+ .upsert_mutation_with_shadow(entry, now_ms, reconciliation)
.await
}
@@ -497,6 +497,7 @@ mutation SetEntityProperty($input: SetEntityPropertyInput!) {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000002",
query: mutation,
operation_name: Some("SetEntityProperty"),
variables: &mutation_variables,
diff --git a/crates/client/cache-core/tests/record_selection.rs b/crates/client/cache-core/tests/record_selection.rs
index fb4f287f04..0ea87ea611 100644
--- a/crates/client/cache-core/tests/record_selection.rs
+++ b/crates/client/cache-core/tests/record_selection.rs
@@ -287,6 +287,7 @@ fn merges_optimistic_updates_with_cold_linked_bases() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000003",
query: mutation,
operation_name: Some("SetProperty"),
variables: &variables,
@@ -346,6 +347,7 @@ fn includes_optimistic_only_records() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000004",
query: mutation,
operation_name: Some("SetProperty"),
variables: &variables,
diff --git a/crates/client/cache-core/tests/search.rs b/crates/client/cache-core/tests/search.rs
index e897c58404..6c1fcdd1c9 100644
--- a/crates/client/cache-core/tests/search.rs
+++ b/crates/client/cache-core/tests/search.rs
@@ -252,6 +252,7 @@ fn optimistic_records_explicitly_overlay_the_durable_search_catalog() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000000020",
query: RENAME,
operation_name: Some("Rename"),
variables: &rename_variables,
diff --git a/crates/client/cache-turso/Cargo.toml b/crates/client/cache-turso/Cargo.toml
index dd23da10d2..a4d1f122c4 100644
--- a/crates/client/cache-turso/Cargo.toml
+++ b/crates/client/cache-turso/Cargo.toml
@@ -13,6 +13,7 @@ cache-core = { path = "../cache-core" }
maybe_send = { path = "../../maybe_send" }
predicate-index = { path = "../../predicate_index" }
thiserror = { workspace = true }
+uuid = { workspace = true }
[target.'cfg(target_arch = "wasm32")'.dependencies]
turso-opfs = { path = "../turso-opfs" }
diff --git a/crates/client/cache-turso/src/storage.rs b/crates/client/cache-turso/src/storage.rs
index 3ef97f630c..c3a5c27933 100644
--- a/crates/client/cache-turso/src/storage.rs
+++ b/crates/client/cache-turso/src/storage.rs
@@ -5,27 +5,31 @@ use cache_core::codec::{
cache_namespace, decode_record, decode_record_updates, encode_record, encode_record_updates,
};
use cache_core::predicate::{
- OptimisticShadowReconciliation, PredicateIndexStorage, PredicateQueryResult,
- ProjectionIncompleteKind, ProjectionMutation, ProjectionState,
- apply_authoritative_projection_patch,
+ OptimisticShadowReconciliation, OptimisticUpsertReconciliation, PredicateIndexStorage,
+ PredicateQueryResult, ProjectionIncompleteKind, ProjectionMutation, ProjectionState,
+ StagedOptimisticProjectionOwner, apply_authoritative_projection_patch,
};
use cache_core::queue::{
- ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationRequest,
- NewQueuedMutation, PersistedOptimisticLayer, QueuedMutation, StoredMutation,
+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationQueueSnapshot,
+ MutationRequest, MutationUpsertKind, MutationUpsertResult, NewQueuedMutation,
+ PersistedOptimisticLayer, QueuedMutation, StoredMutation,
};
use cache_core::search::{SearchCursor, SearchDocument, SearchProfile, project_search_documents};
use cache_core::store::{QueueDiagnostics, QueueDiagnosticsAvailability, Storage};
use cache_core::value::{EntityKey, Record};
use predicate_index::{
- EffectiveOptimisticProjection, OptimisticProjectionState, OptimisticUncertainty,
- PendingOptimisticProjection, PredicateExpr, Profile, RangeBound,
- RecordKey as PredicateRecordKey, SortDirection, Token, ValidatedIndexQuery,
+ EffectiveOptimisticProjection, OptimisticProjectionState, OptimisticUncertainty, PredicateExpr,
+ Profile, RangeBound, RecordKey as PredicateRecordKey, SortDirection, Token,
+ ValidatedIndexQuery,
};
-use std::collections::{BTreeSet, HashMap, HashSet};
+use std::collections::{BTreeSet, HashMap};
use std::sync::Arc;
use std::sync::atomic::{AtomicU8, Ordering};
use turso_core::{Connection, Numeric, Value};
+#[cfg(test)]
+use predicate_index::PendingOptimisticProjection;
+
#[cfg(not(target_arch = "wasm32"))]
use std::io::ErrorKind;
#[cfg(not(target_arch = "wasm32"))]
@@ -43,7 +47,7 @@ use turso_opfs::{
};
/// Frozen storage schema version, independent of cache postcard versions.
-pub const STORAGE_SCHEMA_VERSION: u32 = 10;
+pub const STORAGE_SCHEMA_VERSION: u32 = 11;
/// Coarse outcome of validating a Turso database.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
@@ -54,13 +58,14 @@ pub enum TursoStorageOpenOutcome {
OpenedNew,
}
-const CREATE_SCHEMA: [&str; 27] = [
+const CREATE_SCHEMA: [&str; 28] = [
"CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)",
"CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL, value BLOB NOT NULL, PRIMARY KEY (__typename, id))",
"CREATE TABLE search_documents (profile TEXT NOT NULL, __typename TEXT NOT NULL, id TEXT NOT NULL, bucket TEXT NOT NULL, search_text TEXT NOT NULL, timestamp_ms INTEGER NOT NULL, source_hash TEXT NOT NULL, PRIMARY KEY (profile, __typename, id))",
"CREATE INDEX search_documents_browse_idx ON search_documents(profile, bucket, timestamp_ms DESC, __typename, id)",
- "CREATE TABLE 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 mutation_queue (id INTEGER PRIMARY KEY AUTOINCREMENT, uuid TEXT NOT NULL, superseded INTEGER NOT NULL DEFAULT 0, 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 INDEX mutation_queue_created_at_ms_idx ON mutation_queue(created_at_ms)",
+ "CREATE UNIQUE INDEX mutation_queue_current_uuid_idx ON mutation_queue(uuid) WHERE superseded = 0",
"CREATE TABLE 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)",
"CREATE TABLE index_documents (id INTEGER PRIMARY KEY, record_key TEXT NOT NULL, profile TEXT NOT NULL, partition TEXT NOT NULL, state INTEGER NOT NULL)",
"CREATE UNIQUE INDEX index_documents_record_key_idx ON index_documents(record_key)",
@@ -105,10 +110,10 @@ const INTEGER_FACT_INSERT: &str =
"INSERT INTO integer_facts (document_id, attribute, value) VALUES (?1, ?2, ?3)";
const SORT_FACT_INSERT: &str =
"INSERT INTO sort_facts (document_id, attribute, value) VALUES (?1, ?2, ?3)";
-const QUEUE_INSERT: &str = "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)";
+const QUEUE_INSERT: &str = "INSERT INTO mutation_queue (uuid, superseded, 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, 0, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12)";
const LAYER_INSERT: &str = "INSERT INTO optimistic_layers (mutation_id, optimistic_data_json, normalized_updates) VALUES (?1, ?2, ?3)";
-const QUEUE_SELECT: &str = "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 AS m LEFT JOIN optimistic_layers AS o ON o.mutation_id = m.id ORDER BY m.id ASC";
-const QUEUE_HEAD_SELECT: &str = "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 AS m LEFT JOIN optimistic_layers AS o ON o.mutation_id = m.id ORDER BY m.id ASC LIMIT 1";
+const QUEUE_SELECT: &str = "SELECT m.id, m.uuid, m.superseded, 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 AS m LEFT JOIN optimistic_layers AS o ON o.mutation_id = m.id ORDER BY m.id ASC";
+const QUEUE_HEAD_SELECT: &str = "SELECT m.id, m.uuid, m.superseded, 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 AS m LEFT JOIN optimistic_layers AS o ON o.mutation_id = m.id ORDER BY m.id ASC LIMIT 1";
const ORPHAN_LAYER_SELECT: &str = "SELECT o.mutation_id FROM optimistic_layers AS o LEFT JOIN mutation_queue AS m ON m.id = o.mutation_id WHERE m.id IS NULL LIMIT 1";
const ANY_LAYER_SELECT: &str = "SELECT mutation_id FROM optimistic_layers LIMIT 1";
const CLAIM_SELECT: &str = "SELECT lease_owner, lease_generation FROM mutation_queue WHERE id = ?1";
@@ -245,6 +250,7 @@ impl TursoStorage {
&connection,
QUEUE_INSERT,
vec![
+ text("00000000-0000-4000-8000-000000000001"),
text("mutation BrowserTestCorrupt { __typename }"),
Value::Null,
text("{}"),
@@ -935,24 +941,70 @@ impl Storage for TursoStorage {
self.latch_result(result)
}
- async fn enqueue_mutation_with_shadow(
+ async fn upsert_mutation_with_shadow(
&mut self,
entry: NewQueuedMutation,
- projections: Vec<PendingOptimisticProjection>,
- ) -> Result<MutationId, Self::Error> {
+ now_ms: i64,
+ reconciliation: OptimisticUpsertReconciliation,
+ ) -> Result<MutationUpsertResult, Self::Error> {
self.require_healthy()?;
let result = (|| {
- validate_pending_optimistic_projections(&projections)?;
- let mutation_values = mutation_values(&entry.mutation)?;
+ reconciliation
+ .validate()
+ .map_err(|_| TursoStorageError::InvalidInput)?;
+ let mutation_values = mutation_values(&entry)?;
let updates = encode_record_updates(&entry.optimistic.normalized_updates);
let connection = self.connection();
driver::write_transaction(&connection, || {
+ if let Some(expected) = &reconciliation.expected_queue
+ && !queue_snapshot_matches(&connection, expected)?
+ {
+ return Err(TursoStorageError::InvalidInput);
+ }
+ let collision = driver::query(
+ &connection,
+ "SELECT id, lease_expires_at_ms FROM mutation_queue WHERE uuid = ?1 AND superseded = 0",
+ vec![text(&entry.uuid.to_string())],
+ )?;
+ let kind = match collision.as_slice() {
+ [] => MutationUpsertKind::Inserted,
+ [row] if row.len() == 2 => {
+ let existing = mutation_id_from_row(required_i64(row, 0)?)?;
+ if nullable_i64(row, 1)?.is_some_and(|expiry| expiry > now_ms) {
+ require_changed(
+ driver::execute(
+ &connection,
+ "UPDATE mutation_queue SET superseded = 1 WHERE id = ?1 AND superseded = 0",
+ vec![Value::from_i64(mutation_id_to_sql(existing)?)],
+ )?,
+ 1,
+ )?;
+ MutationUpsertKind::AppendedAfterActive {
+ active_id: existing,
+ }
+ } else {
+ require_changed(
+ driver::execute(
+ &connection,
+ "DELETE FROM mutation_queue WHERE id = ?1 AND superseded = 0",
+ vec![Value::from_i64(mutation_id_to_sql(existing)?)],
+ )?,
+ 1,
+ )?;
+ MutationUpsertKind::ReplacedPending {
+ removed_id: existing,
+ }
+ }
+ }
+ _ => return Err(invariant()),
+ };
+ self.fault_after(TestFaultSite::Enqueue, 0)?;
require_changed(
driver::execute(&connection, QUEUE_INSERT, mutation_values)?,
1,
)?;
- self.fault_after(TestFaultSite::Enqueue, 0)?;
let id = mutation_id_from_row(connection.last_insert_rowid())?;
+ self.fault_after(TestFaultSite::Enqueue, 1)?;
require_changed(
driver::execute(
&connection,
@@ -965,10 +1017,11 @@ impl Storage for TursoStorage {
)?,
1,
)?;
- write_pending_optimistic_projections(&connection, id, projections, |index| {
- self.fault_after(TestFaultSite::Enqueue, index + 1)
+ self.fault_after(TestFaultSite::Enqueue, 2)?;
+ write_upsert_shadow_reconciliation(&connection, id, reconciliation, |index| {
+ self.fault_after(TestFaultSite::Enqueue, index + 3)
})?;
- Ok(id)
+ Ok(MutationUpsertResult { id, kind })
})
})();
self.latch_result(result)
@@ -1009,6 +1062,8 @@ impl Storage for TursoStorage {
let optimistic = parsed.optimistic.ok_or_else(invariant)?;
queue.push(QueuedMutation {
id: parsed.id,
+ uuid: parsed.uuid,
+ superseded: parsed.superseded,
mutation: parsed.mutation,
optimistic,
});
@@ -1104,6 +1159,8 @@ impl Storage for TursoStorage {
Ok(Some(ClaimedMutation {
queued: QueuedMutation {
id: parsed.id,
+ uuid: parsed.uuid,
+ superseded: parsed.superseded,
mutation: parsed.mutation,
optimistic,
},
@@ -1429,21 +1486,6 @@ impl PredicateIndexStorage for TursoStorage {
}
}
-fn validate_pending_optimistic_projections(
- projections: &[PendingOptimisticProjection],
-) -> Result<(), TursoStorageError> {
- let mut keys = HashSet::with_capacity(projections.len());
- for projection in projections {
- projection
- .validate()
- .map_err(|_| TursoStorageError::InvalidInput)?;
- if !keys.insert(projection.state.record_key()) {
- return Err(TursoStorageError::InvalidInput);
- }
- }
- Ok(())
-}
-
fn validate_shadow_reconciliation(
id: MutationId,
reconciliation: &OptimisticShadowReconciliation,
@@ -1453,6 +1495,35 @@ fn validate_shadow_reconciliation(
.map_err(|_| TursoStorageError::InvalidInput)
}
+fn queue_snapshot_matches(
+ connection: &Arc<Connection>,
+ expected: &[MutationQueueSnapshot],
+) -> Result<bool, TursoStorageError> {
+ let rows = driver::query(
+ connection,
+ "SELECT id, uuid, superseded, lease_owner, lease_generation, lease_expires_at_ms, next_attempt_at_ms FROM mutation_queue ORDER BY id ASC",
+ Vec::new(),
+ )?;
+ if rows.len() != expected.len() {
+ return Ok(false);
+ }
+ for (row, expected) in rows.iter().zip(expected) {
+ if row.len() != 7
+ || mutation_id_from_row(required_i64(row, 0)?)? != expected.id
+ || parse_uuid(&required_text(row, 1)?)? != expected.uuid
+ || parse_boolean(row, 2)? != expected.superseded
+ || nullable_text(row, 3)? != expected.lease_owner
+ || u64::try_from(required_i64(row, 4)?).map_err(|_| invariant())?
+ != expected.lease_generation
+ || nullable_i64(row, 5)? != expected.lease_expires_at_ms
+ || nullable_i64(row, 6)? != expected.next_attempt_at_ms
+ {
+ return Ok(false);
+ }
+ }
+ Ok(true)
+}
+
fn queue_identity_matches(
connection: &Arc<Connection>,
expected: &[MutationId],
@@ -1493,16 +1564,26 @@ fn write_shadow_reconciliation(
Ok(())
}
-fn write_pending_optimistic_projections(
+fn write_upsert_shadow_reconciliation(
connection: &Arc<Connection>,
- owner: MutationId,
- projections: Vec<PendingOptimisticProjection>,
+ enqueued: MutationId,
+ reconciliation: OptimisticUpsertReconciliation,
mut after_write: impl FnMut(usize) -> Result<(), TursoStorageError>,
) -> Result<(), TursoStorageError> {
- let owner = mutation_id_to_sql(owner)?;
- for (index, projection) in projections.into_iter().enumerate() {
- delete_optimistic_projection(connection, projection.state.record_key())?;
- insert_optimistic_projection(connection, owner, projection.state, projection.uncertainty)?;
+ for key in &reconciliation.affected_keys {
+ delete_optimistic_projection(connection, key)?;
+ }
+ for (index, replacement) in reconciliation.replacements.into_iter().enumerate() {
+ let owner = match replacement.owner {
+ StagedOptimisticProjectionOwner::Existing(owner) => owner,
+ StagedOptimisticProjectionOwner::Enqueued => enqueued,
+ };
+ insert_optimistic_projection(
+ connection,
+ mutation_id_to_sql(owner)?,
+ replacement.state,
+ replacement.uncertainty,
+ )?;
after_write(index)?;
}
Ok(())
@@ -2680,6 +2761,20 @@ const MUTATION_COLUMNS: &[ColumnSpec] = &[
default_zero: false,
primary_key_position: 1,
},
+ ColumnSpec {
+ name: "uuid",
+ declared_type: "TEXT",
+ not_null: true,
+ default_zero: false,
+ primary_key_position: 0,
+ },
+ ColumnSpec {
+ name: "superseded",
+ declared_type: "INTEGER",
+ not_null: true,
+ default_zero: true,
+ primary_key_position: 0,
+ },
ColumnSpec {
name: "query",
declared_type: "TEXT",
@@ -3077,6 +3172,7 @@ fn validate_allowed_schema_objects(connection: &Arc<Connection>) -> Result<(), T
"integer_facts_lookup_idx",
"index_documents_record_key_idx",
"mutation_queue_created_at_ms_idx",
+ "mutation_queue_current_uuid_idx",
"optimistic_exact_facts_lookup_idx",
"optimistic_index_documents_owner_idx",
"optimistic_index_documents_record_key_idx",
@@ -3334,41 +3430,87 @@ fn validate_mutation_queue_indexes(connection: &Arc<Connection>) -> Result<(), T
Vec::new(),
)
.map_err(TursoStorageError::initialization)?;
- let [row] = rows.as_slice() else {
+ if rows.len() != 2 {
+ return Err(compatibility());
+ }
+ let created = rows
+ .iter()
+ .find(|row| {
+ required_text(row, 1).ok().as_deref() == Some("mutation_queue_created_at_ms_idx")
+ })
+ .ok_or_else(compatibility)?;
+ let current = rows
+ .iter()
+ .find(|row| {
+ required_text(row, 1).ok().as_deref() == Some("mutation_queue_current_uuid_idx")
+ })
+ .ok_or_else(compatibility)?;
+ if created.len() != 5
+ || required_i64(created, 2).ok() != Some(0)
+ || required_text(created, 3).ok().as_deref() != Some("c")
+ || required_i64(created, 4).ok() != Some(0)
+ || current.len() != 5
+ || required_i64(current, 2).ok() != Some(1)
+ || required_text(current, 3).ok().as_deref() != Some("c")
+ || required_i64(current, 4).ok() != Some(1)
+ {
+ return Err(compatibility());
+ }
+ validate_mutation_index_columns(
+ connection,
+ "mutation_queue_created_at_ms_idx",
+ 13,
+ "created_at_ms",
+ )?;
+ validate_mutation_index_columns(connection, "mutation_queue_current_uuid_idx", 1, "uuid")?;
+ let sql = driver::query(
+ connection,
+ "SELECT sql FROM sqlite_schema WHERE type = 'index' AND name = 'mutation_queue_current_uuid_idx'",
+ Vec::new(),
+ )
+ .map_err(TursoStorageError::initialization)?;
+ let [row] = sql.as_slice() else {
return Err(compatibility());
};
- if row.len() != 5
- || required_i64(row, 0).ok() != Some(0)
- || required_text(row, 1).ok().as_deref() != Some("mutation_queue_created_at_ms_idx")
- || required_i64(row, 2).ok() != Some(0)
- || required_text(row, 3).ok().as_deref() != Some("c")
- || required_i64(row, 4).ok() != Some(0)
+ let normalized = required_text(row, 0)
+ .map_err(|_| compatibility())?
+ .split_whitespace()
+ .collect::<Vec<_>>()
+ .join(" ")
+ .to_ascii_lowercase();
+ if normalized
+ != "create unique index mutation_queue_current_uuid_idx on mutation_queue (uuid) where superseded = 0"
{
return Err(compatibility());
}
- let index_rows = driver::query(
+ Ok(())
+}
+
+fn validate_mutation_index_columns(
+ connection: &Arc<Connection>,
+ index: &str,
+ column: i64,
+ name: &str,
+) -> Result<(), TursoStorageError> {
+ let rows = driver::query(
connection,
- "PRAGMA index_xinfo('mutation_queue_created_at_ms_idx')",
+ &format!("PRAGMA index_xinfo('{index}')"),
Vec::new(),
)
.map_err(TursoStorageError::initialization)?;
- let [created_at, rowid] = index_rows.as_slice() else {
+ let [key, rowid] = rows.as_slice() else {
return Err(compatibility());
};
- if created_at.len() != 6
- || required_i64(created_at, 0).ok() != Some(0)
- || required_i64(created_at, 1).ok() != Some(11)
- || required_text(created_at, 2).ok().as_deref() != Some("created_at_ms")
- || required_i64(created_at, 3).ok() != Some(0)
- || required_text(created_at, 4).ok().as_deref() != Some("BINARY")
- || required_i64(created_at, 5).ok() != Some(1)
+ if key.len() != 6
+ || required_i64(key, 0).ok() != Some(0)
+ || required_i64(key, 1).ok() != Some(column)
+ || required_text(key, 2).ok().as_deref() != Some(name)
+ || required_i64(key, 3).ok() != Some(0)
+ || required_text(key, 4).ok().as_deref() != Some("BINARY")
+ || required_i64(key, 5).ok() != Some(1)
|| rowid.len() != 6
|| required_i64(rowid, 0).ok() != Some(1)
|| required_i64(rowid, 1).ok() != Some(-1)
- || !rowid.get(2).is_some_and(|value| {
- matches!(value, Value::Null)
- || matches!(value, Value::Text(text) if text.as_str().is_empty())
- })
|| required_i64(rowid, 3).ok() != Some(0)
|| required_text(rowid, 4).ok().as_deref() != Some("BINARY")
|| required_i64(rowid, 5).ok() != Some(0)
@@ -4016,8 +4158,10 @@ fn parse_search_document(
})
}
-fn mutation_values(mutation: &StoredMutation) -> Result<Vec<Value>, TursoStorageError> {
+fn mutation_values(entry: &NewQueuedMutation) -> Result<Vec<Value>, TursoStorageError> {
+ let mutation = &entry.mutation;
Ok(vec![
+ text(&entry.uuid.to_string()),
text(&mutation.request.query),
optional_text(mutation.request.operation_name.as_deref()),
text(&mutation.request.variables_json),
@@ -4034,44 +4178,60 @@ fn mutation_values(mutation: &StoredMutation) -> Result<Vec<Value>, TursoStorage
struct ParsedQueueRow {
id: MutationId,
+ uuid: uuid::Uuid,
+ superseded: bool,
mutation: StoredMutation,
optimistic: Option<PersistedOptimisticLayer>,
}
fn parse_queue_row(row: &[Value]) -> Result<ParsedQueueRow, TursoStorageError> {
- if row.len() != 14 {
+ if row.len() != 16 {
return Err(invariant());
}
- let optimistic = match (&row[12], &row[13]) {
+ let optimistic = match (&row[14], &row[15]) {
(Value::Null, Value::Null) => None,
(Value::Null, _) | (_, Value::Null) => return Err(invariant()),
_ => Some(PersistedOptimisticLayer {
- optimistic_data_json: required_text(row, 12)?,
- normalized_updates: decode_record_updates(&required_blob(row, 13)?)
+ optimistic_data_json: required_text(row, 14)?,
+ normalized_updates: decode_record_updates(&required_blob(row, 15)?)
.map_err(|_| TursoStorageError::reset(PhysicalResetReason::Codec))?,
}),
};
Ok(ParsedQueueRow {
id: mutation_id_from_row(required_i64(row, 0)?)?,
+ uuid: parse_uuid(&required_text(row, 1)?)?,
+ superseded: parse_boolean(row, 2)?,
mutation: StoredMutation {
request: MutationRequest {
- query: required_text(row, 1)?,
- operation_name: nullable_text(row, 2)?,
- variables_json: required_text(row, 3)?,
- identity: nullable_text(row, 4)?,
+ query: required_text(row, 3)?,
+ operation_name: nullable_text(row, 4)?,
+ variables_json: required_text(row, 5)?,
+ identity: nullable_text(row, 6)?,
},
- attempt_count: u32::try_from(required_i64(row, 5)?).map_err(|_| invariant())?,
- next_attempt_at_ms: nullable_i64(row, 6)?,
- lease_owner: nullable_text(row, 7)?,
- lease_generation: u64::try_from(required_i64(row, 8)?).map_err(|_| invariant())?,
- lease_expires_at_ms: nullable_i64(row, 9)?,
- last_error: nullable_text(row, 10)?,
- created_at_ms: required_i64(row, 11)?,
+ attempt_count: u32::try_from(required_i64(row, 7)?).map_err(|_| invariant())?,
+ next_attempt_at_ms: nullable_i64(row, 8)?,
+ lease_owner: nullable_text(row, 9)?,
+ lease_generation: u64::try_from(required_i64(row, 10)?).map_err(|_| invariant())?,
+ lease_expires_at_ms: nullable_i64(row, 11)?,
+ last_error: nullable_text(row, 12)?,
+ created_at_ms: required_i64(row, 13)?,
},
optimistic,
})
}
+fn parse_uuid(value: &str) -> Result<uuid::Uuid, TursoStorageError> {
+ uuid::Uuid::parse_str(value).map_err(|_| invariant())
+}
+
+fn parse_boolean(row: &[Value], index: usize) -> Result<bool, TursoStorageError> {
+ match required_i64(row, index)? {
+ 0 => Ok(false),
+ 1 => Ok(true),
+ _ => Err(invariant()),
+ }
+}
+
fn claim_is_current(
connection: &Arc<Connection>,
id: i64,
diff --git a/crates/client/cache-turso/src/storage/browser_test.rs b/crates/client/cache-turso/src/storage/browser_test.rs
index cf236c3486..f668e7059d 100644
--- a/crates/client/cache-turso/src/storage/browser_test.rs
+++ b/crates/client/cache-turso/src/storage/browser_test.rs
@@ -10,6 +10,36 @@ fn key(value: &str) -> EntityKey<'static> {
EntityKey(value.to_owned().into())
}
+#[cfg(feature = "browser-test-hooks")]
+#[wasm_bindgen_test(async)]
+async fn browser_corrupt_queue_hook_preserves_queue_bindings() {
+ let owner = OpfsOwner::acquire("cache-turso-browser-corrupt-queue.db")
+ .await
+ .unwrap()
+ .recovery_wipe()
+ .await
+ .unwrap();
+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {
+ panic!("recovery wipe must produce a complete fresh pair")
+ };
+ let mut storage =
+ TursoStorage::from_opfs_session(session.connect().unwrap(), "browser-corrupt-queue")
+ .unwrap();
+ storage.browser_test_corrupt_queue_payload().unwrap();
+ assert_eq!(
+ storage
+ .load_mutation_queue()
+ .await
+ .unwrap_err()
+ .physical_reset_reason(),
+ Some(PhysicalResetReason::Codec)
+ );
+ let TursoStorageCloseOutcome::ResetRequired(closed) = storage.try_close().unwrap() else {
+ panic!("corrupt queue payload must require reset")
+ };
+ closed.reset().await.unwrap().release().await.unwrap();
+}
+
#[wasm_bindgen_test(async)]
async fn runtime_corruption_closes_reset_only_and_replacement_is_empty() {
let owner = OpfsOwner::acquire("cache-turso-wp06-runtime-reset.db")
diff --git a/crates/client/cache-turso/src/storage/test.rs b/crates/client/cache-turso/src/storage/test.rs
index 4f7ef448e3..3e0a68f73c 100644
--- a/crates/client/cache-turso/src/storage/test.rs
+++ b/crates/client/cache-turso/src/storage/test.rs
@@ -23,6 +23,7 @@ fn record(value: &str) -> Record {
fn queued(label: &str) -> NewQueuedMutation {
NewQueuedMutation {
+ uuid: uuid::Uuid::new_v4(),
mutation: StoredMutation::new(
MutationRequest {
query: format!("mutation {label} {{ update {{ id }} }}"),
@@ -312,7 +313,7 @@ fn queue_diagnostics_use_the_created_at_covering_index_at_scale() {
let storage = TursoStorage::open_in_memory("queue-diagnostics-plan").unwrap();
raw_execute(
&storage,
- "WITH RECURSIVE values_to_insert(value) AS (VALUES(1) UNION ALL SELECT value + 1 FROM values_to_insert WHERE value < 10000) INSERT INTO mutation_queue (query, variables_json, created_at_ms) SELECT 'mutation Scale { scale }', '{}', 10001 - value FROM values_to_insert",
+ "WITH RECURSIVE values_to_insert(value) AS (VALUES(1) UNION ALL SELECT value + 1 FROM values_to_insert WHERE value < 10000) INSERT INTO mutation_queue (uuid, query, variables_json, created_at_ms) SELECT printf('00000000-0000-4000-8000-%012d', value), 'mutation Scale { scale }', '{}', 10001 - value FROM values_to_insert",
Vec::new(),
);
let plan = driver::query(
@@ -412,6 +413,44 @@ fn fresh_schema_metadata_foreign_keys_quick_check_and_cascade_are_real() {
});
}
+#[test]
+fn partial_uuid_index_rejects_two_current_rows_but_allows_superseded_history() {
+ block_on(async {
+ let mut storage = TursoStorage::open_in_memory("partial-current-uuid-index").unwrap();
+ let uuid = uuid::Uuid::new_v4();
+ let mut first = queued("First");
+ first.uuid = uuid;
+ let first_id = storage.enqueue_mutation(first).await.unwrap();
+
+ assert!(
+ driver::execute(
+ &storage.connection(),
+ "INSERT INTO mutation_queue (uuid, query, variables_json, created_at_ms) VALUES (?1, ?2, ?3, ?4)",
+ vec![text(&uuid.to_string()), text("mutation Duplicate { x }"), text("{}"), Value::from_i64(2)],
+ )
+ .is_err()
+ );
+ raw_execute(
+ &storage,
+ "UPDATE mutation_queue SET superseded = 1 WHERE id = ?1",
+ vec![Value::from_i64(mutation_id_to_sql(first_id).unwrap())],
+ );
+ assert_eq!(
+ raw_execute(
+ &storage,
+ "INSERT INTO mutation_queue (uuid, query, variables_json, created_at_ms) VALUES (?1, ?2, ?3, ?4)",
+ vec![
+ text(&uuid.to_string()),
+ text("mutation Current { x }"),
+ text("{}"),
+ Value::from_i64(3)
+ ],
+ ),
+ 1
+ );
+ });
+}
+
#[test]
fn enqueue_atomically_replaces_one_effective_shadow_per_key() {
block_on(async {
@@ -816,6 +855,10 @@ fn every_metadata_mismatch_and_missing_schema_requests_physical_reset() {
"queue-diagnostics-index",
"DROP INDEX mutation_queue_created_at_ms_idx",
),
+ (
+ "queue-current-uuid-index",
+ "DROP INDEX mutation_queue_current_uuid_idx",
+ ),
("search-table", "DROP TABLE search_documents"),
("search-index", "DROP INDEX search_documents_browse_idx"),
] {
@@ -872,6 +915,8 @@ fn semantically_equivalent_schema_formatting_is_accepted_on_reopen() {
)"#,
r#"create table 'mutation_queue' (
'id' integer /* AUTOINCREMENT UNIQUE CHECK COLLATE */ primary key autoincrement,
+ "uuid" text not null,
+ [superseded] integer default ((0)) not null,
"query" text not null,
[operation_name] text,
`variables_json` text not null,
@@ -885,6 +930,7 @@ fn semantically_equivalent_schema_formatting_is_accepted_on_reopen() {
"created_at_ms" integer not null
)"#,
"CREATE INDEX mutation_queue_created_at_ms_idx ON mutation_queue(created_at_ms)",
+ "CREATE UNIQUE INDEX mutation_queue_current_uuid_idx ON mutation_queue(uuid) WHERE superseded = 0",
r#"create table `optimistic_layers` (
`mutation_id` integer primary key,
[optimistic_data_json] text not null,
@@ -1175,8 +1221,9 @@ fn corrupt_keys_blobs_queue_relationships_and_numerics_request_reset() {
let storage = TursoStorage::open_in_memory("missing-layer").unwrap();
raw_execute(
&storage,
- "INSERT INTO mutation_queue (query, variables_json, created_at_ms) VALUES (?1, ?2, ?3)",
+ "INSERT INTO mutation_queue (uuid, query, variables_json, created_at_ms) VALUES (?1, ?2, ?3, ?4)",
vec![
+ text("00000000-0000-4000-8000-000000000001"),
text("mutation Missing { x }"),
text("{}"),
Value::from_i64(0),
@@ -1257,14 +1304,36 @@ fn corrupt_keys_blobs_queue_relationships_and_numerics_request_reset() {
);
}
+ for (name, assignment) in [
+ ("invalid-uuid", "uuid = 'not-a-uuid'"),
+ ("invalid-superseded", "superseded = 2"),
+ ] {
+ let mut storage = TursoStorage::open_in_memory(name).unwrap();
+ let id = storage.enqueue_mutation(queued(name)).await.unwrap();
+ raw_execute(
+ &storage,
+ &format!("UPDATE mutation_queue SET {assignment} WHERE id = ?1"),
+ vec![Value::from_i64(mutation_id_to_sql(id).unwrap())],
+ );
+ assert_eq!(
+ storage
+ .load_mutation_queue()
+ .await
+ .unwrap_err()
+ .physical_reset_reason(),
+ Some(PhysicalResetReason::Invariant)
+ );
+ }
+
for invalid_id in [0, -1] {
let storage =
TursoStorage::open_in_memory(&format!("invalid-id-{invalid_id}")).unwrap();
raw_execute(
&storage,
- "INSERT INTO mutation_queue (id, query, variables_json, created_at_ms) VALUES (?1, ?2, ?3, ?4)",
+ "INSERT INTO mutation_queue (id, uuid, query, variables_json, created_at_ms) VALUES (?1, ?2, ?3, ?4, ?5)",
vec![
Value::from_i64(invalid_id),
+ text("00000000-0000-4000-8000-000000000002"),
text("mutation Invalid { x }"),
text("{}"),
Value::from_i64(0),
@@ -1590,6 +1659,54 @@ fn record_and_projection_patch_roll_back_together_on_storage_fault() {
});
}
+#[test]
+fn every_uuid_upsert_fault_rolls_back_queue_layer_and_shadow_changes() {
+ block_on(async {
+ for fault_index in 0..=3 {
+ let mut storage =
+ TursoStorage::open_in_memory(&format!("uuid-upsert-fault-{fault_index}")).unwrap();
+ let uuid = uuid::Uuid::new_v4();
+ let mut first = queued("First");
+ first.uuid = uuid;
+ storage
+ .enqueue_mutation_with_shadow(
+ first,
+ vec![pending_projection("Thing:1", "user-1", 10)],
+ )
+ .await
+ .unwrap();
+ let queue_before = storage.load_mutation_queue().await.unwrap();
+ let shadow_before = storage
+ .load_optimistic_projections(&[PredicateRecordKey::new("Thing:1").unwrap()])
+ .await
+ .unwrap();
+
+ let mut replacement = queued("Replacement");
+ replacement.uuid = uuid;
+ storage.arm_fault(TestFault::After {
+ site: TestFaultSite::Enqueue,
+ index: fault_index,
+ });
+ storage
+ .enqueue_mutation_with_shadow(
+ replacement,
+ vec![pending_projection("Thing:1", "user-2", 20)],
+ )
+ .await
+ .unwrap_err();
+
+ assert_eq!(storage.load_mutation_queue().await.unwrap(), queue_before);
+ assert_eq!(
+ storage
+ .load_optimistic_projections(&[PredicateRecordKey::new("Thing:1").unwrap()])
+ .await
+ .unwrap(),
+ shadow_before
+ );
+ }
+ });
+}
+
#[test]
fn injected_statement_failures_roll_back_every_storage_boundary() {
block_on(async {
diff --git a/crates/client/cache-turso/tests/engine_turso.rs b/crates/client/cache-turso/tests/engine_turso.rs
index 5adf243307..93a0dde9b5 100644
--- a/crates/client/cache-turso/tests/engine_turso.rs
+++ b/crates/client/cache-turso/tests/engine_turso.rs
@@ -203,6 +203,7 @@ fn optimistic_hydration_retry_complete_and_reopen_run_over_turso() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000001008",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("doing"),
@@ -316,6 +317,7 @@ fn stale_local_head_and_storage_settlement_races_report_stale_claims() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000001009",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("first"),
@@ -331,6 +333,7 @@ fn stale_local_head_and_storage_settlement_races_report_stale_claims() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000001010",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("second"),
@@ -413,6 +416,7 @@ fn optimistic_discard_restores_durable_base_over_turso() {
.begin_optimistic_write(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000001011",
query: MUTATION,
operation_name: Some("SetEntityProperty"),
variables: &mutation_vars("bad"),
diff --git a/crates/client/cache-turso/tests/native_file.rs b/crates/client/cache-turso/tests/native_file.rs
index b0743aa0b2..e51c19f2a9 100644
--- a/crates/client/cache-turso/tests/native_file.rs
+++ b/crates/client/cache-turso/tests/native_file.rs
@@ -58,6 +58,7 @@ fn filesystem_database_preserves_the_mutation_queue() {
let mut storage = database.open("scope-1").unwrap();
let mutation_id = storage
.enqueue_mutation(NewQueuedMutation {
+ uuid: uuid::Uuid::new_v4(),
mutation: StoredMutation::new(
MutationRequest {
query: "mutation Persist { persist }".into(),
diff --git a/crates/client/cache-turso/tests/predicate.rs b/crates/client/cache-turso/tests/predicate.rs
index 358aefccff..e8ef437dcf 100644
--- a/crates/client/cache-turso/tests/predicate.rs
+++ b/crates/client/cache-turso/tests/predicate.rs
@@ -109,6 +109,7 @@ async fn begin_optimistic_projection(
.begin_optimistic_write_with_projections(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000001000",
query: r#"
mutation SetEntityProperty($input: SetEntityPropertyInput!) {
setEntityProperty(input: $input) {
@@ -465,6 +466,7 @@ fn turso_rehydrates_and_queries_durable_optimistic_projection_layers() {
.begin_optimistic_write_with_projections(
None,
BeginOptimisticWrite {
+ uuid: "00000000-0000-4000-8000-000000001001",
query: r#"
mutation SetEntityProperty($input: SetEntityPropertyInput!) {
setEntityProperty(input: $input) {
diff --git a/crates/client/cache-turso/tests/shared_conformance.rs b/crates/client/cache-turso/tests/shared_conformance.rs
index 04a826ce48..21e7668da4 100644
--- a/crates/client/cache-turso/tests/shared_conformance.rs
+++ b/crates/client/cache-turso/tests/shared_conformance.rs
@@ -78,6 +78,7 @@ fn record(value: &str) -> Record {
fn queued(label: &str) -> NewQueuedMutation {
NewQueuedMutation {
+ uuid: uuid::Uuid::new_v4(),
mutation: StoredMutation::new(
MutationRequest {
query: format!("mutation {label} {{ update {{ id }} }}"),
@@ -96,6 +97,7 @@ fn queued(label: &str) -> NewQueuedMutation {
fn fully_populated_queued() -> NewQueuedMutation {
NewQueuedMutation {
+ uuid: uuid::Uuid::new_v4(),
mutation: StoredMutation {
request: MutationRequest {
query: "mutation Full($id: ID!) { update(id: $id) { id } }".into(),
diff --git a/crates/client/cache-turso/tests/storage_conformance.rs b/crates/client/cache-turso/tests/storage_conformance.rs
index 4325c69ef8..593e35a9d6 100644
--- a/crates/client/cache-turso/tests/storage_conformance.rs
+++ b/crates/client/cache-turso/tests/storage_conformance.rs
@@ -28,6 +28,7 @@ fn queued(label: &str, created_at_ms: i64) -> NewQueuedMutation {
.fields
.insert("value".into(), CacheValue::String(label.into()));
NewQueuedMutation {
+ uuid: uuid::Uuid::new_v4(),
mutation: StoredMutation {
request: MutationRequest {
query: format!("mutation {label} {{ update {{ id }} }}"),
@@ -50,6 +51,12 @@ fn queued(label: &str, created_at_ms: i64) -> NewQueuedMutation {
}
}
+fn queued_with_uuid(label: &str, created_at_ms: i64, uuid: uuid::Uuid) -> NewQueuedMutation {
+ let mut queued = queued(label, created_at_ms);
+ queued.uuid = uuid;
+ queued
+}
+
fn claim(owner: &str, generation: u64) -> MutationClaimToken {
MutationClaimToken {
owner: owner.into(),
@@ -57,6 +64,63 @@ fn claim(owner: &str, generation: u64) -> MutationClaimToken {
}
}
+#[test]
+fn uuid_replacements_survive_reopen_with_pending_and_active_semantics() {
+ block_on(async {
+ let database = TursoMemoryDatabase::new("uuid-replacements.db");
+ let uuid = uuid::Uuid::new_v4();
+ let mut storage = database.open("pending").unwrap();
+ let first = storage
+ .enqueue_mutation(queued_with_uuid("First", 1, uuid))
+ .await
+ .unwrap();
+ let replacement = storage
+ .enqueue_mutation(queued_with_uuid("Replacement", 2, uuid))
+ .await
+ .unwrap();
+ assert!(replacement > first);
+ assert_eq!(storage.load_mutation_queue().await.unwrap().len(), 1);
+ storage.try_close().unwrap();
+
+ let storage = database.open("pending").unwrap();
+ let queue = storage.load_mutation_queue().await.unwrap();
+ assert_eq!(queue.len(), 1);
+ assert_eq!(queue[0].id, replacement);
+ assert_eq!(queue[0].uuid, uuid);
+ storage.try_close().unwrap();
+
+ database.physical_reset();
+ let mut storage = database.open("active").unwrap();
+ let active = storage
+ .enqueue_mutation(queued_with_uuid("Active", 10, uuid))
+ .await
+ .unwrap();
+ let claimed = storage
+ .claim_next_mutation(MutationClaimRequest {
+ owner: "runner".into(),
+ now_ms: 10,
+ lease_expires_at_ms: 100,
+ })
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(claimed.queued.id, active);
+ let replacement = storage
+ .enqueue_mutation(queued_with_uuid("Latest", 11, uuid))
+ .await
+ .unwrap();
+ storage.try_close().unwrap();
+
+ let storage = database.open("active").unwrap();
+ let queue = storage.load_mutation_queue().await.unwrap();
+ assert_eq!(queue.len(), 2);
+ assert_eq!(queue[0].id, active);
+ assert!(queue[0].superseded);
+ assert_eq!(queue[1].id, replacement);
+ assert!(!queue[1].superseded);
+ });
+}
+
#[test]
fn compound_keys_batches_duplicates_and_checked_inputs_conform() {
block_on(async {
@@ -141,6 +205,7 @@ fn queue_preserves_every_field_order_and_reopen_state() {
first_entry.mutation.lease_owner = Some("reopen-owner".into());
first_entry.mutation.lease_expires_at_ms = Some(175);
let second_entry = NewQueuedMutation {
+ uuid: uuid::Uuid::new_v4(),
mutation: StoredMutation::new(
MutationRequest {
query: "mutation Second { update { id } }".into(),
diff --git a/crates/client/cache-turso/tests/web.rs b/crates/client/cache-turso/tests/web.rs
index 341cc6556f..f1b955fec7 100644
--- a/crates/client/cache-turso/tests/web.rs
+++ b/crates/client/cache-turso/tests/web.rs
@@ -34,6 +34,7 @@ fn healthy_close(outcome: TursoStorageCloseOutcome) -> HealthyTursoStorageClosed
fn queued() -> NewQueuedMutation {
NewQueuedMutation {
+ uuid: uuid::Uuid::new_v4(),
mutation: StoredMutation::new(
MutationRequest {
query: "mutation Browser { update { id } }".into(),
diff --git a/crates/client/cache-wasm/Cargo.toml b/crates/client/cache-wasm/Cargo.toml
index 5b3862a282..5af6db50bb 100644
--- a/crates/client/cache-wasm/Cargo.toml
+++ b/crates/client/cache-wasm/Cargo.toml
@@ -2,7 +2,7 @@
edition = "2024"
name = "cache-wasm"
publish = false
-version = "0.6.3"
+version = "0.6.4"
[features]
default = []
diff --git a/crates/client/cache-wasm/src/shell.rs b/crates/client/cache-wasm/src/shell.rs
index e169844791..9907d24299 100644
--- a/crates/client/cache-wasm/src/shell.rs
+++ b/crates/client/cache-wasm/src/shell.rs
@@ -2,14 +2,17 @@ use async_lock::Mutex;
use cache_core::codec::cache_database_name;
use cache_core::deps::OpId;
use cache_core::engine::{
- BeginOptimisticWrite, Engine, EngineError, InitialClaimOutcome, NetworkWrite,
- QueryRegistration, ReadResult, WriteResult,
+ BeginOptimisticWrite, CommitOptimisticWriteResult, DeferOptimisticWriteResult, Engine,
+ EngineError, InitialClaimOutcome, NetworkWrite, QueryRegistration, ReadResult,
+ RollbackOptimisticWriteResult, WriteResult,
};
use cache_core::entity_resolver::EntityResolver;
use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};
use cache_core::predicate::PredicateQueryResult;
use cache_core::query_inspection::QueryInspection;
-use cache_core::queue::{ClaimedMutation, MutationClaimRequest, MutationClaimToken};
+use cache_core::queue::{
+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationUpsertKind,
+};
use cache_core::record_selection::RecordSelection;
use cache_core::search::SearchRequest;
use cache_core::store::QueueDiagnosticsAvailability;
@@ -167,6 +170,7 @@ struct JsInspectionPathSegment {
#[serde(rename_all = "camelCase")]
struct JsEnqueueOptimisticMutationResult {
transaction_id: String,
+ upsert_kind: JsMutationUpsertKind,
revision: String,
changed: Vec<String>,
affected_ops: Vec<String>,
@@ -175,6 +179,32 @@ struct JsEnqueueOptimisticMutationResult {
initial_claim: JsInitialMutationClaim,
}
+#[derive(Serialize)]
+#[serde(
+ tag = "kind",
+ rename_all = "kebab-case",
+ rename_all_fields = "camelCase"
+)]
+enum JsMutationUpsertKind {
+ Inserted,
+ ReplacedPending { removed_transaction_id: String },
+ AppendedAfterActive { active_transaction_id: String },
+}
+
+impl From<MutationUpsertKind> for JsMutationUpsertKind {
+ fn from(kind: MutationUpsertKind) -> Self {
+ match kind {
+ MutationUpsertKind::Inserted => Self::Inserted,
+ MutationUpsertKind::ReplacedPending { removed_id } => Self::ReplacedPending {
+ removed_transaction_id: removed_id.to_string(),
+ },
+ MutationUpsertKind::AppendedAfterActive { active_id } => Self::AppendedAfterActive {
+ active_transaction_id: active_id.to_string(),
+ },
+ }
+ }
+}
+
#[derive(Serialize)]
#[serde(tag = "kind", rename_all = "kebab-case")]
enum JsInitialMutationClaim {
@@ -187,6 +217,8 @@ enum JsInitialMutationClaim {
#[serde(rename_all = "camelCase")]
struct JsClaimedMutation {
transaction_id: String,
+ uuid: String,
+ superseded: bool,
lease_generation: String,
query: String,
operation_name: Option<String>,
@@ -202,6 +234,8 @@ impl TryFrom<ClaimedMutation> for JsClaimedMutation {
let request = claimed.queued.mutation.request;
Ok(Self {
transaction_id: claimed.queued.id.to_string(),
+ uuid: claimed.queued.uuid.to_string(),
+ superseded: claimed.queued.superseded,
lease_generation: claimed.lease_generation.to_string(),
query: request.query,
operation_name: request.operation_name,
@@ -301,6 +335,57 @@ struct JsRevisionResult {
revision: String,
}
+#[derive(Serialize)]
+#[serde(
+ tag = "kind",
+ rename_all = "kebab-case",
+ rename_all_fields = "camelCase"
+)]
+enum JsDeferOptimisticWriteResult {
+ Deferred,
+ DiscardedSuperseded {
+ replacement_transaction_id: String,
+ #[serde(flatten)]
+ result: JsWriteResult,
+ },
+}
+
+#[derive(Serialize)]
+#[serde(
+ tag = "kind",
+ rename_all = "kebab-case",
+ rename_all_fields = "camelCase"
+)]
+enum JsCommitOptimisticWriteResult {
+ Committed {
+ #[serde(flatten)]
+ result: JsWriteResult,
+ },
+ CommittedSuperseded {
+ replacement_transaction_id: String,
+ #[serde(flatten)]
+ result: JsWriteResult,
+ },
+}
+
+#[derive(Serialize)]
+#[serde(
+ tag = "kind",
+ rename_all = "kebab-case",
+ rename_all_fields = "camelCase"
+)]
+enum JsRollbackOptimisticWriteResult {
+ RolledBack {
+ #[serde(flatten)]
+ result: JsWriteResult,
+ },
+ DiscardedSuperseded {
+ replacement_transaction_id: String,
+ #[serde(flatten)]
+ result: JsWriteResult,
+ },
+}
+
fn js_write_result(result: WriteResult, ops: &OpInterner) -> JsWriteResult {
JsWriteResult {
revision: result.revision.to_string(),
@@ -1050,6 +1135,7 @@ impl CacheEngine {
pub fn enqueue_optimistic_mutation(
&self,
origin_op_id: Option<String>,
+ uuid: String,
query: String,
operation_name: Option<String>,
variables: JsValue,
@@ -1086,6 +1172,7 @@ impl CacheEngine {
.enqueue_optimistic_mutation_with_projections(
origin,
BeginOptimisticWrite {
+ uuid: &uuid,
query: &query,
operation_name: operation_name.as_deref(),
variables: &vars,
@@ -1113,6 +1200,7 @@ impl CacheEngine {
};
to_js(&JsEnqueueOptimisticMutationResult {
transaction_id: result.transaction_id.to_string(),
+ upsert_kind: result.upsert_kind.into(),
revision: result.write_result.revision.to_string(),
changed: result
.write_result
@@ -1208,6 +1296,7 @@ impl CacheEngine {
error: String,
) -> js_sys::Promise {
let state = self.state.clone();
+ let ops = self.ops.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
@@ -1221,8 +1310,17 @@ impl CacheEngine {
.engine_mut()?
.defer_optimistic_write(transaction, claim, next_attempt_at_ms, error)
.await;
- state.engine_result(result)?;
- Ok(JsValue::UNDEFINED)
+ let result = state.engine_result(result)?;
+ let result = match result {
+ DeferOptimisticWriteResult::Deferred => JsDeferOptimisticWriteResult::Deferred,
+ DeferOptimisticWriteResult::DiscardedSuperseded(result) => {
+ JsDeferOptimisticWriteResult::DiscardedSuperseded {
+ replacement_transaction_id: result.replacement_transaction_id.to_string(),
+ result: js_write_result(result.write_result, &ops.borrow()),
+ }
+ }
+ };
+ to_js(&result)
})
}
@@ -1257,7 +1355,7 @@ impl CacheEngine {
.map_err(err_js)?;
let result = state
.engine_mut()?
- .commit_optimistic_write_with_projections(
+ .commit_optimistic_write_with_projections_outcome(
transaction,
claim,
&query,
@@ -1267,8 +1365,20 @@ impl CacheEngine {
projections,
)
.await;
- let result = state.engine_result(result)?;
- to_js(&js_write_result(result, &ops.borrow()))
+ let result = match state.engine_result(result)? {
+ CommitOptimisticWriteResult::Committed(result) => {
+ JsCommitOptimisticWriteResult::Committed {
+ result: js_write_result(result, &ops.borrow()),
+ }
+ }
+ CommitOptimisticWriteResult::CommittedSuperseded(result) => {
+ JsCommitOptimisticWriteResult::CommittedSuperseded {
+ replacement_transaction_id: result.replacement_transaction_id.to_string(),
+ result: js_write_result(result.write_result, &ops.borrow()),
+ }
+ }
+ };
+ to_js(&result)
})
}
@@ -1293,10 +1403,22 @@ impl CacheEngine {
};
let result = state
.engine_mut()?
- .rollback_optimistic_write(transaction, claim)
+ .rollback_optimistic_write_with_outcome(transaction, claim)
.await;
- let result = state.engine_result(result)?;
- to_js(&js_write_result(result, &ops.borrow()))
+ let result = match state.engine_result(result)? {
+ RollbackOptimisticWriteResult::RolledBack(result) => {
+ JsRollbackOptimisticWriteResult::RolledBack {
+ result: js_write_result(result, &ops.borrow()),
+ }
+ }
+ RollbackOptimisticWriteResult::DiscardedSuperseded(result) => {
+ JsRollbackOptimisticWriteResult::DiscardedSuperseded {
+ replacement_transaction_id: result.replacement_transaction_id.to_string(),
+ result: js_write_result(result.write_result, &ops.borrow()),
+ }
+ }
+ };
+ to_js(&result)
})
}
diff --git a/crates/client/cache-wasm/src/shell/test.rs b/crates/client/cache-wasm/src/shell/test.rs
index 6c5e565345..93c5b5285a 100644
--- a/crates/client/cache-wasm/src/shell/test.rs
+++ b/crates/client/cache-wasm/src/shell/test.rs
@@ -181,6 +181,58 @@ async fn resolved(promise: js_sys::Promise) -> JsValue {
JsFuture::from(promise).await.expect("promise resolves")
}
+fn empty_js_write_result() -> JsWriteResult {
+ JsWriteResult {
+ revision: "0".to_string(),
+ changed: Vec::new(),
+ affected_ops: Vec::new(),
+ reset: false,
+ revalidations: Vec::new(),
+ }
+}
+
+#[wasm_bindgen_test]
+fn tagged_wire_enum_fields_are_camel_case() {
+ assert_eq!(
+ serde_json::to_value(JsMutationUpsertKind::ReplacedPending {
+ removed_transaction_id: "1".to_string(),
+ })
+ .unwrap(),
+ serde_json::json!({"kind": "replaced-pending", "removedTransactionId": "1"})
+ );
+ assert_eq!(
+ serde_json::to_value(JsMutationUpsertKind::AppendedAfterActive {
+ active_transaction_id: "2".to_string(),
+ })
+ .unwrap(),
+ serde_json::json!({"kind": "appended-after-active", "activeTransactionId": "2"})
+ );
+ assert_eq!(
+ serde_json::to_value(JsDeferOptimisticWriteResult::DiscardedSuperseded {
+ replacement_transaction_id: "3".to_string(),
+ result: empty_js_write_result(),
+ })
+ .unwrap()["replacementTransactionId"],
+ "3"
+ );
+ assert_eq!(
+ serde_json::to_value(JsCommitOptimisticWriteResult::CommittedSuperseded {
+ replacement_transaction_id: "4".to_string(),
+ result: empty_js_write_result(),
+ })
+ .unwrap()["replacementTransactionId"],
+ "4"
+ );
+ assert_eq!(
+ serde_json::to_value(JsRollbackOptimisticWriteResult::DiscardedSuperseded {
+ replacement_transaction_id: "5".to_string(),
+ result: empty_js_write_result(),
+ })
+ .unwrap()["replacementTransactionId"],
+ "5"
+ );
+}
+
async fn assert_closed(promise: js_sys::Promise) {
let error = JsFuture::from(promise)
.await
@@ -959,6 +1011,7 @@ async fn optimistic_v2_patch_is_filterable_after_enqueue_reopen_and_rollback() {
let enqueue: serde_json::Value = from_js(
resolved(engine.enqueue_optimistic_mutation(
None,
+ "00000000-0000-4000-8000-000000000001".into(),
OPTIMISTIC_DOCUMENT_MUTATION.into(),
Some("RenameEntities".into()),
js(serde_json::json!({
@@ -1089,6 +1142,7 @@ async fn queue_and_optimistic_layers_survive_preserve_reopen_in_id_order() {
let first: serde_json::Value = from_js(
resolved(engine.enqueue_optimistic_mutation(
None,
+ "00000000-0000-4000-8000-000000000002".into(),
PROPERTY_MUTATION.into(),
Some("SetEntityProperty".into()),
js(mutation_variables()),
@@ -1109,6 +1163,7 @@ async fn queue_and_optimistic_layers_survive_preserve_reopen_in_id_order() {
let second: serde_json::Value = from_js(
resolved(engine.enqueue_optimistic_mutation(
None,
+ "00000000-0000-4000-8000-000000000003".into(),
PROPERTY_MUTATION.into(),
Some("SetEntityProperty".into()),
js(mutation_variables()),
@@ -1211,6 +1266,7 @@ async fn optimistic_commit_reports_affected_ops_and_rejects_settled_or_malformed
let enqueue: serde_json::Value = from_js(
resolved(engine.enqueue_optimistic_mutation(
None,
+ "00000000-0000-4000-8000-000000000004".into(),
PROPERTY_MUTATION.into(),
Some("SetEntityProperty".into()),
js(mutation_variables()),
@@ -1308,6 +1364,7 @@ async fn destroy_recovery_wipes_records_and_queue() {
.await;
resolved(engine.enqueue_optimistic_mutation(
None,
+ "00000000-0000-4000-8000-000000000005".into(),
PROPERTY_MUTATION.into(),
Some("SetEntityProperty".into()),
js(mutation_variables()),
@@ -1523,6 +1580,7 @@ async fn storage_reset_errors_latch_and_block_hot_read_write_and_control_methods
.await;
assert_reset_required(engine.enqueue_optimistic_mutation(
None,
+ "00000000-0000-4000-8000-000000000006".into(),
PROPERTY_MUTATION.into(),
Some("SetEntityProperty".into()),
js(mutation_variables()),
@@ -1572,6 +1630,7 @@ async fn physical_reset_serializes_recreates_and_preserves_interner_registration
.expect("operation is interned before reset");
resolved(engine.enqueue_optimistic_mutation(
None,
+ "00000000-0000-4000-8000-000000000007".into(),
PROPERTY_MUTATION.into(),
Some("SetEntityProperty".into()),
js(mutation_variables()),
@@ -1690,6 +1749,7 @@ async fn every_method_rejects_after_consuming_close() {
.await;
assert_closed(engine.enqueue_optimistic_mutation(
None,
+ "00000000-0000-4000-8000-000000000008".into(),
PROPERTY_MUTATION.into(),
Some("SetEntityProperty".into()),
js(mutation_variables()),
diff --git a/crates/client/cache-wasm/src/shell/test_storage.rs b/crates/client/cache-wasm/src/shell/test_storage.rs
index 1ac420b28f..3209a54ba1 100644
--- a/crates/client/cache-wasm/src/shell/test_storage.rs
+++ b/crates/client/cache-wasm/src/shell/test_storage.rs
@@ -1,18 +1,16 @@
use cache_core::predicate::{
- OptimisticShadowReconciliation, PredicateIndexStorage, PredicateQueryResult,
- ProjectionMutation, ProjectionState,
+ OptimisticShadowReconciliation, OptimisticUpsertReconciliation, PredicateIndexStorage,
+ PredicateQueryResult, ProjectionMutation, ProjectionState,
};
use cache_core::queue::{
- ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,
- QueuedMutation,
+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationUpsertResult,
+ NewQueuedMutation, QueuedMutation,
};
use cache_core::search::{SearchCursor, SearchDocument, SearchProfile};
use cache_core::store::{QueueDiagnostics, Storage};
use cache_core::value::{EntityKey, Record};
use cache_turso::{PhysicalResetReason, TursoStorage, TursoStorageError};
-use predicate_index::{
- EffectiveOptimisticProjection, PendingOptimisticProjection, RecordKey, ValidatedIndexQuery,
-};
+use predicate_index::{EffectiveOptimisticProjection, RecordKey, ValidatedIndexQuery};
use std::sync::atomic::{AtomicU8, Ordering};
#[derive(Clone, Copy)]
@@ -105,13 +103,14 @@ impl Storage for BrowserStorage {
.await
}
- async fn enqueue_mutation_with_shadow(
+ async fn upsert_mutation_with_shadow(
&mut self,
entry: NewQueuedMutation,
- projections: Vec<PendingOptimisticProjection>,
- ) -> Result<MutationId, Self::Error> {
+ now_ms: i64,
+ reconciliation: OptimisticUpsertReconciliation,
+ ) -> Result<MutationUpsertResult, Self::Error> {
self.inner
- .enqueue_mutation_with_shadow(entry, projections)
+ .upsert_mutation_with_shadow(entry, now_ms, reconciliation)
.await
}