@lovrozagar/honey 0.7.3 → 1.0.0-rc.3

package/dist/adapters/node/response.js

@@ -0,0 +1,126 @@
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { isHoneyResponse, rawBodyOf } from "../../response/builder.js";
+/** A cancel that rejects (the stream had already failed) has nothing left to stop. */
+function ignore() { }
+/** A known-size native body up to this many bytes is buffered and sent in one write. */
+const BUFFER_BODY_MAX = 256 * 1024;
+/** Hop-by-hop headers (RFC 9110 §7.6.1) describe one connection: Node writes its own. */
+const HOP_BY_HOP = /^(?:connection|keep-alive|proxy-connection|te|trailer|transfer-encoding|upgrade)$/;
+/** The header names a `Connection` header lists: hop-by-hop too. */
+function connectionNamed(value) {
+    return String(value ?? "")
+        .toLowerCase()
+        .split(",")
+        .map((token) => token.trim());
+}
+function hasHopByHop(headers) {
+    for (const name in headers)
+        if (HOP_BY_HOP.test(name))
+            return true;
+    return false;
+}
+/** A Honey header map, without the hop-by-hop ones a handler set; the same object when it has none. */
+function honeyHeaders(headers) {
+    if (!hasHopByHop(headers))
+        return headers;
+    const named = connectionNamed(headers.connection);
+    return Object.fromEntries(Object.entries(headers).filter(([name]) => !HOP_BY_HOP.test(name) && !named.includes(name)));
+}
+/**
+ * A native response's headers as a fresh map Node takes: every Set-Cookie kept, hop-by-hop and
+ * Connection-named dropped. The Connection list and the cookie list are read only when present.
+ */
+function nativeHeaders(response) {
+    const connection = response.headers.get("connection");
+    const named = connection === null ? null : connectionNamed(connection);
+    const headers = {};
+    let cookies = false;
+    response.headers.forEach((value, name) => {
+        if (name === "set-cookie")
+            cookies = true;
+        else if (!HOP_BY_HOP.test(name) && (named === null || !named.includes(name)))
+            headers[name] = value;
+    });
+    if (cookies)
+        headers["set-cookie"] = response.headers.getSetCookie();
+    return headers;
+}
+/** A header map this write may change: a native one is fresh, a Honey one is copied. */
+function ownHeaders(response) {
+    return isHoneyResponse(response) ? { ...honeyHeaders(response.plainHeaders) } : nativeHeaders(response);
+}
+function headersOf(response) {
+    return isHoneyResponse(response) ? honeyHeaders(response.plainHeaders) : nativeHeaders(response);
+}
+function writeHead(res, response, headers) {
+    res.writeHead(response.status, response.statusText === "" ? undefined : response.statusText, headers);
+}
+function writeBuffered(res, response, body) {
+    const length = typeof body === "string" ? Buffer.byteLength(body) : body.byteLength;
+    const headers = ownHeaders(response);
+    headers["content-length"] = String(length);
+    writeHead(res, response, headers);
+    res.end(body);
+}
+/** A native body whose declared length is small enough to buffer: one write instead of a pipe. */
+function isSmallDeclared(response) {
+    const declared = response.headers.get("content-length");
+    return declared !== null && /^\d+$/.test(declared) && Number(declared) <= BUFFER_BODY_MAX;
+}
+/** Pipe a body to the socket; when the response closes first, the producer is cancelled. */
+async function pipeBody(stream, res) {
+    /* Node's web stream and the DOM ReadableStream brands do not overlap */
+    const readable = Readable.fromWeb(stream);
+    try {
+        await pipeline(readable, res);
+    }
+    catch {
+        /* the client left, or the stream failed after the headers went out: cut the connection */
+        res.destroy();
+        /* the connection is cut already: a cancel failing has no one left to tell */
+        await stream.cancel().catch(ignore);
+    }
+}
+/**
+ * The head GET would send, then the end: the body is cancelled unread, so a streaming route's
+ * producer never runs. A stream GET would chunk keeps no length; one GET buffers keeps its own.
+ */
+function writeHeadOnly(res, response, body) {
+    const headers = ownHeaders(response);
+    if (!isHoneyResponse(response) && !isSmallDeclared(response))
+        delete headers["content-length"];
+    writeHead(res, response, headers);
+    res.end();
+    /* a HEAD's body is never sent: a cancel failing changes nothing the client sees */
+    body.cancel().catch(ignore);
+}
+/**
+ * Write `response` to `res`: headers for this connection, the body buffered or piped. For a
+ * HEAD (`head`), Node writes no body; a body still unread is never read.
+ */
+export async function writeResponse(response, res, head = false) {
+    const raw = rawBodyOf(response);
+    if (raw !== null)
+        return writeBuffered(res, response, raw);
+    const body = response.body;
+    if (body === null) {
+        writeHead(res, response, headersOf(response));
+        res.end();
+        return;
+    }
+    if (head)
+        return writeHeadOnly(res, response, body);
+    if (isHoneyResponse(response)) {
+        writeHead(res, response, headersOf(response));
+        return pipeBody(body, res);
+    }
+    if (isSmallDeclared(response))
+        return writeBuffered(res, response, new Uint8Array(await response.arrayBuffer()));
+    /* a stream's declared length is never trusted (`fetch()` keeps the encoded length of a body it
+     * decoded): Node chunks it, so a wrong length cannot truncate it or desynchronize keep-alive */
+    const headers = nativeHeaders(response);
+    delete headers["content-length"];
+    writeHead(res, response, headers);
+    return pipeBody(body, res);
+}

package/dist/adapters/node/serve.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The Node adapter's server: it hands each request to the app through the request view, writes
+ * the answer (`response.ts`), answers what it refuses itself, and drains on shutdown. A WebSocket
+ * handshake takes Node's `'upgrade'` path: the raw socket rides on the request view under
+ * `NODE_UPGRADE`, `ws` writes the 101 itself, and the body writer never touches an upgraded socket.
+ */
+import { type Server } from "node:http";
+export type NodeServeOptions<TEnv> = {
+    env: TEnv;
+    hostname?: string;
+    /** Default: a free port. */
+    port?: number;
+    /** The largest request body a read accepts, in bytes; over it the read fails with 413. `0` turns it off. Default 128 MiB. */
+    maxRequestBodySize?: number;
+    /** Node's `server.headersTimeout`, in ms. */
+    headersTimeout?: number;
+    /** Node's `server.requestTimeout`, in ms. */
+    requestTimeout?: number;
+    /** Node's `server.keepAliveTimeout`, in ms. */
+    keepAliveTimeout?: number;
+    /** How long an upgrade request may take to become a WebSocket or be answered, in ms. Default 30 000. */
+    upgradeTimeout?: number;
+    /** Errors the adapter could not hand to the app (it then answers 500). Default: the app's logger. */
+    onError?: (error: unknown) => void;
+};
+export type HoneyServer = Server & {
+    /**
+     * Stop accepting connections and let in-flight requests finish. Responses already streaming
+     * never finish on their own, so their signal aborts now. After `timeout` ms, everything still
+     * working is aborted and every connection closes.
+     */
+    shutdown(timeout?: number): Promise<void>;
+};
+type FetchApp<TEnv> = {
+    fetch(request: Request, env: TEnv): Response | Promise<Response>;
+};
+/** Serve `app` with `node:http`. The server starts listening at once; `'listening'` tells when it is bound. */
+export declare function serve<TEnv>(app: FetchApp<TEnv>, options: NodeServeOptions<TEnv>): HoneyServer;
+export {};

package/dist/adapters/node/serve.js

@@ -0,0 +1,205 @@
+/**
+ * The Node adapter's server: it hands each request to the app through the request view, writes
+ * the answer (`response.ts`), answers what it refuses itself, and drains on shutdown. A WebSocket
+ * handshake takes Node's `'upgrade'` path: the raw socket rides on the request view under
+ * `NODE_UPGRADE`, `ws` writes the 101 itself, and the body writer never touches an upgraded socket.
+ */
+import { createServer, ServerResponse } from "node:http";
+import { GRAPH } from "../../routing/app.js";
+import { NODE_UPGRADE, nodeWebSocket } from "../../ws/node.js";
+import { HoneyError } from "../../errors/error.js";
+import { createLogger } from "../../telemetry/logger.js";
+import { DEFAULT_MAX_REQUEST_BODY } from "../serve.js";
+import { ABORT_REQUEST, BODY_OVERFLOW, nodeRequest } from "./request.js";
+import { writeResponse } from "./response.js";
+import { nodeRequestUrl } from "./url.js";
+function abort(request, reason) {
+    ;
+    request[ABORT_REQUEST](reason);
+}
+function shuttingDown() {
+    return new DOMException("The server is shutting down", "AbortError");
+}
+function answerPlain(res, status, text, close) {
+    const headers = { "content-length": String(text.length), "content-type": "text/plain" };
+    /* the reason phrase is explicit: a writeHead that threw on a bad header already set "OK" */
+    res.writeHead(status, text, close ? { connection: "close", ...headers } : headers);
+    res.end(text);
+}
+const DEFAULT_UPGRADE_TIMEOUT = 30_000;
+function isWebSocketUpgrade(incoming) {
+    return incoming.headers.upgrade?.toLowerCase() === "websocket";
+}
+/** The honey app's settings, its ws adapter filled with `nodeWebSocket()` when none is set. */
+function settingsOf(app) {
+    const settings = app[GRAPH]?.settings ?? null;
+    if (settings === null)
+        return null;
+    settings.wsAdapter ??= nodeWebSocket();
+    if (settings.wsAdapter.runtime !== "node") {
+        throw new Error("serve() on Node needs a nodeWebSocket() adapter, but app.wsAdapter() was given another");
+    }
+    return settings;
+}
+/** Answer on a socket Node handed over through `'upgrade'`, with a real ServerResponse; the connection ends with it. */
+function responseOnSocket(incoming, socket) {
+    const res = new ServerResponse(incoming);
+    res.shouldKeepAlive = false;
+    res.assignSocket(socket);
+    res.once("finish", () => {
+        res.detachSocket(socket);
+        socket.end();
+    });
+    return res;
+}
+function shutdown(server, drain, timeout) {
+    drain.draining = true;
+    return new Promise((resolve) => {
+        let timer;
+        server.close(() => {
+            clearTimeout(timer);
+            resolve();
+        });
+        server.closeIdleConnections();
+        for (const [res, request] of drain.inflight)
+            if (res.headersSent)
+                abort(request, shuttingDown());
+        drain.settings?.wsAdapter?.closeAll?.(1001, "server shutting down");
+        if (timeout !== undefined) {
+            timer = setTimeout(() => {
+                for (const request of drain.inflight.values())
+                    abort(request, shuttingDown());
+                for (const socket of drain.upgraded)
+                    socket.destroy();
+                server.closeAllConnections();
+            }, timeout);
+        }
+    });
+}
+/** The default serve failure reporter: the app's logger, or a default one for a plain fetch handler. */
+function reportTo(logger) {
+    return (error) => logger.error({ err: HoneyError.serialize(error) }, "serve failed");
+}
+/** Hand `error` to the operator's onError; one that throws itself must not become an unhandled rejection. */
+function report(s, error) {
+    try {
+        s.onError(error);
+    }
+    catch {
+        /* the 500 still goes out; nothing else is left to tell */
+    }
+}
+async function handleRequest(s, incoming, res) {
+    const { drain } = s;
+    if (drain.draining)
+        return answerPlain(res, 503, "Service Unavailable", true);
+    const url = nodeRequestUrl(incoming);
+    if (url === null)
+        return answerPlain(res, 400, "Bad Request", true);
+    const request = nodeRequest(incoming, url, s.maxBody);
+    drain.inflight.set(res, request);
+    /* closed before it finished: the client left, or shutdown cut it */
+    res.once("close", () => {
+        if (!res.writableFinished)
+            abort(request);
+    });
+    try {
+        /* a synchronous answer skips the extra microtask an await would cost */
+        const answer = s.app.fetch(request, s.env);
+        const response = answer instanceof Promise ? await answer : answer;
+        /* a body over the cap was left on the socket; while draining, the connection ends here */
+        if (drain.draining || request[BODY_OVERFLOW])
+            res.shouldKeepAlive = false;
+        await writeResponse(response, res, incoming.method === "HEAD");
+    }
+    catch (error) {
+        report(s, error);
+        /* every failure before this point comes before writeHead; a failing body pipe cuts the connection itself */
+        answerPlain(res, 500, "Internal Server Error", false);
+    }
+    finally {
+        drain.inflight.delete(res);
+        /* a keep-alive connection that just went idle would hold close() open until it times out */
+        if (drain.draining)
+            setImmediate(() => s.server.closeIdleConnections());
+    }
+}
+/** Node without shouldUpgradeCallback sends every Upgrade to 'upgrade': a bodiless one is an ordinary request. */
+function upgradeAsRequest(s, incoming, socket) {
+    /* its body bytes would already be on the raw socket: only a bodiless one can be served */
+    if (incoming.headers["transfer-encoding"] !== undefined || Number(incoming.headers["content-length"] ?? 0) > 0) {
+        return answerPlain(responseOnSocket(incoming, socket), 400, "Bad Request", true);
+    }
+    socket.setTimeout(0);
+    return handleRequest(s, incoming, responseOnSocket(incoming, socket));
+}
+/** A WebSocket handshake: the app's ws route upgrades it through the adapter, or answers it on the socket. */
+async function handleUpgrade(s, incoming, socket, head) {
+    if (!isWebSocketUpgrade(incoming))
+        return upgradeAsRequest(s, incoming, socket);
+    const url = s.drain.draining ? null : nodeRequestUrl(incoming);
+    if (url === null) {
+        const [status, text] = s.drain.draining ? [503, "Service Unavailable"] : [400, "Bad Request"];
+        return answerPlain(responseOnSocket(incoming, socket), status, text, true);
+    }
+    const request = nodeRequest(incoming, url, s.maxBody);
+    const upgrade = { head, req: incoming, socket, upgraded: false };
+    Object.defineProperty(request, NODE_UPGRADE, { value: upgrade });
+    socket.once("close", () => abort(request));
+    try {
+        const answer = await s.app.fetch(request, s.env);
+        socket.setTimeout(0);
+        /* the socket is a WebSocket now: an HTTP answer on it would corrupt the stream */
+        if (upgrade.upgraded)
+            return trackUpgraded(s.drain, socket);
+        if (!socket.destroyed)
+            await writeResponse(answer, responseOnSocket(incoming, socket), false);
+    }
+    catch (error) {
+        report(s, error);
+        /* a socket ws already took stays the WebSocket's; shutdown still has to be able to cut it */
+        if (upgrade.upgraded)
+            trackUpgraded(s.drain, socket);
+        else if (!socket.destroyed)
+            answerPlain(responseOnSocket(incoming, socket), 500, "Internal Server Error", false);
+    }
+}
+function trackUpgraded(drain, socket) {
+    drain.upgraded.add(socket);
+    socket.once("close", () => drain.upgraded.delete(socket));
+}
+/** Serve `app` with `node:http`. The server starts listening at once; `'listening'` tells when it is bound. */
+export function serve(app, options) {
+    const drain = { draining: false, inflight: new Map(), settings: settingsOf(app), upgraded: new Set() };
+    const server = createServer(
+    /* only a WebSocket handshake takes the 'upgrade' path where Node can tell (shouldUpgradeCallback) */
+    { shouldUpgradeCallback: isWebSocketUpgrade });
+    const serving = {
+        app,
+        drain,
+        env: options.env,
+        maxBody: options.maxRequestBodySize ?? DEFAULT_MAX_REQUEST_BODY,
+        onError: options.onError ?? reportTo(drain.settings?.logger ?? createLogger()),
+        server,
+    };
+    server.on("request", (incoming, res) => {
+        void handleRequest(serving, incoming, res);
+    });
+    const upgradeTimeout = options.upgradeTimeout ?? DEFAULT_UPGRADE_TIMEOUT;
+    server.on("upgrade", (incoming, socket, head) => {
+        /* a reset while the app is still deciding must not become an uncaught 'error' */
+        socket.on("error", () => socket.destroy());
+        if (upgradeTimeout > 0)
+            socket.setTimeout(upgradeTimeout, () => socket.destroy());
+        void handleUpgrade(serving, incoming, socket, head);
+    });
+    if (options.headersTimeout !== undefined)
+        server.headersTimeout = options.headersTimeout;
+    if (options.requestTimeout !== undefined)
+        server.requestTimeout = options.requestTimeout;
+    if (options.keepAliveTimeout !== undefined)
+        server.keepAliveTimeout = options.keepAliveTimeout;
+    server.shutdown = (timeout) => shutdown(server, drain, timeout);
+    server.listen(options.port ?? 0, options.hostname);
+    return server;
+}

package/dist/adapters/node/url.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The Request URL from what the client sent, spelled as Bun and Workers spell it. Anything that is
+ * not one URL (a second Host, a Host that is not `host[:port]`, a target form Fetch has no URL for)
+ * is `null`, and the request gets 400.
+ */
+import type { IncomingMessage } from "node:http";
+/**
+ * The request URL: the scheme from the socket's TLS state, the authority from `Host` (or from an
+ * absolute-form target, which wins per RFC 9112), the path and query from the target, parsed as
+ * Bun and Workers parse the same bytes. Any other target form, a second `Host`, and a
+ * `Host` that is not `host[:port]` are `null`: the request gets 400.
+ */
+export declare function nodeRequestUrl(incoming: IncomingMessage): string | null;

package/dist/adapters/node/url.js

@@ -0,0 +1,87 @@
+/** `host[:port]` as RFC 9110 allows it in `Host`: no userinfo, path or anything else that changes the URL. */
+const HOST = /^(?:\[[0-9A-Fa-f:.]+\]|[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?\.?)(?::\d{1,5})?$/;
+/** Already what URL parsing serializes: lowercase labels ending in a letter-led one, or a dotted quad. */
+const CANONICAL_HOST = /^(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)*[a-z](?:[a-z0-9-]*[a-z0-9])?\.?|(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d))(?::[1-9]\d{0,4})?$/;
+/** Characters URL parsing leaves alone in a path and query, on every runtime. */
+const PLAIN_TARGET = /^\/[\w\-.~!$&()*+,;=:@/?%]*$/;
+const ESCAPED_DOT = /%2e/i;
+/** A target URL parsing would leave exactly as it is: no dot segment, escaped or not. */
+function isPlainTarget(target) {
+    return PLAIN_TARGET.test(target) && !target.includes("/.") && !ESCAPED_DOT.test(target);
+}
+/** `URL.parse` without it: Node 20 lacks it. */
+function parseUrl(text) {
+    try {
+        return new URL(text);
+    }
+    catch {
+        /* not a URL: the answer, not a failure; the caller refuses it with a 400 */
+        return null;
+    }
+}
+/**
+ * The host as the Request URL carries it (Bun and Workers serialize it through URL parsing), or
+ * `null` when it is not one. The common spelling skips the parse; IPv4 shorthands, IPv6 literals,
+ * punycode, uppercase and a default port go through it.
+ */
+function canonicalHost(scheme, host) {
+    if (!HOST.test(host))
+        return null;
+    if (CANONICAL_HOST.test(host) && !host.includes("xn--")) {
+        const colon = host.lastIndexOf(":");
+        if (colon === -1)
+            return host;
+        const port = host.slice(colon + 1);
+        if (Number(port) <= 65535 && port !== (scheme === "https" ? "443" : "80"))
+            return host;
+    }
+    return parseUrl(`${scheme}://${host}/`)?.host ?? null;
+}
+function absoluteFormUrl(scheme, target) {
+    const lower = target.slice(0, 8).toLowerCase();
+    if (!lower.startsWith("http://") && !lower.startsWith("https://"))
+        return null;
+    const url = parseUrl(target);
+    if (url === null || url.username !== "" || url.password !== "" || !HOST.test(url.host))
+        return null;
+    return `${scheme}://${url.host}${url.pathname}${url.search}`;
+}
+/** The one Host header's value, `undefined` without one, `null` with several: the request is ambiguous. */
+function soleHost(raw) {
+    let host;
+    for (let i = 0; i < raw.length; i += 2) {
+        const name = raw[i];
+        if (name.length !== 4 || name.toLowerCase() !== "host")
+            continue;
+        if (host !== undefined)
+            return null;
+        host = raw[i + 1];
+    }
+    return host;
+}
+/**
+ * The request URL: the scheme from the socket's TLS state, the authority from `Host` (or from an
+ * absolute-form target, which wins per RFC 9112), the path and query from the target, parsed as
+ * Bun and Workers parse the same bytes. Any other target form, a second `Host`, and a
+ * `Host` that is not `host[:port]` are `null`: the request gets 400.
+ */
+export function nodeRequestUrl(incoming) {
+    const scheme = incoming.socket.encrypted === true ? "https" : "http";
+    /* a request node:http parsed always has its target and method */
+    const target = incoming.url;
+    const header = soleHost(incoming.rawHeaders);
+    if (header === null)
+        return null;
+    if (target.charCodeAt(0) !== 47)
+        return absoluteFormUrl(scheme, target);
+    const given = header === undefined || header === "" ? (incoming.httpVersion === "1.0" ? "localhost" : null) : header;
+    const host = given === null ? null : canonicalHost(scheme, given);
+    if (host === null)
+        return null;
+    if (isPlainTarget(target))
+        return `${scheme}://${host}${target}`;
+    /* never `new URL(target, base)`: a `//x/y` target would become the host. A canonical host and a
+     * target starting with `/` always parse. */
+    const url = new URL(`${scheme}://${host}${target}`);
+    return `${scheme}://${host}${url.pathname}${url.search}`;
+}

package/dist/adapters/serve.d.ts

@@ -0,0 +1,36 @@
+/** The largest request body a read accepts by default, in bytes: Bun's own default, applied on Node too. */
+export declare const DEFAULT_MAX_REQUEST_BODY: number;
+type FetchApp<TEnv> = {
+    fetch(request: Request, env: TEnv): Response | Promise<Response>;
+};
+export type ServeOptions<TEnv> = {
+    /** Handed to the app as `ctx.env`. Default `{}`. */
+    env?: TEnv;
+    /** Default `0.0.0.0`: every interface. */
+    hostname?: string;
+    /** Default 3000; `0` picks a free port. */
+    port?: number;
+    /** The largest request body a read accepts, in bytes; over it the answer is 413. Default 128 MiB. */
+    maxRequestBodySize?: number;
+    /** Errors the adapter could not hand to the app (it then answers 500). Default on Node: the app's logger. */
+    onError?: (error: unknown) => void;
+    /** Node only: `server.headersTimeout`, in ms. */
+    headersTimeout?: number;
+    /** Node only: `server.requestTimeout`, in ms. */
+    requestTimeout?: number;
+    /** Node only: `server.keepAliveTimeout`, in ms. */
+    keepAliveTimeout?: number;
+    /** Node only: how long an upgrade request may take to become a WebSocket or be answered, in ms. Default 30 000. */
+    upgradeTimeout?: number;
+};
+export type ServeHandle = {
+    /** Stop accepting connections and let in-flight requests finish for up to `timeout` ms (default 1000); then cut every connection. */
+    close(timeout?: number): Promise<void>;
+    readonly hostname: string;
+    readonly port: number;
+    readonly runtime: "bun" | "node";
+    /** Where a client on this machine reaches the server. */
+    readonly url: string;
+};
+export declare function serve<TEnv>(app: FetchApp<TEnv>, options?: ServeOptions<TEnv>): Promise<ServeHandle>;
+export {};

package/dist/adapters/serve.js

@@ -0,0 +1,52 @@
+/**
+ * `serve(app, options)`: run the app on the runtime this process is, through that runtime's
+ * adapter. A plain function the app module imports (`@lovrozagar/honey/serve`); nothing registers
+ * itself (H23). On Cloudflare Workers the exported app is the Worker, so there is nothing to start.
+ */
+import { detectRuntime } from "../runtime/detect-runtime.js";
+/** The largest request body a read accepts by default, in bytes: Bun's own default, applied on Node too. */
+export const DEFAULT_MAX_REQUEST_BODY = 128 * 1024 * 1024;
+const DEFAULT_CLOSE_TIMEOUT = 1_000;
+/** The address a local client dials: the loopback for a wildcard bind, brackets around IPv6. */
+function urlOf(hostname, port) {
+    const host = hostname === "0.0.0.0" || hostname === "::" ? "127.0.0.1" : hostname;
+    return `http://${host.includes(":") ? `[${host}]` : host}:${port}`;
+}
+export async function serve(app, options = {}) {
+    const runtime = detectRuntime();
+    if (runtime === "cloudflare") {
+        throw new Error("serve() does not run on Cloudflare Workers: export the app instead (`export default app`)");
+    }
+    const settings = {
+        ...options,
+        env: options.env ?? {},
+        hostname: options.hostname ?? "0.0.0.0",
+        maxRequestBodySize: options.maxRequestBodySize ?? DEFAULT_MAX_REQUEST_BODY,
+        port: options.port ?? 3000,
+    };
+    const listener = runtime === "bun" ? await serveBun(app, settings) : await serveNode(app, settings);
+    return {
+        close: (timeout = DEFAULT_CLOSE_TIMEOUT) => listener.close(timeout),
+        hostname: settings.hostname,
+        port: listener.port,
+        runtime,
+        url: urlOf(settings.hostname, listener.port),
+    };
+}
+/* each adapter loads only on its own runtime, so the other's builtins are never imported */
+async function serveBun(app, settings) {
+    const { serve: bunServe } = await import("./bun/serve.js");
+    return bunServe(app, settings);
+}
+async function serveNode(app, settings) {
+    const { serve: nodeServe } = await import("./node/serve.js");
+    const server = nodeServe(app, settings);
+    await new Promise((resolve, reject) => {
+        server.once("listening", resolve);
+        server.once("error", reject);
+    });
+    return {
+        close: (timeout) => server.shutdown(timeout),
+        port: server.address().port,
+    };
+}

package/dist/build/artifacts.d.ts

@@ -0,0 +1,34 @@
+import { generateOpenApi } from "../openapi/generate.ts";
+import type { InvalidateCheckConfig } from "../routing/invalidate-check.ts";
+import type { EffectConverter } from "../schema/to-json-schema.ts";
+import { type ResolvedHoneyConfig, type ResolvedOpenApiOutput } from "./config.ts";
+import { type Source } from "./source.ts";
+/** This module's path, which generate.ts loads into the app's graph. */
+export declare const ARTIFACTS: string;
+export type Clients = typeof import("@lovrozagar/honey-clients");
+/** Where a generation's diagnostics go, one line each. */
+export type Report = (message: string) => void;
+/** The document `entry` describes, sanitized as it asks. */
+export declare function documentOf(app: Parameters<typeof generateOpenApi>[0], entry: ResolvedOpenApiOutput, invalidate: InvalidateCheckConfig | undefined, effect: EffectConverter | undefined): object;
+type Run = {
+    codegen: Clients;
+    report: Report;
+    root: string;
+};
+/**
+ * What a generation reads, and, on a `first` pass whose documented app loads the tree it writes, that tree when it
+ * changed: to be written first and the pass redone over it on a fresh graph.
+ */
+export declare function prepare(config: ResolvedHoneyConfig, run: Pick<Run, "codegen" | "root"> & {
+    first: boolean;
+}): Promise<{
+    rewrite: [string, string] | undefined;
+    source: Source;
+}>;
+/** Every artifact `config` asks for from `source`, by its path from the project root. */
+export declare function artifactsOf(config: ResolvedHoneyConfig, run: Run, source: Source): Promise<[string, string][]>;
+/** A virtual module's code: the route tree, the manifest, or the first OpenAPI document. */
+export declare function virtualCode(kind: "manifest" | "openApi" | "routes", config: ResolvedHoneyConfig, run: Pick<Run, "root"> & {
+    codegen: () => Promise<Clients>;
+}): Promise<string>;
+export {};