@pattern-js/runtime-node 0.2.0

package/dist/http.js

@@ -0,0 +1,799 @@
+/**
+ * @pattern-js/runtime-node — HTTP host (§6, §7).
+ *
+ * Routing is **declarative**: the host derives its routes from the
+ * `boundary.http.request` nodes of the workflows registered on the engine. Each
+ * node's config carries the method, path, port, CORS policy, and JSON-Schema
+ * validation for body/query — there is no programmatic route table. When
+ * workflows change at runtime (e.g. loaded/updated from a DB), the host
+ * re-derives its routes live, opening/closing servers per declared port.
+ *
+ * Response modes: `buffered`, `sse` (Server-Sent Events), `chunked`.
+ */
+import { Buffer } from "node:buffer";
+import { createServer } from "node:http";
+import { extname } from "node:path";
+import { Readable } from "node:stream";
+import { ANONYMOUS, AUTH_LOGIN_URL, jsonSchemaToZod, principalToUser, } from "@pattern-js/core";
+import { filesystems } from "./filesystem.js";
+const DEFAULT_MAX_BODY = 10 * 1024 * 1024;
+/** Thrown by `readBody` when a buffered body exceeds the configured cap. */
+class BodyTooLargeError extends Error {
+    limit;
+    constructor(limit) {
+        super(`request body exceeds ${limit} bytes`);
+        this.limit = limit;
+    }
+}
+/**
+ * Inject the app bootstrap into entry HTML: a `<base href="${mount}/">` (so a
+ * bundle built with relative asset URLs resolves under ANY mount) and a
+ * `window.__APP__` carrying the app's manifest plus the mount/apiBase the host
+ * resolved. Inserted right after `<head>` so the base governs every relative URL
+ * below it. JSON `<` is escaped so a stray `</script>` can't break out.
+ */
+function injectBootstrap(bytes, mount, manifest) {
+    let html;
+    try {
+        html = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+    }
+    catch {
+        return bytes;
+    }
+    const baseHref = `${mount}/`.replace(/\/{2,}/g, "/"); // "" → "/", "/sales" → "/sales/"
+    // apiBase defaults to this mount's /api, but a manifest may point at a SHARED
+    // backend elsewhere (a branded SPA at /sales calling /chat/api).
+    const apiBase = typeof manifest.apiBase === "string" ? manifest.apiBase : `${mount}/api`;
+    const boot = { ...manifest, mount: mount || "/", apiBase };
+    const json = JSON.stringify(boot).replace(/</g, "\\u003c");
+    const inject = `<base href="${baseHref}"><script>window.__APP__=${json}</script>`;
+    const head = html.match(/<head[^>]*>/i);
+    html = head ? html.slice(0, head.index + head[0].length) + inject + html.slice(head.index + head[0].length) : inject + html;
+    return new TextEncoder().encode(html);
+}
+/** Read a positive integer port from the PORT env var, if valid. */
+function envPort() {
+    const raw = process.env.PORT;
+    if (!raw)
+        return undefined;
+    const n = Number(raw);
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+/**
+ * Per-segment route specificity: a static segment (2) outranks a `:param` (1).
+ * Compared left-to-right, this makes a HARDWIRED path win over a parametrized
+ * one that also matches — e.g. `/api/sales/turns` takes precedence over the
+ * generic `/api/:ns/turns`. So forking a workflow with a concrete path in place
+ * of a `:param` overrides the generic handler, for any route, not just chat.
+ */
+function routeSpec(path) {
+    return path
+        .split("/")
+        .filter(Boolean)
+        .map((seg) => (seg.startsWith(":") ? 1 : 2));
+}
+/** Order routes most-specific-first (stable, so equal specificity keeps registration order). */
+function bySpecificity(a, b) {
+    const n = Math.max(a.spec.length, b.spec.length);
+    for (let i = 0; i < n; i++) {
+        const x = a.spec[i] ?? -1;
+        const y = b.spec[i] ?? -1;
+        if (x !== y)
+            return y - x; // higher specificity first
+    }
+    return 0;
+}
+function compilePath(path) {
+    const paramNames = [];
+    // Escape regex specials (`:` is not one, so params survive as `:name`), then
+    // turn each `:param` segment into a capture group.
+    const pattern = path
+        .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+        .replace(/:([A-Za-z0-9_]+)/g, (_, name) => {
+        paramNames.push(name);
+        return "([^/]+)";
+    });
+    return { regex: new RegExp(`^${pattern}/?$`), paramNames };
+}
+/** Normalize a mount prefix: leading slash, no trailing slash; root → "". */
+function normalizeMount(mount) {
+    let m = mount.trim();
+    if (!m.startsWith("/"))
+        m = `/${m}`;
+    m = m.replace(/\/+$/, "");
+    return m; // "" for root
+}
+/** Is `pathname` at or under `mount` ("" matches everything)? */
+function pathUnderMount(pathname, mount) {
+    if (mount === "")
+        return true;
+    return pathname === mount || pathname.startsWith(`${mount}/`);
+}
+const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".map": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".ico": "image/x-icon",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf",
+    ".txt": "text/plain; charset=utf-8",
+    ".wasm": "application/wasm",
+};
+/** Content-type for a served asset, from its extension. */
+function mimeType(path) {
+    return MIME[extname(path).toLowerCase()] ?? "application/octet-stream";
+}
+function normalizeCors(cors) {
+    if (!cors)
+        return undefined;
+    if (cors === true)
+        return { origin: "*", credentials: false };
+    const c = cors;
+    return { origin: c.origin ?? "*", credentials: c.credentials ?? false, methods: c.methods, headers: c.headers, maxAge: c.maxAge, exposeHeaders: c.exposeHeaders };
+}
+export class HttpHost {
+    engine;
+    opts;
+    servers = new Map();
+    /** Live sockets per server, so shutdown can force-close lingering connections
+     *  (e.g. an open SSE stream that would otherwise keep `close()` pending). */
+    sockets = new Map();
+    routes = [];
+    apps = [];
+    unsubscribe;
+    defaultPort;
+    serverListeners = new Set();
+    constructor(engine, opts = {}) {
+        this.engine = engine;
+        this.opts = opts;
+        // Port resolution for a route: its op `config.port`, else this default.
+        // Default = explicit `defaultPort` (e.g. from pattern.config.json http.port),
+        // else the PORT env var, else 3000.
+        this.defaultPort = opts.defaultPort ?? envPort() ?? 3000;
+    }
+    /** Derive routes from registered workflows, open servers, and watch for changes. */
+    async start() {
+        await this.rebuild();
+        this.warnIfUnenforceableAuth();
+        this.unsubscribe = this.engine.onWorkflowsChanged(() => {
+            void this.rebuild().catch((err) => console.error("[pattern] http rebuild failed:", err));
+        });
+        return { ports: [...this.servers.keys()], close: () => this.close() };
+    }
+    /**
+     * Loud, honest signal: with NO auth provider installed, any route that
+     * *declares* `requireAuth` can't be enforced (nobody can authenticate) — the
+     * engine serves it open (advisory). Say so plainly at boot so it's never a
+     * silent surprise. Add a provider and the same declarations are enforced.
+     */
+    warnIfUnenforceableAuth() {
+        if (this.engine.hasAuthProvider())
+            return;
+        const gated = [...this.routes, ...this.apps].filter((r) => r.requireAuth).length;
+        if (!gated)
+            return;
+        console.warn(`\n[pattern] ⚠ ${gated} route(s) declare requireAuth but NO auth provider is installed —\n` +
+            `[pattern]   they are NOT enforced and serve UNAUTHENTICATED (anyone who can reach the\n` +
+            `[pattern]   port has access). Add an auth provider (e.g. @pattern-js/mod-identity) to enforce\n` +
+            `[pattern]   them. Routes without requireAuth are unaffected.\n`);
+    }
+    /** Tail of the rebuild queue — see `rebuild()`. */
+    rebuilding = Promise.resolve();
+    /**
+     * Scan workflows for `boundary.http.request` routes and reconcile servers.
+     * Rebuilds are serialized: workflow-change events can fire in rapid bursts
+     * (project load, admin batch deploys), and two interleaved reconciles would
+     * race `openServer` on the same port into EADDRINUSE.
+     */
+    rebuild() {
+        const next = this.rebuilding.then(() => this.rebuildNow());
+        // The queue itself never rejects (errors surface to each caller via `next`).
+        this.rebuilding = next.catch(() => { });
+        return next;
+    }
+    async rebuildNow() {
+        this.routes = this.scanRoutes();
+        this.apps = await this.scanApps();
+        const needed = new Set([...this.routes.map((r) => r.port), ...this.apps.map((a) => a.port)]);
+        for (const port of needed) {
+            if (!this.servers.has(port))
+                await this.openServer(port);
+        }
+        for (const port of [...this.servers.keys()]) {
+            if (!needed.has(port)) {
+                await this.closeServer(port);
+            }
+        }
+    }
+    /** Close one server, destroying any lingering sockets first. */
+    closeServer(port) {
+        const server = this.servers.get(port);
+        if (!server)
+            return Promise.resolve();
+        for (const socket of this.sockets.get(port) ?? [])
+            socket.destroy();
+        this.sockets.delete(port);
+        this.servers.delete(port);
+        return new Promise((r) => server.close(() => r()));
+    }
+    scanRoutes() {
+        const routes = [];
+        for (const wf of this.engine.workflows.list()) {
+            for (const node of wf.nodes) {
+                const op = this.engine.ops.get(node.op);
+                if (op?.type !== "boundary.http.request")
+                    continue;
+                const cfg = parseConfig(op, node.config);
+                if (!cfg.path)
+                    continue; // not routable without a path
+                const { regex, paramNames } = compilePath(cfg.path);
+                routes.push({
+                    method: String(cfg.method ?? "GET").toUpperCase(),
+                    path: cfg.path,
+                    port: cfg.port ?? this.defaultPort,
+                    regex,
+                    paramNames,
+                    spec: routeSpec(cfg.path),
+                    workflowId: wf.id,
+                    trigger: node.id,
+                    bodyMode: cfg.bodyMode === "stream" ? "stream" : "buffered",
+                    cors: normalizeCors(cfg.cors),
+                    bodySchema: cfg.body ? jsonSchemaToZod(cfg.body) : undefined,
+                    querySchema: cfg.query ? jsonSchemaToZod(cfg.query, { coerce: true }) : undefined,
+                    paramsSchema: cfg.params ? jsonSchemaToZod(cfg.params, { coerce: true }) : undefined,
+                    requireAuth: cfg.requireAuth,
+                    cancelOnDisconnect: Boolean(cfg.cancelOnDisconnect),
+                });
+            }
+        }
+        // Most-specific-first, so a hardwired path out-matches a generic :param one.
+        return routes.sort(bySpecificity);
+    }
+    /**
+     * Scan workflows for `boundary.http.app` mounts (admin-spec P1). The trigger
+     * declares the HTTP side (mount/port/cors/auth); the app itself is *resolved
+     * by running the workflow once* — the run flows trigger → app op (e.g.
+     * `core.app.static`, `admin.app`) → the `boundary.http.app.serve` out-gate,
+     * whose captured `app` descriptor tells the host what to serve.
+     */
+    async scanApps() {
+        const apps = [];
+        for (const wf of this.engine.workflows.list()) {
+            for (const node of wf.nodes) {
+                const op = this.engine.ops.get(node.op);
+                if (op?.type !== "boundary.http.app")
+                    continue;
+                const cfg = parseConfig(op, node.config);
+                const mount = normalizeMount(cfg.mount ?? "/");
+                let app;
+                try {
+                    const result = await this.engine.runFrom(wf, node.id, { mount: cfg.mount ?? "/" }, ANONYMOUS);
+                    if (result.status === "error")
+                        throw result.error;
+                    const payload = firstOutgate(result, wf, "boundary.http.app.serve");
+                    app = payload?.app;
+                }
+                catch (err) {
+                    console.error(`[pattern] app workflow "${wf.id}" failed to resolve its app:`, err);
+                    continue;
+                }
+                if (!app || typeof app.filesystem !== "string") {
+                    console.error(`[pattern] app workflow "${wf.id}" produced no app descriptor — not mounted`);
+                    continue;
+                }
+                apps.push({
+                    mount,
+                    port: cfg.port ?? this.defaultPort,
+                    filesystem: app.filesystem,
+                    spaFallback: typeof app.spaFallback === "string" ? app.spaFallback : "index.html",
+                    immutableAssets: Boolean(app.immutableAssets),
+                    cors: normalizeCors(cfg.cors),
+                    requireAuth: cfg.requireAuth,
+                    manifest: app.manifest && typeof app.manifest === "object" ? app.manifest : undefined,
+                });
+            }
+        }
+        // Longest mount first, so "/admin/sub" wins over "/admin" / "/".
+        apps.sort((a, b) => b.mount.length - a.mount.length);
+        return apps;
+    }
+    /** The first app mount on `port` whose prefix matches `pathname`. */
+    matchApp(port, pathname) {
+        return this.apps.find((a) => a.port === port && pathUnderMount(pathname, a.mount));
+    }
+    openServer(port) {
+        return new Promise((resolve, reject) => {
+            // The backstop: NOTHING a request does may become an unhandled rejection
+            // (plain `node` kills the process on those). E.g. a streaming out-gate
+            // whose producer fails AFTER the run settled errors the response stream
+            // mid-write — that's a request-level failure, not a process-level one.
+            const server = createServer((req, res) => this.handle(req, res, port).catch((err) => {
+                console.error("[pattern] request handler failed:", err);
+                try {
+                    if (!res.headersSent)
+                        res.writeHead(500, { "content-type": "application/json" });
+                    res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+                }
+                catch {
+                    res.destroy();
+                }
+            }));
+            // Surface listen errors (e.g. EADDRINUSE) as a rejection instead of an
+            // unhandled 'error' event that would crash the process.
+            server.once("error", (err) => reject(err));
+            // Track live sockets so close() can force them shut.
+            const live = new Set();
+            this.sockets.set(port, live);
+            server.on("connection", (socket) => {
+                live.add(socket);
+                socket.once("close", () => live.delete(socket));
+            });
+            server.listen(port, this.opts.host, () => {
+                server.removeAllListeners("error");
+                this.servers.set(port, server);
+                for (const cb of this.serverListeners)
+                    cb(server, port);
+                resolve();
+            });
+        });
+    }
+    /** The live http.Server for `port`, if open (e.g. to attach a WS host). */
+    server(port) {
+        return this.servers.get(port);
+    }
+    /**
+     * Run `cb` for every open server, now and as new ports open (route
+     * reconciliation opens/closes servers live) — the WS auto-wiring seam.
+     */
+    onServer(cb) {
+        for (const [port, server] of this.servers)
+            cb(server, port);
+        this.serverListeners.add(cb);
+        return () => this.serverListeners.delete(cb);
+    }
+    match(port, method, pathname) {
+        for (const route of this.routes) {
+            if (route.port !== port)
+                continue;
+            if (route.method !== "ANY" && route.method !== method)
+                continue;
+            const m = route.regex.exec(pathname);
+            if (!m)
+                continue;
+            const params = {};
+            route.paramNames.forEach((name, i) => (params[name] = decodeURIComponent(m[i + 1] ?? "")));
+            return { route, params };
+        }
+        return undefined;
+    }
+    async handle(req, res, port) {
+        // Build the URL from the real Host header (and forwarded proto), so the
+        // trigger's `url` output carries the actual request origin — workflows that
+        // build absolute links (magic-link callbacks) need the right host + port.
+        const fwdProto = req.headers["x-forwarded-proto"];
+        const proto = (Array.isArray(fwdProto) ? fwdProto[0] : fwdProto)?.split(",")[0]?.trim() || "http";
+        const host = req.headers.host || `localhost:${port}`;
+        const url = new URL(req.url ?? "/", `${proto}://${host}`);
+        const method = (req.method ?? "GET").toUpperCase();
+        // CORS preflight: any route on this port + path that declares CORS.
+        if (method === "OPTIONS") {
+            const cors = this.routes.find((r) => r.port === port && r.cors && r.regex.test(url.pathname))?.cors ??
+                this.matchApp(port, url.pathname)?.cors;
+            if (cors)
+                return this.preflight(req, res, cors, port, url.pathname);
+        }
+        const matched = this.match(port, method, url.pathname);
+        if (!matched) {
+            // API routes take precedence; fall back to static app mounts (P1).
+            const app = this.matchApp(port, url.pathname);
+            if (app)
+                return this.serveApp(req, res, app, url.pathname);
+            res.writeHead(404, { "content-type": "text/plain" }).end("Not Found");
+            return;
+        }
+        const { route, params } = matched;
+        if (route.cors)
+            applyCors(res, route.cors, req.headers.origin);
+        const workflow = this.engine.workflows.get(route.workflowId);
+        if (!workflow) {
+            res.writeHead(500).end("workflow not registered");
+            return;
+        }
+        // ── Auth (§9) ──
+        const headers = new Headers();
+        for (const [k, v] of Object.entries(req.headers)) {
+            if (typeof v === "string")
+                headers.set(k, v);
+            else if (Array.isArray(v))
+                headers.set(k, v.join(", "));
+        }
+        const principal = await this.engine.authenticate({ headers, raw: req });
+        const auth = this.engine.authorize(principal, route.requireAuth);
+        if (!auth.ok) {
+            res.writeHead(401, { "content-type": "text/plain" }).end(`Unauthorized: ${auth.reason}`);
+            return;
+        }
+        // ── Validate params, query & body against the declared JSON Schemas (§7) ──
+        const headersObj = {};
+        headers.forEach((v, k) => (headersObj[k] = v));
+        let routeParams = params;
+        if (route.paramsSchema) {
+            const parsed = route.paramsSchema.safeParse(routeParams);
+            if (!parsed.success)
+                return badRequest(res, "params", parsed.error);
+            routeParams = parsed.data;
+        }
+        let query = Object.fromEntries(url.searchParams.entries());
+        if (route.querySchema) {
+            const parsed = route.querySchema.safeParse(query);
+            if (!parsed.success)
+                return badRequest(res, "query", parsed.error);
+            query = parsed.data;
+        }
+        let body;
+        if (route.bodyMode === "stream") {
+            body = Readable.toWeb(req);
+        }
+        else {
+            try {
+                body = await readBody(req, headers.get("content-type"), this.opts.maxBodyBytes ?? DEFAULT_MAX_BODY);
+            }
+            catch (err) {
+                if (err instanceof BodyTooLargeError) {
+                    res.writeHead(413, { "content-type": "application/json" }).end(JSON.stringify({ error: err.message }));
+                    return;
+                }
+                throw err;
+            }
+            if (route.bodySchema) {
+                const parsed = route.bodySchema.safeParse(body);
+                if (!parsed.success)
+                    return badRequest(res, "body", parsed.error);
+                body = parsed.data;
+            }
+        }
+        const input = {
+            method,
+            url: url.toString(),
+            path: url.pathname,
+            headers: headersObj,
+            cookies: parseCookies(headersObj.cookie),
+            query,
+            params: routeParams,
+            body,
+            // Seeds the trigger's `user` output port (§9): the resolved principal
+            // flattened for wiring, null when anonymous.
+            user: principalToUser(principal),
+        };
+        // The run is independent of the connection by default — a chat turn or a
+        // long task keeps running (and persisting) if the client drops, and replays
+        // on reconnect. Only when the route opts in (`cancelOnDisconnect`) do we
+        // cancel on a client disconnect — for a pure passthrough stream with nothing
+        // worth finishing. Then: abort propagates to the run's producers so they stop
+        // writing to a dead socket and the trace true-end fires promptly.
+        // We can't gate on `res.writableFinished`: a mid-stream disconnect makes the
+        // write fail, `writeResponse` ends the response, and only THEN does `close`
+        // fire (finished already true). So we track our own "delivered in full" flag.
+        const ac = new AbortController();
+        let delivered = false;
+        if (route.cancelOnDisconnect) {
+            res.on("close", () => {
+                if (!delivered)
+                    ac.abort(new Error("client disconnected"));
+            });
+        }
+        let result;
+        try {
+            result = await this.engine.runFrom(workflow, route.trigger, input, principal, ac.signal);
+        }
+        catch (err) {
+            delivered = true;
+            return writeError(res, err);
+        }
+        if (result.status === "error") {
+            delivered = true;
+            return writeError(res, result.error);
+        }
+        const payload = firstOutgate(result, workflow, "boundary.http.response");
+        if (!payload) {
+            delivered = true;
+            res.writeHead(204).end();
+            return;
+        }
+        await writeResponse(res, payload);
+        delivered = true;
+    }
+    /** Serve a static asset (or SPA fallback) for an app mount (admin-spec P1). */
+    async serveApp(req, res, app, pathname) {
+        const method = (req.method ?? "GET").toUpperCase();
+        if (method !== "GET" && method !== "HEAD") {
+            res.writeHead(404, { "content-type": "text/plain" }).end("Not Found");
+            return;
+        }
+        if (app.cors)
+            applyCors(res, app.cors, req.headers.origin);
+        // Auth (§9): the app mount may require it, like any route.
+        if (app.requireAuth) {
+            const headers = new Headers();
+            for (const [k, v] of Object.entries(req.headers)) {
+                if (typeof v === "string")
+                    headers.set(k, v);
+                else if (Array.isArray(v))
+                    headers.set(k, v.join(", "));
+            }
+            const principal = await this.engine.authenticate({ headers, raw: req });
+            const auth = this.engine.authorize(principal, app.requireAuth);
+            if (!auth.ok) {
+                // A browser asking for HTML gets bounced to the advertised login page
+                // (§9) — the identity mod registers AUTH_LOGIN_URL; fetch/XHR callers
+                // still get the bare 401 and handle it client-side.
+                const loginUrl = this.engine.service(AUTH_LOGIN_URL);
+                const accept = String(req.headers["accept"] ?? "");
+                if (loginUrl && accept.includes("text/html")) {
+                    const next = encodeURIComponent(req.url ?? "/");
+                    res.writeHead(302, { location: `${loginUrl}?next=${next}` }).end();
+                    return;
+                }
+                res.writeHead(401, { "content-type": "text/plain" }).end(`Unauthorized: ${auth.reason}`);
+                return;
+            }
+        }
+        const fs = filesystems(this.engine).get(app.filesystem);
+        if (!fs) {
+            res.writeHead(500, { "content-type": "text/plain" }).end(`filesystem "${app.filesystem}" not registered`);
+            return;
+        }
+        let rel = pathname.slice(app.mount.length).replace(/^\/+/, "");
+        if (rel === "")
+            rel = app.spaFallback || "index.html";
+        const readIfExists = async (p) => (await fs.fileExists(p)) ? fs.readToUint8Array(p) : null;
+        let bytes = await readIfExists(rel);
+        let servedFallback = false;
+        if (bytes == null && app.spaFallback) {
+            // Client-side routing: serve the fallback for HTML navigations only.
+            const accept = String(req.headers["accept"] ?? "");
+            if (accept.includes("text/html")) {
+                bytes = await readIfExists(app.spaFallback);
+                servedFallback = true;
+                rel = app.spaFallback;
+            }
+        }
+        if (bytes == null) {
+            res.writeHead(404, { "content-type": "text/plain" }).end("Not Found");
+            return;
+        }
+        const headers = { "content-type": mimeType(rel) };
+        const isHtmlEntry = servedFallback || rel === app.spaFallback;
+        if (app.immutableAssets && !isHtmlEntry)
+            headers["cache-control"] = "public, max-age=31536000, immutable";
+        else if (isHtmlEntry)
+            headers["cache-control"] = "no-cache";
+        // Entry HTML of a bootstrap-aware app: inject a mount-portable <base href>
+        // and window.__APP__ so the SAME static bundle works under any mount and
+        // learns its brand/apiBase at load. Other assets (and apps without a
+        // manifest, e.g. admin) are served byte-for-byte.
+        const out = isHtmlEntry && app.manifest ? injectBootstrap(bytes, app.mount, app.manifest) : bytes;
+        res.writeHead(200, headers);
+        if (method === "HEAD")
+            return void res.end();
+        res.end(Buffer.from(out));
+    }
+    preflight(req, res, cors, port, pathname) {
+        const methods = cors.methods ?? collectMethods(this.routes, port, pathname);
+        applyCors(res, cors, req.headers.origin);
+        res.setHeader("Access-Control-Allow-Methods", methods.join(", "));
+        res.setHeader("Access-Control-Allow-Headers", cors.headers?.join(", ") ?? req.headers["access-control-request-headers"] ?? "*");
+        if (cors.maxAge != null)
+            res.setHeader("Access-Control-Max-Age", String(cors.maxAge));
+        res.writeHead(204).end();
+    }
+    async close() {
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+        await Promise.all([...this.servers.keys()].map((port) => this.closeServer(port)));
+        this.servers.clear();
+        this.sockets.clear();
+    }
+}
+// ── helpers ──
+function parseConfig(op, config) {
+    return op.config ? op.config.parse(config ?? {}) : (config ?? {});
+}
+function collectMethods(routes, port, pathname) {
+    const methods = new Set();
+    for (const r of routes)
+        if (r.port === port && r.regex.test(pathname))
+            methods.add(r.method);
+    methods.add("OPTIONS");
+    return [...methods];
+}
+function applyCors(res, cors, reqOrigin) {
+    // With an array allowlist, a non-matching (or absent) request origin gets NO
+    // Access-Control-Allow-Origin header at all — echoing any allowlisted value
+    // back to an unlisted origin would effectively open CORS to everyone.
+    const origin = cors.origin === "*"
+        ? "*"
+        : Array.isArray(cors.origin)
+            ? reqOrigin && cors.origin.includes(reqOrigin)
+                ? reqOrigin
+                : undefined
+            : cors.origin;
+    if (origin !== undefined)
+        res.setHeader("Access-Control-Allow-Origin", origin);
+    if (origin !== "*")
+        res.setHeader("Vary", "Origin");
+    if (cors.credentials)
+        res.setHeader("Access-Control-Allow-Credentials", "true");
+    if (cors.exposeHeaders?.length)
+        res.setHeader("Access-Control-Expose-Headers", cors.exposeHeaders.join(", "));
+}
+function badRequest(res, where, error) {
+    res.writeHead(400, { "content-type": "application/json" }).end(JSON.stringify({
+        error: `invalid ${where}`,
+        issues: error.issues.map((i) => ({ path: i.path.join("."), message: i.message })),
+    }));
+}
+async function readBody(req, contentType, maxBytes = DEFAULT_MAX_BODY) {
+    const chunks = [];
+    let size = 0;
+    for await (const c of req) {
+        size += c.length;
+        if (size > maxBytes) {
+            req.destroy(); // stop the client from streaming the rest into memory
+            throw new BodyTooLargeError(maxBytes);
+        }
+        chunks.push(c);
+    }
+    const buf = Buffer.concat(chunks);
+    if (buf.length === 0)
+        return undefined;
+    const ct = contentType ?? "";
+    if (ct.includes("application/json")) {
+        try {
+            return JSON.parse(buf.toString("utf8"));
+        }
+        catch {
+            return buf.toString("utf8");
+        }
+    }
+    // Browser form posts → a plain object, so a workflow can decompose the fields
+    // (core.object.extract) just like a JSON body. Ops never parse forms.
+    if (ct.includes("application/x-www-form-urlencoded")) {
+        return Object.fromEntries(new URLSearchParams(buf.toString("utf8")).entries());
+    }
+    if (ct.startsWith("text/") || ct === "")
+        return buf.toString("utf8");
+    return new Uint8Array(buf);
+}
+/** Parse a request `Cookie` header into a name→value record (network-IN). */
+function parseCookies(header) {
+    const out = {};
+    if (!header)
+        return out;
+    for (const part of header.split(";")) {
+        const eq = part.indexOf("=");
+        if (eq < 0)
+            continue;
+        const name = part.slice(0, eq).trim();
+        if (!name)
+            continue;
+        try {
+            out[name] = decodeURIComponent(part.slice(eq + 1).trim());
+        }
+        catch {
+            out[name] = part.slice(eq + 1).trim();
+        }
+    }
+    return out;
+}
+/** Serialize one Set-Cookie value from `{ name: value | { value, … } }` (network-OUT). */
+function serializeCookie(name, spec) {
+    if (spec === null || spec === undefined)
+        return `${name}=; Path=/; Max-Age=0; SameSite=Lax`;
+    if (typeof spec !== "object")
+        return `${name}=${encodeURIComponent(String(spec))}; Path=/; SameSite=Lax; HttpOnly`;
+    const o = spec;
+    const parts = [`${name}=${encodeURIComponent(String(o.value ?? ""))}`, `Path=${o.path ?? "/"}`];
+    if (o.maxAge != null)
+        parts.push(`Max-Age=${o.maxAge}`);
+    if (o.expires)
+        parts.push(`Expires=${o.expires}`);
+    if (o.domain)
+        parts.push(`Domain=${o.domain}`);
+    parts.push(`SameSite=${o.sameSite ?? "Lax"}`);
+    if (o.httpOnly !== false)
+        parts.push("HttpOnly");
+    if (o.secure)
+        parts.push("Secure");
+    return parts.join("; ");
+}
+async function writeResponse(res, payload) {
+    const mode = payload.mode ?? "buffered";
+    // A redirect is just 302 + Location (status overridable for 301/307/308).
+    const redirecting = typeof payload.redirect === "string" && payload.redirect.length > 0;
+    const status = payload.status ?? (redirecting ? 302 : 200);
+    const headers = { ...(payload.headers ?? {}) };
+    if (redirecting)
+        headers.location = payload.redirect;
+    if (payload.cookies && typeof payload.cookies === "object") {
+        const set = Object.entries(payload.cookies).map(([n, s]) => serializeCookie(n, s));
+        if (set.length)
+            headers["set-cookie"] = set;
+    }
+    if (mode === "sse" || mode === "chunked") {
+        const sse = mode === "sse";
+        res.writeHead(status, sse
+            ? { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive", ...headers }
+            : { "transfer-encoding": "chunked", ...headers });
+        const src = payload.stream ?? (payload.body instanceof ReadableStream ? payload.body : undefined);
+        if (src) {
+            try {
+                for await (const chunk of streamIter(src)) {
+                    if (sse)
+                        res.write(`data: ${typeof chunk === "string" ? chunk : JSON.stringify(chunk)}\n\n`);
+                    else
+                        res.write(chunk instanceof Uint8Array ? chunk : typeof chunk === "string" ? chunk : JSON.stringify(chunk));
+                }
+            }
+            catch (err) {
+                // The producer failed mid-stream (headers are long gone) — end the
+                // response; consumers recover from their source of truth.
+                console.error("[pattern] response stream errored mid-flight:", err instanceof Error ? err.message : err);
+            }
+        }
+        res.end();
+        return;
+    }
+    const body = payload.body;
+    if (body == null)
+        res.writeHead(status, headers).end();
+    else if (typeof body === "string")
+        res.writeHead(status, { "content-type": "text/plain; charset=utf-8", ...headers }).end(body);
+    else if (body instanceof Uint8Array)
+        res.writeHead(status, headers).end(Buffer.from(body));
+    else
+        res.writeHead(status, { "content-type": "application/json", ...headers }).end(JSON.stringify(body));
+}
+async function* streamIter(stream) {
+    const reader = stream.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                return;
+            yield value;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function writeError(res, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (!res.headersSent)
+        res.writeHead(500, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: message }));
+}
+function firstOutgate(result, workflow, opType) {
+    for (const [nodeId, payload] of Object.entries(result.outputs)) {
+        if (workflow.nodes.find((n) => n.id === nodeId)?.op === opType)
+            return payload;
+    }
+    return Object.values(result.outputs)[0];
+}
+/** Create an HTTP host that derives its routes from the engine's workflows. */
+export function createHttpHost(engine, opts) {
+    return new HttpHost(engine, opts);
+}
+//# sourceMappingURL=http.js.map