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/perf/improve backfill (#5910)

Sean Aye39c42cd6f4a9
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 e758a15f0a..4e01e2b67e 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
@@ -247,6 +247,159 @@ describe('CacheWorkerCore', () => {
]);
});
+ it('runs foreground cache reads ahead of queued background hydration', 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 entityFilter = vi.fn(async () => {
+ order.push('entity-filter');
+ return { kind: 'incomplete' as const };
+ });
+ const hydrateQuery = vi.fn(async () => {
+ order.push('hydrate');
+ return { kind: 'none' as const };
+ });
+ loadCacheWasmMock.mockResolvedValue({
+ openCache: vi.fn().mockResolvedValue({
+ readQuery,
+ entityFilter,
+ hydrateQuery,
+ }),
+ });
+ 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 hydration = core.handleRequest(port, {
+ id: 3,
+ kind: 'hydrate',
+ query: 'query Backfill { backfill }',
+ data: { backfill: true },
+ });
+ const filter = core.handleRequest(port, {
+ id: 4,
+ kind: 'entity-filter',
+ request: {
+ filters: {},
+ sortMethod: 'UPDATED_AT',
+ sortDirection: 'DESC',
+ limit: 20,
+ },
+ });
+ const visibleRead = core.handleRequest(port, {
+ id: 5,
+ kind: 'read',
+ opId: 'client:visible',
+ query: 'query Visible { visible }',
+ priority: 'user-visible',
+ });
+
+ releaseBlocker();
+ await Promise.all([running, hydration, filter, visibleRead]);
+
+ expect(order).toEqual([
+ 'read:client:blocker',
+ 'read:client:visible',
+ 'entity-filter',
+ 'hydrate',
+ ]);
+ });
+
+ it('does not let stale hydration overwrite a newer queued write', async () => {
+ let releaseBlocker!: () => void;
+ let markBlockerStarted!: () => void;
+ const blocker = new Promise<void>((resolve) => {
+ releaseBlocker = resolve;
+ });
+ const blockerStarted = new Promise<void>((resolve) => {
+ markBlockerStarted = resolve;
+ });
+ const record = { id: 'doc-1', title: 'initial' };
+ const mergeDocument = (data: unknown) => {
+ Object.assign(
+ record,
+ (data as { document: { id: string; title: string } }).document
+ );
+ };
+ const readQuery = vi.fn(async () => {
+ markBlockerStarted();
+ await blocker;
+ return { kind: 'miss' as const };
+ });
+ const hydrateQuery = vi.fn(async (...args: unknown[]) => {
+ mergeDocument(args[3]);
+ return { changed: [], affectedOps: [], reset: false, data: null };
+ });
+ const writeQuery = vi.fn(async (...args: unknown[]) => {
+ mergeDocument(args[4]);
+ return { changed: [], affectedOps: [], reset: false };
+ });
+ loadCacheWasmMock.mockResolvedValue({
+ openCache: vi.fn().mockResolvedValue({
+ readQuery,
+ hydrateQuery,
+ writeQuery,
+ }),
+ });
+ 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',
+ query: 'query Blocker { blocker }',
+ });
+ await blockerStarted;
+ const hydration = core.handleRequest(port, {
+ id: 3,
+ kind: 'hydrate',
+ query: 'query Backfill { document { id title } }',
+ data: { document: { id: 'doc-1', title: 'stale' } },
+ });
+ const write = core.handleRequest(port, {
+ id: 4,
+ kind: 'write',
+ query: 'query Current { document { id title } }',
+ data: { document: { id: 'doc-1', title: 'newer' } },
+ });
+
+ releaseBlocker();
+ await Promise.all([running, hydration, write]);
+
+ expect(record).toEqual({ id: 'doc-1', title: 'newer' });
+ expect(hydrateQuery).toHaveBeenCalledBefore(writeQuery);
+ });
+
it('coalesces queued affected rereads and runs them ahead of incidental reads', async () => {
const order: string[] = [];
let releaseBlocker!: () => void;
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 b047ba269d..6961f33a50 100644
--- a/apps/web/src/lib/graphql-cache/worker/worker-core.ts
+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.ts
@@ -60,6 +60,10 @@ export interface CacheWorkerCoreOptions {
queueDiagnosticsTimeoutMs?: number;
}
+// Backfill hydration is cache warming, so foreground reads may overtake it.
+// Hydration and authoritative writes still retain arrival order so stale
+// hydration cannot overwrite a newer queued response.
+const BACKGROUND_HYDRATION_PRIORITY = -1;
const NORMAL_READ_PRIORITY = 0;
const USER_VISIBLE_READ_PRIORITY = 1;
const CACHE_WRITE_PRIORITY = 2;
@@ -73,7 +77,12 @@ function isOrderingBarrier(request: CacheRequest): boolean {
);
}
+function isQueryDataWrite(request: CacheRequest): boolean {
+ return request.kind === 'write' || request.kind === 'hydrate';
+}
+
function requestPriority(request: CacheRequest): number {
+ if (request.kind === 'hydrate') return BACKGROUND_HYDRATION_PRIORITY;
if (request.kind === 'read') {
return request.priority === 'user-visible'
? USER_VISIBLE_READ_PRIORITY
@@ -81,7 +90,6 @@ function requestPriority(request: CacheRequest): number {
}
if (
request.kind === 'write' ||
- request.kind === 'hydrate' ||
request.kind === 'enqueue-optimistic-mutation' ||
request.kind === 'claim-next-mutation' ||
request.kind === 'commit-optimistic-write' ||
@@ -325,12 +333,24 @@ export class CacheWorkerCore {
);
if (segmentEnd === -1) segmentEnd = this.queue.length;
+ const firstQueryDataWrite = this.queue
+ .slice(0, segmentEnd)
+ .findIndex((queued) => isQueryDataWrite(queued.request));
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) {
+ const preservesWriteOrder =
+ !candidate ||
+ !isQueryDataWrite(candidate.request) ||
+ i === firstQueryDataWrite;
+ if (
+ candidate &&
+ selected &&
+ preservesWriteOrder &&
+ candidate.priority > selected.priority
+ ) {
index = i;
}
}
diff --git a/apps/web/src/lib/queries/soup/backfill.test.tsx b/apps/web/src/lib/queries/soup/backfill.test.tsx
new file mode 100644
index 0000000000..7134cecbc0
--- /dev/null
+++ b/apps/web/src/lib/queries/soup/backfill.test.tsx
@@ -0,0 +1,172 @@
+import { render } from '@solidjs/testing-library';
+import * as Effect from 'effect/Effect';
+import { createSignal, Show } from 'solid-js';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+ loadSoupBackfillCheckpoint,
+ runSoupBackfills,
+ type SoupBackfillParams,
+ useSoupBackfills,
+} from './backfill';
+
+const graphqlMocks = vi.hoisted(() => ({
+ hydrateGraphqlSoup: vi.fn(),
+}));
+
+vi.mock('@core/constant/featureFlags', () => ({
+ ENABLE_GRAPHQL_BACKFILL: true,
+}));
+
+vi.mock('@core/cross-tab/tab-leader', () => ({
+ createTabLeaderSignal: () => () => true,
+}));
+
+vi.mock('@service-storage/graphql/generated/graphql', () => ({
+ SoupBackfillDocument: {},
+}));
+
+vi.mock('@service-storage/graphql-soup', () => ({
+ getGraphqlSoupCacheHost: () => ({}),
+ hydrateGraphqlSoup: graphqlMocks.hydrateGraphqlSoup,
+}));
+
+const lane = (
+ checkpointId: string,
+ fetchPage: NonNullable<SoupBackfillParams['fetchPage']>
+): SoupBackfillParams => ({
+ checkpointId,
+ fetchPage,
+ input: {
+ limit: 1,
+ expand: true,
+ sortMethod: 'VIEWED_UPDATED',
+ },
+});
+
+function BackfillRunner(props: { userId: string }) {
+ useSoupBackfills(props.userId);
+ return null;
+}
+
+describe('runSoupBackfills', () => {
+ beforeEach(() => {
+ localStorage.clear();
+ graphqlMocks.hydrateGraphqlSoup.mockReset();
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it('runs each lane to completion before starting the next lane', async () => {
+ const order: string[] = [];
+ let finishFirstLane!: () => void;
+ const firstLaneFinished = new Promise<void>((resolve) => {
+ finishFirstLane = resolve;
+ });
+ const firstFetch = vi.fn(async () => {
+ order.push('first:start');
+ await firstLaneFinished;
+ order.push('first:end');
+ return { nextCursor: null };
+ });
+ const secondFetch = vi.fn(async () => {
+ order.push('second');
+ return { nextCursor: null };
+ });
+
+ const running = Effect.runPromise(
+ runSoupBackfills('user-1', [
+ lane('first-lane', firstFetch),
+ lane('second-lane', secondFetch),
+ ])
+ );
+
+ await vi.waitFor(() => expect(firstFetch).toHaveBeenCalledOnce());
+ expect(secondFetch).not.toHaveBeenCalled();
+
+ finishFirstLane();
+ await running;
+
+ expect(order).toEqual(['first:start', 'first:end', 'second']);
+ expect(loadSoupBackfillCheckpoint('user-1', 'first-lane').completed).toBe(
+ true
+ );
+ expect(loadSoupBackfillCheckpoint('user-1', 'second-lane').completed).toBe(
+ true
+ );
+ });
+
+ it('continues to later lanes after a lane exhausts its retries', async () => {
+ vi.useFakeTimers();
+ const failedFetch = vi.fn(async () => {
+ throw new Error('failed lane');
+ });
+ const laterFetch = vi.fn(async () => ({ nextCursor: null }));
+
+ const running = Effect.runPromise(
+ runSoupBackfills('user-1', [
+ lane('failed-lane', failedFetch),
+ lane('later-lane', laterFetch),
+ ])
+ );
+
+ await vi.advanceTimersByTimeAsync(31_000);
+ await running;
+
+ expect(failedFetch).toHaveBeenCalledTimes(6);
+ expect(laterFetch).toHaveBeenCalledOnce();
+ expect(loadSoupBackfillCheckpoint('user-1', 'failed-lane').completed).toBe(
+ false
+ );
+ expect(loadSoupBackfillCheckpoint('user-1', 'later-lane').completed).toBe(
+ true
+ );
+ });
+
+ it('cancels the current backfill and starts a new one when the user changes', async () => {
+ const fetchSignals: AbortSignal[] = [];
+ graphqlMocks.hydrateGraphqlSoup.mockImplementation(
+ (_document, _variables, options: { signal: AbortSignal }) =>
+ new Promise((_resolve, reject) => {
+ fetchSignals.push(options.signal);
+ options.signal.addEventListener(
+ 'abort',
+ () =>
+ reject(
+ options.signal.reason ??
+ new DOMException('Aborted', 'AbortError')
+ ),
+ { once: true }
+ );
+ })
+ );
+ const [userId, setUserId] = createSignal<string | undefined>('user-1');
+ const rendered = render(() => (
+ <Show when={userId()} keyed>
+ {(currentUserId) => <BackfillRunner userId={currentUserId} />}
+ </Show>
+ ));
+
+ await vi.waitFor(() =>
+ expect(graphqlMocks.hydrateGraphqlSoup).toHaveBeenCalledOnce()
+ );
+ expect(
+ loadSoupBackfillCheckpoint('user-1', 'core-entities').scanStartedAt
+ ).not.toBeNull();
+
+ setUserId('user-2');
+
+ await vi.waitFor(() =>
+ expect(graphqlMocks.hydrateGraphqlSoup).toHaveBeenCalledTimes(2)
+ );
+ expect(fetchSignals[0]?.aborted).toBe(true);
+ expect(fetchSignals[1]?.aborted).toBe(false);
+ expect(
+ loadSoupBackfillCheckpoint('user-2', 'core-entities').scanStartedAt
+ ).not.toBeNull();
+
+ rendered.unmount();
+ expect(fetchSignals[1]?.aborted).toBe(true);
+ });
+});
diff --git a/apps/web/src/lib/queries/soup/backfill.ts b/apps/web/src/lib/queries/soup/backfill.ts
index 31698f3a85..4a8f923a33 100644
--- a/apps/web/src/lib/queries/soup/backfill.ts
+++ b/apps/web/src/lib/queries/soup/backfill.ts
@@ -9,24 +9,20 @@ import {
getGraphqlSoupCacheHost,
hydrateGraphqlSoup,
} from '@service-storage/graphql-soup';
-import { useQueries, useQueryClient } from '@tanstack/solid-query';
-import {
- type Accessor,
- createEffect,
- createSignal,
- on,
- onCleanup,
-} from 'solid-js';
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+import * as Schedule from 'effect/Schedule';
+import { createEffect, onCleanup } from 'solid-js';
// Bump when a default backfill input changes so persisted opaque cursors
// cannot retain the previous server-side filters.
const BACKFILL_VERSION = 6;
-const PAGE_LIMIT = 250;
+const PAGE_LIMIT = 100;
// Five threads × twenty messages reaches the backend's 100-message cap.
const EMAIL_CONTENT_PAGE_LIMIT = 5;
const PAGE_DELAY_MS = 2_000;
-const INITIAL_RETRY_DELAY_MS = 1_000;
-const MAX_RETRY_DELAY_MS = 30_000;
+const BACKFILL_RETRY_COUNT = 5;
+const BACKFILL_RETRY_SCHEDULE = Schedule.exponential('1 second');
const EXCLUDED_ENTITY_ID = '00000000-0000-0000-0000-000000000000';
type SoupBackfillFetchPage = (
@@ -118,7 +114,7 @@ export const AUXILIARY_SOUP_BACKFILL_LANE: SoupBackfillParams = {
},
};
-/** Independently checkpointed backfills started together by the coordinator. */
+/** Independently checkpointed backfills run serially in priority order. */
export const DEFAULT_SOUP_BACKFILL_LANES = [
CORE_SOUP_BACKFILL_LANE,
EMAIL_SOUP_BACKFILL_LANE,
@@ -238,32 +234,6 @@ export function resetSoupBackfillCheckpoint(
}
}
-function abortReason(signal: AbortSignal): unknown {
- return signal.reason ?? new DOMException('Aborted', 'AbortError');
-}
-
-function delay(ms: number, signal: AbortSignal): Promise<void> {
- if (signal.aborted) return Promise.reject(abortReason(signal));
-
- return new Promise((resolve, reject) => {
- const timeout = setTimeout(resolve, ms);
- signal.addEventListener(
- 'abort',
- () => {
- clearTimeout(timeout);
- reject(abortReason(signal));
- },
- { once: true }
- );
- });
-}
-
-/** Retry after 1s, 2s, 4s, 8s, and so on, capped at 30s. */
-function backfillRetryDelay(attempt: number): number {
- const exponentialDelay = INITIAL_RETRY_DELAY_MS * 2 ** attempt;
- return Math.min(exponentialDelay, MAX_RETRY_DELAY_MS);
-}
-
function and<T>(left: T | null | undefined, right: T): T {
return left ? ({ and: { left, right } } as T) : right;
}
@@ -310,12 +280,13 @@ export function withUpdatedSince(
};
}
-export async function runSoupBackfill(
+export const runSoupBackfill = Effect.fn('runSoupBackfill')(function* (
userId: string,
- params: SoupBackfillParams,
- signal: AbortSignal
-): Promise<void> {
- let checkpoint = loadSoupBackfillCheckpoint(userId, params.checkpointId);
+ params: SoupBackfillParams
+) {
+ let checkpoint = yield* Effect.sync(() =>
+ loadSoupBackfillCheckpoint(userId, params.checkpointId)
+ );
// `completed` only marks the end of one pass. A later invocation resets
// pagination so it can run another pass narrowed by the stored updatedSince.
@@ -328,12 +299,15 @@ export async function runSoupBackfill(
completed: false,
scanStartedAt: new Date().toISOString(),
};
- saveSoupBackfillCheckpoint(checkpoint, params.checkpointId);
+ yield* Effect.sync(() =>
+ saveSoupBackfillCheckpoint(checkpoint, params.checkpointId)
+ );
}
const passInput = withUpdatedSince(params.input, checkpoint.updatedSince);
+ const fetchPage = params.fetchPage ?? fetchSoupPage;
- while (!signal.aborted) {
+ while (true) {
const input: GraphqlSoupInput = checkpoint.nextCursor
? {
continuation: {
@@ -345,8 +319,9 @@ export async function runSoupBackfill(
: { initial: passInput };
// Hydration returns only the cursor projection. Cache-only entity payloads
// are persisted without being materialized back into this page.
- const fetchPage = params.fetchPage ?? fetchSoupPage;
- const page = await fetchPage(input, { signal });
+ const page = yield* Effect.tryPromise((signal) =>
+ fetchPage(input, { signal })
+ );
const completed = page.nextCursor == null;
checkpoint = {
@@ -364,87 +339,56 @@ export async function runSoupBackfill(
}
: {}),
};
- saveSoupBackfillCheckpoint(checkpoint, params.checkpointId);
+ yield* Effect.sync(() =>
+ saveSoupBackfillCheckpoint(checkpoint, params.checkpointId)
+ );
if (checkpoint.completed) return;
- await delay(params.pageDelayMs ?? PAGE_DELAY_MS, signal);
+ yield* Effect.sleep(params.pageDelayMs ?? PAGE_DELAY_MS);
}
+});
- throw abortReason(signal);
-}
+/** Runs each backfill lane to completion before starting the next lane. */
+export const runSoupBackfills = Effect.fn('runSoupBackfills')(function* (
+ userId: string,
+ lanes: readonly SoupBackfillParams[] = DEFAULT_SOUP_BACKFILL_LANES
+) {
+ yield* Effect.forEach(
+ lanes,
+ (lane) =>
+ runSoupBackfill(userId, lane).pipe(
+ Effect.retry({
+ times: BACKFILL_RETRY_COUNT,
+ schedule: BACKFILL_RETRY_SCHEDULE,
+ }),
+ Effect.ignore
+ ),
+ { concurrency: 1, discard: true }
+ );
+});
/**
- * Slowly fills the browser GraphQL cache through independently checkpointed
- * lanes. Every lane starts together on the elected tab.
+ * Runs the checkpointed backfill Effect while this tab owns leadership.
+ * Interrupting the fiber cancels the active fetch or inter-page sleep.
*/
-export function useSoupBackfills(userId: Accessor<string | undefined>) {
- const queryClient = useQueryClient();
+export function useSoupBackfills(userId: string): void {
const isLeader = createTabLeaderSignal(
`graphql-soup-backfill:v${BACKFILL_VERSION}:coordinator`
);
- const initialLeadershipController = new AbortController();
- const initiallyLeader = isLeader();
- if (!initiallyLeader) initialLeadershipController.abort();
- const [leadership, setLeadership] = createSignal({
- isLeader: initiallyLeader,
- controller: initialLeadershipController,
- });
- createEffect(
- on(
- isLeader,
- (leader) => {
- setLeadership((current) => {
- current.controller.abort();
- const controller = new AbortController();
- if (!leader) {
- controller.abort();
- void queryClient.cancelQueries({
- queryKey: ['graphql-soup-backfill', BACKFILL_VERSION],
- });
- }
- return { isLeader: leader, controller };
- });
- },
- { defer: true }
- )
- );
-
- onCleanup(() => leadership().controller.abort());
-
- return useQueries(() => {
- const currentUserId = userId();
- const currentLeadership = leadership();
- const backfillEnabled =
- ENABLE_GRAPHQL_BACKFILL &&
- currentUserId !== undefined &&
- getGraphqlSoupCacheHost() !== undefined &&
- currentLeadership.isLeader;
-
- return {
- queries: DEFAULT_SOUP_BACKFILL_LANES.map((lane) => ({
- queryKey: [
- 'graphql-soup-backfill',
- BACKFILL_VERSION,
- currentUserId,
- lane.checkpointId,
- ] as const,
- enabled: backfillEnabled,
- queryFn: ({ signal }: { signal: AbortSignal }) =>
- runSoupBackfill(
- currentUserId!,
- lane,
- AbortSignal.any([signal, currentLeadership.controller.signal])
- ),
- networkMode: 'online' as const,
- retry: 5,
- retryDelay: backfillRetryDelay,
- // A completed lane stays fresh for this QueryClient lifetime. A new
- // session starts another watermark-based pass from its checkpoint.
- staleTime: Infinity,
- refetchOnWindowFocus: false,
- })),
- };
+ createEffect(() => {
+ if (
+ !ENABLE_GRAPHQL_BACKFILL ||
+ getGraphqlSoupCacheHost() === undefined ||
+ !isLeader()
+ ) {
+ return;
+ }
+
+ const fiber = Effect.runFork(runSoupBackfills(userId));
+ onCleanup(() => {
+ Effect.runFork(Fiber.interrupt(fiber));
+ });
});
}
diff --git a/apps/web/src/routes/Root.tsx b/apps/web/src/routes/Root.tsx
index 4fd30aa106..6f0a25e785 100644
--- a/apps/web/src/routes/Root.tsx
+++ b/apps/web/src/routes/Root.tsx
@@ -408,6 +408,11 @@ function ConfiguredGlobalAppStateProvider(props: ParentProps) {
);
}
+function SoupBackfillSideEffect(props: { userId: string }) {
+ useSoupBackfills(props.userId);
+ return null;
+}
+
/** Sets user info for observability, analytics, and login cookie. Must be inside QueryClientProvider. */
function UserInfoSideEffects() {
const analytics = useAnalytics();
@@ -418,8 +423,6 @@ function UserInfoSideEffects() {
// Set user info for observability and analytics
const userInfo = useUserInfo();
- useSoupBackfills(() => userInfo()?.id);
-
// Keep the active theme following the OS color scheme when auto-detect is on.
systemThemeEffect();
@@ -463,7 +466,11 @@ function UserInfoSideEffects() {
})
);
- return null;
+ return (
+ <Show when={userInfo()?.id} keyed>
+ {(userId) => <SoupBackfillSideEffect userId={userId} />}
+ </Show>
+ );
}
const clearBodyInlineStyleColor = () => {