@nifrajs/proxy 2.13.0 → 3.1.0

package/src/node-stream.ts

@@ -0,0 +1,174 @@
+/**
+ * The Node-stream escape hatch: a Web `ReadableStream` over a Node `Readable` that can hand the
+ * Node stream back, so two adjacent Node-native layers do not have to round-trip bytes through Web
+ * objects just because the contract between them is Web-shaped.
+ *
+ * Why this exists: `@nifrajs/node` receives a Node `IncomingMessage` and must present a Web
+ * `Request`; `@nifrajs/proxy/undici` receives that `Request` and must hand undici a Node stream
+ * again. Measured on a pinned-core Linux rig, that round trip - not hygiene, not routing, not the
+ * adapter - is the entire remaining distance to `@fastify/reply-from`, which never leaves Node
+ * streams: -17% on GET (one conversion) and -34% on POST (two, since the request body converts on
+ * the way out as well).
+ *
+ * Why it cannot be `Readable.toWeb`: that consumes its source EAGERLY. Wrapping a `Readable` and
+ * then never reading the wrapper still leaves the source read (`readableDidRead === true`), so
+ * handing the raw stream onward afterwards loses the body outright. The wrapper here touches its
+ * source only on the first `pull`, which is what makes the hand-back sound.
+ *
+ * The seam is a `Symbol.for` key because the two packages that use it share no runtime dependency.
+ * This file is a verbatim copy of `@nifrajs/node`'s - importing it would give this package a
+ * runtime dependency, and only the symbol and the shape below actually have to match. It is
+ * reachable only through the `./undici` subpath, so the base package stays runtime-portable.
+ *
+ * Claiming is ONE-SHOT and refused once the Web view has been touched, which is the property that
+ * makes it safe: a body can never be split between the two views, and a layer that already started
+ * reading the Web stream silently keeps the ordinary path instead of forwarding a truncated body.
+ */
+
+import { Readable } from "node:stream"
+
+/** Shared with `@nifrajs/node`'s copy of this module - the value is the contract. */
+export const NODE_STREAM_CLAIM = Symbol.for("nifra.node.stream-claim")
+
+interface NodeStreamClaim {
+  /** The backing Node stream, or `null` if the Web view was already read, cancelled, or claimed. */
+  claim(): Readable | null
+}
+
+type ClaimableStream = ReadableStream<Uint8Array> & {
+  readonly [NODE_STREAM_CLAIM]?: NodeStreamClaim
+}
+
+/**
+ * What cancelling the Web view should do to the Node stream under it.
+ *
+ * `"destroy"` releases the source immediately, which is what a response body wants: a client that
+ * walked away from a file or an upstream response must not cost another byte of it.
+ *
+ * `"drain"` lets the source run to its own end and destroys it then, which is what a REQUEST body
+ * wants, and is `Readable.toWeb`'s behaviour rather than a new policy. Destroying an
+ * `IncomingMessage` destroys its socket, so cancelling a half-read upload synchronously tears the
+ * connection down before the handler can answer - a body rejected by the size cap reaches the client
+ * as a connection reset instead of the `413` that explains it. Draining leaves the socket writable
+ * long enough for the response to go out. It does NOT mean reading the rest of a hostile upload:
+ * once that response completes, Node destroys the socket itself because the request is incomplete,
+ * so an over-cap body stops arriving within roughly the cap either way (measured: a 64 MB body
+ * against a 1 MB cap transfers about 2 MB before the connection closes, on this path and on
+ * `Readable.toWeb` alike).
+ */
+export type CancelPolicy = "destroy" | "drain"
+
+/**
+ * Hard ceiling on a post-cancel drain. Draining exists only to let the early response (a 413 cap
+ * rejection) flush on a clean FIN; it is never meant to read a hostile upload to its end. Node
+ * normally tears the socket down once that response completes, which ends the drain well before this
+ * - but a slow client that keeps both directions alive could otherwise trickle bytes forever and
+ * pin the connection. Past this many drained bytes the response has long since left, so destroying
+ * (an RST) no longer risks discarding it; the ceiling just caps the pathological case.
+ */
+const DRAIN_BYTE_CAP = 8 * 1024 * 1024
+
+/**
+ * A Web view of `source` that defers to it lazily and can be traded back in for it.
+ *
+ * `highWaterMark: 0` keeps construction free of a speculative pull - a stream that is going to be
+ * claimed must not have read a byte first.
+ */
+export function claimableWebStream(
+  source: Readable,
+  onCancel: CancelPolicy = "destroy",
+): ReadableStream<Uint8Array> {
+  let iterator: AsyncIterator<Buffer | Uint8Array> | undefined
+  let surrendered = false
+
+  const stream = new ReadableStream<Uint8Array>(
+    {
+      pull(controller): Promise<void> {
+        if (surrendered) {
+          // Unreachable through `claimNodeStream` (it refuses a locked stream and the claim is
+          // one-shot), so reaching it means someone kept a reader across the hand-off. Fail loudly
+          // rather than serve a body that is missing whatever the other consumer already took.
+          const error = new Error(
+            "[nifra] this request body was handed to a Node-native consumer; the Web stream over it can no longer be read",
+          )
+          controller.error(error)
+          return Promise.reject(error)
+        }
+        iterator ??= source[Symbol.asyncIterator]() as AsyncIterator<Buffer | Uint8Array>
+        return iterator.next().then(
+          ({ done, value }) => {
+            if (done === true) {
+              controller.close()
+              return
+            }
+            // `Buffer` is a `Uint8Array`, so a binary-mode stream needs no conversion. An
+            // object-mode stream has no business being an HTTP body.
+            if (!(value instanceof Uint8Array)) {
+              throw new TypeError("[nifra] request body stream yielded a non-binary chunk")
+            }
+            controller.enqueue(value)
+          },
+          (error: unknown) => {
+            controller.error(error)
+            throw error
+          },
+        )
+      },
+      cancel(reason): void {
+        if (surrendered) return
+        surrendered = true
+        const error = reason instanceof Error ? reason : undefined
+        if (onCancel === "destroy" || source.destroyed) {
+          source.destroy(error)
+          return
+        }
+        // The source stays live after this returns, so it keeps the right to emit `error` - and an
+        // unhandled `error` on a Node stream terminates the process. A client that resets the
+        // connection mid-drain is an ordinary event here, not a fault worth propagating: the read
+        // was already abandoned.
+        source.on("error", () => {
+          if (!source.destroyed) source.destroy()
+        })
+        // Both, because only one of them is reached: a source that runs out ends, and one whose
+        // socket is torn down by the completed response closes without ending.
+        source.once("end", () => source.destroy())
+        source.once("close", () => source.destroy())
+        // Bounded drain: a `data` listener flows the source to discard it, the same as `resume()`,
+        // but also counts bytes so an over-cap trickle is destroyed at the cap rather than held open
+        // indefinitely.
+        let drained = 0
+        source.on("data", (chunk: Buffer) => {
+          drained += chunk.byteLength
+          if (drained > DRAIN_BYTE_CAP && !source.destroyed) source.destroy()
+        })
+      },
+    },
+    { highWaterMark: 0 },
+  )
+
+  const claim: NodeStreamClaim = {
+    claim(): Readable | null {
+      // `iterator !== undefined` means a pull already happened, so bytes are gone; `destroyed`
+      // means there is nothing left to hand over.
+      if (surrendered || iterator !== undefined || source.destroyed) return null
+      surrendered = true
+      return source
+    },
+  }
+  Object.defineProperty(stream, NODE_STREAM_CLAIM, { value: claim, enumerable: false })
+  return stream
+}
+
+/**
+ * Trade a Web stream back for the Node stream underneath it, or `null` when that is not sound -
+ * a foreign stream, one someone holds a reader on, or one that has already been read or claimed.
+ * Every `null` means "use the ordinary Web path", never "fail".
+ */
+export function claimNodeStream(body: ReadableStream<Uint8Array> | null): Readable | null {
+  if (body === null || body.locked) return null
+  const holder = (body as ClaimableStream)[NODE_STREAM_CLAIM]
+  if (holder === undefined || typeof holder.claim !== "function") return null
+  const claimed = holder.claim()
+  // A `Symbol.for` key is reachable by anything in the process, so the value is not taken on trust.
+  return claimed instanceof Readable ? claimed : null
+}

package/src/undici.ts

@@ -0,0 +1,164 @@
+/**
+ * undici-backed transport for `createProxy` - the fast upstream path on Node.
+ *
+ * `fetch()` is a spec-compliant wrapper over the same client. Measured against a local origin at 50
+ * concurrent connections, going straight to undici's dispatcher API instead is roughly 2.5x the
+ * throughput on GET and 2.2x on POST; on Bun there is no such gap, so this is a Node remedy and the
+ * default `fetch` transport stays the portable one.
+ *
+ * The security obligations in {@link ProxyTransport} are met here as follows: undici does not follow
+ * redirects unless asked to, so a 3xx is relayed and the upstream can never steer the next hop; the
+ * URL is passed through untouched, so the dialed host is still the one `createProxy` computed; and
+ * TLS verification is left alone, with no option offered to weaken it. Sanitised headers are
+ * forwarded exactly as handed over.
+ *
+ * The redirect guarantee is the one a caller can break: undici 8 moved redirect following into an
+ * opt-in interceptor (undici 7 spelled it `maxRedirections`, defaulting to none). Composing a
+ * redirect interceptor into a `dispatcher` passed here would defeat it, and this transport cannot
+ * detect that. Do not.
+ *
+ * ```ts
+ * import { createProxy } from "@nifrajs/proxy"
+ * import { undiciTransport } from "@nifrajs/proxy/undici"
+ *
+ * const proxy = createProxy({ upstream: "http://127.0.0.1:8081", transport: undiciTransport() })
+ * ```
+ *
+ * Requires `undici` (>= 7) to be installed; it is an optional peer, so the base package stays
+ * dependency-free for everyone who does not opt in.
+ */
+
+import { Readable } from "node:stream"
+import { type Dispatcher, request as undiciRequest } from "undici"
+import type { NativeProxyTransport, ProxyTransport, ProxyUpstreamResponse } from "./index.ts"
+import { claimableWebStream, claimNodeStream } from "./node-stream.ts"
+
+const NODE_NATIVE_TRANSPORT = Symbol.for("@nifrajs/proxy/node-native-transport")
+
+export interface UndiciTransportOptions {
+  /**
+   * Connection pool to dial through - an undici `Agent`, `Pool`, or any other `Dispatcher`. Omit to
+   * use undici's global dispatcher. Supply one to tune `connections` per origin, which is the knob
+   * that matters under load. It must not compose a redirect interceptor: this proxy relays 3xx
+   * rather than following it, and a dispatcher that follows would hand the upstream the next hop.
+   */
+  readonly dispatcher?: Dispatcher
+  /**
+   * Milliseconds of silence tolerated *within* the response body before undici destroys it.
+   * `createProxy`'s own `timeoutMs` only covers the wait for response headers - after the status is
+   * relayed a `504` is no longer sendable - so this is what protects against a body that starts and
+   * then stalls. Default `30_000`; `0` disables it.
+   */
+  readonly bodyTimeoutMs?: number
+}
+
+/**
+ * Statuses that MUST NOT carry a body. `fetch` reports `response.body === null` for these, but
+ * undici hands back a real (empty) stream, and `new Response(stream, { status: 204 })` throws. The
+ * stream is dumped rather than dropped, because an unread undici body holds its socket open.
+ */
+const NULL_BODY_STATUS: ReadonlySet<number> = new Set([101, 204, 205, 304])
+
+function toHeaders(raw: Readonly<Record<string, string | string[] | undefined>>): Headers {
+  const out = new Headers()
+  for (const [name, value] of Object.entries(raw)) {
+    if (value === undefined) continue
+    if (Array.isArray(value)) {
+      for (const entry of value) out.append(name, entry)
+    } else {
+      out.append(name, value)
+    }
+  }
+  return out
+}
+
+function requestBody(body: ReadableStream<Uint8Array> | null): Readable | null {
+  if (body === null) return null
+  return claimNodeStream(body) ?? Readable.fromWeb(body)
+}
+
+/** Create an undici-backed {@link ProxyTransport}. */
+export function undiciTransport(options: UndiciTransportOptions = {}): ProxyTransport {
+  // Under Bun the `undici` specifier resolves to a built-in shim whose response bodies have no
+  // `dump()` and whose request bodies undici cannot iterate - every POST and every bodiless status
+  // would come back as a flat 502. Fail at construction instead: there is nothing to gain anyway,
+  // since Bun's own fetch measures level with a raw client, and the default transport is faster.
+  if (typeof (globalThis as { readonly Bun?: unknown }).Bun !== "undefined") {
+    throw new Error(
+      "[nifra/proxy] undiciTransport() is a Node remedy - under Bun the `undici` specifier resolves to a built-in shim this cannot drive, and Bun's own fetch shows no gap. Leave `transport` unset there.",
+    )
+  }
+  const bodyTimeout = options.bodyTimeoutMs ?? 30_000
+  if (!Number.isFinite(bodyTimeout) || bodyTimeout < 0) {
+    throw new Error("[nifra/proxy] bodyTimeoutMs must be a non-negative number")
+  }
+  const dispatcher = options.dispatcher
+
+  const transport: ProxyTransport = async (target, request): Promise<ProxyUpstreamResponse> => {
+    // Flat name/value pairs preserve what `Headers` already merged, without a second object.
+    const headers: string[] = []
+    for (const [name, value] of request.headers) headers.push(name, value)
+
+    const response = await undiciRequest(target, {
+      method: request.method as Dispatcher.HttpMethod,
+      headers,
+      // Node's own stream type, so undici never has to guess how to consume it. When the adapter
+      // upstream of us built that Web stream over a Node one and nothing has read it, take the
+      // Node stream back instead of converting: the client's body then reaches undici without ever
+      // being repackaged. `claimNodeStream` returns null for any stream that is foreign, held, or
+      // already read, and the conversion below is what happens then.
+      body: requestBody(request.body),
+      signal: request.signal,
+      bodyTimeout,
+      ...(dispatcher === undefined ? {} : { dispatcher }),
+    })
+
+    if (NULL_BODY_STATUS.has(response.statusCode) || request.method === "HEAD") {
+      await response.body.dump()
+      return {
+        status: response.statusCode,
+        statusText: "",
+        headers: toHeaders(response.headers),
+        body: null,
+        // No body to describe, but undici never decodes, so the contract stays consistent.
+        bodyEncoded: true,
+      }
+    }
+
+    return {
+      status: response.statusCode,
+      statusText: "",
+      headers: toHeaders(response.headers),
+      // Claimable rather than `Readable.toWeb`: an adapter that writes this response to a Node
+      // socket (`@nifrajs/node`) can pipe the upstream stream straight through, and anything else
+      // reads it as the ordinary Web stream it is.
+      body: claimableWebStream(response.body),
+      // undici's `request` does not decode `Content-Encoding`, so the body is the upstream's exact
+      // bytes and its encoding/length headers must survive the relay for the client to decode.
+      bodyEncoded: true,
+    }
+  }
+
+  const nativeTransport: NativeProxyTransport = async (target, request) => {
+    const response = await undiciRequest(target, {
+      method: request.method as Dispatcher.HttpMethod,
+      headers: Array.from(request.headers),
+      // This is the original IncomingMessage from @nifrajs/node. Keeping it as a Node stream is
+      // the point of this lane: no Web stream wrapper is constructed on either side of the proxy.
+      body: request.body === null ? null : (request.body as never),
+      signal: request.signal,
+      headersTimeout: request.headersTimeout,
+      bodyTimeout,
+      ...(dispatcher === undefined ? {} : { dispatcher }),
+    })
+    return {
+      status: response.statusCode,
+      headers: response.headers as Readonly<Record<string, string | readonly string[] | undefined>>,
+      body: response.body,
+      dump: () => response.body.dump(),
+    }
+  }
+
+  Object.defineProperty(transport, NODE_NATIVE_TRANSPORT, { value: nativeTransport })
+  return transport
+}