@nimbus-sh/core 0.1.0

package/src/runtime/port-registry.ts

@@ -0,0 +1,298 @@
+/**
+ * port-registry.ts — Maps virtual ports to facet stubs.
+ *
+ * When a facet calls http.createServer().listen(3000), it notifies the
+ * supervisor via SupervisorRPC.registerPort(3000). The supervisor stores
+ * the facet stub here. When the DO receives a request to /port/3000/*,
+ * it looks up the facet and forwards the request.
+ *
+ * Transport (audit C2):
+ *   The proxy forwards a real Request and returns a real Response.
+ *   Workers RPC natively transfers Request/Response values between
+ *   isolates with streaming bodies and flow control (they are NOT
+ *   structured-cloneable — RPC has its own transfer mechanism for
+ *   these types). Binary payloads (images, wasm, gzip, multipart
+ *   uploads, audio/video) go through byte-for-byte with no UTF-8
+ *   coercion or JSON envelope anywhere in the path.
+ *
+ *   Facet contract for handleHttpRequest:
+ *     async handleHttpRequest(request: Request): Promise<Response>
+ *
+ *   where `request.url` is the inner URL the user's HTTP server
+ *   expects (pathname + search, absolute against a synthetic origin),
+ *   `request.method` and application headers mirror the outer request,
+ *   Nimbus credentials/internal headers are removed, and
+ *   `request.body` is a ReadableStream (or null for GET/HEAD) that
+ *   the facet can consume once. The returned Response is returned
+ *   to the outer fetch as-is; its body is streamed directly.
+ */
+
+import { sanitizeUntrustedHeaders } from '../_shared/untrusted-request.js';
+import type { RouteableFacetTarget } from './os-contracts.js';
+
+export interface PortEntry {
+  port: number;
+  pid: number;
+  /**
+   * Facet stub exposing `handleHttpRequest(Request): Promise<Response>`.
+   * May be null when a facet has reserved a port but not yet wired up
+   * the request handler (see _rpcRegisterPort in nimbus-session.ts).
+   */
+  facetStub: RouteableFacetTarget | null;
+  registeredAt: number;
+}
+
+export class PortRegistry {
+  private ports = new Map<number, PortEntry>();
+  private facetStubsByPid = new Map<number, RouteableFacetTarget>();
+  private portWaitersByPid = new Map<number, Set<() => void>>();
+
+  /** Remember the available facet capabilities for a running process. */
+  bindFacetStub(pid: number, facetStub: unknown): void {
+    const target = routeableFacetTarget(facetStub);
+    if (!target) return;
+    this.facetStubsByPid.set(pid, target);
+    this.attachFacetStubByPid(pid, target);
+    this.notifyPortWaiters(pid);
+  }
+
+  /**
+   * Register a process as listening on a port. The route target comes from
+   * the pid's binding — one target per process, owned by whoever started it —
+   * so a port announced by the facet itself and one reserved by the spawn
+   * resolve to the same handler.
+   */
+  register(port: number, pid: number): void {
+    const target = this.facetStubsByPid.get(pid) ?? null;
+    this.ports.set(port, { port, pid, facetStub: target, registeredAt: Date.now() });
+    this.notifyPortWaiters(pid);
+  }
+
+  /** Unregister a port. */
+  unregister(port: number): boolean {
+    return this.ports.delete(port);
+  }
+
+  /** Unregister all ports owned by a specific PID. */
+  unregisterByPid(pid: number): number {
+    let count = 0;
+    for (const [port, entry] of this.ports) {
+      if (entry.pid === pid) {
+        this.ports.delete(port);
+        count++;
+      }
+    }
+    this.facetStubsByPid.delete(pid);
+    return count;
+  }
+
+  /** Look up a port entry. */
+  get(port: number): PortEntry | undefined {
+    return this.ports.get(port);
+  }
+
+  /** Attach a normalized route target to ports previously reserved by a PID. */
+  private attachFacetStubByPid(pid: number, target: RouteableFacetTarget): number[] {
+    const ports: number[] = [];
+    for (const entry of this.ports.values()) {
+      if (entry.pid !== pid || entry.facetStub) continue;
+      entry.facetStub = target;
+      ports.push(entry.port);
+    }
+    if (ports.length > 0) this.notifyPortWaiters(pid);
+    return ports;
+  }
+
+  getRouteablePortsByPid(pid: number): number[] {
+    return [...this.ports.values()]
+      .filter((entry) => entry.pid === pid && entry.facetStub)
+      .map((entry) => entry.port);
+  }
+
+  async waitForRouteablePortsByPid(pid: number, timeoutMs: number): Promise<number[]> {
+    const immediate = this.getRouteablePortsByPid(pid);
+    if (immediate.length > 0) return immediate;
+    await this.waitForPidPortChange(pid, timeoutMs);
+    return this.getRouteablePortsByPid(pid);
+  }
+
+  /** Check if a port is registered. */
+  has(port: number): boolean {
+    return this.ports.has(port);
+  }
+
+  /** Get all registered ports. */
+  getAll(): PortEntry[] {
+    return [...this.ports.values()];
+  }
+
+  /**
+   * Forward an HTTP request to the facet owning a port.
+   *
+   * Returns null if no facet is listening on this port (or if a port
+   * is registered but its stub is not yet attached — see PortEntry).
+   *
+   * The Request passed to the facet has a rewritten URL whose pathname
+   * is the inner path (without the `/port/<n>` prefix) and whose origin
+   * matches the outer request, so user code reading `request.url`
+   * sees a URL shape consistent with "my server is running at this
+   * port". Application headers and the body are forwarded; Nimbus
+   * credentials and internal routing headers are removed before crossing
+   * the user-code trust boundary. The body remains a ReadableStream so
+   * binary payloads aren't materialised in memory.
+   *
+   * Binary safety: Workers RPC transfers Request/Response values with
+   * their streaming bodies; it does not structured-clone them. No UTF-8
+   * round-trip occurs anywhere.
+   * A user-facet serving a PNG will return the exact same bytes the
+   * client receives.
+   */
+  async routeRequest(port: number, request: Request, pathname: string): Promise<Response | null> {
+    const entry = this.ports.get(port);
+    // Honour the documented contract: no entry at all → null, so callers
+    // report "no process listening". (Pre-fix this fell into the 501 below,
+    // which mislabelled a wiped/unregistered port as a half-registered one.)
+    if (!entry) return null;
+    // Some short-lived/foreground paths can reserve a port through
+    // SupervisorRPC.registerPort before a routeable WorkerEntrypoint
+    // exists. Explicit long-running processes (for example
+    // `node --watch server.js`) register a non-null facet stub and route
+    // below. For a null-stub reservation, return an honest 501 instead
+    // of a misleading "no process listening" 502.
+    if (!entry.facetStub) {
+      return new Response(
+        JSON.stringify({
+          error: 'port is registered but has no routeable facet handler',
+          port,
+        }),
+        {
+          status: 501,
+          headers: { 'Content-Type': 'application/json' },
+        },
+      );
+    }
+
+    try {
+      const outerUrl = new URL(request.url);
+      // Preserve query; replace the pathname with the inner path so
+      // the user's HTTP server sees its own URL shape. (Fragments
+      // never make it onto the wire, so there's nothing to forward.)
+      const innerUrl = new URL(pathname + outerUrl.search, outerUrl.origin);
+
+      // Rebuild a Request targeting the inner URL. Body is forwarded as
+      // a stream — we do NOT await `.text()`/`.arrayBuffer()`, which
+      // would corrupt any binary payload and block large uploads.
+      //
+      // Construct via (url, init) so we can override the URL while
+      // inheriting method/headers/body from the original. For GET/HEAD
+      // we must omit `body` entirely — the Request constructor throws
+      // if a body is supplied on those methods.
+      const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
+      const headers = new Headers(request.headers);
+      sanitizeUntrustedHeaders(headers);
+
+      headers.set('X-Nimbus-Port', String(port));
+      // `duplex: 'half'` is required by workerd when body is a
+      // ReadableStream — otherwise `new Request(…)` throws. It's not
+      // part of the published @cloudflare/workers-types RequestInit,
+      // so extend the type locally rather than casting the whole
+      // init — that keeps typos in other fields caught by the compiler.
+      const init: RequestInit & { duplex?: 'half' } = {
+        method: request.method,
+        headers,
+        body: hasBody ? request.body : undefined,
+      };
+      if (hasBody) init.duplex = 'half';
+      const forwarded = new Request(innerUrl.toString(), init);
+
+      // RPC: the facet receives the Request and returns a Response.
+      // Both cross the isolate boundary via Workers RPC's native
+      // Request/Response transport — bytes are streamed with
+      // flow-control, never materialised.
+      const response: Response = await entry.facetStub.handleHttpRequest(forwarded);
+
+      if (!(response instanceof Response)) {
+        // Defensive: if a facet ever returns something else (JSON
+        // envelope, string, etc.), treat it as a 502 so the client
+        // sees a clear signal rather than a confusing surprise.
+        return new Response(
+          JSON.stringify({
+            error: 'port proxy: facet returned non-Response value',
+            type: typeof response,
+          }),
+          {
+            status: 502,
+            headers: { 'Content-Type': 'application/json' },
+          },
+        );
+      }
+
+      // Return the facet's Response as-is. Body is streamed; headers,
+      // status, and status-text pass through unchanged. We do NOT
+      // inject Access-Control-Allow-Origin — a port proxy forwards
+      // whatever CORS policy the user's HTTP server chose (audit C3
+      // discourages gratuitous wildcards on non-static routes).
+      return response;
+    } catch (error: unknown) {
+      // Server-side triage — users see only the 502 body, operators
+      // see the full error + stack in Worker logs.
+      console.error('[port-registry] routeRequest failed for port', port, ':', error);
+      return new Response(
+        JSON.stringify({ error: errorMessage(error) }),
+        {
+          status: 502,
+          headers: { 'Content-Type': 'application/json' },
+        },
+      );
+    }
+  }
+
+  get stats() {
+    return {
+      activePorts: this.ports.size,
+      ports: [...this.ports.entries()].map(([port, e]) => ({ port, pid: e.pid })),
+    };
+  }
+
+  private waitForPidPortChange(pid: number, timeoutMs: number): Promise<void> {
+    return new Promise((resolve) => {
+      let done = false;
+      let timeout: ReturnType<typeof setTimeout>;
+      const finish = () => {
+        if (done) return;
+        done = true;
+        clearTimeout(timeout);
+        const waiters = this.portWaitersByPid.get(pid);
+        if (waiters) {
+          waiters.delete(finish);
+          if (waiters.size === 0) this.portWaitersByPid.delete(pid);
+        }
+        resolve();
+      };
+      timeout = setTimeout(finish, timeoutMs);
+      const waiters = this.portWaitersByPid.get(pid) || new Set<() => void>();
+      waiters.add(finish);
+      this.portWaitersByPid.set(pid, waiters);
+    });
+  }
+
+  private notifyPortWaiters(pid: number): void {
+    const waiters = this.portWaitersByPid.get(pid);
+    if (!waiters) return;
+    this.portWaitersByPid.delete(pid);
+    for (const resolve of waiters) resolve();
+  }
+}
+
+function routeableFacetTarget(value: unknown): RouteableFacetTarget | null {
+  if ((typeof value !== 'object' && typeof value !== 'function') || value === null) return null;
+  const method = Reflect.get(value, 'fetch') || Reflect.get(value, 'handleHttpRequest');
+  if (typeof method !== 'function') return null;
+  return {
+    handleHttpRequest: method.bind(value),
+  };
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/runtime/process-input-routing.ts

@@ -0,0 +1,92 @@
+/**
+ * process-input-routing.ts — the single zod-validated protocol path for
+ * process-terminal client frames (`input` / `stdin-end` / `resize` /
+ * `signal`). Both WebSocket surfaces (the `/api/logs/<pid>` upgrade
+ * handler and the hibernatable `webSocketMessage` dispatcher) and the
+ * programmatic SDK RPCs route through these helpers.
+ */
+
+import type { SessionProcessSupervisor } from './session-process-supervisor.js';
+import type { ProcessLogClientFrame } from './process-io-protocol.js';
+import {
+  parseProcessPid,
+  parseProcessSignalName,
+  parseProcessTerminalSize,
+} from './process-io-protocol.js';
+
+/** The slice of the process supervisor the frame router drives. */
+export type ProcessInputController = Pick<
+  SessionProcessSupervisor,
+  'writeInput' | 'endInput' | 'resize' | 'signal'
+>;
+
+function rejectedPid(value: unknown): number {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : 0;
+}
+
+export async function writeProcessInput(
+  processes: ProcessInputController,
+  pid: number,
+  data: string,
+): Promise<{ ok: boolean; pid: number }> {
+  const n = parseProcessPid(pid);
+  if (n === null) return { ok: false, pid: rejectedPid(pid) };
+  const text = String(data ?? '');
+  const queued = processes.writeInput(n, text);
+  return { ok: queued.ok, pid: n };
+}
+
+export async function endProcessInput(
+  processes: ProcessInputController,
+  pid: number,
+): Promise<{ ok: boolean; pid: number }> {
+  const n = parseProcessPid(pid);
+  if (n === null) return { ok: false, pid: rejectedPid(pid) };
+  processes.endInput(n);
+  return { ok: true, pid: n };
+}
+
+export async function resizeProcess(
+  processes: ProcessInputController,
+  pid: number,
+  columns: number,
+  rows: number,
+): Promise<{ ok: boolean; pid: number }> {
+  const n = parseProcessPid(pid);
+  if (n === null) return { ok: false, pid: rejectedPid(pid) };
+  const size = parseProcessTerminalSize({ columns, rows });
+  if (!size) return { ok: false, pid: n };
+  const resized = processes.resize(n, size.columns, size.rows);
+  return { ok: resized.ok, pid: n };
+}
+
+export async function signalProcess(
+  processes: ProcessInputController,
+  pid: number,
+  signal: string,
+): Promise<{ ok: boolean; pid: number }> {
+  const n = parseProcessPid(pid);
+  if (n === null) return { ok: false, pid: rejectedPid(pid) };
+  const parsed = parseProcessSignalName(signal);
+  if (!parsed) return { ok: false, pid: n };
+  const signaled = processes.signal(n, parsed);
+  return { ok: signaled.ok, pid: n };
+}
+
+export async function applyProcessClientFrame(
+  processes: ProcessInputController,
+  pid: number,
+  frame: ProcessLogClientFrame,
+): Promise<{ ok: boolean; pid: number; type: ProcessLogClientFrame['type'] }> {
+  if (frame.type === 'input') {
+    return { ...(await writeProcessInput(processes, pid, frame.data)), type: frame.type };
+  }
+  if (frame.type === 'stdin-end') {
+    return { ...(await endProcessInput(processes, pid)), type: frame.type };
+  }
+  if (frame.type === 'resize') {
+    return { ...(await resizeProcess(processes, pid, frame.columns, frame.rows)), type: frame.type };
+  }
+  return { ...(await signalProcess(processes, pid, frame.signal)), type: frame.type };
+}

package/src/runtime/process-input.ts

@@ -0,0 +1,148 @@
+import type { ProcessSignalName } from './process-io-protocol.js';
+
+interface InputWaiter {
+  resolve: (packet: ProcessInputPacket) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export interface ProcessInputPacket {
+  data: string;
+  ended: boolean;
+  resize?: { columns: number; rows: number };
+  signal?: ProcessSignalName;
+}
+
+interface InputState {
+  packets: ProcessInputPacket[];
+  closed: boolean;
+  bytes: number;
+  waiters: InputWaiter[];
+  columns: number;
+  rows: number;
+}
+
+export interface ProcessInputStoreOptions {
+  maxQueuedBytes?: number;
+}
+
+const DEFAULT_MAX_QUEUED_BYTES = 256 * 1024;
+
+function isValidPid(pid: number): boolean {
+  return Number.isSafeInteger(pid) && pid > 0;
+}
+
+export class ProcessInputStore {
+  private readonly maxQueuedBytes: number;
+  private pids = new Map<number, InputState>();
+
+  constructor(options: ProcessInputStoreOptions = {}) {
+    this.maxQueuedBytes = options.maxQueuedBytes ?? DEFAULT_MAX_QUEUED_BYTES;
+  }
+
+  private createState(): InputState {
+    return { packets: [], closed: false, bytes: 0, waiters: [], columns: 80, rows: 24 };
+  }
+
+  open(pid: number): void {
+    if (!isValidPid(pid) || this.pids.has(pid)) return;
+    this.pids.set(pid, this.createState());
+  }
+
+  has(pid: number): boolean {
+    return this.pids.has(pid);
+  }
+
+  write(pid: number, data: string): { ok: boolean } {
+    if (!isValidPid(pid)) return { ok: false };
+    const state = this.pids.get(pid);
+    if (!state) return { ok: false };
+    if (state.closed) return { ok: false };
+
+    const text = String(data);
+    if (state.bytes + text.length > this.maxQueuedBytes) return { ok: false };
+
+    return this.enqueue(state, { data: text, ended: false }, text.length);
+  }
+
+  resize(pid: number, columns: number, rows: number): { ok: boolean } {
+    if (!isValidPid(pid)) return { ok: false };
+    const state = this.pids.get(pid);
+    if (!state) return { ok: false };
+    if (state.closed) return { ok: false };
+    state.columns = columns;
+    state.rows = rows;
+    return this.enqueue(state, { data: '', ended: false, resize: { columns, rows } }, 0);
+  }
+
+  signal(pid: number, signal: ProcessSignalName): { ok: boolean } {
+    if (!isValidPid(pid)) return { ok: false };
+    const state = this.pids.get(pid);
+    if (!state) return { ok: false };
+    if (state.closed) return { ok: false };
+    return this.enqueue(state, { data: '', ended: false, signal }, 0);
+  }
+
+  terminalSize(pid: number): { columns: number; rows: number } | null {
+    const state = this.pids.get(pid);
+    return state ? { columns: state.columns, rows: state.rows } : null;
+  }
+
+  private enqueue(state: InputState, packet: ProcessInputPacket, bytes: number): { ok: boolean } {
+    const waiter = state.waiters.shift();
+    if (waiter) {
+      clearTimeout(waiter.timer);
+      waiter.resolve(packet);
+      return { ok: true };
+    }
+
+    const last = state.packets[state.packets.length - 1];
+    if (packet.resize && last?.resize && !last.data && !last.ended && !last.signal) {
+      state.packets[state.packets.length - 1] = packet;
+      return { ok: true };
+    }
+
+    state.packets.push(packet);
+    state.bytes += bytes;
+    return { ok: true };
+  }
+
+  end(pid: number): void {
+    const state = this.pids.get(pid);
+    if (!state || state.closed) return;
+    state.closed = true;
+    for (const waiter of state.waiters.splice(0)) {
+      clearTimeout(waiter.timer);
+      waiter.resolve({ data: '', ended: true });
+    }
+  }
+
+  close(pid: number): void {
+    this.end(pid);
+    this.pids.delete(pid);
+  }
+
+  async read(pid: number, waitMs = 1000): Promise<ProcessInputPacket> {
+    if (!isValidPid(pid)) return { data: '', ended: true };
+    const state = this.pids.get(pid);
+    if (!state) return { data: '', ended: true };
+
+    const next = state.packets.shift();
+    if (next !== undefined) {
+      state.bytes -= next.data.length;
+      return next;
+    }
+    if (state.closed) return { data: '', ended: true };
+
+    return new Promise((resolve) => {
+      const waiter: InputWaiter = {
+        resolve,
+        timer: setTimeout(() => {
+          const idx = state.waiters.indexOf(waiter);
+          if (idx >= 0) state.waiters.splice(idx, 1);
+          resolve({ data: '', ended: false });
+        }, Math.max(0, Math.min(waitMs, 5000))),
+      };
+      state.waiters.push(waiter);
+    });
+  }
+}

package/src/runtime/process-io-protocol.ts

@@ -0,0 +1,97 @@
+import { z } from 'zod/v4';
+
+const ProcessPidSchema = z.coerce.number().int().positive().safe();
+
+const ProcessTerminalSizeSchema = z.object({
+  columns: z.coerce.number().int().min(1).max(1000),
+  rows: z.coerce.number().int().min(1).max(1000),
+});
+
+export const ProcessSignalNameSchema = z.enum([
+  'SIGHUP',
+  'SIGINT',
+  'SIGQUIT',
+  'SIGILL',
+  'SIGTRAP',
+  'SIGABRT',
+  'SIGBUS',
+  'SIGFPE',
+  'SIGKILL',
+  'SIGUSR1',
+  'SIGSEGV',
+  'SIGUSR2',
+  'SIGPIPE',
+  'SIGALRM',
+  'SIGTERM',
+  'SIGCHLD',
+  'SIGCONT',
+  'SIGSTOP',
+  'SIGTSTP',
+  'SIGTTIN',
+  'SIGTTOU',
+  'SIGURG',
+  'SIGXCPU',
+  'SIGXFSZ',
+  'SIGVTALRM',
+  'SIGPROF',
+  'SIGWINCH',
+  'SIGIO',
+  'SIGPWR',
+  'SIGSYS',
+]);
+
+export type ProcessTerminalSize = z.infer<typeof ProcessTerminalSizeSchema>;
+export type ProcessSignalName = z.infer<typeof ProcessSignalNameSchema>;
+
+export function parseProcessPid(value: unknown): number | null {
+  const parsed = ProcessPidSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}
+
+export function parseProcessTerminalSize(value: unknown): ProcessTerminalSize | null {
+  const parsed = ProcessTerminalSizeSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}
+
+export function parseProcessSignalName(value: string): ProcessSignalName | null {
+  const parsed = ProcessSignalNameSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}
+
+const ProcessInputFrameSchema = z.object({
+  type: z.literal('input'),
+  data: z.unknown().optional().transform((value) => value == null ? '' : String(value)),
+}).passthrough();
+
+const ProcessStdinEndFrameSchema = z.object({
+  type: z.literal('stdin-end'),
+}).passthrough();
+
+const ProcessResizeFrameSchema = z.object({
+  type: z.literal('resize'),
+}).merge(ProcessTerminalSizeSchema).passthrough();
+
+const ProcessSignalFrameSchema = z.object({
+  type: z.literal('signal'),
+  signal: ProcessSignalNameSchema,
+}).passthrough();
+
+export const ProcessLogClientFrameSchema = z.discriminatedUnion('type', [
+  ProcessInputFrameSchema,
+  ProcessStdinEndFrameSchema,
+  ProcessResizeFrameSchema,
+  ProcessSignalFrameSchema,
+]);
+
+export type ProcessLogClientFrame = z.infer<typeof ProcessLogClientFrameSchema>;
+
+export function parseProcessLogClientFrame(raw: string): ProcessLogClientFrame | null {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const parsed = ProcessLogClientFrameSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}