@telorun/runner-core 0.5.2 → 0.7.0

package/src/index.ts

@@ -30,4 +30,8 @@ export { probeRoute, type ProbeRouteDeps } from "./routes/probe.js";
 export { sessionsRoute, type SessionsRouteDeps } from "./routes/sessions.js";
 export { ioRoute, type IoRouteDeps } from "./routes/io.js";
 export { relayDebugStream, type DebugRelayOptions } from "./debug/relay.js";
+export {
+  watchReachability,
+  type WatchReachabilityOptions,
+} from "./reachability.js";
 export type { DebugFrame, DebugEvent, DebugLog } from "@telorun/debug-wire";

package/src/reachability.test.ts

@@ -0,0 +1,83 @@
+import net from "node:net";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import type { ReachabilityState } from "./contract.js";
+import { watchReachability } from "./reachability.js";
+
+const servers: net.Server[] = [];
+
+function listen(port = 0): Promise<{ port: number; server: net.Server }> {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    servers.push(server);
+    server.listen(port, "127.0.0.1", () => {
+      resolve({ port: (server.address() as net.AddressInfo).port, server });
+    });
+  });
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+afterEach(() => {
+  for (const s of servers) s.close();
+  servers.length = 0;
+});
+
+// Short windows so the suite is fast; real defaults are seconds.
+const fast = { timeoutMs: 120, intervalMs: 20, recheckIntervalMs: 20, connectTimeoutMs: 50 };
+
+describe("watchReachability", () => {
+  it("reports checking then reachable for a live port", async () => {
+    const { port } = await listen();
+    const states: ReachabilityState[] = [];
+    await watchReachability({
+      host: "127.0.0.1",
+      ports: [port],
+      onState: (_p, s) => states.push(s),
+      signal: new AbortController().signal,
+      ...fast,
+    });
+    expect(states[0]).toBe("checking");
+    expect(states.at(-1)).toBe("reachable");
+  });
+
+  it("reports unreachable after the timeout when nothing listens", async () => {
+    const { port, server } = await listen();
+    server.close(); // free the port → connections are refused
+    const states: ReachabilityState[] = [];
+    const controller = new AbortController();
+    const run = watchReachability({
+      host: "127.0.0.1",
+      ports: [port],
+      onState: (_p, s) => states.push(s),
+      signal: controller.signal,
+      ...fast,
+    });
+    await sleep(300);
+    controller.abort();
+    await run;
+    expect(states[0]).toBe("checking");
+    expect(states).toContain("unreachable");
+  });
+
+  it("flips back to reachable when the port recovers", async () => {
+    const { port, server } = await listen();
+    server.close();
+    const states: ReachabilityState[] = [];
+    const run = watchReachability({
+      host: "127.0.0.1",
+      ports: [port],
+      onState: (_p, s) => states.push(s),
+      signal: new AbortController().signal,
+      ...fast,
+    });
+    await sleep(200); // past the timeout → unreachable
+    await listen(port); // bind the same port → recovers
+    await run; // resolves once reachable
+    expect(states).toContain("unreachable");
+    expect(states.at(-1)).toBe("reachable");
+  });
+});

package/src/reachability.ts

@@ -0,0 +1,106 @@
+import net from "node:net";
+
+import { abortableDelay } from "./abortable-delay.js";
+import type { ReachabilityState } from "./contract.js";
+
+export interface WatchReachabilityOptions {
+  /** Address the runner dials — pod IP (k8s) or published host / container name (docker). */
+  host: string;
+  /** TCP ports the workload declared; each is watched and reported by port. */
+  ports: number[];
+  /** Receives every state transition for a port: `checking` on start, then
+   *  `reachable` once it accepts a connection, or `unreachable` after the timeout. */
+  onState: (port: number, state: ReachabilityState) => void;
+  /** Aborts the watch — wire to the session's teardown. */
+  signal: AbortSignal;
+  /** How long a port may stay unreachable before it's reported `unreachable`.
+   *  Default 30s. */
+  timeoutMs?: number;
+  /** Poll interval while waiting for a port to come up. Default 1s. */
+  intervalMs?: number;
+  /** Poll interval after a port was reported `unreachable`, to flip it back to
+   *  `reachable` if it recovers. Default 5s. */
+  recheckIntervalMs?: number;
+  /** Per-attempt TCP connect timeout. Default 1s. */
+  connectTimeoutMs?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_INTERVAL_MS = 1_000;
+const DEFAULT_RECHECK_INTERVAL_MS = 5_000;
+const DEFAULT_CONNECT_TIMEOUT_MS = 1_000;
+
+interface WatchConfig {
+  host: string;
+  onState: (port: number, state: ReachabilityState) => void;
+  signal: AbortSignal;
+  timeoutMs: number;
+  intervalMs: number;
+  recheckIntervalMs: number;
+  connectTimeoutMs: number;
+}
+
+/** One TCP connect attempt. Resolves true on a completed connection, false on
+ *  refusal / timeout / error. Never throws; `unref`'d so a pending attempt can't
+ *  keep the event loop alive, and always torn down. */
+function tryConnect(host: string, port: number, timeoutMs: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host, port });
+    socket.unref();
+    let settled = false;
+    const done = (ok: boolean): void => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}
+
+async function watchPort(port: number, cfg: WatchConfig): Promise<void> {
+  cfg.onState(port, "checking");
+  const start = Date.now();
+  let reportedUnreachable = false;
+  while (!cfg.signal.aborted) {
+    if (await tryConnect(cfg.host, port, cfg.connectTimeoutMs)) {
+      cfg.onState(port, "reachable");
+      return;
+    }
+    if (!reportedUnreachable && Date.now() - start >= cfg.timeoutMs) {
+      reportedUnreachable = true;
+      cfg.onState(port, "unreachable");
+    }
+    await abortableDelay(reportedUnreachable ? cfg.recheckIntervalMs : cfg.intervalMs, cfg.signal);
+  }
+}
+
+/**
+ * Watches each declared TCP port for reachability from the runner network and
+ * reports per-port transitions via `onState`: `checking` immediately, then
+ * `reachable` the moment a connection succeeds, or `unreachable` after
+ * `timeoutMs` of refusal. After `unreachable` it keeps probing (slower) and
+ * flips back to `reachable` on recovery — so a slow-but-correct start
+ * self-corrects.
+ *
+ * This catches the loopback-bind / wrong-port / crash-loop failure that
+ * otherwise surfaces only as an opaque downstream 502; emitting state (not a log
+ * line) lets the editor render it on the endpoint badge. Backend-neutral: the
+ * runner supplies how its workload is dialed and where state goes.
+ */
+export async function watchReachability(options: WatchReachabilityOptions): Promise<void> {
+  if (options.ports.length === 0) return;
+  const cfg: WatchConfig = {
+    host: options.host,
+    onState: options.onState,
+    signal: options.signal,
+    timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    intervalMs: options.intervalMs ?? DEFAULT_INTERVAL_MS,
+    recheckIntervalMs: options.recheckIntervalMs ?? DEFAULT_RECHECK_INTERVAL_MS,
+    connectTimeoutMs: options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS,
+  };
+  await Promise.all(options.ports.map((port) => watchPort(port, cfg)));
+}

package/src/routes/sessions.ts

@@ -5,10 +5,12 @@ import type { RunnerBackend } from "../backend.js";
 import {
   ACCEPTED_TERMS_HEADER,
   SessionStartError,
+  type RunBundle,
   type RunnerTerms,
   type SessionConfig,
   type StartSessionRequest,
 } from "../contract.js";
+import type { ResolvedRunnerApp } from "../config.js";
 import { BundlePathError, normalizeBundlePath } from "../session/bundle-path.js";
 import { generateSessionId } from "../session/session-id.js";
 import { SessionLimitError, type SessionRegistry } from "../session/registry.js";
@@ -24,6 +26,10 @@ export interface SessionsRouteDeps {
   /** When set, a session may only start if the client acknowledges this exact
    *  terms version via the `x-telo-accepted-terms` header. */
   terms?: RunnerTerms;
+  /** Operator-predefined applications launchable by name
+   *  (`StartSessionRequest.app`), with their operator env already resolved.
+   *  The catalog is the whole gate — an unknown name is rejected. */
+  apps?: Record<string, ResolvedRunnerApp>;
   /** Backend-supplied config gate. Returns an error message to reject the
    *  request with `400 invalid_config`, or `undefined` to accept. The runner is
    *  the source of truth, so this re-checks what `/v1/capabilities` advertises
@@ -31,10 +37,13 @@ export interface SessionsRouteDeps {
   validateConfig?: (config: SessionConfig) => string | undefined;
 }
 
+// `bundle`/`config` are schema-optional because an `app` session needs neither;
+// the route enforces their presence for regular bundle sessions.
 const startBodySchema = {
   type: "object",
-  required: ["bundle", "env", "config"],
+  required: ["env"],
   properties: {
+    app: { type: "string", minLength: 1 },
     bundle: {
       type: "object",
       required: ["entryRelativePath", "files"],
@@ -157,29 +166,68 @@ async function startSession(
 ): Promise<void> {
   const sessionId = generateSessionId();
 
+  // App sessions launch an operator-predefined image by name: the catalog
+  // resolves the image and operator env server-side, so the client can neither
+  // pick the image nor reach the secrets — the catalog IS the gate, and an
+  // unknown name is rejected here.
+  const appEntry = body.app === undefined ? undefined : deps.apps?.[body.app];
+  if (body.app !== undefined && !appEntry) {
+    const offered = Object.keys(deps.apps ?? {});
+    reply.code(400).send({
+      error: "unknown_app",
+      message:
+        `app '${body.app}' is not offered by this runner` +
+        (offered.length > 0
+          ? ` — offered apps: ${offered.join(", ")}`
+          : " — it offers no predefined applications") +
+        " (see /v1/capabilities).",
+    });
+    return;
+  }
+  if (!appEntry && (!body.bundle || !body.config)) {
+    reply.code(400).send({
+      error: "invalid_request",
+      message: "'bundle' and 'config' are required unless launching a predefined app via 'app'.",
+    });
+    return;
+  }
+
+  let bundle: RunBundle;
   let entryRelative: string;
-  try {
-    // Traversal guard for the entry path and every bundle file — a `../foo`
-    // would let the workload read or execute paths outside its session dir.
-    // Validated here (backend-neutral) so a bad path is a 400, not a backend
-    // 500, regardless of how the backend ultimately delivers the bundle.
-    entryRelative = normalizeBundlePath(body.bundle.entryRelativePath);
-    for (const file of body.bundle.files) normalizeBundlePath(file.relativePath);
-  } catch (err) {
-    if (err instanceof BundlePathError) {
-      reply.code(400).send({ error: "invalid_bundle", message: err.message });
-      return;
+  let config: SessionConfig;
+  if (appEntry) {
+    // Self-contained image — no bundle to deliver; the entry path is an unused
+    // placeholder so the backend spec stays total.
+    bundle = { entryRelativePath: "telo.yaml", files: [] };
+    entryRelative = bundle.entryRelativePath;
+    config = { image: appEntry.image, pullPolicy: appEntry.pullPolicy };
+  } else {
+    bundle = body.bundle!;
+    config = body.config!;
+    try {
+      // Traversal guard for the entry path and every bundle file — a `../foo`
+      // would let the workload read or execute paths outside its session dir.
+      // Validated here (backend-neutral) so a bad path is a 400, not a backend
+      // 500, regardless of how the backend ultimately delivers the bundle.
+      entryRelative = normalizeBundlePath(bundle.entryRelativePath);
+      for (const file of bundle.files) normalizeBundlePath(file.relativePath);
+    } catch (err) {
+      if (err instanceof BundlePathError) {
+        reply.code(400).send({ error: "invalid_bundle", message: err.message });
+        return;
+      }
+      throw err;
     }
-    throw err;
-  }
 
-  // Backend config gate (e.g. an image allowlist). The advertised capabilities
-  // constrain the editor; this enforces the same against any client.
-  if (deps.validateConfig) {
-    const message = deps.validateConfig(body.config);
-    if (message) {
-      reply.code(400).send({ error: "invalid_config", message });
-      return;
+    // Backend config gate (e.g. an image allowlist). The advertised capabilities
+    // constrain the editor; this enforces the same against any client. App
+    // sessions skip it — their image comes from the catalog, not the client.
+    if (deps.validateConfig) {
+      const message = deps.validateConfig(config);
+      if (message) {
+        reply.code(400).send({ error: "invalid_config", message });
+        return;
+      }
     }
   }
 
@@ -194,16 +242,28 @@ async function startSession(
     throw err;
   }
 
+  // For an app session, drop client-supplied values for any env key the
+  // catalog defines (a client must never override operator-held values, which
+  // include secrets), then inject the operator's values.
+  const clientEnv = appEntry
+    ? {
+        ...Object.fromEntries(
+          Object.entries(body.env).filter(([key]) => !(key in appEntry.env)),
+        ),
+        ...appEntry.env,
+      }
+    : body.env;
+
   // Surface a TELO_REGISTRY_URL to the workload so the telo CLI inside picks
-  // it up. Precedence: body.env explicit value > body.config.registryUrl
-  // (per-request override) > runner's own default. Trim client-supplied URLs
-  // so stray whitespace from an editor input doesn't flow into the workload.
-  const configRegistryUrl = body.config.registryUrl?.trim() || undefined;
+  // it up. Precedence: explicit env value > config.registryUrl (per-request
+  // override) > runner's own default. Trim client-supplied URLs so stray
+  // whitespace from an editor input doesn't flow into the workload.
+  const configRegistryUrl = config.registryUrl?.trim() || undefined;
   const registryUrl = configRegistryUrl ?? deps.defaultRegistryUrl;
   const sessionEnv =
-    registryUrl && !("TELO_REGISTRY_URL" in body.env)
-      ? { ...body.env, TELO_REGISTRY_URL: registryUrl }
-      : body.env;
+    registryUrl && !("TELO_REGISTRY_URL" in clientEnv)
+      ? { ...clientEnv, TELO_REGISTRY_URL: registryUrl }
+      : clientEnv;
 
   // Respond as soon as the session is registered — BEFORE the backend starts.
   // `backend.start()` now spans the on-cluster image build and pod bring-up,
@@ -221,11 +281,12 @@ async function startSession(
   deps.backend
     .start({
       sessionId,
-      bundle: body.bundle,
+      bundle,
       entryRelativePath: entryRelative,
       env: sessionEnv,
       ports: body.ports ?? [],
-      config: body.config,
+      config,
+      selfContained: appEntry !== undefined,
       inspect: body.inspect ?? false,
       onStatus: (status) => deps.registry.emit(sessionId, { type: "status", status }),
       onProgress: (phase, message, done) =>
@@ -238,6 +299,8 @@ async function startSession(
       onDebug: (frame) => {
         if (isEventFrame(frame)) deps.registry.emit(sessionId, { type: "debug", frame });
       },
+      onReachability: (port, state) =>
+        deps.registry.emit(sessionId, { type: "reachability", port, state }),
       isUserStopped: () => entry.userStopped,
     })
     .then(async (session) => {

package/src/server.ts

@@ -3,8 +3,8 @@ import cors from "@fastify/cors";
 import websocket from "@fastify/websocket";
 
 import type { RunnerBackend } from "./backend.js";
-import type { RunnerCoreConfig } from "./config.js";
-import type { RunnerCapabilities, SessionConfig } from "./contract.js";
+import type { ResolvedRunnerApp, RunnerCoreConfig } from "./config.js";
+import type { RunnerAppDescriptor, RunnerCapabilities, SessionConfig } from "./contract.js";
 import { capabilitiesRoute } from "./routes/capabilities.js";
 import { healthRoute } from "./routes/health.js";
 import { ioRoute } from "./routes/io.js";
@@ -25,8 +25,13 @@ export interface ServerDeps {
   /** Runner's default registry URL, passed to workloads as TELO_REGISTRY_URL. */
   defaultRegistryUrl?: string;
   /** Backend config gate, enforced on `POST /v1/sessions` before the workload
-   *  starts (e.g. an `image` allowlist). Rejects with `400 invalid_config`. */
+   *  starts (e.g. an `image` allowlist). Rejects with `400 invalid_config`.
+   *  Not consulted for app sessions — their image comes from `apps`. */
   validateConfig?: (config: SessionConfig) => string | undefined;
+  /** Operator-predefined applications launchable by name (usually
+   *  `loadResolvedApps(process.env)`). Advertised on /v1/capabilities as
+   *  `apps` descriptors; the session route resolves and gates against it. */
+  apps?: Record<string, ResolvedRunnerApp>;
   registry?: SessionRegistry;
 }
 
@@ -58,13 +63,26 @@ export async function buildServer(deps: ServerDeps): Promise<ServerHandle> {
       replayBufferBytes: deps.config.replayBufferBytes,
     });
 
+  // The app catalog is injected into the served capabilities document here, so
+  // what /v1/capabilities advertises and what the session route accepts can
+  // never drift — both come from `deps.apps`.
+  const appDescriptors: RunnerAppDescriptor[] = Object.values(deps.apps ?? {}).map(
+    ({ name, title, description }) => ({ name, title, description }),
+  );
+  const withApps = (caps: RunnerCapabilities): RunnerCapabilities =>
+    appDescriptors.length > 0 ? { ...caps, apps: appDescriptors } : caps;
+  const capabilitiesGetter =
+    typeof deps.capabilities === "function"
+      ? () => withApps((deps.capabilities as () => RunnerCapabilities)())
+      : withApps(deps.capabilities);
+
   // Terms are stable across the process — resolve the capabilities once for them
   // even when `capabilities` is a getter (the route still re-resolves per request).
   const capabilitiesValue =
-    typeof deps.capabilities === "function" ? deps.capabilities() : deps.capabilities;
+    typeof capabilitiesGetter === "function" ? capabilitiesGetter() : capabilitiesGetter;
 
   await app.register(healthRoute(deps.version));
-  await app.register(capabilitiesRoute(deps.capabilities));
+  await app.register(capabilitiesRoute(capabilitiesGetter));
   await app.register(probeRoute({ backend: deps.backend }));
   await app.register(
     sessionsRoute({
@@ -76,6 +94,7 @@ export async function buildServer(deps: ServerDeps): Promise<ServerHandle> {
       // The capabilities document is the single source of the runner's terms;
       // the session route enforces what /v1/capabilities advertises.
       terms: capabilitiesValue.terms,
+      apps: deps.apps,
     }),
   );
   await app.register(ioRoute({ registry, corsOrigins: deps.config.corsOrigins }));