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.

perf(graphql-cache): prioritize optimistic affected rereads (#5428)

Sean Aye56bc758700b4
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 5c0c788f55..3c6a19d9d4 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
@@ -124,7 +124,12 @@ const ALIASED_RENAME_MUTATION = gql`
`;
type FakeHost = CacheHost & {
- reads: Array<{ opKey?: number; query: string; variables?: object }>;
+ reads: Array<{
+ opKey?: number;
+ query: string;
+ variables?: object;
+ priority?: 'user-visible';
+ }>;
writes: Array<{ opKey?: number; data: unknown; identity?: string }>;
begins: Array<{
query: string;
@@ -184,6 +189,7 @@ function makeFakeHost(): FakeHost {
opKey: args.opKey,
query: args.query,
variables: args.variables,
+ priority: args.priority,
});
return readResult;
},
@@ -825,18 +831,27 @@ describe('normalizedCacheExchange', () => {
expect(host.writes[0]?.identity).toBe('macro|[email protected]');
});
- it('re-executes affected active operations as cache-first', async () => {
+ it('re-executes each affected active operation once as a prioritized cache read', async () => {
+ host.scriptRead({ kind: 'hit', data: { from: 'cache' } });
const { ops, client } = harness(host);
const op = makeOp(7, 'cache-and-network');
ops.next(op);
await tick();
+ vi.mocked(client.reexecuteOperation).mockImplementation((reissued) => {
+ ops.next(reissued);
+ });
host.pushAffected([7, 999]); // 999 is not active → ignored
+ await tick();
+
const reexec = vi.mocked(client.reexecuteOperation);
expect(reexec).toHaveBeenCalledOnce();
const reissued = reexec.mock.calls[0]?.[0] as Operation;
expect(reissued.key).toBe(7);
expect(reissued.context.requestPolicy).toBe('cache-first');
+ expect(host.reads).toHaveLength(2);
+ expect(host.reads[0]?.priority).toBeUndefined();
+ expect(host.reads[1]?.priority).toBe('user-visible');
});
it('teardown unregisters the op with the host and stops re-execution', async () => {
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 c7b225654b..d273f7dc1e 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
@@ -71,6 +71,8 @@ import {
* carries its own transaction.
*/
const QUEUE_ATTEMPT_CONTEXT_KEY = 'normalizedCacheQueueAttempt';
+/** Marks dependency-pushed reads as latency-sensitive worker work. */
+const AFFECTED_READ_CONTEXT_KEY = 'normalizedCacheAffectedRead';
const QUEUE_REQUEST_TIMEOUT_MS = 60_000;
const QUEUE_LEASE_MS = 5 * 60_000;
const EMPTY_QUEUE_POLL_MS = 30_000;
@@ -319,6 +321,7 @@ export function normalizedCacheExchange(
makeOperation(op.kind, op, {
...op.context,
requestPolicy: 'cache-first',
+ [AFFECTED_READ_CONTEXT_KEY]: true,
})
);
}
@@ -489,6 +492,10 @@ export function normalizedCacheExchange(
query: queryText(op),
operationName: operationName(op),
variables: op.variables as Record<string, unknown> | undefined,
+ priority:
+ op.context[AFFECTED_READ_CONTEXT_KEY] === true
+ ? 'user-visible'
+ : undefined,
});
if (read.kind === 'hit') {
const stale = policy === 'cache-and-network';
diff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.ts
index 14ef0da6f9..a6da384cee 100644
--- a/apps/web/src/lib/graphql-cache/host/types.ts
+++ b/apps/web/src/lib/graphql-cache/host/types.ts
@@ -7,6 +7,7 @@
import type {
CachedQueryInstanceWire,
+ CacheReadPriority,
ClaimedMutation,
MutationClaim,
MutationSettlement,
@@ -25,6 +26,8 @@ export interface CacheReadArgs {
query: string;
operationName?: string;
variables?: Record<string, unknown>;
+ /** Prioritizes a pushed, user-visible refresh over incidental reads. */
+ priority?: CacheReadPriority;
}
export interface InspectQueryArgs {
@@ -34,7 +37,7 @@ export interface InspectQueryArgs {
path: Array<{ field: string }>;
}
-export interface CacheWriteArgs extends CacheReadArgs {
+export interface CacheWriteArgs extends Omit<CacheReadArgs, 'priority'> {
data: unknown;
/** Opaque session tag; see protocol.ts `identity`. */
identity?: string;
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 23e20cb97d..0b5d85d13c 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
@@ -77,6 +77,52 @@ describe('createWorkerCacheHost', () => {
host.dispose();
});
+ it('forwards user-visible read priority to the worker', async () => {
+ const requests: Array<{ id?: number; kind: string; priority?: string }> =
+ [];
+ class FakeSharedWorker {
+ port = {
+ onmessage: null as ((event: MessageEvent) => void) | null,
+ start() {},
+ close() {},
+ postMessage: (request: {
+ id?: number;
+ kind: string;
+ priority?: string;
+ }) => {
+ requests.push(request);
+ if (request.id === undefined) return;
+ queueMicrotask(() => {
+ this.port.onmessage?.({
+ data: {
+ id: request.id,
+ ok: true,
+ result:
+ request.kind === 'read'
+ ? { kind: 'hit', data: { soup: true } }
+ : null,
+ },
+ } as MessageEvent);
+ });
+ },
+ };
+ }
+ vi.stubGlobal('SharedWorker', FakeSharedWorker);
+ const host = createWorkerCacheHost({ scope: 'scope-1' });
+
+ await expect(
+ host.readQuery({
+ opKey: 7,
+ query: 'query GroupSoup { groupSoup }',
+ priority: 'user-visible',
+ })
+ ).resolves.toEqual({ kind: 'hit', data: { soup: true } });
+ expect(requests).toContainEqual(
+ expect.objectContaining({ kind: 'read', priority: 'user-visible' })
+ );
+ host.dispose();
+ });
+
it('delivers queued mutation settlements pushed by the worker', async () => {
let push: (message: unknown) => void = () => {
throw new Error('worker not initialized');
diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.ts
index 17b1889136..6d9d761ec9 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts
@@ -181,6 +181,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
query: args.query,
operationName: args.operationName,
variables: args.variables,
+ priority: args.priority,
})) as ReadResult;
},
diff --git a/apps/web/src/lib/graphql-cache/index.ts b/apps/web/src/lib/graphql-cache/index.ts
index 27bbd83668..41826e73dc 100644
--- a/apps/web/src/lib/graphql-cache/index.ts
+++ b/apps/web/src/lib/graphql-cache/index.ts
@@ -41,6 +41,7 @@ export { createWorkerCacheHost } from './host/worker-host';
export type {
CachedQueryInstanceWire,
CachePush,
+ CacheReadPriority,
CacheRequest,
CacheResponse,
MutationSettlement,
diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.ts
index 6aabe2135c..aa614654c5 100644
--- a/apps/web/src/lib/graphql-cache/protocol.ts
+++ b/apps/web/src/lib/graphql-cache/protocol.ts
@@ -11,6 +11,9 @@
export type ReadResult = { kind: 'hit'; data: unknown } | { kind: 'miss' };
+/** Scheduling hint for latency-sensitive cache reads. */
+export type CacheReadPriority = 'user-visible';
+
/** Opaque exclusive cursor for deterministic normalized-record scans. */
export type RecordCursor = string;
@@ -140,6 +143,8 @@ export type CacheRequest = { id: number } & (
query: string;
operationName?: string;
variables?: Record<string, unknown>;
+ /** May overtake unrelated observational reads, never ordering barriers. */
+ priority?: CacheReadPriority;
}
| {
kind: 'write';
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 09cbfda42e..569547d23e 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
@@ -7,7 +7,7 @@ vi.mock('./wasm-module', () => ({ loadCacheWasm: loadCacheWasmMock }));
import type { SelectedRecordPageWire } from '../protocol';
import { CacheWorkerCore } from './worker-core';
-describe('CacheWorkerCore record selection', () => {
+describe('CacheWorkerCore', () => {
beforeEach(() => {
vi.clearAllMocks();
});
@@ -48,6 +48,232 @@ describe('CacheWorkerCore record selection', () => {
expect(messages.at(-1)).toEqual({ id: 2, ok: true, result: page });
});
+ it('coalesces queued affected rereads and runs them ahead of incidental reads', async () => {
+ const order: string[] = [];
+ let releaseBlocker!: () => void;
+ let markBlockerStarted!: () => void;
+ const blocker = new Promise<void>((resolve) => {
+ releaseBlocker = resolve;
+ });
+ const blockerStarted = new Promise<void>((resolve) => {
+ markBlockerStarted = resolve;
+ });
+ const readQuery = vi.fn(async (opId: string | undefined) => {
+ order.push(`read:${opId}`);
+ if (opId === 'client:blocker') {
+ markBlockerStarted();
+ await blocker;
+ }
+ return { kind: 'hit' as const, data: { opId } };
+ });
+ const beginOptimisticWrite = vi.fn(
+ async (_originOpId: string | undefined, query: string) => {
+ order.push(`begin:${query}`);
+ return {
+ transactionId: query,
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ };
+ }
+ );
+ loadCacheWasmMock.mockResolvedValue({
+ openCache: vi.fn().mockResolvedValue({
+ readQuery,
+ beginOptimisticWrite,
+ }),
+ });
+ const messages: unknown[] = [];
+ const port = { postMessage: (message: unknown) => messages.push(message) };
+ const core = new CacheWorkerCore();
+ await core.handleRequest(port, {
+ id: 1,
+ kind: 'init',
+ scope: 'scope-1',
+ });
+
+ const running = core.handleRequest(port, {
+ id: 2,
+ kind: 'read',
+ opId: 'client:blocker',
+ query: 'query Blocker { blocker }',
+ });
+ await blockerStarted;
+ const ordinaryDuplicate = core.handleRequest(port, {
+ id: 3,
+ kind: 'read',
+ opId: 'client:group-soup',
+ query: 'query GroupSoup { groupSoup }',
+ variables: { input: { limit: 20 } },
+ });
+ const incidental = core.handleRequest(port, {
+ id: 4,
+ kind: 'read',
+ opId: 'client:child',
+ query: 'query Child { child }',
+ });
+ const firstBegin = core.handleRequest(port, {
+ id: 5,
+ kind: 'begin-optimistic-write',
+ query: 'mutation First { first }',
+ data: { first: true },
+ createdAtMs: 1,
+ });
+ const secondBegin = core.handleRequest(port, {
+ id: 6,
+ kind: 'begin-optimistic-write',
+ query: 'mutation Second { second }',
+ data: { second: true },
+ createdAtMs: 2,
+ });
+ const affectedDuplicate = core.handleRequest(port, {
+ id: 7,
+ kind: 'read',
+ opId: 'client:group-soup',
+ query: 'query GroupSoup { groupSoup }',
+ variables: { input: { limit: 20 } },
+ priority: 'user-visible',
+ });
+
+ releaseBlocker();
+ await Promise.all([
+ running,
+ ordinaryDuplicate,
+ incidental,
+ firstBegin,
+ secondBegin,
+ affectedDuplicate,
+ ]);
+
+ expect(order).toEqual([
+ 'read:client:blocker',
+ 'begin:mutation First { first }',
+ 'begin:mutation Second { second }',
+ 'read:client:group-soup',
+ 'read:client:child',
+ ]);
+ // Two read RPCs for the same active operation require one wasm call, so
+ // the full denormalization and its IndexedDB get_batch work run once.
+ expect(
+ readQuery.mock.calls.filter(([opId]) => opId === 'client:group-soup')
+ ).toHaveLength(1);
+ expect(messages).toContainEqual({
+ id: 3,
+ ok: true,
+ result: {
+ kind: 'hit',
+ data: { opId: 'client:group-soup' },
+ },
+ });
+ expect(messages).toContainEqual({
+ id: 7,
+ ok: true,
+ result: {
+ kind: 'hit',
+ data: { opId: 'client:group-soup' },
+ },
+ });
+ });
+
+ it('does not reorder or coalesce reads across operation teardown', async () => {
+ const order: string[] = [];
+ let releaseBlocker!: () => void;
+ let markBlockerStarted!: () => void;
+ const blocker = new Promise<void>((resolve) => {
+ releaseBlocker = resolve;
+ });
+ const blockerStarted = new Promise<void>((resolve) => {
+ markBlockerStarted = resolve;
+ });
+ const readQuery = vi.fn(async (opId: string | undefined) => {
+ order.push(`read:${opId}`);
+ if (opId === 'client:blocker') {
+ markBlockerStarted();
+ await blocker;
+ }
+ return { kind: 'miss' as const };
+ });
+ const teardownOperation = vi.fn(async (opId: string) => {
+ order.push(`teardown:${opId}`);
+ });
+ const beginOptimisticWrite = vi.fn(async () => {
+ order.push('begin');
+ return {
+ transactionId: '1',
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ };
+ });
+ loadCacheWasmMock.mockResolvedValue({
+ openCache: vi.fn().mockResolvedValue({
+ readQuery,
+ teardownOperation,
+ beginOptimisticWrite,
+ }),
+ });
+ const port = { postMessage: vi.fn() };
+ const core = new CacheWorkerCore();
+ await core.handleRequest(port, {
+ id: 1,
+ kind: 'init',
+ scope: 'scope-1',
+ });
+
+ const running = core.handleRequest(port, {
+ id: 2,
+ kind: 'read',
+ opId: 'client:blocker',
+ query: 'query Blocker { blocker }',
+ });
+ await blockerStarted;
+ const readBeforeTeardown = core.handleRequest(port, {
+ id: 3,
+ kind: 'read',
+ opId: 'client:group-soup',
+ query: 'query GroupSoup { groupSoup }',
+ });
+ const teardown = core.handleRequest(port, {
+ id: 4,
+ kind: 'teardown',
+ opId: 'client:group-soup',
+ });
+ const begin = core.handleRequest(port, {
+ id: 5,
+ kind: 'begin-optimistic-write',
+ query: 'mutation Update { update }',
+ data: { update: true },
+ createdAtMs: 1,
+ });
+ const readAfterTeardown = core.handleRequest(port, {
+ id: 6,
+ kind: 'read',
+ opId: 'client:group-soup',
+ query: 'query GroupSoup { groupSoup }',
+ priority: 'user-visible',
+ });
+
+ releaseBlocker();
+ await Promise.all([
+ running,
+ readBeforeTeardown,
+ teardown,
+ begin,
+ readAfterTeardown,
+ ]);
+
+ expect(order).toEqual([
+ 'read:client:blocker',
+ 'read:client:group-soup',
+ 'teardown:client:group-soup',
+ 'begin',
+ 'read:client:group-soup',
+ ]);
+ expect(
+ readQuery.mock.calls.filter(([opId]) => opId === 'client:group-soup')
+ ).toHaveLength(2);
+ });
+
it('pushes cache changes even without affected operations', async () => {
const writeResult = {
changed: ['GraphqlSoupDocument:doc-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 515c8b3b14..305ee9cd79 100644
--- a/apps/web/src/lib/graphql-cache/worker/worker-core.ts
+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.ts
@@ -19,12 +19,68 @@ type PortLike = {
postMessage(msg: unknown): void;
};
+type RequestWaiter = {
+ resolve: (value: unknown) => void;
+ reject: (error: unknown) => void;
+};
+
+type QueuedEngineRequest = {
+ request: CacheRequest;
+ priority: number;
+ readSignature?: string;
+ waiters: RequestWaiter[];
+};
+
+const NORMAL_READ_PRIORITY = 0;
+const USER_VISIBLE_READ_PRIORITY = 1;
+const CACHE_WRITE_PRIORITY = 2;
+
+/** Reads may reorder while they overlap, but never across lifecycle barriers. */
+function isOrderingBarrier(request: CacheRequest): boolean {
+ return (
+ request.kind === 'init' ||
+ request.kind === 'teardown' ||
+ request.kind === 'clear'
+ );
+}
+
+function requestPriority(request: CacheRequest): number {
+ if (request.kind === 'read') {
+ return request.priority === 'user-visible'
+ ? USER_VISIBLE_READ_PRIORITY
+ : NORMAL_READ_PRIORITY;
+ }
+ if (
+ request.kind === 'write' ||
+ request.kind === 'begin-optimistic-write' ||
+ request.kind === 'commit-optimistic-write' ||
+ request.kind === 'rollback-optimistic-write' ||
+ request.kind === 'invalidate' ||
+ request.kind === 'delete-records'
+ ) {
+ return CACHE_WRITE_PRIORITY;
+ }
+ return NORMAL_READ_PRIORITY;
+}
+
+/** Exact active-operation reads can share one denormalization/storage pass. */
+function readSignature(request: CacheRequest): string | undefined {
+ if (request.kind !== 'read' || request.opId === undefined) return;
+ return JSON.stringify([
+ request.opId,
+ request.query,
+ request.operationName ?? null,
+ request.variables ?? null,
+ ]);
+}
+
export class CacheWorkerCore {
private engine: CacheEngine | undefined;
private initPromise: Promise<void> | undefined;
private scope: string | undefined;
- /** Serializes engine calls (defense in depth; the engine also locks). */
- private queue: Promise<unknown> = Promise.resolve();
+ /** Serializes engine calls while allowing safe read prioritization. */
+ private readonly queue: QueuedEngineRequest[] = [];
+ private running = false;
private readonly ports = new Set<PortLike>();
addPort(port: PortLike): void {
@@ -38,7 +94,7 @@ export class CacheWorkerCore {
async handleRequest(port: PortLike, request: CacheRequest): Promise<void> {
const respond = (response: CacheResponse) => port.postMessage(response);
try {
- const result = await this.enqueue(() => this.dispatch(request));
+ const result = await this.enqueue(request);
respond({ id: request.id, ok: true, result });
} catch (error) {
respond({
@@ -49,10 +105,83 @@ export class CacheWorkerCore {
}
}
- private enqueue<T>(task: () => Promise<T>): Promise<T> {
- const next = this.queue.then(task, task);
- this.queue = next.catch(() => undefined);
- return next;
+ private enqueue(request: CacheRequest): Promise<unknown> {
+ return new Promise((resolve, reject) => {
+ const priority = requestPriority(request);
+ const signature = readSignature(request);
+
+ // Coalesce only within the current lifecycle segment. In particular, a
+ // remount after teardown must perform a fresh read to re-register deps.
+ if (signature !== undefined) {
+ let segmentStart = 0;
+ for (let i = this.queue.length - 1; i >= 0; i -= 1) {
+ const queued = this.queue[i];
+ if (queued && isOrderingBarrier(queued.request)) {
+ segmentStart = i + 1;
+ break;
+ }
+ }
+ const duplicate = this.queue
+ .slice(segmentStart)
+ .find((queued) => queued.readSignature === signature);
+ if (duplicate) {
+ duplicate.priority = Math.max(duplicate.priority, priority);
+ duplicate.waiters.push({ resolve, reject });
+ this.drain();
+ return;
+ }
+ }
+
+ this.queue.push({
+ request,
+ priority,
+ readSignature: signature,
+ waiters: [{ resolve, reject }],
+ });
+ this.drain();
+ });
+ }
+
+ /**
+ * Runs the highest-priority request before the next lifecycle barrier.
+ * Cache-view writes retain FIFO order with each other; overlapping reads
+ * may observe the newer state, which is linearizable and avoids stale work.
+ */
+ private drain(): void {
+ if (this.running || this.queue.length === 0) return;
+
+ let segmentEnd = this.queue.findIndex((queued) =>
+ isOrderingBarrier(queued.request)
+ );
+ if (segmentEnd === -1) segmentEnd = this.queue.length;
+
+ let index = 0;
+ if (segmentEnd > 0) {
+ for (let i = 1; i < segmentEnd; i += 1) {
+ const candidate = this.queue[i];
+ const selected = this.queue[index];
+ if (candidate && selected && candidate.priority > selected.priority) {
+ index = i;
+ }
+ }
+ }
+
+ const [queued] = this.queue.splice(index, 1);
+ if (!queued) return;
+ this.running = true;
+ void this.dispatch(queued.request)
+ .then(
+ (result) => {
+ for (const waiter of queued.waiters) waiter.resolve(result);
+ },
+ (error) => {
+ for (const waiter of queued.waiters) waiter.reject(error);
+ }
+ )
+ .finally(() => {
+ this.running = false;
+ this.drain();
+ });
}
private async dispatch(request: CacheRequest): Promise<unknown> {