Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

perf(web): reduce cold cache restore processing (#1089)

Gener89b59127f8f4
diff --git a/src/web/src/app/c/community-layout-client.tsx b/src/web/src/app/c/community-layout-client.tsx
index 570e83a81..ab0ac38c6 100644
--- a/src/web/src/app/c/community-layout-client.tsx
+++ b/src/web/src/app/c/community-layout-client.tsx
@@ -16,6 +16,7 @@ import { useHydratedClient } from "@/components/community/shell/use-hydrated-cli
import { clearCommunityColdEntryAttempts, retireCommunityColdEntryAttempt } from "@/lib/community/last-community-route"
import type { CurrentUser } from "@/contexts/community/current-user"
import { CommunityApplicationNavigation } from "@/contexts/community/application-navigation"
+import { preparePersistedCache } from "@/lib/query-persister"
export function CommunityLayoutClient() {
const hydrated = useHydratedClient()
@@ -43,6 +44,10 @@ function CommunityAccountEntry({ pathname }: { pathname: string }) {
const [retry, setRetry] = useState(0)
const [signOutFailed, setSignOutFailed] = useState(false)
+ useEffect(() => {
+ if (session.isPending) void preparePersistedCache().catch(() => undefined)
+ }, [session.isPending])
+
useEffect(() => {
if (!ready || currentUserId) return
clearCommunityColdEntryAttempts()
diff --git a/src/web/src/app/c/layout.dom.test.ts b/src/web/src/app/c/layout.dom.test.ts
index 6687b0a63..fba7d79e9 100644
--- a/src/web/src/app/c/layout.dom.test.ts
+++ b/src/web/src/app/c/layout.dom.test.ts
@@ -8,10 +8,12 @@ const mocks = vi.hoisted(() => ({
isPending: true, error: null as null | Error, refetch: vi.fn(async () => {}) },
signOut: vi.fn(async () => ({ error: null })), mounted: vi.fn(), unmounted: vi.fn(),
retireAttempt: vi.fn(), clearAttempts: vi.fn(),
+ prepareCache: vi.fn(async () => {}),
}))
vi.mock("next/navigation", () => ({ usePathname: () => mocks.pathname, useSearchParams: () => new URLSearchParams(mocks.search), useRouter: () => mocks.router, notFound: () => { throw new Error("not-found") } }))
vi.mock("@/lib/auth-client", () => ({ useSession: () => mocks.session, authClient: { signOut: mocks.signOut } }))
vi.mock("@/lib/community/last-community-route", () => ({ retireCommunityColdEntryAttempt: mocks.retireAttempt, clearCommunityColdEntryAttempts: mocks.clearAttempts }))
+vi.mock("@/lib/query-persister", () => ({ preparePersistedCache: mocks.prepareCache }))
vi.mock("./community-shell", () => ({ CommunityShell: ({ currentUser, children }: { currentUser: { id: string }; children: ReactNode }) => {
useEffect(() => { mocks.mounted(currentUser.id); return () => mocks.unmounted(currentUser.id) }, [currentUser.id])
return createElement("main", { "data-testid": "private-shell", "data-account": currentUser.id }, children)
@@ -34,6 +36,31 @@ beforeEach(() => {
const tree = () => createElement(CommunityLayoutClient)
describe("client account startup", () => {
+ it("prepares local storage during pending auth without revealing or delaying the private account", async () => {
+ let prepared!: () => void
+ mocks.prepareCache.mockImplementationOnce(() => new Promise<void>(resolve => { prepared = resolve }))
+ mocks.session.data = { user: user("unconfirmed") }
+ const view = render(tree())
+ expect(mocks.prepareCache).toHaveBeenCalledOnce()
+ expect(mocks.mounted).not.toHaveBeenCalled()
+ expect(screen.queryByTestId("private-shell")).not.toBeInTheDocument()
+ mocks.session.data = { user: user("confirmed") }; mocks.session.isPending = false
+ view.rerender(tree())
+ expect(screen.getByTestId("private-shell")).toHaveAttribute("data-account", "confirmed")
+ await act(async () => { prepared() })
+ expect(mocks.mounted).toHaveBeenCalledExactlyOnceWith("confirmed")
+ })
+ it("keeps preparation failure separate from the original session and Retry owner", async () => {
+ mocks.prepareCache.mockRejectedValueOnce(new Error("IDB open failed"))
+ const view = render(tree())
+ await act(async () => {})
+ expect(screen.queryByTestId("private-shell")).not.toBeInTheDocument()
+ expect(mocks.router.replace).not.toHaveBeenCalled()
+ expect(mocks.session.refetch).not.toHaveBeenCalled()
+ mocks.session.data = { user: user("confirmed") }; mocks.session.isPending = false
+ view.rerender(tree())
+ expect(screen.getByTestId("private-shell")).toHaveAttribute("data-account", "confirmed")
+ })
it("renders a neutral frame before authentication and mounts an account without a profile prerequisite", () => {
const view = render(tree())
expect(screen.getByTestId("pending")).toHaveAttribute("data-pathname", "/c/me/machines")
diff --git a/src/web/src/lib/query-persister.cold-restore.test.ts b/src/web/src/lib/query-persister.cold-restore.test.ts
new file mode 100644
index 000000000..07c2d6308
--- /dev/null
+++ b/src/web/src/lib/query-persister.cold-restore.test.ts
@@ -0,0 +1,151 @@
+import "fake-indexeddb/auto"
+import { del, get, set } from "idb-keyval"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { dehydrate, QueryClient } from "@tanstack/react-query"
+import { persistQueryClientRestore, type PersistedClient } from "@tanstack/react-query-persist-client"
+import { canonicalChannelRow } from "./community-db/schema"
+import { communityKeys } from "./query-keys"
+import * as persistence from "./query-persister"
+
+const key = (user: string) => `${persistence.PERSIST_CACHE_PREFIX}:${user}:client`
+const accountKey = (user: string) => `${persistence.PERSIST_CACHE_PREFIX}:${user}:account-epoch`
+
+function snapshot(user: string, content = "Cached"): PersistedClient {
+ const client = new QueryClient()
+ client.setQueryData(communityKeys.communityDbCollection(user, "channels"), ["a", "b"].map(id => canonicalChannelRow({ id, type: "dm", name: id, preview: content })))
+ client.setQueryData(communityKeys.communityDbCollection(user, "messages"), ["a", "b"].map(channelId => ({ id: `m-${channelId}`, channelId, type: "chat", resourceComplete: false, authorId: user, authorName: "Viewer", authorAvatar: "V", authorAvatarVersion: 0, seq: 1, content })))
+ const result = { timestamp: Date.now(), buster: persistence.PERSIST_BUSTER, clientState: dehydrate(client) }
+ client.clear()
+ return result
+}
+
+function messages(value: PersistedClient | undefined) {
+ return value?.clientState.queries.find(query => query.queryKey[3] === "messages")?.state.data
+}
+
+afterEach(() => vi.restoreAllMocks())
+
+describe("cold IDB snapshot processing", () => {
+ it("decodes unchanged qualified bytes once without a restore JSON round trip", async () => {
+ const user = "cold-once", writer = persistence.createIdbPersister(user)
+ await writer.persistClient(snapshot(user, "cached body".repeat(2000)))
+ const raw = await get<string>(key(user))
+ expect(raw).toEqual(expect.any(String))
+ const parse = vi.spyOn(JSON, "parse")
+ const stringify = vi.spyOn(JSON, "stringify")
+ const reader = persistence.createIdbPersister(user)
+ const restored = await reader.restoreClient()
+ expect(messages(restored)).toHaveLength(2)
+ expect(parse.mock.calls.filter(([input]) => input === raw)).toHaveLength(1)
+ expect(stringify).not.toHaveBeenCalled()
+ })
+
+ it("rereads a payload changed after qualification instead of publishing the provisional decode", async () => {
+ const user = "cold-changed", writer = persistence.createIdbPersister(user)
+ await writer.persistClient(snapshot(user, "Old"))
+ const reader = persistence.createIdbPersister(user)
+ expect(await reader.isCurrent()).toBe(true)
+ await set(key(user), JSON.stringify({ ...snapshot(user, "New"), version: persistence.PERSIST_VERSION, channelFences: [] }))
+ expect(messages(await reader.restoreClient())).toEqual(expect.arrayContaining([expect.objectContaining({ content: "New" })]))
+ })
+
+ it.each(["removed", "corrupt", "version", "buster"])("rejects a %s payload written after qualification", async kind => {
+ const user = `cold-${kind}`, writer = persistence.createIdbPersister(user)
+ await writer.persistClient(snapshot(user))
+ const reader = persistence.createIdbPersister(user)
+ await reader.isCurrent()
+ if (kind === "removed") await del(key(user))
+ else if (kind === "corrupt") await set(key(user), "{")
+ else await set(key(user), JSON.stringify({ ...snapshot(user), version: kind === "version" ? 5 : persistence.PERSIST_VERSION, buster: kind === "buster" ? "old" : persistence.PERSIST_BUSTER, channelFences: [] }))
+ expect(await reader.restoreClient()).toBeUndefined()
+ expect(await get(key(user))).toBeUndefined()
+ })
+
+ it.each(["device", "account", "scope"])("rejects a late %s retirement without deleting a newer owner's bytes", async kind => {
+ const user = `cold-fence-${kind}`, writer = persistence.createIdbPersister(user)
+ await writer.persistClient(snapshot(user))
+ const reader = persistence.createIdbPersister(user)
+ await reader.isCurrent()
+ const raw = await get(key(user))
+ const fenceKey = kind === "device" ? "alook:qc:device-epoch" : kind === "account" ? accountKey(user) : `${key(user)}:epoch`
+ await set(fenceKey, kind === "scope" ? { version: persistence.PERSIST_VERSION, epoch: crypto.randomUUID() } : crypto.randomUUID())
+ expect(await reader.restoreClient()).toBeUndefined()
+ await reader.removeClient()
+ expect(await get(key(user))).toBe(raw)
+ })
+
+ it("applies freshly read channel fences even when the payload bytes did not change", async () => {
+ const user = "cold-channel-fence", writer = persistence.createIdbPersister(user)
+ await writer.persistClient(snapshot(user))
+ const raw = await get(key(user))
+ const reader = persistence.createIdbPersister(user)
+ await reader.isCurrent()
+ await set(`${accountKey(user)}:channels`, new Map([["a", { epoch: crypto.randomUUID(), deleted: true }]]))
+ expect(messages(await reader.restoreClient())).toEqual([expect.objectContaining({ channelId: "b" })])
+ expect(await get(key(user))).toBe(raw)
+ })
+
+ it.each(["expired", "missing-timestamp"])("keeps native removal and subsequent fresh persistence after %s", async kind => {
+ const user = `cold-native-${kind}`, writer = persistence.createIdbPersister(user)
+ await writer.persistClient({ ...snapshot(user), timestamp: kind === "expired" ? Date.now() - persistence.PERSIST_MAX_AGE_MS - 1 : 0 })
+ const reader = persistence.createIdbPersister(user), client = new QueryClient()
+ await persistQueryClientRestore({ queryClient: client, persister: reader, maxAge: persistence.PERSIST_MAX_AGE_MS, buster: persistence.PERSIST_BUSTER })
+ expect(client.getQueryCache().getAll()).toEqual([])
+ expect(await get(key(user))).toBeUndefined()
+ expect(await reader.isCurrent()).toBe(true)
+ await reader.persistClient(snapshot(user, "Fresh"))
+ expect(messages(await reader.restoreClient())).toEqual(expect.arrayContaining([expect.objectContaining({ content: "Fresh" })]))
+ client.clear()
+ })
+
+ it("repeats key-only legacy cleanup for later old-software writes while preserving sibling data", async () => {
+ const user = "cold-legacy", writer = persistence.createIdbPersister(user)
+ await writer.persistClient(snapshot(user))
+ const legacy = `alook:qc:v2:${user}:client`
+ await set(legacy, "first legacy body")
+ await set("alook:qc:v2:other:client", "other account")
+ await set(`alook:qc:v2:${user}:preference`, "preference")
+ await set(`${persistence.PERSIST_CACHE_PREFIX}:${user}:application:client`, "application")
+ const valueCursor = vi.spyOn(IDBObjectStore.prototype, "openCursor")
+ const reader = persistence.createIdbPersister(user)
+ await reader.restoreClient()
+ expect(await get(legacy)).toBeUndefined()
+ await set(legacy, "later legacy body")
+ await reader.retireChannels(["a"], true)
+ expect(await get(legacy)).toBeUndefined()
+ expect(valueCursor).not.toHaveBeenCalled()
+ expect(await get("alook:qc:v2:other:client")).toBe("other account")
+ expect(await get(`alook:qc:v2:${user}:preference`)).toBe("preference")
+ expect(await get(`${persistence.PERSIST_CACHE_PREFIX}:${user}:application:client`)).toBe("application")
+ expect(messages(await reader.restoreClient())).toEqual([expect.objectContaining({ channelId: "b" })])
+ })
+})
+
+describe("account-free cache preparation", () => {
+ it("shares the native connection without accessing any private key or qualification", async () => {
+ vi.resetModules()
+ const fresh = await import("./query-persister")
+ const open = vi.spyOn(indexedDB, "open")
+ const methods = ["get", "put", "delete", "openCursor", "openKeyCursor"] as const
+ const spies = methods.map(method => vi.spyOn(IDBObjectStore.prototype, method))
+ await Promise.all([fresh.preparePersistedCache(), fresh.preparePersistedCache()])
+ expect(open).toHaveBeenCalledExactlyOnceWith("keyval-store")
+ for (const spy of spies) expect(spy).not.toHaveBeenCalled()
+ })
+
+ it("can retry a failed preparation through the same native connection owner", async () => {
+ vi.resetModules()
+ const fresh = await import("./query-persister")
+ const open = vi.spyOn(indexedDB, "open").mockImplementationOnce(() => {
+ const request = new IDBOpenDBRequest()
+ Object.defineProperty(request, "error", { value: new DOMException("Preparation failed", "UnknownError") })
+ queueMicrotask(() => request.onerror?.call(request, new Event("error")))
+ return request
+ })
+ await expect(fresh.preparePersistedCache()).rejects.toThrow("Preparation failed")
+ const owner = fresh.createIdbPersister("cold-retry")
+ await owner.persistClient(snapshot("cold-retry"))
+ expect(messages(await owner.restoreClient())).toHaveLength(2)
+ expect(open).toHaveBeenCalledTimes(2)
+ })
+})
diff --git a/src/web/src/lib/query-persister.ts b/src/web/src/lib/query-persister.ts
index 5348262e4..958ed304d 100644
--- a/src/web/src/lib/query-persister.ts
+++ b/src/web/src/lib/query-persister.ts
@@ -9,7 +9,7 @@ import type {
PersistedClient,
Persister,
} from "@tanstack/react-query-persist-client"
-import { createStore, promisifyRequest } from "idb-keyval"
+import { createStore, get, promisifyRequest } from "idb-keyval"
import { isCommunityListResourceKey, persistentCommunityListResource } from "@/lib/community/list-persistence"
import {
communityCollectionSchemas,
@@ -337,6 +337,10 @@ async function cacheTransaction<T>(
})
}
+export function preparePersistedCache(): Promise<void> {
+ return cacheTransaction("readonly", async () => undefined)
+}
+
async function readEligibility(store: IDBObjectStore, key: string, userId: string | null) {
const [device, scope, account, channels] = await Promise.all([
promisifyRequest<unknown>(store.get(DEVICE_EPOCH_KEY)),
@@ -350,7 +354,7 @@ async function readEligibility(store: IDBObjectStore, key: string, userId: strin
// Qualification starts when the account owner is created, before restore or
// any throttled persistence. Missing/corrupt eligibility never revives an old
// writer or trusts its payload; generation tombstones survive payload removal.
-function qualifyPersister(key: string, userId: string | null): Promise<PersistEligibility> {
+function qualifyPersister(key: string, userId: string | null, captureSnapshot: (raw: string, decoded: NonNullable<ReturnType<typeof decodeDiskSnapshot>>) => void): Promise<PersistEligibility> {
return cacheTransaction("readwrite", async (store) => {
await clearAccountRows(store, userId, true)
const raw = await promisifyRequest<unknown>(store.get(key))
@@ -360,7 +364,8 @@ function qualifyPersister(key: string, userId: string | null): Promise<PersistEl
const account = intact ? current.account as string : crypto.randomUUID()
const channels = intact ? current.channels as Map<string, ChannelDiskFence> : new Map<string, ChannelDiskFence>()
const currentScope = communityScopeEpoch(current.scope)
- const compatiblePayload = raw === undefined || Boolean(decodeDiskSnapshot(raw))
+ const decoded = decodeDiskSnapshot(raw)
+ const compatiblePayload = raw === undefined || Boolean(decoded)
let scope = currentScope && compatiblePayload ? currentScope : crypto.randomUUID()
if (!intact) {
for (const domain of ["community", "application"] as const) {
@@ -376,6 +381,7 @@ function qualifyPersister(key: string, userId: string | null): Promise<PersistEl
if (!isEpoch(current.device) || !currentScope || !compatiblePayload) store.delete(key)
if (!isEpoch(current.device)) store.put(device, DEVICE_EPOCH_KEY)
store.put({ version: PERSIST_VERSION, epoch: scope }, scopeEpochKey(key))
+ if (intact && isEpoch(current.device) && currentScope && decoded && typeof raw === "string") captureSnapshot(raw, decoded)
return { device, scope, account, channels }
})
}
@@ -399,17 +405,16 @@ async function withEligiblePersister<T>(
/** Native TanStack persister, qualified against durable device/account epochs. */
export function createIdbPersister(userId: string | null): QualifiedPersister {
const key = blobKeyFor(userId)
- const eligibility = qualifyPersister(key, userId)
+ let initialSnapshot: { raw: string; decoded: NonNullable<ReturnType<typeof decodeDiskSnapshot>> } | undefined
+ let captureInitialSnapshot = true
+ const discardInitialSnapshot = () => { captureInitialSnapshot = false; initialSnapshot = undefined }
+ const eligibility = qualifyPersister(key, userId, (raw, decoded) => { if (captureInitialSnapshot) initialSnapshot = { raw, decoded } })
// An unavailable IDB must also fail restore through the provider's onError;
// attach a handler immediately so qualification cannot reject unobserved.
void eligibility.catch(() => undefined)
- const persister = createAsyncStoragePersister({
+ const writer = createAsyncStoragePersister({
storage: {
- getItem: () => observeRestoreRead(() => withEligiblePersister(key, userId, eligibility, "readwrite", null, async (store, current) => {
- const decoded = decodeDiskSnapshot(await promisifyRequest<unknown>(store.get(key)))
- if (!decoded) store.delete(key)
- return decoded ? JSON.stringify(scrubDehydratedClient(decoded.snapshot, userId, changedChannelFences(current, decoded.fences))) : null
- }), persister),
+ getItem: (get<string>).bind(undefined, key, cacheStore),
setItem: (_k: string, value: string) => withEligiblePersister(
key, userId, eligibility, "readwrite", undefined, async (store, current, expected) => {
const snapshot = scrubDehydratedClient(JSON.parse(value) as PersistedClient, userId, changedChannelFences(current, expected))
@@ -424,12 +429,31 @@ export function createIdbPersister(userId: string | null): QualifiedPersister {
},
key: "alook-query-cache",
serialize: (client) => JSON.stringify(scrubDehydratedClient(client, userId)),
- deserialize: (raw) => observeRestoreDecode(persister, () => scrubDehydratedClient(JSON.parse(raw) as PersistedClient, userId), PERSIST_BUSTER, PERSIST_MAX_AGE_MS),
})
+ const persister: Persister = {
+ persistClient: (client) => { discardInitialSnapshot(); return writer.persistClient(client) },
+ restoreClient: async () => {
+ try {
+ const input = await observeRestoreRead(() => withEligiblePersister(key, userId, eligibility, "readwrite", undefined, async (store, current) => {
+ const raw = await promisifyRequest<unknown>(store.get(key))
+ const decoded = initialSnapshot && initialSnapshot.raw === raw ? initialSnapshot.decoded : decodeDiskSnapshot(raw)
+ discardInitialSnapshot()
+ if (!decoded) { store.delete(key); return undefined }
+ return { ...decoded, retired: changedChannelFences(current, decoded.fences) }
+ }), persister)
+ return input && observeRestoreDecode(persister, () => scrubDehydratedClient(input.snapshot, userId, input.retired), PERSIST_BUSTER, PERSIST_MAX_AGE_MS)
+ } finally { discardInitialSnapshot() }
+ },
+ removeClient: () => { discardInitialSnapshot(); return writer.removeClient() },
+ }
return Object.assign(persister, {
isCurrent: () => withEligiblePersister(key, userId, eligibility, "readonly", false, async () => true),
- retireChannels: (ids: Iterable<string>, deleted = false) => withEligiblePersister(key, userId, eligibility, "readwrite", undefined, (store, current) => retireChannelRows(store, key, userId, current, ids, deleted)),
+ retireChannels: (ids: Iterable<string>, deleted = false) => {
+ discardInitialSnapshot()
+ return withEligiblePersister(key, userId, eligibility, "readwrite", undefined, (store, current) => retireChannelRows(store, key, userId, current, ids, deleted))
+ },
retireAccount: async () => {
+ discardInitialSnapshot()
const retired = await withEligiblePersister(key, userId, eligibility, "readwrite", false, async (store) => { await clearAccountRows(store, userId); return true })
if (retired) publishCacheInvalidation()
},
@@ -447,16 +471,16 @@ async function clearAccountRows(store: IDBObjectStore, userId: string | null, le
}
}
await new Promise<void>((resolve, reject) => {
- const request = store.openCursor()
+ const request = store.openKeyCursor()
request.onerror = () => reject(request.error)
request.onsuccess = () => {
const cursor = request.result
if (!cursor) { resolve(); return }
const match = typeof cursor.key === "string" && /^(alook:qc:[^:]+):([^:]+):((?:application:)?client(?::epoch)?|account-epoch(?::channels)?)$/.exec(cursor.key)
if (match && match[2] === (userId ?? "anon") && (!legacyOnly || match[1] !== IDB_PREFIX)) {
- if (match[3] === "account-epoch:channels") cursor.update(new Map())
- else if (match[3]?.endsWith("epoch")) cursor.update(crypto.randomUUID())
- else cursor.delete()
+ if (match[3] === "account-epoch:channels") store.put(new Map(), cursor.key)
+ else if (match[3]?.endsWith("epoch")) store.put(crypto.randomUUID(), cursor.key)
+ else store.delete(cursor.key)
}
cursor.continue()
}