@nifrajs/node 2.13.0 → 3.1.0

package/dist/index.js

@@ -19,13 +19,16 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  * `Request`/`Response`, plus a Bun-`listen()`-style graceful `stop()`.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
+import { constants as FS } from "node:fs";
 import { open, realpath } from "node:fs/promises";
 import { createServer, } from "node:http";
 import { extname, isAbsolute, relative, resolve, sep } from "node:path";
-import { Readable } from "node:stream";
 import { fileURLToPath } from "node:url";
 // srvx's lazy spec-shaped Response - see nodeOutcomeToResponse for why the bridge uses it.
 import { FastResponse } from "srvx/node";
+import { NODE_BRIDGE_MARKER_KEYS } from "./generated/bridge-markers.js";
+import { claimableWebStream, claimNodeStream } from "./node-stream.js";
+const RESOLVE_NODE_MOUNT = Symbol.for(NODE_BRIDGE_MARKER_KEYS.resolveNodeMount);
 /**
  * The `Content-Type` the host runtime's `Response.json` emits - Node's undici uses `application/json`,
  * Bun uses `application/json;charset=utf-8`. Probed once at module load (zero per-request cost) so the
@@ -34,12 +37,12 @@ import { FastResponse } from "srvx/node";
 const JSON_CONTENT_TYPE = Response.json(0).headers.get("content-type") ?? "application/json";
 const INTERNAL_ERROR_BODY = '{"ok":false,"error":"internal_error"}';
 const EMPTY_BUFFER = Buffer.alloc(0);
-const NODE_RESPONSE_BODY = Symbol.for("nifra.response.body");
-const RESPONSE_RESULT = Symbol.for("nifra.response.result");
+const NODE_RESPONSE_BODY = Symbol.for(NODE_BRIDGE_MARKER_KEYS.responseBody);
+const RESPONSE_RESULT = Symbol.for(NODE_BRIDGE_MARKER_KEYS.responseResult);
 /** Core's proof that a header record's names are already the lowercase wire spelling - set once per
  * request by the native response walk, which had to look at the same keys anyway. Declared by key
  * rather than imported: the same cross-package convention as the two marks above. */
-const LOWERCASE_HEADER_KEYS = Symbol.for("nifra.headers.lowercase");
+const LOWERCASE_HEADER_KEYS = Symbol.for(NODE_BRIDGE_MARKER_KEYS.lowercaseHeaderKeys);
 function isBodylessStatus(status) {
     return status === 204 || status === 205 || status === 304;
 }
@@ -59,6 +62,19 @@ function normalizeBodylessResponse(response) {
 const NODE_OUTCOME_RUNTIME = {
     toOutcome(result, set) {
         if (isResponseResult(result)) {
+            // A plain render never builds a `Response` - same `kind: "json"` lane a handler's return takes.
+            const plain = result.plain;
+            if (plain !== undefined) {
+                return {
+                    kind: "json",
+                    status: plain.status,
+                    headers: plainRenderHeaders(plain.headers, set._headers),
+                    cookies: set._cookies,
+                    body: plain.body === undefined || isBodylessStatus(plain.status)
+                        ? null
+                        : JSON.stringify(plain.body),
+                };
+            }
             const body = result.toNodeBody?.();
             if (body !== undefined) {
                 return {
@@ -91,6 +107,14 @@ const NODE_OUTCOME_RUNTIME = {
     }),
     jsonContentType: JSON_CONTENT_TYPE,
 };
+/** Mirror of core's `plainRenderHeaders`: the render's own headers on top of `c.set.headers`, always
+ * a fresh record when it has any, because the writers below mutate what they are handed and a
+ * `status(...)` value is commonly hoisted and reused across requests. */
+function plainRenderHeaders(own, ambient) {
+    if (own === undefined)
+        return ambient;
+    return ambient === undefined ? { ...own } : { ...ambient, ...own };
+}
 function isResponseResult(value) {
     return (typeof value === "object" &&
         value !== null &&
@@ -272,8 +296,27 @@ function appendCookiesToResponse(response, cookies) {
     }
     return response;
 }
-function nodeOutcomeFromResponse(response) {
-    response = normalizeBodylessResponse(response);
+/** Early exits built outside the handler's finalizer - an `onRequest` hook's response, a mount's,
+ * every framework error render. A plain-data carrier takes the `kind: "json"` lane a handler's plain
+ * return takes, with no `Response` built and none drained; there is no `c.set` at these sites, which
+ * is why they are wrapped rather than finalized. */
+function nodeOutcomeFromResponse(result) {
+    if (!(result instanceof Response)) {
+        const plain = result.plain;
+        if (plain !== undefined) {
+            return {
+                kind: "json",
+                status: plain.status,
+                headers: plain.headers === undefined ? undefined : { ...plain.headers },
+                cookies: undefined,
+                body: plain.body === undefined || isBodylessStatus(plain.status)
+                    ? null
+                    : JSON.stringify(plain.body),
+            };
+        }
+        return nodeOutcomeFromResponse(result.toResponse());
+    }
+    const response = normalizeBodylessResponse(result);
     if (!response.bodyUsed) {
         const body = response[NODE_RESPONSE_BODY];
         if (typeof body === "string" || body instanceof Uint8Array) {
@@ -556,19 +599,23 @@ function staticMatch(state, rawUrl) {
 async function readStatic(file, state, method) {
     let handle;
     try {
-        handle = await open(file, "r");
-        const stat = await handle.stat();
-        if (!stat.isFile()) {
-            await handle.close();
-            return { kind: "response", response: new Response("Not Found", { status: 404 }) };
-        }
         // Defense-in-depth: the lexical `..` guard in staticMatch can't catch a symlink INSIDE root that
-        // points outside it. Re-confirm the real path is contained before streaming the bytes.
+        // points outside it. Resolve first, check containment on the RESOLVED name, and open that -
+        // never open the requested path and re-resolve it afterwards. A local attacker who can write
+        // inside the served tree wins that ordering: swap a link between the open and the lookup and the
+        // descriptor already streaming refers to an external file while the lookup answers with a
+        // contained path. `O_NOFOLLOW` closes the remainder on the final component - `realpath` returned
+        // a name with no links left in it, so one appearing before the open is an attack, not a layout.
         const [realFile, realRoot] = await Promise.all([realpath(file), realpath(state.root)]);
         if (realFile !== realRoot && !realFile.startsWith(realRoot + sep)) {
-            await handle.close();
             return { kind: "response", response: new Response("Forbidden", { status: 403 }) };
         }
+        handle = await open(realFile, FS.O_RDONLY | FS.O_NOFOLLOW);
+        const stat = await handle.stat();
+        if (!stat.isFile()) {
+            await handle.close();
+            return { kind: "response", response: new Response("Not Found", { status: 404 }) };
+        }
         const headers = { ...state.headers };
         headers["content-type"] =
             STATIC_CONTENT_TYPES[extname(file).toLowerCase()] ?? "application/octet-stream";
@@ -585,7 +632,11 @@ async function readStatic(file, state, method) {
         const stream = handle.createReadStream();
         return {
             kind: "response",
-            response: new Response(Readable.toWeb(stream), { headers }),
+            // Claimable rather than `Readable.toWeb`: served straight from disk to the socket when this
+            // response reaches the writer untouched, and read as an ordinary Web stream by anything that
+            // gets to it first (a middleware that rewrites or compresses the body, say), which refuses
+            // the claim and takes the conversion instead.
+            response: new Response(claimableWebStream(stream), { headers }),
         };
     }
     catch {
@@ -648,7 +699,13 @@ export function serve(app, options) {
         try {
             const handled = handle(app, nodeReq, nodeRes, protocol, staticState, hostPolicy);
             if (handled instanceof Promise) {
-                void handled.finally(() => {
+                // `catch` before `finally`: a `finally` alone forwards the rejection to a promise nothing
+                // observes, and Node terminates the process on an unhandled rejection by default. Every
+                // writer already ends its own failures (`failWrite`), so anything arriving here is a fault
+                // no response can still be built from - the connection is the only thing left to end.
+                void handled
+                    .catch(() => failWrite(nodeRes))
+                    .finally(() => {
                     inFlight -= 1;
                 });
                 return;
@@ -656,7 +713,7 @@ export function serve(app, options) {
             inFlight -= 1;
         }
         catch {
-            writeInternalError(nodeRes);
+            failWrite(nodeRes);
             inFlight -= 1;
         }
     });
@@ -713,6 +770,49 @@ export function serve(app, options) {
             server.listen(options.port, options.hostname, onListening);
     });
 }
+/** Run the existing Node-direct/Web bridge after a native mount either was not selected or declined
+ * because its optional transport was unavailable. Kept as a top-level helper so ordinary requests
+ * do not allocate a per-request closure merely to preserve the fallback. */
+function runNodeSource(app, source, nodeReq, nodeRes, protocol, host, platform) {
+    const resolveNodeSource = app.resolveNodeSource;
+    if (typeof resolveNodeSource === "function") {
+        try {
+            const outcome = resolveNodeSource.call(app, source, platform, NODE_OUTCOME_RUNTIME);
+            return outcome instanceof Promise
+                ? outcome.then((settled) => writeOutcomeSafely(settled, nodeRes, nodeReq.method), () => failWrite(nodeRes))
+                : writeOutcomeSafely(outcome, nodeRes, nodeReq.method);
+        }
+        catch {
+            failWrite(nodeRes);
+            return;
+        }
+    }
+    const request = toWebRequest(nodeReq, protocol, host);
+    const resolveNode = app.resolveNode;
+    if (typeof resolveNode === "function") {
+        try {
+            const outcome = resolveNode.call(app, request, platform);
+            return outcome instanceof Promise
+                ? outcome.then((settled) => writeOutcomeSafely(settled, nodeRes, nodeReq.method), () => failWrite(nodeRes))
+                : writeOutcomeSafely(outcome, nodeRes, nodeReq.method);
+        }
+        catch {
+            failWrite(nodeRes);
+            return;
+        }
+    }
+    try {
+        const response = app.fetch(request, platform);
+        return response instanceof Promise
+            ? response.then((settled) => writeResponseSafely(settled, nodeRes, nodeReq.method), () => failWrite(nodeRes))
+            : writeResponseSafely(response, nodeRes, nodeReq.method);
+    }
+    catch {
+        // The app should never throw (nifra returns a 500), but never leak a stack to the wire.
+        failWrite(nodeRes);
+        return;
+    }
+}
 function handle(app, nodeReq, nodeRes, getProtocol, staticState, hostPolicy) {
     const host = requestHost(nodeReq, hostPolicy);
     if (host === undefined) {
@@ -746,27 +846,53 @@ function handle(app, nodeReq, nodeRes, getProtocol, staticState, hostPolicy) {
         const matched = staticMatch(staticState, nodeReq.url ?? "/");
         if (matched !== "pass") {
             if ("reject" in matched)
-                return writeNodeResponse(matched.reject, nodeRes);
-            return readStatic(matched.file, staticState, nodeReq.method ?? "GET").then((outcome) => writeNodeOutcome(outcome, nodeRes), () => writeInternalError(nodeRes));
+                return writeResponseSafely(matched.reject, nodeRes, nodeReq.method);
+            return readStatic(matched.file, staticState, nodeReq.method ?? "GET").then((outcome) => writeOutcomeSafely(outcome, nodeRes, nodeReq.method), () => failWrite(nodeRes));
         }
     }
-    // Fast path: a nifra app exposes `resolveNode`, which renders a plain-data result as primitives we
-    // write straight to the socket - skipping the undici `Response` build + body drain (the bulk of the
-    // Web-bridge cost on Node). A handler-returned `Response`/redirect, 404/405, error, timeout, or any
-    // `onResponse` hook comes back as `{ kind: "response" }` and takes the same Web path as before, so
-    // behavior is identical. A plain `{ fetch }` handler (no `resolveNode`) uses the Web path too.
+    // A mounted handler may advertise a native Node lane. Core has already checked route precedence
+    // and every global lifecycle gate before returning this selection. The handler writes directly to
+    // `nodeRes`; `false` means its optional transport was unavailable, so the same untouched source
+    // continues through the ordinary Web/direct path below.
     const resolveNodeSource = app.resolveNodeSource;
-    if (typeof resolveNodeSource === "function") {
-        try {
-            const outcome = resolveNodeSource.call(app, toNodeRequestSource(nodeReq, protocol, host), platform, NODE_OUTCOME_RUNTIME);
-            return outcome instanceof Promise
-                ? outcome.then((settled) => writeNodeOutcome(settled, nodeRes), () => writeInternalError(nodeRes))
-                : writeNodeOutcome(outcome, nodeRes);
-        }
-        catch {
-            writeInternalError(nodeRes);
-            return;
+    const resolveNodeMount = app[RESOLVE_NODE_MOUNT];
+    if (typeof resolveNodeSource === "function" || typeof resolveNodeMount === "function") {
+        const nodeSource = toNodeRequestSource(nodeReq, protocol, host);
+        if (typeof resolveNodeMount === "function") {
+            let selection;
+            try {
+                selection = resolveNodeMount.call(app, nodeSource, platform);
+            }
+            catch {
+                writeInternalError(nodeRes);
+                return;
+            }
+            if (selection !== undefined) {
+                const nativeRequest = {
+                    method: nodeReq.method ?? "GET",
+                    url: selection.stripPrefix
+                        ? stripNodeMountPrefix(`${protocol}://${host}${nodeReq.url ?? "/"}`, selection.path)
+                        : `${protocol}://${host}${nodeReq.url ?? "/"}`,
+                    headers: nodeReq.headers,
+                    raw: nodeReq,
+                };
+                try {
+                    const outcome = selection.handler(nativeRequest, nodeRes, platform);
+                    if (outcome instanceof Promise) {
+                        return outcome.then((handled) => handled === false
+                            ? runNodeSource(app, nodeSource, nodeReq, nodeRes, protocol, host, platform)
+                            : undefined, () => failWrite(nodeRes));
+                    }
+                    if (outcome !== false)
+                        return;
+                }
+                catch {
+                    failWrite(nodeRes);
+                    return;
+                }
+            }
         }
+        return runNodeSource(app, nodeSource, nodeReq, nodeRes, protocol, host, platform);
     }
     const request = toWebRequest(nodeReq, protocol, host);
     const resolveNode = app.resolveNode;
@@ -774,42 +900,91 @@ function handle(app, nodeReq, nodeRes, getProtocol, staticState, hostPolicy) {
         try {
             const outcome = resolveNode.call(app, request, platform);
             return outcome instanceof Promise
-                ? outcome.then((settled) => writeNodeOutcome(settled, nodeRes), () => writeInternalError(nodeRes))
-                : writeNodeOutcome(outcome, nodeRes);
+                ? outcome.then((settled) => writeOutcomeSafely(settled, nodeRes, nodeReq.method), () => failWrite(nodeRes))
+                : writeOutcomeSafely(outcome, nodeRes, nodeReq.method);
         }
         catch {
-            writeInternalError(nodeRes);
+            failWrite(nodeRes);
             return;
         }
     }
     try {
         const response = app.fetch(request, platform);
         return response instanceof Promise
-            ? response.then((settled) => writeNodeResponse(settled, nodeRes), () => writeInternalError(nodeRes))
-            : writeNodeResponse(response, nodeRes);
+            ? response.then((settled) => writeResponseSafely(settled, nodeRes, nodeReq.method), () => failWrite(nodeRes))
+            : writeResponseSafely(response, nodeRes, nodeReq.method);
     }
     catch {
         // The app should never throw (nifra returns a 500), but never leak a stack to the wire.
-        writeInternalError(nodeRes);
+        failWrite(nodeRes);
         return;
     }
 }
-function writeNodeOutcome(outcome, nodeRes) {
+function writeNodeOutcome(outcome, nodeRes, method) {
+    const isHead = method?.toUpperCase() === "HEAD";
     if (outcome.kind === "json") {
-        writeJsonOutcome(outcome, nodeRes);
+        writeJsonOutcome(outcome, nodeRes, isHead);
         return;
     }
     if (outcome.kind === "body") {
-        writeBodyOutcome(outcome, nodeRes);
+        writeBodyOutcome(outcome, nodeRes, isHead);
         return;
     }
-    return writeNodeResponse(outcome.response, nodeRes);
+    return writeNodeResponse(outcome.response, nodeRes, method);
 }
 /** A flat 500 with no leaked detail - the adapter's last-resort guard if a handler throws. */
 function writeInternalError(nodeRes) {
     nodeRes.writeHead(500, { "content-type": "application/json" });
     nodeRes.end(INTERNAL_ERROR_BODY);
 }
+/**
+ * End a request whose WRITE failed, from anywhere a write can fail.
+ *
+ * `writeHead` throws on an invalid status or a header value carrying CR/LF - reachable whenever an
+ * app reflects request data into `status(...)`/`c.set.headers`, which on the Web lane the `Headers`
+ * constructor rejects instead. It also throws once the head is already out. Both have to end here:
+ * on the async lanes the write runs inside a `.then` callback whose rejection nothing downstream
+ * catches (`serve` only observes `finally`), and Node's default for an unhandled rejection is to
+ * terminate the process - a route-shaped input turning into a server-wide DoS.
+ *
+ * A 500 while the head is unsent, otherwise a destroy: there is no way to correct a response whose
+ * status line already shipped, and a half-written body must not be left for the client to parse.
+ */
+function failWrite(nodeRes) {
+    try {
+        if (!nodeRes.headersSent) {
+            writeInternalError(nodeRes);
+            return;
+        }
+    }
+    catch {
+        // The socket went away between the check and the write; fall through to the destroy.
+    }
+    nodeRes.destroy();
+}
+/** {@link writeNodeOutcome} with {@link failWrite} behind it, sync throw and async rejection alike. */
+function writeOutcomeSafely(outcome, nodeRes, method) {
+    try {
+        const written = writeNodeOutcome(outcome, nodeRes, method);
+        return written instanceof Promise ? written.catch(() => failWrite(nodeRes)) : written;
+    }
+    catch {
+        failWrite(nodeRes);
+        return;
+    }
+}
+/** {@link writeNodeResponse} with {@link failWrite} behind it - same contract as
+ * {@link writeOutcomeSafely}, for the lanes that carry a `Response`. */
+function writeResponseSafely(response, nodeRes, method) {
+    try {
+        const written = writeNodeResponse(response, nodeRes, method);
+        return written instanceof Promise ? written.catch(() => failWrite(nodeRes)) : written;
+    }
+    catch {
+        failWrite(nodeRes);
+        return;
+    }
+}
 function writeBadRequest(nodeRes) {
     const body = "Bad Request";
     nodeRes.writeHead(400, {
@@ -836,7 +1011,7 @@ function allHeaderKeysLowercase(record) {
  * match undici's `Headers` normalization, the JSON `Content-Type` matches the host runtime's, and each
  * queued cookie is emitted as its own `Set-Cookie` line (never comma-joined).
  */
-function writeJsonOutcome(outcome, nodeRes) {
+function writeJsonOutcome(outcome, nodeRes, isHead = false) {
     // The outcome's record is the request's own (`c.set.headers`, already mutated by any native
     // response hooks), and its writers - middleware twins and the framework's own additions - emit
     // lowercase names. Confirmed either by core's mark (the native response walk already looked at
@@ -881,21 +1056,31 @@ function writeJsonOutcome(outcome, nodeRes) {
         // already represented as null so the direct writer cannot advertise bytes that will not ship.
         delete headers["content-length"];
     }
+    else if (!isHead && headers["content-length"] === undefined) {
+        // A body-less render at a status that MAY carry a body - a `redirect()`, above all. Node frames
+        // a `writeHead` + bare `end()` as chunked, so the shortest response the framework emits went out
+        // with a chunk terminator and no length, where every Web-native runtime sends `content-length: 0`.
+        // Declared here so the wire matches them. HEAD is excluded: its length describes the GET's body,
+        // which this lane does not know.
+        headers["content-length"] = "0";
+    }
     if (outcome.cookies !== undefined && outcome.cookies.length > 0) {
         headers["set-cookie"] = [...outcome.cookies];
     }
     nodeRes.writeHead(outcome.status, headers);
-    if (outcome.body !== null)
-        nodeRes.end(outcome.body);
-    else
+    if (isHead || outcome.body === null) {
         nodeRes.end();
+    }
+    else {
+        nodeRes.end(outcome.body);
+    }
 }
 /**
  * Write a node-direct buffered body outcome straight to the socket. This is the Response-shaped
  * sibling of `writeJsonOutcome`: headers/status were already normalized by core, and the body is the
  * exact marked payload from the Response producer, so there is no Web body reader to drain.
  */
-function writeBodyOutcome(outcome, nodeRes) {
+function writeBodyOutcome(outcome, nodeRes, isHead = false) {
     // Body outcomes already carry response-normalized header names and values. Node consumes the same
     // mutable runtime shapes (`string` / `string[]`); avoid cloning this record and every Set-Cookie
     // array on the hot SSR path. The readonly type is an ownership guarantee from the producer, not a
@@ -924,7 +1109,10 @@ function writeBodyOutcome(outcome, nodeRes) {
         }
         nodeRes.writeHead(outcome.status, headers);
     }
-    nodeRes.end(outcome.body);
+    if (isHead)
+        nodeRes.end();
+    else
+        nodeRes.end(outcome.body);
 }
 const byteLengthOf = (body) => typeof body === "string" ? Buffer.byteLength(body) : body.byteLength;
 /** Per-connection cache slot for the socket-peer platform object (see `handle`). */
@@ -953,6 +1141,14 @@ function toNodeRequestSource(req, protocol, host) {
         ? new LeanNodeGetSource(req, method, protocol, host)
         : new LazyNodeRequestSource(req, method, protocol, host);
 }
+function stripNodeMountPrefix(url, prefix) {
+    if (prefix === "/")
+        return url;
+    const target = new URL(url);
+    const rest = target.pathname.slice(prefix.length);
+    target.pathname = rest === "" ? "/" : rest;
+    return target.href;
+}
 /**
  * Split an origin-form request target ("/path?q#frag") into pathname + search without synthesizing
  * an absolute URL first. Mirrors `@nifrajs/core`'s `urlPartsOf` for the origin-form case (kept in
@@ -1050,7 +1246,7 @@ class LazyNodeRequestSource {
             return null;
         if (this.consumedBody !== undefined)
             return this.request.body;
-        this.bodyValue ??= Readable.toWeb(this.nodeReq);
+        this.bodyValue ??= claimableWebStream(this.nodeReq, "drain");
         return this.bodyValue;
     }
     arrayBuffer() {
@@ -1120,7 +1316,7 @@ class LazyNodeRequestSource {
         const consumed = this.consumedBody;
         if (consumed !== undefined)
             return streamOfBytes(consumed);
-        this.bodyValue ??= Readable.toWeb(this.nodeReq);
+        this.bodyValue ??= claimableWebStream(this.nodeReq, "drain");
         return this.bodyValue;
     }
     get request() {
@@ -1263,7 +1459,7 @@ function makeWebRequest(req, method, url, headers, body) {
     const init = { method, headers };
     if (method !== "GET" && method !== "HEAD") {
         // Stream the body in; `duplex: "half"` is required for a streamed request body.
-        init.body = body ?? Readable.toWeb(req);
+        init.body = body ?? claimableWebStream(req, "drain");
         init.duplex = "half";
     }
     return new Request(url, init);
@@ -1391,7 +1587,8 @@ function waitForDrain(nodeRes) {
         }
     });
 }
-function writeNodeResponse(response, nodeRes) {
+function writeNodeResponse(response, nodeRes, method) {
+    const isHead = method?.toUpperCase() === "HEAD";
     // `ServerResponse.setHeaders` (Node 18.14+) takes the Headers object directly and iterates its
     // native Symbol.iterator, which - unlike `Headers.forEach`/`.get()` - never comma-joins repeated
     // `Set-Cookie` values (Node's own implementation carries the identical correctness note this
@@ -1399,27 +1596,158 @@ function writeNodeResponse(response, nodeRes) {
     // forEach into a fresh plain object plus a second cookie-specific pass. Must run before
     // `writeHead`: headers are already flushed by the time `writeHead` returns.
     nodeRes.setHeaders(response.headers);
-    nodeRes.writeHead(response.status);
+    if (isHead) {
+        nodeRes.writeHead(response.status);
+        nodeRes.end();
+        return;
+    }
     const directBody = nodeResponseBody(response);
     if (directBody !== undefined) {
+        // Node computes the length itself for `end(data)` while the header is still unflushed, so this
+        // lane already declares one. The three below do not get that for free.
+        nodeRes.writeHead(response.status);
         nodeRes.end(directBody);
         return;
     }
+    // `end()` with no data is framed as chunked instead, so a body-less `Response` - a hand-rolled
+    // redirect, above all - went out with a chunk terminator and no length where every Web-native
+    // runtime sends `content-length: 0`. Declared before `writeHead`, the last point a header can
+    // still be added. Excluded: HEAD, whose length describes the GET's body that this lane does not
+    // know; a status that cannot carry a body; and a length the caller set for itself.
+    const canDeclareLength = !isBodylessStatus(response.status) && !response.headers.has("content-length");
     if (response.body === null) {
+        if (canDeclareLength)
+            nodeRes.setHeader("content-length", "0");
+        nodeRes.writeHead(response.status);
         if (!nodeRes.destroyed && !nodeRes.writableEnded && nodeRes.writable)
             nodeRes.end();
         return;
     }
-    return writeNodeResponseBody(response, nodeRes);
+    // A body that is a Web view over a Node stream (an upstream response relayed by
+    // `@nifrajs/proxy/undici`, say) goes to the socket as the Node stream it already is, skipping the
+    // per-chunk trip through Web objects that the reader loop below pays for. Length is the upstream's
+    // business: it either forwarded a `content-length` or is genuinely streaming.
+    const nodeBody = response.bodyUsed ? null : claimNodeStream(response.body);
+    if (nodeBody !== null) {
+        nodeRes.writeHead(response.status);
+        return pipeNodeResponseBody(nodeBody, nodeRes);
+    }
+    return writeNodeResponseBody(response, nodeRes, canDeclareLength);
+}
+/**
+ * Send a claimed Node body straight to the socket.
+ *
+ * `pipe` rather than `pipeline`: the status line is already flushed by here, so the only teardown
+ * still available is a destroy on both ends, and `pipeline`'s per-request `eos` machinery costs
+ * more than it buys at this point - it measured as a net loss against the Web reader loop it
+ * replaces, where plain `pipe` measured as a win on both GET and POST.
+ *
+ * The two destroys below are belt-and-braces, not the mechanism: for a body claimed from
+ * `@nifrajs/proxy`, the request's abort signal already tears the upstream down when the client
+ * hangs up, and an upstream that dies mid-body already reaches the client as a broken transfer
+ * rather than a short `200`. They are kept because `pipe` itself guarantees neither, and the claim
+ * seam is open to any transport - including one that wires no signal.
+ */
+function pipeNodeResponseBody(body, nodeRes) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = () => {
+            if (settled)
+                return;
+            settled = true;
+            if (!body.destroyed)
+                body.destroy();
+            resolve();
+        };
+        // Attached before anything here can destroy `body`, and with `on` rather than `once`, because
+        // destroying an upstream body emits `error` (undici raises `RequestAbortedError` for a request
+        // cut short) and an unhandled `error` on a Node stream terminates the process. Every path below
+        // ends in a destroy, including the ones that run after this listener has already fired once.
+        body.on("error", () => {
+            // Only meaningful before the response completes; afterwards there is nothing left to abort.
+            if (!settled && !nodeRes.destroyed && !nodeRes.writableEnded)
+                nodeRes.destroy();
+            done();
+        });
+        // The client is already gone: `pipe` would wait on `close`/`finish` that have both fired.
+        if (nodeRes.destroyed || nodeRes.writableEnded || !nodeRes.writable) {
+            done();
+            return;
+        }
+        nodeRes.once("close", done);
+        nodeRes.once("finish", done);
+        body.pipe(nodeRes);
+    });
 }
-async function writeNodeResponseBody(response, nodeRes) {
+/**
+ * Send a Web `ReadableStream` body to the socket, declaring a length when the body turns out to be
+ * one already-complete chunk.
+ *
+ * `new Response("hi")` hands its bytes over as a stream, exactly as a live producer does, so the
+ * framing decision looks identical from here and Node picks chunked for both. The two are told apart
+ * by reading one chunk and then giving the stream a microtask to say it is done: a source-backed body
+ * - a string, a `Uint8Array`, a `Blob` - has already enqueued everything and closes inside it, while
+ * a producer still generating does not.
+ *
+ * What is held is one chunk, never the whole body, so a large or endless stream is unaffected in
+ * memory. What is spent is a microtask, and it costs a streaming response no bytes on the wire: Node
+ * does not flush the header until the first write either way, so nothing was going out during it.
+ */
+async function writeNodeResponseBody(response, nodeRes, canDeclareLength) {
     const reader = response.body.getReader();
+    let first;
+    try {
+        first = await reader.read();
+    }
+    catch {
+        await reader.cancel().catch(() => { });
+        if (!nodeRes.headersSent)
+            writeInternalError(nodeRes);
+        else
+            nodeRes.destroy();
+        return;
+    }
+    if (first.done) {
+        if (canDeclareLength)
+            nodeRes.setHeader("content-length", "0");
+        nodeRes.writeHead(response.status);
+        if (!nodeRes.destroyed && !nodeRes.writableEnded && nodeRes.writable)
+            nodeRes.end();
+        return;
+    }
+    // Attached with `then` rather than awaited: the point is to observe whether it has settled by the
+    // end of this turn, not to wait for it. The rejection handler is only here so a body that fails
+    // between the two reads is not an unhandled rejection - the drain below awaits the same promise
+    // and is where that failure is actually handled.
+    const pending = reader.read();
+    let settled;
+    pending.then((value) => {
+        settled = value;
+    }, () => { });
+    // A microtask, not a turn of the event loop. It is enough - a source-backed body has already
+    // enqueued everything, so its close is a microtask away on Node and two on Bun, both of which this
+    // covers - and it is short enough to leave the socket's write order alone: yielding a whole turn
+    // here wedged a pipelined keep-alive connection under Bun's `node:http` shim, where the second
+    // response never reached the wire.
+    await new Promise((resolve) => queueMicrotask(resolve));
+    if (settled?.done === true && canDeclareLength && ArrayBuffer.isView(first.value)) {
+        nodeRes.setHeader("content-length", String(first.value.byteLength));
+        nodeRes.writeHead(response.status);
+        if (!nodeRes.destroyed && !nodeRes.writableEnded && nodeRes.writable)
+            nodeRes.end(first.value);
+        return;
+    }
+    nodeRes.writeHead(response.status);
+    return drainWebResponseBody(reader, nodeRes, first.value, pending);
+}
+/** The streaming half of {@link writeNodeResponseBody}, resumed from the chunk and the outstanding
+ * read the length probe already took off the stream. */
+async function drainWebResponseBody(reader, nodeRes, firstChunk, pending) {
+    let chunk = firstChunk;
+    let outstanding = pending;
     try {
         for (;;) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            if (!nodeRes.write(value)) {
+            if (!nodeRes.write(chunk)) {
                 if (nodeRes.destroyed || nodeRes.writableEnded || !nodeRes.writable) {
                     try {
                         await reader.cancel();
@@ -1436,6 +1764,11 @@ async function writeNodeResponseBody(response, nodeRes) {
                     return;
                 }
             }
+            const result = await (outstanding ?? reader.read());
+            outstanding = undefined;
+            if (result.done)
+                break;
+            chunk = result.value;
         }
     }
     catch {