@ccmsg/cli 0.1.0

package/src/upstream/usage.ts

@@ -0,0 +1,208 @@
+import type {
+  LlmUsageAuth,
+  LlmUsageCredential,
+  LlmUsageLimit,
+  LlmUsageOverage,
+  LlmUsageReadArgs,
+  LlmUsageReadResult,
+  LlmUsageSnapshot,
+  LlmUsageWindow,
+} from "@ccmsg/protocol";
+import { OpError } from "../dispatch/index.ts";
+import {
+  fetchJson,
+  objectOf,
+  optionalFlag,
+  optionalInstant,
+  optionalInteger,
+  optionalText,
+} from "./json.ts";
+
+/** A handful of credentials. Past this the address is pointing at something
+ * else entirely, and the whole document is held to be parsed. */
+const MAX_BYTES = 1024 * 1024;
+
+/** The gateway answers a cached read from a snapshot it keeps. */
+const TIMEOUT_MS = 10_000;
+
+/** A probe waits on every provider in turn rather than on the gateway's own
+ * cache, so it is legitimately slower — wide enough that one slow provider does
+ * not lose the whole answer. */
+const PROBE_TIMEOUT_MS = 60_000;
+
+export interface UsageDeps {
+  /** Where the gateway answers, already joined to its usage path. */
+  readonly url: string;
+  readonly fetch?: typeof fetch;
+}
+
+/** Ask the gateway what quota each credential has left.
+ *
+ * A failed read is the op's failure, unlike the status report's: there is no
+ * last-good reading held here to fall back on, and answering with an empty list
+ * of credentials would read as "this host has none". */
+export async function readUsage(
+  deps: UsageDeps,
+  args: LlmUsageReadArgs,
+): Promise<LlmUsageReadResult> {
+  const refresh = args.refresh === true;
+  const url = refresh ? withQuery(deps.url, "refresh", "true") : deps.url;
+  let document: unknown;
+  try {
+    document = await fetchJson(url, {
+      timeoutMs: refresh ? PROBE_TIMEOUT_MS : TIMEOUT_MS,
+      maxBytes: MAX_BYTES,
+      ...(deps.fetch === undefined ? {} : { fetch: deps.fetch }),
+    });
+  } catch (cause) {
+    throw new OpError("internal_error", `the gateway's usage could not be read: ${String(cause)}`);
+  }
+  const usage = usageOf(document, deps.url);
+  if (usage === undefined) {
+    throw new OpError("internal_error", "the gateway's usage could not be understood");
+  }
+  return usage;
+}
+
+/** Read the gateway's document as this contract's answer (§3.5).
+ *
+ * The names that differ are the two the gateway spells its own way — `reset`
+ * and `window_seconds` — and both are already Unix ms and seconds, so the
+ * conversion is the name alone. Everything else is taken at the type this
+ * contract states and is otherwise absent: an open vocabulary travels as sent,
+ * because a verdict this daemon does not recognise has to reach the screen as
+ * itself. */
+export function usageOf(value: unknown, base?: string): LlmUsageReadResult | undefined {
+  const raw = objectOf(value);
+  if (raw === undefined || !Array.isArray(raw["credentials"])) return undefined;
+  return {
+    ...optionalInstant("generated_at", raw["generated_at"]),
+    credentials: raw["credentials"].flatMap((entry) => credentialOf(entry, base) ?? []),
+  };
+}
+
+/** A credential with no name cannot be told from its neighbours, so it is
+ * dropped; every other field degrades to absent and the row still renders. */
+function credentialOf(value: unknown, base?: string): LlmUsageCredential | undefined {
+  const raw = objectOf(value);
+  const name = raw?.["name"];
+  if (raw === undefined || typeof name !== "string") return undefined;
+  const auth = authOf(raw["auth"], base);
+  const snapshot = snapshotOf(raw["snapshot"]);
+  const limits = Array.isArray(raw["limits"])
+    ? raw["limits"].flatMap((limit) => limitOf(limit) ?? [])
+    : [];
+  return {
+    name,
+    ...optionalText("type", raw["type"]),
+    support: typeof raw["support"] === "string" ? raw["support"] : "unknown",
+    ...(auth === undefined ? {} : { auth }),
+    ...(snapshot === undefined ? {} : { snapshot }),
+    ...(limits.length === 0 ? {} : { limits }),
+    ...optionalText("probe_error", raw["probe_error"]),
+  };
+}
+
+/** Only `status` is required: a reading with no word for what it is would have
+ * to be shown as a state this daemon invented. */
+function authOf(value: unknown, base?: string): LlmUsageAuth | undefined {
+  const raw = objectOf(value);
+  const status = raw?.["status"];
+  if (raw === undefined || typeof status !== "string") return undefined;
+  const login = loginUrl(raw["login_path"], base);
+  return {
+    status,
+    ...optionalText("reason", raw["reason"]),
+    ...optionalInstant("observed_at", raw["observed_at"]),
+    ...(login === undefined ? {} : { login_url: login }),
+  };
+}
+
+/** The gateway states a path rather than an address, because it does not know
+ * the one it is published under. It is resolved against the endpoint this
+ * instance fetched from, and only that origin is kept.
+ *
+ * Design rationale: the link is rendered in a person's browser, so a gateway —
+ * or something answering in its place — that named another host would be
+ * planting a "log in here" button pointing off it. Dropping such a link costs a
+ * button; following one could cost a credential. */
+function loginUrl(path: unknown, base?: string): string | undefined {
+  if (typeof path !== "string" || base === undefined) return undefined;
+  try {
+    const origin = new URL(base);
+    const resolved = new URL(path, origin);
+    return resolved.origin === origin.origin ? resolved.toString() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function overageOf(value: unknown): LlmUsageOverage | undefined {
+  const raw = objectOf(value);
+  const status = raw?.["status"];
+  if (raw === undefined || typeof status !== "string") return undefined;
+  return { status, ...optionalText("disabled_reason", raw["disabled_reason"]) };
+}
+
+/** The windows are the snapshot's own keys, beside the two fields that are not
+ * windows. Read by shape rather than against a list of names, so a provider
+ * that starts reporting a third window needs no change here — and an unrelated
+ * key is dropped instead of drawn as an empty bar. */
+function snapshotOf(value: unknown): LlmUsageSnapshot | undefined {
+  const raw = objectOf(value);
+  if (raw === undefined) return undefined;
+  const windows: Record<string, LlmUsageWindow> = {};
+  for (const [name, entry] of Object.entries(raw)) {
+    if (name === "observed_at" || name === "overage") continue;
+    const window = windowOf(entry);
+    if (window !== undefined) windows[name] = window;
+  }
+  const overage = overageOf(raw["overage"]);
+  return {
+    ...optionalInstant("observed_at", raw["observed_at"]),
+    ...(overage === undefined ? {} : { overage }),
+    windows,
+  };
+}
+
+function windowOf(value: unknown): LlmUsageWindow | undefined {
+  const raw = objectOf(value);
+  const utilization = raw?.["utilization"];
+  const status = raw?.["status"];
+  if (raw === undefined || typeof utilization !== "number" || typeof status !== "string") {
+    return undefined;
+  }
+  return {
+    utilization,
+    status,
+    ...optionalInstant("reset_at", raw["reset"]),
+    ...optionalInteger("window_secs", raw["window_seconds"]),
+    ...optionalFlag("expired", raw["expired"]),
+  };
+}
+
+/** Recognised by shape like a window: an entry counts as a limit when it names
+ * what it limits and states a figure for it. */
+function limitOf(value: unknown): LlmUsageLimit | undefined {
+  const raw = objectOf(value);
+  const kind = raw?.["kind"];
+  const percent = raw?.["percent"];
+  if (raw === undefined || typeof kind !== "string" || typeof percent !== "number") {
+    return undefined;
+  }
+  return {
+    kind,
+    percent,
+    severity: typeof raw["severity"] === "string" ? raw["severity"] : "unknown",
+    ...optionalInstant("resets_at", raw["resets_at"]),
+    ...optionalText("model", raw["model"]),
+    ...optionalFlag("is_active", raw["is_active"]),
+    ...optionalInteger("window_secs", raw["window_seconds"]),
+  };
+}
+
+export function withQuery(base: string, name: string, value: string): string {
+  const url = new URL(base);
+  url.searchParams.set(name, value);
+  return url.toString();
+}

package/src/upstream/webhook.ts

@@ -0,0 +1,141 @@
+import { timingSafeEqual } from "node:crypto";
+
+/** Cap on one posted body. The gateway splits its own deliveries at a
+ * megabyte, so a body past this is not one of its batches. */
+export const MAX_BODY_BYTES = 1024 * 1024;
+
+/** What a path segment naming a producer may be. Narrow on purpose: the
+ * segment picks a configured source, so it must not be able to express
+ * traversal or a case that matches two ways. */
+export const SOURCE_NAME = /^[a-z0-9-]{1,64}$/;
+
+/** The producer a path names, matched at the end of the path.
+ *
+ * A gateway posts to whatever URL its operator gave it, which may sit under a
+ * proxy's prefix, so the segment before `/webhook/` is not read (DR-0001 §2.7).
+ * Which instance is meant was settled by the address the proxy forwarded to;
+ * what still has to be right is the source name and the token it presents.
+ *
+ * The last `/webhook/` wins, so a source cannot be smuggled in through a
+ * prefix that contains the marker itself. */
+export function sourceOfPath(pathname: string): string | undefined {
+  const marker = "/webhook/";
+  const at = pathname.lastIndexOf(marker);
+  return at === -1 ? undefined : pathname.slice(at + marker.length);
+}
+
+export interface WebhookSource {
+  /** The path segment this producer posts to, after `/webhook/`. */
+  readonly name: string;
+  /** The secret it presents as `Authorization: Bearer`. The gateway reads the
+   * same value out of its own token file (DR-0012); this is the only thing
+   * standing between the route and anyone the entry check let through. */
+  readonly token: string;
+  /** Take one posted batch. The items are raw: reading them is the source's
+   * own business, and one it cannot read must not fail the delivery. */
+  handle(items: readonly unknown[]): void;
+}
+
+/** Serve `POST /webhook/<source>`, or answer nothing when the request is for
+ * something else — the caller then goes on to its other routes.
+ *
+ * Fire and forget by design. The gateway sends one way, does not retry and
+ * does not reorder, so an item this instance cannot use is worth a log line
+ * and nothing more: answering 4xx over one bad item would only teach a
+ * producer to repeat it. The body being unreadable as a whole is the one
+ * failure its sender can act on, so it is the one it hears about. */
+export async function handleWebhook(
+  request: Request,
+  source: WebhookSource | undefined,
+  log?: (msg: string, fields?: Record<string, unknown>) => void,
+): Promise<Response | undefined> {
+  const name = sourceOfPath(new URL(request.url).pathname);
+  if (name === undefined) return undefined;
+  if (request.method !== "POST") return new Response("Method Not Allowed", { status: 405 });
+  // An unconfigured source does not exist as far as a caller can tell, which
+  // is also what keeps the answer from naming what could be turned on.
+  if (source === undefined || !SOURCE_NAME.test(name) || name !== source.name) {
+    return new Response("Not Found", { status: 404 });
+  }
+  if (!authorized(request.headers.get("authorization"), source.token)) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  const declared = Number(request.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) return tooLarge();
+
+  let text: string;
+  try {
+    text = await bounded(request);
+  } catch (cause) {
+    if (cause instanceof TooLarge) return tooLarge();
+    return new Response(`the body could not be read: ${String(cause)}`, { status: 400 });
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (cause) {
+    log?.("a webhook delivery was not JSON", { source: source.name, error: String(cause) });
+    return new Response("the body is not JSON", { status: 400 });
+  }
+  try {
+    // The gateway always posts an array; one bare item is the same thing to
+    // whoever reads them.
+    source.handle(Array.isArray(parsed) ? parsed : [parsed]);
+  } catch (cause) {
+    // A reader that throws is this instance's own fault, not the sender's: it
+    // is logged and the delivery is still accepted.
+    log?.("a webhook reader failed", { source: source.name, error: String(cause) });
+  }
+  return new Response(null, { status: 204 });
+}
+
+/** Whether the request presents exactly this source's token.
+ *
+ * Compared in constant time. The route is reachable only by whoever the entry
+ * check of §3.1 already let through, but a comparison that leaks its prefix
+ * through timing is the kind of thing that quietly stops being enough once an
+ * instance is bound past loopback. */
+function authorized(header: string | null, token: string): boolean {
+  if (header === null) return false;
+  const prefix = "Bearer ";
+  if (!header.startsWith(prefix)) return false;
+  const presented = Buffer.from(header.slice(prefix.length));
+  const expected = Buffer.from(token);
+  // A length mismatch cannot go through `timingSafeEqual`, and the length is
+  // not the secret.
+  if (presented.length !== expected.length) return false;
+  return timingSafeEqual(presented, expected);
+}
+
+class TooLarge extends Error {}
+
+function tooLarge(): Response {
+  return new Response(`the body is over ${MAX_BODY_BYTES} bytes`, { status: 413 });
+}
+
+/** Read the body with a hard ceiling. `request.json()` would buffer the whole
+ * stream before any limit could apply, and the declared length is advisory —
+ * absent entirely under chunked encoding. This route shares an event loop with
+ * every connected client. */
+async function bounded(request: Request): Promise<string> {
+  const body = request.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 > MAX_BODY_BYTES) throw new TooLarge();
+      text += decoder.decode(value, { stream: true });
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return text + decoder.decode();
+}

package/src/version.ts

@@ -0,0 +1,8 @@
+import { version } from "../package.json";
+
+/** This build of ccmsg, taken from the package it is published as so that the
+ * binary, the CLI and the plugin it installs never name three versions.
+ *
+ * It is also the daemon build `hello` and `instance_ping` report, which is what
+ * makes "what a client is told" and "what was released" the same number. */
+export const VERSION: string = version;