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(soup): stop hidden tabs evaluating lists on every cache change (#9791)

Eric Hayes5e4df40cc7d8
diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.md
index 546a1349ea..9e303ed031 100644
--- a/apps/web/AGENTS.md
+++ b/apps/web/AGENTS.md
@@ -542,6 +542,13 @@ resolved session ID; keep the existing `AgentSessionProvider` subscription to
- Coalesce broad browser cache-change hints across the coordinator's in-flight
backlog, not the engine's per-message queue; keep reset fences, mutation
settlements, and query-specific invalidations immediate.
+- Open tabs share one cache engine, so a source that reads on cache changes must
+ not read while hidden: use `createVisibleRefresh` to throttle too, or
+ `createHiddenDeferral` when its own reads already coalesce. Initial and
+ explicit reads still run.
+- Report cache operation failures through `createCacheErrorThrottle`: one owner
+ loss rejects every queued operation, and each report reaches the console and
+ session replay. The next report for that kind carries `cache.suppressed_count`.
- Retry still-current query reads once when engine replacement invalidates their
snapshot; do not strand urql's in-flight key or revive torn-down or superseded reads.
Keep network forwarding deduplicated and cache-only reads off the network.
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/context/LexicalWrapperContext.tsx b/apps/web/src/lib/core/component/LexicalMarkdown/context/LexicalWrapperContext.tsx
index 8402e33473..b2ae85a84e 100644
--- a/apps/web/src/lib/core/component/LexicalMarkdown/context/LexicalWrapperContext.tsx
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/context/LexicalWrapperContext.tsx
@@ -9,6 +9,7 @@ import {
RegisteredNodesByType,
SupportedNodeTypes,
} from '@macro-inc/lexical-core';
+import { Telemetry } from '@macro-inc/observability';
import type { NodeKey } from 'lexical';
import {
createEditor,
@@ -101,7 +102,11 @@ export function createLexicalWrapper({
theme: theme ?? baseTheme,
namespace: namespace + '_' + _id,
nodes: [...nodes, ...replacements],
- onError: console.error,
+ onError: (error) =>
+ Telemetry.error(error, {
+ 'error.source': 'lexical',
+ 'lexical.editor_type': type,
+ }),
});
const plugins = createPluginManager(editor, type);
diff --git a/apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.ts b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.ts
index 29d51b386e..e3c60e3b9b 100644
--- a/apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.ts
+++ b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.ts
@@ -265,3 +265,25 @@ it('does not create root performance spans for repeated cache evaluations', asyn
span.mockRestore();
}
});
+
+it('does not read on cache changes while hidden, then catches up once', async () => {
+ const visibility = vi.spyOn(document, 'visibilityState', 'get');
+ try {
+ const state = setup();
+ state.requests[0].resolve(snapshot());
+ await flush();
+
+ visibility.mockReturnValue('hidden');
+ state.change('2');
+ state.change('3');
+ state.generations.forEach((cb) => cb({ storage: 'preserved' }));
+ expect(state.requests).toHaveLength(1);
+
+ visibility.mockReturnValue('visible');
+ document.dispatchEvent(new Event('visibilitychange'));
+ expect(state.requests).toHaveLength(2);
+ expect(state.requests[1].args.liveQuery?.since).toBeUndefined();
+ } finally {
+ visibility.mockRestore();
+ }
+});
diff --git a/apps/web/src/lib/queries/soup/graphql/create-predicate-query.ts b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.ts
index f09dac173e..4510eddfaa 100644
--- a/apps/web/src/lib/queries/soup/graphql/create-predicate-query.ts
+++ b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.ts
@@ -18,6 +18,7 @@ import {
type EntityFilterCacheArgs,
parseCacheRevision,
} from '../../../graphql-cache/protocol';
+import { createHiddenDeferral } from '../../visible-refresh';
import { soupCacheTelemetry } from './cache-activity-telemetry';
/** A declared source and generated fragment; no mutation-specific query updates. */
@@ -242,10 +243,13 @@ export function createPredicateQuery<T extends object>(options: {
if (!running) runPromise = run();
};
requestRefresh = refresh;
+ // Every open tab shares one cache engine. A hidden tab keeps a dirty bit
+ // instead of reading on each revision; initial and explicit reads still run.
+ const deferral = createHiddenDeferral(refresh);
const unsubscribeChanges = host.onCacheChanged(
(revision) => {
latest = revision;
- refresh();
+ deferral.request();
},
{ includeHydration: true }
);
@@ -258,11 +262,12 @@ export function createPredicateQuery<T extends object>(options: {
setData(undefined);
setStatus('loading');
});
- refresh();
+ deferral.request();
});
refresh();
onCleanup(() => {
active = false;
+ deferral.dispose();
unsubscribeChanges();
unsubscribeGeneration();
// Serialize release after any pending read, so disposal cannot recreate
diff --git a/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts b/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts
index f3b156f89e..c2c004b716 100644
--- a/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts
+++ b/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts
@@ -50,6 +50,7 @@ import {
} from '../../../service-clients/service-storage/graphql-soup';
import { createUrqlInfiniteQuery } from '../../../urql-solid/create-urql-infinite-query';
import type { UrqlInfiniteData } from '../../../urql-solid/types';
+import { createHiddenDeferral } from '../../visible-refresh';
import { registerGraphqlSoupRevalidations } from './active-queries';
import { soupCacheTelemetry } from './cache-activity-telemetry';
import { createPredicateQuery } from './create-predicate-query';
@@ -320,6 +321,13 @@ export function createSoupLiveQuery(
// Keep network data usable while the local cache is unavailable.
}
};
+ let latestRevision: CacheRevision | undefined;
+ // Every open tab shares one cache engine. A hidden tab keeps a dirty bit
+ // instead of evaluating this list on each revision or engine replacement.
+ const deferral = createHiddenDeferral(() => {
+ if (latestRevision !== undefined) setCurrentCacheRevision(latestRevision);
+ else fireAndForget(observeCurrentRevision(), 'soup-live-query');
+ });
const unsubscribeChanges = host.onCacheChanged(
(revision) => {
cacheObservation += 1;
@@ -331,7 +339,8 @@ export function createSoupLiveQuery(
staleFallbackStartedAt = performance.now();
recordAuthority('stale-fallback');
}
- setCurrentCacheRevision(revision);
+ latestRevision = revision;
+ deferral.request();
},
// The authority watermark must observe the same writes as the live view.
{ includeHydration: true }
@@ -340,12 +349,14 @@ export function createSoupLiveQuery(
soupCacheTelemetry.record('generation');
cacheGeneration += 1;
invalidateGeneration();
- fireAndForget(observeCurrentRevision(), 'soup-live-query');
+ latestRevision = undefined;
+ deferral.request();
});
fireAndForget(observeCurrentRevision(), 'soup-live-query');
onCleanup(() => {
finishStaleFallback(true);
cacheGeneration += 1;
+ deferral.dispose();
unsubscribeChanges();
unsubscribeGeneration();
});
diff --git a/apps/web/src/lib/queries/soup/graphql/items.test.ts b/apps/web/src/lib/queries/soup/graphql/items.test.ts
index 28e76fc5b2..3726d39f90 100644
--- a/apps/web/src/lib/queries/soup/graphql/items.test.ts
+++ b/apps/web/src/lib/queries/soup/graphql/items.test.ts
@@ -4425,6 +4425,76 @@ describe('createGraphqlSoupAstItemsQuery', () => {
dispose();
});
+ it('skips local evaluation on cache changes while hidden and catches up once', async () => {
+ const fake = makeFakeClient();
+ getGraphqlSoupClientMock.mockReturnValue(fake.client);
+ let currentRevision = REVISION_1;
+ let notifyCacheChanged!: (revision: string) => void;
+ let notifyGenerationChanged!: () => void;
+ getGraphqlSoupCacheHostMock.mockReturnValue({
+ currentRevision: async () => currentRevision,
+ onCacheChanged: (callback: (revision: string) => void) => {
+ notifyCacheChanged = callback;
+ return () => undefined;
+ },
+ onCacheGenerationChanged: (callback: () => void) => {
+ notifyGenerationChanged = callback;
+ return () => undefined;
+ },
+ entityFilter: entityFilterMock,
+ });
+ entityFilterMock.mockImplementation(async () => ({
+ kind: 'reconciled',
+ retainedKeys: [],
+ revision: currentRevision,
+ keys: [],
+ optimistic: false,
+ }));
+ readRecordsByKeysMock.mockImplementation(async () => ({
+ revision: currentRevision,
+ records: [],
+ }));
+ const visibility = vi.spyOn(document, 'visibilityState', 'get');
+ let dispose!: () => void;
+ createRoot((rootDispose) => {
+ dispose = rootDispose;
+ createGraphqlSoupAstItemsQuery(
+ () => ({ params: {}, body: {} }) as never,
+ () => ({ enabled: true })
+ );
+ });
+ try {
+ fake.executions[0]?.next(
+ graphqlSoupPage({
+ items: [{ id: 'item-0', type: 'document', name: 'Network item' }],
+ next_cursor: null,
+ }),
+ { source: 'live-network', revision: REVISION_1 }
+ );
+ await Promise.resolve();
+ entityFilterMock.mockClear();
+
+ visibility.mockReturnValue('hidden');
+ currentRevision = REVISION_2;
+ notifyCacheChanged(REVISION_2);
+ currentRevision = '3';
+ notifyCacheChanged('3');
+ notifyGenerationChanged();
+ currentRevision = '4';
+ notifyCacheChanged('4');
+ await Promise.resolve();
+ await Promise.resolve();
+ expect(entityFilterMock).not.toHaveBeenCalled();
+
+ visibility.mockReturnValue('visible');
+ document.dispatchEvent(new Event('visibilitychange'));
+ await vi.waitFor(() => expect(entityFilterMock).toHaveBeenCalledTimes(1));
+ } finally {
+ dispose();
+ visibility.mockRestore();
+ }
+ });
+
it('merges baseline survivors with candidates without resetting server pagination', async () => {
const fake = makeFakeClient();
getGraphqlSoupClientMock.mockReturnValue(fake.client);
diff --git a/apps/web/src/lib/queries/visible-refresh.test.ts b/apps/web/src/lib/queries/visible-refresh.test.ts
new file mode 100644
index 0000000000..9d62b44a57
--- /dev/null
+++ b/apps/web/src/lib/queries/visible-refresh.test.ts
@@ -0,0 +1,48 @@
+import { afterEach, expect, it, vi } from 'vitest';
+import { createHiddenDeferral } from './visible-refresh';
+
+const setVisibility = (value: DocumentVisibilityState) => {
+ vi.spyOn(document, 'visibilityState', 'get').mockReturnValue(value);
+};
+const dispatch = () => document.dispatchEvent(new Event('visibilitychange'));
+
+afterEach(() => vi.restoreAllMocks());
+
+it('runs every request synchronously while visible', () => {
+ const run = vi.fn();
+ const deferral = createHiddenDeferral(run);
+ deferral.request();
+ deferral.request();
+ expect(run).toHaveBeenCalledTimes(2);
+ deferral.dispose();
+});
+
+it('coalesces hidden requests into one run on becoming visible', () => {
+ setVisibility('hidden');
+ const run = vi.fn();
+ const deferral = createHiddenDeferral(run);
+ deferral.request();
+ deferral.request();
+ dispatch();
+ expect(run).not.toHaveBeenCalled();
+
+ setVisibility('visible');
+ dispatch();
+ dispatch();
+ expect(run).toHaveBeenCalledTimes(1);
+ deferral.dispose();
+});
+
+it('stays quiet when shown with nothing deferred or after disposal', () => {
+ const run = vi.fn();
+ const deferral = createHiddenDeferral(run);
+ dispatch();
+ expect(run).not.toHaveBeenCalled();
+
+ setVisibility('hidden');
+ deferral.request();
+ deferral.dispose();
+ setVisibility('visible');
+ dispatch();
+ expect(run).not.toHaveBeenCalled();
+});
diff --git a/apps/web/src/lib/queries/visible-refresh.ts b/apps/web/src/lib/queries/visible-refresh.ts
index 4c8631acbf..0e115725ae 100644
--- a/apps/web/src/lib/queries/visible-refresh.ts
+++ b/apps/web/src/lib/queries/visible-refresh.ts
@@ -73,3 +73,29 @@ export function createVisibleRefresh(
},
};
}
+
+/**
+ * Runs immediately while visible, with no throttle. A hidden tab keeps one dirty
+ * bit and runs once when it becomes visible, for a source whose own reads
+ * already coalesce.
+ *
+ * The caller must dispose it.
+ */
+export function createHiddenDeferral(run: () => void): {
+ request: () => void;
+ dispose: () => void;
+} {
+ let deferred = false;
+ const dispose = makeEventListener(document, 'visibilitychange', () => {
+ if (!deferred || document.visibilityState === 'hidden') return;
+ deferred = false;
+ run();
+ });
+ return {
+ request: () => {
+ deferred = document.visibilityState === 'hidden';
+ if (!deferred) run();
+ },
+ dispose,
+ };
+}
diff --git a/apps/web/src/lib/service-clients/service-storage/cache-error-throttle.test.ts b/apps/web/src/lib/service-clients/service-storage/cache-error-throttle.test.ts
new file mode 100644
index 0000000000..6a16f094bc
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-storage/cache-error-throttle.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { createCacheErrorThrottle } from './cache-error-throttle';
+
+describe('createCacheErrorThrottle', () => {
+ it('reports the first failure, then the count dropped in that minute', () => {
+ let time = 0;
+ const throttle = createCacheErrorThrottle(() => time);
+ const error = new Error('cache worker timeout: read');
+
+ expect(throttle.admit(error, 'query')).toEqual({
+ report: true,
+ suppressed: 0,
+ });
+ expect(throttle.admit(error, 'query').report).toBe(false);
+ expect(throttle.admit(error, 'query').report).toBe(false);
+
+ time = 60_000;
+ expect(throttle.admit(error, 'query')).toEqual({
+ report: true,
+ suppressed: 2,
+ });
+ });
+
+ it('treats failures that differ only by a number as one kind', () => {
+ const throttle = createCacheErrorThrottle(() => 0);
+
+ expect(
+ throttle.admit(new Error('owner epoch 81 was lost'), 'query').report
+ ).toBe(true);
+ expect(
+ throttle.admit(new Error('owner epoch 82 was lost'), 'query').report
+ ).toBe(false);
+ });
+
+ it('keeps different failures and operation kinds separate', () => {
+ const throttle = createCacheErrorThrottle(() => 0);
+ const error = new Error('cache worker timeout: read');
+
+ expect(throttle.admit(error, 'query').report).toBe(true);
+ expect(throttle.admit(error, 'subscription').report).toBe(true);
+ expect(throttle.admit(new Error('other'), 'query').report).toBe(true);
+ });
+});
diff --git a/apps/web/src/lib/service-clients/service-storage/cache-error-throttle.ts b/apps/web/src/lib/service-clients/service-storage/cache-error-throttle.ts
new file mode 100644
index 0000000000..410dd46565
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-storage/cache-error-throttle.ts
@@ -0,0 +1,31 @@
+const REPORT_INTERVAL_MS = 60_000;
+const MAX_TRACKED_ERRORS = 100;
+
+const errorMessage = (error: unknown): string =>
+ error instanceof Error ? error.message : String(error);
+
+/**
+ * Admits one report per minute for each kind of cache failure. Failures that
+ * differ only by a number, such as an owner epoch, count as one kind. The next
+ * admitted report carries how many were dropped since the last one.
+ */
+export function createCacheErrorThrottle(now: () => number = Date.now) {
+ const seen = new Map<string, { reportedAt: number; suppressed: number }>();
+ return {
+ admit(
+ error: unknown,
+ operationKind?: string
+ ): { report: boolean; suppressed: number } {
+ const key = `${operationKind ?? ''}:${errorMessage(error).replace(/\d+/g, '#')}`;
+ const entry = seen.get(key);
+ const at = now();
+ if (entry && at - entry.reportedAt < REPORT_INTERVAL_MS) {
+ entry.suppressed += 1;
+ return { report: false, suppressed: 0 };
+ }
+ if (!entry && seen.size >= MAX_TRACKED_ERRORS) seen.clear();
+ seen.set(key, { reportedAt: at, suppressed: 0 });
+ return { report: true, suppressed: entry?.suppressed ?? 0 };
+ },
+ };
+}
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts
index 4c4c85fe0a..1ec4fdcbd2 100644
--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts
+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts
@@ -88,6 +88,7 @@ import { match } from 'ts-pattern';
import { delegateChannelNotificationRefresh } from '../../queries/channel/notification-refresh';
import { soupOptimisticResolvers } from '../../queries/optimistic-resolvers';
import { resolveCrmExternalWriteTypes } from '../../queries/soup/graphql/external-write-scope';
+import { createCacheErrorThrottle } from './cache-error-throttle';
import { createCacheRecovery } from './cache-recovery';
import { emailCacheDeletionKeys } from './email-cache-deletions';
import { emailThreadSortTs } from './email-thread-sort';
@@ -751,6 +752,7 @@ export function getGraphqlSoupClient(): Client {
if (cachedClient) return cachedClient;
disposeUncachedRealtimeClient();
cachedClient = (() => {
+ const cacheErrorThrottle = createCacheErrorThrottle();
const reportCacheError = (
error: unknown,
phase: 'initialization' | 'operation',
@@ -768,6 +770,12 @@ export function getGraphqlSoupClient(): Client {
isOwnerLockUnavailableError(error)
)
return;
+ // One owner loss rejects every queued operation at once.
+ const throttled =
+ phase === 'operation'
+ ? cacheErrorThrottle.admit(error, operationKind)
+ : { report: true, suppressed: 0 };
+ if (!throttled.report) return;
// Caught cache failures never reach window.unhandledrejection. Report
// them through the Datadog-bound exporter without query/variable data.
Telemetry.error(error, {
@@ -775,6 +783,9 @@ export function getGraphqlSoupClient(): Client {
'cache.backend': native ? 'native' : 'turso-wasm-opfs',
'cache.phase': phase,
...(operationKind ? { 'cache.operation_kind': operationKind } : {}),
+ ...(throttled.suppressed > 0
+ ? { 'cache.suppressed_count': throttled.suppressed }
+ : {}),
});
} catch {
// Observability must not prevent network fallback or cache cleanup.