castrum 0.9.7 → 0.9.9

package/src/ingress/server-node.ts

@@ -22,6 +22,7 @@ import {
 import { type Duplex, Readable } from 'node:stream'
 import { buildPathMatcher } from './path-matcher'
 import { fallbackHandler } from './routes'
+import { createServerErrorHandler } from './server-error'
 import {
   type BakedServer,
   buildRouteHandlers,
@@ -52,8 +53,20 @@ export interface NodeIngressServer extends BakedServer {
   ready: Promise<number>
 }
 
-/** Convert a Node IncomingMessage into a web-standard Request. */
-function nodeRequestToWebRequest(req: IncomingMessage): Request {
+/**
+ * Convert a Node IncomingMessage into a web-standard `Request`.
+ *
+ * Node's `IncomingMessage` has no web `AbortSignal`, so this bridges one to
+ * `Request.signal`: the request aborts when the client disconnects — on the
+ * explicit `'aborted'` event, or on `'close'` while the request has NOT
+ * completed (`close` after a fully-received request is normal socket
+ * teardown and must not abort). Exported so the adapter's signal wiring is
+ * unit-testable without a socket.
+ *
+ * @param req - The Node incoming request.
+ * @returns A web `Request` whose `signal` tracks client disconnect.
+ */
+export function nodeRequestToWebRequest(req: IncomingMessage): Request {
   const host = req.headers.host ?? 'localhost'
   const url = new URL(req.url ?? '/', `http://${host}`)
 
@@ -73,11 +86,20 @@ function nodeRequestToWebRequest(req: IncomingMessage): Request {
   // request actually carries one (content-length > 0 or chunked), so DELETE/
   // OPTIONS-with-a-body are no longer dropped.
   const bodyForbidden = method === 'GET' || method === 'HEAD'
-  const hasBody =
-    Number(req.headers['content-length'] ?? 0) > 0 || req.headers['transfer-encoding'] !== undefined
+  const hasBody = requestHasBody(req)
 
   const init: RequestInit & { duplex?: 'half' } = { method, headers }
 
+  // Client-disconnect bridge (Node-only code — the Bun path uses Bun's native
+  // `Request.signal`). `abort()` is idempotent, so the two listeners may both
+  // fire on a premature close.
+  const abort = new AbortController()
+  req.on('aborted', () => abort.abort())
+  req.on('close', () => {
+    if (!req.complete) abort.abort()
+  })
+  init.signal = abort.signal
+
   // Stream the request body through (the route handlers call
   // `req.arrayBuffer()` which drains this stream).
   if (hasBody && !bodyForbidden) {
@@ -143,7 +165,7 @@ async function writeResponse(res: ServerResponse, response: Response): Promise<v
  */
 function drainUnreadBody(res: ServerResponse): void {
   const req = res.req
-  if (req !== undefined && req !== null && !req.complete && hasBody(req)) {
+  if (req !== undefined && req !== null && !req.complete && requestHasBody(req)) {
     req.resume()
     // Only force-close when the request actually carried a body that was not
     // consumed. A bodiless GET/HEAD is always safe to keep alive (bun's
@@ -156,12 +178,60 @@ function drainUnreadBody(res: ServerResponse): void {
 }
 
 /** Whether an incoming request carried a body (content-length or chunked). */
-function hasBody(req: IncomingMessage): boolean {
+function requestHasBody(req: IncomingMessage): boolean {
   return (
     Number(req.headers['content-length'] ?? 0) > 0 || req.headers['transfer-encoding'] !== undefined
   )
 }
 
+/**
+ * Cached body/status/headers for a bare static `Response` route value.
+ *
+ * A web `Response` body is ONE-SHOT: writing it once consumes the stream.
+ * `Bun.serve` snapshots a bare `Response` into its native table, but the
+ * node:http adapter must materialize a FRESH `Response` per request, so the
+ * body is read once and the bytes cached. The WeakMap key is the original
+ * `Response` instance, so the cache never retains anything the route table
+ * does not already hold. The cached value is the in-flight PROMISE (not the
+ * resolved bytes) so concurrent first requests share ONE body read instead of
+ * racing to consume the same one-shot stream.
+ */
+const STATIC_RESPONSE_CACHE = new WeakMap<
+  Response,
+  Promise<{ status: number; statusText: string; headers: Headers; body: Uint8Array | null }>
+>()
+
+/** Materialize a fresh, unconsumed `Response` from a static route value. */
+function materializeStaticResponse(response: Response): Promise<Response> {
+  let cached = STATIC_RESPONSE_CACHE.get(response)
+  if (cached === undefined) {
+    cached = (async () => {
+      const body = response.body === null ? null : new Uint8Array(await response.arrayBuffer())
+      const headers = new Headers(response.headers)
+      // Framing headers describe the ORIGINAL stream; drop them so the runtime
+      // recomputes them from the re-materialized body (avoiding a stale
+      // `content-length` on every replay).
+      headers.delete('content-length')
+      headers.delete('transfer-encoding')
+      return {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+        body,
+      }
+    })()
+    STATIC_RESPONSE_CACHE.set(response, cached)
+  }
+  return cached.then(
+    (c) =>
+      new Response(c.body, {
+        status: c.status,
+        statusText: c.statusText,
+        headers: new Headers(c.headers),
+      }),
+  )
+}
+
 /** Build a request listener that dispatches to the shared route map. */
 function makeRequestListener(
   options: CreateIngressServerOptions,
@@ -170,6 +240,11 @@ function makeRequestListener(
 ): (req: IncomingMessage, res: ServerResponse) => Promise<void> {
   // Exact paths win; `:param`/`*` patterns are matched most-specific-first.
   const matchPath = buildPathMatcher(routes)
+  // Shared masked-500 responder: same body + `onError` hook as the Bun path.
+  const onServerError = createServerErrorHandler({
+    onError: options.onError,
+    logger: options.logger,
+  })
 
   return async (req, res) => {
     try {
@@ -202,14 +277,27 @@ function makeRequestListener(
       const method = webReq.method ?? 'GET'
 
       const matched = matchPath(pathname)
-      const handler = matched?.methods?.[method] as RouteHandler | undefined
+      const entry = matched?.methods?.[method]
 
       let response: Response
-      if (handler !== undefined && matched !== undefined) {
+      if (entry !== undefined && matched !== undefined) {
         // The ingress pipeline does not echo path params, so matching only
         // selects the handler; the extracted params are passed as a 3rd arg
         // (ignored by current handlers) for future/raw-handler use.
-        response = await handler(webReq, req, matched.params)
+        if (typeof entry === 'function') {
+          response = await (entry as RouteHandler)(webReq, req, matched.params)
+        } else if (entry instanceof Response) {
+          // Bare static route value (Bun's native-table path). Node cannot
+          // replay a consumed body, so build a fresh Response per request.
+          // `instanceof Response` assumes the value was built with the global
+          // `Response` constructor (the one this adapter also uses).
+          response = await materializeStaticResponse(entry)
+        } else if (options.fallback !== undefined) {
+          const fallback = fallbackHandler(options.fallback, baseOpts)
+          response = await fallback(webReq, req)
+        } else {
+          response = new Response('Not Found', { status: 404 })
+        }
       } else if (options.fallback !== undefined) {
         const fallback = fallbackHandler(options.fallback, baseOpts)
         response = await fallback(webReq, req)
@@ -219,28 +307,18 @@ function makeRequestListener(
 
       await writeResponse(res, response)
     } catch (err) {
-      // Never leave a client hanging on a handler failure.
+      // Never leave a client hanging on a handler failure. Reuse the shared
+      // masked-500 responder so both runtimes emit the same body and hook.
       if (!res.headersSent) {
-        res.statusCode = 500
-        res.setHeader('content-type', 'application/json')
-        res.end(
-          JSON.stringify({
-            error: { code: 'internal_error', message: 'Internal Server Error' },
-          }),
-        )
+        await writeResponse(res, onServerError(err))
       } else {
+        // Headers already flushed (e.g. a body-stream error mid-write): the
+        // masked 500 cannot be delivered, but the onError/logger hooks MUST
+        // still observe the failure before the socket is dropped. The returned
+        // Response is intentionally discarded.
+        onServerError(err)
         res.destroy()
       }
-      // NOTE: surfaced via the onError hook (observability phase).
-      if (options.onError) {
-        try {
-          options.onError({
-            error: err instanceof Error ? err : new Error(String(err)),
-          })
-        } catch {
-          // hook must never crash the server
-        }
-      }
     }
   }
 }
@@ -254,6 +332,35 @@ function makeRequestListener(
  * (which owns the frame codec — e.g. the `ws` library). Previously a 101 was
  * written as a normal response and the connection never became a socket.
  */
+/** RFC 6455 subprotocol is an HTTP token (no separators / control bytes). */
+const WS_PROTOCOL_TOKEN = /^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/
+
+/**
+ * Build the RFC 6455 `101 Switching Protocols` response head for a hijacked
+ * socket. `protocol` is emitted only when it is a valid HTTP token, so a caller
+ * that reflects an untrusted `Sec-WebSocket-Protocol` cannot inject CRLF or
+ * extra headers.
+ *
+ * @param accept - The `Sec-WebSocket-Accept` value (must contain no CR/LF).
+ * @param protocol - Optional negotiated subprotocol.
+ * @returns The raw response head, terminated by a blank line.
+ * @throws If `accept` contains a CR/LF.
+ */
+export function formatWebSocketHandshake(accept: string, protocol?: string | null): string {
+  if (/[\r\n]/.test(accept)) {
+    throw new Error('invalid Sec-WebSocket-Accept value')
+  }
+  let raw =
+    'HTTP/1.1 101 Switching Protocols\r\n' +
+    'Upgrade: websocket\r\n' +
+    'Connection: Upgrade\r\n' +
+    `Sec-WebSocket-Accept: ${accept}\r\n`
+  if (protocol && WS_PROTOCOL_TOKEN.test(protocol)) {
+    raw += `Sec-WebSocket-Protocol: ${protocol}\r\n`
+  }
+  return `${raw}\r\n`
+}
+
 function makeUpgradeListener(
   options: CreateIngressServerOptions,
 ): (req: IncomingMessage, socket: Duplex, head: Buffer) => Promise<void> {
@@ -268,16 +375,7 @@ function makeUpgradeListener(
       }
 
       // Complete the RFC 6455 handshake on the hijacked socket.
-      let raw =
-        'HTTP/1.1 101 Switching Protocols\r\n' +
-        'Upgrade: websocket\r\n' +
-        'Connection: Upgrade\r\n' +
-        `Sec-WebSocket-Accept: ${handshake.accept}\r\n`
-      if (handshake.protocol) {
-        raw += `Sec-WebSocket-Protocol: ${handshake.protocol}\r\n`
-      }
-      raw += '\r\n'
-      socket.write(raw)
+      socket.write(formatWebSocketHandshake(handshake.accept, handshake.protocol))
 
       // Hand the upgraded socket to the caller (frame codec / message loop).
       options.onUpgrade?.(socket, req, head)

package/src/ingress/server.ts

@@ -15,6 +15,7 @@ import {
 import type { BakedHandlerOptions } from './routes/common'
 import { nativeRouteHandler } from './routes/native'
 import { nativeResponderRoute } from './routes/responder'
+import { createServerErrorHandler, guardRouteHandler } from './server-error'
 import type { NativeResponder, OptimizedIngressHandler, TerminalStyle } from './types'
 
 /** Server-level default for the socket request-body cap (16 MiB). */
@@ -33,8 +34,46 @@ export type RouteHandler = (
   params?: Record<string, string>,
 ) => Response | Promise<Response>
 
+/**
+ * A prebuilt constant response for static route promotion.
+ *
+ * Either a bare `Response` or a factory that builds a FRESH `Response` per
+ * request. Behavior differs by runtime:
+ *
+ * - **Bun**: a bare `Response` is snapshotted into `Bun.serve`'s native route
+ *   table at bind time (verified on Bun 1.4.2 — the body is NOT consumed by the
+ *   first request) and served on every request without entering JS.
+ * - **Node** (`createIngressServerNode`): the adapter reads the bare `Response`
+ *   body ONCE and materializes a fresh `Response` per request (a web body is
+ *   one-shot).
+ *
+ * A factory is invoked by the runtime on every request, so it MUST return a new
+ * `Response` each call. Returning the SAME already-sent instance fails on the
+ * second request with `ERR_BODY_ALREADY_USED` (Bun) / a consumed stream
+ * (Node) — use a factory only when the response genuinely varies per request.
+ */
+export type StaticRoute = Response | (() => Response)
+
 /** Route spec for the Bun.serve builder. */
 export interface BakedRoute {
+  /**
+   * A prebuilt constant response served for GET, bypassing the ingress
+   * pipeline entirely. Takes precedence over `read`/`cookies` for GET (the
+   * pipeline handler is never wired); other methods (`write`/`echo`/`delete`)
+   * are unaffected. See {@link StaticRoute} for the one-shot-body contract.
+   *
+   * HEAD is intentionally NOT wired for `static` (a bare `Response` carries a
+   * body; static responses are probes/constants served over GET). This matches
+   * the raw-`read` probe behavior — but note that a route which previously
+   * served HEAD via a native `read` now 405s (Node) on HEAD once `static` is
+   * set. When `static` is combined with `write`/`echo`/`delete`, those dynamic
+   * methods remain wired.
+   *
+   * Runtime note: `createIngressRouter` treats `static` differently — there,
+   * like `raw`, it OWNS THE WHOLE SPEC (the router has no compiled ingress for
+   * the other methods; see `RouterRouteSpec.static` in src/ingress/router.ts).
+   */
+  static?: StaticRoute
   /**
    * Wires GET + HEAD read handlers. Accepts an optimized ingress handler OR a
    * raw `RouteHandler` function (health/metrics probes are raw — see
@@ -113,11 +152,17 @@ export interface CreateIngressServerOptions {
   routes: Record<string, BakedRoute>
   fallback?: OptimizedIngressHandler
   /**
-   * Invoked when an unhandled error escapes a request handler (currently wired
-   * on the Node adapter; the Bun path uses runtime.onResponse). Never throws —
-   * hook failures are swallowed.
+   * Invoked when an unhandled error escapes a request handler (raw `read`
+   * functions, `responder`/`native` responders, or the Bun/Node adapter
+   * catch-all). The error is masked to a generic 500 on the wire. Never
+   * throws — hook failures are swallowed.
    */
   onError?: (info: { error: Error; request?: Request }) => void
+  /**
+   * Optional structured-log sink for escaped handler errors (one JSON line per
+   * masked 500, message only). Never throws.
+   */
+  logger?: (line: string) => void
   /** Node adapter only: ms to receive the complete request (headers + body).
    *  Guards slowloris/trickling requests. Default: 30_000. */
   requestTimeoutMs?: number
@@ -225,7 +270,7 @@ export function gracefulShutdown(
  *  options — it does not need `port` or the Node-only server fields). */
 export type BuildRouteHandlersOptions = Pick<
   CreateIngressServerOptions,
-  'routes' | 'fallback' | 'getIp' | 'copyBody'
+  'routes' | 'fallback' | 'getIp' | 'copyBody' | 'onError' | 'logger'
 >
 
 /**
@@ -243,6 +288,16 @@ export function buildRouteHandlers(options: BuildRouteHandlersOptions): {
     copyBody: options.copyBody,
   }
 
+  // Masked-500 responder for the escape-capable handlers below. Built once per
+  // server: the raw `read` function, the `responder` route, and the `native`
+  // route run OUTSIDE the native pipeline (and outside the built-in factories'
+  // own error handling). Built-in factories stay unwrapped so the hot path is
+  // unchanged.
+  const onServerError = createServerErrorHandler({
+    onError: options.onError,
+    logger: options.logger,
+  })
+
   const serverRoutes: Record<string, Record<string, unknown>> = {}
 
   for (const [path, spec] of Object.entries(options.routes)) {
@@ -252,13 +307,27 @@ export function buildRouteHandlers(options: BuildRouteHandlersOptions): {
       bodyTimeoutMs: spec.bodyTimeoutMs,
     }
     const methods: Record<string, unknown> = {}
-
-    if (spec.read) {
+    const hasStatic = spec.static !== undefined
+
+    if (hasStatic) {
+      // Static promotion: `static` owns GET and is placed in the route table
+      // verbatim (a bare Response relies on Bun's native table; see
+      // BakedRoute.static). The read/cookies GET wiring below is skipped so
+      // the ingress pipeline is NEVER entered for a static route. A
+      // function-valued factory is user code with no built-in fault
+      // containment, so guard it like a raw `read` function (a bare Response
+      // cannot throw and is placed verbatim for zero-copy Bun serving).
+      methods.GET =
+        typeof spec.static === 'function'
+          ? guardRouteHandler(spec.static, onServerError)
+          : spec.static
+    } else if (spec.read) {
       if (typeof spec.read === 'function') {
         // Raw request→Response handler (probes, /metrics): serve GET directly,
         // outside the ingress pipeline. HEAD is intentionally not wired (a raw
-        // handler returns a body; probes use GET).
-        methods.GET = spec.read
+        // handler returns a body; probes use GET). Guarded: a raw handler is
+        // user code with no built-in fault containment.
+        methods.GET = guardRouteHandler(spec.read, onServerError)
       } else {
         methods.GET = readHandler(spec.read, routeOpts)
         methods.HEAD = headHandler(spec.read, routeOpts)
@@ -279,7 +348,7 @@ export function buildRouteHandlers(options: BuildRouteHandlersOptions): {
       methods.POST = echoHandler(spec.echo, routeOpts)
     }
 
-    if (spec.cookies) {
+    if (spec.cookies && !hasStatic) {
       methods.GET = readHandler(spec.cookies, routeOpts)
     }
 
@@ -288,44 +357,65 @@ export function buildRouteHandlers(options: BuildRouteHandlersOptions): {
     }
 
     if (spec.responder) {
-      // JS responder route: native decides + rejects; JS builds the 2xx.
-      const responderRoute = nativeResponderRoute(spec.responder.ingress, spec.responder.handler, {
-        ...routeOpts,
-        terminalStyle: spec.responder.terminalStyle,
-        readBody: spec.responder.readBody,
-      })
-      const responderMethods = spec.responder.methods ?? ['GET']
-      for (const m of responderMethods) {
-        methods[m] = responderRoute
+      // JS responder route: native decides + rejects; JS builds the 2xx. The
+      // user responder is guarded — a throw/rejection becomes a masked 500.
+      // A static GET takes precedence: filter GET out of the wired methods.
+      const responderMethods = (spec.responder.methods ?? ['GET']).filter(
+        (m) => !(hasStatic && m === 'GET'),
+      )
+      if (responderMethods.length > 0) {
+        const responderRoute = nativeResponderRoute(
+          spec.responder.ingress,
+          spec.responder.handler,
+          {
+            ...routeOpts,
+            terminalStyle: spec.responder.terminalStyle,
+            readBody: spec.responder.readBody,
+          },
+        )
+        const guardedResponderRoute = guardRouteHandler(responderRoute, onServerError)
+        for (const m of responderMethods) {
+          methods[m] = guardedResponderRoute
+        }
       }
     }
 
     if (spec.native) {
       // LEAN native-stack responder route: route-wire v3 stack, no envelope.
       // The compiled route is injected into the pure route factory (DI across
-      // the purity boundary — the compile touches the dlopen layer here).
-      const nativeRoute = nativeRouteHandler(
-        createNativeRoute(spec.native.plan),
-        spec.native.handler,
-        {
-          ...routeOpts,
-          readBody: spec.native.readBody,
-        },
+      // the purity boundary — the compile touches the dlopen layer here). The
+      // user responder is guarded — a throw/rejection becomes a masked 500.
+      // A static GET takes precedence: filter GET out of the wired methods.
+      const nativeMethods = (spec.native.methods ?? ['GET']).filter(
+        (m) => !(hasStatic && m === 'GET'),
       )
-      const nativeMethods = spec.native.methods ?? ['GET']
-      for (const m of nativeMethods) {
-        methods[m] = nativeRoute
+      if (nativeMethods.length > 0) {
+        const nativeRoute = nativeRouteHandler(
+          createNativeRoute(spec.native.plan),
+          spec.native.handler,
+          {
+            ...routeOpts,
+            readBody: spec.native.readBody,
+          },
+        )
+        const guardedNativeRoute = guardRouteHandler(nativeRoute, onServerError)
+        for (const m of nativeMethods) {
+          methods[m] = guardedNativeRoute
+        }
       }
     }
 
     // CORS preflight (OPTIONS) is served for EVERY route with a NATIVE handler
     // (not just write routes with a fallback), so read-only routes also answer
     // preflights with 204/403 from the native pipeline. Raw probe handlers
-    // (plain functions) are excluded — browsers don't preflight probes.
+    // (plain functions) and the GET that `static` replaced are excluded from
+    // `primary` — browsers don't preflight probes, and a static route has no
+    // pipeline to answer with. A static route that ALSO wires `write`/`echo`/
+    // `delete` still gets OPTIONS from that other native handler.
     const primary =
       spec.delete ??
-      (spec.read && typeof spec.read !== 'function' ? spec.read : undefined) ??
-      spec.cookies ??
+      (!hasStatic && spec.read && typeof spec.read !== 'function' ? spec.read : undefined) ??
+      (!hasStatic ? spec.cookies : undefined) ??
       spec.write ??
       spec.echo
     if (primary) {
@@ -339,11 +429,10 @@ export function buildRouteHandlers(options: BuildRouteHandlersOptions): {
 }
 
 // ── Path matching (shared with server-node.ts + router.ts) ─────────
-// `buildPathMatcher` / `PathMatch` / `safeDecode` live in path-matcher.ts;
-// re-exported here for back-compat (they were historically exported from this
-// module).
+// `PathMatch` / `safeDecode` live in path-matcher.ts and are not part of this
+// module's surface; only `buildPathMatcher` is re-exported for back-compat.
 
-export { buildPathMatcher, type PathMatch, safeDecode } from './path-matcher'
+export { buildPathMatcher } from './path-matcher'
 
 /** Typed options forwarded to `Bun.serve`. */
 interface BunServerOptions {
@@ -354,6 +443,14 @@ interface BunServerOptions {
   maxRequestBodySize: number
   reusePort?: boolean
   fetch?: (req: Request) => Response | Promise<Response>
+  /**
+   * Bun's server-level error trap. Invoked when an error escapes a route
+   * handler that was NOT already contained by `guardRouteHandler` (e.g. a
+   * built-in factory calling user/config code such as `getIp`). Delegates to
+   * the shared masked-500 responder so Bun's default handler never surfaces
+   * stack/internal detail. See `server-error.ts`.
+   */
+  error?: (error: Error, req: Request) => Response | Promise<Response>
 }
 
 /** Build a Bun.serve config from pre-baked route handlers. */
@@ -369,6 +466,15 @@ export function createIngressServer(options: CreateIngressServerOptions): BakedS
   }
   const { routes: serverRoutes, baseOpts } = buildRouteHandlers(options)
 
+  // Server-level backstop (Bun's `error` option). `buildRouteHandlers` guards
+  // the escape-capable route handlers; this covers everything else — built-in
+  // factories that call user/config code without a try/catch (notably
+  // `resolveIp` → `opts.getIp`) — with the SAME masked 500 + `onError` hook.
+  const onServerError = createServerErrorHandler({
+    onError: options.onError,
+    logger: options.logger,
+  })
+
   const serverOptions: BunServerOptions = {
     hostname: options.hostname ?? '0.0.0.0',
     port: options.port,
@@ -378,6 +484,7 @@ export function createIngressServer(options: CreateIngressServerOptions): BakedS
     // to 16 MiB so an oversized request is rejected at the socket without ever
     // being buffered (route handlers enforce the tighter `maxBodyBytes`).
     maxRequestBodySize: options.maxRequestBodySize ?? DEFAULT_MAX_REQUEST_BODY_SIZE,
+    error: (error, req) => onServerError(error, req),
   }
   if (options.reusePort) {
     serverOptions.reusePort = true

package/src/ingress/shared.ts

@@ -36,7 +36,7 @@ export const DEFAULT_BAKED_OUTPUT_BUFFER_SIZE = 131_072
  * (`handle_request_full_sync` allocates `vec![0u8; output_size]`), OOM-ing the
  * process. Callers that genuinely need more can raise it here.
  */
-export const MAX_OUTPUT_BUFFER_SIZE = 64 * 1024 * 1024
+const MAX_OUTPUT_BUFFER_SIZE = 64 * 1024 * 1024
 
 /**
  * Clamp an ingress output-buffer size into `[min, MAX_OUTPUT_BUFFER_SIZE]` so

package/src/ingress/types.ts

@@ -120,6 +120,21 @@ export interface OptimizedIngressHandler {
     retryAfterSecs?: number,
   ): [string, string][]
 
+  /**
+   * Success-path headers as a ready `Headers` instance: the memoized base
+   * (template + reflected origin) plus per-request rate/request-id extras,
+   * without rebuilding `Headers` from an array on every response. Optional so
+   * hand-rolled mocks need not provide it; callers fall back to
+   * `memoizedHeaders(responseHeaders(...))`.
+   */
+  successHeaders?(
+    variant: number,
+    requestIdHeader: string | null,
+    origin: string | null,
+    rateRemaining?: number,
+    rateResetSecs?: number,
+  ): Headers
+
   terminalHeaders(
     variant: number,
     ctx: BakedContext,

package/src/integration/pipeline.ts

@@ -7,6 +7,7 @@
 // context to the app's own handler. `handleRequest` is a fetch-compatible
 // convenience that serves the terminal response or a rendered OK response.
 
+import { abortResponse, isAbortError } from '../ingress/abort'
 import { readBodyWithLimit } from '../ingress/body'
 import type { BakedIngressResult } from '../ingress/decode/baked-result'
 import {
@@ -172,6 +173,11 @@ export function createPipeline(opts: CreatePipelineOptions = {}): IngressPipelin
       try {
         body = await readBodyWithLimit(req, maxBodyBytes, true, bodyTimeoutMs)
       } catch (err) {
+        // Client disconnect is the cancelled response, never the
+        // `bodyErrorResponse` 400/408/413 fallback.
+        if (isAbortError(err)) {
+          return { terminal: true, response: abortResponse(), result: null, ctx }
+        }
         return {
           terminal: true,
           response: bodyErrorResponse(ingress, req, requestId, err),

package/src/loader/ops.ts

@@ -26,7 +26,7 @@ import { decoder } from '../shared/bytes'
 import type { SchemaValidator } from '../shared/packed'
 
 /** Empty bytes sentinel for skip-on-error scalar parity (e.g. AEAD decrypt). */
-export const EMPTY_BYTES = new Uint8Array(0)
+const EMPTY_BYTES = new Uint8Array(0)
 
 /** Result kinds supported by the loader (mirrors the packed batch wire shapes). */
 export type LoaderResultKind = 'boolean' | 'number' | 'bigint' | 'bytes'