opencode-plugboard 0.0.0-stage → 0.3.0

package/src/runtime.ts

@@ -0,0 +1,535 @@
+/**
+ * Process runtime: the one owner of everything that outlives a plugin generation.
+ *
+ * OpenCode loads the plugin once per Location, so many generations exist at once, and the module
+ * itself may be re-evaluated per Location or on reload. The runtime therefore lives on
+ * `globalThis` under a versioned key and holds:
+ *   - the generation list: the ACCEPTED generations (request handler, catalog loader), newest
+ *     last. A generation whose Location is a confirmed plugboard app directory is the preferred
+ *     owner: it serves requests and supplies the catalog; without one the newest generation does;
+ *   - the confirmed directories: app directories (real paths strictly inside the canonical data
+ *     root) that `ensureBackend` has verified asynchronously. Nothing in setup touches the
+ *     filesystem, so a Location is unconfirmed, and plugboard's hook and transforms stay no-ops
+ *     there, until a request has confirmed its directory (fail closed);
+ *   - the HTTP listener lifetime: the first generation binds the port, later ones join; when the
+ *     last generation is gone the listener waits a grace period (a config reload recreates every
+ *     generation at once) before closing; requests arriving with no live generation get 503;
+ *   - the event pump lifetime: one fiber on the host's default runtime, owned by no generation
+ *     scope, forwarding bus events of request sessions to the session store. If it dies, the
+ *     requests in flight fail with a 502 instead of waiting for their deadline;
+ *   - the session store (src/session/state.ts), which outlives the listener and owns the request
+ *     guards, their cleanup timers included;
+ *   - the history sweep state: every registered request session is indexed in the host's plugin
+ *     storage and, at most every `SWEEP_INTERVAL_MS`, a sweep prunes old ones past the `history`
+ *     limits (src/session/prune.ts). Both start from request handling (the store's `register`).
+ *
+ * Registration is explicit: `registerGeneration` returns whether the generation was accepted. A
+ * rejected one (different `listen`, options that differ from the live ones, foreign runtime) never
+ * serves and must not install hooks or seeds. `ensureBackend` is the per-directory readiness gate
+ * the session caller awaits before creating a session: it confirms the app directory, boots its
+ * Location from request handling when no generation is there yet, and fails with
+ * `backend_unavailable` (503) when the generation there is rejected or never becomes ready.
+ *
+ * Version policy: a runtime written by a different version is never touched or replaced; this
+ * module then behaves as inert (no listener, no pump, an empty detached session store) and logs
+ * once that the server needs a restart.
+ *
+ * Freeze safety: everything a generation calls from plugin setup or a finalizer here is
+ * synchronous and makes no call on the plugin context or the filesystem. `Registration.dispose`
+ * only mutates state and arms an unref'd timer; the pump is started lazily by request handling,
+ * never awaited. `ensureBackend` and `Registration.refresh` run from request handling only.
+ */
+
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http"
+import { Cause, Effect, Stream } from "effect"
+import { isPlugError, type CatalogModel, type PlugError } from "./contract.js"
+import { errorMessage, log, logError } from "./log.js"
+import { ensureAppDir } from "./session/history.js"
+import type { HistoryPort } from "./session/host.js"
+import { recordSession, sweepHistory, type HistoryLimits } from "./session/prune.js"
+import { createSessionStore, type SessionStore } from "./session/state.js"
+
+export type Handler = (request: IncomingMessage, response: ServerResponse) => void
+
+export interface Registration {
+  /** False when the generation was rejected: it serves nothing and must not install hooks or seeds. */
+  readonly accepted: boolean
+  /** Synchronous; safe in a finalizer. */
+  dispose(): void
+  /**
+   * Whether `ensureBackend` has confirmed this generation's Location as a plugboard app directory.
+   * Synchronous, no filesystem; false until then. Everything plugboard installs for app
+   * directories (context hook, agent deny, seed tools) must be a no-op while this is false.
+   */
+  confirmed(): boolean
+  /** Setup has finished installing the app-directory registrations (the context hook is in place). */
+  ready(): void
+}
+
+export interface GenerationInput {
+  readonly listen: { readonly host: string; readonly port: number }
+  /** The parsed options. Generations must agree on them; compared by canonical JSON (key order is irrelevant). */
+  readonly options: unknown
+  /** This generation's Location directory as the host reports it. Compared as a string with the real path `ensureAppDir` returns; never resolved against the filesystem here. */
+  readonly directory: string
+  readonly handler: Handler
+  /** The enabled models as this generation's Location sees them. */
+  readonly loadCatalog: () => Promise<ReadonlyArray<CatalogModel>>
+  /**
+   * Rebuild what depends on `Registration.confirmed()` (the agent and tool transforms) after it
+   * flipped to true for a generation that was set up before. Called from request handling only,
+   * never from setup or a finalizer.
+   */
+  readonly refresh: () => Promise<void>
+  /** The host storage and session deletion used to index and prune request sessions, with the configured limits (identical in every accepted generation). */
+  readonly history: { readonly port: HistoryPort; readonly limits: HistoryLimits }
+}
+
+const GRACE_MS = 10_000
+/** Earliest next history sweep after one ran (sweeps are triggered by requests, never by a timer). */
+const SWEEP_INTERVAL_MS = 10 * 60_000
+/** Earliest next sweep when one left work behind (its budget ran out). */
+const SWEEP_BACKLOG_MS = 60_000
+/** A sweep stops starting host calls after this long; a hung one stops blocking later sweeps 5 s after. */
+const SWEEP_DEADLINE_MS = 60_000
+/** How long `ensureBackend` waits for a Location to boot and its generation to become ready. */
+const BACKEND_TIMEOUT_MS = 15_000
+const BACKEND_POLL_MS = 25
+
+/** 4: adds the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
+const VERSION = 4
+const KEY = Symbol.for("opencode-plugboard.runtime")
+
+interface Listener {
+  readonly server: Server
+  readonly listen: { readonly host: string; readonly port: number }
+  /** Canonical JSON of the parsed options of the generations the listener serves; later generations must match it. */
+  fingerprint: string
+  mismatchLogged: boolean
+  bound: boolean
+  graceTimer?: ReturnType<typeof setTimeout>
+}
+
+interface Generation {
+  readonly directory: string
+  readonly handler: Handler
+  readonly loadCatalog: GenerationInput["loadCatalog"]
+  readonly refresh: GenerationInput["refresh"]
+  readonly history: GenerationInput["history"]
+  /** The context hook and transforms are installed (setup got to its end). */
+  hooked: boolean
+  /** The transforms have been rebuilt since `confirmed` became true for the directory. */
+  activated: boolean
+  activating?: Promise<void>
+}
+
+interface Pump {
+  /** Set by `stop`: the end of the fiber is then expected. */
+  stopped: boolean
+  stop(): void
+}
+
+interface Runtime {
+  readonly version: number
+  readonly sessions: SessionStore
+  /** Accepted generations only, newest last. */
+  readonly generations: Generation[]
+  /** App directories (real paths, strictly inside the canonical data root) confirmed by `ensureBackend`. */
+  readonly confirmed: Set<string>
+  /** Live rejected generations per directory: tells "rejected" from "no generation yet". */
+  readonly rejected: Map<string, number>
+  /** History sweep rate limit: no sweep starts before `nextAt` (epoch ms) or while one `running`. */
+  readonly sweep: { nextAt: number; running: boolean }
+  listener?: Listener
+  /** Present while a fiber is subscribed to the server event bus. */
+  pump?: Pump
+}
+
+const REJECTED: Registration = { accepted: false, dispose() {}, confirmed: () => false, ready() {} }
+
+/** Used when a foreign-version runtime owns the process: never registered into, never dispatched to. */
+const detachedSessions = createSessionStore()
+let foreignVersionLogged = false
+
+/** The process runtime, created on first use; undefined when a different version already owns the process. */
+function runtime(): Runtime | undefined {
+  const slot = globalThis as Record<symbol, unknown>
+  const existing = slot[KEY] as { readonly version: number } | undefined
+  if (!existing) {
+    const created: Runtime = {
+      version: VERSION,
+      sessions: createSessionStore({ onRegister: (state) => trackSession(created, state.app, state.sessionID) }),
+      generations: [],
+      confirmed: new Set(),
+      rejected: new Map(),
+      sweep: { nextAt: 0, running: false },
+    }
+    slot[KEY] = created
+    return created
+  }
+  if (existing.version === VERSION) return existing as Runtime
+  if (!foreignVersionLogged) {
+    foreignVersionLogged = true
+    logError("runtime.foreign_version", { found: existing.version, expected: VERSION, action: "restart the server" })
+  }
+  return undefined
+}
+
+/**
+ * A request session was just created: index it, then sweep if due. Runs from request handling
+ * (the store's `register`), never awaited, never throws. Uses the preferred generation's host
+ * handles; the storage and `session.remove` are server-wide, so any live generation works.
+ */
+function trackSession(rt: Runtime, app: string, sessionID: string): void {
+  const history = preferred(rt)?.history
+  if (!history) return logError("history.index_skipped", { app, sessionID, reason: "no live generation" })
+  // No limits, no index: an unbounded index would grow opencode.db by a row per request forever (#85).
+  if (history.limits.maxSessions === undefined && history.limits.maxAgeDays === undefined) return
+  void recordSession(history.port, app, sessionID, Date.now())
+    .catch((error) => logError("history.index_failed", { app, sessionID, error: errorMessage(error) }))
+    .then(() => maybeSweep(rt, history))
+}
+
+/**
+ * Run a history sweep when limits are set, none is running and the rate limit allows. Bounded:
+ * see `sweepHistory`. A sweep that leaves work behind is followed up after `SWEEP_BACKLOG_MS`,
+ * a complete one after `SWEEP_INTERVAL_MS`. Logs one line with counts only.
+ */
+async function maybeSweep(rt: Runtime, history: GenerationInput["history"]): Promise<void> {
+  const { limits, port } = history
+  if (limits.maxSessions === undefined && limits.maxAgeDays === undefined) return
+  const now = Date.now()
+  if (rt.sweep.running || now < rt.sweep.nextAt) return
+  rt.sweep.running = true
+  rt.sweep.nextAt = now + SWEEP_INTERVAL_MS
+  const deadline = AbortSignal.timeout(SWEEP_DEADLINE_MS)
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    const result = await Promise.race([
+      sweepHistory({ port, limits, sessions: rt.sessions, now, signal: deadline }),
+      new Promise<undefined>((resolve) => {
+        timer = setTimeout(() => resolve(undefined), SWEEP_DEADLINE_MS + 5_000)
+        timer.unref?.()
+      }),
+    ])
+    if (!result) return logError("history.sweep_timeout", { limit: SWEEP_DEADLINE_MS })
+    if (result.more) rt.sweep.nextAt = Date.now() + SWEEP_BACKLOG_MS
+    log("history.swept", { ...result, durationMs: Date.now() - now })
+  } catch (error) {
+    logError("history.sweep_failed", { error: errorMessage(error) })
+  } finally {
+    clearTimeout(timer)
+    rt.sweep.running = false
+  }
+}
+
+/** The session store shared by every generation in the process. */
+export const sessionStore = (): SessionStore => runtime()?.sessions ?? detachedSessions
+
+/** The generation that serves requests and supplies the catalog: the newest confirmed app-directory one, else the newest. */
+function preferred(rt: Runtime): Generation | undefined {
+  for (let index = rt.generations.length - 1; index >= 0; index--) if (rt.confirmed.has(rt.generations[index]!.directory)) return rt.generations[index]
+  return rt.generations.at(-1)
+}
+
+/**
+ * The catalog of the preferred accepted generation. `fallback` (the caller's own loader) is only
+ * used when no generation is registered, which a live request does not normally see.
+ */
+export function loadServingCatalog(fallback: () => Promise<ReadonlyArray<CatalogModel>>): Promise<ReadonlyArray<CatalogModel>> {
+  const rt = runtime()
+  return (rt ? (preferred(rt)?.loadCatalog ?? fallback) : fallback)()
+}
+
+/** JSON with object keys sorted at every level, so equal options compare equal whatever their key order. */
+function canonicalJson(value: unknown): string {
+  const canonical = (item: unknown): unknown => {
+    if (Array.isArray(item)) return item.map(canonical)
+    if (typeof item !== "object" || item === null) return item
+    return Object.fromEntries(
+      Object.entries(item)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([key, entry]) => [key, canonical(entry)]),
+    )
+  }
+  return JSON.stringify(canonical(value))
+}
+
+const unavailable = (response: ServerResponse, message: string) => {
+  if (response.headersSent) return response.end()
+  const body = JSON.stringify({ error: { message, type: "server_error", code: "unavailable" } })
+  response.writeHead(503, { "content-type": "application/json", "content-length": Buffer.byteLength(body) })
+  response.end(body)
+}
+
+function startListener(rt: Runtime, listen: { host: string; port: number }, fingerprint: string): Listener {
+  const listener: Listener = { server: createServer(), listen, fingerprint, mismatchLogged: false, bound: false }
+  listener.server.on("request", (request, response) => {
+    const current = preferred(rt)
+    if (!current) return unavailable(response, "plugboard is reloading")
+    try {
+      current.handler(request, response)
+    } catch (error) {
+      logError("listener.handler_failed", { error: errorMessage(error) })
+      unavailable(response, "plugboard handler failed")
+    }
+  })
+  listener.server.on("error", (error: NodeJS.ErrnoException) => {
+    if (listener.bound) return logError("listener.error", { code: error.code, error: error.message })
+    // Never bound: another process (or an older runtime) owns the port. Log once, stay inert.
+    logError(error.code === "EADDRINUSE" ? "listener.address_in_use" : "listener.failed", {
+      listen: `${listen.host}:${listen.port}`,
+      error: error.message,
+    })
+  })
+  listener.server.listen(listen.port, listen.host, () => {
+    listener.bound = true
+    log("listener.listening", { listen: `${listen.host}:${listen.port}` })
+  })
+  return listener
+}
+
+function closeListener(rt: Runtime, listener: Listener): void {
+  if (rt.listener !== listener) return
+  rt.listener = undefined
+  try {
+    rt.pump?.stop()
+  } catch {}
+  listener.server.close()
+  listener.server.closeAllConnections()
+  if (listener.bound) log("listener.closed")
+}
+
+/**
+ * Join (or create) the shared listener. The first accepted generation's options are the
+ * listener's (`fingerprint`, canonical JSON of the parsed options): a generation whose options
+ * differ is rejected and logs once while any generation is live, so a project config entry can
+ * never serve with weaker auth than the live one. When none is live (config reload) the next
+ * generation's options are adopted. A different `listen` needs a server restart and is rejected.
+ * A rejected generation is not in the generation list: it never serves, supplies no catalog, and
+ * the caller must not install hooks or seeds for it.
+ */
+export function registerGeneration(input: GenerationInput): Registration {
+  const rt = runtime()
+  if (!rt) return REJECTED
+  const { listen, directory } = input
+  const reject = (): Registration => {
+    rt.rejected.set(directory, (rt.rejected.get(directory) ?? 0) + 1)
+    let disposed = false
+    return {
+      accepted: false,
+      confirmed: () => false,
+      ready() {},
+      dispose() {
+        if (disposed) return
+        disposed = true
+        const left = (rt.rejected.get(directory) ?? 1) - 1
+        if (left > 0) rt.rejected.set(directory, left)
+        else rt.rejected.delete(directory)
+      },
+    }
+  }
+  const fingerprint = canonicalJson(input.options)
+  const listener = (rt.listener ??= startListener(rt, listen, fingerprint))
+  if (listener.listen.host !== listen.host || listener.listen.port !== listen.port) {
+    if (!listener.mismatchLogged) {
+      listener.mismatchLogged = true
+      logError("listener.listen_mismatch", {
+        bound: `${listener.listen.host}:${listener.listen.port}`,
+        requested: `${listen.host}:${listen.port}`,
+        action: "this Location is rejected; restart the server after changing `listen`",
+      })
+    }
+    return reject()
+  }
+  if (listener.fingerprint !== fingerprint) {
+    if (rt.generations.length > 0) {
+      if (!listener.mismatchLogged) {
+        listener.mismatchLogged = true
+        logError("listener.options_mismatch", { action: "this Location is rejected; global config is authoritative" })
+      }
+      return reject()
+    }
+    listener.fingerprint = fingerprint
+    listener.mismatchLogged = false
+  }
+  if (listener.graceTimer) clearTimeout(listener.graceTimer)
+  listener.graceTimer = undefined
+  const generation: Generation = {
+    directory,
+    handler: input.handler,
+    loadCatalog: input.loadCatalog,
+    refresh: input.refresh,
+    history: input.history,
+    hooked: false,
+    // A directory confirmed before this Location booted needs no rebuild: its transforms already read `confirmed()` as true.
+    activated: rt.confirmed.has(directory),
+  }
+  rt.generations.push(generation)
+  return {
+    accepted: true,
+    confirmed: () => rt.confirmed.has(directory),
+    ready() {
+      generation.hooked = true
+    },
+    dispose() {
+      const index = rt.generations.indexOf(generation)
+      if (index !== -1) rt.generations.splice(index, 1)
+      if (rt.listener !== listener || rt.generations.length > 0 || listener.graceTimer) return
+      listener.graceTimer = setTimeout(() => {
+        listener.graceTimer = undefined
+        if (rt.generations.length === 0) closeListener(rt, listener)
+      }, GRACE_MS)
+      listener.graceTimer.unref?.()
+    },
+  }
+}
+
+/**
+ * Start the process-wide event pump if it is not running. The bus is server-wide, so the store
+ * drops everything that is not a registered request session before it is buffered. The pump is
+ * stopped when the listener closes and restarted by the next caller. `subscribe` is the calling
+ * generation's bus subscription; it is only invoked when a pump actually starts.
+ *
+ * If the fiber ends without `stop` (the subscription failed or was closed), no more events
+ * reach the store: every registered request is failed with a 502 and the pump is restarted by
+ * the next request.
+ */
+export function ensurePump(subscribe: () => Stream.Stream<unknown, unknown, never>): void {
+  const rt = runtime()
+  if (!rt || rt.pump) return
+  const fiber = Effect.runFork(subscribe().pipe(Stream.runForEach((event) => Effect.sync(() => rt.sessions.dispatch(event)))))
+  const pump: Pump = {
+    stopped: false,
+    stop: () => {
+      pump.stopped = true
+      fiber.interruptUnsafe()
+    },
+  }
+  rt.pump = pump
+  fiber.addObserver((exit) => {
+    if (rt.pump === pump) rt.pump = undefined
+    if (pump.stopped) return
+    const failed = rt.sessions.failAll({
+      status: 502,
+      kind: "server",
+      code: "event_stream_lost",
+      message: "Lost the event stream of the OpenCode server",
+    })
+    logError("pump.stopped", {
+      exit: exit._tag,
+      failedRequests: failed,
+      ...(exit._tag === "Failure" ? { error: (Cause.pretty(exit.cause).split("\n")[0] ?? "").slice(0, 200) } : {}),
+    })
+  })
+}
+
+const backendUnavailable = (message: string): PlugError => ({ status: 503, kind: "server", code: "backend_unavailable", message })
+
+/** Rejects when `signal` aborts; the underlying promise is left running (its late result or error is swallowed). */
+function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(new Error("aborted"))
+    if (signal.aborted) return onAbort()
+    signal.addEventListener("abort", onAbort, { once: true })
+    promise.then(
+      (value) => (signal.removeEventListener("abort", onAbort), resolve(value)),
+      (error) => (signal.removeEventListener("abort", onAbort), reject(error)),
+    )
+  })
+}
+
+const sleep = (ms: number, signal: AbortSignal) =>
+  new Promise<void>((resolve) => {
+    if (signal.aborted) return resolve()
+    const timer = setTimeout(done, ms)
+    function done() {
+      clearTimeout(timer)
+      signal.removeEventListener("abort", done)
+      resolve()
+    }
+    signal.addEventListener("abort", done, { once: true })
+  })
+
+/** Rebuild the transforms of a generation set up before its directory was confirmed; shared by concurrent requests. */
+function activate(generation: Generation): Promise<void> {
+  generation.activating ??= generation.refresh().then(
+    () => void (generation.activated = true),
+    (error) => {
+      generation.activating = undefined
+      throw error
+    },
+  )
+  return generation.activating
+}
+
+/**
+ * The per-directory readiness gate (docs/architecture.md): resolves with undefined once an
+ * accepted generation in the app directory of `app` is ready to rewrite request sessions, else
+ * with a `PlugError`, so the caller never prompts a session that no context hook would rewrite.
+ * Only ever called from request handling, never from plugin setup.
+ *
+ * 1. Create and canonicalize the app directory asynchronously (`ensureAppDir`: symlink
+ *    containment, the resolved directory must be strictly inside the canonical data root).
+ * 2. Confirm it (before booting, so a Location that boots now sees it at setup).
+ * 3. No generation there yet: `boot(directory)` makes the host boot the Location (any host call
+ *    scoped to that directory that builds it; the entry passes `ctx.agent.list({ location })`),
+ *    which loads the plugin there. Abandoned, not interrupted, when the request ends.
+ * 4. Generations set up before the directory was confirmed get their transforms rebuilt
+ *    (`GenerationInput.refresh`).
+ * 5. Wait, bounded by `signal` and a timeout, until a generation there is accepted (so it runs
+ *    with the live options) and has installed its hook. A generation that was rejected (options
+ *    or `listen` differ) is a 503 `backend_unavailable` at once.
+ */
+export async function ensureBackend(
+  app: string,
+  signal: AbortSignal,
+  boot: (directory: string) => Promise<unknown>,
+): Promise<PlugError | undefined> {
+  const rt = runtime()
+  if (!rt) return backendUnavailable("A different plugboard runtime owns this server process; restart the server")
+  try {
+    const directory = await ensureAppDir(app)
+    if (isPlugError(directory)) return directory
+    const bounded = AbortSignal.any([signal, AbortSignal.timeout(BACKEND_TIMEOUT_MS)])
+    rt.confirmed.add(directory)
+
+    let booted = false
+    while (true) {
+      if (bounded.aborted)
+        return backendUnavailable(
+          signal.aborted ? "The request ended before the app directory was ready" : "Timed out waiting for the plugboard app directory to load its backend",
+        )
+      const here = rt.generations.filter((generation) => generation.directory === directory)
+      if (here.length === 0) {
+        if ((rt.rejected.get(directory) ?? 0) > 0)
+          return backendUnavailable("The plugboard app directory was rejected (its plugin options or `listen` differ from the live ones)")
+        if (!booted) {
+          booted = true
+          try {
+            await abortable(boot(directory), bounded)
+          } catch (error) {
+            if (bounded.aborted) continue
+            logError("backend.boot_failed", { app, error: errorMessage(error) })
+            return backendUnavailable("Could not start the plugboard app directory")
+          }
+          continue
+        }
+      } else {
+        try {
+          await abortable(Promise.all(here.filter((generation) => !generation.activated).map(activate)), bounded)
+        } catch (error) {
+          if (bounded.aborted) continue
+          throw error
+        }
+        if (here.some((generation) => generation.hooked && generation.activated)) return undefined
+      }
+      await sleep(BACKEND_POLL_MS, bounded)
+    }
+  } catch (error) {
+    if (signal.aborted) return backendUnavailable("The request ended before the app directory was ready")
+    logError("backend.check_failed", { app, error: errorMessage(error) })
+    return backendUnavailable("Could not prepare the plugboard app directory")
+  }
+}