diff --git a/packages/app/src/runtime/plugin/store-machine.test.ts b/packages/app/src/runtime/plugin/store-machine.test.ts new file mode 100644 index 00000000000..30339bfb1ac --- /dev/null +++ b/packages/app/src/runtime/plugin/store-machine.test.ts @@ -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 => ({ 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(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[] = [{ 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(true) + const ready = createStoreLoadState(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[] = [ + { 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() } + + 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") }, + ]) +}) diff --git a/packages/app/src/runtime/plugin/store-machine.ts b/packages/app/src/runtime/plugin/store-machine.ts new file mode 100644 index 00000000000..0067e931a1b --- /dev/null +++ b/packages/app/src/runtime/plugin/store-machine.ts @@ -0,0 +1,139 @@ +import type { Mutable } from "@opencode/plugin/gui" + +/** A `Persisted` write, kept as data while it waits. */ +export type StoreWrite = + | { readonly kind: "update"; readonly mutate: (draft: Mutable) => undefined } + | { readonly kind: "set"; readonly value: T } + +/** One opened plugin store, from its storage read until its owner goes away. */ +export type StoreLoadState = + /** The storage read is pending; writes wait, in call order. */ + | { readonly status: "loading"; readonly queue: readonly StoreWrite[] } + | { readonly status: "ready" } + /** The storage read failed: the value never loads, and writes are dropped. */ + | { readonly status: "failed" } + | { readonly status: "disposed" } + +export type StoreLoadEvent = + | { readonly type: "write"; readonly write: StoreWrite } + | { readonly type: "loaded" } + | { readonly type: "failed"; readonly cause: unknown } + | { readonly type: "disposed" } + +export type StoreLoadEffect = + /** + * `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[]; 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 = { + readonly state: StoreLoadState + readonly effects: readonly StoreLoadEffect[] +} + +/** `async`: storage answers through a promise, so the value loads later. */ +export function createStoreLoadState(async: boolean): StoreLoadState { + return async ? { status: "loading", queue: [] } : { status: "ready" } +} + +export function transitionStoreLoad(state: StoreLoadState, event: StoreLoadEvent): StoreLoadTransition { + 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(state: StoreLoadState) { + 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 = + /** 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[] } + | { readonly status: "open"; readonly handle: H } + | { readonly status: "disposed" } + +export type DeferredStoreEvent = + /** The store currently open, if any. */ + | { readonly type: "sync"; readonly handle: H | undefined } + | { readonly type: "write"; readonly write: StoreWrite } + | { readonly type: "disposed" } + +export type DeferredStoreEffect = + /** The writes that waited: each applies on its own, in order. */ + | { readonly type: "handover"; readonly handle: H; readonly writes: readonly StoreWrite[] } + /** A write to the open store, which throws to its caller. */ + | { readonly type: "forward"; readonly handle: H; readonly write: StoreWrite } + +export type DeferredStoreTransition = { + readonly state: DeferredStoreState + readonly effects: readonly DeferredStoreEffect[] +} + +export function createDeferredStoreState(): DeferredStoreState { + return { status: "pending", queue: [] } +} + +export function transitionDeferredStore( + state: DeferredStoreState, + event: DeferredStoreEvent, +): DeferredStoreTransition { + 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(state: StoreLoadState, effects: readonly StoreLoadEffect[] = []): StoreLoadTransition { + return { state, effects } +} + +function deferredStep( + state: DeferredStoreState, + effects: readonly DeferredStoreEffect[] = [], +): DeferredStoreTransition { + return { state, effects } +} diff --git a/packages/app/src/runtime/plugin/stores.ts b/packages/app/src/runtime/plugin/stores.ts index b720bcc288e..71375129a10 100644 --- a/packages/app/src/runtime/plugin/stores.ts +++ b/packages/app/src/runtime/plugin/stores.ts @@ -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[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(input: { readonly store: T @@ -94,93 +107,134 @@ export function persistedHandle(input: { /** The storage read; undefined when storage answered synchronously. */ readonly init: Promise | undefined }) { - const [loaded, setLoaded] = createSignal(!input.init) - const queue: (() => void)[] = [] + const [loadState, setLoadState] = createSignal(createStoreLoadState(input.init !== undefined)) + const settled = input.init && Promise.withResolvers() - 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) => { + 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) + + 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) => { + 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 = { 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) - - 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(handle: Persisted) { 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(store: Accessor | undefined>): Persisted { - const queue: ((current: Persisted) => void)[] = [] + const machine = { state: createDeferredStoreState, 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, 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) => { + 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(handle: Persisted, write: StoreWrite) { + 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. diff --git a/packages/app/test-browser/plugin-primitives.test.ts b/packages/app/test-browser/plugin-primitives.test.ts index 163bff2256a..47731f240d4 100644 --- a/packages/app/test-browser/plugin-primitives.test.ts +++ b/packages/app/test-browser/plugin-primitives.test.ts @@ -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() @@ -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({