fix(app): drive plugin store loads and deferred writes with explicit state machines (#61918)

This commit is contained in:
Luke Parker
2026-11-04 22:49:16 -06:00
committed by GitHub
Unverified
parent ba5f113228
commit 2eedbc5a73
4 changed files with 337 additions and 56 deletions
@@ -0,0 +1,69 @@
import { expect, test } from "bun:test"
import {
createDeferredStoreState,
createStoreLoadState,
transitionDeferredStore,
transitionStoreLoad,
type DeferredStoreEvent,
type StoreLoadEvent,
type StoreWrite,
} from "./store-machine"
// `plugin-primitives.test.ts` covers loading, the hand-over before the first open and the batched open through the real
// handles. These cover the exits it cannot observe: a failed read, disposal and a store that reopens.
type Value = { readonly items: readonly string[] }
const set = (item: string): StoreWrite<Value> => ({ kind: "set", value: { items: [item] } })
// Before, a failed read only logged: the store looked like it was still loading, and it held every write for good.
test("a failed read ends in failed, drops the writes that waited, and ignores later ones", () => {
const cause = new Error("read failed")
const loading = transitionStoreLoad(createStoreLoadState<Value>(true), { type: "write", write: set("a") }).state
const failed = transitionStoreLoad(loading, { type: "failed", cause })
expect(failed).toEqual({ state: { status: "failed" }, effects: [{ type: "reject", cause, log: true }] })
const late: StoreLoadEvent<Value>[] = [{ type: "write", write: set("b") }, { type: "loaded" }]
expect(late.map((event) => transitionStoreLoad(failed.state, event).state)).toEqual([failed.state, failed.state])
})
test("disposal settles only a load still pending, and ignores everything after", () => {
const loading = createStoreLoadState<Value>(true)
const ready = createStoreLoadState<Value>(false)
const disposed = transitionStoreLoad(loading, { type: "disposed" })
expect({
loading: disposed.effects.map((effect) => effect.type),
ready: transitionStoreLoad(ready, { type: "disposed" }).effects,
late: transitionStoreLoad(disposed.state, { type: "loaded" }).state,
}).toEqual({ loading: ["reject"], ready: [], late: disposed.state })
})
test("writes made while the store reopens wait for the next one, never the store that closed", () => {
const events: DeferredStoreEvent<string, Value>[] = [
{ type: "sync", handle: "first" },
{ type: "sync", handle: undefined },
{ type: "write", write: set("a") },
{ type: "sync", handle: "second" },
{ type: "write", write: set("b") },
{ type: "disposed" },
{ type: "write", write: set("c") },
]
const machine = { state: createDeferredStoreState<string, Value>() }
const effects = events.flatMap((event) => {
const next = transitionDeferredStore(machine.state, event)
machine.state = next.state
return next.effects
})
expect(effects).toEqual([
{ type: "handover", handle: "second", writes: [set("a")] },
{ type: "forward", handle: "second", write: set("b") },
])
})
@@ -0,0 +1,139 @@
import type { Mutable } from "@opencode/plugin/gui"
/** A `Persisted` write, kept as data while it waits. */
export type StoreWrite<T> =
| { readonly kind: "update"; readonly mutate: (draft: Mutable<T>) => undefined }
| { readonly kind: "set"; readonly value: T }
/** One opened plugin store, from its storage read until its owner goes away. */
export type StoreLoadState<T> =
/** The storage read is pending; writes wait, in call order. */
| { readonly status: "loading"; readonly queue: readonly StoreWrite<T>[] }
| { readonly status: "ready" }
/** The storage read failed: the value never loads, and writes are dropped. */
| { readonly status: "failed" }
| { readonly status: "disposed" }
export type StoreLoadEvent<T> =
| { readonly type: "write"; readonly write: StoreWrite<T> }
| { readonly type: "loaded" }
| { readonly type: "failed"; readonly cause: unknown }
| { readonly type: "disposed" }
export type StoreLoadEffect<T> =
/**
* `hydrated`: the writes that waited for the read. Each applies on its own, so an invalid one cannot keep the rest
* or the value from loading, and the load settles after them. Otherwise one write, which throws to its caller.
*/
| { readonly type: "apply"; readonly writes: readonly StoreWrite<T>[]; readonly hydrated: boolean }
/** Settles the load as failed; `log` reports a real failure rather than a disposal. */
| { readonly type: "reject"; readonly cause: unknown; readonly log: boolean }
export type StoreLoadTransition<T> = {
readonly state: StoreLoadState<T>
readonly effects: readonly StoreLoadEffect<T>[]
}
/** `async`: storage answers through a promise, so the value loads later. */
export function createStoreLoadState<T>(async: boolean): StoreLoadState<T> {
return async ? { status: "loading", queue: [] } : { status: "ready" }
}
export function transitionStoreLoad<T>(state: StoreLoadState<T>, event: StoreLoadEvent<T>): StoreLoadTransition<T> {
if (state.status === "disposed") return step(state)
if (event.type === "disposed") {
if (state.status !== "loading") return step({ status: "disposed" })
return step({ status: "disposed" }, [{ type: "reject", cause: new Error("Plugin store disposed"), log: false }])
}
if (state.status === "ready") {
if (event.type !== "write") return step(state)
return step(state, [{ type: "apply", writes: [event.write], hydrated: false }])
}
if (state.status === "failed") return step(state)
if (event.type === "write") return step({ status: "loading", queue: [...state.queue, event.write] })
if (event.type === "loaded")
return step({ status: "ready" }, [{ type: "apply", writes: state.queue, hydrated: true }])
return step({ status: "failed" }, [{ type: "reject", cause: event.cause, log: true }])
}
/** The value has loaded: `Persisted.value` and `ready()` read it. */
export function selectStoreReady<T>(state: StoreLoadState<T>) {
return state.status === "ready"
}
/** A `Persisted` over a store that opens later, and opens again when its key moves (a new directory or mount). */
export type DeferredStoreState<H, T> =
/** No store is open, before the first or between two: writes wait for the next one, in call order. */
| { readonly status: "pending"; readonly queue: readonly StoreWrite<T>[] }
| { readonly status: "open"; readonly handle: H }
| { readonly status: "disposed" }
export type DeferredStoreEvent<H, T> =
/** The store currently open, if any. */
| { readonly type: "sync"; readonly handle: H | undefined }
| { readonly type: "write"; readonly write: StoreWrite<T> }
| { readonly type: "disposed" }
export type DeferredStoreEffect<H, T> =
/** The writes that waited: each applies on its own, in order. */
| { readonly type: "handover"; readonly handle: H; readonly writes: readonly StoreWrite<T>[] }
/** A write to the open store, which throws to its caller. */
| { readonly type: "forward"; readonly handle: H; readonly write: StoreWrite<T> }
export type DeferredStoreTransition<H, T> = {
readonly state: DeferredStoreState<H, T>
readonly effects: readonly DeferredStoreEffect<H, T>[]
}
export function createDeferredStoreState<H, T>(): DeferredStoreState<H, T> {
return { status: "pending", queue: [] }
}
export function transitionDeferredStore<H, T>(
state: DeferredStoreState<H, T>,
event: DeferredStoreEvent<H, T>,
): DeferredStoreTransition<H, T> {
if (state.status === "disposed") return deferredStep(state)
if (event.type === "disposed") return deferredStep({ status: "disposed" })
if (state.status === "open") {
if (event.type === "write")
return deferredStep(state, [{ type: "forward", handle: state.handle, write: event.write }])
if (event.handle === state.handle) return deferredStep(state)
if (event.handle === undefined) return deferredStep({ status: "pending", queue: [] })
return deferredStep({ status: "open", handle: event.handle })
}
if (event.type === "write") return deferredStep({ status: "pending", queue: [...state.queue, event.write] })
if (event.handle === undefined) return deferredStep(state)
if (state.queue.length === 0) return deferredStep({ status: "open", handle: event.handle })
return deferredStep({ status: "open", handle: event.handle }, [
{ type: "handover", handle: event.handle, writes: state.queue },
])
}
function step<T>(state: StoreLoadState<T>, effects: readonly StoreLoadEffect<T>[] = []): StoreLoadTransition<T> {
return { state, effects }
}
function deferredStep<H, T>(
state: DeferredStoreState<H, T>,
effects: readonly DeferredStoreEffect<H, T>[] = [],
): DeferredStoreTransition<H, T> {
return { state, effects }
}
+107 -53
View File
@@ -4,7 +4,9 @@ import {
createRenderEffect,
createRoot,
createSignal,
getOwner,
on,
onCleanup,
untrack,
type Accessor,
type Owner,
@@ -15,6 +17,16 @@ import type { Mutable, Persisted, SessionRef } from "@opencode/plugin/gui"
import type { BuiltinStoreFrom } from "@opencode/plugin/gui/builtin"
import { Persist, type persisted } from "@/runtime/persistence/storage"
import type { SessionStateKey } from "@/runtime/server/scope"
import {
createDeferredStoreState,
createStoreLoadState,
selectStoreReady,
transitionDeferredStore,
transitionStoreLoad,
type DeferredStoreEvent,
type StoreLoadEvent,
type StoreWrite,
} from "./store-machine"
/** One older key persistence imports a store's value from. */
type CopyFrom = NonNullable<Exclude<Parameters<typeof persisted>[0], string>["copyFrom"]>[number]
@@ -85,7 +97,8 @@ function sessionCopy(from: BuiltinStoreFrom, session: SessionStateKey): CopyFrom
}
/**
* What `Storage.store` returns: a `Persisted` whose `update` and `set` wait for load, then apply in call order.
* What `Storage.store` returns: a `Persisted` whose `update` and `set` wait for load, then apply in call order. When
* the storage read fails, the value never loads and writes are dropped.
*/
export function persistedHandle<T extends object>(input: {
readonly store: T
@@ -94,93 +107,134 @@ export function persistedHandle<T extends object>(input: {
/** The storage read; undefined when storage answered synchronously. */
readonly init: Promise<unknown> | undefined
}) {
const [loaded, setLoaded] = createSignal(!input.init)
const queue: (() => void)[] = []
const [loadState, setLoadState] = createSignal(createStoreLoadState<T>(input.init !== undefined))
const settled = input.init && Promise.withResolvers<void>()
const write = (apply: () => void) => {
if (untrack(loaded)) return apply()
// Runtime-key stores have no setup awaiter, and nothing awaits the load of a store disposed while it loads.
void settled?.promise.catch(() => undefined)
queue.push(apply)
const apply = (write: StoreWrite<T>) => {
if (write.kind === "set") return input.set(reconcile(write.value))
input.set(
produce((draft) => {
// SAFETY: Solid's produce draft is writable recursively; schema readonly fields constrain readers, not drafts.
const returned = write.mutate(draft as Mutable<T>)
if (returned !== undefined)
throw new Error("Persisted.update must not return a value. Use set(next) to replace the value.")
}),
)
}
// Registered after the store's own hydration on the same read, so queued changes apply over the stored value.
const load = input.init?.then(() =>
batch(() => {
queue.splice(0).forEach((apply) => apply())
setLoaded(true)
}),
const dispatch = (event: StoreLoadEvent<T>) => {
const next = transitionStoreLoad(untrack(loadState), event)
setLoadState(next.state)
next.effects.forEach((effect) => {
if (effect.type === "reject") {
if (effect.log) console.error("[plugin storage] Load failed", effect.cause)
return settled?.reject(effect.cause)
}
if (!effect.hydrated) return effect.writes.forEach(apply)
// Promise.try applies each write now and isolates a throw, which still reports its contract error.
const applied = effect.writes.map((write) => Promise.try(() => apply(write)))
applied.forEach(
(write) => void write.catch((cause: unknown) => console.error("[plugin storage] Queued write failed", cause)),
)
void Promise.all(applied).then(
() => settled?.resolve(),
(cause: unknown) => settled?.reject(cause),
)
})
}
// Registered after the store's own hydration on the same read, so queued changes apply over the stored value. One
// batch: readers see the value only with the queued changes on it.
void input.init?.then(
() => batch(() => dispatch({ type: "loaded" })),
(cause: unknown) => dispatch({ type: "failed", cause }),
)
// Runtime-key stores have no setup awaiter: a failed queued mutation must still report its contract error.
void load?.catch((cause: unknown) => console.error("[plugin storage] Load or queued write failed", cause))
if (getOwner()) onCleanup(() => dispatch({ type: "disposed" }))
const handle: Persisted<T> = {
get value() {
return loaded() ? input.store : undefined
},
ready: loaded,
update(mutate) {
write(() =>
input.set(
produce((draft) => {
// SAFETY: Solid's produce draft is writable recursively; schema readonly fields constrain readers, not drafts.
const returned = mutate(draft as Mutable<T>)
if (returned !== undefined)
throw new Error("Persisted.update must not return a value. Use set(next) to replace the value.")
}),
),
)
},
set(next) {
write(() => input.set(reconcile(next)))
return selectStoreReady(loadState()) ? input.store : undefined
},
ready: () => selectStoreReady(loadState()),
update: (mutate) => dispatch({ type: "write", write: { kind: "update", mutate } }),
set: (next) => dispatch({ type: "write", write: { kind: "set", value: next } }),
}
if (load) loads.set(handle, load)
if (settled) loads.set(handle, settled.promise)
return handle
}
/** Settles once a handle from `persistedHandle` has loaded; rejects when its storage read failed. */
/**
* Settles once a handle from `persistedHandle` has loaded and applied the writes that waited; rejects when its storage
* read failed, it was disposed first, or a waiting write threw (the value still loads then).
*/
export function whenLoaded<T>(handle: Persisted<T>) {
return loads.get(handle) ?? Promise.resolve()
}
/**
* A `Persisted` over a store that opens later: `value` is undefined and `ready()` false until `store` returns one, and
* changes made before then wait and apply in order. Call it inside an owner, which ends the hand-over.
* changes made before then, or while `store` reopens, wait and apply in order. Call it inside an owner, which ends the
* hand-over.
*/
export function deferredHandle<T>(store: Accessor<Persisted<T> | undefined>): Persisted<T> {
const queue: ((current: Persisted<T>) => void)[] = []
const machine = { state: createDeferredStoreState<Persisted<T>, T>() }
// Hands changes made before the store opened to it, which applies them once it has loaded.
createRenderEffect(() => {
const current = store()
const dispatch = (event: DeferredStoreEvent<Persisted<T>, T>) => {
const next = transitionDeferredStore(machine.state, event)
if (current && queue.length > 0) untrack(() => queue.splice(0).forEach((apply) => apply(current)))
})
machine.state = next.state
next.effects.forEach((effect) =>
untrack(() => {
if (effect.type === "forward") return forward(effect.handle, effect.write)
// Promise.try isolates a throw, so every write that waited still reaches the store.
effect.writes.forEach(
(write) =>
void Promise.try(() => forward(effect.handle, write)).catch((cause: unknown) =>
console.error("[plugin storage] Queued write failed", cause),
),
)
}),
)
}
// Hands changes made while no store was open to the one that opens, which applies them once it has loaded.
createRenderEffect(() => dispatch({ type: "sync", handle: store() }))
if (getOwner()) onCleanup(() => dispatch({ type: "disposed" }))
// A store that opened in this batch takes the waiting writes before this one, ahead of the render effect.
const write = (value: StoreWrite<T>) => {
dispatch({ type: "sync", handle: untrack(store) })
dispatch({ type: "write", write: value })
}
return {
get value() {
return store()?.value
},
ready: () => store()?.ready() ?? false,
update(mutate) {
const current = untrack(store)
if (current) return current.update(mutate)
queue.push((opened) => opened.update(mutate))
},
set(next) {
const current = untrack(store)
if (current) return current.set(next)
queue.push((opened) => opened.set(next))
},
update: (mutate) => write({ kind: "update", mutate }),
set: (next) => write({ kind: "set", value: next }),
}
}
function forward<T>(handle: Persisted<T>, write: StoreWrite<T>) {
if (write.kind === "set") return handle.set(write.value)
handle.update(write.mutate)
}
/**
* A store of one session, which needs the session's location: it opens once the location is known, and again in a
* new directory. The session is one session's ref or `MountedSession`, so it never reads another session's location.
@@ -1,5 +1,5 @@
import { describe, expect, test } from "bun:test"
import { createComponent, createRoot, createSignal, onCleanup, type Accessor } from "solid-js"
import { batch, createComponent, createRoot, createSignal, onCleanup, type Accessor } from "solid-js"
import { Schema } from "effect"
import {
createKeyed,
@@ -250,6 +250,8 @@ describe("plugin primitives", () => {
test.each([
{ name: "while the storage read is held", location: { directory: "/repo" } },
{ name: "while the session location is unknown", location: undefined },
// Before, the store opened inside the batch took the last write at once, ahead of the writes that waited.
{ name: "as the session location becomes known in the same batch", location: undefined, batched: true },
{ name: "while held with an invalid returned replacement", location: { directory: "/repo" }, invalid: true },
])("store writes made $name apply in order over the stored value", async (row) => {
const held = Promise.withResolvers<void>()
@@ -299,11 +301,18 @@ describe("plugin primitives", () => {
}
})
// Before, the invalid write threw before the load finished: the valid write after it never applied and the store
// never became ready.
if ("invalid" in row) {
// @ts-expect-error JavaScript plugins can return an invalid replacement before hydration too
root.handle.update(() => ({ items: ["wrong"] }))
root.handle.update((draft) => void draft.items.push("valid"))
held.resolve()
await expect(Promise.all(opened.map(whenLoaded))).rejects.toThrow("Use set")
expect({ value: root.handle.value?.items, ready: root.handle.ready() }).toEqual({
value: ["stored", "valid"],
ready: true,
})
root.dispose()
return
@@ -312,11 +321,21 @@ describe("plugin primitives", () => {
root.handle.update((draft) => void draft.items.push("discarded"))
root.handle.set({ items: ["replacement"] })
root.handle.update((draft) => void draft.items.push("first"))
root.handle.update((draft) => void draft.items.push("second"))
const before = { value: root.handle.value, ready: root.handle.ready() }
const second = () => root.handle.update((draft) => void draft.items.push("second"))
if ("batched" in row)
batch(() => {
setLocation({ directory: "/repo" })
second()
})
if (!("batched" in row)) {
second()
setLocation({ directory: "/repo" })
}
setLocation({ directory: "/repo" })
held.resolve()
await Promise.all(opened.map(whenLoaded))
expect({ before, after: root.handle.value?.items, ready: root.handle.ready() }).toEqual({