@ccmsg/cli 0.1.0

package/src/transport/ws.ts

@@ -0,0 +1,170 @@
+import { MAX_FRAME_BYTES } from "@ccmsg/protocol";
+import { BaseConn, type Conn, type ConnRegistry } from "./conn.ts";
+import { createDriver, type FrameHandler } from "./driver.ts";
+import { LineReader, WriteQueue } from "./framing.ts";
+import { type EntryPolicy, OPEN } from "./entry.ts";
+import type { Listener } from "./listener.ts";
+
+/** What the upgrade hands the socket: whether it was let in as a peer. */
+interface UpgradeData {
+  readonly mesh: boolean;
+}
+
+interface WsState {
+  conn: BaseConn;
+  reader: LineReader;
+  queue: WriteQueue<string>;
+}
+
+export interface WsOptions {
+  readonly hostname?: string;
+  /** 0 asks the kernel for a free port; the bound one is on `address`. */
+  readonly port: number;
+  readonly path?: string;
+  readonly conns: ConnRegistry;
+  readonly handle: FrameHandler;
+  readonly entry?: EntryPolicy;
+  /** `mesh` is set when the handshake was let in as a peer rather than on the
+   * entry token, so whoever holds the connection can keep it to the one
+   * exchange that can prove what it is. */
+  readonly onConn?: (conn: Conn, info: { readonly mesh: boolean }) => void;
+  /** An HTTP request that is not the upgrade, answered by whoever wants it.
+   *
+   * It shares this listener rather than opening a second one: a producer that
+   * posts to this instance reaches it at the address it already has, and the
+   * entry check of §3.1 runs before this is asked, so a route cannot be
+   * reached by anyone the WebSocket could not be. Answering `undefined` leaves
+   * the request to the upgrade, which refuses it. */
+  readonly route?: (request: Request) => Promise<Response | undefined>;
+}
+
+/** Accept the webui, and later mesh peers, over WebSocket.
+ *
+ * A WS message is a message, not a stream, but it carries the same
+ * newline-delimited framing as the unix socket: one line is one frame, whether
+ * a message holds one line or several. Backpressure differs from UDS — a send
+ * is either buffered whole by Bun or dropped whole — and the queue absorbs
+ * that difference here (§3.1). */
+export function serveWs(options: WsOptions): Listener {
+  const path = options.path ?? "/ws";
+  const entry = options.entry ?? OPEN;
+  // The per-connection state is made in `open`, where the socket to write to
+  // exists, so the upgrade carries nothing and the socket keeps no data of its
+  // own.
+  const states = new WeakMap<object, WsState>();
+  const server = Bun.serve<UpgradeData, never>({
+    hostname: options.hostname ?? "127.0.0.1",
+    port: options.port,
+    async fetch(request, srv) {
+      if (entry.allowRequest?.(request, srv.requestIP(request)?.address) === false) {
+        return new Response("Forbidden", { status: 403 });
+      }
+      const routed = await options.route?.(request);
+      if (routed !== undefined) return routed;
+      if (!entryPath(new URL(request.url).pathname, path)) {
+        return new Response("Not Found", { status: 404 });
+      }
+      // The handshake's own check, asked after the routes so a route carrying
+      // its own secret is not also asked for the entry token.
+      const decision = entry.allowUpgrade?.(request) ?? { ok: true as const };
+      if (!decision.ok) return new Response(decision.reason, { status: 401 });
+      const selected = decision.protocol;
+      if (
+        srv.upgrade(request, {
+          data: { mesh: decision.mesh === true },
+          ...(selected === undefined
+            ? {}
+            : { headers: { "sec-websocket-protocol": selected } satisfies Record<string, string> }),
+        })
+      ) {
+        return undefined;
+      }
+      return new Response("Expected a WebSocket upgrade", { status: 426 });
+    },
+    websocket: {
+      // The line limit is enforced by the framing both transports share, which
+      // answers `bad_request` and keeps the connection. This cap only bounds
+      // one message's memory, so it sits above the line limit — a message at
+      // or under it always reaches the framing and gets that answer.
+      maxPayloadLength: MAX_FRAME_BYTES + 64 * 1024,
+      open(ws) {
+        const queue = new WriteQueue<string>({
+          encode: (line) => line,
+          // 0 means the message was dropped; anything else means it was sent
+          // or is buffered by Bun and will be, so re-queuing it would send it
+          // twice.
+          write: (chunk) => (ws.send(chunk) === 0 ? chunk : undefined),
+        });
+        const conn = new BaseConn(options.conns.nextId(), {
+          send: (line) => {
+            queue.push(line);
+          },
+          close: (code, reason) => {
+            if (code === undefined) ws.close();
+            else ws.close(code, reason);
+          },
+        });
+        const driver = createDriver(conn, options.handle);
+        states.set(ws, { conn, queue, reader: new LineReader(driver) });
+        options.conns.add(conn);
+        const data = ws.data as UpgradeData | undefined;
+        options.onConn?.(conn, { mesh: data?.mesh === true });
+      },
+      message(ws, message) {
+        const state = states.get(ws);
+        if (state === undefined) return;
+        const bytes = typeof message === "string" ? new TextEncoder().encode(message) : message;
+        state.reader.push(bytes);
+        // A message need not end in a newline, and one message is one frame on
+        // this transport, so the last line is complete even without it.
+        state.reader.push(NEWLINE);
+      },
+      drain(ws) {
+        states.get(ws)?.queue.drain();
+      },
+      close(ws) {
+        const state = states.get(ws);
+        if (state === undefined) return;
+        options.conns.remove(state.conn);
+        state.conn.closed();
+      },
+    },
+  });
+
+  return {
+    kind: "ws",
+    address: `${server.hostname}:${server.port}`,
+    async close() {
+      // Bounded rather than simply awaited. Measured against Bun 1.3.13: once
+      // this server has closed a WebSocket itself — which the mesh does, to
+      // drop the loser of a glare, a link gone silent, or a peer speaking out
+      // of turn — `stop` never settles, while the address is in fact given up
+      // within a millisecond and can be bound again. Waiting on the promise
+      // would hang the stop order at its last step for a listener that is
+      // already down, so the wait is capped and the address is what is trusted.
+      await Promise.race([server.stop(true), Bun.sleep(STOP_DEADLINE_MS)]);
+    },
+  };
+}
+
+/** Whether a request's path is this listener's entry.
+ *
+ * Matched at the end rather than whole, so a proxy that puts the instance under
+ * a prefix of its own passes the request through untouched and an alias URL
+ * reaches the same door (DR-0001 §2.7). The boundary before it has to be a
+ * separator, or `/notws` would answer for `/ws`. The mesh's own routes are not
+ * matched this way: they stay under the configured endpoint, which is what
+ * keeps two instances on one origin from answering for each other's keys.
+ *
+ * The prefix is not read: which instance a proxy meant is settled by which
+ * address it forwarded to, and a person's connection names itself by
+ * authenticating rather than by the path it arrived on. */
+export function entryPath(pathname: string, path: string): boolean {
+  return pathname === path || pathname.endsWith(`/${path.replace(/^\//, "")}`);
+}
+
+/** How long the stop above waits before trusting the address over the promise.
+ * Two orders of magnitude above the millisecond the release was measured at. */
+const STOP_DEADLINE_MS = 250;
+
+const NEWLINE = new Uint8Array([0x0a]);

package/src/upstream/events.ts

@@ -0,0 +1,125 @@
+import type { LlmRequestInfo, Sid, Timestamp } from "@ccmsg/protocol";
+
+/** One request the gateway forwarded, in this contract's spelling, before the
+ * instance decides whether its series is the session's main one.
+ *
+ * `main` is a verdict about a session's several series, so it needs the other
+ * series to be made and cannot be read off one event (§3.5 renames, it does not
+ * derive). `instance` is stamped by whoever publishes, since an event says
+ * nothing about which instance received it. */
+export type LlmRequestObservation = Omit<LlmRequestInfo, "main" | "instance">;
+
+/** An answer the gateway saw close. Only the two fields the sessions domain
+ * reads: it says inference for that session has stopped running, and when. */
+export interface LlmResponseObservation {
+  readonly sid: Sid;
+  readonly at: Timestamp;
+}
+
+/** One item of a posted batch, as this instance reads it.
+ *
+ * `ignored` is a kind the gateway sends that nothing here reads — kept apart
+ * from `undefined`, which is an item that could not be understood at all. The
+ * difference is the whole value of the log line: a batch of ignorable items is
+ * the gateway working, a batch of unreadable ones is a schema that moved. */
+export type GatewayItem =
+  | { readonly kind: "request"; readonly info: LlmRequestObservation }
+  | { readonly kind: "response"; readonly info: LlmResponseObservation }
+  | { readonly kind: "ignored" };
+
+/** Kinds the gateway posts beside the two above: a keepalive it wants replayed
+ * into a session, and its keepalive strategy being held off for one. Neither
+ * is read here. They are named rather than reached as "not a request", so a
+ * kind the gateway grows still arrives as unreadable and shows up in the log. */
+const IGNORED = new Set(["cache_keepalive", "keepalive_paused"]);
+
+/** The fields whose name is the same on both sides, and whose value is already
+ * this contract's unit — a count of seconds, or an instant in Unix ms. */
+const SAME_NAME_NUMBERS = [
+  "cache_ttl_secs",
+  "cache_expires_at",
+  "cache_count",
+  "next_keepalive_at",
+  "cache_until_count",
+  "cache_breakeven_count",
+] as const;
+
+/** The instants the gateway names without the suffix this contract requires of
+ * every field that is a point in time. Renamed here, at the boundary, so
+ * nothing downstream sees the gateway's spelling (§3.5). */
+const RENAMED_INSTANTS = [
+  ["cache_since", "cache_since_at"],
+  ["cache_until", "cache_until_at"],
+  ["cache_breakeven_until", "cache_breakeven_until_at"],
+] as const;
+
+const SAME_NAME_STRINGS = ["keepalive", "ns", "model", "credential", "origin"] as const;
+
+/** Read one posted item.
+ *
+ * Nothing here throws: one item a batch could not be understood must not cost
+ * the items beside it, so an unusable one is `undefined` and the caller drops
+ * it. Every field is taken only when it is the type this contract states —
+ * which is also what keeps a value the gateway might one day send in another
+ * shape (an ISO instant, a string status) from travelling as itself. */
+export function parseGatewayItem(value: unknown): GatewayItem | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  const raw = value as Record<string, unknown>;
+  const kind = raw["type"];
+  if (typeof kind === "string" && IGNORED.has(kind)) return { kind: "ignored" };
+  // A client that named no session gives an event with no row to put it on.
+  // The gateway states the field as null rather than leaving it out, and this
+  // is the ordinary case of a call made by something other than a session — so
+  // it is passed over rather than counted as an event that could not be read.
+  if (raw["session_id"] === null) return { kind: "ignored" };
+  if (kind === "response") {
+    const info = responseOf(raw);
+    return info === undefined ? undefined : { kind: "response", info };
+  }
+  // The forwarding notice is the one kind that carries no mark, because it
+  // existed before the others did. So it is a request by position, and only
+  // when it names no kind at all: an item that names one and is not handled
+  // above must not be read as a request whose fields happen to line up.
+  if (kind !== undefined) return undefined;
+  const info = requestOf(raw);
+  return info === undefined ? undefined : { kind: "request", info };
+}
+
+function requestOf(raw: Record<string, unknown>): LlmRequestObservation | undefined {
+  const at = raw["ts"];
+  const sid = raw["session_id"];
+  if (!isInstant(at) || typeof sid !== "string" || sid === "") return undefined;
+  const info: Record<string, unknown> = { received_at: at, sid };
+  const prefix = raw["prefix"];
+  if (typeof prefix === "string" && prefix !== "") info["prefix"] = prefix;
+  for (const field of SAME_NAME_NUMBERS) {
+    const num = raw[field];
+    if (typeof num === "number" && Number.isFinite(num)) info[field] = num;
+  }
+  for (const [there, here] of RENAMED_INSTANTS) {
+    const num = raw[there];
+    if (isInstant(num)) info[here] = num;
+  }
+  for (const field of SAME_NAME_STRINGS) {
+    const text = raw[field];
+    if (typeof text === "string" && text !== "") info[field] = text;
+  }
+  const paused = raw["cache_paused"];
+  if (typeof paused === "boolean") info["cache_paused"] = paused;
+  const status = raw["status"];
+  if (typeof status === "number" && Number.isInteger(status)) info["status"] = status;
+  return info as unknown as LlmRequestObservation;
+}
+
+function responseOf(raw: Record<string, unknown>): LlmResponseObservation | undefined {
+  const at = raw["ts"];
+  const sid = raw["session_id"];
+  if (!isInstant(at) || typeof sid !== "string" || sid === "") return undefined;
+  return { sid, at };
+}
+
+/** A number that can be an instant on this wire. Rejecting a non-number is
+ * what stops an ISO string from reaching a `*_at` field. */
+function isInstant(value: unknown): value is Timestamp {
+  return typeof value === "number" && Number.isFinite(value);
+}

package/src/upstream/gateway.ts

@@ -0,0 +1,275 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import type {
+  Capability,
+  InstanceId,
+  LlmStatsReadArgs,
+  LlmStatsReadResult,
+  LlmUsageReadArgs,
+  LlmUsageReadResult,
+  Sid,
+  Timestamp,
+} from "@ccmsg/protocol";
+import type { HandlerInput } from "../dispatch/index.ts";
+import { ConfigError, type UpstreamConfig } from "../instance/config.ts";
+import type { Env } from "../instance/paths.ts";
+import type { TopicValue, UpstreamResource } from "../topics/index.ts";
+import { parseGatewayItem } from "./events.ts";
+import { LlmRequests } from "./requests.ts";
+import { readStats } from "./stats.ts";
+import { LlmStatus } from "./status.ts";
+import { readUsage } from "./usage.ts";
+import { handleWebhook, SOURCE_NAME, type WebhookSource } from "./webhook.ts";
+
+/** Where the gateway's own endpoints live under its address (DR-0006). */
+const STATUS_PATH = "/llm-gateway/status";
+const USAGE_PATH = "/llm-gateway/usage";
+const STATS_PATH = "/llm-gateway/stats";
+
+/** What the config says this instance can reach of the gateway, resolved.
+ *
+ * Both halves are independent: an instance can be posted to without being able
+ * to ask anything back, and the other way round. Each grants its own
+ * capability, so a client is told which of the two it has rather than
+ * discovering it by subscribing. */
+export interface GatewaySetup {
+  /** Present when a webhook source is configured, with the secret it must
+   * present already read. */
+  readonly source?: { readonly name: string; readonly token: string };
+  /** Present when the gateway's address is configured. The three are one
+   * decision — the address — and are resolved together so a client is told
+   * about all three at once rather than discovering each by asking. */
+  readonly statusUrl?: string;
+  readonly usageUrl?: string;
+  readonly statsUrl?: string;
+}
+
+/** Read the upstream section (§8.2).
+ *
+ * A setting that is there and cannot be honoured ends the start rather than
+ * leaving the feature it asked for silently off (DV-Q9): an operator who named
+ * a webhook source wants the route, and an instance that came up without it
+ * looks identical to one nobody is posting to. A section that is absent is not
+ * broken — it states that this instance has no gateway, which costs the rows
+ * one attribute and nothing else (§5.2). */
+export function gatewaySetup(config: UpstreamConfig, file: string, env: Env): GatewaySetup {
+  const name = config.gateway_webhook_source;
+  const url = config.gateway_url;
+  return {
+    ...(name === undefined
+      ? {}
+      : { source: { name: sourceName(file, name), token: token(file, config, env, name) } }),
+    ...(url === undefined
+      ? {}
+      : {
+          statusUrl: endpoint(file, url, STATUS_PATH),
+          usageUrl: endpoint(file, url, USAGE_PATH),
+          statsUrl: endpoint(file, url, STATS_PATH),
+        }),
+  };
+}
+
+/** The capabilities the setup grants. `llm_events` says request activity
+ * arrives to be pushed; the other three say the gateway can be asked for its
+ * report, its quota and its spend. */
+export function gatewayCapabilities(setup: GatewaySetup): Capability[] {
+  return [
+    ...(setup.source === undefined ? [] : (["llm_events"] as const)),
+    ...(setup.statusUrl === undefined ? [] : (["llm_status"] as const)),
+    ...(setup.usageUrl === undefined ? [] : (["llm_usage"] as const)),
+    ...(setup.statsUrl === undefined ? [] : (["llm_stats"] as const)),
+  ];
+}
+
+/** The two ops that ask the gateway a question and answer with what it said.
+ *
+ * They are handlers rather than resources: neither has a current value to hold
+ * or a topic to push on, so each read is one question asked because a person
+ * asked it. */
+export function gatewayHandlers(setup: GatewaySetup, fetcher?: typeof fetch) {
+  const call = fetcher === undefined ? {} : { fetch: fetcher };
+  const usageUrl = setup.usageUrl;
+  const statsUrl = setup.statsUrl;
+  return {
+    ...(usageUrl === undefined
+      ? {}
+      : {
+          llm_usage_read: (input: HandlerInput): Promise<LlmUsageReadResult> =>
+            readUsage({ url: usageUrl, ...call }, input.args as unknown as LlmUsageReadArgs),
+        }),
+    ...(statsUrl === undefined
+      ? {}
+      : {
+          llm_stats_read: (input: HandlerInput): Promise<LlmStatsReadResult> =>
+            readStats({ url: statsUrl, ...call }, input.args as unknown as LlmStatsReadArgs),
+        }),
+  };
+}
+
+export interface GatewayDeps {
+  readonly self: InstanceId;
+  readonly setup: GatewaySetup;
+  readonly publish: (topic: string, data: unknown) => void;
+  /** The gateway saw something happen for a session, which is an input of the
+   * sessions domain (§5.1) rather than of either topic. */
+  readonly onActivity?: () => void;
+  readonly log?: (msg: string, fields?: Record<string, unknown>) => void;
+  /** Replaces the outward read in tests. */
+  readonly fetch?: typeof fetch;
+  readonly settleMs?: number;
+}
+
+/** What this instance takes from the llm-gateway.
+ *
+ * One direction each. The gateway posts what it saw the moment it saw it,
+ * because it runs as more than one process and a subscription would only ever
+ * have reached whichever one it connected to; this instance asks for the
+ * service report, because that is a document with a current value rather than
+ * a stream of occurrences. Both arrive as events and neither is polled (M3):
+ * the report is re-read when a posted event says an upstream refused, which is
+ * this instance being told the one thing that changes it. */
+export class Gateway {
+  readonly requests: LlmRequests;
+  readonly status: LlmStatus | undefined;
+  readonly #source: WebhookSource | undefined;
+
+  constructor(private readonly deps: GatewayDeps) {
+    this.requests = new LlmRequests({
+      self: deps.self,
+      publish: deps.publish,
+      ...(deps.onActivity === undefined ? {} : { onActivity: deps.onActivity }),
+    });
+    this.status =
+      deps.setup.statusUrl === undefined
+        ? undefined
+        : new LlmStatus({
+            self: deps.self,
+            url: deps.setup.statusUrl,
+            publish: deps.publish,
+            ...(deps.log === undefined ? {} : { log: deps.log }),
+            ...(deps.fetch === undefined ? {} : { fetch: deps.fetch }),
+            ...(deps.settleMs === undefined ? {} : { settleMs: deps.settleMs }),
+          });
+    this.#source =
+      deps.setup.source === undefined
+        ? undefined
+        : {
+            name: deps.setup.source.name,
+            token: deps.setup.source.token,
+            handle: (items) => this.take(items),
+          };
+  }
+
+  /** The resource behind `llm_status`. A stand-in that states nothing when the
+   * gateway's address is not configured — the topic's capability is absent
+   * then, so nothing reaches it, and the attachment stays unconditional. */
+  get statusResource(): UpstreamResource {
+    return this.status ?? SILENT;
+  }
+
+  /** When the gateway last saw inference for a session (§5.1). */
+  activeAt(sid: Sid, now?: Timestamp): Timestamp | undefined {
+    return this.requests.activeAt(sid, now);
+  }
+
+  /** One HTTP request that reached this instance's entry, answered if it is
+   * the webhook and left alone if it is not. */
+  route(request: Request): Promise<Response | undefined> {
+    return handleWebhook(request, this.#source, this.deps.log);
+  }
+
+  /** Stop what is pending. Called from the stop order (§8.5). */
+  close(): void {
+    this.status?.stop();
+  }
+
+  /** One posted batch. Every item is read on its own: a kind this instance
+   * does not use is passed over, and one it cannot read at all is counted, so
+   * a schema that moved shows up as a number instead of as silence. */
+  private take(items: readonly unknown[]): void {
+    let unreadable = 0;
+    for (const value of items) {
+      const item = parseGatewayItem(value);
+      if (item === undefined) {
+        unreadable += 1;
+        continue;
+      }
+      if (item.kind === "request") {
+        this.requests.record(item.info);
+        this.status?.noteRequestStatus(item.info.status);
+      } else if (item.kind === "response") {
+        this.requests.note(item.info.sid, item.info.at);
+      }
+    }
+    if (unreadable > 0) {
+      this.deps.log?.("dropped items a gateway delivery could not be read as", { unreadable });
+    }
+  }
+}
+
+/** A resource with nothing behind it: subscribing to its topic starts nothing
+ * and states nothing. */
+const SILENT: UpstreamResource = {
+  start(): void {},
+  stop(): void {},
+  snapshot(): readonly TopicValue[] {
+    return [];
+  },
+};
+
+function sourceName(file: string, name: string): string {
+  if (!SOURCE_NAME.test(name)) {
+    throw new ConfigError(
+      file,
+      "upstream.gateway_webhook_source must be lowercase letters, digits and dashes",
+    );
+  }
+  return name;
+}
+
+/** One of the gateway's endpoints under the configured address. */
+function endpoint(file: string, url: string, path: string): string {
+  let base: URL;
+  try {
+    base = new URL(url);
+  } catch {
+    throw new ConfigError(file, `upstream.gateway_url must be a URL, got ${url}`);
+  }
+  if (base.protocol !== "http:" && base.protocol !== "https:") {
+    throw new ConfigError(file, "upstream.gateway_url must be an http:// or https:// address");
+  }
+  return `${base.origin}${base.pathname.replace(/\/+$/, "")}${path}`;
+}
+
+/** The secret the gateway presents.
+ *
+ * It is the gateway that writes the file and this instance that reads it, so
+ * the default is the path the gateway defaults to (DR-0012) rather than one of
+ * this instance's own — a path per config home would have to be configured on
+ * both sides to mean the same thing. */
+function token(file: string, config: UpstreamConfig, env: Env, source: string): string {
+  const path = config.gateway_webhook_token_file ?? defaultTokenFile(env, source);
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (cause) {
+    throw new ConfigError(
+      file,
+      `upstream.gateway_webhook_source is set but its token file ${path} could not be read (${String(cause)})`,
+    );
+  }
+  const token = raw.trim();
+  if (token === "") throw new ConfigError(file, `the webhook token file ${path} is empty`);
+  return token;
+}
+
+export function defaultTokenFile(env: Env, source: string): string {
+  const xdg = env["XDG_DATA_HOME"];
+  const home = env["HOME"];
+  const base =
+    xdg !== undefined && isAbsolute(xdg)
+      ? xdg
+      : join(home !== undefined && isAbsolute(home) ? home : homedir(), ".local", "share");
+  return join(base, "ccmsg", `webhook-${source}.token`);
+}

package/src/upstream/index.ts

@@ -0,0 +1,8 @@
+export * from "./events.ts";
+export * from "./gateway.ts";
+export * from "./json.ts";
+export * from "./requests.ts";
+export * from "./stats.ts";
+export * from "./status.ts";
+export * from "./usage.ts";
+export * from "./webhook.ts";

package/src/upstream/json.ts

@@ -0,0 +1,81 @@
+import type { Timestamp } from "@ccmsg/protocol";
+
+/** What every read of an upstream document is built from (§3.5).
+ *
+ * The gateway's three documents are read the same way — a field is taken only
+ * at the type this contract states for it, and anything else is absent — so the
+ * readers live here once rather than once per document. */
+
+export interface FetchOptions {
+  /** How long the read is given before it is one that is not coming. */
+  readonly timeoutMs: number;
+  /** Cap on the document, since the whole of it is held to be parsed. */
+  readonly maxBytes: number;
+  /** Replaces the outward read in tests. */
+  readonly fetch?: typeof fetch;
+}
+
+/** One JSON document from the gateway, or a throw saying why not. */
+export async function fetchJson(url: string, options: FetchOptions): Promise<unknown> {
+  const call = options.fetch ?? fetch;
+  const answer = await call(url, {
+    signal: AbortSignal.timeout(options.timeoutMs),
+    headers: { accept: "application/json" },
+  });
+  if (!answer.ok) throw new Error(`the gateway answered ${answer.status}`);
+  return JSON.parse(await bounded(answer, options.maxBytes)) as unknown;
+}
+
+async function bounded(answer: Response, maxBytes: number): Promise<string> {
+  const body = answer.body;
+  if (body === null) return "";
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let size = 0;
+  let text = "";
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done === true) break;
+      size += value.byteLength;
+      if (size > maxBytes) throw new Error(`the document is over ${maxBytes} bytes`);
+      text += decoder.decode(value, { stream: true });
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return text + decoder.decode();
+}
+
+export function objectOf(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+}
+
+export function oneOf<T extends string>(allowed: readonly T[], value: unknown, fallback: T): T {
+  return typeof value === "string" && (allowed as readonly string[]).includes(value)
+    ? (value as T)
+    : fallback;
+}
+
+export function optionalText(name: string, value: unknown): Record<string, string> {
+  return typeof value === "string" ? { [name]: value } : {};
+}
+
+export function optionalInteger(name: string, value: unknown): Record<string, number> {
+  return typeof value === "number" && Number.isInteger(value) ? { [name]: value } : {};
+}
+
+export function optionalNumber(name: string, value: unknown): Record<string, number> {
+  return typeof value === "number" && Number.isFinite(value) ? { [name]: value } : {};
+}
+
+export function optionalFlag(name: string, value: unknown): Record<string, boolean> {
+  return typeof value === "boolean" ? { [name]: value } : {};
+}
+
+/** An instant, taken only as a number. Rejecting a string is what stops an ISO
+ * time from travelling on a field this contract says is Unix ms. */
+export function optionalInstant(name: string, value: unknown): Record<string, Timestamp> {
+  return typeof value === "number" && Number.isFinite(value) ? { [name]: value } : {};
+}