opencode-courier 0.2.2 → 0.3.0

package/dist/hub.js

@@ -0,0 +1,343 @@
+import { randomInt } from "node:crypto";
+import { hostname } from "node:os";
+import { deliverReleased } from "./group.js";
+import { num, obj, str } from "./json.js";
+import { deliverDue, TICK_MS } from "./later.js";
+import { processWide } from "./storage.js";
+/**
+ * The plugin's process-wide state on `globalThis`, shared by every loaded copy; only this module puts
+ * it there. `HUB_VERSION`, the fixed claim keys and version skew: docs/reference.md, § Several copies.
+ */
+export const HUB_VERSION = 2;
+/** The key of the hub; a copy that finds another version there keeps its own under `${HUB_KEY}@<version>`. */
+export const HUB_KEY = "opencode-courier.hub";
+const realTimers = {
+    every: (run, ms) => setInterval(run, ms),
+    stop: (timer) => clearInterval(timer),
+    wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+/**
+ * The storage key, shared by every server on one data directory, naming the server whose scheduler
+ * delivers `courier_later` messages: `{ server, at }`, its id and when it last wrote (epoch ms).
+ */
+export const OWNER_KEY = "scheduler/owner";
+/** How long the owner key holds without being renewed; the owner renews it every tick, four times as often. */
+export const OWNER_EXPIRY_MS = 4 * TICK_MS;
+/**
+ * How old the owner's own key may be for it to renew the key and deliver at once. An older one,
+ * which it may no longer hold by the time it writes, is taken again like a free one, with the wait.
+ */
+export const OWNER_RENEW_MS = OWNER_EXPIRY_MS / 2;
+/** The wait between writing the owner key and reading it back, at least `OWNER_WAIT_MS` and up to twice that. */
+export const OWNER_WAIT_MS = 500;
+/**
+ * This server's id in the owner key: the same for every copy of the plugin in the process, and
+ * different in every other process, a restart of this one included.
+ */
+export const SERVER = `${hostname()}:${process.pid}:${performance.timeOrigin}`;
+async function readOwner(ports) {
+    const value = obj(await ports.storage.get(OWNER_KEY));
+    const server = str(value.server);
+    const at = num(value.at);
+    return server !== undefined && at !== undefined ? { server, at } : undefined;
+}
+/**
+ * How long an unloading instance waits for the work it leaves behind: what it started itself, a tick
+ * or a notice under way through it, and on the last leave the owner key's release.
+ */
+export const LEAVE_MS = 2_000;
+/** Whether a key written at `at` still holds at `now`; one from the future, after the clock went back, holds as long. */
+const holds = (at, now, ms) => Math.abs(now - at) < ms;
+/** How many subscriptions to OpenCode's events a hub keeps, each through another member: one, and a standby. */
+export const WATCHERS = 2;
+/**
+ * Finds or makes this copy's hub in `registry`: the one under `HUB_KEY`, or its own under a versioned
+ * key when another version holds that; its claim sets are the pre-hub keys', made when missing.
+ */
+export function open(registry, timers = realTimers, server = SERVER) {
+    const shared = (name, create) => processWide(`opencode-courier.${name}`, create, registry);
+    const questionState = () => {
+        // Field by field, since a copy before the hub may have made it without the fields added later.
+        const state = shared("questions", () => ({}));
+        state.questions ??= new Map();
+        state.noticed ??= new Set();
+        state.shown ??= new Map();
+        state.passing ??= new Map();
+        state.answered ??= new Set();
+        state.loaded ??= new Set();
+        state.following ??= 0;
+        state.followed ??= false;
+        state.shutdowns ??= new Map();
+        state.closingWaiters ??= new Set();
+        return state;
+    };
+    const create = () => ({
+        version: HUB_VERSION,
+        members: new Set(),
+        scheduler: {},
+        watchers: [],
+        claimed: shared("claimed", () => new Set()),
+        watched: shared("watched", () => ({ seen: new Set(), waiting: new Set(), answered: new Set() })),
+        forms: shared("forms", () => ({ told: new Map(), settled: new Set() })),
+        locations: shared("locations", () => new Map()),
+        receivers: shared("receiver", () => ({})),
+        questions: questionState(),
+        skewLogged: false,
+    });
+    const found = registry[Symbol.for(HUB_KEY)];
+    // The version of the hub of another copy found under `HUB_KEY`, if one is there.
+    const skew = found != null && found.version !== HUB_VERSION ? { version: found.version } : undefined;
+    const hub = processWide(skew ? `${HUB_KEY}@${HUB_VERSION}` : HUB_KEY, create, registry);
+    /**
+     * Whether this server holds the owner key, taking or renewing it through `ports`. A free, expired
+     * or stalled key is written and read back after a random wait: the last of two writers holds it.
+     */
+    const own = async (ports) => {
+        const held = await readOwner(ports);
+        const now = ports.now();
+        if (held && held.server !== server && holds(held.at, now, OWNER_EXPIRY_MS))
+            return false;
+        await ports.storage.set(OWNER_KEY, { server, at: now });
+        if (fresh(held, now))
+            return true;
+        await timers.wait(randomInt(OWNER_WAIT_MS, 2 * OWNER_WAIT_MS));
+        return (await readOwner(ports))?.server === server;
+    };
+    /** Whether `held` is this server's key, recent enough to renew without reading it back. */
+    const fresh = (held, now) => held?.server === server && holds(held.at, now, OWNER_RENEW_MS);
+    /** Renews the owner key if this server holds it fresh: what a tick does, for a tick still delivering. */
+    const renew = async (ports) => {
+        const now = ports.now();
+        if (fresh(await readOwner(ports), now))
+            await ports.storage.set(OWNER_KEY, { server, at: now });
+    };
+    /** Whether a hub of another version in the process has instances, so its loop, under the same server id, still holds the key. */
+    const othersRunning = () => Object.getOwnPropertySymbols(registry).some((key) => {
+        const other = registry[key];
+        const name = key.description ?? "";
+        return other !== hub && (name === HUB_KEY || name.startsWith(`${HUB_KEY}@`)) && Number(other?.members?.size) > 0;
+    });
+    /**
+     * Removes the owner key if this server holds it, so another takes over at its next tick: once the
+     * loop has stopped, no tick is under way and no other hub version here runs a loop under this id.
+     */
+    const release = async (ports) => {
+        const scheduler = hub.scheduler;
+        const idle = () => scheduler.timer === undefined && !scheduler.running && !scheduler.ticking && !othersRunning();
+        if (idle() && (await readOwner(ports))?.server === server && idle())
+            await ports.storage.remove(OWNER_KEY);
+    };
+    /**
+     * Whether the tick under way still holds the next up: within a minute of its start it does; past
+     * that it is taken to hang, holding up only while its member is loaded. `recent` says which.
+     */
+    const busy = () => {
+        const { running, ticking } = hub.scheduler;
+        if (!running)
+            return { busy: ticking !== undefined && hub.members.has(ticking), recent: false };
+        const first = hub.members.values().next().value;
+        if (first && holds(running.since, first.later.now(), OWNER_EXPIRY_MS))
+            return { busy: true, recent: true };
+        return { busy: hub.members.has(running.member), recent: false };
+    };
+    /** `busy`, renewing the key for a recent tick under way, as each tick falling due meanwhile does. */
+    const underWay = () => {
+        const state = busy();
+        const first = hub.members.values().next().value;
+        if (state.recent && first)
+            void renew(first.later).catch((error) => first.log(`courier_later scheduler: ${String(error)}`));
+        return state.busy;
+    };
+    // One tick, through the first loaded member, by the server holding the owner key. The claim on each
+    // delivery stays, as a second line of defence against a pre-hub copy running its own interval.
+    const tick = async () => {
+        const scheduler = hub.scheduler;
+        if (underWay())
+            return;
+        scheduler.nudged = false;
+        const owner = hub.members.values().next().value;
+        if (!owner)
+            return;
+        let since;
+        try {
+            since = owner.later.now();
+        }
+        catch (error) {
+            owner.log(`courier_later scheduler: ${String(error)}`);
+            return;
+        }
+        let end = () => { };
+        const run = { member: owner, since, done: new Promise((resolve) => (end = resolve)) };
+        scheduler.running = run;
+        scheduler.ticking = owner;
+        // `done` settles however the tick ends, and the key is given back, a log that throws included:
+        // leaves wait for it. A log that throws is not logged again; there is nowhere left to tell.
+        const tell = (message) => {
+            try {
+                owner.log(message);
+            }
+            catch { }
+        };
+        try {
+            if ((await own(owner.later)) && scheduler.timer !== undefined && hub.members.has(owner)) {
+                await deliverDue(owner.later, hub.claimed);
+                await deliverReleased(owner.later, hub.claimed);
+            }
+        }
+        catch (error) {
+            tell(`courier_later scheduler: ${String(error)}`);
+        }
+        finally {
+            // A tick past its minute may have been followed by another, whose record stays.
+            if (scheduler.running === run) {
+                scheduler.running = undefined;
+                scheduler.ticking = undefined;
+            }
+        }
+        // A loop stopped meanwhile, its members gone, gives back the key this tick may have written.
+        if (scheduler.timer === undefined)
+            await release(owner.later).catch((error) => tell(`courier_later scheduler: owner key not released: ${String(error)}`));
+        end();
+        if (scheduler.nudged && scheduler.timer !== undefined)
+            void scheduler.tick?.();
+    };
+    // Through the hub's tick, the copy loaded last's, like the loop's; this copy's only before one joined. A
+    // tick under way runs once more when it ends, so nothing is started here meanwhile.
+    const nudge = () => {
+        const scheduler = hub.scheduler;
+        if (scheduler.timer === undefined)
+            return;
+        scheduler.nudged = true;
+        if (!busy().busy)
+            void (scheduler.tick ?? tick)();
+    };
+    // Subscriptions through the earliest members without one, the longest loaded, until there are
+    // `WATCHERS`; never through `leaving`.
+    const watch = (leaving) => {
+        const watching = new Set(hub.watchers.map((watcher) => watcher.member));
+        for (const member of hub.members) {
+            if (hub.watchers.length >= WATCHERS || !hub.subscribe)
+                return;
+            if (member !== leaving && !watching.has(member))
+                hub.watchers.push(hub.subscribe(member));
+        }
+    };
+    // The work each member of this copy started and handed over, until it settles.
+    const work = new WeakMap();
+    const track = (member, started) => {
+        const set = work.get(member) ?? new Set();
+        work.set(member, set);
+        const settled = started.catch(() => { }).finally(() => set.delete(settled));
+        set.add(settled);
+    };
+    const join = (member) => {
+        if (skew && !hub.skewLogged) {
+            hub.skewLogged = true;
+            member.log(`courier: another copy of the plugin with hub version ${String(skew.version)} has been loaded in this process; ` +
+                `this copy (hub version ${HUB_VERSION}) keeps its own under ${HUB_KEY}@${HUB_VERSION} and shares the claim sets with it`);
+        }
+        hub.members.add(member);
+        hub.locations.set(member, member.permission);
+        const scheduler = hub.scheduler;
+        scheduler.tick = tick;
+        if (scheduler.timer === undefined) {
+            scheduler.timer = timers.every(() => void hub.scheduler.tick?.(), TICK_MS);
+            void tick();
+        }
+        watch();
+        return () => {
+            hub.members.delete(member);
+            hub.locations.delete(member);
+            // What this member leaves behind: the work it handed over, and a tick under way through it,
+            // which keeps using its storage and session until it ends.
+            const behind = [...(work.get(member) ?? [])];
+            if (scheduler.running?.member === member)
+                behind.push(scheduler.running.done);
+            // The other subscription, already connected, follows the events meanwhile; this one is replaced
+            // before it ends, after its current event, so the relay's watcher count never drops to none.
+            const index = hub.watchers.findIndex((watcher) => watcher.member === member);
+            if (index >= 0) {
+                const [leaving] = hub.watchers.splice(index, 1);
+                watch(member);
+                leaving.stop.abort();
+                behind.push(leaving.done);
+            }
+            if (hub.members.size === 0 && scheduler.timer !== undefined) {
+                timers.stop(scheduler.timer);
+                scheduler.timer = undefined;
+                // After the tick under way, whichever copy started it, which may be writing the key.
+                behind.push((async () => {
+                    await scheduler.running?.done;
+                    await release(member.later);
+                })().catch((error) => member.log(`courier_later scheduler: owner key not released: ${String(error)}`)));
+            }
+            if (behind.length === 0)
+                return Promise.resolve();
+            return Promise.race([Promise.allSettled(behind).then(() => { }), timers.wait(LEAVE_MS)]);
+        };
+    };
+    return {
+        hub,
+        join,
+        track,
+        gate: shared("spawning", () => ({ reserved: new Set(), turn: Promise.resolve() })),
+        inbox: shared("inbox", () => new Map()),
+        nudge,
+    };
+}
+const opened = open(globalThis);
+/** This copy's hub, in the process. */
+export const hub = opened.hub;
+/** Joins this copy's hub; see `Opened.join`. */
+export const join = opened.join;
+/** Hands this copy's hub work a member started; see `Opened.track`. */
+export const track = opened.track;
+/** The spawns under way in the process; see `Opened.gate`. */
+export const gate = opened.gate;
+/** The types of the items enqueued for spawned sessions; see `Opened.inbox`. */
+export const inbox = opened.inbox;
+/** Has this copy's scheduler deliver what is due now; see `Opened.nudge`. */
+export const nudge = opened.nudge;
+/** The member of this copy's hub set up with `location` that joined last, while it is loaded. */
+export function memberAt(location) {
+    let found;
+    for (const member of hub.members)
+        if (member.location === location)
+            found = member;
+    return found;
+}
+/**
+ * The question ports of the member that just joined at `location`, while it is loaded: resolved once,
+ * so a later instance at the same location does not take its place while this one is still loaded.
+ */
+export function portsAt(location) {
+    const own = memberAt(location);
+    return () => (own && hub.members.has(own) ? own.questions : undefined);
+}
+/** The permission domains of the loaded instances. */
+export const permissions = () => hub.locations.values();
+/**
+ * For tests: forgets every remembered id, the spawns under way and the question relay's state, loaded
+ * instances and watcher count included. Members, locations and the receiver are left to unloading.
+ */
+export function resetHub() {
+    gate.reserved.clear();
+    inbox.clear();
+    hub.claimed.clear();
+    hub.watched.seen.clear();
+    hub.watched.waiting.clear();
+    hub.watched.answered.clear();
+    hub.forms.told.clear();
+    hub.forms.settled.clear();
+    const questions = hub.questions;
+    questions.questions.clear();
+    questions.noticed.clear();
+    questions.shown.clear();
+    questions.passing.clear();
+    questions.answered.clear();
+    questions.loaded.clear();
+    questions.following = 0;
+    questions.followed = false;
+    questions.shutdowns.clear();
+    questions.closingWaiters.clear();
+}

package/dist/index.d.ts

@@ -1,21 +1,13 @@
 import { Plugin } from "@opencode/plugin";
 import { Plugin as EffectPlugin } from "@opencode/plugin/effect";
-import { type QuestionPorts } from "./question.js";
-/** What a question relay needs from the plugin instance that wraps the question tool. */
-export interface RelaySlot {
-    ports?: QuestionPorts;
-}
 /**
- * The courier tools, scheduler, webhook receiver and event watcher, as a promise plugin. `relay`
- * receives this instance's ports for the question relay while it is loaded.
+ * The courier tools and webhook receiver, as a promise plugin joining the hub that runs the scheduler
+ * and the watcher; its member carries the location by which the question relay finds its ports.
  */
-export declare const courier: (relay?: RelaySlot) => Plugin.Plugin;
+export declare const courier: () => Plugin.Plugin;
 /**
- * The plugin OpenCode loads. It is an Effect plugin, because the question relay wraps OpenCode's own
- * question tool, whose execute the promise API hands out only as a promise that cannot be
- * interrupted, so a child's question could not be withdrawn once its parent answered. Everything
- * else is the promise plugin above, run through the plugin package's own adapter, as OpenCode runs
- * a promise plugin.
+ * The plugin OpenCode loads: an Effect plugin, since the question relay wraps OpenCode's question tool
+ * and only the Effect API makes its call interruptible; the rest is the promise plugin, adapted.
  */
 declare const _default: EffectPlugin.Plugin<import("effect/Scope").Scope>;
 export default _default;