opencode-plugboard 0.2.1 → 0.4.0

package/src/runtime.ts

@@ -18,7 +18,10 @@
  *     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.
+ *     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
@@ -42,6 +45,8 @@ 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
@@ -76,15 +81,23 @@ export interface GenerationInput {
    * 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
 
-/** 3: the runtime tracks confirmed directories and rejected generations (a version-2 runtime lacks both). */
-const VERSION = 3
+/** 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 {
@@ -102,6 +115,7 @@ interface Generation {
   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. */
@@ -124,6 +138,8 @@ interface Runtime {
   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
@@ -140,7 +156,14 @@ 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(), generations: [], confirmed: new Set(), rejected: new Map() }
+    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
   }
@@ -152,6 +175,54 @@ function runtime(): Runtime | undefined {
   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
 
@@ -290,6 +361,7 @@ export function registerGeneration(input: GenerationInput): Registration {
     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),

package/src/session/host.ts

@@ -89,6 +89,46 @@ export function createSessionPort(ctx: HostContext): SessionPort {
   }
 }
 
+/**
+ * What the history index needs from the host: the plugin's own key-value storage (`ctx.storage`,
+ * namespaced by plugin id and shared by every Location of the server) and `session.remove`. The
+ * plugin session API has no `list`, so plugboard indexes its own request sessions in that storage
+ * and prunes from the index (src/session/prune.ts).
+ */
+export interface HistoryPort {
+  put(key: string, value: string): Promise<void>
+  drop(key: string): Promise<void>
+  /** Keys under `prefix` in ascending order, after `after` (exclusive); `next` is set when more remain. */
+  scan(input: { readonly prefix: string; readonly after?: string; readonly limit: number }): Promise<{ readonly keys: ReadonlyArray<string>; readonly next?: string }>
+  /** `missing` when the session no longer exists (the host's `Session.NotFoundError`); any other failure rejects. */
+  removeSession(sessionID: string): Promise<"removed" | "missing">
+}
+
+const failureTag = (error: unknown): unknown => (typeof error === "object" && error !== null ? (error as { _tag?: unknown })._tag : undefined)
+
+/** `ctx.storage` and `ctx.session.remove` as a Promise port. The branded session ID is the same host-issued string as above. */
+export function createHistoryPort(ctx: HostContext): HistoryPort {
+  return {
+    put: (key, value) => Effect.runPromise(ctx.storage.set(key, value)),
+    drop: (key) => Effect.runPromise(ctx.storage.remove(key)),
+    scan: (input) =>
+      Effect.runPromise(ctx.storage.scan(input)).then((result) => ({
+        keys: result.entries.map((entry) => entry.key),
+        ...(result.next === undefined ? {} : { next: result.next }),
+      })),
+    removeSession: (sessionID) =>
+      Effect.runPromise(
+        ctx.session.remove({ sessionID: hostSessionID(sessionID) } satisfies Parameters<HostSession["remove"]>[0]).pipe(
+          Effect.match({ onSuccess: () => undefined, onFailure: (error) => ({ error }) }),
+        ),
+      ).then((failed) => {
+        if (failed === undefined) return "removed" as const
+        if (failureTag(failed.error) === "Session.NotFoundError") return "missing" as const
+        throw failed.error
+      }),
+  }
+}
+
 const record = (value: unknown): Record<string, unknown> | undefined =>
   typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined
 

package/src/session/prune.ts

@@ -0,0 +1,175 @@
+/**
+ * History pruning: an index of plugboard's own request sessions and the sweep that deletes the
+ * old ones.
+ *
+ * The plugin session API has no `list`, so plugboard cannot ask the host which sessions it owns.
+ * It keeps an index in the plugin's own host storage (`ctx.storage`, a key-value table in the
+ * host database, shared by every Location): one key per request session,
+ *
+ *   history/<app>/<created, 15 digits of epoch ms>/<sessionID>
+ *
+ * Everything the sweep needs is in the key, so a scan returns an app's sessions oldest first.
+ * Sessions created before this index existed are not in it and are never pruned.
+ *
+ * Both functions run from request handling only (the runtime calls them), never from plugin
+ * setup or a finalizer. A sweep does bounded work: it reads at most `maxScan` index entries per
+ * app, makes at most `maxDeletes` host deletions and stops at its deadline; what is left waits for
+ * the next sweep. A session whose request guard is still in the session store (the host
+ * execution has not ended) is never deleted.
+ */
+
+import type { HistoryPort } from "./host.js"
+import type { SessionStore } from "./state.js"
+
+/** Pruning limits. A field that is unset is not applied; with none set nothing is ever deleted. */
+export interface HistoryLimits {
+  /** Keep at most this many sessions per app (the newest). */
+  readonly maxSessions?: number
+  /** Delete sessions older than this many days. */
+  readonly maxAgeDays?: number
+}
+
+export interface SweepResult {
+  readonly apps: number
+  /** Index entries read. */
+  readonly scanned: number
+  readonly removed: number
+  /** Already gone from the host (deleted by hand); only the index entry was dropped. */
+  readonly missing: number
+  /** Host deletions or index updates that failed; retried by the next sweep. */
+  readonly failed: number
+  /** Over a limit but skipped because the request guard is still active. */
+  readonly active: number
+  /** Work was left (budget, deadline or scan cap reached): run the next sweep soon. */
+  readonly more: boolean
+}
+
+export interface SweepInput {
+  readonly port: HistoryPort
+  readonly limits: HistoryLimits
+  readonly sessions: SessionStore
+  readonly now: number
+  /** Aborts the sweep between host calls. */
+  readonly signal: AbortSignal
+  /** Most host deletions per sweep. */
+  readonly maxDeletes?: number
+  /** Most index entries read per app per sweep. */
+  readonly maxScan?: number
+}
+
+const PREFIX = "history/"
+const AT_WIDTH = 15
+const DAY_MS = 86_400_000
+const PAGE = 500
+const MAX_DELETES = 200
+const MAX_SCAN = 20_000
+
+export const indexKey = (app: string, createdAt: number, sessionID: string): string =>
+  `${PREFIX}${app}/${String(Math.max(0, Math.floor(createdAt))).padStart(AT_WIDTH, "0")}/${sessionID}`
+
+/** Index one new request session. The value repeats the ID; the key carries app and time. */
+export const recordSession = (port: HistoryPort, app: string, sessionID: string, createdAt: number): Promise<void> =>
+  port.put(indexKey(app, createdAt, sessionID), sessionID)
+
+interface Entry {
+  readonly key: string
+  readonly sessionID: string
+  readonly createdAt: number
+}
+
+function parseKey(key: string): Entry | undefined {
+  const [, at, ...rest] = key.slice(PREFIX.length).split("/")
+  const createdAt = Number(at)
+  const sessionID = rest.join("/")
+  if (!/^\d+$/.test(at ?? "") || !Number.isFinite(createdAt) || sessionID.length === 0) return undefined
+  return { key, sessionID, createdAt }
+}
+
+/** App names in the index, found by hopping over each app's keys (one tiny scan per app). */
+async function indexedApps(port: HistoryPort, signal: AbortSignal): Promise<string[]> {
+  const apps: string[] = []
+  let after: string | undefined
+  while (!signal.aborted) {
+    const page = await port.scan({ prefix: PREFIX, ...(after === undefined ? {} : { after }), limit: 1 })
+    const first = page.keys[0]
+    if (first === undefined) break
+    const app = first.slice(PREFIX.length).split("/")[0] ?? ""
+    if (app.length > 0) apps.push(app)
+    // `\uffff` sorts after every character of an ID or timestamp, so this skips the rest of the app.
+    after = `${PREFIX}${app}/\uffff`
+  }
+  return apps
+}
+
+/** One app's entries, oldest first, at most `maxScan`; `capped` when more remain in the index. */
+async function readApp(port: HistoryPort, app: string, maxScan: number, signal: AbortSignal): Promise<{ entries: Entry[]; capped: boolean }> {
+  const entries: Entry[] = []
+  const prefix = `${PREFIX}${app}/`
+  let after: string | undefined
+  while (!signal.aborted) {
+    const page = await port.scan({ prefix, ...(after === undefined ? {} : { after }), limit: Math.min(PAGE, maxScan - entries.length) })
+    for (const key of page.keys) {
+      const entry = parseKey(key)
+      if (entry) entries.push(entry)
+    }
+    if (page.next === undefined) return { entries, capped: false }
+    if (entries.length >= maxScan) return { entries, capped: true }
+    after = page.next
+  }
+  return { entries, capped: true }
+}
+
+/**
+ * One pass over the index. Per app, the sessions to delete are a prefix of its oldest-first list:
+ * as many as exceed `maxSessions`, or are older than `maxAgeDays`, whichever is more. A session
+ * with an active request guard is skipped (it still counts as kept). Entries of sessions the host
+ * no longer has are dropped. A scan that hit `maxScan` only undercounts the app, so it can only
+ * delete fewer sessions than the limit asks for, never more.
+ */
+export async function sweepHistory(input: SweepInput): Promise<SweepResult> {
+  const { port, limits, sessions, signal } = input
+  const maxDeletes = input.maxDeletes ?? MAX_DELETES
+  const maxScan = input.maxScan ?? MAX_SCAN
+  const cutoff = limits.maxAgeDays === undefined ? undefined : input.now - limits.maxAgeDays * DAY_MS
+  let scanned = 0
+  let removed = 0
+  let missing = 0
+  let failed = 0
+  let active = 0
+  let attempts = 0
+  let more = false
+
+  const apps = await indexedApps(port, signal)
+  for (const app of apps) {
+    if (signal.aborted) {
+      more = true
+      break
+    }
+    const { entries, capped } = await readApp(port, app, maxScan, signal)
+    scanned += entries.length
+    if (capped) more = true
+    const excess = limits.maxSessions === undefined ? 0 : Math.max(0, entries.length - limits.maxSessions)
+    const expired = cutoff === undefined ? 0 : entries.findIndex((entry) => entry.createdAt >= cutoff)
+    const count = Math.max(excess, cutoff === undefined ? 0 : expired === -1 ? entries.length : expired)
+    for (const entry of entries.slice(0, count)) {
+      if (signal.aborted || attempts >= maxDeletes) {
+        more = true
+        break
+      }
+      // Checked right before the host call: a guard that is still registered means the host execution is running.
+      if (sessions.lookup(entry.sessionID)) {
+        active++
+        continue
+      }
+      attempts++
+      try {
+        if ((await port.removeSession(entry.sessionID)) === "removed") removed++
+        else missing++
+        await port.drop(entry.key)
+      } catch {
+        failed++
+      }
+    }
+  }
+  return { apps: apps.length, scanned, removed, missing, failed, active, more }
+}

package/src/session/state.ts

@@ -67,7 +67,12 @@ interface Entry {
   timer?: ReturnType<typeof setTimeout>
 }
 
-export function createSessionStore(): SessionStore {
+export interface SessionStoreOptions {
+  /** Called once per `register`, from request handling (the runtime indexes the session for pruning). Must not block; errors are logged. */
+  readonly onRegister?: (state: RequestState) => void
+}
+
+export function createSessionStore(options: SessionStoreOptions = {}): SessionStore {
   const entries = new Map<string, Entry>()
 
   const release = (sessionID: string): boolean => {
@@ -82,6 +87,11 @@ export function createSessionStore(): SessionStore {
       const previous = entries.get(state.sessionID)
       if (previous?.timer) clearTimeout(previous.timer)
       entries.set(state.sessionID, { state, startedAt: Date.now() })
+      try {
+        options.onRegister?.(state)
+      } catch (error) {
+        logError("session.register_hook_failed", { error: errorMessage(error) })
+      }
     },
     lookup: (sessionID) => entries.get(sessionID)?.state,
     release,