@nifrajs/node 3.3.0 → 4.0.0

package/src/index.ts

@@ -18,14 +18,18 @@ import {
   type IncomingHttpHeaders,
   type IncomingMessage,
   type ServerResponse,
+  STATUS_CODES,
 } from "node:http"
+import { createServer as createHttpsServer } from "node:https"
 import { extname, isAbsolute, relative, resolve, sep } from "node:path"
 import type { Duplex, Readable } from "node:stream"
+import type { TlsOptions } from "node:tls"
 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 { hasDotSegment, resolveDotSegments } from "./generated/request-target.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. */
@@ -39,7 +43,10 @@ export interface FetchHandler {
   /** Nifra apps also expose this WS-upgrade seam; present → this adapter serves `app.ws()` routes via
    * the optional `ws` package (lazy-imported on the first upgrade). Absent (a plain `{ fetch }`
    * handler) → HTTP only, and an upgrade request gets a 404. */
-  resolveWebSocketUpgrade?(request: Request): WsUpgradeOutcome | Promise<WsUpgradeOutcome>
+  resolveWebSocketUpgrade?(
+    request: Request,
+    platform?: NodePlatform,
+  ): WsUpgradeOutcome | Promise<WsUpgradeOutcome>
 }
 
 // --- WebSocket types: structurally mirrored from @nifrajs/core. The adapter stays dependency-free;
@@ -506,10 +513,17 @@ function appendCookiesToResponse(
   response: Response,
   cookies: readonly string[] | undefined,
 ): Response {
-  if (cookies !== undefined) {
+  if (cookies === undefined || cookies.length === 0) return response
+  try {
     for (const cookie of cookies) response.headers.append("set-cookie", cookie)
+    return response
+  } catch {
+    // Guarded `Headers` (`Response.redirect()`, a raw `fetch()` result) reject every write, so the
+    // first append throws with nothing applied and the cookies land on a mutable copy instead.
+    const clone = new Response(response.body, response)
+    for (const cookie of cookies) clone.headers.append("set-cookie", cookie)
+    return clone
   }
-  return response
 }
 
 /** Early exits built outside the handler's finalizer - an `onRequest` hook's response, a mount's,
@@ -583,7 +597,12 @@ function nodeOutcomeToResponse(outcome: NodeServeOutcome): Response {
       if (pairs[i]?.[0].toLowerCase() === "content-length") pairs.splice(i, 1)
     }
   }
-  const body = isBodylessStatus(outcome.status) ? null : outcome.body
+  const body =
+    isBodylessStatus(outcome.status) || outcome.body === null
+      ? null
+      : typeof outcome.body === "string"
+        ? outcome.body
+        : outcome.body.slice()
   const response = new FastResponse(body, {
     status: outcome.status,
     headers: pairs,
@@ -652,11 +671,18 @@ export interface ServeOptions {
   /**
    * Protocol used when the adapter constructs `Request.url`.
    *
-   * `@nifrajs/node` creates a plain Node `http` server, so the safe default is `"http"`. Deployments behind
-   * TLS termination can set `"https"` (or a trusted infra-aware function) so app code that reads
+   * The default is `"https"` when {@link ServeOptions.tls} is set and `"http"` otherwise. Deployments
+   * behind TLS termination can set `"https"` (or a trusted infra-aware function) so app code that reads
    * `request.url` sees the public scheme. Forwarded headers are not trusted implicitly.
    */
   readonly protocol?: RequestProtocolOption
+  /**
+   * Serve HTTPS directly, with no proxy in front: `{ cert, key }` as PEM text or the files' bytes
+   * (`readFileSync("cert.pem")`), plus any other `node:tls` server option (`passphrase`, `ca`,
+   * `requestCert` for client certificates, `minVersion`, `SNICallback`, ...). Unset, the server speaks
+   * plain HTTP, which is what a proxy or platform that terminates TLS expects.
+   */
+  readonly tls?: TlsOptions
   /** Reject requests whose normalized Host authority is not in this allowlist or callback result. */
   readonly allowedHosts?: readonly string[] | ((host: string) => boolean)
   /** Use this validated authority when constructing Request.url, ignoring the inbound Host value. */
@@ -833,6 +859,15 @@ interface StaticState {
   readonly denyDotfiles: boolean
 }
 
+function staticHeadersOf(
+  input: Readonly<Record<string, string>> | undefined,
+): Readonly<Record<string, string>> | undefined {
+  if (input === undefined) return undefined
+  const headers = Object.create(null) as Record<string, string>
+  for (const [name, value] of Object.entries(input)) headers[name.toLowerCase()] = value
+  return headers
+}
+
 function staticStateOf(options: ServeStaticOptions): StaticState {
   const root = resolve(typeof options.dir === "string" ? options.dir : fileURLToPath(options.dir))
   const raw = options.prefix ?? "/assets"
@@ -846,7 +881,7 @@ function staticStateOf(options: ServeStaticOptions): StaticState {
     root,
     prefix,
     immutable: options.immutable !== false,
-    headers: options.headers,
+    headers: staticHeadersOf(options.headers),
     denyDotfiles: options.dotfiles !== "allow",
   }
 }
@@ -901,10 +936,94 @@ function staticMatch(
   return { file }
 }
 
+/** Strong validator from mtime + size (the nginx scheme): rewriting a file changes at least one. */
+function staticEtag(size: number, mtimeMs: number): string {
+  return `"${Math.floor(mtimeMs).toString(16)}-${size.toString(16)}"`
+}
+
+function weakEtag(value: string): string {
+  return value.startsWith("W/") ? value.slice(2) : value
+}
+
+/** `If-None-Match` uses the weak comparison (RFC 9110 section 13.1.2): a `W/` prefix is ignored. */
+function etagListMatches(header: string, etag: string): boolean {
+  const comparable = weakEtag(etag)
+  for (const raw of header.split(",")) {
+    const candidate = raw.trim()
+    if (candidate === "*" || weakEtag(candidate) === comparable) return true
+  }
+  return false
+}
+
+/** Whether the client's cached copy is current. `If-None-Match` wins over `If-Modified-Since`, whose
+ * HTTP-date only carries whole seconds. */
+function staticNotModified(
+  headers: IncomingHttpHeaders,
+  etag: string,
+  lastModified: number | undefined,
+): boolean {
+  const ifNoneMatch = headers["if-none-match"]
+  if (typeof ifNoneMatch === "string") return etagListMatches(ifNoneMatch, etag)
+  if (lastModified === undefined) return false
+  const ifModifiedSince = headers["if-modified-since"]
+  if (typeof ifModifiedSince !== "string") return false
+  const since = Date.parse(ifModifiedSince)
+  return Number.isFinite(since) && Math.floor(lastModified / 1000) * 1000 <= since
+}
+
+function staticIfRangeMatches(
+  value: string,
+  etag: string,
+  lastModified: number | undefined,
+): boolean {
+  const item = value.trim()
+  if (item.startsWith('"') || item.startsWith("W/")) {
+    return !item.startsWith("W/") && !etag.startsWith("W/") && item === etag
+  }
+  // A date validator must match Last-Modified exactly (RFC 9110 section 13.1.5), not merely be later:
+  // a file swapped for one with an older mtime would otherwise splice foreign bytes into a resume.
+  if (lastModified === undefined) return false
+  const date = Date.parse(item)
+  return Number.isFinite(date) && Math.floor(lastModified / 1000) === Math.floor(date / 1000)
+}
+
+/**
+ * One `bytes=` range as inclusive offsets, `"unsatisfiable"` (416), or `undefined` to send the whole
+ * file: no header, a malformed or multi-range one (RFC 9110 lets a server ignore Range), or an
+ * `If-Range` validator that no longer matches the file.
+ */
+function staticByteRange(
+  headers: IncomingHttpHeaders,
+  size: number,
+  etag: string,
+  lastModified: number | undefined,
+): readonly [number, number] | "unsatisfiable" | undefined {
+  const range = headers.range
+  if (typeof range !== "string") return undefined
+  const ifRange = headers["if-range"]
+  if (typeof ifRange === "string" && !staticIfRangeMatches(ifRange, etag, lastModified)) {
+    return undefined
+  }
+  const match = /^bytes=(\d*)-(\d*)$/.exec(range.trim())
+  if (match === null) return undefined
+  const first = match[1] as string
+  const last = match[2] as string
+  if (first === "") {
+    if (last === "") return undefined
+    const suffix = Number(last)
+    return suffix === 0 || size === 0 ? "unsatisfiable" : [Math.max(0, size - suffix), size - 1]
+  }
+  const start = Number(first)
+  if (start >= size) return "unsatisfiable"
+  const end = last === "" ? size - 1 : Math.min(Number(last), size - 1)
+  return end < start ? undefined : [start, end]
+}
+
 async function readStatic(
   file: string,
   state: StaticState,
   method: string,
+  requestHeaders: IncomingHttpHeaders,
 ): Promise<NodeServeOutcome> {
   let handle: Awaited<ReturnType<typeof open>> | undefined
   try {
@@ -926,26 +1045,60 @@ async function readStatic(
       return { kind: "response", response: new Response("Not Found", { status: 404 }) }
     }
     const headers: Record<string, string> = { ...state.headers }
+    if (state.immutable && headers["cache-control"] === undefined) {
+      headers["cache-control"] = "public, max-age=31536000, immutable"
+    }
+    headers.etag ??= staticEtag(stat.size, stat.mtimeMs)
+    headers["last-modified"] ??= stat.mtime.toUTCString()
+    // Custom validators are response headers, not decoration: compare the exact values the client saw.
+    const etag = headers.etag
+    const parsedLastModified = Date.parse(headers["last-modified"])
+    const lastModified = Number.isFinite(parsedLastModified) ? parsedLastModified : undefined
+    // Revalidation: a current cached copy costs a header-only 304 instead of the whole file.
+    if (staticNotModified(requestHeaders, etag, lastModified)) {
+      await handle.close()
+      delete headers["content-length"]
+      delete headers["content-type"]
+      return { kind: "response", response: new Response(null, { status: 304, headers }) }
+    }
     headers["content-type"] =
       STATIC_CONTENT_TYPES[extname(file).toLowerCase()] ?? "application/octet-stream"
     // Never let a client sniff a served file into a more dangerous type (e.g. an .svg as active content).
     headers["x-content-type-options"] = "nosniff"
-    headers["content-length"] = String(stat.size)
-    if (state.immutable && headers["cache-control"] === undefined) {
-      headers["cache-control"] = "public, max-age=31536000, immutable"
+    headers["accept-ranges"] = "bytes"
+    // Range applies to GET only (RFC 9110 section 14.2); HEAD reports the whole representation.
+    const range =
+      method === "GET" ? staticByteRange(requestHeaders, stat.size, etag, lastModified) : undefined
+    if (range === "unsatisfiable") {
+      await handle.close()
+      headers["content-range"] = `bytes */${stat.size}`
+      delete headers["content-length"]
+      delete headers["content-type"]
+      return { kind: "response", response: new Response(null, { status: 416, headers }) }
+    }
+    let status = 200
+    if (range !== undefined) {
+      status = 206
+      headers["content-range"] = `bytes ${range[0]}-${range[1]}/${stat.size}`
+      headers["content-length"] = String(range[1] - range[0] + 1)
+    } else {
+      headers["content-length"] = String(stat.size)
     }
     if (method === "HEAD") {
       await handle.close()
       return { kind: "response", response: new Response(null, { headers }) }
     }
-    const stream = handle.createReadStream()
+    const stream =
+      range === undefined
+        ? handle.createReadStream()
+        : handle.createReadStream({ start: range[0], end: range[1] })
     return {
       kind: "response",
       // 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 }),
+      response: new Response(claimableWebStream(stream), { status, headers }),
     }
   } catch {
     await handle?.close().catch(() => {})
@@ -991,37 +1144,74 @@ function activateAsyncContextFrame(): void {
   new AsyncLocalStorage()
 }
 
+interface ActiveResponseState {
+  readonly socket: { readonly destroyed: boolean; destroy(): void }
+  active: number
+  parserError: boolean
+}
+
+const ACTIVE_RESPONSE_STATE = Symbol("nifra.node.active-response-state")
+const ACTIVE_RESPONSE_RELEASED = Symbol("nifra.node.active-response-released")
+const ACTIVE_SOCKET_STATE = Symbol("nifra.node.active-socket-state")
+type TrackedSocket = {
+  readonly destroyed: boolean
+  destroy(): void
+  once(event: "close", listener: (this: TrackedSocket) => void): unknown
+  [ACTIVE_SOCKET_STATE]?: ActiveResponseState
+}
+type TrackedServerResponse = ServerResponse & {
+  [ACTIVE_RESPONSE_STATE]?: ActiveResponseState
+  [ACTIVE_RESPONSE_RELEASED]?: boolean
+}
+
+/** Shared finish/close listener - response state carries the per-response release bit. */
+function releaseActiveResponse(this: ServerResponse): void {
+  const response = this as TrackedServerResponse
+  const state = response[ACTIVE_RESPONSE_STATE]
+  if (state === undefined || response[ACTIVE_RESPONSE_RELEASED]) return
+  response[ACTIVE_RESPONSE_RELEASED] = true
+  state.active -= 1
+  if (state.parserError && state.active === 0 && !state.socket.destroyed) {
+    state.socket.destroy()
+  }
+}
+
+function clearActiveResponseState(this: TrackedSocket): void {
+  const state = this[ACTIVE_SOCKET_STATE]
+  if (state !== undefined) state.active = 0
+}
+
 export function serve(app: FetchHandler, options: ServeOptions): Promise<NodeServer> {
   activateAsyncContextFrame()
   enableNodeDirect(app)
   if (options.fastResponse === true) installFastResponse()
   let inFlight = 0
   let closed = false
-  const protocol = protocolResolver(options.protocol)
+  // Upgrade sockets an HTTP route answers instead: Node's server no longer tracks them, so stop()
+  // drains and closes them itself.
+  const answering = new Set<Duplex>()
+  const protocol = protocolResolver(
+    options.protocol ?? (options.tls === undefined ? undefined : "https"),
+  )
   const hostPolicy = hostPolicyOf(options)
   const staticState = options.static !== undefined ? staticStateOf(options.static) : undefined
   // Node otherwise destroys a socket as soon as its HTTP parser emits `clientError`. That can
   // discard the response for an already-dispatched request when an understated Content-Length
   // leaves surplus bytes that look like a malformed pipelined request. Keep the parser error
   // connection-scoped and close only after active responses finish, preserving response ordering.
-  const activeResponses = new WeakMap<object, Set<ServerResponse>>()
-  const parserErrorSockets = new WeakSet<object>()
-  const server = createServer((nodeReq, nodeRes) => {
-    const socket = nodeReq.socket
-    let responses = activeResponses.get(socket)
-    if (responses === undefined) {
-      responses = new Set<ServerResponse>()
-      activeResponses.set(socket, responses)
-    }
-    responses.add(nodeRes)
-    const releaseResponse = (): void => {
-      const current = activeResponses.get(socket)
-      if (current === undefined) return
-      current.delete(nodeRes)
-      if (current.size === 0) activeResponses.delete(socket)
-    }
-    nodeRes.once("finish", releaseResponse)
-    nodeRes.once("close", releaseResponse)
+  const onRequest = (nodeReq: IncomingMessage, nodeRes: ServerResponse): void => {
+    const socket = nodeReq.socket as TrackedSocket
+    let responseState = socket[ACTIVE_SOCKET_STATE]
+    if (responseState === undefined) {
+      responseState = { socket, active: 0, parserError: false }
+      socket[ACTIVE_SOCKET_STATE] = responseState
+      socket.once("close", clearActiveResponseState)
+    }
+    responseState.active += 1
+    ;(nodeRes as TrackedServerResponse)[ACTIVE_RESPONSE_STATE] = responseState
+    ;(nodeRes as TrackedServerResponse)[ACTIVE_RESPONSE_RELEASED] = false
+    nodeRes.once("finish", releaseActiveResponse)
+    nodeRes.once("close", releaseActiveResponse)
     inFlight += 1
     try {
       const handled = handle(app, nodeReq, nodeRes, protocol, staticState, hostPolicy)
@@ -1042,23 +1232,23 @@ export function serve(app: FetchHandler, options: ServeOptions): Promise<NodeSer
       failWrite(nodeRes)
       inFlight -= 1
     }
-  })
+  }
+  const resolveWs = app.resolveWebSocketUpgrade?.bind(app)
+  // Only a WebSocket handshake leaves the HTTP parser; any other `Upgrade` (curl's h2c offer) is an
+  // ordinary request. Node versions without the option send every upgrade to the `upgrade` event.
+  const upgradeOptions =
+    resolveWs === undefined ? {} : { shouldUpgradeCallback: isWebSocketUpgrade }
+  const server =
+    options.tls === undefined
+      ? createServer(upgradeOptions, onRequest)
+      : createHttpsServer({ ...options.tls, ...upgradeOptions }, onRequest)
 
   server.on("clientError", (_error, socket) => {
     if (socket.destroyed) return
-    const responses = activeResponses.get(socket)
-    if (responses !== undefined && responses.size > 0) {
-      if (parserErrorSockets.has(socket)) return
-      parserErrorSockets.add(socket)
-      const closeWhenDrained = (): void => {
-        const current = activeResponses.get(socket)
-        if (current === undefined || current.size === 0) socket.destroy()
-      }
-      for (const response of responses) {
-        if (response.writableEnded || response.destroyed) closeWhenDrained()
-        else response.once("finish", closeWhenDrained)
-        response.once("close", closeWhenDrained)
-      }
+    const responseState = (socket as TrackedSocket)[ACTIVE_SOCKET_STATE]
+    if (responseState !== undefined && responseState.active > 0) {
+      if (responseState.parserError) return
+      responseState.parserError = true
       return
     }
     const body = "Bad Request"
@@ -1070,11 +1260,12 @@ export function serve(app: FetchHandler, options: ServeOptions): Promise<NodeSer
   // WebSocket upgrades (a nifra app exposing the seam): handled on the http server's `upgrade` event via
   // the optional `ws` package - lazy-imported (and the server lazily built) on the FIRST real WS
   // upgrade, so a non-WS Node app never loads `ws`.
-  const resolveWs = app.resolveWebSocketUpgrade?.bind(app)
   if (resolveWs !== undefined) {
     let wssPromise: Promise<WsServer | undefined> | undefined
     server.on("upgrade", (nodeReq, socket, head) => {
       void handleUpgrade(
+        app,
+        answering,
         resolveWs,
         protocol,
         hostPolicy,
@@ -1105,10 +1296,11 @@ export function serve(app: FetchHandler, options: ServeOptions): Promise<NodeSer
     }
     server.close() // stop accepting new connections; existing requests continue
     const deadline = Date.now() + drainMs
-    while (inFlight > 0 && Date.now() < deadline) {
+    while ((inFlight > 0 || answering.size > 0) && Date.now() < deadline) {
       await new Promise((r) => setTimeout(r, DRAIN_POLL_MS))
     }
     server.closeAllConnections() // force-close stragglers + idle keep-alive sockets
+    for (const socket of answering) socket.destroy()
   }
 
   return new Promise((resolve) => {
@@ -1157,7 +1349,7 @@ function runNodeSource(
     }
   }
 
-  const request = toWebRequest(nodeReq, protocol, host)
+  const request = toWebRequest(nodeReq, protocol, host, nodeRes)
   const resolveNode = (app as Partial<NodeFastHandler>).resolveNode
   if (typeof resolveNode === "function") {
     try {
@@ -1189,6 +1381,30 @@ function runNodeSource(
   }
 }
 
+/**
+ * Resolve the target's `.` / `..` segments and backslashes in place, before anything reads it. Node
+ * keeps the target as the client sent it, where Bun and workerd deliver it parsed; resolving it here
+ * routes `/users/../admin` to `/admin` on every runtime, and every later reader - static files,
+ * mounts, the app, `c.req.url` - sees the one path.
+ */
+const ABSOLUTE_FORM = /^[a-z][a-z\d+.-]*:\/\//i
+
+function resolveTarget(nodeReq: IncomingMessage): void {
+  let target = nodeReq.url
+  if (target === undefined) return
+  // Absolute-form (`GET http://host/path`, RFC 9112 section 3.2.2) is routed as its origin-form path
+  // with the Host header, as Bun does. Kept whole, hooks saw `http://hosthttp://...` while the
+  // router matched the full URL against a `/*` route.
+  if (target.charCodeAt(0) !== 47 && ABSOLUTE_FORM.test(target)) {
+    let end = target.indexOf("//") + 2
+    while (end < target.length && target[end] !== "/" && target[end] !== "?") end++
+    const rest = target.slice(end)
+    target = rest.charCodeAt(0) === 47 ? rest : `/${rest}`
+    nodeReq.url = target
+  }
+  if (hasDotSegment(target)) nodeReq.url = resolveDotSegments(target)
+}
+
 function handle(
   app: FetchHandler,
   nodeReq: IncomingMessage,
@@ -1197,6 +1413,7 @@ function handle(
   staticState: StaticState | undefined,
   hostPolicy: HostPolicy,
 ): void | Promise<void> {
+  resolveTarget(nodeReq)
   const host = requestHost(nodeReq, hostPolicy)
   if (host === undefined) {
     writeBadRequest(nodeRes)
@@ -1230,7 +1447,7 @@ function handle(
     const matched = staticMatch(staticState, nodeReq.url ?? "/")
     if (matched !== "pass") {
       if ("reject" in matched) return writeResponseSafely(matched.reject, nodeRes, nodeReq.method)
-      return readStatic(matched.file, staticState, nodeReq.method ?? "GET").then(
+      return readStatic(matched.file, staticState, nodeReq.method ?? "GET", nodeReq.headers).then(
         (outcome) => writeOutcomeSafely(outcome, nodeRes, nodeReq.method),
         () => failWrite(nodeRes),
       )
@@ -1244,7 +1461,7 @@ function handle(
   const resolveNodeSource = (app as Partial<NodeFastHandler>).resolveNodeSource
   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)
+    const nodeSource = toNodeRequestSource(nodeReq, protocol, host, nodeRes)
 
     if (typeof resolveNodeMount === "function") {
       let selection: NodeNativeMountSelection | undefined
@@ -1290,7 +1507,7 @@ function handle(
     return runNodeSource(app, nodeSource, nodeReq, nodeRes, protocol, host, platform)
   }
 
-  const request = toWebRequest(nodeReq, protocol, host)
+  const request = toWebRequest(nodeReq, protocol, host, nodeRes)
   const resolveNode = (app as Partial<NodeFastHandler>).resolveNode
   if (typeof resolveNode === "function") {
     try {
@@ -1422,6 +1639,69 @@ function allHeaderKeysLowercase(record: Readonly<Record<string, unknown>>): bool
   return true
 }
 
+/**
+ * Store one wire header on a literal record. A literal `__proto__` name must not go through plain
+ * assignment - the inherited setter would silently swallow it - so it is defined as an own data
+ * property instead; every other name takes the fast plain store. Same guard core's portable header
+ * view makes over the same record, so a hook-set `__proto__` header round-trips to the wire
+ * exactly as it did through the old normalization copy.
+ */
+function storeWireHeader(
+  headers: Record<string, string | string[]>,
+  name: string,
+  value: string | string[],
+): void {
+  if (name === "__proto__") {
+    Object.defineProperty(headers, name, {
+      value,
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    })
+    return
+  }
+  headers[name] = value
+}
+
+/** True when an existing header slot can be replaced without throwing or invoking an accessor. */
+function canReplaceHeaderSlot(record: Readonly<Record<string, unknown>>, name: string): boolean {
+  const descriptor = Object.getOwnPropertyDescriptor(record, name)
+  return descriptor === undefined || ("writable" in descriptor && descriptor.writable === true)
+}
+
+/**
+ * A proven lowercase record can stay on the Node hot path when the writer only has to append its
+ * own framing headers. Non-default framing names and explicit lengths take the copy path: the old
+ * writer moved those names to the end of the record, and retaining that order keeps raw HTTP/1.1
+ * snapshots stable. Core's default JSON type is the one exception - it appends that value before
+ * this writer runs, so recognizing it lets the common hooked route retain the record and append
+ * length in place. An application that explicitly supplies the same default value is indistinguishable
+ * here and follows that same semantics-preserving fast path.
+ */
+function canWriteJsonHeadersInPlace(
+  source: Readonly<Record<string, string | readonly string[]>>,
+  cookies: readonly string[] | undefined,
+): source is Record<string, string | string[]> {
+  try {
+    if (!Object.isExtensible(source)) return false
+    if (Object.hasOwn(source, "content-length")) return false
+    if (Object.hasOwn(source, "content-type") && source["content-type"] !== JSON_CONTENT_TYPE) {
+      return false
+    }
+    if (
+      cookies !== undefined &&
+      cookies.length > 0 &&
+      !canReplaceHeaderSlot(source, "set-cookie")
+    ) {
+      return false
+    }
+    return true
+  } catch {
+    // A proxy or a hostile descriptor should use the same isolated fallback as mixed-case input.
+    return false
+  }
+}
+
 /**
  * Serialize a node-direct JSON outcome straight to the socket - no undici `Response`, no stream drain.
  * Mirrors `Response.json(data, { status, headers })` byte-for-byte: user headers are lowercased to
@@ -1435,31 +1715,37 @@ function writeJsonOutcome(
 ): 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
-  // lowercase names. Confirmed either by core's mark (the native response walk already looked at
-  // these keys, so re-walking them here is the same pass twice) or, when the record never went
-  // through that walk, by the scan below. Either way the record is then used as-is and the additions
-  // below mutate it in place; nothing reads it after the write. Only a mixed-case key (a user's
-  // hand-set `X-Foo`) pays the normalization copy, keeping the wire byte-identical to undici's
-  // `Headers` lowercasing on every other runtime.
-  let headers: Record<string, string | string[]>
+  // lowercase names. Whether a name needs folding is answered either by core's mark (the native
+  // response walk already looked at these keys, so re-walking them here is the same pass twice)
+  // or, when the record never went through that walk, by the scan below.
+  //
+  // A proven lowercase, extensible record is owned by this request. Keep it in place and append
+  // lowercase framing names directly; the old uppercase rename paid two deletes and demoted the
+  // record to dictionary mode. Mixed-case, frozen, and explicitly framed records take an isolated
+  // copy below, preserving the old source order and protecting caller-owned objects.
   const source = outcome.headers
-  if (source === undefined) {
-    // A route that set no headers gets a record the FRAMEWORK alone fills - content-type,
-    // content-length, set-cookie - so no attacker-influenced name can reach it and the
-    // null-prototype guard the normalization branch needs buys nothing here. It does cost: a
-    // null-prototype object never enters V8's fast property mode, and Node's `_storeHeader` walks
-    // this record key by key on every response (measured at over twice fastify's share of the same
-    // frame on a bare route). A literal keeps it in fast mode.
-    headers = {}
-  } else if (
+  const lowercase =
+    source === undefined ||
     (source as Record<symbol, unknown>)[LOWERCASE_HEADER_KEYS] === true ||
     allHeaderKeysLowercase(source)
-  ) {
-    headers = source as Record<string, string | string[]>
-  } else {
-    headers = Object.create(null) as Record<string, string | string[]>
-    for (const [key, value] of Object.entries(source)) {
-      headers[key.toLowerCase()] = value as string | string[]
+  const inPlace =
+    source === undefined || (lowercase && canWriteJsonHeadersInPlace(source, outcome.cookies))
+  const headers: Record<string, string | string[]> =
+    inPlace && source !== undefined ? (source as Record<string, string | string[]>) : {}
+  let contentType: string | string[] | undefined
+  let hasLength = false
+  if (!inPlace && source !== undefined) {
+    for (const key of Object.keys(source)) {
+      const lower = lowercase ? key : key.toLowerCase()
+      if (lower === "content-type") {
+        contentType = source[key] as string | string[]
+        continue
+      }
+      if (lower === "content-length") {
+        hasLength = true
+        continue
+      }
+      storeWireHeader(headers, lower, source[key] as string | string[])
     }
   }
   // A `null` body is a 204/no-content render - `new Response(null)` carries no Content-Type, so we add
@@ -1468,25 +1754,23 @@ function writeJsonOutcome(
   // without it Node falls back to chunked framing, which costs extra wire bytes and client parsing
   // on every response (and no other runtime chunks a buffered JSON body).
   if (outcome.body !== null) {
-    if (headers["content-type"] === undefined) headers["Content-Type"] = JSON_CONTENT_TYPE
-    else {
-      headers["Content-Type"] = headers["content-type"]
-      delete headers["content-type"]
+    if (inPlace) {
+      if (!Object.hasOwn(headers, "content-type")) headers["content-type"] = JSON_CONTENT_TYPE
+      headers["content-length"] = String(Buffer.byteLength(outcome.body))
+    } else {
+      storeWireHeader(headers, "content-type", contentType ?? JSON_CONTENT_TYPE)
+      storeWireHeader(headers, "content-length", String(Buffer.byteLength(outcome.body)))
     }
-    headers["Content-Length"] = String(Buffer.byteLength(outcome.body))
-    delete headers["content-length"]
   } else if (isBodylessStatus(outcome.status)) {
-    // 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"]
-    delete headers["Content-Length"]
-  } else if (!isHead && headers["content-length"] === undefined) {
+    // 204/205/304 never carry a payload; a user/native-hook length is dropped rather than copied,
+    // so the direct writer cannot advertise bytes that will not ship.
+  } else if (!isHead && !hasLength) {
     // 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"
+    headers["content-length"] = "0"
   }
   if (outcome.cookies !== undefined && outcome.cookies.length > 0) {
     headers["set-cookie"] = [...outcome.cookies]
@@ -1560,21 +1844,34 @@ function normalizeProtocol(value: string): RequestProtocol {
   )
 }
 
-function toWebRequest(req: IncomingMessage, protocol: RequestProtocol, host: string): Request {
+/** What a request's signal follows: the response it is answered on, or an upgrade's raw socket. */
+interface RequestEnd {
+  readonly writableFinished: boolean
+  readonly closed: boolean
+  once(event: "close", listener: () => void): unknown
+}
+
+function toWebRequest(
+  req: IncomingMessage,
+  protocol: RequestProtocol,
+  host: string,
+  res?: RequestEnd,
+): Request {
   const url = `${protocol}://${host}${req.url ?? "/"}`
   const method = req.method ?? "GET"
-  return makeWebRequest(req, method, url, headerRecordFromNode(req.headers))
+  return makeWebRequest(req, method, url, headerRecordFromNode(req.headers), undefined, res)
 }
 
 function toNodeRequestSource(
   req: IncomingMessage,
   protocol: RequestProtocol,
   host: string,
+  res: ServerResponse,
 ): NodeRequestSource {
   const method = req.method ?? "GET"
   return method === "GET" || method === "HEAD"
-    ? new LeanNodeGetSource(req, method, protocol, host)
-    : new LazyNodeRequestSource(req, method, protocol, host)
+    ? new LeanNodeGetSource(req, method, protocol, host, res)
+    : new LazyNodeRequestSource(req, method, protocol, host, res)
 }
 
 function stripNodeMountPrefix(url: string, prefix: string): string {
@@ -1657,12 +1954,20 @@ class LazyNodeRequestSource implements NodeRequestSource {
   private readonly nodeReq: IncomingMessage
   private readonly protocol: RequestProtocol
   private readonly host: string
-
-  constructor(nodeReq: IncomingMessage, method: string, protocol: RequestProtocol, host: string) {
+  private readonly nodeRes: ServerResponse
+
+  constructor(
+    nodeReq: IncomingMessage,
+    method: string,
+    protocol: RequestProtocol,
+    host: string,
+    nodeRes: ServerResponse,
+  ) {
     this.nodeReq = nodeReq
     this.method = method
     this.protocol = protocol
     this.host = host
+    this.nodeRes = nodeRes
   }
 
   /** The absolute URL, built only when something reads it - routing uses `urlParts` instead. */
@@ -1752,13 +2057,25 @@ class LazyNodeRequestSource implements NodeRequestSource {
    */
   private rawBodyBytes(): Promise<Uint8Array> {
     if (this.consumedBody !== undefined) return Promise.resolve(this.consumedBody)
-    const handed = this.bodyValue
+    const handed = this.handedBody()
     if (handed != null) {
       return new Response(handed).arrayBuffer().then((buffer) => new Uint8Array(buffer))
     }
     return this.readNodeBody()
   }
 
+  /**
+   * The stream the Web `Request` was built on, or - once a hook's `req.clone()` teed it (which locks
+   * the original) - the branch that request kept. Reading the locked original threw, so a middleware
+   * that peeked at the body through a clone turned every downstream body read into a 500.
+   */
+  private handedBody(): ReadableStream<Uint8Array> | undefined {
+    const handed = this.bodyValue
+    if (handed == null || !handed.locked) return handed ?? undefined
+    const owner = this.requestValue as unknown as { readonly _real?: Request } | undefined
+    return owner?._real?.body ?? handed
+  }
+
   /**
    * The raw body stream, never routed back through `this.request` - post-cap that getter is the
    * shadowed one, which reads back through these very readers. An already-consumed body replays
@@ -1769,7 +2086,7 @@ class LazyNodeRequestSource implements NodeRequestSource {
     const consumed = this.consumedBody
     if (consumed !== undefined) return streamOfBytes(consumed)
     this.bodyValue ??= claimableWebStream(this.nodeReq, "drain")
-    return this.bodyValue
+    return this.handedBody() ?? this.bodyValue
   }
 
   get request(): Request {
@@ -1785,13 +2102,14 @@ class LazyNodeRequestSource implements NodeRequestSource {
             this.url,
             headers,
             this.consumedBody,
+            this.nodeRes,
           )
           // Preserve one-shot body semantics if user code asks for `c.req` after nifra already
           // consumed it.
           void real.arrayBuffer().catch(() => {})
           return real
         }
-        return makeWebRequest(this.nodeReq, this.method, this.url, headers, this.body)
+        return makeWebRequest(this.nodeReq, this.method, this.url, headers, this.body, this.nodeRes)
       },
     ) as unknown as Request
     return this.requestValue
@@ -1862,12 +2180,20 @@ class LeanNodeGetSource implements NodeRequestSource {
   private readonly nodeReq: IncomingMessage
   private readonly protocol: RequestProtocol
   private readonly host: string
-
-  constructor(nodeReq: IncomingMessage, method: string, protocol: RequestProtocol, host: string) {
+  private readonly nodeRes: ServerResponse
+
+  constructor(
+    nodeReq: IncomingMessage,
+    method: string,
+    protocol: RequestProtocol,
+    host: string,
+    nodeRes: ServerResponse,
+  ) {
     this.nodeReq = nodeReq
     this.method = method
     this.protocol = protocol
     this.host = host
+    this.nodeRes = nodeRes
   }
 
   /** The absolute URL, built only when something reads it - routing uses `urlParts` instead. */
@@ -1908,7 +2234,7 @@ class LeanNodeGetSource implements NodeRequestSource {
       this.method,
       this.url,
       () => this.headersValue ?? headerRecordFromNode(this.nodeReq.headers),
-      (headers) => makeWebRequest(this.nodeReq, this.method, this.url, headers, null),
+      (headers) => makeWebRequest(this.nodeReq, this.method, this.url, headers, null, this.nodeRes),
     ) as unknown as Request
     return this.requestValue
   }
@@ -1940,11 +2266,23 @@ function makeWebRequest(
   url: string,
   headers: Headers | Record<string, string>,
   body?: ReadableStream<Uint8Array> | Uint8Array | null,
+  res?: RequestEnd,
 ): Request {
   const init: RequestInit & { duplex?: "half" } = { method, headers }
+  if (res !== undefined) {
+    // `signal` aborts when the client goes away before the response finished, as on Bun and Deno.
+    const disconnect = new AbortController()
+    init.signal = disconnect.signal
+    const onClose = (): void => {
+      if (!res.writableFinished) disconnect.abort()
+    }
+    if (res.closed) onClose()
+    else res.once("close", onClose)
+  }
   if (method !== "GET" && method !== "HEAD") {
     // Stream the body in; `duplex: "half"` is required for a streamed request body.
-    init.body = body ?? claimableWebStream(req, "drain")
+    init.body =
+      body instanceof Uint8Array ? body.slice() : (body ?? claimableWebStream(req, "drain"))
     init.duplex = "half"
   }
   return new Request(url, init)
@@ -2052,7 +2390,16 @@ const LazyWebRequest = /* @__PURE__ */ (() => {
   return LazyWebRequest
 })()
 
-function waitForDrain(nodeRes: ServerResponse): Promise<boolean> {
+/** A writable end whose backpressure can be awaited: a response, or an upgrade socket answered as one. */
+interface DrainTarget {
+  readonly destroyed: boolean
+  readonly writableEnded: boolean
+  readonly writable: boolean
+  once(event: "drain" | "close" | "error", listener: () => void): unknown
+  removeListener(event: "drain" | "close" | "error", listener: () => void): unknown
+}
+
+function waitForDrain(nodeRes: DrainTarget): Promise<boolean> {
   if (nodeRes.destroyed || nodeRes.writableEnded || !nodeRes.writable) {
     return Promise.resolve(false)
   }
@@ -2100,6 +2447,9 @@ function writeNodeResponse(
   if (isHead) {
     nodeRes.writeHead(response.status)
     nodeRes.end()
+    // Nothing reads a HEAD answer's body. Cancelled, its source learns the exchange is over, as on
+    // Bun and Deno; left alone, a streaming route's producer runs on with no reader.
+    response.body?.cancel().catch(() => {})
     return
   }
   const directBody = nodeResponseBody(response)
@@ -2205,6 +2555,26 @@ async function writeNodeResponseBody(
   canDeclareLength: boolean,
 ): Promise<void> {
   const reader = response.body!.getReader()
+  // A client that leaves while the stream is idle never fails a write. Its departure cancels the
+  // stream, as on Bun and Deno, so a producer waiting to send learns the exchange is over.
+  const onClose = (): void => {
+    reader.cancel().catch(() => {})
+  }
+  nodeRes.once("close", onClose)
+  if (nodeRes.destroyed) onClose()
+  try {
+    await writeNodeResponseChunks(reader, response, nodeRes, canDeclareLength)
+  } finally {
+    nodeRes.removeListener("close", onClose)
+  }
+}
+
+async function writeNodeResponseChunks(
+  reader: BodyReader,
+  response: Response,
+  nodeRes: ServerResponse,
+  canDeclareLength: boolean,
+): Promise<void> {
   let first: BodyChunk
   try {
     first = await reader.read()
@@ -2337,7 +2707,12 @@ const WS_STATUS_TEXT: Readonly<Record<number, string>> = {
 /** Resolve a Node `upgrade` event: run the nifra upgrade guard, then either reject (write an HTTP error
  * to the raw socket) or perform the `ws` upgrade and wire the socket to the handler. */
 async function handleUpgrade(
-  resolveWs: (request: Request) => WsUpgradeOutcome | Promise<WsUpgradeOutcome>,
+  app: FetchHandler,
+  answering: Set<Duplex>,
+  resolveWs: (
+    request: Request,
+    platform?: NodePlatform,
+  ) => WsUpgradeOutcome | Promise<WsUpgradeOutcome>,
   getProtocol: RequestProtocolResolver,
   hostPolicy: HostPolicy,
   nodeReq: IncomingMessage,
@@ -2345,20 +2720,49 @@ async function handleUpgrade(
   head: Buffer,
   getWss: (maxPayloadBytes?: number) => Promise<WsServer | undefined>,
 ): Promise<void> {
+  // A peer can reset the socket while the guard is awaited; with no listener that error ends the process.
+  socket.on("error", ignoreSocketError)
+  resolveTarget(nodeReq)
   let outcome: WsUpgradeOutcome
+  let request: Request
+  let platform: NodePlatform | undefined
   try {
     const host = requestHost(nodeReq, hostPolicy)
     if (host === undefined) {
       writeUpgradeRejection(socket, 400, "bad_request")
       return
     }
-    outcome = await resolveWs(toWebRequest(nodeReq, getProtocol(nodeReq), host))
+    const peerAddress = nodeReq.socket.remoteAddress
+    platform = peerAddress === undefined ? undefined : { clientIp: peerAddress }
+    // Its signal follows the socket, so a route answered below stops when the client leaves.
+    request = toWebRequest(nodeReq, getProtocol(nodeReq), host, socket)
+    outcome = await resolveWs(request, platform)
   } catch {
     writeUpgradeRejection(socket, 500, "internal_error")
     return
   }
   if (outcome.kind === "pass") {
-    writeUpgradeRejection(socket, 404, "not_found") // upgrade to a path with no WS route
+    // No WS route here: the HTTP route answers, as on Bun. Only a bodiless request can be served from
+    // an upgrade socket - Node parses no body for one, so a POST here (Node without
+    // `shouldUpgradeCallback`) keeps the 404.
+    if (nodeReq.method !== "GET" && nodeReq.method !== "HEAD") {
+      writeUpgradeRejection(socket, 404, "not_found")
+      return
+    }
+    let response: Response
+    try {
+      response = await app.fetch(request, platform)
+    } catch {
+      writeUpgradeRejection(socket, 500, "internal_error")
+      return
+    }
+    answering.add(socket)
+    socket.once("close", () => answering.delete(socket))
+    // Detached from Node's HTTP handling, the socket comes paused and nothing ends it on the client's
+    // FIN. Reading it and ending on `end`, as Node's server does, lets a departure reach the signal.
+    socket.once("end", () => socket.end())
+    socket.resume()
+    await writeSocketResponse(socket, response, nodeReq.method)
     return
   }
   if (outcome.kind === "reject") {
@@ -2425,6 +2829,13 @@ function attachNodeWebSocket(
   safe(() => handler.open?.(nifra)) // open: the socket is already established here
 }
 
+function ignoreSocketError(): void {}
+
+function isWebSocketUpgrade(nodeReq: IncomingMessage): boolean {
+  // A handshake is a GET (RFC 6455 section 4.1); any other method is an ordinary request with a body.
+  return nodeReq.method === "GET" && /\bwebsocket\b/i.test(nodeReq.headers.upgrade ?? "")
+}
+
 /** Write a minimal JSON error response to a raw upgrade socket, then close it. */
 function writeUpgradeRejection(socket: Duplex, status: number, error: string): void {
   const body = JSON.stringify({ ok: false, error })
@@ -2448,3 +2859,39 @@ async function writeRejectionResponse(socket: Duplex, response: Response): Promi
   socket.write(head + body)
   socket.destroy()
 }
+
+/** Answer an upgrade socket with an ordinary response: the body streams as produced, paced by the
+ * socket's backpressure and delimited by the close (RFC 9112 section 6.3), never buffered whole. */
+async function writeSocketResponse(
+  socket: Duplex,
+  response: Response,
+  method: string,
+): Promise<void> {
+  let head = `HTTP/1.1 ${response.status} ${response.statusText || STATUS_CODES[response.status] || "Unknown"}\r\n`
+  response.headers.forEach((value, key) => {
+    if (key !== "connection" && key !== "keep-alive" && key !== "transfer-encoding") {
+      head += `${key}: ${value}\r\n`
+    }
+  })
+  socket.write(`${head}Connection: close\r\n\r\n`)
+  if (response.body === null || method === "HEAD") {
+    await response.body?.cancel().catch(() => {})
+    socket.end()
+    return
+  }
+  const reader = response.body.getReader()
+  try {
+    for (;;) {
+      const chunk = await reader.read()
+      if (chunk.done) break
+      if (!socket.write(chunk.value) && !(await waitForDrain(socket))) {
+        await reader.cancel()
+        return
+      }
+    }
+    socket.end()
+  } catch {
+    socket.destroy()
+    await reader.cancel().catch(() => {})
+  }
+}