@telorun/runner-core 0.7.0 → 0.8.1

package/src/routes/session-start.ts

@@ -0,0 +1,174 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+
+import { isEventFrame } from "@telorun/debug-wire";
+import type { RunnerBackend } from "../backend.js";
+import {
+  ACCEPTED_TERMS_HEADER,
+  SessionStartError,
+  type PortMapping,
+  type RunBundle,
+  type RunnerTerms,
+  type SessionConfig,
+} from "../contract.js";
+import { generateSessionId } from "../session/session-id.js";
+import { SessionLimitError, type SessionRegistry } from "../session/registry.js";
+
+/** JSON Schema for the `ports` body field, shared by every session-creating
+ *  route so bundle and app sessions validate port mappings identically. */
+export const portsSchema = {
+  type: "array",
+  items: {
+    type: "object",
+    required: ["port", "protocol"],
+    properties: {
+      port: { type: "integer", minimum: 1, maximum: 65535 },
+      protocol: { type: "string", enum: ["tcp", "udp"] },
+    },
+  },
+} as const;
+
+/**
+ * Terms enforcement shared by every session-creating route — the server is the
+ * source of truth, so a client that skips the editor gate still can't start a
+ * workload without acknowledging the current terms version. Sends the 428 and
+ * returns false when the gate is closed.
+ */
+export function enforceTerms(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  terms: RunnerTerms | undefined,
+): boolean {
+  if (!terms) return true;
+  const raw = req.headers[ACCEPTED_TERMS_HEADER];
+  const accepted = Array.isArray(raw) ? raw[0] : raw;
+  if (accepted !== terms.version) {
+    reply.code(428).send({ error: "terms_required", terms });
+    return false;
+  }
+  return true;
+}
+
+/** Dependencies the shared session-creation leaf needs, independent of which
+ *  route drives it. Both `SessionsRouteDeps` and `AppsRouteDeps` satisfy it. */
+export interface WorkloadStartDeps {
+  backend: RunnerBackend;
+  registry: SessionRegistry;
+  /** The runner's own default registry URL, surfaced to the workload as
+   *  TELO_REGISTRY_URL when the request doesn't override it. */
+  defaultRegistryUrl?: string;
+}
+
+export interface WorkloadStartArgs {
+  bundle: RunBundle;
+  entryRelativePath: string;
+  env: Record<string, string>;
+  ports: PortMapping[];
+  config: SessionConfig;
+  selfContained: boolean;
+  inspect: boolean;
+}
+
+/**
+ * The session-creation leaf shared by `POST /v1/sessions` (bundle sessions) and
+ * `POST /v1/apps/:name/sessions` (operator-predefined apps): registers the
+ * session, responds 201 with the shared `/v1/sessions/:id/events` stream URL,
+ * and starts the workload in the background. Whatever door a session was
+ * created through, everything after creation lives in the one session
+ * collection (status, DELETE, events, io).
+ */
+export async function startWorkloadSession(
+  app: FastifyInstance,
+  deps: WorkloadStartDeps,
+  args: WorkloadStartArgs,
+  reply: FastifyReply,
+): Promise<void> {
+  const sessionId = generateSessionId();
+
+  let entry: ReturnType<SessionRegistry["register"]>;
+  try {
+    entry = deps.registry.register({ sessionId });
+  } catch (err) {
+    if (err instanceof SessionLimitError) {
+      reply.code(409).send({ error: "too_many_sessions", message: err.message });
+      return;
+    }
+    throw err;
+  }
+
+  // Surface a TELO_REGISTRY_URL to the workload so the telo CLI inside picks
+  // 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 = args.config.registryUrl?.trim() || undefined;
+  const registryUrl = configRegistryUrl ?? deps.defaultRegistryUrl;
+  const sessionEnv =
+    registryUrl && !("TELO_REGISTRY_URL" in args.env)
+      ? { ...args.env, TELO_REGISTRY_URL: registryUrl }
+      : args.env;
+
+  // 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,
+  // which can take seconds-to-minutes; awaiting it here would hide the event
+  // stream until the workload is already up, so the client never sees build /
+  // provision / boot progress live. Returning the streamUrl first lets the
+  // client connect immediately; start runs in the background and its progress,
+  // output, and terminal status flow over the stream.
+  reply.code(201).send({
+    sessionId,
+    streamUrl: `/v1/sessions/${sessionId}/events`,
+    createdAt: entry.createdAt.toISOString(),
+  });
+
+  deps.backend
+    .start({
+      sessionId,
+      bundle: args.bundle,
+      entryRelativePath: args.entryRelativePath,
+      env: sessionEnv,
+      ports: args.ports,
+      config: args.config,
+      selfContained: args.selfContained,
+      inspect: args.inspect,
+      onStatus: (status) => deps.registry.emit(sessionId, { type: "status", status }),
+      onProgress: (phase, message, done) =>
+        deps.registry.emit(sessionId, { type: "progress", phase, message, done }),
+      onOutput: (chunk) => deps.registry.pushBytes(sessionId, chunk),
+      // Relay only kernel *event* frames to the client. stdout/stderr already
+      // arrive over the byte channel (onOutput), so forwarding log frames would
+      // double the traffic and let log spam evict lifecycle events from the
+      // byte-capped replay buffer. The editor discards relayed logs anyway.
+      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) => {
+      entry.session = session;
+      // Pre-start DELETE race: a DELETE received during backend.start (e.g.
+      // while an image build was running) can't stop a workload that didn't
+      // exist yet — it set userStopped and returned 204. Now that the workload
+      // is live, honor the earlier DELETE.
+      if (entry.userStopped) {
+        try {
+          await session.stop();
+        } catch (err) {
+          app.log.warn({ err, sessionId }, "failed to stop after race with pre-start DELETE");
+        }
+      }
+    })
+    .catch((err) => {
+      // The 201 is already sent, so a start failure surfaces as a terminal
+      // `failed` status on the stream (the registry schedules eviction on a
+      // terminal status; the SSE channel delivers it, then closes).
+      const message =
+        err instanceof SessionStartError
+          ? `${err.stage}: ${err.message}`
+          : err instanceof Error
+            ? err.message
+            : String(err);
+      app.log.error({ err, sessionId }, "session start failed");
+      deps.registry.emit(sessionId, { type: "status", status: { kind: "failed", message } });
+    });
+}

package/src/routes/sessions.ts

@@ -1,19 +1,10 @@
 import type { FastifyInstance, FastifyPluginAsync, FastifyReply } from "fastify";
 
-import { isEventFrame } from "@telorun/debug-wire";
 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 type { RunnerTerms, SessionConfig, StartSessionRequest } from "../contract.js";
 import { BundlePathError, normalizeBundlePath } from "../session/bundle-path.js";
-import { generateSessionId } from "../session/session-id.js";
-import { SessionLimitError, type SessionRegistry } from "../session/registry.js";
+import type { SessionRegistry } from "../session/registry.js";
+import { enforceTerms, portsSchema, startWorkloadSession } from "./session-start.js";
 import { streamSessionEvents } from "../sse/channel.js";
 
 export interface SessionsRouteDeps {
@@ -26,10 +17,6 @@ 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
@@ -37,13 +24,10 @@ 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: ["env"],
+  required: ["bundle", "env", "config"],
   properties: {
-    app: { type: "string", minLength: 1 },
     bundle: {
       type: "object",
       required: ["entryRelativePath", "files"],
@@ -66,17 +50,7 @@ const startBodySchema = {
       type: "object",
       additionalProperties: { type: "string" },
     },
-    ports: {
-      type: "array",
-      items: {
-        type: "object",
-        required: ["port", "protocol"],
-        properties: {
-          port: { type: "integer", minimum: 1, maximum: 65535 },
-          protocol: { type: "string", enum: ["tcp", "udp"] },
-        },
-      },
-    },
+    ports: portsSchema,
     config: {
       type: "object",
       required: ["image", "pullPolicy"],
@@ -96,17 +70,7 @@ export function sessionsRoute(deps: SessionsRouteDeps): FastifyPluginAsync {
       "/v1/sessions",
       { schema: { body: startBodySchema } },
       async (req, reply) => {
-        // Terms enforcement — the server is the source of truth, so a client that
-        // skips the editor gate still can't start a session without acknowledging
-        // the current terms version.
-        if (deps.terms) {
-          const raw = req.headers[ACCEPTED_TERMS_HEADER];
-          const accepted = Array.isArray(raw) ? raw[0] : raw;
-          if (accepted !== deps.terms.version) {
-            reply.code(428).send({ error: "terms_required", terms: deps.terms });
-            return;
-          }
-        }
+        if (!enforceTerms(req, reply, deps.terms)) return;
         return startSession(app, deps, req.body, reply);
       },
     );
@@ -164,170 +128,44 @@ async function startSession(
   body: StartSessionRequest,
   reply: FastifyReply,
 ): 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;
-  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;
-    }
-
-    // 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;
-      }
-    }
-  }
-
-  let entry: ReturnType<SessionRegistry["register"]>;
   try {
-    entry = deps.registry.register({ sessionId });
+    // 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 SessionLimitError) {
-      reply.code(409).send({ error: "too_many_sessions", message: err.message });
+    if (err instanceof BundlePathError) {
+      reply.code(400).send({ error: "invalid_bundle", message: err.message });
       return;
     }
     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: 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 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,
-  // which can take seconds-to-minutes; awaiting it here would hide the event
-  // stream until the workload is already up, so the client never sees build /
-  // provision / boot progress live. Returning the streamUrl first lets the
-  // client connect immediately; start runs in the background and its progress,
-  // output, and terminal status flow over the stream.
-  reply.code(201).send({
-    sessionId,
-    streamUrl: `/v1/sessions/${sessionId}/events`,
-    createdAt: entry.createdAt.toISOString(),
-  });
+  // 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;
+    }
+  }
 
-  deps.backend
-    .start({
-      sessionId,
-      bundle,
+  return startWorkloadSession(
+    app,
+    deps,
+    {
+      bundle: body.bundle,
       entryRelativePath: entryRelative,
-      env: sessionEnv,
+      env: body.env,
       ports: body.ports ?? [],
-      config,
-      selfContained: appEntry !== undefined,
+      config: body.config,
+      selfContained: false,
       inspect: body.inspect ?? false,
-      onStatus: (status) => deps.registry.emit(sessionId, { type: "status", status }),
-      onProgress: (phase, message, done) =>
-        deps.registry.emit(sessionId, { type: "progress", phase, message, done }),
-      onOutput: (chunk) => deps.registry.pushBytes(sessionId, chunk),
-      // Relay only kernel *event* frames to the client. stdout/stderr already
-      // arrive over the byte channel (onOutput), so forwarding log frames would
-      // double the traffic and let log spam evict lifecycle events from the
-      // byte-capped replay buffer. The editor discards relayed logs anyway.
-      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) => {
-      entry.session = session;
-      // Pre-start DELETE race: a DELETE received during backend.start (e.g.
-      // while an image build was running) can't stop a workload that didn't
-      // exist yet — it set userStopped and returned 204. Now that the workload
-      // is live, honor the earlier DELETE.
-      if (entry.userStopped) {
-        try {
-          await session.stop();
-        } catch (err) {
-          app.log.warn({ err, sessionId }, "failed to stop after race with pre-start DELETE");
-        }
-      }
-    })
-    .catch((err) => {
-      // The 201 is already sent, so a start failure surfaces as a terminal
-      // `failed` status on the stream (the registry schedules eviction on a
-      // terminal status; the SSE channel delivers it, then closes).
-      const message =
-        err instanceof SessionStartError
-          ? `${err.stage}: ${err.message}`
-          : err instanceof Error
-            ? err.message
-            : String(err);
-      app.log.error({ err, sessionId }, "session start failed");
-      deps.registry.emit(sessionId, { type: "status", status: { kind: "failed", message } });
-    });
+    },
+    reply,
+  );
 }

package/src/server.ts

@@ -5,6 +5,7 @@ import websocket from "@fastify/websocket";
 import type { RunnerBackend } from "./backend.js";
 import type { ResolvedRunnerApp, RunnerCoreConfig } from "./config.js";
 import type { RunnerAppDescriptor, RunnerCapabilities, SessionConfig } from "./contract.js";
+import { appsRoute } from "./routes/apps.js";
 import { capabilitiesRoute } from "./routes/capabilities.js";
 import { healthRoute } from "./routes/health.js";
 import { ioRoute } from "./routes/io.js";
@@ -30,7 +31,8 @@ export interface ServerDeps {
   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` descriptors; sessions of them are created via
+   *  `POST /v1/apps/:name/sessions`. */
   apps?: Record<string, ResolvedRunnerApp>;
   registry?: SessionRegistry;
 }
@@ -92,7 +94,15 @@ export async function buildServer(deps: ServerDeps): Promise<ServerHandle> {
       defaultRegistryUrl: deps.defaultRegistryUrl,
       validateConfig: deps.validateConfig,
       // The capabilities document is the single source of the runner's terms;
-      // the session route enforces what /v1/capabilities advertises.
+      // every session-creating route enforces what /v1/capabilities advertises.
+      terms: capabilitiesValue.terms,
+    }),
+  );
+  await app.register(
+    appsRoute({
+      backend: deps.backend,
+      registry,
+      defaultRegistryUrl: deps.defaultRegistryUrl,
       terms: capabilitiesValue.terms,
       apps: deps.apps,
     }),