castrum 0.9.7 → 0.9.9

package/src/ingress/abort.ts

@@ -0,0 +1,48 @@
+// src/ingress/abort.ts — PURE request-cancellation helpers.
+//
+// The async ingress reads `Request.signal` (fired when the client disconnects)
+// at its genuine async boundaries. A body read or a route wrapper that observes
+// an abort returns the cancelled-client response instead of running more work.
+// PURE: no addon / pool imports — safe for the route factories.
+
+/**
+ * The `err.code` value a body read carries when it is rejected because the
+ * client disconnected (`Request.signal` aborted).
+ */
+export const ABORT_CODE = 'REQUEST_ABORTED'
+
+/**
+ * Whether a thrown value is the cancellation error produced when `req.signal`
+ * aborts during a body read (see `readBodyWithLimit` in `./body`).
+ *
+ * @param err - The caught value.
+ * @returns `true` when `err.code === 'REQUEST_ABORTED'`.
+ * @example
+ * ```ts
+ * try {
+ *   await readBodyWithLimit(req, 1 << 20, true)
+ * } catch (err) {
+ *   if (isAbortError(err)) return abortResponse()
+ *   throw err
+ * }
+ * ```
+ */
+export function isAbortError(err: unknown): boolean {
+  return (err as { code?: unknown } | null | undefined)?.code === ABORT_CODE
+}
+
+/**
+ * Build the cancelled-client response: status **499** ("Client Closed
+ * Request", a de-facto nginx status) with no body. This is the only new
+ * outcome added by cancellation — it never replaces an existing success or
+ * error status.
+ *
+ * @returns A bodyless `Response` with status 499.
+ * @example
+ * ```ts
+ * if (req.signal?.aborted) return abortResponse()
+ * ```
+ */
+export function abortResponse(): Response {
+  return new Response(null, { status: 499 })
+}

package/src/ingress/body.ts

@@ -2,6 +2,7 @@
 // API.
 
 import { isBun } from '../shared/runtime'
+import { ABORT_CODE } from './abort'
 
 const EMPTY_BODY = new Uint8Array(0)
 
@@ -65,6 +66,59 @@ function bodyTooLargeError(): Error & { code?: string } {
   return err
 }
 
+function abortError(): Error & { code?: string } {
+  const err = new Error(ABORT_CODE) as Error & { code?: string }
+  err.code = ABORT_CODE
+  return err
+}
+
+/** Reject when `signal` is already aborted (the entry guard for every path). */
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw abortError()
+}
+
+/** A reusable rejection promise + listener-cleanup pair for a read race. */
+interface ReadGuard {
+  promise: Promise<never>
+  cancel: () => void
+}
+
+/**
+ * Track `req.signal` as a rejection racer: settles with a `REQUEST_ABORTED`
+ * error when the client disconnects. Returns `null` when the request carries no
+ * signal, so runtimes without `Request.signal` are unaffected. The
+ * `{ once: true }` listener self-removes when it fires; `cancel()` detaches it
+ * on the read-completed-first path so no listener outlives the read.
+ */
+function createAbortGuard(signal: AbortSignal | undefined): ReadGuard | null {
+  if (!signal) return null
+  if (signal.aborted) {
+    return { promise: Promise.reject(abortError()), cancel: () => {} }
+  }
+  let listener: (() => void) | null = null
+  const promise = new Promise<never>((_resolve, reject) => {
+    listener = () => reject(abortError())
+    signal.addEventListener('abort', listener, { once: true })
+  })
+  return {
+    promise,
+    cancel: () => {
+      if (listener !== null) {
+        signal.removeEventListener('abort', listener)
+        listener = null
+      }
+    },
+  }
+}
+
+/** Race a read against guard rejections (a plain await when there are none). */
+function raceRead<T>(read: Promise<T>, guards: ReadonlyArray<ReadGuard>): Promise<T> {
+  if (guards.length === 0) return read
+  const racers: Promise<unknown>[] = [read]
+  for (const guard of guards) racers.push(guard.promise)
+  return Promise.race(racers) as Promise<T>
+}
+
 // ── Shared body-read deadline watchdog ──────────────────────────────────────
 // One interval timer sweeps ALL in-flight body reads that carry a deadline,
 // replacing a per-request `setTimeout` + `clearTimeout` + `timer.unref` on
@@ -145,6 +199,9 @@ function createDeadline(deadlineMs: number): { promise: Promise<never>; cancel:
  *   (thrown as soon as the limit is crossed — the body is never fully
  *   buffered first, which is the slowloris/large-body protection).
  * - `REQUEST_TIMEOUT` when `timeoutMs` elapses before the body completes.
+ * - `REQUEST_ABORTED` when `req.signal` aborts (client disconnect) before the
+ *   read settles — including an already-aborted signal at entry. The race's
+ *   abort listener is removed once the read settles.
  */
 export async function readBodyWithLimit(
   req: Request,
@@ -152,6 +209,10 @@ export async function readBodyWithLimit(
   guard: boolean,
   timeoutMs?: number,
 ): Promise<Uint8Array> {
+  // Client disconnect before any read work: reject immediately (also covers an
+  // already-aborted signal on every downstream path).
+  throwIfAborted(req.signal)
+
   const deadline = timeoutMs && timeoutMs > 0 ? timeoutMs : 0
 
   // Fast path: a declared Content-Length lets us PROVE the body fits the
@@ -173,11 +234,34 @@ export async function readBodyWithLimit(
       // path — `req.bytes()` (Bun) / `arrayBuffer()` (Node) read the buffered
       // body directly, avoiding a lazily-constructed stream per write request.
       if (deadline <= 0) {
-        const bytes = await readBodyBytes(req)
-        if (guard && bytes.byteLength > maxBytes) {
-          throw bodyTooLargeError()
+        // No deadline: use the same buffered fast path as the deadline branch.
+        // Under Bun a small declared-length body is usually already buffered —
+        // `Bun.peek` returns the bytes synchronously, so the common case skips
+        // the abort race + microtask entirely. Only a genuinely pending read
+        // (slow/trickling body) or a runtime without `req.bytes()` (Node) pays
+        // the abort race.
+        const buffered = peekBufferedBody(req)
+        if (buffered !== false && 'bytes' in buffered) {
+          throwIfAborted(req.signal)
+          if (guard && buffered.bytes.byteLength > maxBytes) {
+            throw bodyTooLargeError()
+          }
+          return buffered.bytes
+        }
+        const abort = createAbortGuard(req.signal)
+        try {
+          const bytes = await raceRead(
+            buffered === false ? readBodyBytes(req) : buffered,
+            abort !== null ? [abort] : [],
+          )
+          throwIfAborted(req.signal)
+          if (guard && bytes.byteLength > maxBytes) {
+            throw bodyTooLargeError()
+          }
+          return bytes
+        } finally {
+          abort?.cancel()
         }
-        return bytes
       }
       // Deadline path. Under Bun, a small declared-length body is usually
       // already buffered — `Bun.peek` returns the bytes synchronously, so we
@@ -187,31 +271,38 @@ export async function readBodyWithLimit(
       const buffered = peekBufferedBody(req)
       if (buffered === false) {
         const dl = createDeadline(deadline)
+        const abort = createAbortGuard(req.signal)
         try {
-          const bytes = await Promise.race([readBodyBytes(req), dl.promise])
+          const bytes = await raceRead(readBodyBytes(req), abort !== null ? [dl, abort] : [dl])
+          throwIfAborted(req.signal)
           if (guard && bytes.byteLength > maxBytes) {
             throw bodyTooLargeError()
           }
           return bytes
         } finally {
           dl.cancel()
+          abort?.cancel()
         }
       }
       if ('bytes' in buffered) {
+        throwIfAborted(req.signal)
         if (guard && buffered.bytes.byteLength > maxBytes) {
           throw bodyTooLargeError()
         }
         return buffered.bytes
       }
       const dl = createDeadline(deadline)
+      const abort = createAbortGuard(req.signal)
       try {
-        const bytes = await Promise.race([buffered, dl.promise])
+        const bytes = await raceRead(buffered, abort !== null ? [dl, abort] : [dl])
+        throwIfAborted(req.signal)
         if (guard && bytes.byteLength > maxBytes) {
           throw bodyTooLargeError()
         }
         return bytes
       } finally {
         dl.cancel()
+        abort?.cancel()
       }
     }
   }
@@ -220,6 +311,7 @@ export async function readBodyWithLimit(
   // is only touched here — the declared-length fast path never needs it.
   const body = req.body
   if (!body) {
+    throwIfAborted(req.signal)
     return EMPTY_BODY
   }
 
@@ -231,11 +323,14 @@ export async function readBodyWithLimit(
   // per request. It is still required when the loop exits early (timeout/error).
   let completed = false
   const dl = deadline > 0 ? createDeadline(deadline) : null
+  const abort = createAbortGuard(req.signal)
+  const guards: ReadGuard[] = []
+  if (dl !== null) guards.push(dl)
+  if (abort !== null) guards.push(abort)
 
   try {
     for (;;) {
-      const { done, value } =
-        dl !== null ? await Promise.race([reader.read(), dl.promise]) : await reader.read()
+      const { done, value } = await raceRead(reader.read(), guards)
 
       if (done) {
         completed = true
@@ -253,6 +348,7 @@ export async function readBodyWithLimit(
     }
   } finally {
     dl?.cancel()
+    abort?.cancel()
     // Release the underlying stream. Cancelling while a read() is still
     // pending (the timeout case) can resolve that pending read() as `done`
     // and RACE the timeout rejection — so reject first, cancel only AFTER

package/src/ingress/decode/baked-result.ts

@@ -36,12 +36,12 @@ import { IngressResultBase } from './result-base'
 
 /** Zero-alloc, reusable result decoder for the pre-baked handler path. */
 export class BakedIngressResult extends IngressResultBase {
-  refresh(buf: Uint8Array, body: Uint8Array, view: DataView): void {
+  refresh(buf: Uint8Array, body: Uint8Array, view: DataView, len: number = buf.byteLength): void {
     // Defensive: the native core always writes the full fixed header
     // (>= OUT_DATA_START bytes) before returning `written`. The cached
     // whole-buffer DataView (see viewForArrayBuffer) would otherwise decode
     // stale bytes if this contract is ever violated — treat as internal error.
-    if (buf.byteLength < OUT_DATA_START) {
+    if (len < OUT_DATA_START) {
       this.setInternalError()
       return
     }
@@ -59,7 +59,7 @@ export class BakedIngressResult extends IngressResultBase {
 
     // Bounds-checked section offsets shared with the fast decoder: a
     // malformed/truncated buffer can never produce slices past its end.
-    const layout = sectionLayout(buf.byteLength, cookiesLenRaw, queryLenRaw, bodyJsonLenRaw)
+    const layout = sectionLayout(len, cookiesLenRaw, queryLenRaw, bodyJsonLenRaw)
 
     if (h0 === 0 && h1 === 0) {
       this.verdict = 1
@@ -85,7 +85,7 @@ export class BakedIngressResult extends IngressResultBase {
 
     // The baked path trusts the already-clamped section lengths, so pass the
     // safe body len here (the fast path re-checks bounds on read instead).
-    this.setSections(buf, layout, layout.safeBodyJsonLen)
+    this.setSections(buf, layout, layout.safeBodyJsonLen, len)
 
     this.updateOkTerminal()
 
@@ -115,7 +115,15 @@ export class BakedIngressResult extends IngressResultBase {
   }
 
   bodyJson(copy: boolean): Uint8Array {
+    if (copy) {
+      // Copy directly out of the buffer — `buffer.slice(begin, end)` avoids the
+      // intermediate `subarray()` view that `bodyJsonSlice().slice()` created.
+      if (this._bodyJsonLen === 0) return this._buf.slice(0, 0)
+      const end = this._bodyJsonStart + this._bodyJsonLen
+      if (end > this._len) return this._buf.slice(0, 0)
+      return this._buf.slice(this._bodyJsonStart, end)
+    }
     const slice = this.bodyJsonSlice()
-    return (copy ? slice.slice() : slice) as Uint8Array
+    return slice as Uint8Array
   }
 }

package/src/ingress/decode/fast-result.ts

@@ -127,7 +127,7 @@ export class FastIngressResult extends IngressResultBase {
     // Store slices for lazy decode instead of eagerly decoding strings. The
     // fast path trusts the RAW declared body length and re-checks bounds on
     // read (bodyJson()), so pass the raw declared length here.
-    this.setSections(buf, layout, bodyJsonLen)
+    this.setSections(buf, layout, bodyJsonLen, buf.byteLength)
 
     // Parity with the baked decoder: any declared section (cookies, query,
     // OR body) that overran the buffer counts as truncated.

package/src/ingress/decode/result-base.ts

@@ -62,6 +62,13 @@ export abstract class IngressResultBase {
   body: Uint8Array = EMPTY_BODY
 
   protected _buf: Uint8Array = EMPTY_BODY
+  /**
+   * Valid byte length of `_buf` (the native `written` count). `_buf` may be the
+   * WHOLE pooled output buffer (`outputBufferSize` bytes), so bounds checks must
+   * use this, not `_buf.byteLength` — that lets `run()` skip a per-request
+   * `buffer.subarray(0, written)` view.
+   */
+  protected _len = 0
   protected _bodyJsonStart = OUT_DATA_START
   protected _bodyJsonLen = 0
   private _cookiesBuf: Uint8Array | null = null
@@ -89,6 +96,7 @@ export abstract class IngressResultBase {
     this.bodyTruncated = false
     this.body = EMPTY_BODY
     this._buf = EMPTY_BODY
+    this._len = 0
     this._bodyJsonStart = OUT_DATA_START
     this._bodyJsonLen = 0
     this._cookiesBuf = null
@@ -134,8 +142,14 @@ export abstract class IngressResultBase {
    * baked path passes the already-clamped `layout.safeBodyJsonLen`. Sections
    * are stored as slices and decoded lazily by `cookiesJson()`/`queryJson()`.
    */
-  protected setSections(buf: Uint8Array, layout: PackedSectionLayout, bodyJsonLen: number): void {
+  protected setSections(
+    buf: Uint8Array,
+    layout: PackedSectionLayout,
+    bodyJsonLen: number,
+    len: number = buf.byteLength,
+  ): void {
     this._buf = buf
+    this._len = len
     this._bodyJsonStart = layout.bodyJsonStart
     this._bodyJsonLen = bodyJsonLen
     this._cookiesBuf =
@@ -174,7 +188,7 @@ export abstract class IngressResultBase {
   protected bodyJsonSlice(): Uint8Array {
     if (this._bodyJsonLen === 0) return EMPTY_BODY
     const end = this._bodyJsonStart + this._bodyJsonLen
-    if (end > this._buf.byteLength) return EMPTY_BODY
+    if (end > this._len) return EMPTY_BODY
     return this._buf.subarray(this._bodyJsonStart, end)
   }
 }

package/src/ingress/handlers.ts

@@ -44,7 +44,7 @@ import { BufferPool, type PooledBuffer } from '../shared/buffer-pool'
 import { decoder, viewForArrayBuffer } from '../shared/bytes'
 import { createStructuredLogger } from '../shared/log'
 import { generateRequestId } from '../shared/request-id'
-import { OUT_DATA_START } from './constants'
+import { OUT_DATA_START, HV_CORS_SIMPLE, HV_JSON, HV_RATE_ACTIVE } from './constants'
 import { BakedIngressResult } from './decode/baked-result'
 import { buildBakedHeaderTemplates } from './headers/baked-templates'
 import { buildBakedSecurityEntries } from './headers/security'
@@ -54,9 +54,13 @@ import {
   type IngressHandlerOptions,
   warnTrustProxyDeprecated,
 } from './options'
-import { gatherRawHeadersPacked } from './packing/gather-raw-headers'
+import { gatherRawHeadersPacked, prewarmOriginBlocks } from './packing/gather-raw-headers'
 import { IngressInputPacker } from './packing/input-packer'
-import { type BakedResponseState, buildBakedResponseBuilders } from './response/baked-response'
+import {
+  type BakedResponseState,
+  buildBakedResponseBuilders,
+  prewarmOriginHeaders,
+} from './response/baked-response'
 import {
   assertSyncCallback,
   buildHeaderPlan,
@@ -90,6 +94,7 @@ export type {
   CreateIngressServerOptions,
   GracefulShutdownOptions,
   ServerHandle,
+  StaticRoute,
 } from './server'
 export { createIngressServer, gracefulShutdown } from './server'
 export type { RouteHandler as IngressNodeRouteHandler } from './server-node'
@@ -110,6 +115,22 @@ export const RATE_LIMIT_U32_MAX = 4_294_967_295
  */
 const MAX_FFI_FAILURES = 3
 
+/**
+ * Number of output buffers pre-allocated into the handler's pool at
+ * construction (`prefill`), so the first burst wave never pays per-request
+ * `new Uint8Array` + GC. Memory trade: `outputBufferSize` × this many bytes
+ * retained per handler (bounded by the pool's `maxBuffers` cap).
+ */
+const PREWARM_POOL_BUFFERS = 16
+
+/**
+ * Byte budget for the pool prefill. `createIngressRouter` builds one handler
+ * (and therefore one pool) per route, so an unbounded `prefill × outputBufferSize`
+ * could reach ~1 GiB per route at the 64 MiB output clamp. This caps the
+ * per-handler up-front allocation at 4 MiB regardless of buffer size.
+ */
+const PREWARM_POOL_BYTES = 4 * 1024 * 1024
+
 /**
  * Best-effort URL pathname extraction for log/error lines.
  *
@@ -285,12 +306,24 @@ export function createIngressHandler(
     logger
   )
 
+  // Hoisted observer-presence flags: the hot path skips the response-status
+  // computation (an `instanceof` + `safeTerminalStatus`) and the per-request
+  // hook call entirely when nothing observes the outcome.
+  const hasOnRequest = runtime.onRequest !== undefined
+  const hasOnResponse = runtime.onResponse !== undefined
+
   // Reusable output-buffer pool: eliminates the per-request output-buffer
   // allocation by reusing buffers across requests.
   // `maxInFlight` (when set) bounds zero-copy borrowing under slow consumers.
+  // `prefill` spends up-front memory (`outputBufferSize` × 16 per handler) so
+  // a burst ramp never allocates during its first wave — the packaged
+  // load-test flow, where the pool would otherwise go 1 buffered → allocate
+  // under a 2000-connection flood.
   const outputPool = new BufferPool({
     initialSize: outputBufferSize,
     maxInFlight: runtime.maxInFlight,
+    prefill: PREWARM_POOL_BUFFERS,
+    prefillBytes: PREWARM_POOL_BYTES,
   })
 
   // Reusable packed-input builder (same zero-alloc discipline as the fast
@@ -313,16 +346,24 @@ export function createIngressHandler(
   // flaky FFI path degrades to a correct response instead of a failure storm.
   let ffiFailures = 0
   let ffiDisabled = false
+  // Cold path only (called from a `catch`): counts a recurrence and trips the
+  // circuit breaker. Defined once at construction, so it adds nothing per call.
+  const noteFfiFailure = (): void => {
+    ffiFailures++
+    if (ffiFailures >= MAX_FFI_FAILURES) {
+      ffiDisabled = true
+    }
+  }
 
   // Cache Origin-augmented header arrays keyed by `variant\u0000origin` (the
   // steady-state CORS case: the pre-baked template + one
   // `access-control-allow-origin` row). Callers treat the returned array as
   // read-only (the `Headers`/`Response` constructors copy entries), so every
   // distinct (variant, origin) is reused after its first hit — removing the
-  // per-request array alloc + copy when an Origin header is present. Only
-  // ALLOWED origins reach the CORS-allowed path (the native pipeline gates the
-  // variant on CORS approval), so the map stays bounded by the configured
-  // allow-origin list (+ a couple of preflight variants).
+  // per-request array alloc + copy when an Origin header is present. The map is
+  // bounded by `ORIGIN_HEADER_CACHE_MAX` in baked-response.ts: with wildcard
+  // CORS the Origin is attacker-controlled, so an unbounded map would be a
+  // remote memory-exhaustion vector.
   const originHeaderCache = new Map<string, [string, string][]>()
 
   // ── Variant-indexed header templates (precomputed once) ──
@@ -379,6 +420,34 @@ export function createIngressHandler(
     state: responseState,
   })
 
+  // Pre-warm the CORS caches for the configured exact allow-origins
+  // (load-time-for-RPS trade): the FIRST request from each known origin then
+  // hits the baked origin-packed header block AND the cached
+  // origin-augmented header array + memoized `Headers` instead of building
+  // them. Wildcard/pattern entries (e.g. `https://*.example.com`) are skipped
+  // — the concrete resolved origin differs from the pattern string, so
+  // caching the pattern would only waste a slot.
+  if (headerPlan.cors && typeof cors?.allowOrigin === 'object') {
+    const exactOrigins: string[] = []
+    for (const origin of cors.allowOrigin) {
+      if (
+        typeof origin === 'string' &&
+        origin.length > 0 &&
+        origin.length <= 512 &&
+        !origin.includes('*')
+      ) {
+        exactOrigins.push(origin)
+      }
+    }
+    prewarmOriginBlocks(exactOrigins)
+    // Warm the SUCCESS variant the native pipeline actually returns for an
+    // allowed CORS JSON response (HV_JSON | HV_CORS_SIMPLE, plus HV_RATE_ACTIVE
+    // when rate limiting is on) — not HV_CORS_SIMPLE alone, which is a
+    // different cache key and left the warmed entry unreachable.
+    const successVariant = HV_JSON | HV_CORS_SIMPLE | (rateEnabled ? HV_RATE_ACTIVE : 0)
+    prewarmOriginHeaders(responseBuilders.responseHeaders, exactOrigins, successVariant)
+  }
+
   const result = new BakedIngressResult()
   const ctx: BakedContext = {
     requestIdHeader: null,
@@ -399,7 +468,7 @@ export function createIngressHandler(
     ctx.requestIdHeader = emitRequestIdHeader ? requestIdStr : null
     ctx.origin = headerPlan.cors ? req.headers.get('origin') : null
 
-    runtime.onRequest?.(req, requestIdStr, ip)
+    if (hasOnRequest) runtime.onRequest?.(req, requestIdStr, ip)
 
     const ipStr = ip ?? EMPTY_IP
 
@@ -463,10 +532,7 @@ export function createIngressHandler(
             )
             ffiFailures = 0
           } catch {
-            ffiFailures++
-            if (ffiFailures >= MAX_FFI_FAILURES) {
-              ffiDisabled = true
-            }
+            noteFfiFailure()
             // napi re-run: crash-safe (napi-rs catch_unwind) and semantically
             // identical — a transient ffi panic still serves the request. The
             // packed frame respects the same url/ip minimal-processing.
@@ -485,10 +551,7 @@ export function createIngressHandler(
             written = bunFFI.ingressHandlePacked(ingressPtr, input, body, handle.buffer)
             ffiFailures = 0
           } catch {
-            ffiFailures++
-            if (ffiFailures >= MAX_FFI_FAILURES) {
-              ffiDisabled = true
-            }
+            noteFfiFailure()
             // napi re-run: crash-safe (napi-rs catch_unwind) and semantically
             // identical — a transient ffi panic still serves the request.
             written = handler.handleRequestPacked(input, body, handle.buffer)
@@ -498,9 +561,16 @@ export function createIngressHandler(
           written = handler.handleRequestPacked(input, body, handle.buffer)
         }
 
-        const used = handle.buffer.subarray(0, written)
-        // Cached per-ArrayBuffer DataView: no per-request view allocation.
-        result.refresh(used, body ?? EMPTY_BODY, viewForArrayBuffer(used.buffer, used.byteOffset))
+        // Pass the WHOLE pooled buffer + the written length instead of a
+        // per-request `buffer.subarray(0, written)` view (a ~35ns allocation in
+        // Bun); the decoder bounds-checks against the length. Same DataView
+        // (cached per-ArrayBuffer, offset unchanged).
+        result.refresh(
+          handle.buffer,
+          body ?? EMPTY_BODY,
+          viewForArrayBuffer(handle.buffer.buffer, handle.buffer.byteOffset),
+          written,
+        )
       } catch (err) {
         result.setInternalError()
         const error = err instanceof Error ? err : new Error(String(err))
@@ -522,18 +592,21 @@ export function createIngressHandler(
         assertSyncCallback(out, 'createIngressHandler().run()')
         // Report observability for every outcome. Non-Response callbacks
         // (e.g. echoHandler's object return) fall back to the decoded terminal
-        // status so they are not silently invisible to onResponse/logging.
-        const status = out instanceof Response ? out.status : safeTerminalStatus(result)
-        runtime.onResponse?.(req, result, status, requestIdStr)
-        if (logger) {
-          logger.request({
-            requestId: requestIdStr,
-            method: req.method,
-            path: pathForLog(req),
-            status,
-            durationMs: Math.round((performance.now() - startedAt) * 1000) / 1000,
-            ip: ipStr,
-          })
+        // status so they are not silently invisible to onResponse/logging. The
+        // status is computed ONLY when something observes it.
+        if (hasOnResponse || logger !== null) {
+          const status = out instanceof Response ? out.status : safeTerminalStatus(result)
+          if (hasOnResponse) runtime.onResponse?.(req, result, status, requestIdStr)
+          if (logger !== null) {
+            logger.request({
+              requestId: requestIdStr,
+              method: req.method,
+              path: pathForLog(req),
+              status,
+              durationMs: Math.round((performance.now() - startedAt) * 1000) / 1000,
+              ip: ipStr,
+            })
+          }
         }
         return out
       } finally {

package/src/ingress/headers/memoized-headers.ts

@@ -0,0 +1,40 @@
+// src/ingress/headers/memoized-headers.ts — memoized `Headers` for baked header arrays.
+//
+// `new Response(body, { headers })` copies its headers either way, but Bun
+// re-parses an array-of-pairs on every construction whereas a persistent
+// `Headers` instance is copied directly — measured ~1.4 µs cheaper per response
+// with the full security + CORS set (398 ns vs 1832 ns), the single largest
+// per-request JS cost on the success path.
+//
+// The arrays the ingress builds are themselves cached (the pre-baked templates
+// and the per-origin cache return the SAME array instance across requests), so
+// this memo hits on the steady state. Fresh per-request arrays (rate-limit /
+// request-id extras) are simply never retained — a `WeakMap` lets them be
+// collected, so the cache cannot grow without bound.
+//
+// The returned `Headers` is treated as IMMUTABLE: it is only ever handed to a
+// `Response` constructor, which copies it. Verified: mutating the source array
+// after construction, or one served response's headers, never leaks into
+// another response.
+
+/** Memoized `Headers` keyed by the identity of the baked header array. */
+const CACHE = new WeakMap<readonly [string, string][], Headers>()
+
+/**
+ * Return a memoized `Headers` for a baked header array.
+ *
+ * @param entries Header pairs from a handler header builder (baked template,
+ *   per-origin cache, or a fresh extras array).
+ * @returns A `Headers` instance safe to pass to a `Response` constructor.
+ * @example
+ * ```ts
+ * new Response(body, { status: 200, headers: memoizedHeaders(pairs) })
+ * ```
+ */
+export function memoizedHeaders(entries: readonly [string, string][]): Headers {
+  const existing = CACHE.get(entries)
+  if (existing !== undefined) return existing
+  const built = new Headers(entries as [string, string][])
+  CACHE.set(entries, built)
+  return built
+}

package/src/ingress/health.ts

@@ -11,6 +11,11 @@
 //     "/livez":   { read: healthHandler() },
 //   }});
 //
+// For probes that are truly constant, prefer static promotion — it skips the
+// JS ingress pipeline entirely:
+//
+//   createIngressServer({ routes: { "/livez": { static: staticLiveness() } } });
+//
 // The liveness probe NEVER touches dependencies (process alive? -> 200).
 // The readiness probe runs the optional `check` (deps up? -> 200/503).
 // The health probe is an alias of liveness (process up) plus optional check.
@@ -36,6 +41,23 @@ export function livenessHandler() {
   return (_req: Request): Response => jsonResponse(200, { status: 'ok' })
 }
 
+/**
+ * Liveness probe as a PREBUILT `Response`, for static route promotion.
+ *
+ * Wire it as `{ static: staticLiveness() }` so `Bun.serve` snapshots the
+ * constant body into its native route table and serves `/livez` without
+ * entering the JavaScript ingress pipeline at all (see `BakedRoute.static` in
+ * src/ingress/server.ts). On the node:http adapter the bare `Response` is
+ * re-materialized per request from cached body bytes, so the one-shot body is
+ * never replayed. Unlike {@link readinessHandler}, it never runs a dependency
+ * check.
+ *
+ * @returns A fresh 200 `{"status":"ok"}` `Response`.
+ */
+export function staticLiveness(): Response {
+  return jsonResponse(200, { status: 'ok' })
+}
+
 /**
  * Readiness probe: runs the optional async `check` (dependency readiness).
  * Returns `200 {"status":"ready"}` when the check passes (or no check is