@telorun/runner-core 0.5.2

package/src/base-image-catalog.ts

@@ -0,0 +1,320 @@
+/**
+ * A base-image catalog backed by the Docker Hub repository-tags API. A runner
+ * advertises the resolved tag list as an `enum` on its session `image` field so
+ * the editor renders a base-image picker, and validates a chosen image against
+ * the same list server-side — the runner is the source of truth, so a non-editor
+ * client can't widen the allowed set.
+ *
+ * The list is fetched at startup and on a refresh interval, cached in memory,
+ * and degrades gracefully: when Docker Hub is unreachable the catalog still
+ * serves the configured default (always present), so the runner boots and a
+ * session can still start on the default image.
+ *
+ * Free of runner specifics — it takes only a repository, a default ref, and a
+ * tag filter — but the tag source is specifically Docker Hub's registry API
+ * (`hub.docker.com/v2`); a base on another registry (GHCR, a private registry)
+ * can't be enumerated or digest-resolved here. The Docker registry the kubelet
+ * pulls from is a separate concern; this resolves the *menu* of base images, not
+ * pull auth.
+ */
+
+/** A composable predicate set narrowing a repository's tag list to the offered
+ *  menu. Named flags cover the common cases; `include`/`exclude` are the regex
+ *  escape hatch for everything else. */
+export interface TagFilter {
+  /** Keep only `MAJOR.MINOR.PATCH[-variant]` tags — drops moving tags (`latest`,
+   *  `0`, `0.30`) and their variants (`latest-slim`, `0-slim`). */
+  pinnedOnly?: boolean;
+  /** Drop commit-hash tags (`sha-<hex>` or a bare hex string). */
+  excludeSha?: boolean;
+  /** Drop semver prereleases (`0.30.1-rc.1`, `…-alpha`). Variant suffixes like
+   *  `-slim` / `-rust-1.95.0` are NOT prereleases and are kept. */
+  excludePrerelease?: boolean;
+  /** A tag must match at least one of these to be kept. */
+  include?: RegExp[];
+  /** A tag matching any of these is dropped. */
+  exclude?: RegExp[];
+}
+
+export interface BaseImageCatalogOptions {
+  /** `namespace/repository`, e.g. `telorun/node`. */
+  repository: string;
+  /** Always-present default ref — the pre-selected option and the
+   *  Docker-Hub-unreachable fallback, e.g. `telorun/node:latest-slim`. */
+  defaultRef: string;
+  filter?: TagFilter;
+  /** Cap the advertised list to this many tags (newest first). Default 20. */
+  limit?: number;
+  /** Background refresh cadence in ms. Default 1h. */
+  refreshIntervalMs?: number;
+  /** Upper bound on tags pulled from Docker Hub before filtering. Default 200. */
+  maxTagsScanned?: number;
+  /** Per-request timeout for a Docker Hub call, in ms. Default 10s. */
+  requestTimeoutMs?: number;
+  /** Injectable fetch for tests; defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+
+const SHA_TAG = /^(?:sha-)?[0-9a-f]{7,}$/i;
+const PINNED_TAG = /^\d+\.\d+\.\d+(?:[-.].*)?$/;
+const PRERELEASE_CORE = /^\d+\.\d+\.\d+-(.+)$/;
+/** First `-` identifier on a pinned tag that marks it a prerelease rather than a
+ *  build variant (`-slim`, `-rust-*`). */
+const PRERELEASE_TOKENS = new Set([
+  "rc",
+  "alpha",
+  "beta",
+  "pre",
+  "preview",
+  "next",
+  "canary",
+  "dev",
+  "nightly",
+  "snapshot",
+]);
+
+function isShaTag(tag: string): boolean {
+  return SHA_TAG.test(tag);
+}
+
+function isPrerelease(tag: string): boolean {
+  const m = PRERELEASE_CORE.exec(tag);
+  if (!m) return false;
+  const firstId = m[1].split(/[-.]/, 1)[0].toLowerCase();
+  return PRERELEASE_TOKENS.has(firstId);
+}
+
+/** Apply a {@link TagFilter} to a tag list, preserving input order. Pure — the
+ *  unit-testable core of the catalog. */
+export function filterTags(tags: string[], filter: TagFilter = {}): string[] {
+  return tags.filter((tag) => {
+    if (filter.excludeSha && isShaTag(tag)) return false;
+    if (filter.pinnedOnly && !PINNED_TAG.test(tag)) return false;
+    if (filter.excludePrerelease && isPrerelease(tag)) return false;
+    if (filter.include && filter.include.length > 0 && !filter.include.some((re) => re.test(tag))) {
+      return false;
+    }
+    if (filter.exclude && filter.exclude.some((re) => re.test(tag))) return false;
+    return true;
+  });
+}
+
+function splitRepository(repository: string): [namespace: string, repo: string] {
+  const slash = repository.indexOf("/");
+  // A bare name (no slash) is a Docker official image under `library/`.
+  if (slash < 0) return ["library", repository];
+  return [repository.slice(0, slash), repository.slice(slash + 1)];
+}
+
+function unique(refs: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const ref of refs) {
+    if (!seen.has(ref)) {
+      seen.add(ref);
+      out.push(ref);
+    }
+  }
+  return out;
+}
+
+/**
+ * Fetch a repository's tags from Docker Hub, newest first, bounded by
+ * `maxTagsScanned`. Paginates the `/v2/repositories/{ns}/{repo}/tags` endpoint
+ * and sorts by `last_updated` descending so the cap keeps the most recent tags
+ * regardless of the API's page ordering. Throws on a network/HTTP error — the
+ * caller decides whether a failure degrades to default-only.
+ */
+async function fetchRepoTags(
+  repository: string,
+  maxTagsScanned: number,
+  requestTimeoutMs: number,
+  fetchImpl: typeof fetch,
+): Promise<string[]> {
+  const [namespace, repo] = splitRepository(repository);
+  const collected: Array<{ name: string; lastUpdated: string }> = [];
+  let url: string | null =
+    `https://hub.docker.com/v2/repositories/${encodeURIComponent(namespace)}/` +
+    `${encodeURIComponent(repo)}/tags?page_size=100`;
+
+  while (url && collected.length < maxTagsScanned) {
+    const res = await fetchImpl(url, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(requestTimeoutMs),
+    });
+    if (!res.ok) {
+      throw new Error(
+        `Docker Hub tags request for '${repository}' failed: ${res.status} ${res.statusText}`,
+      );
+    }
+    const body = (await res.json()) as {
+      next?: string | null;
+      results?: Array<{ name?: string; last_updated?: string }>;
+    };
+    for (const r of body.results ?? []) {
+      if (typeof r.name === "string") {
+        collected.push({ name: r.name, lastUpdated: r.last_updated ?? "" });
+      }
+    }
+    url = body.next ?? null;
+  }
+
+  collected.sort((a, b) =>
+    a.lastUpdated < b.lastUpdated ? 1 : a.lastUpdated > b.lastUpdated ? -1 : 0,
+  );
+  return collected.map((c) => c.name);
+}
+
+/**
+ * Parse a Docker image reference into the Docker Hub coordinates needed to look
+ * up its digest, or `null` when the ref points at a non-Docker-Hub registry.
+ * Handles the `library/` shorthand, optional `docker.io` host, and an already
+ * `@sha256:`-pinned digest (carried through verbatim).
+ */
+export function parseDockerHubRef(
+  ref: string,
+): { namespace: string; repo: string; tag: string; digest?: string } | null {
+  let rest = ref;
+  let digest: string | undefined;
+  const at = ref.indexOf("@");
+  if (at >= 0) {
+    digest = ref.slice(at + 1);
+    rest = ref.slice(0, at);
+  }
+
+  // A first path segment with a `.`/`:` (or `localhost`) is a registry host.
+  const firstSlash = rest.indexOf("/");
+  const firstPart = firstSlash >= 0 ? rest.slice(0, firstSlash) : "";
+  if (firstPart.includes(".") || firstPart.includes(":") || firstPart === "localhost") {
+    const hubHosts = new Set(["docker.io", "index.docker.io", "registry-1.docker.io"]);
+    if (!hubHosts.has(firstPart)) return null;
+    rest = rest.slice(firstSlash + 1);
+  }
+
+  // `rest` is now `name[:tag]`; the tag is the segment after a colon that isn't
+  // inside the path (i.e. after the last `/`).
+  const lastColon = rest.lastIndexOf(":");
+  const lastSlash = rest.lastIndexOf("/");
+  let name = rest;
+  let tag = "latest";
+  if (lastColon > lastSlash) {
+    name = rest.slice(0, lastColon);
+    tag = rest.slice(lastColon + 1);
+  }
+
+  const slash = name.indexOf("/");
+  return {
+    namespace: slash >= 0 ? name.slice(0, slash) : "library",
+    repo: slash >= 0 ? name.slice(slash + 1) : name,
+    tag,
+    digest,
+  };
+}
+
+/**
+ * Resolve a Docker Hub image ref's CURRENT manifest digest. A moving tag
+ * (`latest-slim`) maps to a new digest once a new version is published, so a
+ * build that folds this into its cache key detects that the base moved and
+ * rebuilds. An already `@sha256:`-pinned ref returns its digest without a
+ * network call. Returns `undefined` for a non-Docker-Hub ref (not an error —
+ * resolution simply doesn't apply) or when a Hub request fails. A genuine
+ * request failure is reported to `onError` rather than swallowed, so an operator
+ * whose Hub calls persistently fail (auth / network / rate-limit) gets a signal
+ * instead of an unexplained "always reuses the cached image".
+ */
+export async function resolveTagDigest(
+  ref: string,
+  opts: {
+    fetchImpl?: typeof fetch;
+    requestTimeoutMs?: number;
+    onError?: (err: unknown) => void;
+  } = {},
+): Promise<string | undefined> {
+  const parsed = parseDockerHubRef(ref);
+  if (!parsed) return undefined;
+  if (parsed.digest) return parsed.digest;
+
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const url =
+    `https://hub.docker.com/v2/repositories/${encodeURIComponent(parsed.namespace)}/` +
+    `${encodeURIComponent(parsed.repo)}/tags/${encodeURIComponent(parsed.tag)}`;
+  try {
+    const res = await fetchImpl(url, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(opts.requestTimeoutMs ?? 10_000),
+    });
+    if (!res.ok) {
+      opts.onError?.(new Error(`Docker Hub tag request for '${ref}' failed: ${res.status} ${res.statusText}`));
+      return undefined;
+    }
+    const body = (await res.json()) as { digest?: string; images?: Array<{ digest?: string }> };
+    return body.digest ?? body.images?.find((i) => i.digest)?.digest ?? undefined;
+  } catch (err) {
+    opts.onError?.(err);
+    return undefined;
+  }
+}
+
+export class BaseImageCatalog {
+  private readonly repository: string;
+  private readonly defaultRef: string;
+  private readonly filter: TagFilter;
+  private readonly limit: number;
+  private readonly refreshIntervalMs: number;
+  private readonly maxTagsScanned: number;
+  private readonly requestTimeoutMs: number;
+  private readonly fetchImpl: typeof fetch;
+  /** Filtered tags (bare, newest first); empty until the first refresh. */
+  private tags: string[] = [];
+  private timer?: ReturnType<typeof setInterval>;
+
+  constructor(opts: BaseImageCatalogOptions) {
+    this.repository = opts.repository;
+    this.defaultRef = opts.defaultRef;
+    this.filter = opts.filter ?? {};
+    this.limit = opts.limit ?? 20;
+    this.refreshIntervalMs = opts.refreshIntervalMs ?? 60 * 60 * 1000;
+    this.maxTagsScanned = opts.maxTagsScanned ?? 200;
+    this.requestTimeoutMs = opts.requestTimeoutMs ?? 10_000;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+  }
+
+  /** The advertised image refs: the default first, then the filtered tags. */
+  current(): string[] {
+    const refs = this.tags.map((tag) => `${this.repository}:${tag}`);
+    return unique([this.defaultRef, ...refs]);
+  }
+
+  /** Whether `ref` is offered by this catalog (server-side allowlist check). */
+  isAllowed(ref: string): boolean {
+    return this.current().includes(ref);
+  }
+
+  /** Refetch and re-filter the tag list. Throws on a fetch/HTTP failure. */
+  async refresh(): Promise<void> {
+    const tags = await fetchRepoTags(
+      this.repository,
+      this.maxTagsScanned,
+      this.requestTimeoutMs,
+      this.fetchImpl,
+    );
+    this.tags = filterTags(tags, this.filter).slice(0, this.limit);
+  }
+
+  /** Begin periodic background refresh. Refresh failures are surfaced to
+   *  `onError` rather than swallowed; the last good list keeps serving. */
+  start(onError?: (err: unknown) => void): void {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      this.refresh().catch((err) => onError?.(err));
+    }, this.refreshIntervalMs);
+    this.timer.unref?.();
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+  }
+}

package/src/capabilities-schema.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+
+import { sessionConfigSchema } from "./capabilities-schema.js";
+
+describe("sessionConfigSchema", () => {
+  it("advertises editable image/pullPolicy with defaults", () => {
+    const schema = sessionConfigSchema({ imageDefault: "telorun/node:0-slim" });
+    const props = schema.properties as Record<string, Record<string, unknown>>;
+    expect(props.image.default).toBe("telorun/node:0-slim");
+    expect(props.image.readOnly).toBeUndefined();
+    expect(props.pullPolicy.default).toBe("missing");
+    expect(props.registryUrl).toBeUndefined();
+    expect(schema.required).toEqual(["image", "pullPolicy"]);
+  });
+
+  it("locks image (only) when enforced; pullPolicy stays editable", () => {
+    const schema = sessionConfigSchema({ imageDefault: "telorun/node:latest-slim", enforced: true });
+    const props = schema.properties as Record<string, Record<string, unknown>>;
+    expect(props.image.readOnly).toBe(true);
+    expect(props.image.default).toBe("telorun/node:latest-slim");
+    expect(props.pullPolicy.readOnly).toBeUndefined();
+  });
+
+  it("includes registryUrl only when requested", () => {
+    const schema = sessionConfigSchema({ imageDefault: "x", registryUrl: true });
+    const props = schema.properties as Record<string, unknown>;
+    expect(props.registryUrl).toBeDefined();
+  });
+
+  it("renders image as an editable enum picker — overriding enforced — when imageEnum is set", () => {
+    const schema = sessionConfigSchema({
+      imageDefault: "telorun/node:latest-slim",
+      enforced: true,
+      imageEnum: ["telorun/node:latest-slim", "telorun/node:0.30.1-slim"],
+    });
+    const props = schema.properties as Record<string, Record<string, unknown>>;
+    expect(props.image.enum).toEqual(["telorun/node:latest-slim", "telorun/node:0.30.1-slim"]);
+    expect(props.image.readOnly).toBeUndefined();
+    expect(props.image.default).toBe("telorun/node:latest-slim");
+    // pullPolicy is a client-editable freshness control.
+    expect(props.pullPolicy.readOnly).toBeUndefined();
+  });
+
+  it("ignores an empty imageEnum and falls back to the enforced field", () => {
+    const schema = sessionConfigSchema({
+      imageDefault: "telorun/node:latest-slim",
+      enforced: true,
+      imageEnum: [],
+    });
+    const props = schema.properties as Record<string, Record<string, unknown>>;
+    expect(props.image.enum).toBeUndefined();
+    expect(props.image.readOnly).toBe(true);
+  });
+});

package/src/capabilities-schema.ts

@@ -0,0 +1,71 @@
+import type { JsonSchema, PullPolicy } from "./contract.js";
+
+export interface SessionConfigSchemaOptions {
+  /** Default container image; becomes the field's advertised `default`. */
+  imageDefault: string;
+  /** When set (and non-empty), constrains `image` to this allowlist — advertised
+   *  as a JSON Schema `enum` so the editor renders a base-image picker. The
+   *  picker is editable within the list, so an `imageEnum` overrides `enforced`
+   *  for the `image` field (a one-entry enum is effectively locked anyway). */
+  imageEnum?: string[];
+  /** Default pull policy (defaults to `missing`). */
+  pullPolicyDefault?: PullPolicy;
+  /** Override the `pullPolicy` field description. `pullPolicy` semantics differ
+   *  per backend (docker: container pull policy; k8s: base-image build
+   *  freshness), so each runner can supply wording that matches its behaviour. */
+  pullPolicyDescription?: string;
+  /** When true, `image` is server-enforced — advertised `readOnly` (locked to
+   *  `imageDefault`) so the editor renders it disabled but still sends it. No
+   *  effect once `imageEnum` is set (the picker is the constraint). `pullPolicy`
+   *  is always client-editable. */
+  enforced?: boolean;
+  /** Include the optional `registryUrl` field (a runner that forwards a module
+   *  registry URL to its workloads). */
+  registryUrl?: boolean;
+}
+
+/**
+ * Builds the JSON Schema a runner advertises on `/v1/capabilities` for the
+ * editable `SessionConfig` surface. `baseUrl` is deliberately absent — the
+ * client owns it. Server-enforced runners pass `enforced: true` to lock `image`
+ * as `readOnly` (the value still travels on the wire); `pullPolicy` is always
+ * client-editable.
+ */
+export function sessionConfigSchema(opts: SessionConfigSchemaOptions): JsonSchema {
+  const readOnly = opts.enforced === true;
+  const hasEnum = Array.isArray(opts.imageEnum) && opts.imageEnum.length > 0;
+  const properties: Record<string, JsonSchema> = {
+    image: {
+      type: "string",
+      minLength: 1,
+      default: opts.imageDefault,
+      title: "Image",
+      description: "Container image the runner spawns for each run.",
+      // An allowlist renders as an editable picker; otherwise fall back to the
+      // enforced (readOnly) single value.
+      ...(hasEnum ? { enum: opts.imageEnum } : readOnly ? { readOnly: true } : {}),
+    },
+    pullPolicy: {
+      type: "string",
+      enum: ["missing", "always", "never"],
+      default: opts.pullPolicyDefault ?? "missing",
+      title: "Pull policy",
+      description:
+        opts.pullPolicyDescription ??
+        "`missing` pulls on first use; `always` forces a pull every run; `never` fails if the image isn't present.",
+    },
+  };
+  if (opts.registryUrl) {
+    properties.registryUrl = {
+      type: "string",
+      title: "Registry URL",
+      description:
+        "Optional base URL for the telo module registry, forwarded to the runner as TELO_REGISTRY_URL. Leave blank for the default registry.",
+    };
+  }
+  return {
+    type: "object",
+    required: ["image", "pullPolicy"],
+    properties,
+  };
+}

package/src/config.ts

@@ -0,0 +1,122 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+import type { RunnerTerms } from "./contract.js";
+
+/**
+ * Backend-neutral runner configuration. Concrete runners (docker, k8s) extend
+ * `RunnerCoreConfig` with their own fields and reuse these parse helpers so
+ * config validation and error reporting stay identical across backends.
+ */
+export interface RunnerCoreConfig {
+  port: number;
+  logLevel: string;
+  maxSessions: number;
+  exitTtlMs: number;
+  replayBufferBytes: number;
+  corsOrigins: string[] | "*";
+}
+
+export class RunnerConfigError extends Error {}
+
+export function parsePositiveInt(
+  raw: string | undefined,
+  fallback: number,
+  field: string,
+): number {
+  if (raw === undefined || raw.trim() === "") return fallback;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new RunnerConfigError(`${field} must be a positive integer, got '${raw}'.`);
+  }
+  return n;
+}
+
+export function parseBool(raw: string | undefined, fallback: boolean, field: string): boolean {
+  const v = raw?.trim().toLowerCase();
+  if (v === undefined || v === "") return fallback;
+  if (v === "true" || v === "1" || v === "yes") return true;
+  if (v === "false" || v === "0" || v === "no") return false;
+  throw new RunnerConfigError(`${field} must be a boolean (true/false), got '${raw}'.`);
+}
+
+export function parsePort(raw: string | undefined, fallback: number): number {
+  const portStr = raw ?? String(fallback);
+  const port = Number(portStr);
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new RunnerConfigError(`PORT must be an integer in 1..65535, got '${portStr}'.`);
+  }
+  return port;
+}
+
+/**
+ * Build the runner's usage terms from the environment. Terms are opt-in: returns
+ * `undefined` (no gate) unless a non-empty body is provided.
+ *
+ * The body comes from `RUNNER_TERMS_FILE` (a path read at startup — the natural
+ * fit for a k8s ConfigMap mount or a bind-mounted file) or, for short notes,
+ * inline `RUNNER_TERMS_BODY`. `RUNNER_TERMS_VERSION` is optional and defaults to
+ * a short hash of the body, so editing the agreement automatically re-prompts
+ * every client; set it explicitly only to control "material change vs. typo".
+ * A configured-but-unreadable `RUNNER_TERMS_FILE` is a hard error rather than a
+ * silent "no terms", so a misconfiguration can't quietly drop the gate.
+ */
+export function loadTermsFromEnv(env: NodeJS.ProcessEnv): RunnerTerms | undefined {
+  const body = resolveTermsBody(env);
+  if (!body || body.trim() === "") return undefined;
+  return {
+    version: env.RUNNER_TERMS_VERSION?.trim() || hashTermsVersion(body),
+    title: env.RUNNER_TERMS_TITLE?.trim() || "Usage agreement",
+    body,
+  };
+}
+
+function resolveTermsBody(env: NodeJS.ProcessEnv): string | undefined {
+  const file = env.RUNNER_TERMS_FILE?.trim();
+  if (file) {
+    try {
+      return readFileSync(file, "utf8");
+    } catch (err) {
+      throw new RunnerConfigError(
+        `RUNNER_TERMS_FILE could not be read at '${file}': ${(err as Error).message}`,
+      );
+    }
+  }
+  return env.RUNNER_TERMS_BODY;
+}
+
+/** Short content fingerprint used as the terms version when none is set. Any
+ *  edit to the body changes it, which re-prompts every client. */
+function hashTermsVersion(body: string): string {
+  return createHash("sha256").update(body).digest("hex").slice(0, 12);
+}
+
+export function parseCorsOrigins(raw: string | undefined): string[] | "*" {
+  if (raw === undefined || raw.trim() === "" || raw.trim() === "*") return "*";
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+export function loadCoreConfig(
+  env: NodeJS.ProcessEnv,
+  defaults: { port?: number } = {},
+): RunnerCoreConfig {
+  return {
+    port: parsePort(env.PORT, defaults.port ?? 8061),
+    logLevel: env.LOG_LEVEL?.trim() || "info",
+    maxSessions: parsePositiveInt(env.RUNNER_MAX_SESSIONS, 32, "RUNNER_MAX_SESSIONS"),
+    // Exited sessions linger so the editor can re-attach and replay their console
+    // + inspection history after a page reload. The registry evicts the oldest
+    // *terminal* session early when at capacity, so a long TTL never blocks a new
+    // run while live sessions are protected.
+    exitTtlMs: parsePositiveInt(env.RUNNER_EXIT_TTL_MS, 4 * 60 * 60 * 1000, "RUNNER_EXIT_TTL_MS"),
+    replayBufferBytes: parsePositiveInt(
+      env.RUNNER_REPLAY_BUFFER_BYTES,
+      5_000_000,
+      "RUNNER_REPLAY_BUFFER_BYTES",
+    ),
+    corsOrigins: parseCorsOrigins(env.RUNNER_CORS_ORIGINS),
+  };
+}