@telorun/runner-core 0.5.2

package/dist/sse/channel.js

@@ -0,0 +1,129 @@
+import { isTerminal } from "../contract.js";
+import { SessionEvictedError } from "../session/registry.js";
+const HEARTBEAT_MS = 20_000;
+export async function streamSessionEvents(args) {
+    const { registry, req, reply, sessionId, corsOrigins } = args;
+    const entry = registry.get(sessionId);
+    if (!entry) {
+        reply.code(404).send({ error: "not_found", message: `session '${sessionId}' not in registry` });
+        return;
+    }
+    const lastEventId = resolveLastEventId(req);
+    const raw = reply.raw;
+    // @fastify/cors adds Access-Control-Allow-Origin via an onSend hook, which
+    // never fires for this route because we bypass reply and write directly to
+    // reply.raw. Inject the CORS headers manually from our config.
+    const headers = {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache, no-transform",
+        connection: "keep-alive",
+        "x-accel-buffering": "no",
+    };
+    const allowOrigin = resolveAllowOrigin(corsOrigins, req.headers.origin);
+    if (allowOrigin) {
+        headers["access-control-allow-origin"] = allowOrigin;
+        headers["vary"] = "Origin";
+    }
+    raw.writeHead(200, headers);
+    // Replay any buffered history > lastEventId. `hasGap` triggers a synthetic
+    // gap marker so the client knows earlier output was evicted before we could
+    // deliver it.
+    const { entries, hasGap } = entry.buffer.replay(lastEventId);
+    if (hasGap) {
+        writeFrame(raw, "gap", { reason: "buffer_evicted" });
+    }
+    for (const buffered of entries) {
+        writeBufferedEvent(raw, buffered);
+    }
+    // If the session already reached a terminal status before the client hit
+    // /events, replay has delivered the terminal status frame and we're done.
+    if (isTerminal(entry.status)) {
+        raw.end();
+        return;
+    }
+    let unsubscribe = null;
+    let heartbeat = null;
+    let closed = false;
+    const cleanup = () => {
+        if (closed)
+            return;
+        closed = true;
+        if (heartbeat)
+            clearInterval(heartbeat);
+        if (unsubscribe)
+            unsubscribe();
+        if (!raw.writableEnded)
+            raw.end();
+    };
+    heartbeat = setInterval(() => {
+        if (!raw.writableEnded)
+            raw.write(": heartbeat\n\n");
+    }, HEARTBEAT_MS);
+    heartbeat.unref?.();
+    try {
+        unsubscribe = registry.subscribe(sessionId, (buffered) => {
+            writeBufferedEvent(raw, buffered);
+            if (buffered.event.type === "status" && isTerminal(buffered.event.status)) {
+                cleanup();
+            }
+        });
+    }
+    catch (err) {
+        if (err instanceof SessionEvictedError) {
+            cleanup();
+            return;
+        }
+        throw err;
+    }
+    req.raw.on("close", cleanup);
+    req.raw.on("end", cleanup);
+    // Keep the response alive — Fastify's handler must not return until the
+    // stream closes, otherwise it sends a default end.
+    await new Promise((resolve) => {
+        raw.on("close", resolve);
+        raw.on("finish", resolve);
+    });
+}
+function resolveLastEventId(req) {
+    // Spec: header wins over query. EventSource sets the header on native
+    // auto-reconnect; the query param is for fresh instances (tab reload) where
+    // sse-client.ts passes the persisted id explicitly.
+    const header = req.headers["last-event-id"];
+    const fromHeader = parseId(Array.isArray(header) ? header[0] : header);
+    if (fromHeader !== null)
+        return fromHeader;
+    const query = req.query;
+    const fromQuery = parseId(query?.lastEventId);
+    return fromQuery ?? 0;
+}
+function resolveAllowOrigin(corsOrigins, requestOrigin) {
+    if (corsOrigins === "*")
+        return "*";
+    const origin = Array.isArray(requestOrigin) ? requestOrigin[0] : requestOrigin;
+    if (!origin)
+        return null;
+    return corsOrigins.includes(origin) ? origin : null;
+}
+function parseId(raw) {
+    if (!raw)
+        return null;
+    const n = Number.parseInt(raw, 10);
+    // `Last-Event-ID: 0` is valid per the SSE spec — it means "resume from the
+    // beginning." Our ids start at 1, so replay(0) returns all buffered entries
+    // and the hasGap check correctly compares against first-resident-id.
+    return Number.isFinite(n) && n >= 0 ? n : null;
+}
+function writeBufferedEvent(raw, buffered) {
+    writeFrame(raw, buffered.event.type, buffered.event, buffered.id);
+}
+function writeFrame(raw, event, data, id) {
+    if (!("writable" in raw) || raw.writableEnded)
+        return;
+    let frame = "";
+    if (id !== undefined)
+        frame += `id: ${id}\n`;
+    frame += `event: ${event}\n`;
+    frame += `data: ${JSON.stringify(data)}\n\n`;
+    raw.write(frame);
+}
+//# sourceMappingURL=channel.js.map

package/dist/sse/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../../src/sse/channel.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@telorun/runner-core",
+  "version": "0.5.2",
+  "description": "Backend-neutral core for Telo runners: the /v1 session contract, the RunnerBackend interface, the session registry, SSE/byte ring buffers, and bundle handling. Shared by docker-runner and k8s-runner.",
+  "keywords": [
+    "telo",
+    "runner"
+  ],
+  "author": "Bartosz Pasiński <bartosz.pasinski@codenet.pl>",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telorun/telo.git",
+    "directory": "packages/runner-core"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/**",
+    "src/**"
+  ],
+  "dependencies": {
+    "@fastify/cors": "^11.0.1",
+    "@fastify/websocket": "^11.0.1",
+    "fastify": "^5.7.2",
+    "yaml": "^2.8.3",
+    "@telorun/debug-wire": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.8",
+    "ws": "^8.18.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/backend.ts

@@ -0,0 +1,88 @@
+import type { DebugFrame } from "@telorun/debug-wire";
+
+import type {
+  AvailabilityReport,
+  PortMapping,
+  ProbeConfig,
+  RunBundle,
+  RunPhase,
+  RunStatus,
+  SessionConfig,
+} from "./contract.js";
+
+/**
+ * The seam between backend-neutral session machinery (routes, registry, SSE)
+ * and a concrete workload runtime (docker container, kubernetes pod).
+ *
+ * Deliberately abstract: a byte-stream out (`onOutput`), a stdin writer
+ * (`BackendSession.writeStdin`), a resize signal, and a wait/exit (`done`) —
+ * NOT docker's `ReadWriteStream` duplex. The k8s backend serves the same shape
+ * over the Pod `attach` subresource; the docker backend adapts its hijacked
+ * attach duplex onto it. Bundle delivery is the backend's responsibility too
+ * (docker writes a shared-volume workdir; k8s stages the bundle for an
+ * initContainer fetch), so the spec carries the raw `bundle` rather than a
+ * pre-resolved on-disk path.
+ */
+export interface RunnerBackend {
+  /** Report readiness without starting a session (daemon/cluster reachable,
+   *  image pullable, scaffolding present). Backs `POST /v1/probe`. */
+  probe(config: ProbeConfig): Promise<AvailabilityReport>;
+
+  /** Spawn the workload and wire it to the supplied callbacks. Resolves once
+   *  the workload has started (after a `running` status is emitted); rejects
+   *  with `SessionStartError` for any pre-start failure. */
+  start(spec: BackendStartSpec): Promise<BackendSession>;
+
+  /** Reap workloads orphaned by a prior runner process, matched by the
+   *  backend's own labelling. Run once at boot — the session registry is
+   *  in-memory, so a restart otherwise leaks running workloads. */
+  reapOrphans?(): Promise<void>;
+}
+
+export interface BackendStartSpec {
+  sessionId: string;
+  bundle: RunBundle;
+  /** Bundle-relative entry path, already traversal-normalized by core. */
+  entryRelativePath: string;
+  env: Record<string, string>;
+  ports: PortMapping[];
+  config: SessionConfig;
+  /** When true, launch the workload with `--inspect` and relay its kernel debug
+   *  stream via `onDebug`. The inspect endpoint stays reachable only by the
+   *  runner — never published outward. */
+  inspect: boolean;
+
+  /** Emit a lifecycle status. The backend drives `starting` → `running` →
+   *  terminal (`exited`/`failed`/`stopped`). */
+  onStatus(status: RunStatus): void;
+  /** Emit a progress message for a coming-up phase (build / provision / boot).
+   *  Additive to status — surfaces what's happening while the session is still
+   *  `starting`, driving the editor's spinner + step feed. */
+  onProgress(phase: RunPhase, message: string, done?: boolean): void;
+  /** Raw merged stdout/stderr (PTY) bytes from the workload. */
+  onOutput(chunk: Buffer): void;
+  /** A frame relayed from the workload's kernel debug stream. Only called when
+   *  `inspect` is true and the backend has connected to the inspect endpoint. */
+  onDebug(frame: DebugFrame): void;
+  /** True once a user stop / shutdown has been requested — lets the backend
+   *  classify a kill as `stopped` rather than `failed`. */
+  isUserStopped(): boolean;
+}
+
+export interface BackendSession {
+  /** Write bytes to the workload's stdin (PTY). A no-op once the workload has
+   *  terminated, so callers need not track liveness. */
+  writeStdin(bytes: Uint8Array): void;
+
+  /** Resize the workload's PTY. */
+  resize(cols: number, rows: number): void;
+
+  /** Resolves after the workload terminates and its terminal status has been
+   *  emitted via `onStatus`. Never rejects — terminal failures surface as a
+   *  `failed` status. */
+  readonly done: Promise<void>;
+
+  /** Force-stop the workload. Idempotent and safe to call after natural exit
+   *  (a backend should treat an already-gone workload as a no-op). */
+  stop(): Promise<void>;
+}

package/src/base-image-catalog.test.ts

@@ -0,0 +1,209 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  BaseImageCatalog,
+  filterTags,
+  parseDockerHubRef,
+  resolveTagDigest,
+} from "./base-image-catalog.js";
+
+const SAMPLE = [
+  "latest",
+  "latest-slim",
+  "0",
+  "0-slim",
+  "0.30",
+  "0.30-slim",
+  "0.30.1",
+  "0.30.1-slim",
+  "0.30.0",
+  "0.29.3-slim",
+  "latest-rust-1.95.0-slim",
+  "0.30.1-rust-1.95.0",
+  "0.30.1-rc.1",
+  "0.30.1-rc.1-slim",
+  "sha-abc1234",
+  "deadbeef1234",
+];
+
+describe("filterTags", () => {
+  it("pinnedOnly keeps only MAJOR.MINOR.PATCH[-variant] tags", () => {
+    const out = filterTags(SAMPLE, { pinnedOnly: true });
+    expect(out).toEqual([
+      "0.30.1",
+      "0.30.1-slim",
+      "0.30.0",
+      "0.29.3-slim",
+      "0.30.1-rust-1.95.0",
+      "0.30.1-rc.1",
+      "0.30.1-rc.1-slim",
+    ]);
+  });
+
+  it("excludeSha drops commit-hash tags", () => {
+    const out = filterTags(SAMPLE, { excludeSha: true });
+    expect(out).not.toContain("sha-abc1234");
+    expect(out).not.toContain("deadbeef1234");
+    expect(out).toContain("0.30.1");
+  });
+
+  it("excludePrerelease drops semver prereleases but keeps build variants", () => {
+    const out = filterTags(["0.30.1", "0.30.1-slim", "0.30.1-rust-1.95.0", "0.30.1-rc.1", "0.30.1-rc.1-slim"], {
+      excludePrerelease: true,
+    });
+    expect(out).toEqual(["0.30.1", "0.30.1-slim", "0.30.1-rust-1.95.0"]);
+  });
+
+  it("pinnedOnly + excludeSha + excludePrerelease yields the release menu", () => {
+    const out = filterTags(SAMPLE, { pinnedOnly: true, excludeSha: true, excludePrerelease: true });
+    expect(out).toEqual(["0.30.1", "0.30.1-slim", "0.30.0", "0.29.3-slim", "0.30.1-rust-1.95.0"]);
+  });
+
+  it("include / exclude regexes are the escape hatch", () => {
+    expect(filterTags(SAMPLE, { include: [/-slim$/] })).toEqual([
+      "latest-slim",
+      "0-slim",
+      "0.30-slim",
+      "0.30.1-slim",
+      "0.29.3-slim",
+      "latest-rust-1.95.0-slim",
+      "0.30.1-rc.1-slim",
+    ]);
+    expect(filterTags(SAMPLE, { pinnedOnly: true, exclude: [/-rust-/] })).not.toContain(
+      "0.30.1-rust-1.95.0",
+    );
+  });
+});
+
+/** A fake Docker Hub tags endpoint serving one page of `results`. */
+function fakeHub(results: Array<{ name: string; last_updated?: string }>): typeof fetch {
+  return (async () =>
+    new Response(JSON.stringify({ next: null, results }), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    })) as unknown as typeof fetch;
+}
+
+describe("BaseImageCatalog", () => {
+  const defaultRef = "telorun/node:latest-slim";
+
+  it("serves only the default before the first refresh", () => {
+    const catalog = new BaseImageCatalog({ repository: "telorun/node", defaultRef });
+    expect(catalog.current()).toEqual([defaultRef]);
+    expect(catalog.isAllowed(defaultRef)).toBe(true);
+    expect(catalog.isAllowed("telorun/node:0.30.1-slim")).toBe(false);
+  });
+
+  it("advertises the default first, then filtered tags newest-first within the limit", async () => {
+    const catalog = new BaseImageCatalog({
+      repository: "telorun/node",
+      defaultRef,
+      filter: { pinnedOnly: true },
+      limit: 2,
+      fetchImpl: fakeHub([
+        { name: "0.30.0", last_updated: "2026-06-14T00:00:00Z" },
+        { name: "0.30.1", last_updated: "2026-06-15T00:00:00Z" },
+        { name: "0.29.9", last_updated: "2026-06-10T00:00:00Z" },
+        { name: "latest", last_updated: "2026-06-15T00:00:00Z" },
+      ]),
+    });
+    await catalog.refresh();
+    expect(catalog.current()).toEqual([
+      defaultRef,
+      "telorun/node:0.30.1",
+      "telorun/node:0.30.0",
+    ]);
+    expect(catalog.isAllowed("telorun/node:0.30.1")).toBe(true);
+    expect(catalog.isAllowed("telorun/node:0.29.9")).toBe(false); // dropped by limit
+  });
+
+  it("keeps the default offered even when filters would exclude it", async () => {
+    const catalog = new BaseImageCatalog({
+      repository: "telorun/node",
+      defaultRef, // latest-slim — a moving tag pinnedOnly drops
+      filter: { pinnedOnly: true },
+      fetchImpl: fakeHub([{ name: "0.30.1", last_updated: "2026-06-15T00:00:00Z" }]),
+    });
+    await catalog.refresh();
+    expect(catalog.current()).toContain(defaultRef);
+    expect(catalog.isAllowed(defaultRef)).toBe(true);
+  });
+
+  it("throws on a non-ok Docker Hub response so the caller can degrade", async () => {
+    const catalog = new BaseImageCatalog({
+      repository: "telorun/node",
+      defaultRef,
+      fetchImpl: (async () => new Response("nope", { status: 500 })) as unknown as typeof fetch,
+    });
+    await expect(catalog.refresh()).rejects.toThrow(/Docker Hub tags request/);
+    expect(catalog.current()).toEqual([defaultRef]); // unchanged
+  });
+});
+
+describe("parseDockerHubRef", () => {
+  it("parses namespace/repo:tag", () => {
+    expect(parseDockerHubRef("telorun/node:latest-slim")).toEqual({
+      namespace: "telorun",
+      repo: "node",
+      tag: "latest-slim",
+      digest: undefined,
+    });
+  });
+
+  it("defaults the tag and the library namespace", () => {
+    expect(parseDockerHubRef("node")).toMatchObject({ namespace: "library", repo: "node", tag: "latest" });
+  });
+
+  it("strips a docker.io host and carries an @digest through", () => {
+    expect(parseDockerHubRef("docker.io/telorun/node:0.30.1")).toMatchObject({
+      namespace: "telorun",
+      repo: "node",
+      tag: "0.30.1",
+    });
+    expect(parseDockerHubRef("telorun/node@sha256:abc")?.digest).toBe("sha256:abc");
+  });
+
+  it("returns null for a non-Docker-Hub registry", () => {
+    expect(parseDockerHubRef("ghcr.io/telorun/node:latest")).toBeNull();
+    expect(parseDockerHubRef("registry.telo-runner.svc:5000/x:y")).toBeNull();
+  });
+});
+
+describe("resolveTagDigest", () => {
+  it("returns an already-pinned digest without a network call", async () => {
+    let called = false;
+    const fetchImpl = (async () => {
+      called = true;
+      return new Response("{}");
+    }) as unknown as typeof fetch;
+    expect(await resolveTagDigest("telorun/node@sha256:deadbeef", { fetchImpl })).toBe(
+      "sha256:deadbeef",
+    );
+    expect(called).toBe(false);
+  });
+
+  it("reads the manifest digest from the Docker Hub tag endpoint", async () => {
+    const fetchImpl = (async () =>
+      new Response(JSON.stringify({ digest: "sha256:abc123", images: [{ digest: "sha256:zzz" }] }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      })) as unknown as typeof fetch;
+    expect(await resolveTagDigest("telorun/node:latest-slim", { fetchImpl })).toBe("sha256:abc123");
+  });
+
+  it("returns undefined for a non-Hub ref or on a failed request", async () => {
+    expect(await resolveTagDigest("ghcr.io/foo/bar:1")).toBeUndefined();
+    const fetchImpl = (async () => new Response("nope", { status: 404 })) as unknown as typeof fetch;
+    expect(await resolveTagDigest("telorun/node:missing", { fetchImpl })).toBeUndefined();
+  });
+
+  it("reports a genuine Hub failure to onError but stays silent for a non-Hub ref", async () => {
+    const errors: unknown[] = [];
+    const fail = (async () => new Response("boom", { status: 500 })) as unknown as typeof fetch;
+    await resolveTagDigest("telorun/node:latest", { fetchImpl: fail, onError: (e) => errors.push(e) });
+    expect(errors).toHaveLength(1);
+
+    await resolveTagDigest("ghcr.io/foo/bar:1", { onError: (e) => errors.push(e) });
+    expect(errors).toHaveLength(1); // non-Hub ref is not an error
+  });
+});