@lovrozagar/honey 0.7.3 → 1.0.0-rc.1

package/bin/honey.js

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
-import { spawnSync } from "node:child_process"
-import { existsSync } from "node:fs"
-import { basename } from "node:path"
+// The honey bin (bit 19 h2), honey-clients's twin. A repository checkout (marked by tsconfig.json, which is not
+// published) runs the TypeScript source, through jiti on Node, so a stale dist/ never runs; an installed package runs
+// the compiled JavaScript on any runtime (the tarball ships dist/, not src/).
+import { spawn } from "node:child_process"
+import { existsSync, readFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import { basename, dirname, join } from "node:path"
 import { fileURLToPath } from "node:url"
 
-/* Bun runs the TypeScript source; an installed package on any other runtime runs the compiled
- * JavaScript. A repository checkout (marked by tsconfig.json, which is not published) runs the
- * source on Node too, through jiti, so `honey generate` never runs a stale dist/. */
 const isBun = typeof globalThis.Bun !== "undefined"
 const checkout = existsSync(new URL("../tsconfig.json", import.meta.url))
 
-/* `bun run generate` starts this file through its node shebang. The app is meant for Bun, though
- * (text-module imports such as `.md`, Bun-only APIs), so hand over to the Bun that started us,
- * which `bun run` and `bunx` name in npm_execpath. */
+// `bun run` and `bunx` start this file through its node shebang, while what they run is meant for Bun: hand over to
+// the Bun that started us, which they name in npm_execpath. Once, never again in the child.
 function invokingBun() {
 	if (isBun || process.env.HONEY_NO_BUN_HANDOFF === "1") return null
 	if (!process.env.npm_config_user_agent?.startsWith("bun/")) return null
@@ -21,28 +21,88 @@ function invokingBun() {
 	return bun
 }
 
-const bun = invokingBun()
-if (bun) {
-	const run = spawnSync(bun, [fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
-		env: { ...process.env, HONEY_NO_BUN_HANDOFF: "1" },
+// The handoff: Bun runs this file with our arguments and `env` over ours; a signal we get is passed on to it, and we
+// end as it ended, its exit code or the same signal.
+function handOff(bun, env = {}) {
+	// Forwarders first: a signal landing as spawn returns would otherwise end this process by its default action,
+	// orphaning the child. A handler runs from the event loop, after this block, so `child` is set by then.
+	let child
+	const forward = (signal) => child.kill(signal)
+	for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(signal, forward)
+	child = spawn(bun, [fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+		env: { ...process.env, ...env, HONEY_NO_BUN_HANDOFF: "1" },
 		stdio: "inherit",
 	})
-	if (run.error) throw run.error
-	if (run.signal) process.kill(process.pid, run.signal)
-	process.exit(run.status ?? 1)
-} else if (isBun) {
-	await import("../src/cli.ts")
-} else if (checkout) {
-	const { createJiti } = await import("jiti")
-	await createJiti(import.meta.url).import("../src/cli.ts")
-} else {
+	child.on("error", (error) => {
+		console.error(`honey: could not start ${bun}: ${error.message}`)
+		process.exit(1)
+	})
+	child.on("exit", (code, signal) => {
+		if (signal) {
+			for (const each of ["SIGINT", "SIGTERM", "SIGHUP"]) process.off(each, forward)
+			process.kill(process.pid, signal)
+			return
+		}
+		process.exit(code ?? 1)
+	})
+}
+
+// A checkout's specifier for `name` mapped to its source: each export's `honey-source` file. The published exports
+// send `default` to dist/, which a checkout does not build.
+function sourceAliases(name) {
+	const root = dirname(createRequire(import.meta.url).resolve(`${name}/package.json`))
+	const { exports = {} } = JSON.parse(readFileSync(join(root, "package.json"), "utf8"))
+	return Object.fromEntries(
+		Object.entries(exports)
+			.filter(([, target]) => typeof target === "object" && target["honey-source"])
+			.map(([subpath, target]) => [name + subpath.slice(1), join(root, target["honey-source"])]),
+	)
+}
+
+// A checkout on Bun runs its source natively, under the honey-source condition: honey-clients, and an app's honey,
+// resolve to source then, not to the unbuilt dist/. Set through BUN_OPTIONS when the caller did not, so every
+// generation child inherits it.
+const SOURCE_CONDITION = "--conditions=honey-source"
+const unconditioned = isBun && checkout && !process.execArgv.includes(SOURCE_CONDITION)
+// The hand-off's backstop: its child carries HONEY_BUN_HANDOFF, the depth of hand-offs before it. A child that would
+// hand off again (the condition set but not in its execArgv) refuses instead of re-running itself without end.
+const handOffDepth = Number(process.env.HONEY_BUN_HANDOFF ?? 0)
+
+async function entry() {
+	if (checkout) {
+		/* never jiti on Bun: its Babel, loaded on any fs-cache miss, hooks Error.prepareStackTrace, and Bun's own then
+		 * throws "First argument must be an Error object" at a captureStackTrace on a non-Error (bit 20 k-fix) */
+		if (isBun) return import("../src/build/cli.ts")
+		const { createJiti } = await import("jiti")
+		const alias = sourceAliases("@lovrozagar/honey-clients")
+		return createJiti(import.meta.url, { alias, tryNative: false }).import("../src/build/cli.ts")
+	}
 	try {
-		await import("../dist/cli.js")
-	} catch (err) {
-		if (err?.code === "ERR_MODULE_NOT_FOUND" && String(err.url).endsWith("/dist/cli.js")) {
-			console.error("honey: dist/ is missing from this install. Reinstall @lovrozagar/honey, or run honey with Bun.")
+		return await import("../dist/build/cli.js")
+	} catch (error) {
+		if (error?.code === "ERR_MODULE_NOT_FOUND" && String(error.url).endsWith("/dist/build/cli.js")) {
+			console.error("honey: dist/ is missing from this install. Reinstall it, or run it with Bun.")
 			process.exit(1)
 		}
-		throw err
+		throw error
 	}
 }
+
+const bun = invokingBun()
+if (bun) handOff(bun)
+else if (unconditioned && handOffDepth >= 1) {
+	console.error("honey: Bun hand-off loop: --conditions=honey-source not visible after re-exec")
+	process.exit(1)
+} else if (unconditioned)
+	handOff(process.execPath, {
+		BUN_OPTIONS: `${process.env.BUN_OPTIONS ?? ""} ${SOURCE_CONDITION}`.trim(),
+		HONEY_BUN_HANDOFF: String(handOffDepth + 1),
+	})
+else {
+	const { main } = await entry()
+	const io = { err: (text) => process.stderr.write(text), out: (text) => process.stdout.write(text) }
+	const code = await main(process.argv.slice(2), io)
+	/* the app may leave a timer or a socket open: the run is over once main returns, its output flushed */
+	for (const stream of [process.stdout, process.stderr]) await new Promise((done) => stream.write("", done))
+	process.exit(code)
+}

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

@@ -0,0 +1,18 @@
+type FetchApp<TEnv> = {
+    fetch(request: Request, env: TEnv): Response | Promise<Response>;
+};
+export type BunServeOptions<TEnv> = {
+    env: TEnv;
+    hostname: string;
+    maxRequestBodySize: number;
+    /** Errors the app could not answer; Bun then answers 500. Unset, Bun's own error handling applies. */
+    onError?: (error: unknown) => void;
+    port: number;
+};
+export type BunListener = {
+    /** Let in-flight requests finish for up to `timeout` ms, then cut every connection. */
+    close(timeout: number): Promise<void>;
+    readonly port: number;
+};
+export declare function serve<TEnv>(app: FetchApp<TEnv>, options: BunServeOptions<TEnv>): BunListener;
+export {};

package/dist/adapters/bun/serve.js

@@ -0,0 +1,89 @@
+/**
+ * The Bun adapter: `Bun.serve` with the app's fetch, the server passed in the env so `ctx.ip` and
+ * the WebSocket upgrade read it. Bun takes the `websocket` handlers at creation, so a honey app's
+ * ws adapter is fixed here: its own `bunWebSocket()`, or one set before `serve()`.
+ *
+ * A known residual: when a response body stream errors (a proxied upstream cut by its idle
+ * timeout, a producer that fails), Bun itself prints the error to stderr, outside both the
+ * `error` handler and the app's logger. The stream erroring is correct, since closing it would
+ * pass a cut body off as complete; redirecting Bun's own diagnostic would mean wrapping every
+ * response body, a per-response cost for a sink change, so it is left as Bun reports it.
+ */
+import { HoneyError } from "../../errors/error.js";
+import { GRAPH } from "../../routing/app.js";
+import { createLogger } from "../../telemetry/logger.js";
+import { bunWebSocket } from "../../ws/bun.js";
+/** Settle when `work` does or after `ms`, whichever is first; the timer never outlives it. */
+async function within(work, ms) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve("timeout"), ms);
+    });
+    try {
+        return await Promise.race([work.then(() => "done"), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const SWAPPED = "honey: app.wsAdapter() changed after serve(app) on Bun, where Bun.serve took the first adapter's handlers: set app.wsAdapter() before serve()";
+/** The honey app's settings, where its ws adapter lives; `null` for a plain fetch handler. */
+function settingsOf(app) {
+    return app[GRAPH]?.settings ?? null;
+}
+/** The app's ws adapter for Bun: the one it was given, else `bunWebSocket()`, set on the app. */
+function bunAdapterOf(settings) {
+    settings.wsAdapter ??= bunWebSocket();
+    if (settings.wsAdapter.runtime !== "bun") {
+        throw new Error("serve() on Bun needs a bunWebSocket() adapter, but app.wsAdapter() was given another");
+    }
+    return settings.wsAdapter;
+}
+function isWebSocketUpgrade(request) {
+    return request.headers.get("upgrade")?.toLowerCase() === "websocket";
+}
+/** Bun expects nothing back from a fetch that upgraded the request. */
+/** The default 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");
+}
+function unlessUpgraded(response) {
+    return response.status === 101 ? undefined : response;
+}
+export function serve(app, options) {
+    const settings = settingsOf(app);
+    /* no onError: the app's logger, never Bun's own error page (a stack in development, outside the sink) */
+    const onError = options.onError ?? reportTo(settings?.logger ?? createLogger());
+    const adapter = settings === null ? null : bunAdapterOf(settings);
+    /* the server is the same object on every request: the env carrying it is built once */
+    let env;
+    const server = globalThis.Bun.serve({
+        error: (error) => {
+            onError(error);
+            return new Response("Internal Server Error", { status: 500 });
+        },
+        fetch: (request, bun) => {
+            /* an adapter set after Bun.serve took the first one's handlers can never upgrade: say so */
+            if (settings !== null && settings.wsAdapter !== adapter && isWebSocketUpgrade(request))
+                throw new Error(SWAPPED);
+            const answer = app.fetch(request, (env ??= { ...options.env, server: bun }));
+            return answer instanceof Promise ? answer.then(unlessUpgraded) : unlessUpgraded(answer);
+        },
+        hostname: options.hostname,
+        maxRequestBodySize: options.maxRequestBodySize,
+        port: options.port,
+        ...(adapter === null ? {} : { websocket: adapter.websocket }),
+    });
+    return {
+        async close(timeout) {
+            /* graceful first; idle keep-alive connections would otherwise keep serving, so close them
+             * now and again once the in-flight requests have finished and left theirs idle */
+            const graceful = server.stop(false);
+            server.closeIdleConnections();
+            if ((await within(graceful, timeout)) === "timeout")
+                await server.stop(true);
+            server.closeIdleConnections();
+        },
+        port: server.port,
+    };
+}

package/dist/adapters/fetch-request.d.ts

@@ -0,0 +1,20 @@
+/** A request view (the Node adapter's) hands over the Fetch `Request` behind it under this key. */
+export declare const TO_FETCH_REQUEST: unique symbol;
+/**
+ * The Fetch `Request` for `req`. On Bun and Workers that is `req` itself. On Node, `ctx.req` is a
+ * lighter view of the incoming message, so `new Request(ctx.req)`, `fetch(ctx.req)` and
+ * `instanceof Request` need this first. The view builds its Request once, which then owns the body.
+ */
+export declare function toFetchRequest(req: Request): Request;
+/**
+ * A request view (the Node adapter's) swaps its body for another stream under this key and stays
+ * the view. Not TO_FETCH_REQUEST: that builds the Fetch Request behind the view, which then owns
+ * the body; this keeps the view, so no Request is built unless something later asks for one, and
+ * then it carries the swapped body.
+ */
+export declare const REPLACE_BODY: unique symbol;
+/**
+ * `req` with `body` in place of its own body: a request view swaps it in place and is returned
+ * as is; a Fetch Request becomes one new Request with the same method, URL, headers and signal.
+ */
+export declare function withBody(req: Request, body: ReadableStream<Uint8Array>): Request;

package/dist/adapters/fetch-request.js

@@ -0,0 +1,29 @@
+/** A request view (the Node adapter's) hands over the Fetch `Request` behind it under this key. */
+export const TO_FETCH_REQUEST = /* @__PURE__ */ Symbol.for("honey.toFetchRequest");
+/**
+ * The Fetch `Request` for `req`. On Bun and Workers that is `req` itself. On Node, `ctx.req` is a
+ * lighter view of the incoming message, so `new Request(ctx.req)`, `fetch(ctx.req)` and
+ * `instanceof Request` need this first. The view builds its Request once, which then owns the body.
+ */
+export function toFetchRequest(req) {
+    const own = req[TO_FETCH_REQUEST];
+    return typeof own === "function" ? own.call(req) : req;
+}
+/**
+ * A request view (the Node adapter's) swaps its body for another stream under this key and stays
+ * the view. Not TO_FETCH_REQUEST: that builds the Fetch Request behind the view, which then owns
+ * the body; this keeps the view, so no Request is built unless something later asks for one, and
+ * then it carries the swapped body.
+ */
+export const REPLACE_BODY = /* @__PURE__ */ Symbol.for("honey.replaceBody");
+/**
+ * `req` with `body` in place of its own body: a request view swaps it in place and is returned
+ * as is; a Fetch Request becomes one new Request with the same method, URL, headers and signal.
+ */
+export function withBody(req, body) {
+    const swap = req[REPLACE_BODY];
+    if (typeof swap !== "function")
+        return new Request(req, { body, duplex: "half" });
+    swap.call(req, body);
+    return req;
+}

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

@@ -0,0 +1,27 @@
+import type { IncomingMessage } from "node:http";
+/**
+ * Fetch's `Headers` over Node's parsed headers. `get` and `has` read maps over what Node parsed;
+ * a real `Headers` is built only when something iterates or writes, and answers from then on.
+ */
+export declare class NodeHeaders {
+    #private;
+    constructor(incoming: IncomingMessage);
+    /**
+     * Every value, joined as Fetch joins them. Node's `headers` map keeps only the first
+     * `Authorization`, `Host`, …; the raw pairs keep them all, so the answer does not change once
+     * something iterates. Built from `rawHeaders`, never `headersDistinct`: Bun's node:http before
+     * 1.4 has no `headersDistinct`.
+     */
+    get(name: string): string | null;
+    has(name: string): boolean;
+    append(name: string, value: string): void;
+    delete(name: string): void;
+    set(name: string, value: string): void;
+    getSetCookie(): string[];
+    forEach(callback: (value: string, key: string, parent: Headers) => void, thisArg?: unknown): void;
+    keys(): HeadersIterator<string>;
+    values(): HeadersIterator<string>;
+    entries(): HeadersIterator<[string, string]>;
+    [Symbol.iterator](): HeadersIterator<[string, string]>;
+    get [Symbol.toStringTag](): string;
+}

package/dist/adapters/node/headers.js

@@ -0,0 +1,86 @@
+/** Every raw header value under its lowercased name, in order: what `headersDistinct` holds on Node. */
+function distinctOf(raw) {
+    const all = new Map();
+    for (let i = 0; i < raw.length; i += 2) {
+        const key = raw[i].toLowerCase();
+        const values = all.get(key);
+        if (values === undefined)
+            all.set(key, [raw[i + 1]]);
+        else
+            values.push(raw[i + 1]);
+    }
+    return all;
+}
+/**
+ * Fetch's `Headers` over Node's parsed headers. `get` and `has` read maps over what Node parsed;
+ * a real `Headers` is built only when something iterates or writes, and answers from then on.
+ */
+export class NodeHeaders {
+    #incoming;
+    #distinct = null;
+    #native = null;
+    constructor(incoming) {
+        this.#incoming = incoming;
+    }
+    /**
+     * Every value, joined as Fetch joins them. Node's `headers` map keeps only the first
+     * `Authorization`, `Host`, …; the raw pairs keep them all, so the answer does not change once
+     * something iterates. Built from `rawHeaders`, never `headersDistinct`: Bun's node:http before
+     * 1.4 has no `headersDistinct`.
+     */
+    get(name) {
+        if (this.#native !== null)
+            return this.#native.get(name);
+        this.#distinct ??= distinctOf(this.#incoming.rawHeaders);
+        const values = this.#distinct.get(name.toLowerCase());
+        if (values === undefined)
+            return null;
+        return values.length === 1 ? values[0] : values.join(", ");
+    }
+    has(name) {
+        if (this.#native !== null)
+            return this.#native.has(name);
+        return Object.hasOwn(this.#incoming.headers, name.toLowerCase());
+    }
+    append(name, value) {
+        this.#ensureNative().append(name, value);
+    }
+    delete(name) {
+        this.#ensureNative().delete(name);
+    }
+    set(name, value) {
+        this.#ensureNative().set(name, value);
+    }
+    getSetCookie() {
+        return this.#ensureNative().getSetCookie();
+    }
+    forEach(callback, thisArg) {
+        this.#ensureNative().forEach(callback, thisArg);
+    }
+    keys() {
+        return this.#ensureNative().keys();
+    }
+    values() {
+        return this.#ensureNative().values();
+    }
+    entries() {
+        return this.#ensureNative().entries();
+    }
+    [Symbol.iterator]() {
+        return this.#ensureNative()[Symbol.iterator]();
+    }
+    get [Symbol.toStringTag]() {
+        return "Headers";
+    }
+    /* from the raw pairs, so every repeated value survives */
+    #ensureNative() {
+        if (this.#native !== null)
+            return this.#native;
+        const headers = new Headers();
+        const raw = this.#incoming.rawHeaders;
+        for (let i = 0; i < raw.length; i += 2)
+            headers.append(raw[i], raw[i + 1]);
+        this.#native = headers;
+        return headers;
+    }
+}

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

@@ -0,0 +1,16 @@
+/**
+ * The `node:http` → Fetch side of the Node adapter: a Request-shaped view of the IncomingMessage
+ * that builds a real `Request` only when something needs one (formData, blob, clone,
+ * `toFetchRequest`).
+ */
+import type { IncomingMessage } from "node:http";
+/** The serve side calls this when the response closed before it finished: client gone, or shutdown. */
+export declare const ABORT_REQUEST: unique symbol;
+/** True once a body read went over the cap: the body is left on the socket, so the connection is not reused. */
+export declare const BODY_OVERFLOW: unique symbol;
+/**
+ * The Request the app sees for `incoming`. It is not a Fetch `Request` (`instanceof Request` is
+ * false): `toFetchRequest()` gives the real one. A body over `maxBody` bytes fails its read with
+ * 413; `0` turns the cap off.
+ */
+export declare function nodeRequest(incoming: IncomingMessage, url: string, maxBody: number): Request;

package/dist/adapters/node/request.js

@@ -0,0 +1,214 @@
+import { Readable } from "node:stream";
+import { PEER_ADDRESS } from "../../context/peer.js";
+import { EK, HoneyError } from "../../errors/error.js";
+import { NODE_OUTBOUND } from "../../response/builder.js";
+import { REPLACE_BODY, TO_FETCH_REQUEST } from "../fetch-request.js";
+import { NodeHeaders } from "./headers.js";
+/** The serve side calls this when the response closed before it finished: client gone, or shutdown. */
+export const ABORT_REQUEST = /* @__PURE__ */ Symbol("honey.abortRequest");
+/** True once a body read went over the cap: the body is left on the socket, so the connection is not reused. */
+export const BODY_OVERFLOW = /* @__PURE__ */ Symbol("honey.bodyOverflow");
+/** Request-shaped view of an IncomingMessage: no `new Request()` until something needs the real one. */
+class NodeRequest {
+    headers;
+    method;
+    url;
+    #incoming;
+    #hasBody;
+    #maxBody;
+    #received = 0;
+    #overflow = false;
+    #bodyUsed = false;
+    #stream;
+    #fetch;
+    #controller;
+    /* the abort that came before anything read `signal` */
+    #abortReason;
+    constructor(incoming, url, maxBody) {
+        this.#incoming = incoming;
+        this.#maxBody = maxBody;
+        this.url = url;
+        this.method = incoming.method;
+        this.headers = new NodeHeaders(incoming);
+        this.#hasBody = this.method !== "GET" && this.method !== "HEAD";
+    }
+    get cache() {
+        return "default";
+    }
+    get credentials() {
+        return "same-origin";
+    }
+    get destination() {
+        return "";
+    }
+    get duplex() {
+        return "half";
+    }
+    get integrity() {
+        return "";
+    }
+    get keepalive() {
+        return false;
+    }
+    get mode() {
+        return "cors";
+    }
+    get redirect() {
+        return "follow";
+    }
+    get referrer() {
+        return "about:client";
+    }
+    get referrerPolicy() {
+        return "";
+    }
+    get [NODE_OUTBOUND]() {
+        return true;
+    }
+    /** The socket peer, for `ctx.ip`. */
+    get [PEER_ADDRESS]() {
+        return this.#incoming.socket.remoteAddress ?? null;
+    }
+    get [BODY_OVERFLOW]() {
+        return this.#overflow;
+    }
+    get body() {
+        if (!this.#hasBody)
+            return null;
+        /* once a Fetch Request owns the stream, it is the body */
+        if (this.#fetch !== undefined)
+            return this.#fetch.body;
+        this.#stream ??= this.#cappedStream();
+        return this.#stream;
+    }
+    get bodyUsed() {
+        if (this.#fetch !== undefined)
+            return this.#fetch.bodyUsed;
+        return this.#bodyUsed || (this.#hasBody && this.#incoming.readableEnded);
+    }
+    /** Aborts when the response closes before it finished: the client left, or the server shut down. */
+    get signal() {
+        if (this.#controller === undefined) {
+            this.#controller = new AbortController();
+            if (this.#abortReason !== undefined)
+                this.#controller.abort(this.#abortReason.reason);
+        }
+        return this.#controller.signal;
+    }
+    [ABORT_REQUEST](reason = new DOMException("The client disconnected", "AbortError")) {
+        if (this.#controller !== undefined)
+            this.#controller.abort(reason);
+        else
+            this.#abortReason ??= { reason };
+    }
+    /** Swap the body for `body` (bodyLimit's counted stream) and stay the view: nothing has read it yet. */
+    [REPLACE_BODY](body) {
+        this.#stream = body;
+    }
+    /** The real Fetch `Request` behind the view: `new Request(x)`, `fetch(x)` and `instanceof` take it. */
+    [TO_FETCH_REQUEST]() {
+        return this.#asFetch();
+    }
+    async arrayBuffer() {
+        const buf = await this.#read();
+        return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+    }
+    async bytes() {
+        const buf = await this.#read();
+        return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+    }
+    /** As Fetch: an empty body is a `SyntaxError`, not `null`. */
+    async json() {
+        return JSON.parse(await this.text());
+    }
+    async text() {
+        return (await this.#read()).toString("utf8");
+    }
+    blob() {
+        return this.#asFetch().blob();
+    }
+    clone() {
+        return this.#asFetch().clone();
+    }
+    formData() {
+        return this.#asFetch().formData();
+    }
+    #asFetch() {
+        this.#fetch ??= new Request(this.url, {
+            body: this.body,
+            duplex: "half",
+            /* every value of a repeated header, as the view reports them */
+            headers: [...this.headers],
+            method: this.method,
+            signal: this.signal,
+        });
+        return this.#fetch;
+    }
+    /** Count bytes against the cap; over it, the read fails with 413 and the rest stays unread. */
+    #count(n) {
+        this.#received += n;
+        if (this.#maxBody > 0 && this.#received > this.#maxBody)
+            this.#tooLarge();
+    }
+    /** A declared length over the cap fails before anything is read. */
+    #checkDeclared() {
+        if (this.#maxBody > 0 && Number(this.#incoming.headers["content-length"]) > this.#maxBody)
+            this.#tooLarge();
+    }
+    #tooLarge() {
+        this.#overflow = true;
+        throw new HoneyError({ errorKey: EK.content_too_large, status: "content_too_large" });
+    }
+    #cappedStream() {
+        /* Node's web stream and the DOM ReadableStream brands do not overlap */
+        if (this.#maxBody <= 0)
+            return Readable.toWeb(this.#incoming);
+        const chunks = this.#incoming[Symbol.asyncIterator]();
+        return new ReadableStream({
+            cancel: async () => {
+                await chunks.return?.();
+            },
+            pull: async (controller) => {
+                try {
+                    this.#checkDeclared();
+                    const { done, value } = (await chunks.next());
+                    if (done === true)
+                        return controller.close();
+                    this.#count(value.byteLength);
+                    controller.enqueue(value);
+                }
+                catch (error) {
+                    controller.error(error);
+                    void chunks.return?.();
+                }
+            },
+        });
+    }
+    async #read() {
+        /* a request without a body reads as empty, any number of times */
+        if (!this.#hasBody)
+            return Buffer.alloc(0);
+        if (this.bodyUsed)
+            throw new TypeError("Body has already been used");
+        this.#bodyUsed = true;
+        if (this.#fetch !== undefined)
+            return Buffer.from(await this.#fetch.arrayBuffer());
+        if (this.#stream !== undefined)
+            return Buffer.from(await new Response(this.#stream).arrayBuffer());
+        this.#checkDeclared();
+        const chunks = [];
+        for await (const chunk of this.#incoming) {
+            this.#count(chunk.byteLength);
+            chunks.push(chunk);
+        }
+        return chunks.length === 1 ? chunks[0] : Buffer.concat(chunks);
+    }
+}
+/**
+ * The Request the app sees for `incoming`. It is not a Fetch `Request` (`instanceof Request` is
+ * false): `toFetchRequest()` gives the real one. A body over `maxBody` bytes fails its read with
+ * 413; `0` turns the cap off.
+ */
+export function nodeRequest(incoming, url, maxBody) {
+    return new NodeRequest(incoming, url, maxBody);
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Fetch → `node:http`: a Response written to a ServerResponse. Headers that described another
+ * connection are dropped, a stream's declared length is never trusted, a HoneyResponse goes out
+ * from its bytes and header map with no Fetch Response built.
+ */
+import type { ServerResponse } from "node:http";
+/**
+ * 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 declare function writeResponse(response: Response, res: ServerResponse, head?: boolean): Promise<void>;