@stacksjs/rpx 0.11.18 → 0.11.19

package/src/proxy-pool.ts

@@ -0,0 +1,1003 @@
+/**
+ * Pooled raw-socket HTTP/1.1 client for the proxy hot path.
+ *
+ * `fetch()` is convenient but churns upstream connections under load: even with
+ * a concurrency cap, Bun's fetch opens and closes connections far faster than the
+ * OS recycles ephemeral ports, they pile into TIME_WAIT, and throughput collapses
+ * by ~15x (verified: ~11k TIME_WAIT sockets, 45% errors at c=400). nginx avoids
+ * this with a small, *reused* keepalive pool. This module gives rpx the same
+ * model: persistent upstream sockets per `host:port`, reused across requests, so
+ * the proxy stays flat under load instead of falling over.
+ *
+ * It is deliberately scoped to the common case (plain-HTTP upstream, ordinary
+ * request/response). Anything unusual — streaming/large request uploads, `Expect`,
+ * protocol upgrades — throws {@link FALLBACK} so the caller can defer to the
+ * proven `fetch()` path. Correctness first; the fast path is the optimization.
+ */
+// `connect` is a Bun runtime builtin. A static value-import (`from 'bun'`) trips
+// the declaration/bundle step at publish time ("Browser build cannot import Bun
+// builtin: 'bun'"), so reach it through the `Bun` global instead — identical at
+// runtime (rpx only ever runs under Bun), but invisible to the bundler.
+const { connect } = Bun
+
+/** Sentinel thrown when the pooled path declines a request; caller uses fetch(). */
+export const FALLBACK: unique symbol = Symbol('rpx.pool.fallback')
+
+/** Marker for "a reused socket closed before/at the start of the response" — retryable. */
+const STALE = Symbol('rpx.pool.stale')
+
+/** Thrown when the upstream stalls past the configured timeout; caller maps to 504. */
+export const TIMEOUT: unique symbol = Symbol('rpx.pool.timeout')
+
+/**
+ * Thrown when every connection to an upstream is busy and the wait for a free
+ * slot exceeded {@link queueWaitMs}, or the waiter queue is already at its cap.
+ * The caller maps it to a 503. This is the backstop that keeps a saturated or
+ * stalled upstream from making the *listener* appear wedged: instead of parking
+ * a request forever with no response (the production incident), rpx fails it
+ * fast and loud so the listener keeps answering every other request.
+ */
+export const POOL_BUSY: unique symbol = Symbol('rpx.pool.busy')
+
+/**
+ * Max time (ms) a request waits for a free connection slot when an upstream is
+ * at its connection cap, from `RPX_QUEUE_WAIT_MS` (default 30s). On expiry the
+ * request gets a 503 rather than hanging indefinitely. This bound is what makes
+ * a leaked/stalled slot a localized 503 instead of a global wedge.
+ */
+function queueWaitMs(): number {
+  const v = Number.parseInt(process.env.RPX_QUEUE_WAIT_MS ?? '', 10)
+  return Number.isFinite(v) && v > 0 ? v : 30_000
+}
+
+/**
+ * Hard ceiling on queued waiters per upstream, from `RPX_MAX_QUEUED` (default
+ * `maxTotal * 8`). Beyond this, requests are rejected with 503 immediately
+ * rather than appended — so a flood (or a fully wedged upstream) can't grow the
+ * waiter array without bound and exhaust memory on top of the saturation.
+ */
+function maxQueued(maxTotal: number): number {
+  const v = Number.parseInt(process.env.RPX_MAX_QUEUED ?? '', 10)
+  return Number.isFinite(v) && v > 0 ? v : maxTotal * 8
+}
+
+/**
+ * Upstream inactivity timeout in seconds, from `RPX_UPSTREAM_TIMEOUT`. `0`
+ * (the default) disables it — rpx commonly fronts dev servers doing SSE/HMR/
+ * long-poll, where an inactivity timeout would sever legitimately-quiet streams.
+ * The timer resets on every byte, so a streaming response that emits data
+ * periodically never trips it; only a fully-stalled upstream does. Set a value
+ * (e.g. `RPX_UPSTREAM_TIMEOUT=60`) in production to bound hung upstreams.
+ */
+function upstreamTimeoutSeconds(): number {
+  const v = Number.parseInt(process.env.RPX_UPSTREAM_TIMEOUT ?? '', 10)
+  return Number.isFinite(v) && v > 0 ? v : 0
+}
+
+/** Largest request body we will buffer in-memory to keep a request retry-safe. */
+const MAX_BUFFERED_BODY = 1024 * 1024 // 1 MB
+
+/**
+ * Max open connections per upstream, from `RPX_MAX_UPSTREAM_CONNS` (default 256).
+ * Requests beyond this queue for a free connection rather than opening more — the
+ * ceiling that keeps a flood from churning sockets into TIME_WAIT. Raise it for
+ * higher peak parallelism, lower it to cap upstream load.
+ */
+function maxTotalConns(): number {
+  const v = Number.parseInt(process.env.RPX_MAX_UPSTREAM_CONNS ?? '', 10)
+  return Number.isFinite(v) && v > 0 ? v : 256
+}
+
+/** How long an idle pooled connection is kept before it is closed (nginx's keepalive_timeout). */
+const IDLE_TIMEOUT_MS = 30_000
+
+/** Initial per-connection read buffer; grows on demand for larger header blocks. */
+const INITIAL_BUF = 16384
+
+/**
+ * Hard cap on the response header block. A buggy or malicious upstream that
+ * streams bytes without ever sending the terminating `\r\n\r\n` would otherwise
+ * grow the per-connection buffer unbounded (doubling on each read) until the
+ * proxy OOMs. If the header end isn't found within this many bytes, the
+ * connection is torn down and the request fails with 502. 256 KB is far above
+ * any legitimate header block.
+ */
+const MAX_HEADER_BYTES = 256 * 1024
+
+/**
+ * Bodies at least this large take the zero-copy fast path: hand the Response a
+ * *view* of the read buffer and give the connection a fresh (smaller) buffer,
+ * rather than copying the body out. Below it, a plain slice is cheaper than
+ * allocating a replacement buffer.
+ */
+const BODY_HANDOFF_THRESHOLD = 8192
+/** Replacement buffer size after a zero-copy hand-off (just needs the next headers). */
+const HANDOFF_BUF = 4096
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+/**
+ * Request headers never forwarded verbatim: HTTP/1.1 framing headers (we own the
+ * connection lifecycle) plus the `x-forwarded-*` set, which the caller always
+ * supplies as overrides — so client-sent copies must not be passed through.
+ */
+const STRIP_REQUEST = new Set([
+  'host',
+  'connection',
+  'keep-alive',
+  'proxy-connection',
+  'transfer-encoding',
+  'x-forwarded-for',
+  'x-forwarded-proto',
+  'x-forwarded-host',
+])
+
+/**
+ * One pooled upstream socket. A connection serves a single request at a time
+ * (HTTP/1.1, no pipelining); it is checked out of the pool for the duration of a
+ * request and returned once the response body is fully read.
+ */
+class Conn {
+  socket: import('bun').Socket<undefined> | null = null
+  buf: Uint8Array = new Uint8Array(INITIAL_BUF)
+  len = 0 // bytes filled
+  pos = 0 // bytes consumed by the parser
+  closed = false
+  /** True until the first request has been written — lets the pool retry stale reuse. */
+  fresh = true
+  /** Set when the socket's inactivity timeout fired — surfaces as a 504, not a 502. */
+  timedOut = false
+  /** Epoch ms when this connection was last returned to the idle set (for sweeping). */
+  idleSince = 0
+  /** When set, push() routes body bytes here (streaming a content-length body). */
+  bodyQueue: Uint8Array[] | null = null
+  /** Body bytes still expected from the socket while {@link bodyQueue} is active. */
+  bodyRemaining = 0
+  /** Resolves the in-flight reader when new bytes arrive or the socket closes. */
+  private waiter: (() => void) | null = null
+  /** Resolves the in-flight writer when the socket's send buffer drains. */
+  drainWaiter: (() => void) | null = null
+
+  /** Write `bytes` in full, awaiting `drain` when the send buffer backs up. */
+  async writeAll(bytes: Uint8Array): Promise<void> {
+    const socket = this.socket!
+    let off = socket.write(bytes)
+    while (off < bytes.length) {
+      if (this.closed)
+        throw STALE
+      // Send buffer full — wait for drain before writing the remainder.
+      await new Promise<void>((resolve) => { this.drainWaiter = resolve })
+      off += socket.write(bytes.subarray(off))
+    }
+  }
+
+  wakeDrain(): void {
+    const w = this.drainWaiter
+    if (w) {
+      this.drainWaiter = null
+      w()
+    }
+  }
+
+  push(chunk: Uint8Array): void {
+    // Body-streaming mode: route body bytes straight to the per-connection queue
+    // the ReadableStream drains, instead of copying into `buf` and slicing back
+    // out — halving body copies on the hot HTML/asset path. Bun reuses `chunk`
+    // after this callback, so the slice (one necessary copy) keeps the bytes.
+    if (this.bodyQueue) {
+      const n = chunk.length <= this.bodyRemaining ? chunk.length : this.bodyRemaining
+      if (n > 0)
+        this.bodyQueue.push(chunk.slice(0, n))
+      this.bodyRemaining -= n
+      if (n < chunk.length) // bytes past the body (pipelined/over-long) — keep for finish logic
+        this.appendToBuf(chunk.subarray(n))
+      this.wake()
+      return
+    }
+    this.appendToBuf(chunk)
+    this.wake()
+  }
+
+  private appendToBuf(chunk: Uint8Array): void {
+    const need = this.len + chunk.length
+    if (need > this.buf.length) {
+      const grown = new Uint8Array(Math.max(this.buf.length * 2, need))
+      grown.set(this.buf.subarray(0, this.len))
+      this.buf = grown
+    }
+    this.buf.set(chunk, this.len)
+    this.len = need
+  }
+
+  markClosed(): void {
+    this.closed = true
+    // Release both a pending reader and a pending writer — neither can make
+    // progress on a closed socket.
+    this.wake()
+    this.wakeDrain()
+  }
+
+  /** The socket's inactivity timeout fired: flag it (→ 504) and tear it down. */
+  markTimedOut(): void {
+    this.timedOut = true
+    this.markClosed()
+  }
+
+  private wake(): void {
+    const w = this.waiter
+    if (w) {
+      this.waiter = null
+      w()
+    }
+  }
+
+  /**
+   * Resolve once the buffer has grown past `seen` bytes (i.e. *new* data has
+   * arrived) or the socket has closed. Callers pass the length they have already
+   * inspected — crucial for the header/chunk-line scanners, which don't advance
+   * `pos` while searching: a plain "resolve if len>pos" would busy-spin on
+   * microtasks (starving the I/O callback) when a line arrives split across TCP
+   * segments. Waiting for `len > seen` instead yields to the event loop.
+   */
+  waitForData(seen: number): Promise<void> {
+    if (this.len > seen || this.closed)
+      return Promise.resolve()
+    return new Promise<void>((resolve) => { this.waiter = resolve })
+  }
+
+  /** Resolve once the body queue has a chunk to drain or the socket has closed. */
+  waitForBody(): Promise<void> {
+    if ((this.bodyQueue !== null && this.bodyQueue.length > 0) || this.closed)
+      return Promise.resolve()
+    return new Promise<void>((resolve) => { this.waiter = resolve })
+  }
+
+  /** Drop already-consumed bytes so the buffer doesn't grow unbounded across reuse. */
+  compact(): void {
+    if (this.pos === 0)
+      return
+    if (this.pos === this.len) {
+      this.pos = 0
+      this.len = 0
+      return
+    }
+    this.buf.copyWithin(0, this.pos, this.len)
+    this.len -= this.pos
+    this.pos = 0
+  }
+
+  destroy(): void {
+    this.closed = true
+    try { this.socket?.end() }
+    catch { /* already gone */ }
+    this.socket = null
+  }
+}
+
+/**
+ * A bounded keepalive connection pool for a single upstream `host:port`.
+ *
+ * It caps the *total* number of open connections at `maxTotal` and **queues**
+ * requests that arrive while every connection is busy, handing each released
+ * connection straight to the next waiter. Connections are only ever closed on
+ * error or after sitting idle past the timeout — never on the hot release path.
+ *
+ * Bounding the total (rather than just the idle set) is what makes it
+ * collapse-safe: a fixed set of connections is reused indefinitely, so there is
+ * no per-request churn to pile sockets into TIME_WAIT and exhaust ephemeral
+ * ports under a flood. The price is that at concurrency above `maxTotal`,
+ * throughput is bounded by the pool size instead of growing unbounded — exactly
+ * the trade nginx makes, and the reason it stays up under load.
+ */
+class UpstreamPool {
+  private idle: Conn[] = []
+  /** Requests waiting for a connection when all `maxTotal` are busy. */
+  private waiters: Array<(c: Conn | null) => void> = []
+  /** Open connections (idle + checked-out). Capped at {@link maxTotal}. */
+  private open = 0
+  /** Lazily-started interval that closes connections idle past {@link IDLE_TIMEOUT_MS}. */
+  private sweeper: ReturnType<typeof setInterval> | null = null
+  /** Max ms a request waits for a free slot before getting {@link POOL_BUSY}. */
+  private readonly queueWaitMs = queueWaitMs()
+  /** Hard ceiling on {@link waiters} length; beyond it, reject with {@link POOL_BUSY}. */
+  private readonly maxWaiters: number
+
+  constructor(private host: string, private port: number, private maxTotal: number) {
+    this.maxWaiters = maxQueued(maxTotal)
+  }
+
+  dial(): Promise<Conn> {
+    const conn = new Conn()
+    return connect({
+      hostname: this.host,
+      port: this.port,
+      socket: {
+        data: (_s, chunk) => conn.push(chunk),
+        drain: () => conn.wakeDrain(),
+        close: () => conn.markClosed(),
+        end: () => conn.markClosed(),
+        error: () => conn.markClosed(),
+        connectError: () => conn.markClosed(),
+        timeout: () => conn.markTimedOut(),
+      },
+    }).then((socket) => {
+      const s = socket as unknown as {
+        setNoDelay?: (v: boolean) => void
+        timeout?: (seconds: number) => void
+      }
+      // Disable Nagle: proxy writes a complete request in one shot and wants it
+      // on the wire immediately, not coalesced.
+      s.setNoDelay?.(true)
+      // Bound a fully-stalled upstream (opt-in; resets on every byte).
+      const t = upstreamTimeoutSeconds()
+      if (t > 0)
+        s.timeout?.(t)
+      conn.socket = socket as unknown as import('bun').Socket<undefined>
+      return conn
+    })
+  }
+
+  /** Pop a live idle connection synchronously (the hot path), or null if none. */
+  acquireIdleSync(): Conn | null {
+    while (this.idle.length) {
+      const c = this.idle.pop()!
+      if (!c.closed) {
+        // Re-ref the socket: it is now active and must keep the loop alive while
+        // we await the upstream response.
+        c.socket?.ref()
+        c.pos = 0
+        c.len = 0
+        return c
+      }
+      this.open-- // a dead idle connection no longer counts toward the cap
+    }
+    return null
+  }
+
+  /**
+   * Get a connection when the idle set is empty: dial a fresh one if under the
+   * cap, otherwise wait for one to be released. Only awaited off the hot path.
+   */
+  async acquireOrDial(): Promise<Conn> {
+    if (this.open >= this.maxTotal) {
+      // Reject immediately once the queue is full — never let it grow unbounded.
+      if (this.waiters.length >= this.maxWaiters)
+        throw POOL_BUSY
+      const c = await this.waitForSlot()
+      if (c === POOL_BUSY)
+        throw POOL_BUSY
+      if (c) {
+        c.pos = 0
+        c.len = 0
+        return c
+      }
+      // Woken with null — a slot was freed by a closed connection; dial below.
+    }
+    this.open++
+    try {
+      return await this.dial()
+    }
+    catch (err) {
+      this.open--
+      this.wakeWaiter()
+      throw err
+    }
+  }
+
+  /**
+   * Wait for a connection to be released to us, bounded by {@link queueWaitMs}.
+   * Resolves with a reused {@link Conn}, `null` (a slot freed up — dial a fresh
+   * one), or {@link POOL_BUSY} on timeout. On timeout the waiter is removed from
+   * the queue so a freed slot is never handed to a request that already gave up.
+   */
+  private waitForSlot(): Promise<Conn | null | typeof POOL_BUSY> {
+    return new Promise((resolve) => {
+      let settled = false
+      const finish = (v: Conn | null | typeof POOL_BUSY): void => {
+        if (settled)
+          return
+        settled = true
+        clearTimeout(timer)
+        resolve(v)
+      }
+      // The resolver stored in `waiters` clears the timer on a real wake-up.
+      const waiter = (c: Conn | null): void => finish(c)
+      const timer = setTimeout(() => {
+        const i = this.waiters.indexOf(waiter)
+        if (i !== -1)
+          this.waiters.splice(i, 1)
+        finish(POOL_BUSY)
+      }, this.queueWaitMs)
+      timer.unref?.()
+      this.waiters.push(waiter)
+    })
+  }
+
+  /** Hand a healthy connection to the next waiter, or return it to the idle set. */
+  release(conn: Conn): void {
+    if (conn.closed) {
+      this.open--
+      this.wakeWaiter()
+      return
+    }
+    conn.compact()
+    conn.fresh = false
+    const waiter = this.waiters.shift()
+    if (waiter) {
+      // Reuse directly for a queued request — connection stays checked out.
+      conn.socket?.ref()
+      waiter(conn)
+      return
+    }
+    conn.idleSince = Date.now()
+    // An idle pooled socket must not keep the process alive on its own; a single
+    // periodic sweep (not a per-request timer) expires connections idle past the
+    // timeout, mirroring nginx keepalive_timeout without per-request overhead.
+    conn.socket?.unref()
+    this.idle.push(conn)
+    this.ensureSweeper()
+  }
+
+  /** Permanently drop a connection (protocol error / unreusable framing). */
+  destroy(conn: Conn): void {
+    conn.destroy()
+    this.open--
+    this.wakeWaiter()
+  }
+
+  /** A slot freed up — wake one waiter to dial a fresh connection. */
+  private wakeWaiter(): void {
+    const waiter = this.waiters.shift()
+    if (waiter)
+      waiter(null)
+  }
+
+  /** Start the idle sweeper on first use; it self-stops once the pool drains. */
+  private ensureSweeper(): void {
+    if (this.sweeper)
+      return
+    this.sweeper = setInterval(() => this.sweep(), IDLE_TIMEOUT_MS)
+    // Don't let the sweeper keep the process alive.
+    this.sweeper.unref?.()
+  }
+
+  /** Close connections idle longer than the timeout; stop sweeping when empty. */
+  private sweep(): void {
+    const cutoff = Date.now() - IDLE_TIMEOUT_MS
+    if (this.idle.length) {
+      const survivors: Conn[] = []
+      for (const c of this.idle) {
+        if (c.closed || c.idleSince <= cutoff) {
+          c.destroy()
+          this.open--
+        }
+        else {
+          survivors.push(c)
+        }
+      }
+      this.idle = survivors
+    }
+    if (this.idle.length === 0 && this.sweeper) {
+      clearInterval(this.sweeper)
+      this.sweeper = null
+    }
+  }
+}
+
+const pools = new Map<string, UpstreamPool>()
+
+/** Get (or create) the pool for `host:port`. */
+function poolFor(hostPort: string, maxPerHost: number): UpstreamPool {
+  let pool = pools.get(hostPort)
+  if (!pool) {
+    const idx = hostPort.lastIndexOf(':')
+    const host = idx === -1 ? hostPort : hostPort.slice(0, idx)
+    const port = idx === -1 ? 80 : Number(hostPort.slice(idx + 1))
+    pool = new UpstreamPool(host, port, maxPerHost)
+    pools.set(hostPort, pool)
+  }
+  return pool
+}
+
+interface ParsedHead {
+  status: number
+  headerEnd: number // index of the start of CRLFCRLF
+  headers: Array<[string, string]>
+  contentLength: number // -1 if absent
+  chunked: boolean
+  closeConn: boolean // upstream asked to close (or HTTP/1.0)
+}
+
+/** Scan for the end of the header block (\r\n\r\n). Returns the index of \r or -1. */
+function findHeaderEnd(buf: Uint8Array, len: number, from: number): number {
+  for (let i = from + 3; i < len; i++) {
+    if (buf[i] === 10 && buf[i - 1] === 13 && buf[i - 2] === 10 && buf[i - 3] === 13)
+      return i - 3
+  }
+  return -1
+}
+
+/** Parse a complete response header block sitting in `buf[start..headerEnd)`. */
+function parseHead(buf: Uint8Array, start: number, headerEnd: number): ParsedHead {
+  const text = decoder.decode(buf.subarray(start, headerEnd))
+  const firstEol = text.indexOf('\r\n')
+  const statusLine = firstEol === -1 ? text : text.slice(0, firstEol)
+  // "HTTP/1.1 200 OK" → status is the token after the first space.
+  const sp = statusLine.indexOf(' ')
+  const status = Number.parseInt(statusLine.slice(sp + 1, sp + 5), 10)
+  const http10 = statusLine.startsWith('HTTP/1.0')
+
+  const headers: Array<[string, string]> = []
+  let contentLength = -1
+  let chunked = false
+  let closeConn = http10
+  let keepAliveSeen = false
+
+  let pos = firstEol === -1 ? text.length : firstEol + 2
+  while (pos < text.length) {
+    let eol = text.indexOf('\r\n', pos)
+    if (eol === -1)
+      eol = text.length
+    const line = text.slice(pos, eol)
+    pos = eol + 2
+    if (line === '')
+      continue
+    const colon = line.indexOf(':')
+    if (colon === -1)
+      continue
+    const name = line.slice(0, colon)
+    const value = line.slice(colon + 1).trim()
+    // Only the framing/strip headers (content-length, transfer-encoding,
+    // connection, keep-alive) start with c/t/k — so skip the toLowerCase for
+    // every other header (date, server, content-type-pass-through, etc.).
+    const first = name.charCodeAt(0) | 0x20
+    if (first === 99 || first === 116 || first === 107) {
+      const lower = name.toLowerCase()
+      if (lower === 'content-length') {
+        contentLength = Number.parseInt(value, 10)
+        continue
+      }
+      if (lower === 'transfer-encoding') {
+        if (value.toLowerCase().includes('chunked'))
+          chunked = true
+        continue
+      }
+      if (lower === 'connection') {
+        const v = value.toLowerCase()
+        if (v.includes('close'))
+          closeConn = true
+        if (v.includes('keep-alive'))
+          keepAliveSeen = true
+        continue
+      }
+      if (lower === 'keep-alive')
+        continue
+    }
+    headers.push([name, value])
+  }
+  if (http10 && keepAliveSeen)
+    closeConn = false
+
+  return { status, headerEnd, headers, contentLength, chunked, closeConn }
+}
+
+/**
+ * Whether a response with this status / method carries no body (RFC 7230 §3.3.3).
+ * Interim 1xx responses are handled separately (skipped) before this is reached.
+ */
+function isBodyless(status: number, isHead: boolean): boolean {
+  return isHead || status === 204 || status === 304
+}
+
+export interface PoolRequest {
+  /** Upstream `host:port`. */
+  hostPort: string
+  method: string
+  /** Path + query (origin-form), e.g. `/api/x?y=1`. */
+  path: string
+  /** The original client request headers, forwarded minus framing/override keys. */
+  reqHeaders: Headers
+  /** Value for the upstream `x-forwarded-host` (the client-facing hostname). */
+  forwardedHost: string
+  /** When set (changeOrigin), the `origin` header value; also drops the client's. */
+  originOverride?: string
+  /** Request body stream, or null. */
+  body: ReadableStream<Uint8Array> | null
+  /** Max idle connections kept per upstream. */
+  maxPerHost?: number
+}
+
+/**
+ * Forward a request through the pooled transport and return the upstream
+ * {@link Response}. Throws {@link FALLBACK} for cases it intentionally declines
+ * (large/streaming uploads, `Expect`, upgrades) so the caller can use `fetch()`.
+ */
+export async function proxyViaPool(reqOpts: PoolRequest): Promise<Response> {
+  const { hostPort, method, path, reqHeaders, forwardedHost, originOverride, body } = reqOpts
+  const isHead = method === 'HEAD'
+
+  // Decline anything that needs request-time negotiation or a hijacked socket.
+  if (reqHeaders.get('expect') || reqHeaders.get('upgrade'))
+    throw FALLBACK
+
+  // Materialize the request body up-front (keeps retries safe) — but only when
+  // it's small. Large/streaming uploads go through fetch(), which handles
+  // backpressure properly.
+  let bodyBytes: Uint8Array | null = null
+  if (body) {
+    // Only handle bodies with a known, modest Content-Length. Streaming or
+    // unknown-length uploads are declined *before* the stream is touched, so the
+    // caller can still hand the untouched body to fetch().
+    const lenHeader = reqHeaders.get('content-length')
+    const declared = lenHeader ? Number.parseInt(lenHeader, 10) : Number.NaN
+    if (Number.isNaN(declared) || declared > MAX_BUFFERED_BODY)
+      throw FALLBACK
+    bodyBytes = await readBodyCapped(body)
+    if (bodyBytes === null)
+      throw FALLBACK // exceeded cap while reading (Content-Length under-declared)
+  }
+
+  const head = serializeRequest(method, path, reqHeaders, hostPort, forwardedHost, originOverride, bodyBytes)
+  // Send the head and (buffered) body as one write so the common request is a
+  // single syscall with no body-write await.
+  let payload = head
+  if (bodyBytes && bodyBytes.length) {
+    payload = new Uint8Array(head.length + bodyBytes.length)
+    payload.set(head)
+    payload.set(bodyBytes, head.length)
+  }
+  const pool = poolFor(hostPort, reqOpts.maxPerHost ?? maxTotalConns())
+
+  // One transparent retry: a reused keepalive socket may have been closed by the
+  // upstream between requests; if it dies before we read any response, retry on a
+  // fresh connection (always safe — the body is buffered).
+  for (let attempt = 0; ; attempt++) {
+    // Reuse a pooled connection synchronously when one is available (no await on
+    // the hot path); otherwise dial a fresh one or queue for a free slot.
+    const conn = pool.acquireIdleSync() ?? await pool.acquireOrDial()
+    try {
+      const written = conn.socket!.write(payload)
+      if (written < payload.length)
+        await conn.writeAll(payload.subarray(written))
+      return await readResponse(pool, conn, isHead)
+    }
+    catch (err) {
+      const retryable = !conn.fresh && attempt === 0 && err === STALE
+      pool.destroy(conn)
+      if (retryable)
+        continue
+      if (err === STALE)
+        throw new Error('upstream closed connection')
+      throw err
+    }
+  }
+}
+
+/** Block until the full response header block (\r\n\r\n) is buffered. */
+async function waitForHead(conn: Conn): Promise<number> {
+  let headerEnd = findHeaderEnd(conn.buf, conn.len, conn.pos)
+  while (headerEnd === -1) {
+    if (conn.closed) {
+      if (conn.timedOut)
+        throw TIMEOUT
+      // Nothing (or only a partial head) arrived — treat as a stale socket.
+      if (conn.len === conn.pos)
+        throw STALE
+      throw new Error('upstream closed mid-header')
+    }
+    // Bound the header block: an upstream that streams bytes without ever
+    // sending `\r\n\r\n` would otherwise grow `buf` unbounded until OOM.
+    if (conn.len - conn.pos > MAX_HEADER_BYTES)
+      throw new Error('upstream header block too large')
+    await conn.waitForData(conn.len)
+    headerEnd = findHeaderEnd(conn.buf, conn.len, conn.pos)
+  }
+  return headerEnd
+}
+
+/** Read the response head + body from `conn`, returning a streaming Response. */
+async function readResponse(pool: UpstreamPool, conn: Conn, isHead: boolean): Promise<Response> {
+  // Skip any interim 1xx responses (e.g. an unsolicited `103 Early Hints`); they
+  // are header-only and precede the real response on the same connection. (`101`
+  // can't occur here — we decline upgrades up front.)
+  let head: ParsedHead
+  for (;;) {
+    const headerEnd = await waitForHead(conn)
+    head = parseHead(conn.buf, conn.pos, headerEnd)
+    conn.pos = headerEnd + 4
+    if (head.status >= 100 && head.status < 200)
+      continue
+    break
+  }
+
+  // Pass the [name, value][] array straight to Response as HeadersInit — no
+  // intermediate Headers allocation on the hot path.
+  const responseHeaders = head.headers
+
+  if (isBodyless(head.status, isHead)) {
+    finishConn(pool, conn, head.closeConn)
+    return new Response(null, { status: head.status, headers: responseHeaders })
+  }
+
+  if (head.chunked)
+    return new Response(chunkedStream(pool, conn, head.closeConn), { status: head.status, headers: responseHeaders })
+
+  if (head.contentLength >= 0) {
+    // Fast path: the whole body is already buffered — hand back bytes directly,
+    // no ReadableStream machinery. (`finishConn` destroys the connection instead
+    // of pooling it if there are leftover bytes after the body.)
+    const available = conn.len - conn.pos
+    if (available >= head.contentLength) {
+      const bodyEnd = conn.pos + head.contentLength
+      const leftover = conn.len > bodyEnd
+      let out: Uint8Array | null = null
+      if (head.contentLength >= BODY_HANDOFF_THRESHOLD) {
+        // Large body: hand over a view and swap in a fresh (small) buffer, so we
+        // don't copy the whole body just to wrap it in a Response.
+        out = conn.buf.subarray(conn.pos, bodyEnd)
+        conn.buf = new Uint8Array(HANDOFF_BUF)
+      }
+      else if (head.contentLength > 0) {
+        out = conn.buf.slice(conn.pos, bodyEnd) // small body: a copy beats a fresh alloc
+      }
+      conn.pos = 0
+      conn.len = 0
+      // Leftover bytes after the body ⇒ pipelined/over-long ⇒ unsafe to reuse.
+      if (head.closeConn || leftover)
+        pool.destroy(conn)
+      else
+        pool.release(conn)
+      return new Response(out, { status: head.status, headers: responseHeaders })
+    }
+    return new Response(fixedLengthStream(pool, conn, head.contentLength, head.closeConn), {
+      status: head.status,
+      headers: responseHeaders,
+    })
+  }
+
+  // No framing info: body runs until the connection closes; not reusable.
+  return new Response(untilCloseStream(conn), { status: head.status, headers: responseHeaders })
+}
+
+/**
+ * Return a connection to the pool, or destroy it when it can't be safely reused:
+ * the upstream asked to close, or there are leftover bytes after the body (a
+ * pipelined/over-long response we don't support — reusing it would mis-frame the
+ * next response).
+ */
+function finishConn(pool: UpstreamPool, conn: Conn, closeConn: boolean): void {
+  if (closeConn || conn.pos !== conn.len)
+    pool.destroy(conn)
+  else
+    pool.release(conn)
+}
+
+/**
+ * Stream a Content-Length body via the connection's body queue. The already-
+ * buffered prefix is copied out once; every later socket chunk is copied
+ * straight into the queue by {@link Conn.push} (no second copy through `buf`),
+ * which is the dominant saving when proxying HTML/asset-sized responses.
+ */
+function fixedLengthStream(pool: UpstreamPool, conn: Conn, contentLength: number, closeConn: boolean): ReadableStream<Uint8Array> {
+  const buffered = conn.len - conn.pos // body bytes that arrived with the headers
+  const first = buffered > 0 ? conn.buf.slice(conn.pos, conn.len) : null
+  // Switch into body-streaming mode: clear the read buffer (its body bytes are
+  // captured in `first`); subsequent socket data flows to bodyQueue.
+  conn.pos = 0
+  conn.len = 0
+  conn.bodyQueue = []
+  conn.bodyRemaining = contentLength - buffered
+
+  const finish = (controller: ReadableStreamDefaultController<Uint8Array>): void => {
+    conn.bodyQueue = null
+    // Bytes past the body landed back in `buf` ⇒ pipelined/over-long ⇒ don't reuse.
+    if (closeConn || conn.len > 0)
+      pool.destroy(conn)
+    else
+      pool.release(conn)
+    controller.close()
+  }
+
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      if (first)
+        controller.enqueue(first)
+      if (conn.bodyRemaining === 0 && conn.bodyQueue!.length === 0)
+        finish(controller)
+    },
+    async pull(controller) {
+      for (;;) {
+        const q = conn.bodyQueue
+        if (q && q.length > 0) {
+          controller.enqueue(q.shift()!)
+          if (conn.bodyRemaining === 0 && q.length === 0)
+            finish(controller)
+          return
+        }
+        if (conn.bodyRemaining === 0) {
+          if (conn.bodyQueue)
+            finish(controller)
+          return
+        }
+        if (conn.closed) {
+          conn.bodyQueue = null
+          pool.destroy(conn)
+          controller.error(new Error('upstream closed mid-body'))
+          return
+        }
+        await conn.waitForBody()
+      }
+    },
+    cancel() {
+      conn.bodyQueue = null
+      pool.destroy(conn)
+    },
+  })
+}
+
+/** Stream a body that runs until the upstream closes the connection (never reused). */
+function untilCloseStream(conn: Conn): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      for (;;) {
+        if (conn.len > conn.pos) {
+          controller.enqueue(conn.buf.slice(conn.pos, conn.len))
+          conn.pos = conn.len
+          return
+        }
+        if (conn.closed) {
+          conn.destroy()
+          controller.close()
+          return
+        }
+        await conn.waitForData(conn.len)
+      }
+    },
+    cancel() {
+      conn.destroy()
+    },
+  })
+}
+
+/**
+ * Decode a `Transfer-Encoding: chunked` body and stream the decoded bytes. Bun
+ * re-frames the outgoing response to the client, so we hand it the dechunked
+ * payload (with `transfer-encoding` already stripped from the headers).
+ */
+function chunkedStream(pool: UpstreamPool, conn: Conn, closeConn: boolean): ReadableStream<Uint8Array> {
+  let remaining = 0 // bytes left in the current chunk
+  let needTrailerCrlf = false // consume the CRLF after a chunk's data
+
+  // Read the next CRLF-terminated line starting at conn.pos (chunk-size / trailer).
+  async function readLine(): Promise<string> {
+    for (;;) {
+      for (let i = conn.pos; i + 1 < conn.len; i++) {
+        if (conn.buf[i] === 13 && conn.buf[i + 1] === 10) {
+          const line = decoder.decode(conn.buf.subarray(conn.pos, i))
+          conn.pos = i + 2
+          return line
+        }
+      }
+      if (conn.closed)
+        throw new Error('upstream closed mid-chunk-header')
+      await conn.waitForData(conn.len)
+    }
+  }
+
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      for (;;) {
+        if (remaining > 0) {
+          if (conn.len === conn.pos) {
+            if (conn.closed) {
+              pool.destroy(conn)
+              controller.error(new Error('upstream closed mid-chunk'))
+              return
+            }
+            await conn.waitForData(conn.len)
+            continue
+          }
+          const take = Math.min(remaining, conn.len - conn.pos)
+          controller.enqueue(conn.buf.slice(conn.pos, conn.pos + take))
+          conn.pos += take
+          remaining -= take
+          if (remaining === 0)
+            needTrailerCrlf = true
+          return
+        }
+        if (needTrailerCrlf) {
+          await readLine() // the empty CRLF closing the chunk data
+          needTrailerCrlf = false
+        }
+        const sizeLine = await readLine()
+        const semi = sizeLine.indexOf(';')
+        const size = Number.parseInt(semi === -1 ? sizeLine : sizeLine.slice(0, semi), 16)
+        if (size === 0) {
+          // Consume optional trailers up to the final blank line.
+          for (;;) {
+            const t = await readLine()
+            if (t === '')
+              break
+          }
+          finishConn(pool, conn, closeConn)
+          controller.close()
+          return
+        }
+        remaining = size
+      }
+    },
+    cancel() {
+      pool.destroy(conn)
+    },
+  })
+}
+
+/**
+ * Serialize the request line + headers. The forwarded headers (host,
+ * x-forwarded-*, optional origin) are written inline — no per-request overrides
+ * array — and their keys are skipped in the client-header passthrough so values
+ * aren't duplicated. Content-Length is injected when a buffered body has no
+ * declared length.
+ */
+function serializeRequest(
+  method: string,
+  path: string,
+  reqHeaders: Headers,
+  hostValue: string,
+  forwardedHost: string,
+  originOverride: string | undefined,
+  bodyBytes: Uint8Array | null,
+): Uint8Array {
+  let head = `${method} ${path} HTTP/1.1\r\nhost: ${hostValue}\r\n`
+    + `x-forwarded-for: 127.0.0.1\r\nx-forwarded-proto: https\r\n`
+    + `x-forwarded-host: ${forwardedHost}\r\n`
+  if (originOverride !== undefined)
+    head += `origin: ${originOverride}\r\n`
+
+  let sawContentLength = false
+  for (const [name, value] of reqHeaders) {
+    const lower = name.toLowerCase()
+    if (STRIP_REQUEST.has(lower))
+      continue
+    if (originOverride !== undefined && lower === 'origin')
+      continue
+    if (lower === 'content-length')
+      sawContentLength = true
+    head += `${name}: ${value}\r\n`
+  }
+  head += 'connection: keep-alive\r\n'
+  if (bodyBytes && !sawContentLength)
+    head += `content-length: ${bodyBytes.length}\r\n`
+  head += '\r\n'
+  return encoder.encode(head)
+}
+
+/** Read a request body fully, returning null if it exceeds {@link MAX_BUFFERED_BODY}. */
+async function readBodyCapped(body: ReadableStream<Uint8Array>): Promise<Uint8Array | null> {
+  const reader = body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done)
+      break
+    if (value) {
+      total += value.length
+      if (total > MAX_BUFFERED_BODY) {
+        reader.cancel().catch(() => {})
+        return null
+      }
+      chunks.push(value)
+    }
+  }
+  if (chunks.length === 1)
+    return chunks[0]
+  const out = new Uint8Array(total)
+  let off = 0
+  for (const c of chunks) {
+    out.set(c, off)
+    off += c.length
+  }
+  return out
+}