@nifrajs/node 2.13.0 → 3.1.0

package/src/index.ts

@@ -11,6 +11,7 @@
  * `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,
@@ -19,11 +20,13 @@ import {
   type ServerResponse,
 } from "node:http"
 import { extname, isAbsolute, relative, resolve, sep } from "node:path"
-import { type Duplex, Readable } from "node:stream"
+import type { Duplex, 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.ts"
 import type { NodeServeOutcome } from "./generated/node-outcome.ts"
+import { claimableWebStream, claimNodeStream } from "./node-stream.ts"
 
 /** The runtime platform a nifra app accepts as `fetch`'s 2nd arg - here, the observed socket peer. */
 interface NodePlatform {
@@ -126,6 +129,27 @@ interface NodeRequestSource {
   rawBodyReaders?(): NodeRawBodyReaders
 }
 
+/** The request/response view handed to a mounted handler's optional native lane. It deliberately
+ * keeps the raw IncomingMessage so an upstream client receives the original Node stream. */
+interface NodeNativeMountRequest {
+  readonly method: string
+  readonly url: string
+  readonly headers: IncomingHttpHeaders
+  readonly raw: IncomingMessage
+}
+
+type NodeNativeMountHandler = (
+  request: NodeNativeMountRequest,
+  response: ServerResponse,
+  platform?: NodePlatform,
+) => undefined | false | Promise<undefined | false>
+
+interface NodeNativeMountSelection {
+  readonly handler: NodeNativeMountHandler
+  readonly path: string
+  readonly stripPrefix: boolean
+}
+
 /**
  * Core's `RawBodyReaders`: the pre-cap reader surface the transport cap buffers through. Mirrored
  * structurally here rather than imported, matching how the rest of this adapter states core's
@@ -149,7 +173,7 @@ interface NodeContextSet {
 interface NodeOutcomeRuntime {
   toOutcome(result: unknown, set: NodeContextSet): NodeServeOutcome
   toResponse(outcome: NodeServeOutcome): Response
-  fromResponse(response: Response): NodeServeOutcome
+  fromResponse(response: Response | NodeResponseResult): NodeServeOutcome
   timeout(): NodeServeOutcome
   /** The Content-Type the json render writes implicitly - surfaced to core's native hook walk. */
   readonly jsonContentType?: string
@@ -169,6 +193,8 @@ interface NodeFastHandler extends FetchHandler {
   ): NodeServeOutcome | Promise<NodeServeOutcome>
 }
 
+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
@@ -178,12 +204,12 @@ const JSON_CONTENT_TYPE = Response.json(0).headers.get("content-type") ?? "appli
 
 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: number): boolean {
   return status === 204 || status === 205 || status === 304
@@ -204,6 +230,20 @@ function normalizeBodylessResponse(response: Response): Response {
 const NODE_OUTCOME_RUNTIME: NodeOutcomeRuntime = {
   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 {
@@ -245,6 +285,25 @@ interface NodeResponseResult {
     readonly headers: Readonly<Record<string, string | readonly string[]>> | undefined
     readonly body: string | Uint8Array
   }
+  /** Core's `PlainRender` - a response still in value form, rendered without building a `Response`.
+   * Structural, like the rest of this interface: the marker is a `Symbol.for`, so a value from any
+   * copy of core matches. */
+  readonly plain?: {
+    readonly status: number
+    readonly headers?: Readonly<Record<string, string>>
+    readonly body: unknown
+  }
+}
+
+/** 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: Readonly<Record<string, string>> | undefined,
+  ambient: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+  if (own === undefined) return ambient
+  return ambient === undefined ? { ...own } : { ...ambient, ...own }
 }
 
 function isResponseResult(value: unknown): value is NodeResponseResult {
@@ -453,8 +512,28 @@ function appendCookiesToResponse(
   return response
 }
 
-function nodeOutcomeFromResponse(response: Response): NodeServeOutcome {
-  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: Response | NodeResponseResult): NodeServeOutcome {
+  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 as { readonly [NODE_RESPONSE_BODY]?: unknown })[NODE_RESPONSE_BODY]
     if (typeof body === "string" || body instanceof Uint8Array) {
@@ -829,19 +908,23 @@ async function readStatic(
 ): Promise<NodeServeOutcome> {
   let handle: Awaited<ReturnType<typeof open>> | undefined
   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: Record<string, string> = { ...state.headers }
     headers["content-type"] =
       STATIC_CONTENT_TYPES[extname(file).toLowerCase()] ?? "application/octet-stream"
@@ -858,7 +941,11 @@ async function readStatic(
     const stream = handle.createReadStream()
     return {
       kind: "response",
-      response: new Response(Readable.toWeb(stream) as ReadableStream<Uint8Array>, { 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 {
     await handle?.close().catch(() => {})
@@ -918,14 +1005,20 @@ export function serve(app: FetchHandler, options: ServeOptions): Promise<NodeSer
     try {
       const handled = handle(app, nodeReq, nodeRes, protocol, staticState, hostPolicy)
       if (handled instanceof Promise) {
-        void handled.finally(() => {
-          inFlight -= 1
-        })
+        // `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
       }
       inFlight -= 1
     } catch {
-      writeInternalError(nodeRes)
+      failWrite(nodeRes)
       inFlight -= 1
     }
   })
@@ -992,6 +1085,66 @@ export function serve(app: FetchHandler, options: ServeOptions): Promise<NodeSer
   })
 }
 
+/** 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: FetchHandler,
+  source: NodeRequestSource,
+  nodeReq: IncomingMessage,
+  nodeRes: ServerResponse,
+  protocol: RequestProtocol,
+  host: string,
+  platform: NodePlatform | undefined,
+): void | Promise<void> {
+  const resolveNodeSource = (app as Partial<NodeFastHandler>).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 as Partial<NodeFastHandler>).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: FetchHandler,
   nodeReq: IncomingMessage,
@@ -1032,38 +1185,65 @@ function handle(
   if (staticState !== undefined && (nodeReq.method === "GET" || nodeReq.method === "HEAD")) {
     const matched = staticMatch(staticState, nodeReq.url ?? "/")
     if (matched !== "pass") {
-      if ("reject" in matched) return writeNodeResponse(matched.reject, nodeRes)
+      if ("reject" in matched) return writeResponseSafely(matched.reject, nodeRes, nodeReq.method)
       return readStatic(matched.file, staticState, nodeReq.method ?? "GET").then(
-        (outcome) => writeNodeOutcome(outcome, nodeRes),
-        () => writeInternalError(nodeRes),
+        (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 as Partial<NodeFastHandler>).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 as unknown as Record<symbol, unknown>)[RESOLVE_NODE_MOUNT]
+  if (typeof resolveNodeSource === "function" || typeof resolveNodeMount === "function") {
+    const nodeSource = toNodeRequestSource(nodeReq, protocol, host)
+
+    if (typeof resolveNodeMount === "function") {
+      let selection: NodeNativeMountSelection | undefined
+      try {
+        selection = (
+          resolveNodeMount as (
+            source: NodeRequestSource,
+            platform?: NodePlatform,
+          ) => NodeNativeMountSelection | undefined
+        ).call(app, nodeSource, platform)
+      } catch {
+        writeInternalError(nodeRes)
+        return
+      }
+      if (selection !== undefined) {
+        const nativeRequest: NodeNativeMountRequest = {
+          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)
@@ -1073,12 +1253,12 @@ function handle(
       const outcome = resolveNode.call(app, request, platform)
       return outcome instanceof Promise
         ? outcome.then(
-            (settled) => writeNodeOutcome(settled, nodeRes),
-            () => writeInternalError(nodeRes),
+            (settled) => writeOutcomeSafely(settled, nodeRes, nodeReq.method),
+            () => failWrite(nodeRes),
           )
-        : writeNodeOutcome(outcome, nodeRes)
+        : writeOutcomeSafely(outcome, nodeRes, nodeReq.method)
     } catch {
-      writeInternalError(nodeRes)
+      failWrite(nodeRes)
       return
     }
   }
@@ -1087,13 +1267,13 @@ function handle(
     const response = app.fetch(request, platform)
     return response instanceof Promise
       ? response.then(
-          (settled) => writeNodeResponse(settled, nodeRes),
-          () => writeInternalError(nodeRes),
+          (settled) => writeResponseSafely(settled, nodeRes, nodeReq.method),
+          () => failWrite(nodeRes),
         )
-      : writeNodeResponse(response, 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
   }
 }
@@ -1101,16 +1281,18 @@ function handle(
 function writeNodeOutcome(
   outcome: NodeServeOutcome,
   nodeRes: ServerResponse,
+  method?: string,
 ): void | Promise<void> {
+  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. */
@@ -1119,6 +1301,62 @@ function writeInternalError(nodeRes: ServerResponse): void {
   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: ServerResponse): void {
+  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: NodeServeOutcome,
+  nodeRes: ServerResponse,
+  method?: string,
+): void | Promise<void> {
+  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: Response,
+  nodeRes: ServerResponse,
+  method?: string,
+): void | Promise<void> {
+  try {
+    const written = writeNodeResponse(response, nodeRes, method)
+    return written instanceof Promise ? written.catch(() => failWrite(nodeRes)) : written
+  } catch {
+    failWrite(nodeRes)
+    return
+  }
+}
+
 function writeBadRequest(nodeRes: ServerResponse): void {
   const body = "Bad Request"
   nodeRes.writeHead(400, {
@@ -1149,6 +1387,7 @@ function allHeaderKeysLowercase(record: Readonly<Record<string, unknown>>): bool
 function writeJsonOutcome(
   outcome: Extract<NodeServeOutcome, { kind: "json" }>,
   nodeRes: ServerResponse,
+  isHead = false,
 ): void {
   // 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
@@ -1191,13 +1430,23 @@ function writeJsonOutcome(
     // 204/205/304 never carry a payload; discard a user/native-hook length even when the body is
     // 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 nodeRes.end()
+  if (isHead || outcome.body === null) {
+    nodeRes.end()
+  } else {
+    nodeRes.end(outcome.body)
+  }
 }
 
 /**
@@ -1208,6 +1457,7 @@ function writeJsonOutcome(
 function writeBodyOutcome(
   outcome: Extract<NodeServeOutcome, { kind: "body" }>,
   nodeRes: ServerResponse,
+  isHead = false,
 ): void {
   // 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
@@ -1236,7 +1486,8 @@ function writeBodyOutcome(
     }
     nodeRes.writeHead(outcome.status, headers)
   }
-  nodeRes.end(outcome.body)
+  if (isHead) nodeRes.end()
+  else nodeRes.end(outcome.body)
 }
 
 const byteLengthOf = (body: string | Uint8Array): number =>
@@ -1276,6 +1527,14 @@ function toNodeRequestSource(
     : new LazyNodeRequestSource(req, method, protocol, host)
 }
 
+function stripNodeMountPrefix(url: string, prefix: string): string {
+  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
@@ -1382,7 +1641,7 @@ class LazyNodeRequestSource implements NodeRequestSource {
   get body(): ReadableStream<Uint8Array> | null {
     if (this.method === "GET" || this.method === "HEAD") return null
     if (this.consumedBody !== undefined) return this.request.body
-    this.bodyValue ??= Readable.toWeb(this.nodeReq) as ReadableStream<Uint8Array>
+    this.bodyValue ??= claimableWebStream(this.nodeReq, "drain")
     return this.bodyValue
   }
 
@@ -1459,7 +1718,7 @@ class LazyNodeRequestSource implements NodeRequestSource {
     if (this.method === "GET" || this.method === "HEAD") return null
     const consumed = this.consumedBody
     if (consumed !== undefined) return streamOfBytes(consumed)
-    this.bodyValue ??= Readable.toWeb(this.nodeReq) as ReadableStream<Uint8Array>
+    this.bodyValue ??= claimableWebStream(this.nodeReq, "drain")
     return this.bodyValue
   }
 
@@ -1635,7 +1894,7 @@ function makeWebRequest(
   const init: RequestInit & { duplex?: "half" } = { 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) as ReadableStream<Uint8Array>)
+    init.body = body ?? claimableWebStream(req, "drain")
     init.duplex = "half"
   }
   return new Request(url, init)
@@ -1775,7 +2034,12 @@ function waitForDrain(nodeRes: ServerResponse): Promise<boolean> {
   })
 }
 
-function writeNodeResponse(response: Response, nodeRes: ServerResponse): void | Promise<void> {
+function writeNodeResponse(
+  response: Response,
+  nodeRes: ServerResponse,
+  method?: string,
+): void | Promise<void> {
+  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
@@ -1783,26 +2047,170 @@ function writeNodeResponse(response: Response, nodeRes: ServerResponse): void |
   // 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)
 }
 
-async function writeNodeResponseBody(response: Response, nodeRes: ServerResponse): Promise<void> {
+/**
+ * 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: Readable, nodeRes: ServerResponse): Promise<void> {
+  return new Promise<void>((resolve) => {
+    let settled = false
+    const done = (): void => {
+      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)
+  })
+}
+
+/** The two Web-stream shapes the body lane below needs, named structurally: this package builds
+ * without the DOM lib, so `ReadableStreamReadResult` is not a name it can refer to. */
+type BodyChunk =
+  | { readonly done: false; readonly value: Uint8Array }
+  | { readonly done: true; readonly value?: undefined }
+type BodyReader = { read(): Promise<BodyChunk>; cancel(): Promise<void> }
+
+/**
+ * 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: Response,
+  nodeRes: ServerResponse,
+  canDeclareLength: boolean,
+): Promise<void> {
   const reader = response.body!.getReader()
+  let first: BodyChunk
+  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: BodyChunk | undefined
+  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<void>((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: BodyReader,
+  nodeRes: ServerResponse,
+  firstChunk: Uint8Array,
+  pending: Promise<BodyChunk>,
+): Promise<void> {
+  let chunk: Uint8Array | undefined = firstChunk
+  let outstanding: Promise<BodyChunk> | undefined = 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()
@@ -1817,6 +2225,10 @@ async function writeNodeResponseBody(response: Response, nodeRes: ServerResponse
           return
         }
       }
+      const result = await (outstanding ?? reader.read())
+      outstanding = undefined
+      if (result.done) break
+      chunk = result.value
     }
   } catch {
     await reader.cancel().catch(() => {})