@openlup/platform 0.0.0 → 0.15.0

package/src/http/deadline.ts

@@ -0,0 +1,117 @@
+// Bounded request/response lifecycle for the Node HTTP adapter.
+//
+// This owns transport cancellation only. It gives handlers a cooperative
+// AbortSignal, but cannot roll back downstream work that ignores it.
+
+import type { HttpRequest, HttpResponse } from "./types.js";
+
+export const NODE_HTTP_TIMEOUT_CODE = "NODE_HTTP_TIMEOUT";
+
+type Destroyable = { destroy?: (error?: Error) => void };
+type Evented = { once?: (event: string, listener: () => void) => unknown; removeListener?: (event: string, listener: () => void) => unknown };
+type WritableResponse = HttpResponse & {
+  write?: (...args: unknown[]) => boolean;
+  writeHead?: (...args: unknown[]) => unknown;
+  end?: (...args: unknown[]) => unknown;
+  setHeader?: (...args: unknown[]) => unknown;
+};
+
+export interface HttpDeadlineOptions {
+  req: HttpRequest;
+  res: HttpResponse;
+  durationMs: number;
+  run: () => Promise<unknown> | unknown;
+  onLateError?: (error: unknown) => void;
+}
+
+/**
+ * Run one Node HTTP admission from the instant before lazy loading/adaptation.
+ *
+ * A timeout before headers commit gets one minimal JSON 504. After headers are
+ * committed we cannot change the status safely, so the response is destroyed.
+ * The invocation promise remains observed, preventing a late rejection from
+ * becoming an unhandled rejection or a second response.
+ */
+export async function runWithHttpDeadline(options: HttpDeadlineOptions): Promise<void> {
+  const { req, res, durationMs, run, onLateError } = options;
+  if (!Number.isSafeInteger(durationMs) || durationMs <= 0 || durationMs > 2_147_483_647) {
+    throw new Error("invalid_node_http_deadline");
+  }
+
+  const controller = new AbortController();
+  // Node 24 exposes IncomingMessage.signal as a getter without a setter. Keep
+  // that host-native property untouched and use the portable adapter seam.
+  req.abortSignal = controller.signal;
+  const eventedReq = req as HttpRequest & Evented;
+  const eventedRes = res as HttpResponse & Evented;
+  const abortForClose = () => controller.abort();
+  eventedReq.once?.("aborted", abortForClose);
+  eventedRes.once?.("close", abortForClose);
+
+  let expired = false;
+  let finishTimeout: (() => void) | undefined;
+  const timeout = new Promise<void>((resolve) => { finishTimeout = resolve; });
+  const timer = setTimeout(() => {
+    expired = true;
+    controller.abort();
+    if (res.destroyed || res.writableEnded) {
+      destroyInput(req);
+      return finishTimeout?.();
+    }
+    if (!res.headersSent && !res.writableEnded) {
+      closeInputAfterResponse(req, res);
+      res.statusCode = 504;
+      res.setHeader("content-type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({ ok: false, error: { code: NODE_HTTP_TIMEOUT_CODE, message: "Request timed out" } }));
+      sealLateWrites(res);
+    } else if (!res.writableEnded) {
+      sealLateWrites(res);
+      (res as HttpResponse & Destroyable).destroy?.();
+      destroyInput(req);
+    }
+    finishTimeout?.();
+  }, durationMs);
+
+  const invocation = Promise.resolve().then(run);
+  // Keep a late completion/rejection observed after timeout. It must never get a
+  // chance to write a second envelope, and its raw value is not client output.
+  void invocation.catch((error) => {
+    if (expired) onLateError?.(error);
+  });
+
+  try {
+    await Promise.race([invocation.then(() => undefined), timeout]);
+  } finally {
+    clearTimeout(timer);
+    eventedReq.removeListener?.("aborted", abortForClose);
+    eventedRes.removeListener?.("close", abortForClose);
+  }
+}
+
+/** Send a response before closing its request input, so the status is deliverable. */
+export function closeInputAfterResponse(req: HttpRequest, res: HttpResponse): void {
+  const evented = res as HttpResponse & Evented;
+  let closed = false;
+  const destroy = () => {
+    if (closed) return;
+    closed = true;
+    evented.removeListener?.("finish", destroy);
+    evented.removeListener?.("close", destroy);
+    destroyInput(req);
+  };
+  evented.once?.("finish", destroy);
+  evented.once?.("close", destroy);
+}
+
+function destroyInput(req: HttpRequest): void {
+  (req as HttpRequest & Destroyable).destroy?.();
+}
+
+/** Refuse late handler writes after a deadline response has committed. */
+function sealLateWrites(res: HttpResponse): void {
+  const mutable = res as WritableResponse;
+  mutable.write = () => false;
+  mutable.writeHead = () => mutable;
+  mutable.end = () => mutable;
+  mutable.setHeader = () => mutable;
+}

package/src/http/index.ts

@@ -0,0 +1,36 @@
+export type { EntrypointLoader, HttpHandler, HttpRequest, HttpResponse } from "./types.js";
+export {
+  DEFAULT_NODE_BUFFERED_BODY_LIMIT_BYTES,
+  NodeRequestAbortedError,
+  NodeRequestBodyTooLargeError,
+  adaptRequest,
+  decorateRequest,
+  decorateResponse,
+  isRawStreamEntrypoint,
+  isWebhookPath,
+  pathnameOf,
+} from "./requestAdapter.js";
+export {
+  NODE_HTTP_TIMEOUT_CODE,
+  closeInputAfterResponse,
+  runWithHttpDeadline,
+  type HttpDeadlineOptions,
+} from "./deadline.js";
+export {
+  applySecurityHeaders,
+  contentTypeFor,
+  looksLikeAsset,
+  serveSpaStatic,
+  type NodeSecurityHeaderPolicy,
+  type StaticAssetReader,
+} from "./security.js";
+export { createDistStaticReader } from "./staticAssets.js";
+export {
+  createNodeHttpRuntime,
+  createRequestHandler,
+  type HttpEntrypointRegistration,
+  type HttpPathEntrypoint,
+  type NodeCsrFallback,
+  type NodeHttpRuntimeOptions,
+  type NodeLegacyRedirect,
+} from "./runtime.js";

package/src/http/requestAdapter.ts

@@ -0,0 +1,215 @@
+// Node request/response adaptation to the hosted-function request shape for the HttpRuntimePort.
+//
+// Owns the RAW-BODY INVARIANT: every buffered request gets the exact bytes re-exposed as an
+// async-iterable (so raw-body signature verification works for ANY route, including ones outside a
+// `/webhooks/` segment) while still setting a parsed JSON req.body; stream-first standalone
+// entrypoints keep their live stream and NO req.body.
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { HttpRequest, HttpResponse } from "./types.js";
+
+export const DEFAULT_NODE_BUFFERED_BODY_LIMIT_BYTES = 1_048_576;
+
+export class NodeRequestBodyTooLargeError extends Error {
+  constructor() {
+    super("node_request_body_too_large");
+  }
+}
+
+export class NodeRequestAbortedError extends Error {
+  constructor() {
+    super("node_request_aborted");
+  }
+}
+
+/** A path is a webhook iff it contains a `/webhooks/` segment. */
+export function isWebhookPath(pathname: string): boolean {
+  return pathname.includes("/webhooks/");
+}
+
+/**
+ * The PLATFORM's stream-first standalone entrypoints: they read the raw stream
+ * themselves, so the runtime must never pre-parse their body.
+ *
+ * A deployment's own stream-first endpoint is NOT listed here. It declares
+ * `rawStream: true` on its `HttpEntrypointRegistration` and the runtime passes that
+ * decision to `adaptRequest` directly — which is what stops this publishable list
+ * from having to name a path only that deployment owns.
+ */
+export function isRawStreamEntrypoint(pathname: string): boolean {
+  return pathname === "/api/csp-report";
+}
+
+export function pathnameOf(req: IncomingMessage): string {
+  return new URL(req.url ?? "/", "http://node.local").pathname;
+}
+
+function parseQuery(req: IncomingMessage): Record<string, string | string[] | undefined> {
+  const url = new URL(req.url ?? "/", "http://node.local");
+  const query: Record<string, string | string[] | undefined> = {};
+  for (const key of url.searchParams.keys()) {
+    if (key in query) continue;
+    const all = url.searchParams.getAll(key);
+    query[key] = all.length > 1 ? all : all[0];
+  }
+  return query;
+}
+
+function parseCookies(req: IncomingMessage): Record<string, string> {
+  const header = req.headers.cookie;
+  if (!header) return {};
+  const out: Record<string, string> = {};
+  for (const part of header.split(";")) {
+    const idx = part.indexOf("=");
+    if (idx < 0) continue;
+    const key = part.slice(0, idx).trim();
+    const value = part.slice(idx + 1).trim();
+    if (key) out[key] = decodeURIComponent(value);
+  }
+  return out;
+}
+
+/** Buffer the request stream once into a single Buffer (GET/HEAD => empty). */
+async function bufferBody(req: HttpRequest, maxBytes: number): Promise<Buffer> {
+  const method = (req.method ?? "GET").toUpperCase();
+  if (method === "GET" || method === "HEAD") return Buffer.alloc(0);
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let bytes = 0;
+    let settled = false;
+    const finish = (result: Buffer | Error) => {
+      if (settled) return;
+      settled = true;
+      req.removeListener("data", onData);
+      req.removeListener("end", onEnd);
+      req.removeListener("error", onError);
+      req.abortSignal?.removeEventListener("abort", onAbort);
+      if (result instanceof Error) reject(result);
+      else resolve(result);
+    };
+    const onData = (chunk: Buffer | string) => {
+      const bytesChunk = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+      bytes += bytesChunk.length;
+      if (bytes > maxBytes) {
+        finish(new NodeRequestBodyTooLargeError());
+        return;
+      }
+      chunks.push(bytesChunk);
+    };
+    const onEnd = () => finish(Buffer.concat(chunks));
+    const onError = (error: Error) => finish(error);
+    const onAbort = () => finish(new NodeRequestAbortedError());
+    if (req.abortSignal?.aborted) return onAbort();
+    req.on("data", onData);
+    req.once("end", onEnd);
+    req.once("error", onError);
+    req.abortSignal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/** Re-expose a fixed Buffer as the request's async-iterable so readRawBody sees the EXACT bytes. */
+function reexposeRawStream(req: IncomingMessage, raw: Buffer): void {
+  (req as unknown as { [Symbol.asyncIterator]: () => AsyncIterator<Buffer> })[Symbol.asyncIterator] =
+    async function* () {
+      yield raw;
+    };
+}
+
+/** Best-effort JSON parse of a buffered body for handlers that read `req.body`. */
+function parseJsonBody(raw: Buffer, contentType: string): unknown {
+  if (raw.length === 0) return undefined;
+  const text = raw.toString("utf8").trim();
+  if (!text) return undefined;
+  if (contentType.includes("application/json") || text.startsWith("{") || text.startsWith("[")) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  return text;
+}
+
+/**
+ * Decorate a Node response with Vercel's status/json/send/redirect sugar (productionized from the
+ * dev shim's decorateResponse — identical semantics).
+ */
+export function decorateResponse(res: ServerResponse): HttpResponse {
+  const vres = res as HttpResponse;
+  vres.status = function status(code: number): HttpResponse {
+    res.statusCode = code;
+    return vres;
+  };
+  vres.json = function json(body: unknown): HttpResponse {
+    if (!res.hasHeader("content-type")) {
+      res.setHeader("content-type", "application/json; charset=utf-8");
+    }
+    res.end(JSON.stringify(body));
+    return vres;
+  };
+  vres.send = function send(body: string | Buffer | object): HttpResponse {
+    if (Buffer.isBuffer(body) || typeof body === "string") {
+      res.end(body);
+      return vres;
+    }
+    if (!res.hasHeader("content-type")) {
+      res.setHeader("content-type", "application/json; charset=utf-8");
+    }
+    res.end(JSON.stringify(body));
+    return vres;
+  };
+  vres.redirect = function redirect(statusOrUrl: number | string, maybeUrl?: string): HttpResponse {
+    const code = typeof statusOrUrl === "number" ? statusOrUrl : 302;
+    const location = typeof statusOrUrl === "number" ? maybeUrl ?? "/" : statusOrUrl;
+    res.statusCode = code;
+    res.setHeader("location", location);
+    res.end();
+    return vres;
+  };
+  return vres;
+}
+
+/**
+ * Adapt a Node IncomingMessage into the Vercel request shape, honoring the raw-body invariant:
+ *  - raw-stream entrypoints (process/csp/feedback): stream left intact, NO req.body;
+ *  - everything else: raw bytes buffered + re-exposed as async-iterable (so readRawBody sees the
+ *    EXACT bytes for any signature-verifying route, webhook-segment or not) AND req.body = parsed JSON.
+ */
+export async function adaptRequest(
+  req: IncomingMessage,
+  pathname: string,
+  /** Explicit override for a caller that knows the entrypoint's body contract (see above). */
+  rawStream: boolean = isRawStreamEntrypoint(pathname),
+  bufferedBodyLimitBytes: number = DEFAULT_NODE_BUFFERED_BODY_LIMIT_BYTES,
+): Promise<HttpRequest> {
+  const vreq = req as HttpRequest;
+  vreq.query = parseQuery(req);
+  vreq.cookies = parseCookies(req);
+
+  if (rawStream) {
+    // Leave the live stream untouched; the handler reads it itself (formidable / custom readBody).
+    return vreq;
+  }
+
+  const raw = await bufferBody(vreq, bufferedBodyLimitBytes);
+  const contentType = String(req.headers["content-type"] ?? "");
+
+  // Re-expose the EXACT bytes as an async-iterable for EVERY buffered request, not only
+  // `/webhooks/` paths. Some signature-verifying routes live outside that segment — e.g.
+  // `/api/bff/communications/integrations/events` calls readRawBody for HMAC verification.
+  // readRawBody is stream-first (isAsyncIterable), so any handler that needs the raw bytes
+  // works; handlers that read req.body still get parsed JSON. The re-exposed iterator is
+  // simply never consumed for routes that don't call readRawBody, so this is a safe superset
+  // of the old `/webhooks/`-only behavior (and not dependent on a fragile path convention).
+  reexposeRawStream(req, raw);
+  vreq.body = parseJsonBody(raw, contentType);
+  return vreq;
+}
+
+/** Narrow a raw IncomingMessage to HttpRequest at the server boundary (query/cookies set in adapt). */
+export function decorateRequest(req: IncomingMessage): HttpRequest {
+  const vreq = req as HttpRequest;
+  if (!vreq.query) vreq.query = {};
+  return vreq;
+}

package/src/http/runtime.ts

@@ -0,0 +1,319 @@
+// Native Node adapter for manifest-driven public routing and API topology.
+//
+// The request order is fixed: trailing-slash redirect, the CSP report entrypoint, deployment
+// exact-path entrypoints, the BFF router entrypoint, deployment path entrypoints, the BFF
+// dispatcher, robots.txt, declared scheduled routes, the API 404, legacy redirects, deployment
+// fallback path entrypoints, then static documents. Every deployment value (routes, entrypoints,
+// header policy, robots policy, deadlines) is supplied by the composition root.
+
+import { createServer, type Server } from "node:http";
+
+import type { HttpRuntimePort } from "@openlup/core/platform-runtime";
+import type { EntrypointLoader, HttpRequest, HttpResponse } from "./types.js";
+import type { BffDispatch, RouteEntry } from "../bff/index.js";
+import {
+  adaptRequest,
+  decorateRequest,
+  decorateResponse,
+  NodeRequestAbortedError,
+  NodeRequestBodyTooLargeError,
+} from "./requestAdapter.js";
+import { closeInputAfterResponse, runWithHttpDeadline } from "./deadline.js";
+import {
+  applySecurityHeaders,
+  serveSpaStatic,
+  type NodeSecurityHeaderPolicy,
+  type StaticAssetReader,
+} from "./security.js";
+
+const SCHEDULED_PREFIX = "/api/cron/";
+const ROBOTS_CONTENT_TYPE = "text/plain; charset=utf-8";
+const EMPTY_ROUTING = { legacyRedirects: [], ssgPaths: [], csrFallback: { exactPaths: [], routeFamilies: [] } };
+
+function requestUrl(req: HttpRequest): URL {
+  return new URL(req.url ?? "/", "http://node.local");
+}
+
+function capturesFor(source: string, pathname: string): Record<string, string> | null {
+  const sourceParts = source.split("/").slice(1);
+  const pathParts = pathname.split("/").slice(1);
+  const captures: Record<string, string> = {};
+  let cursor = 0;
+  for (const sourcePart of sourceParts) {
+    if (!sourcePart.startsWith(":")) {
+      if (pathParts[cursor++] !== sourcePart) return null;
+      continue;
+    }
+    const name = sourcePart.slice(1).replace(/\*$/, "");
+    if (sourcePart.endsWith("*")) {
+      captures[name] = pathParts.slice(cursor).join("/");
+      cursor = pathParts.length;
+      break;
+    }
+    const value = pathParts[cursor++];
+    if (!value) return null;
+    captures[name] = value;
+  }
+  return cursor === pathParts.length ? captures : null;
+}
+
+function legacyRedirect(pathname: string, redirects: readonly NodeLegacyRedirect[]): string | null {
+  for (const redirect of redirects) {
+    const captures = capturesFor(redirect.source, pathname);
+    if (!captures) continue;
+    return redirect.destination.replace(/:([A-Za-z][A-Za-z0-9_]*)\*?/g, (_match, name: string) => captures[name] ?? "");
+  }
+  return null;
+}
+
+function isCsrFallback(pathname: string, csrFallback: NodeCsrFallback): boolean {
+  return csrFallback.exactPaths.includes(pathname)
+    || csrFallback.routeFamilies.some((path) => pathname === path || pathname.startsWith(`${path}/`));
+}
+
+/** One deployment-specific standalone entrypoint, matched by its exact path. */
+export interface HttpEntrypointRegistration {
+  path: string;
+  rawStream?: boolean;
+  maxDurationMs?: number;
+  load: EntrypointLoader;
+}
+
+/**
+ * One deployment-specific entrypoint matched by a path rule. `match` returns the query values the
+ * entrypoint receives for this path, or null when the path is not its own. The body is buffered.
+ */
+export interface HttpPathEntrypoint {
+  match(pathname: string): Record<string, string> | null;
+  load: EntrypointLoader;
+  /** Request deadline; defaults to 10 seconds. */
+  maxDurationMs?: number;
+}
+
+export interface NodeLegacyRedirect {
+  source: string;
+  destination: string;
+  permanent: boolean;
+}
+
+export interface NodeCsrFallback {
+  exactPaths: readonly string[];
+  routeFamilies: readonly string[];
+}
+
+export interface NodeHttpRuntimeOptions {
+  /** The deployment's BFF route table. */
+  routes: readonly RouteEntry[];
+  /** The dispatcher that matches `routes` (see `createBffDispatcher`). */
+  dispatch: BffDispatch;
+  /** Validated public-route contract supplied by the host composition root. */
+  routing?: {
+    legacyRedirects: readonly NodeLegacyRedirect[];
+    ssgPaths: readonly string[];
+    csrFallback: NodeCsrFallback;
+  };
+  /** Deployment header policy, including the content security policy. */
+  security: NodeSecurityHeaderPolicy;
+  /** robots.txt body for a request host; without it `/robots.txt` is served like any other path. */
+  robotsTxt?: (host: string | undefined) => string;
+  /**
+   * Platform-path standalone handlers: the CSP report sink at `/api/csp-report` and the hosted
+   * BFF router at `/api/bff-router`. A path without a handler is treated like any other path.
+   */
+  entrypoints?: {
+    cspReport?: EntrypointLoader;
+    bffRouter?: EntrypointLoader;
+  };
+  /**
+   * Deployment exact-path handlers, checked after the CSP report entrypoint and before the BFF
+   * router; a later registration replaces an earlier one with the same path.
+   */
+  extraEntrypoints?: readonly HttpEntrypointRegistration[];
+  /** Deployment path-rule handlers checked before the BFF dispatcher, first match wins. */
+  pathEntrypoints?: readonly HttpPathEntrypoint[];
+  /** Deployment path-rule handlers checked after legacy redirects and before static documents. */
+  fallbackPathEntrypoints?: readonly HttpPathEntrypoint[];
+  /** Registry-derived allowlist; undeclared job ids must resolve null. */
+  scheduledEntrypoint?: (jobId: string) => EntrypointLoader | null;
+  /** Explicit host deadlines; missing cells use the bounded defaults below. */
+  durations?: {
+    bff?: number;
+    cspReport?: number;
+    bffRouter?: number;
+    scheduled?: (jobId: string) => number;
+  };
+  /** Static SPA reader; without one, unmatched non-API paths answer 404. */
+  staticReader?: StaticAssetReader;
+  /** Structured error sink (defaults to console.error). */
+  onError?: (context: string, error: unknown) => void;
+}
+
+function finalize(res: HttpResponse): void {
+  if (!res.writableEnded && !res.destroyed) res.end();
+}
+
+function matchPathEntrypoint(
+  entrypoints: readonly HttpPathEntrypoint[] | undefined,
+  pathname: string,
+): { entrypoint: HttpPathEntrypoint; query: Record<string, string> } | null {
+  for (const entrypoint of entrypoints ?? []) {
+    const query = entrypoint.match(pathname);
+    if (query) return { entrypoint, query };
+  }
+  return null;
+}
+
+/** Build the runtime's request handler (exported for unit tests; wraps every dispatch path). */
+export function createRequestHandler(options: NodeHttpRuntimeOptions): HttpRuntimePort["handle"] {
+  const onError = options.onError ?? ((ctx, err) => console.error(`[node-http] ${ctx}`, err));
+  const staticReader = options.staticReader;
+  const routing = options.routing ?? EMPTY_ROUTING;
+  const ssgPaths = new Set(routing.ssgPaths);
+  // Built once; a deployment can deliberately replace an inherited path.
+  const extra = new Map((options.extraEntrypoints ?? []).map((entry) => [entry.path, entry]));
+
+  return async function handle(req: HttpRequest, res: HttpResponse): Promise<void> {
+    const url = requestUrl(req);
+    const pathname = url.pathname;
+    const host = req.headers.host;
+    const bounded = (durationMs: number, run: () => Promise<unknown> | unknown) =>
+      runWithHttpDeadline({ req, res, durationMs, run, onLateError: (error) => onError(`${pathname}:late`, error) });
+    const invoke = (
+      loader: EntrypointLoader,
+      durationMs: number,
+      rawStream?: boolean,
+      query?: Record<string, string>,
+    ) => bounded(durationMs, async () => {
+      const [mod, vreq] = await Promise.all([loader(), adaptRequest(req, pathname, rawStream)]);
+      if (query) vreq.query = { ...vreq.query, ...query };
+      await mod.default(vreq, res);
+    });
+    try {
+      applySecurityHeaders(res, pathname, host, options.security);
+      if (pathname.length > 1 && pathname.endsWith("/")) {
+        res.statusCode = 308;
+        res.setHeader("location", `${pathname.replace(/\/+$/, "")}${url.search}`);
+        return finalize(res);
+      }
+      // 1. Standalone entrypoints (filesystem-parity with api/*.ts).
+      const cspReport = options.entrypoints?.cspReport;
+      if (pathname === "/api/csp-report" && cspReport) {
+        await invoke(cspReport, options.durations?.cspReport ?? 30_000);
+        return finalize(res);
+      }
+      // 1b. Deployment entrypoints: exact path, lazy load, owner-declared body policy.
+      const registered = extra.get(pathname);
+      if (registered) {
+        await invoke(registered.load, registered.maxDurationMs ?? 30_000, registered.rawStream);
+        return finalize(res);
+      }
+      const bffRouter = options.entrypoints?.bffRouter;
+      if (pathname === "/api/bff-router" && bffRouter) {
+        await invoke(bffRouter, options.durations?.bffRouter ?? 30_000);
+        return finalize(res);
+      }
+      // 1c. Deployment path-rule entrypoints, before the BFF dispatcher.
+      const routed = matchPathEntrypoint(options.pathEntrypoints, pathname);
+      if (routed) {
+        await invoke(routed.entrypoint.load, routed.entrypoint.maxDurationMs ?? 10_000, false, routed.query);
+        return finalize(res);
+      }
+
+      // 2. The BFF dispatcher (same routes + dispatch as the hosted entrypoint).
+      if (pathname === "/api/bff" || pathname.startsWith("/api/bff/")) {
+        await bounded(options.durations?.bff ?? 30_000, async () =>
+          options.dispatch(options.routes, await adaptRequest(req, pathname), res));
+        return finalize(res);
+      }
+
+      if (pathname === "/robots.txt" && options.robotsTxt) {
+        res.statusCode = 200;
+        res.setHeader("content-type", ROBOTS_CONTENT_TYPE);
+        res.setHeader("cache-control", "public, max-age=0, s-maxage=300, stale-while-revalidate=3600");
+        res.end(options.robotsTxt(host));
+        return;
+      }
+
+      // 3. Scheduled routes share the scheduler's single-source allowlist.
+      if (pathname.startsWith(SCHEDULED_PREFIX)) {
+        const jobId = pathname.slice(SCHEDULED_PREFIX.length);
+        const loader = options.scheduledEntrypoint?.(jobId);
+        if (loader) {
+          await invoke(loader, options.durations?.scheduled?.(jobId) ?? 60_000);
+          return finalize(res);
+        }
+      }
+
+      // 4. Unknown /api/* => 404 JSON (never fall through to the SPA).
+      if (pathname.startsWith("/api/")) {
+        res.statusCode = 404;
+        res.setHeader("content-type", "application/json; charset=utf-8");
+        res.end(JSON.stringify({ ok: false, error: { code: "NOT_FOUND", message: "Not found" } }));
+        return;
+      }
+
+      const legacyLocation = legacyRedirect(pathname, routing.legacyRedirects);
+      if (legacyLocation) {
+        res.statusCode = 308;
+        res.setHeader("location", `${legacyLocation}${url.search}`);
+        return finalize(res);
+      }
+      const fallback = matchPathEntrypoint(options.fallbackPathEntrypoints, pathname);
+      if (fallback) {
+        await invoke(fallback.entrypoint.load, fallback.entrypoint.maxDurationMs ?? 10_000, false, fallback.query);
+        return finalize(res);
+      }
+
+      // 5. Static documents and declared CSR fallback. Unknown extensionless routes are 404.
+      if (staticReader) {
+        await serveSpaStatic(
+          req,
+          res,
+          pathname,
+          staticReader,
+          ssgPaths.has(pathname),
+          isCsrFallback(pathname, routing.csrFallback),
+        );
+        return;
+      }
+      // No static reader configured (pure-API smoke): respond 404 rather than hang.
+      res.statusCode = 404;
+      res.end("Not Found");
+    } catch (error) {
+      if (error instanceof NodeRequestAbortedError) return;
+      onError(pathname, error);
+      const tooLarge = error instanceof NodeRequestBodyTooLargeError;
+      if (tooLarge) closeInputAfterResponse(req, res);
+      if (!res.headersSent && !res.destroyed) {
+        res.statusCode = tooLarge ? 413 : 500;
+        res.setHeader("content-type", "application/json; charset=utf-8");
+      }
+      if (!res.writableEnded && !res.destroyed) {
+        res.end(JSON.stringify({ ok: false, error: {
+          code: tooLarge ? "REQUEST_BODY_TOO_LARGE" : "NODE_HTTP_ERROR",
+          message: tooLarge ? "Request body too large" : "Internal server error",
+        } }));
+      }
+    }
+  };
+}
+
+/** Create the Node HttpRuntimePort: `handle` for one request, `listen` to bind the server. */
+export function createNodeHttpRuntime(options: NodeHttpRuntimeOptions): HttpRuntimePort & {
+  server: Server | null;
+} {
+  const handle = createRequestHandler(options);
+  let server: Server | null = null;
+
+  return {
+    server,
+    handle,
+    async listen({ port, host }): Promise<void> {
+      server = createServer((req, res) => {
+        void handle(decorateRequest(req), decorateResponse(res));
+      });
+      this.server = server;
+      await new Promise<void>((resolve) => server!.listen(port, host ?? "0.0.0.0", resolve));
+    },
+  };
+}