diff --git a/packages/app/src/runtime/persistence/README.md b/packages/app/src/runtime/persistence/README.md index fa678637350..1c15ad439ab 100644 --- a/packages/app/src/runtime/persistence/README.md +++ b/packages/app/src/runtime/persistence/README.md @@ -85,8 +85,13 @@ until then neither the initial load, a change from another window (`accept`), no of an older failed batch can replace the key. The host also stamps every update with a monotonic revision, returned in the ack and carried by change events and loads, so an event that reaches a window after a newer ack or load for the same key is recognised as stale and -dropped; an event held back during an in-flight write is applied after the ack when the host -ordered it later. +dropped; an event held back during an in-flight write, or a snapshot that finishes during +one, is applied after the ack when the host ordered it later. A failed batch puts its +unsuperseded keys back in the queue and retries on its own, doubling the delay up to about +26 s; a failed load resolves the waiting reads from memory and the next read loads again. +`clear()` raises the revision floor to the newest revision the window knows, so neither a late +snapshot nor an older event brings a cleared key back. The phases and ordering rules live in +the pure machine in `namespace-machine.ts`. ## Migrations diff --git a/packages/app/src/runtime/persistence/namespace-machine.test.ts b/packages/app/src/runtime/persistence/namespace-machine.test.ts new file mode 100644 index 00000000000..f1f84018623 --- /dev/null +++ b/packages/app/src/runtime/persistence/namespace-machine.test.ts @@ -0,0 +1,232 @@ +import { describe, expect, test } from "bun:test" +import { + INITIAL_NAMESPACE_STATE, + selectNamespaceItem, + selectNamespaceKeys, + transitionNamespace, + type NamespaceEvent, + type NamespaceState, + type NamespaceTransition, +} from "./namespace-machine" + +function replay(events: NamespaceEvent[], from = INITIAL_NAMESPACE_STATE) { + return events.reduce((steps, event) => { + steps.push(transitionNamespace(steps.at(-1)?.state ?? from, event)) + + return steps + }, []) +} + +function settle(events: NamespaceEvent[], from = INITIAL_NAMESPACE_STATE) { + return replay(events, from).at(-1)?.state ?? from +} + +const loaded = (items: Record = {}, revision = 0): NamespaceEvent[] => [ + { type: "load" }, + { type: "load.succeeded", items, revision }, +] + +describe("transitionNamespace", () => { + test("a failed batch requeues its keys and schedules a retry with doubling backoff", () => { + const steps = replay([ + { type: "write", key: "tabs", value: "[1]" }, + { type: "flush" }, + { type: "batch.failed", batch: 1 }, + { type: "flush" }, + { type: "batch.failed", batch: 2 }, + ]) + + expect(steps.map((step) => step.effects)).toEqual([ + [{ type: "timer.arm", delayMs: 100 }], + [{ type: "timer.cancel" }, { type: "send", batch: 1, insert: { tabs: "[1]" }, remove: [] }], + [{ type: "timer.arm", delayMs: 200 }], + [{ type: "timer.cancel" }, { type: "send", batch: 2, insert: { tabs: "[1]" }, remove: [] }], + [{ type: "timer.arm", delayMs: 400 }], + ]) + expect(steps.at(-1)?.state.entries.get("tabs")).toEqual({ status: "dirty", value: "[1]", deferred: undefined }) + }) + + test("retry backoff stops growing at the cap and resets after a successful batch", () => { + const failing = settle( + Array.from({ length: 12 }, (_, index): NamespaceEvent[] => [ + { type: "flush" }, + { type: "batch.failed", batch: index + 1 }, + ]).flat(), + settle([{ type: "write", key: "tabs", value: "[1]" }]), + ) + + expect(failing.failures).toBe(12) + expect(replay([{ type: "flush" }, { type: "batch.failed", batch: 13 }], failing).at(-1)?.effects).toEqual([ + { type: "timer.arm", delayMs: 25_600 }, + ]) + + const recovered = settle([{ type: "flush" }, { type: "batch.succeeded", batch: 13, revision: 1 }], failing) + + expect(recovered.failures).toBe(0) + expect(transitionNamespace(recovered, { type: "write", key: "tabs", value: "[2]" }).effects).toEqual([ + { type: "timer.arm", delayMs: 100 }, + ]) + }) + + test("a write while a flush is already scheduled does not move the timer", () => { + const writes: NamespaceEvent[] = [ + { type: "write", key: "tabs", value: "[1]" }, + { type: "write", key: "recent", value: "{}" }, + { type: "write", key: "tabs", value: null }, + ] + + expect(replay(writes).map((step) => step.effects)).toEqual([[{ type: "timer.arm", delayMs: 100 }], [], []]) + expect(transitionNamespace(settle(writes), { type: "flush" }).effects).toEqual([ + { type: "timer.cancel" }, + { type: "send", batch: 1, insert: { recent: "{}" }, remove: ["tabs"] }, + ]) + }) + + test("a batch settles only the keys it still carries", () => { + const state = settle([ + { type: "write", key: "tabs", value: "old" }, + { type: "write", key: "recent", value: "{}" }, + { type: "flush" }, + { type: "write", key: "tabs", value: "new" }, + ]) + + const failed = transitionNamespace(state, { type: "batch.failed", batch: 1 }) + const acked = transitionNamespace(state, { type: "batch.succeeded", batch: 1, revision: 4 }) + + // The rewritten key is already queued, so its timer is armed and the requeued sibling rides along. + expect(failed.effects).toEqual([]) + expect(failed.state.entries.get("tabs")).toEqual({ status: "dirty", value: "new", deferred: undefined }) + expect(failed.state.entries.get("recent")).toEqual({ status: "dirty", value: "{}", deferred: undefined }) + expect(acked.state.entries.get("tabs")).toEqual({ status: "dirty", value: "new", deferred: undefined }) + expect(acked.state.entries.get("recent")).toEqual({ status: "synced", value: "{}", revision: 4 }) + }) + + test("a failed batch whose keys a later batch replaced requeues nothing", () => { + const state = settle([ + { type: "write", key: "tabs", value: "old" }, + { type: "flush" }, + { type: "write", key: "tabs", value: "new" }, + { type: "flush" }, + ]) + + const failed = transitionNamespace(state, { type: "batch.failed", batch: 1 }) + + expect(failed.effects).toEqual([]) + expect(failed.state.entries).toBe(state.entries) + expect(transitionNamespace(state, { type: "batch.succeeded", batch: 1, revision: 1 }).state).toBe(state) + }) + + test("a snapshot that finishes during an in-flight write holds the newer host value for after the ack", () => { + const state = settle([ + { type: "write", key: "model", value: "mine" }, + { type: "flush" }, + // Another window wrote the key at revision 2; this window's write lands at revision 1. + ...loaded({ model: "theirs" }, 2), + ]) + + const echo = transitionNamespace(state, { type: "remote", insert: { model: "theirs" }, remove: [], revision: 2 }) + + expect(selectNamespaceItem(state, "model")).toBe("mine") + expect(echo.state).toBe(state) + expect(settle([{ type: "batch.succeeded", batch: 1, revision: 1 }], state).entries.get("model")).toEqual({ + status: "synced", + value: "theirs", + revision: 2, + }) + }) + + test("a snapshot older than the local write leaves the local value after the ack", () => { + const state = settle([ + { type: "load" }, + { type: "write", key: "model", value: "mine" }, + { type: "flush" }, + { type: "load.succeeded", items: { model: "older" }, revision: 0 }, + { type: "batch.succeeded", batch: 1, revision: 1 }, + ]) + + expect(state.entries.get("model")).toEqual({ status: "synced", value: "mine", revision: 1 }) + }) + + test("a failed load returns to unloaded so the next read loads again", () => { + const steps = replay([{ type: "load" }, { type: "load.failed" }, { type: "load" }]) + + expect(steps.map((step) => [step.state.status, step.effects])).toEqual([ + ["loading", [{ type: "load" }]], + ["unloaded", []], + ["loading", [{ type: "load" }]], + ]) + }) + + test("a snapshot that finishes after a clear cannot bring cleared keys back", () => { + const state = settle([{ type: "load" }, { type: "clear" }]) + const late = transitionNamespace(state, { type: "load.succeeded", items: { tabs: "old" }, revision: 10 }) + + expect(late.state).toBe(state) + expect(selectNamespaceKeys(state)).toEqual([]) + expect(transitionNamespace(state, { type: "load.failed" }).state).toBe(state) + }) + + test("an event stamped before a clear cannot bring a cleared key back", () => { + const state = settle([ + ...loaded(), + { type: "write", key: "tabs", value: "[1]" }, + { type: "flush" }, + { type: "batch.succeeded", batch: 1, revision: 5 }, + { type: "clear" }, + ]) + + expect(state.floor).toBe(5) + expect( + transitionNamespace(state, { type: "remote", insert: { tabs: "stale" }, remove: [], revision: 3 }).state, + ).toBe(state) + expect( + selectNamespaceItem( + settle([{ type: "remote", insert: { tabs: "fresh" }, remove: [], revision: 6 }], state), + "tabs", + ), + ).toBe("fresh") + }) + + test("a clear cancels the scheduled flush and ignores replies to batches sent before it", () => { + const sent = settle([...loaded(), { type: "write", key: "tabs", value: "[1]" }, { type: "flush" }]) + const queued = transitionNamespace(sent, { type: "write", key: "recent", value: "{}" }).state + const cleared = transitionNamespace(queued, { type: "clear" }) + + expect(cleared.effects).toEqual([{ type: "timer.cancel" }]) + expect(transitionNamespace(sent, { type: "clear" }).effects).toEqual([]) + expect(transitionNamespace(cleared.state, { type: "batch.succeeded", batch: 1, revision: 5 }).state).toBe( + cleared.state, + ) + + const failed = transitionNamespace(cleared.state, { type: "batch.failed", batch: 1 }) + + expect(failed.effects).toEqual([]) + expect(selectNamespaceKeys(failed.state)).toEqual([]) + }) + + test("events that do not apply return the same state", () => { + const unloaded = INITIAL_NAMESPACE_STATE + const loading = settle([{ type: "load" }]) + const ready = settle(loaded({ tabs: "[1]" }, 3)) + + const cases: [NamespaceState, NamespaceEvent][] = [ + [loading, { type: "load" }], + [ready, { type: "load" }], + [unloaded, { type: "load.succeeded", items: {}, revision: 1 }], + [ready, { type: "load.succeeded", items: {}, revision: 9 }], + [unloaded, { type: "load.failed" }], + [ready, { type: "load.failed" }], + [ready, { type: "flush" }], + [ready, { type: "batch.succeeded", batch: 7, revision: 9 }], + [ready, { type: "remote", insert: { tabs: "old" }, remove: [], revision: 3 }], + [ready, { type: "remote", insert: {}, remove: [], revision: 4 }], + ] + + cases.forEach(([state, event]) => { + const next = transitionNamespace(state, event) + + expect(next.state).toBe(state) + expect(next.effects).toEqual([]) + }) + }) +}) diff --git a/packages/app/src/runtime/persistence/namespace-machine.ts b/packages/app/src/runtime/persistence/namespace-machine.ts new file mode 100644 index 00000000000..a0ea2c2cbbf --- /dev/null +++ b/packages/app/src/runtime/persistence/namespace-machine.ts @@ -0,0 +1,304 @@ +export const NAMESPACE_FLUSH_DELAY_MS = 100 + +// Retries after failed batches double the flush delay up to 2^8 × 100 ms (about 26 s). +export const NAMESPACE_RETRY_MAX_EXPONENT = 8 + +export type NamespaceRemote = { readonly value: string | null; readonly revision: number } + +// One key's write lifecycle. A local write is `dirty` until a batch carries it and `inflight` until the host acks that +// batch. While it is either, nothing external may replace it: the newest external change waits in `deferred` and wins +// after the ack only if the host applied it later. +export type NamespaceEntry = + | { readonly status: "synced"; readonly value: string | null; readonly revision: number } + | { readonly status: "dirty"; readonly value: string | null; readonly deferred: NamespaceRemote | undefined } + | { + readonly status: "inflight" + readonly value: string | null + readonly batch: number + readonly deferred: NamespaceRemote | undefined + } + +// The namespace's load lifecycle. `floor` is the revision the snapshot (or a clear) reflected for every key, `batch` the +// id of the last batch cut, and `failures` the consecutive failed batches that set the retry backoff. A flush timer is +// armed exactly while some entry is `dirty`. +export type NamespaceState = { + readonly status: "unloaded" | "loading" | "loaded" + readonly entries: ReadonlyMap + readonly floor: number + readonly batch: number + readonly failures: number +} + +export type NamespaceEvent = + | { readonly type: "load" } + | { readonly type: "load.succeeded"; readonly items: Readonly>; readonly revision: number } + | { readonly type: "load.failed" } + | { readonly type: "write"; readonly key: string; readonly value: string | null } + | { readonly type: "flush" } + | { readonly type: "batch.succeeded"; readonly batch: number; readonly revision: number } + | { readonly type: "batch.failed"; readonly batch: number } + | { + readonly type: "remote" + readonly insert: Readonly> + readonly remove: readonly string[] + readonly revision: number + } + | { readonly type: "clear" } + +export type NamespaceEffect = + | { readonly type: "load" } + | { + readonly type: "send" + readonly batch: number + readonly insert: Record + readonly remove: string[] + } + | { readonly type: "timer.arm"; readonly delayMs: number } + | { readonly type: "timer.cancel" } + +export type NamespaceTransition = { + readonly state: NamespaceState + readonly effects: readonly NamespaceEffect[] +} + +type Dirty = Extract + +type Inflight = Extract + +export const INITIAL_NAMESPACE_STATE: NamespaceState = { + status: "unloaded", + entries: new Map(), + floor: -1, + batch: 0, + failures: 0, +} + +export function transitionNamespace(state: NamespaceState, event: NamespaceEvent): NamespaceTransition { + if (event.type === "load") { + if (state.status !== "unloaded") return unchanged(state) + + return changed({ ...state, status: "loading" }, [{ type: "load" }]) + } + + // A clear while loading already settled the namespace, so a late snapshot cannot bring cleared keys back. + if (event.type === "load.succeeded") { + if (state.status !== "loading") return unchanged(state) + + return changed({ + ...state, + status: "loaded", + entries: snapshot(state.entries, event.items, event.revision), + floor: event.revision, + }) + } + + // Readers waiting on this load see what memory holds; the next read loads again. + if (event.type === "load.failed") { + if (state.status !== "loading") return unchanged(state) + + return changed({ ...state, status: "unloaded" }) + } + + if (event.type === "write") { + const previous = state.entries.get(event.key) + const deferred = previous?.status === "synced" ? undefined : previous?.deferred + const entries = new Map(state.entries).set(event.key, { status: "dirty", value: event.value, deferred }) + + return changed( + { ...state, entries }, + queued(state.entries) ? [] : [{ type: "timer.arm", delayMs: retryDelay(state.failures) }], + ) + } + + // Batches go out as soon as they are cut, never behind an earlier reply, so a flush on pagehide is on the wire before + // the page goes away. + if (event.type === "flush") { + const dirty = [...state.entries].filter((item): item is [string, Dirty] => item[1].status === "dirty") + + if (dirty.length === 0) return unchanged(state) + const batch = state.batch + 1 + + return changed( + { + ...state, + batch, + entries: replace( + state.entries, + dirty.map(([key, entry]): [string, NamespaceEntry] => [ + key, + { status: "inflight", value: entry.value, batch, deferred: entry.deferred }, + ]), + ), + }, + [ + { type: "timer.cancel" }, + { + type: "send", + batch, + insert: Object.fromEntries( + dirty.flatMap(([key, entry]) => (entry.value === null ? [] : [[key, entry.value]])), + ), + remove: dirty.flatMap(([key, entry]) => (entry.value === null ? [key] : [])), + }, + ], + ) + } + + // Only keys this batch still owns settle; a key written again since then belongs to a later write. + if (event.type === "batch.succeeded") { + const acked = carried(state.entries, event.batch) + + if (acked.length === 0 && state.failures === 0) return unchanged(state) + + return changed({ + ...state, + failures: 0, + entries: replace( + state.entries, + acked.map(([key, entry]): [string, NamespaceEntry] => [ + key, + entry.deferred && entry.deferred.revision > event.revision + ? { status: "synced", ...entry.deferred } + : { status: "synced", value: entry.value, revision: event.revision }, + ]), + ), + }) + } + + // Unsuperseded keys go back to `dirty` and a retry is scheduled with backoff, so a failure never strands them. + if (event.type === "batch.failed") { + const failed = carried(state.entries, event.batch) + const failures = state.failures + 1 + const retry = failed.length > 0 && !queued(state.entries) + + return changed( + { + ...state, + failures, + entries: replace( + state.entries, + failed.map(([key, entry]): [string, NamespaceEntry] => [ + key, + { status: "dirty", value: entry.value, deferred: entry.deferred }, + ]), + ), + }, + retry ? [{ type: "timer.arm", delayMs: retryDelay(failures) }] : [], + ) + } + + if (event.type === "remote") { + // The snapshot or clear already reflects everything up to `floor`. + if (event.revision <= state.floor) return unchanged(state) + const revision = event.revision + + const updates = [ + ...Object.entries(event.insert), + ...event.remove.map((key): [string, string | null] => [key, null]), + ].flatMap(([key, value]): [string, NamespaceEntry][] => { + const entry = state.entries.get(key) + + if (entry && entry.status !== "synced") { + const held = hold(entry, { value, revision }) + + return held === entry ? [] : [[key, held]] + } + + if (revision <= (entry?.revision ?? state.floor)) return [] + + return [[key, { status: "synced", value, revision }]] + }) + + if (updates.length === 0) return unchanged(state) + + return changed({ ...state, entries: replace(state.entries, updates) }) + } + + // Cleared keys must not come back from events stamped before the clear, so the floor rises to the newest revision + // this window knows. Batches already sent reach the host before its clear, which deletes them there too. + return changed( + { + ...state, + status: "loaded", + entries: new Map(), + floor: Math.max( + state.floor, + ...[...state.entries.values()].map((entry) => + entry.status === "synced" ? entry.revision : (entry.deferred?.revision ?? -1), + ), + ), + }, + queued(state.entries) ? [{ type: "timer.cancel" }] : [], + ) +} + +export function selectNamespaceItem(state: NamespaceState, key: string) { + return state.entries.get(key)?.value ?? null +} + +export function selectNamespaceKeys(state: NamespaceState) { + return [...state.entries].flatMap(([key, entry]) => (entry.value === null ? [] : [key])) +} + +// The snapshot is the whole truth at its revision: a key it lacks was deleted by then, even if an older event inserted +// it meanwhile. A local key keeps its value and holds the snapshot's, which wins after the ack if the host applied it +// later than the local write. +function snapshot( + entries: ReadonlyMap, + items: Readonly>, + revision: number, +) { + const next = new Map( + [...entries].flatMap(([key, entry]): [string, NamespaceEntry][] => { + if (entry.status !== "synced") { + return [[key, hold(entry, { value: Object.hasOwn(items, key) ? (items[key] ?? null) : null, revision })]] + } + + return entry.revision > revision ? [[key, entry]] : [] + }), + ) + + Object.entries(items).forEach(([key, value]) => { + if (!next.has(key)) next.set(key, { status: "synced", value, revision }) + }) + + return next +} + +function hold(entry: Dirty | Inflight, remote: NamespaceRemote): Dirty | Inflight { + if (entry.deferred && entry.deferred.revision >= remote.revision) return entry + + return { ...entry, deferred: remote } +} + +function carried(entries: ReadonlyMap, batch: number) { + return [...entries].filter((item): item is [string, Inflight] => { + const entry = item[1] + + return entry.status === "inflight" && entry.batch === batch + }) +} + +function queued(entries: ReadonlyMap) { + return [...entries.values()].some((entry) => entry.status === "dirty") +} + +function replace(entries: ReadonlyMap, updates: readonly [string, NamespaceEntry][]) { + if (updates.length === 0) return entries + const next = new Map(entries) + updates.forEach(([key, entry]) => next.set(key, entry)) + + return next +} + +function retryDelay(failures: number) { + return NAMESPACE_FLUSH_DELAY_MS * 2 ** Math.min(failures, NAMESPACE_RETRY_MAX_EXPONENT) +} + +function changed(state: NamespaceState, effects: readonly NamespaceEffect[] = []): NamespaceTransition { + return { state, effects } +} + +function unchanged(state: NamespaceState): NamespaceTransition { + return { state, effects: [] } +} diff --git a/packages/app/src/runtime/persistence/namespace.test.ts b/packages/app/src/runtime/persistence/namespace.test.ts index 9223f294ad7..add4eb74580 100644 --- a/packages/app/src/runtime/persistence/namespace.test.ts +++ b/packages/app/src/runtime/persistence/namespace.test.ts @@ -1,8 +1,6 @@ -import { describe, expect, test } from "bun:test" +import { afterEach, beforeEach, describe, expect, test, vi } from "bun:test" import { createNamespaceStorage, type NamespaceDriver, type NamespaceStorage } from "./namespace" -const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)) - type Call = { kind: string; name: string; insert?: Record; remove?: string[] } // A host with a monotonic revision. Each update is acked to its caller and recorded as an event @@ -14,6 +12,24 @@ function host(initial: Record> = {}) { let revision = 0 let fail: (insert: Record) => boolean = () => false let gate: Promise | undefined + // Each update's reply, so a test can wait for one without waiting for a gated earlier one. + const replies: Promise[] = [] + + const update = async (name: string, insert: Record, remove: string[]) => { + calls.push({ kind: "update", name, insert, remove }) + await gate + + if (fail(insert)) throw new Error("disk full") + const items = data.get(name) ?? new Map() + + for (const [key, value] of Object.entries(insert)) items.set(key, value) + + for (const key of remove) items.delete(key) + data.set(name, items) + events.push({ name, insert, remove, revision: ++revision }) + + return revision + } const driver: NamespaceDriver = { items: async (name) => { @@ -21,20 +37,11 @@ function host(initial: Record> = {}) { return { items: Object.fromEntries(data.get(name) ?? []), revision } }, - update: async (name, insert, remove) => { - calls.push({ kind: "update", name, insert, remove }) - await gate + update: (name, insert, remove) => { + const reply = update(name, insert, remove) + replies.push(reply) - if (fail(insert)) throw new Error("disk full") - const items = data.get(name) ?? new Map() - - for (const [key, value] of Object.entries(insert)) items.set(key, value) - - for (const key of remove) items.delete(key) - data.set(name, items) - events.push({ name, insert, remove, revision: ++revision }) - - return revision + return reply }, clear: async (name) => { calls.push({ kind: "clear", name }) @@ -49,8 +56,9 @@ function host(initial: Record> = {}) { events, updates: () => calls.filter((call) => call.kind === "update"), setFail: (value: boolean | ((insert: Record) => boolean)) => - (fail = typeof value === "boolean" ? () => value : value), + (fail = value instanceof Function ? value : () => value), setGate: (value: Promise | undefined) => (gate = value), + replied: (index: number) => Promise.allSettled([replies[index]]), deliver: (target: NamespaceStorage, index: number) => { const event = events[index]! target.accept(event.insert, event.remove, event.revision) @@ -59,9 +67,17 @@ function host(initial: Record> = {}) { } describe("namespace storage", () => { + beforeEach(() => { + vi.useFakeTimers() + }) + + afterEach(() => { + vi.useRealTimers() + }) + test("loads the namespace once and serves reads from memory", async () => { const h = host({ w: { tabs: "[]", recent: "{}" } }) - const storage = createNamespaceStorage(h.driver, "w", { delay: 10 }) + const storage = createNamespaceStorage(h.driver, "w") expect(await storage.getItem("tabs")).toBe("[]") expect(await storage.getItem("recent")).toBe("{}") expect(await storage.getItem("missing")).toBeNull() @@ -71,7 +87,7 @@ describe("namespace storage", () => { test("reads its own writes immediately and coalesces them into one update", async () => { const h = host() - const storage = createNamespaceStorage(h.driver, "w", { delay: 10 }) + const storage = createNamespaceStorage(h.driver, "w") void storage.setItem("tabs", "[1]") void storage.setItem("recent", "{}") void storage.setItem("tabs", "[1,2]") @@ -79,13 +95,13 @@ describe("namespace storage", () => { expect(await storage.getItem("tabs")).toBe("[1,2]") expect(await storage.getItem("recent")).toBeNull() expect(h.updates()).toHaveLength(0) - await wait(30) + vi.advanceTimersByTime(100) expect(h.updates()).toEqual([{ kind: "update", name: "w", insert: { tabs: "[1,2]" }, remove: ["recent"] }]) }) test("writes made while loading win over the loaded snapshot", async () => { const h = host({ w: { tabs: "old" } }) - const storage = createNamespaceStorage(h.driver, "w", { delay: 10 }) + const storage = createNamespaceStorage(h.driver, "w") const read = storage.getItem("tabs") void storage.setItem("tabs", "new") expect(await read).toBe("new") @@ -93,7 +109,7 @@ describe("namespace storage", () => { test("flush writes now and resolves after the driver accepted the batch", async () => { const h = host() - const storage = createNamespaceStorage(h.driver, "w", { delay: 10_000 }) + const storage = createNamespaceStorage(h.driver, "w") void storage.setItem("tabs", "[1]") await storage.flush() expect(h.data.get("w")?.get("tabs")).toBe("[1]") @@ -103,7 +119,7 @@ describe("namespace storage", () => { test("a failed update keeps unsuperseded changes queued for the next flush", async () => { const h = host() - const storage = createNamespaceStorage(h.driver, "w", { delay: 10_000 }) + const storage = createNamespaceStorage(h.driver, "w") h.setFail(true) void storage.setItem("tabs", "[1]") void storage.setItem("recent", "{}") @@ -119,7 +135,7 @@ describe("namespace storage", () => { const h = host() const first = Promise.withResolvers() h.setGate(first.promise) - const storage = createNamespaceStorage(h.driver, "w", { delay: 10_000 }) + const storage = createNamespaceStorage(h.driver, "w") void storage.setItem("tabs", "[1]") void storage.flush() void storage.setItem("tabs", "[2]") @@ -140,7 +156,7 @@ describe("namespace storage", () => { clear: async () => undefined, } - const storage = createNamespaceStorage(driver, "g", { delay: 10_000 }) + const storage = createNamespaceStorage(driver, "g") const read = storage.getItem("model") void storage.setItem("model", "local") void storage.flush() @@ -160,13 +176,13 @@ describe("namespace storage", () => { h.setGate(first.promise) // The first batch (old) is held at the host and will be rejected; the second (new) succeeds. h.setFail((insert) => insert.tabs === "old") - const storage = createNamespaceStorage(h.driver, "w", { delay: 10_000 }) + const storage = createNamespaceStorage(h.driver, "w") void storage.setItem("tabs", "old") void storage.flush() h.setGate(undefined) void storage.setItem("tabs", "new") void storage.flush() - await wait(0) + await h.replied(1) expect(h.data.get("w")?.get("tabs")).toBe("new") first.resolve() await storage.flush() @@ -178,8 +194,8 @@ describe("namespace storage", () => { test("an event that reaches a window after a newer ack for the same key is ignored", async () => { const h = host({ g: { model: "start" } }) - const one = createNamespaceStorage(h.driver, "g", { delay: 10_000 }) - const two = createNamespaceStorage(h.driver, "g", { delay: 10_000 }) + const one = createNamespaceStorage(h.driver, "g") + const two = createNamespaceStorage(h.driver, "g") await one.getItem("model") await two.getItem("model") void one.setItem("model", "A") @@ -199,7 +215,7 @@ describe("namespace storage", () => { const h = host() const gate = Promise.withResolvers() h.setGate(gate.promise) - const storage = createNamespaceStorage(h.driver, "g", { delay: 10_000 }) + const storage = createNamespaceStorage(h.driver, "g") void storage.setItem("model", "mine") void storage.flush() // Another window's write for the same key landed at the host after ours will. @@ -213,7 +229,7 @@ describe("namespace storage", () => { test("the initial load removes a key an older event inserted while the load was in flight", async () => { const loaded = Promise.withResolvers<{ items: Record; revision: number }>() const driver: NamespaceDriver = { items: () => loaded.promise, update: async () => 0, clear: async () => undefined } - const storage = createNamespaceStorage(driver, "g", { delay: 10_000 }) + const storage = createNamespaceStorage(driver, "g") const read = storage.getItem("model") // Host history: insert at 41, delete at 42; the snapshot was taken at 42. storage.accept({ model: "inserted" }, [], 41) @@ -224,7 +240,7 @@ describe("namespace storage", () => { expect(await storage.getItem("model")).toBeNull() // A key inserted by an event newer than the snapshot survives the load. const second = Promise.withResolvers<{ items: Record; revision: number }>() - const other = createNamespaceStorage({ ...driver, items: () => second.promise }, "g", { delay: 10_000 }) + const other = createNamespaceStorage({ ...driver, items: () => second.promise }, "g") const pending = other.getItem("model") other.accept({ model: "after-snapshot" }, [], 43) second.resolve({ items: {}, revision: 42 }) @@ -233,9 +249,8 @@ describe("namespace storage", () => { test("an event older than the initial load is ignored", async () => { const h = host({ g: { model: "loaded" } }) - void h.driver.update("g", { model: "loaded" }, []) - await wait(0) - const storage = createNamespaceStorage(h.driver, "g", { delay: 10_000 }) + await h.driver.update("g", { model: "loaded" }, []) + const storage = createNamespaceStorage(h.driver, "g") await storage.getItem("model") storage.accept({ model: "before-load" }, [], 1) expect(await storage.getItem("model")).toBe("loaded") @@ -245,7 +260,7 @@ describe("namespace storage", () => { test("clear drops the cache and queued changes and clears the driver", async () => { const h = host({ w: { tabs: "[]" } }) - const storage = createNamespaceStorage(h.driver, "w", { delay: 10_000 }) + const storage = createNamespaceStorage(h.driver, "w") await storage.getItem("tabs") void storage.setItem("recent", "{}") await storage.clear() @@ -253,4 +268,37 @@ describe("namespace storage", () => { expect(await storage.getItem("recent")).toBeNull() expect(h.calls.map((call) => call.kind)).toEqual(["items", "clear"]) }) + + test("a failed update retries on its own, backing off, without another write or flush", async () => { + const h = host() + const storage = createNamespaceStorage(h.driver, "w") + h.setFail(true) + void storage.setItem("tabs", "[1]") + vi.advanceTimersByTime(100) + await h.replied(0) + h.setFail(false) + vi.advanceTimersByTime(199) + expect(h.updates()).toHaveLength(1) + vi.advanceTimersByTime(1) + await h.replied(1) + expect(h.updates()).toHaveLength(2) + expect(h.data.get("w")?.get("tabs")).toBe("[1]") + }) + + test("a failed load resolves the waiting reads from memory and the next read loads again", async () => { + const h = host({ w: { tabs: "[1]" } }) + let attempt = 0 + + const storage = createNamespaceStorage( + { + ...h.driver, + items: (name) => (attempt++ === 0 ? Promise.reject(new Error("port closed")) : h.driver.items(name)), + }, + "w", + ) + + void storage.setItem("recent", "{}") + expect(await storage.getItem("recent")).toBe("{}") + expect(await storage.getItem("tabs")).toBe("[1]") + }) }) diff --git a/packages/app/src/runtime/persistence/namespace.ts b/packages/app/src/runtime/persistence/namespace.ts index 5f2171bd83f..1b8216c9266 100644 --- a/packages/app/src/runtime/persistence/namespace.ts +++ b/packages/app/src/runtime/persistence/namespace.ts @@ -1,4 +1,12 @@ import type { AsyncStorage } from "@solid-primitives/storage" +import { + INITIAL_NAMESPACE_STATE, + selectNamespaceItem, + selectNamespaceKeys, + transitionNamespace, + type NamespaceEffect, + type NamespaceEvent, +} from "./namespace-machine" // The host-side store for one namespace: one bulk read, one bulk write. The host stamps every // update with a monotonic revision and reports it with reads, acks, and change events. @@ -15,159 +23,103 @@ export type NamespaceStorage = AsyncStorage & { accept(insert: Record, remove: string[], revision: number): void } -const namespaceFlushDelay = 100 - // In-memory truth for a namespace. Reads load the namespace once and are Map lookups from then // on; writes update the cache immediately and are batched into one driver call per flush window, -// so a burst of setter calls costs one round trip. Mirrors VS Code's Storage class. -// -// Two orderings keep the cache correct. Every local write gets a sequence number that stays -// recorded until the host acks that exact write; while recorded, nothing external may replace -// the key. Every value the cache holds also carries the host revision it came from, so an event -// that reaches this window after a newer ack or load is recognised as stale and dropped. Batches -// are posted as soon as they are cut, never behind an earlier reply, so a flush on pagehide is -// on the wire before the page goes away. -export function createNamespaceStorage( - driver: NamespaceDriver, - name: string, - options: { delay?: number } = {}, -): NamespaceStorage { - const delay = options.delay ?? namespaceFlushDelay - const cache = new Map() - const local = new Map() - const dirty = new Set() - const inflight = new Set>() - // Host revision behind each cached key, and the revision the initial load reflected for all keys. - const applied = new Map() - let floor = -1 - // The newest external change for a key that arrived while a local write was still in flight. - const deferred = new Map() - let seq = 0 - let loading: Promise | undefined +// so a burst of setter calls costs one round trip. Mirrors VS Code's Storage class. The ordering +// rules live in `namespace-machine.ts`; this driver runs its effects and reports their results. +export function createNamespaceStorage(driver: NamespaceDriver, name: string): NamespaceStorage { + let state = INITIAL_NAMESPACE_STATE + // Edge handles only: the armed flush timer, and the requests that reads and `flush()` wait on. let timer: ReturnType | undefined + let load = Promise.resolve() + const requests = new Set>() - const place = (key: string, value: string | null, revision: number) => { - if (value === null) cache.delete(key) - else cache.set(key, value) - applied.set(key, revision) + const dispatch = (event: NamespaceEvent) => { + const next = transitionNamespace(state, event) + state = next.state + next.effects.forEach(execute) } - // The snapshot is the whole truth at its revision: a key it lacks was deleted by then, even if - // an older event inserted it into the cache while the load was in flight. - const load = () => - (loading ??= driver.items(name).then((loaded) => { - floor = loaded.revision - const stale = (key: string) => !local.has(key) && (applied.get(key) ?? -1) <= loaded.revision + const execute = (effect: NamespaceEffect) => { + if (effect.type === "timer.arm") { + clearTimeout(timer) + timer = setTimeout(() => dispatch({ type: "flush" }), effect.delayMs) - for (const key of [...cache.keys()]) { - if (!(key in loaded.items) && stale(key)) place(key, null, loaded.revision) - } - - for (const [key, value] of Object.entries(loaded.items)) { - if (stale(key)) place(key, value, loaded.revision) - } - })) - - const write = (key: string, value: string | null) => { - if (value === null) cache.delete(key) - else cache.set(key, value) - local.set(key, { seq: ++seq, value }) - dirty.add(key) - timer ??= setTimeout(() => void flush(), delay) - } - - // The host accepted this window's value for `key` at `revision`. A change from another window - // that was held back meanwhile wins if the host applied it later than ours. - const acknowledge = (key: string, revision: number) => { - local.delete(key) - const later = deferred.get(key) - deferred.delete(key) - - if (later && later.revision > revision) return place(key, later.value, later.revision) - applied.set(key, revision) - } - - const flush = () => { - clearTimeout(timer) - timer = undefined - - if (dirty.size > 0) { - const batch = [...dirty].map((key) => ({ key, ...local.get(key)! })) - dirty.clear() - const insert = Object.fromEntries(batch.filter((entry) => entry.value !== null).map((e) => [e.key, e.value!])) - const remove = batch.filter((entry) => entry.value === null).map((entry) => entry.key) - const current = (entry: { key: string; seq: number }) => local.get(entry.key)?.seq === entry.seq - - const request = driver - .update(name, insert, remove) - .then((revision) => batch.filter(current).forEach((entry) => acknowledge(entry.key, revision))) - .catch((error: unknown) => { - // Only a value nothing newer has replaced is worth retrying. - batch.filter(current).forEach((entry) => dirty.add(entry.key)) - console.error(`[persistence] flush failed for ${name}`, error) - }) - .finally(() => inflight.delete(request)) - - inflight.add(request) + return } - return Promise.all(inflight).then(() => undefined) + if (effect.type === "timer.cancel") { + clearTimeout(timer) + timer = undefined + + return + } + + if (effect.type === "load") { + load = driver.items(name).then( + (loaded) => dispatch({ type: "load.succeeded", items: loaded.items, revision: loaded.revision }), + (error) => { + console.error(`[persistence] load failed for ${name}`, error) + dispatch({ type: "load.failed" }) + }, + ) + + return + } + + const batch = effect.batch + + const request = driver + .update(name, effect.insert, effect.remove) + .then( + (revision) => dispatch({ type: "batch.succeeded", batch, revision }), + (error) => { + console.error(`[persistence] flush failed for ${name}`, error) + dispatch({ type: "batch.failed", batch }) + }, + ) + .finally(() => requests.delete(request)) + + requests.add(request) + } + + const loaded = async () => { + dispatch({ type: "load" }) + + if (state.status === "loading") await load } const storage: NamespaceStorage = { getItem: async (key) => { - await load() + await loaded() - return cache.get(key) ?? null + return selectNamespaceItem(state, key) }, - setItem: async (key, value) => write(key, value), - removeItem: async (key) => write(key, null), + setItem: async (key, value) => dispatch({ type: "write", key, value }), + removeItem: async (key) => dispatch({ type: "write", key, value: null }), clear: async () => { - clearTimeout(timer) - timer = undefined - cache.clear() - local.clear() - dirty.clear() - applied.clear() - deferred.clear() - loading = Promise.resolve() + dispatch({ type: "clear" }) await driver.clear(name) }, key: async (index: number) => { - await load() + await loaded() - return [...cache.keys()][index] + return selectNamespaceKeys(state)[index] }, getLength: async () => { - await load() + await loaded() - return cache.size + return selectNamespaceKeys(state).length }, get length() { return storage.getLength() }, - flush, - accept(insert, remove, revision) { - // The initial load already reflects everything up to `floor`. - if (revision <= floor) return + flush: () => { + dispatch({ type: "flush" }) - const changes = [ - ...Object.entries(insert).map(([key, value]) => [key, value] as const), - ...remove.map((key) => [key, null] as const), - ] - - for (const [key, value] of changes) { - if (local.has(key)) { - const held = deferred.get(key) - - if (!held || revision > held.revision) deferred.set(key, { revision, value }) - continue - } - - if (revision <= (applied.get(key) ?? floor)) continue - place(key, value, revision) - } + return Promise.all(requests).then(() => undefined) }, + accept: (insert, remove, revision) => dispatch({ type: "remote", insert, remove, revision }), } return storage