fix(app): retry failed namespace writes and settle load and clear races (#61766)

This commit is contained in:
Luke Parker
2026-11-04 14:53:23 -06:00
committed by GitHub
Unverified
parent eab8f49022
commit 0cb3d68f6e
5 changed files with 703 additions and 162 deletions
@@ -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
@@ -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<NamespaceTransition[]>((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<string, string> = {}, 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([])
})
})
})
@@ -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<string, NamespaceEntry>
readonly floor: number
readonly batch: number
readonly failures: number
}
export type NamespaceEvent =
| { readonly type: "load" }
| { readonly type: "load.succeeded"; readonly items: Readonly<Record<string, string>>; 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<Record<string, string>>
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<string, string>
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<NamespaceEntry, { status: "dirty" }>
type Inflight = Extract<NamespaceEntry, { status: "inflight" }>
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<string, NamespaceEntry>,
items: Readonly<Record<string, string>>,
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<string, NamespaceEntry>, 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<string, NamespaceEntry>) {
return [...entries.values()].some((entry) => entry.status === "dirty")
}
function replace(entries: ReadonlyMap<string, NamespaceEntry>, 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: [] }
}
@@ -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<string, string>; 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<string, Record<string, string>> = {}) {
let revision = 0
let fail: (insert: Record<string, string>) => boolean = () => false
let gate: Promise<void> | undefined
// Each update's reply, so a test can wait for one without waiting for a gated earlier one.
const replies: Promise<number>[] = []
const update = async (name: string, insert: Record<string, string>, 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<string, Record<string, string>> = {}) {
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<string, Record<string, string>> = {}) {
events,
updates: () => calls.filter((call) => call.kind === "update"),
setFail: (value: boolean | ((insert: Record<string, string>) => boolean)) =>
(fail = typeof value === "boolean" ? () => value : value),
(fail = value instanceof Function ? value : () => value),
setGate: (value: Promise<void> | 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<string, Record<string, string>> = {}) {
}
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<void>()
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<void>()
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<string, string>; 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<string, string>; 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]")
})
})
+76 -124
View File
@@ -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<string, string>, 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<string, string>()
const local = new Map<string, { seq: number; value: string | null }>()
const dirty = new Set<string>()
const inflight = new Set<Promise<void>>()
// Host revision behind each cached key, and the revision the initial load reflected for all keys.
const applied = new Map<string, number>()
let floor = -1
// The newest external change for a key that arrived while a local write was still in flight.
const deferred = new Map<string, { revision: number; value: string | null }>()
let seq = 0
let loading: Promise<void> | 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<typeof setTimeout> | undefined
let load = Promise.resolve()
const requests = new Set<Promise<void>>()
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