opencode-plugboard 0.16.0 → 0.17.0

package/src/rpc.ts

@@ -0,0 +1,65 @@
+/**
+ * The usage RPC, `opencode-plugboard.usage` (package entry `./rpc`): the report `GET /v1/usage` serves,
+ * for OpenCode's own clients. A TUI plugin reads it with `client.rpc(UsageRpc).get({ ... })` over the
+ * server's password-authenticated API, so the method sees every app.
+ *
+ * The server plugin registers the handler in every accepted generation (`index.ts`). Registration is
+ * synchronous and touches no storage; the handler reads the same store as the route, from request
+ * time only. Input and output are JSON Schema (the host's `Rpc.define`): the input is the query
+ * (`from`, `to`, `app`, all optional), the output is the `UsageReport` as documented in `src/usage.ts`.
+ * A bad query is the declared error `invalid_query` with `{ param }`, naming the parameter.
+ */
+
+import { Rpc } from "@opencode/plugin/rpc"
+import type { RpcHandlers } from "@opencode/plugin/effect/rpc"
+import { Effect } from "effect"
+import { isPlugError, type PlugError } from "./contract.js"
+import type { UsageQuery, UsageReport } from "./usage.js"
+
+export const UsageRpc = Rpc.define({
+  id: "opencode-plugboard.usage",
+  methods: {
+    get: {
+      input: {
+        type: "object",
+        properties: {
+          from: { type: "string", description: "First UTC day, YYYY-MM-DD. Default: 29 days before `to`." },
+          to: { type: "string", description: "Last UTC day, YYYY-MM-DD. Default: today." },
+          app: { type: "string", description: "One app name. Default: every app." },
+        },
+        additionalProperties: false,
+      },
+      output: {
+        type: "object",
+        description: "A UsageReport (see src/usage.ts).",
+        additionalProperties: true,
+      },
+      errors: {
+        invalid_query: {
+          type: "object",
+          properties: { param: { type: "string", description: "The query parameter that is wrong: from, to or app." } },
+          required: ["param"],
+          additionalProperties: false,
+        },
+      },
+    },
+  },
+  events: {},
+})
+
+/** The query fields of an RPC input. The input was validated against JSON Schema by the host; anything else is ignored. */
+function queryOf(input: unknown): UsageQuery {
+  const record: Record<string, unknown> = typeof input === "object" && input !== null ? (input as Record<string, unknown>) : {}
+  const text = (value: unknown) => (typeof value === "string" ? value : undefined)
+  return { from: text(record.from), to: text(record.to), app: text(record.app) }
+}
+
+/** The handlers for `UsageRpc`, reading the given usage query (the generation's recorder). */
+export function usageHandlers(usage: { query(input: UsageQuery): Promise<UsageReport | PlugError> }): RpcHandlers<typeof UsageRpc> {
+  return {
+    get: (input, context) =>
+      Effect.promise(() => usage.query(queryOf(input))).pipe(
+        Effect.flatMap((result) => (isPlugError(result) ? Effect.fail(context.error("invalid_query", result.message, { param: result.param ?? "query" })) : Effect.succeed(result))),
+      ),
+  }
+}

package/src/runtime.ts

@@ -25,8 +25,10 @@
  *  - the metrics registry (src/metrics.ts) and the runtime start time, so counters and uptime
  *     outlive any one generation. `processMetrics` / `processStatus` read them for `/metrics`,
  *     `/v1/status` and the discovery pages;
- *   - the request limiter's queues and rate windows (src/limits.ts), so a cap holds across
- *     generations. `processLimits` reads them.
+  *   - the request limiter's queues and rate windows (src/limits.ts), so a cap holds across
+ *     generations. `processLimits` reads them;
+  *   - the usage store's live days (src/usage.ts), so the in-memory aggregates survive a generation.
+ *     `processUsage` reads them.
  *
  * 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
@@ -60,6 +62,7 @@ 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"
+import { createUsageState, type UsageState } from "./usage.js"
 
 export type Handler = (request: IncomingMessage, response: ServerResponse) => void
 
@@ -112,8 +115,8 @@ const BACKEND_POLL_MS = 25
 const BIND_RETRY_MS = 15_000
 const BIND_REMINDER_MS = 5 * 60_000
 
-/** 10: the response cache store (`src/cache.ts`) lives here too. 9: the request limiter state (`src/limits.ts`) lives here, so the concurrency caps and rate windows survive a generation. 8: `Metrics.render` is async and the registry is @prometheus-io/client's. 7: the options fingerprint comes from safe-stable-stringify, so it must not be compared with an older one. 6: the listener retries a failed bind (new fields on `Listener`). 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
-const VERSION = 10
+/** 12: the live key set (`keys`, `Runtime.keys`) that a stricter newer generation replaces at once (#90). 11: the usage store's live days (`src/usage.ts`) live here too. 10: the response cache store (`src/cache.ts`) lives here too. 9: the request limiter state (`src/limits.ts`) lives here, so the concurrency caps and rate windows survive a generation. 8: `Metrics.render` is async and the registry is @prometheus-io/client's. 7: the options fingerprint comes from safe-stable-stringify, so it must not be compared with an older one. 6: the listener retries a failed bind (new fields on `Listener`). 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
+const VERSION = 12
 const KEY = Symbol.for("opencode-plugboard.runtime")
 
 interface Listener {
@@ -167,8 +170,16 @@ interface Runtime {
   readonly limits: LimitState
   /** When this runtime was created, epoch ms. */
   readonly startedAt: number
+  /**
+   * The app keys authentication checks (app name -> key), once a generation has registered. Replaced
+   * when a newer generation only revokes or rotates keys (`registerGeneration`, #90). Absent means
+   * the handler's own options are used.
+   */
+  keys?: Readonly<Record<string, string>>
   /** The response cache store (src/cache.ts) and the fingerprint of the config and `apps` policy it was built for. */
   cache?: { readonly fingerprint: string; readonly store: CacheStore }
+  /** The usage store's live days and retention clock (src/usage.ts). */
+  readonly usage: UsageState
   listener?: Listener
   /** Present while a fiber is subscribed to the server event bus. */
   pump?: Pump
@@ -181,6 +192,7 @@ const detachedSessions = createSessionStore()
 const detachedMetrics = createMetrics()
 const detachedStartedAt = Date.now()
 const detachedLimits = createLimitState()
+const detachedUsage = createUsageState()
 let foreignVersionLogged = false
 
 /** The process runtime, created on first use; undefined when a different version already owns the process. */
@@ -197,6 +209,7 @@ function runtime(): Runtime | undefined {
       sweep: { nextAt: 0, running: false },
       metrics: createMetrics(),
       limits: createLimitState(),
+      usage: createUsageState(),
       startedAt: Date.now(),
     }
     slot[KEY] = created
@@ -275,6 +288,18 @@ export const processMetrics = (): Metrics => runtime()?.metrics ?? detachedMetri
 /** The request limiter's state shared by every generation in the process (detached under a foreign-version runtime). */
 export const processLimits = (): LimitState => runtime()?.limits ?? detachedLimits
 
+/** The usage store's live days shared by every generation in the process (detached under a foreign-version runtime). */
+export const processUsage = (): UsageState => runtime()?.usage ?? detachedUsage
+
+/**
+ * The options authentication reads: `keys` is the live key set, not the serving generation's own
+ * (a generation that is still live after a key revocation keeps its old keys otherwise, #90).
+ */
+export function liveOptions(options: PlugboardOptions): PlugboardOptions {
+  const keys = runtime()?.keys
+  return keys === undefined || keys === options.keys ? options : { ...options, keys }
+}
+
 /**
  * Wraps `caller` with the response cache when option `cache` is set (a no-op without it). The store
  * lives on the runtime, so it survives plugin generations. It is replaced when the cache option or
@@ -423,6 +448,12 @@ function closeListener(rt: Runtime, listener: Listener): void {
  * 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.
+ *
+ * The key set (`keys`) has one more rule (#90). While generations are live, a newer generation whose
+ * keys only revoke or rotate those of apps the listener already has (no app added, at least one
+ * left) replaces `Runtime.keys` at once, so a Location still on an older generation stops accepting
+ * a removed key. Any other key change is rejected like any other option difference. The listener's
+ * `fingerprint` covers the options without `keys`.
  */
 export function registerGeneration(input: GenerationInput): Registration {
   const rt = runtime()
@@ -444,7 +475,8 @@ export function registerGeneration(input: GenerationInput): Registration {
       },
     }
   }
-  const fingerprint = canonicalJson(input.options)
+  const fingerprint = canonicalJson({ ...(input.options as Record<string, unknown>), keys: undefined })
+  const keys = (input.options as { readonly keys?: Readonly<Record<string, string>> } | null)?.keys ?? {}
   const listener = (rt.listener ??= startListener(rt, listen, fingerprint))
   if (listener.listen.host !== listen.host || listener.listen.port !== listen.port) {
     if (!listener.mismatchLogged) {
@@ -457,16 +489,28 @@ export function registerGeneration(input: GenerationInput): Registration {
     }
     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()
+  const rejectOptions = (): Registration => {
+    if (!listener.mismatchLogged) {
+      listener.mismatchLogged = true
+      logError("listener.options_mismatch", { action: "this Location is rejected; global config is authoritative" })
     }
+    return reject()
+  }
+  if (listener.fingerprint !== fingerprint) {
+    if (rt.generations.length > 0) return rejectOptions()
     listener.fingerprint = fingerprint
     listener.mismatchLogged = false
+    rt.keys = keys
+  } else if (canonicalJson(keys) !== canonicalJson(rt.keys ?? {})) {
+    const live = rt.keys ?? {}
+    if (rt.generations.length === 0) rt.keys = keys
+    else if (revokesOrRotatesOnly(live, keys)) {
+      log("listener.keys_updated", {
+        removed: Object.keys(live).filter((app) => !Object.hasOwn(keys, app)).length,
+        rotated: Object.keys(keys).filter((app) => Object.hasOwn(live, app) && live[app] !== keys[app]).length,
+      })
+      rt.keys = keys
+    } else return rejectOptions()
   }
   if (listener.graceTimer) clearTimeout(listener.graceTimer)
   listener.graceTimer = undefined
@@ -510,6 +554,12 @@ export function registerGeneration(input: GenerationInput): Registration {
   }
 }
 
+/** #90: `next` names no app that `live` lacks, and names at least one app: it only removes or changes keys. */
+function revokesOrRotatesOnly(live: Readonly<Record<string, string>>, next: Readonly<Record<string, string>>): boolean {
+  const apps = Object.keys(next)
+  return apps.length > 0 && apps.every((app) => Object.hasOwn(live, app))
+}
+
 /**
  * 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

package/src/session/host.ts

@@ -129,6 +129,30 @@ export function createHistoryPort(ctx: HostContext): HistoryPort {
   }
 }
 
+/**
+ * `ctx.storage` as a Promise port for string values (the usage store keeps one JSON string per app
+ * and day). Same host table and namespace as `HistoryPort`; the keys never overlap (`usage/` vs `history/`).
+ */
+export interface StoragePort {
+  get(key: string): Promise<string | undefined>
+  put(key: string, value: string): Promise<void>
+  drop(key: string): Promise<void>
+  scan(input: { readonly prefix: string; readonly after?: string; readonly limit: number }): Promise<{ readonly keys: ReadonlyArray<string>; readonly next?: string }>
+}
+
+export function createStoragePort(ctx: HostContext): StoragePort {
+  return {
+    get: (key) => Effect.runPromise(ctx.storage.get(key)).then((value) => (typeof value === "string" ? value : undefined)),
+    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 }),
+      })),
+  }
+}
+
 const record = (value: unknown): Record<string, unknown> | undefined =>
   typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined