castrum 0.9.8 → 0.9.9

package/src/ingress/routes/safe-record.ts

@@ -0,0 +1,57 @@
+// src/ingress/routes/safe-record.ts — prototype-safe key assignment for
+// request-derived objects.
+//
+// PURE: no addon and no pooled-buffer state. Request keys are attacker
+// controlled, so a key of `__proto__` must not invoke the inherited setter on a
+// plain object. `assignOwn` writes `__proto__` with `Object.defineProperty` (an
+// own enumerable data property) and every other key with plain assignment,
+// which is already safe: `constructor` / `prototype` just become own shadowing
+// properties.
+//
+// Scope: this protects the RECORD itself — it keeps `Object.prototype` (so
+// `hasOwnProperty` / `instanceof Object` still work), gains an own `__proto__`
+// data key, and is never mutated through the setter. It does NOT protect a
+// consumer that blindly merges the record into another object, e.g.
+// `Object.assign({}, rec)`: the own `__proto__` key is still enumerable, so a
+// merge target's inherited setter can fire there. Such consumers must guard
+// their own merge.
+
+/** A request-derived key that would invoke the inherited `__proto__` setter. */
+const PROTO_KEY = '__proto__'
+
+/**
+ * Create an empty plain record (`Object.prototype` is preserved, so
+ * `hasOwnProperty` / `instanceof Object` keep working). Safety comes from
+ * {@link assignOwn}, not from the container.
+ *
+ * @returns A fresh, empty `Record<string, unknown>`.
+ */
+export function safeRecord(): Record<string, unknown> {
+  return {}
+}
+
+/**
+ * Assign a request-derived key as an OWN enumerable data property.
+ *
+ * Only `__proto__` is written with `Object.defineProperty` — a plain
+ * `target[key] = value` would invoke the inherited `__proto__` setter and
+ * mutate the prototype. Every other key (including `constructor` /
+ * `prototype`) uses plain assignment: faster, and it merely shadows on the
+ * object.
+ *
+ * @param target - Record to write into (normally from {@link safeRecord}).
+ * @param key - Request-derived key (may be `__proto__` / `constructor`).
+ * @param value - Request-derived value.
+ */
+export function assignOwn(target: Record<string, unknown>, key: string, value: unknown): void {
+  if (key === PROTO_KEY) {
+    Object.defineProperty(target, key, {
+      value,
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    })
+    return
+  }
+  target[key] = value
+}

package/src/ingress/server-error.ts

@@ -0,0 +1,111 @@
+// src/ingress/server-error.ts — request-handler fault containment.
+//
+// User-supplied route handlers (a raw `spec.read`, a `responder`, a `native`
+// responder) run OUTSIDE the native pipeline. On Bun a sync throw / async
+// rejection would otherwise escape to Bun's default handler (which is not
+// castrum-controlled and may surface stack/internal detail); on Node it hit a
+// local generic-500 construction. This module provides ONE masked-500 responder
+// shared by both runtimes plus a guard that contains sync throws and async
+// rejections. The response body is the pre-encoded internal error body — the
+// thrown message/stack is NEVER placed on the wire (info-leak rule).
+
+import { memoizedHeaders } from './headers/memoized-headers'
+import { ERROR_BODIES } from './response/error-bodies'
+import type { RouteHandler } from './server'
+
+/** Options for {@link createServerErrorHandler}. */
+export interface ServerErrorOptions {
+  /**
+   * Observability hook for an escaped handler error. Receives the real `Error`
+   * (unmasked — server-side only). Never throws: a failing hook is swallowed so
+   * it cannot break the masked response.
+   */
+  onError?: (info: { error: Error; request?: Request }) => void
+  /**
+   * Structured-log sink: one JSON line per escaped error (message only, no
+   * stack, no response leak). Never throws.
+   */
+  logger?: (line: string) => void
+}
+
+/** Coerce an unknown thrown value to an `Error` for the hook/logger. */
+function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value))
+}
+
+const INTERNAL_HEADERS: readonly [string, string][] = [
+  ['content-type', 'application/json; charset=utf-8'],
+]
+
+/**
+ * Build a masked-500 responder. The returned function never throws, always
+ * answers with the pre-encoded internal error body, and runs the optional
+ * `onError`/`logger` hooks in a contained way.
+ *
+ * @param opts - Optional observability hooks.
+ * @returns A `(error, req?) => Response` responder for escaped handler errors.
+ * @example
+ * ```ts
+ * const onServerError = createServerErrorHandler({ onError: console.error })
+ * onServerError(new Error('boom')) // Response(500)
+ * ```
+ */
+export function createServerErrorHandler(
+  opts: ServerErrorOptions,
+): (error: unknown, req?: Request) => Response {
+  const headers = memoizedHeaders(INTERNAL_HEADERS)
+  return (error, req) => {
+    const err = toError(error)
+    if (opts.onError) {
+      try {
+        opts.onError({ error: err, request: req })
+      } catch {
+        // Observability must never break the response.
+      }
+    }
+    if (opts.logger) {
+      try {
+        opts.logger(
+          JSON.stringify({
+            level: 'error',
+            msg: 'unhandled_handler_error',
+            error: err.message,
+          }),
+        )
+      } catch {
+        // Logging must never break the response.
+      }
+    }
+    return new Response(ERROR_BODIES.internal, { status: 500, headers })
+  }
+}
+
+/**
+ * Wrap a route handler so a sync throw or an async rejection is contained and
+ * turned into the shared masked 500. The success path is passed through
+ * unchanged.
+ *
+ * @param handler - The route handler to guard.
+ * @param onServerError - The masked-500 responder (see
+ *   {@link createServerErrorHandler}).
+ * @returns A `RouteHandler` with the same signature and success semantics.
+ */
+export function guardRouteHandler(
+  handler: RouteHandler,
+  onServerError: (error: unknown, req?: Request) => Response,
+): RouteHandler {
+  return (req, srv, params) => {
+    try {
+      const out = handler(req, srv, params)
+      // Duck-type thenables (cross-realm Promises/custom thenables fail
+      // `instanceof Promise`). A `Response` never exposes `then`.
+      const thenable = out as Promise<Response> | null | undefined
+      if (thenable !== null && thenable !== undefined && typeof thenable.then === 'function') {
+        return thenable.catch((e) => onServerError(e, req))
+      }
+      return out
+    } catch (e) {
+      return onServerError(e, req)
+    }
+  }
+}

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}`)
 
@@ -77,6 +90,16 @@ function nodeRequestToWebRequest(req: IncomingMessage): Request {
 
   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) {
@@ -161,6 +184,54 @@ function requestHasBody(req: IncomingMessage): boolean {
   )
 }
 
+/**
+ * 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,
@@ -169,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 {
@@ -201,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)
@@ -218,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
-        }
-      }
     }
   }
 }

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) {
@@ -353,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. */
@@ -368,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,
@@ -377,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/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/native/ffi/build/task.ts

@@ -37,7 +37,8 @@ export function buildTask(
   return {
     taskInit: (n) => Number(init(n)),
     // `args` is copied onto the worker by Rust, so the caller's pooled buffer
-    // may be released as soon as this returns.
+    // may be released as soon as this returns. The return code is `1` accepted,
+    // `2` overloaded (bounded work queue full), `0` invalid args.
     taskSubmit: (op, args, taskId) => Number(submit(op, args, lenOrView(args), taskId)),
     taskSubmitOut: (op, args, taskId, output) =>
       Number(submitOut(op, args, lenOrView(args), taskId, output, lenOrView(output))),

package/src/native/ffi/types.ts

@@ -515,18 +515,23 @@ export interface BunFFI {
   // ── Off-thread task runtime (castrum_task_*) ──────────────────────
   /** Start the shared native task pool; 0 = started, 1 = already running. */
   taskInit(threads: number): number
-  /** Submit a task op with packed `args` under `taskId`; 1 = accepted. */
+  /**
+   * Submit a task op with packed `args` under `taskId`. Returns `1` accepted,
+   * `2` overloaded (bounded queue full), `0` invalid args.
+   */
   taskSubmit(op: number, args: Uint8Array, taskId: number): number
   /**
    * Zero-copy submit: the op writes its result DIRECTLY into `output` on the
    * pool thread. `output` must be a stable, caller-owned buffer that stays
    * alive (and untouched) until the completion is drained — the runtime holds
    * the reference. The completion body is the 8-byte LE written length.
+   * Returns `1` accepted, `2` overloaded, `0` invalid args.
    */
   taskSubmitOut(op: number, args: Uint8Array, taskId: number, output: Uint8Array): number
   /**
    * Zero-copy INPUT: only `hdr` is copied; `data` is read in place by the pool
    * thread, so the caller must keep it alive (and untouched) until completion.
+   * Returns `1` accepted, `2` overloaded, `0` invalid args.
    */
   taskSubmitSlice(op: number, hdr: Uint8Array, data: Uint8Array, taskId: number): number
   /**