castrum 0.9.0 → 0.9.1

package/src/ingress/packing/gather-raw-headers.ts

@@ -7,10 +7,10 @@
 // guards so oversized values are dropped rather than forwarded.
 
 import type { HeaderPlan } from '../shared'
+import { METHOD_KIND } from '../shared'
 import { writeHeaderPair } from './header-packing'
-import { forEachSelectedHeader } from './select-headers'
-import { getHeaderBuf } from './scratch'
-import { decoder } from '../../shared/bytes'
+import { forEachSelectedHeader, HDR_ORIGIN } from './select-headers'
+import { getHeaderBuf, MAX_SMALL_HEADER_BYTES } from './scratch'
 
 // Shared per-header size guards (single source of truth in scratch.ts).
 // Re-exported for back-compat with imports that referenced them here.
@@ -20,32 +20,29 @@ export {
   MAX_XFF_HEADER_BYTES,
 } from './scratch'
 
-/**
- * Gather the request headers selected by `plan` as a `[name, value][]` array.
- * `methodKind` is the native method-kind enum (see `METHOD_KIND`).
- */
-export function gatherRawHeaders(
-  req: Request,
-  plan: HeaderPlan,
-  methodKind: number,
-): [string, string][] {
-  const headers: [string, string][] = []
-  forEachSelectedHeader(req, plan, methodKind, undefined, (name, value) => {
-    headers.push([decoder.decode(name), value])
-  })
-  return headers
-}
-
 /**
  * Gather the request headers selected by `plan` as a packed byte block
  * (`[u16 count] { [u16 name_len][name][u32 val_len][value] }`) written into a
  * reusable thread-local buffer.
  *
- * This is the zero-intermediate-string equivalent of [`gatherRawHeaders`] for
- * the packed-input pipeline: identical header selection and per-header size
+ * This is the zero-intermediate-string equivalent of the legacy string-array
+ * header gathering (a test-local reference in header-packing.test.ts) for the
+ * packed-input pipeline: identical header selection and per-header size
  * guards, but no `[string, string][]` array and no napi string marshaling.
  * The returned view is valid only until the next call on this call site.
  *
+ * A plan that selects NO headers (no cookie/cors/proxy/proto) short-circuits
+ * to a shared empty block — skipping the scratch-buffer round-robin, the
+ * `setUint16` and the per-call `subarray` entirely (the common minimal-route
+ * case).
+ *
+ * A CORS-ONLY plan on a non-preflight request (the dominant minimal-route
+ * case, e.g. the benchmark server) produces a block that depends ONLY on the
+ * `Origin` header value — which is constant per deployment. Such blocks are
+ * cached keyed by origin, so the per-request UTF-8 encode of the origin (the
+ * largest single JS packing cost) and the scratch write are skipped entirely;
+ * the cache is bounded (FIFO eviction) so multi-origin deployments stay safe.
+ *
  * @param originValue - When provided (non-undefined), the already-fetched
  *   `Origin` header value to pack, avoiding a second `req.headers.get('origin')`
  *   native→JS string conversion per request on the hot path (the caller, e.g.
@@ -59,6 +56,24 @@ export function gatherRawHeadersPacked(
   methodKind: number,
   originValue?: string | null,
 ): Uint8Array {
+  if (!plan.cookie && !plan.cors && !plan.proxy && !plan.proto) {
+    return EMPTY_HEADERS_BLOCK
+  }
+
+  // CORS-only fast path: the only selected header is the (typically constant)
+  // Origin, so the whole packed block is a pure function of the origin string.
+  // Skip the per-request encode + scratch write by returning the cached block.
+  // Preflight (OPTIONS) is excluded — it also packs ACRM/ACRH and must take
+  // the general path. The MAX_SMALL_HEADER_BYTES guard mirrors the general
+  // path (an oversized origin is dropped → empty block, not cached).
+  if (plan.cors && !plan.cookie && !plan.proxy && !plan.proto && methodKind !== METHOD_KIND.OPTIONS) {
+    const origin = originValue !== undefined ? originValue : req.headers.get('origin')
+    if (origin === null || origin.length > MAX_SMALL_HEADER_BYTES) {
+      return EMPTY_HEADERS_BLOCK
+    }
+    return cachedOriginBlock(origin)
+  }
+
   let [buf, view] = getHeaderBuf()
   let pos = 2
   let count = 0
@@ -70,6 +85,55 @@ export function gatherRawHeadersPacked(
 
   forEachSelectedHeader(req, plan, methodKind, originValue, write)
 
+  // No selected header was actually present (e.g. a route with cookie+cors in
+  // its plan but a request that sends neither) — return the shared empty block
+  // instead of touching the scratch buffer again (setUint16 + subarray) on the
+  // hot path.
+  if (count === 0) {
+    return EMPTY_HEADERS_BLOCK
+  }
+
   view.setUint16(0, count, true)
   return buf.subarray(0, pos)
 }
+
+/** Shared `[0, 0]` (zero headers) block — returned when a plan selects nothing.
+ *  Callers treat the result as read-only (the packers copy it verbatim). */
+const EMPTY_HEADERS_BLOCK = new Uint8Array(2)
+
+/**
+ * Cached packed blocks for the CORS-only case, keyed by origin string.
+ * Bounded (FIFO eviction) — a multi-origin deployment never grows it
+ * unboundedly, and a single-origin deployment hits a stable single entry.
+ * Module state is per-thread in Bun workers, so no cross-thread aliasing.
+ */
+const ORIGIN_BLOCK_CACHE = new Map<string, Uint8Array>()
+const ORIGIN_CACHE_MAX = 8
+
+/**
+ * Return (building and caching on first use) the packed header block for a
+ * CORS-only plan whose only selected header is `origin`.
+ *
+ * The block is byte-identical to what the general path would produce
+ * (`[u16 1][u16 name_len]['origin'][u32 val_len][value]`), built once with the
+ * shared `writeHeaderPair` and copied out of the scratch buffer into a stable
+ * allocation — never aliased to the round-robin scratch, so it stays valid
+ * across subsequent gathers.
+ */
+function cachedOriginBlock(origin: string): Uint8Array {
+  const hit = ORIGIN_BLOCK_CACHE.get(origin)
+  if (hit !== undefined) return hit
+
+  let [buf, view] = getHeaderBuf()
+  let pos = 2
+  ;[pos, buf, view] = writeHeaderPair(buf, view, pos, HDR_ORIGIN, origin)
+  view.setUint16(0, 1, true)
+  const block = buf.slice(0, pos)
+
+  if (ORIGIN_BLOCK_CACHE.size >= ORIGIN_CACHE_MAX) {
+    const firstKey = ORIGIN_BLOCK_CACHE.keys().next().value
+    if (firstKey !== undefined) ORIGIN_BLOCK_CACHE.delete(firstKey)
+  }
+  ORIGIN_BLOCK_CACHE.set(origin, block)
+  return block
+}

package/src/ingress/packing/header-packing.ts

@@ -5,12 +5,11 @@
 // scratch buffers keeps this allocation-free on the hot path while isolating
 // the buffers per call-site sequence.
 
-import { METHOD_KIND, METHOD_KIND_UNKNOWN, type HeaderPlan } from '../shared'
+import { encodeUtf8Into } from '../../shared/codec'
+import { type HeaderPlan, METHOD_KIND, METHOD_KIND_UNKNOWN } from '../shared'
 import { getHeaderBuf } from './scratch'
 import { forEachSelectedHeader } from './select-headers'
 
-const encoder = new TextEncoder()
-
 /**
  * Write one header pair into `buf`/`view`, growing them if needed.
  *
@@ -43,8 +42,9 @@ export function writeHeaderPair(
   const valueLenPos = pos
   pos += 4
 
-  const dest = buf.subarray(pos)
-  const { written } = encoder.encodeInto(value, dest)
+  // Number-returning codec write directly at `pos` (no `{read, written}`
+  // object, no intermediate `subarray` — both were per-header allocations).
+  const written = encodeUtf8Into(value, buf, pos)
 
   view.setUint32(valueLenPos, written, true)
   pos += written

package/src/ingress/packing/input-packer.ts

@@ -4,7 +4,8 @@
 // headers) into a single growable Uint8Array in the layout the native
 // `Ingress.handleRequestPacked` expects.
 
-const encoder = new TextEncoder()
+import { encoder } from '../../shared/bytes'
+
 const EMPTY_BYTES = new Uint8Array(0)
 const EMPTY_IP_BYTES = encoder.encode('0.0.0.0')
 
@@ -12,6 +13,10 @@ const EMPTY_IP_BYTES = encoder.encode('0.0.0.0')
 export class IngressInputPacker {
   private buf: Uint8Array
   private view: DataView
+  /** Cached zero-copy `Buffer` view over `buf`'s backing store (invalidated
+   *  when `buf` grows). `Buffer.write` needs a Buffer; caching it here avoids
+   *  a per-string view/`Buffer.from` allocation on the hot pack path. */
+  private bufView: Buffer | null = null
   private pos = 0
 
   constructor(initialSize = 65536) {
@@ -33,6 +38,7 @@ export class IngressInputPacker {
 
     this.buf = next
     this.view = new DataView(next.buffer)
+    this.bufView = null
   }
 
   private writeU8(value: number): void {
@@ -76,8 +82,16 @@ export class IngressInputPacker {
     this.ensure(4 + value.length * 3)
     const valueLenPos = this.pos
     this.pos += 4
-    const dest = this.buf.subarray(this.pos)
-    const { written } = encoder.encodeInto(value, dest)
+    // Reused `Buffer` view over this buffer: `Buffer.write` encodes the string
+    // in place at the current position and returns bytes written — no
+    // `{read, written}` object, no `Buffer.from`/subarray per string (those
+    // were per-request allocations on this hot path).
+    let view = this.bufView
+    if (view === null) {
+      view = Buffer.from(this.buf.buffer, this.buf.byteOffset, this.buf.byteLength)
+      this.bufView = view
+    }
+    const written = view.write(value, this.pos, 'utf8')
     this.view.setUint32(valueLenPos, written, true)
     this.pos += written
   }

package/src/ingress/packing/select-headers.ts

@@ -1,29 +1,35 @@
 // src/ingress/packing/select-headers.ts — Shared header-selection iterator.
 //
 // Single source of truth for "which headers does a HeaderPlan select" across
-// the THREE packing paths:
+// the TWO packing paths (a string-array reference variant lives test-local in
+// header-packing.test.ts):
 //   - `packHeaders`             (fast path, ./header-packing.ts)
 //   - `gatherRawHeadersPacked`  (pre-baked packed path, ./gather-raw-headers.ts)
-//   - `gatherRawHeaders`        (pre-baked string-array reference, ./gather-raw-headers.ts)
 //
-// All three apply the SAME selection rules and the SAME per-header size guards
+// Both apply the SAME selection rules and the SAME per-header size guards
 // (an oversized value is dropped rather than forwarded, so the packed block can
 // never exceed the native `max_headers_bytes` (65536) and 500). This module
 // owns that logic plus the pre-encoded header-name bytes, so a rule or size
 // change cannot drift between the paths.
 
-import { METHOD_KIND, type HeaderPlan } from '../shared'
+import { encoder } from '../../shared/bytes'
+import { type HeaderPlan, METHOD_KIND } from '../shared'
 import { MAX_COOKIE_HEADER_BYTES, MAX_SMALL_HEADER_BYTES, MAX_XFF_HEADER_BYTES } from './scratch'
 
-const encoder = new TextEncoder()
-
 // ── Header name constants (pre-encoded) ────────────────────────
+/** Pre-encoded `cookie` header name. */
 export const HDR_COOKIE = encoder.encode('cookie')
+/** Pre-encoded `origin` header name. */
 export const HDR_ORIGIN = encoder.encode('origin')
+/** Pre-encoded `access-control-request-method` header name. */
 export const HDR_ACRM = encoder.encode('access-control-request-method')
+/** Pre-encoded `access-control-request-headers` header name. */
 export const HDR_ACRH = encoder.encode('access-control-request-headers')
+/** Pre-encoded `x-forwarded-for` header name. */
 export const HDR_XFF = encoder.encode('x-forwarded-for')
+/** Pre-encoded `x-real-ip` header name. */
 export const HDR_XRI = encoder.encode('x-real-ip')
+/** Pre-encoded `x-forwarded-proto` header name. */
 export const HDR_XFP = encoder.encode('x-forwarded-proto')
 
 /**

package/src/ingress/router.ts

@@ -0,0 +1,237 @@
+// src/ingress/router.ts — createIngressRouter: per-route compiled ingress.
+//
+// The "one super solution" over the existing ingress core. Instead of one
+// global `IngressInner` serving every path (with a superset of options), each
+// route in the table carries its OWN `IngressHandlerOptions` and compiles a
+// DEDICATED native `IngressInner` (via `createIngressHandler`) — so the native
+// pipeline prunes to exactly that route's stages (parseCookies, parseQuery,
+// schema, cors, rateLimit, limits...), and `buildHeaderPlan` (inside
+// `createIngressHandler`) produces a per-route header plan that reads ZERO
+// headers for routes that need none. All routes share the same wire format
+// (the existing packed `handle_request_packed`), the shared process-wide rate
+// limiter budgets, and pre-warm on construction (`warmOnCreate`).
+//
+// This is the completion of what `rust/route.rs` (now deleted — it was dead,
+// external-project wire) attempted: per-route native stage pruning, WITHOUT a
+// second/third wire format. The route factories (`readHandler`,
+// `jsonWriteHandler`, ...) and the dispatch machinery (`buildRouteHandlers` /
+// `buildPathMatcher`) are reused unchanged. The per-route native-compile idea
+// is ALSO exposed as the standalone per-route stack in
+// `rust/ingress/native_route.rs` (the `castrum_route_*`/napi `Route` surface
+// consumed by `@ignex/native`'s `createNativeRoute` — the LIVE successor to
+// the deleted dead wire).
+
+import type { BakedIngressResult } from './decode/baked-result'
+import { type BakedIngressRuntime, createIngressHandler } from './handlers'
+import type { IngressHandlerOptions } from './options'
+import type { BakedRoute, PathMatch, RouteHandler } from './server'
+import { buildPathMatcher, buildRouteHandlers } from './server'
+import type { BakedContext, NativeResponder, OptimizedIngressHandler, TerminalStyle } from './types'
+
+/** Per-route spec for {@link createIngressRouter}. */
+export interface RouterRouteSpec {
+  /**
+   * Per-route ingress options — compiled into a DEDICATED native `IngressInner`
+   * for this route (parseCookies, parseQuery, schema, cors, rateLimit, limits,
+   * requireJsonBody, ...). This is what makes the pipeline prune per route.
+   */
+  options?: IngressHandlerOptions
+  /** Wire GET + HEAD read handlers over this route's compiled handler. */
+  read?: boolean
+  /** Wire POST/PUT/PATCH JSON-write handlers over this route's compiled handler. */
+  write?: boolean
+  /** Wire a POST echo handler over this route's compiled handler. */
+  echo?: boolean
+  /** Wire a GET read handler (cookies-style) over this route's compiled handler. */
+  cookies?: boolean
+  /** Wire a DELETE read-style handler over this route's compiled handler. */
+  delete?: boolean
+  /**
+   * A JS responder route: the native pipeline decides + rejects (terminal
+   * response in {@link terminalStyle}); on success the responder builds the
+   * 2xx body (async OK) from a decoded snapshot. Wired for `methods`
+   * (default `['GET']`). When set, the standard `read`/`write`/etc. flags for
+   * this route are ignored.
+   */
+  responder?: {
+    handler: NativeResponder
+    /** HTTP methods to wire (default `['GET']`). */
+    methods?: ReadonlyArray<string>
+    /** Read the body for native validation (default false — framework owns it). */
+    readBody?: boolean
+  }
+  /** Terminal envelope style for this route's responder (default: router-level
+   *  `terminalStyle` or `'castrum'`). */
+  terminalStyle?: TerminalStyle
+  /**
+   * A raw request→Response handler served directly for GET, OUTSIDE the
+   * ingress pipeline (health/metrics probes, /metrics). When set, `read`/
+   * `write`/etc. for this route are ignored.
+   */
+  raw?: RouteHandler
+  /** Overrides `maxBodyBytes` for this route's write/echo handlers. */
+  maxBodyBytes?: number
+  /** Overrides `bodyTimeoutMs` for this route's write/echo handlers. */
+  bodyTimeoutMs?: number
+}
+
+/** Options for {@link createIngressRouter}. */
+export interface CreateIngressRouterOptions {
+  /** Route table: path → per-route spec. */
+  routes: Record<string, RouterRouteSpec>
+  /** Shared runtime hooks (onRequest/onResponse/onError, security headers,
+   *  output buffer size) applied to EVERY compiled route handler. */
+  runtime?: BakedIngressRuntime
+  /** Shared `getIp` resolver for route handlers. */
+  getIp?: (req: Request, srv: unknown) => string | undefined
+  /** Shared `copyBody` default for route handlers. */
+  copyBody?: boolean
+  /** Default terminal envelope style for responder routes (`'castrum'`). */
+  terminalStyle?: TerminalStyle
+  /** Pre-warm every compiled route at construction (JIT the packed pipeline +
+   *  the FFI ingress call before the first real request). Default: false. */
+  warmOnCreate?: boolean
+}
+
+/** A compiled per-route router. */
+export interface IngressRouter {
+  /** The per-route compiled handlers keyed by path (for custom route wiring). */
+  routeHandlers: Record<string, OptimizedIngressHandler>
+  /** The route → method → handler map (compatible with Bun.serve `routes` and
+   *  `createIngressServerNode`). */
+  routes: Record<string, Record<string, unknown>>
+  /** The path matcher (`:param`/`*` dynamic routes). */
+  match: (pathname: string) => PathMatch | undefined
+  /** A fetch-style dispatcher: match path + method → the route's handler. */
+  fetch: (req: Request, srv?: unknown) => Response | Promise<Response>
+  /** Pre-warm every compiled route (JIT the packed pipeline + FFI call). */
+  prewarm: () => void
+}
+
+/**
+ * Compile a route table into per-route native ingress instances.
+ *
+ * Each route with a pipeline-backed spec (`read`/`write`/`echo`/`cookies`/
+ * `delete`) compiles its OWN `createIngressHandler(options)` — a dedicated
+ * `IngressInner` pruned to that route's stages + a per-route header plan.
+ * Routes that need nothing (a bare `read` with no cookies/query/cors) therefore
+ * gather zero headers and run a near-empty native pipeline. All routes share
+ * the same wire format and the shared process-wide rate-limiter budgets.
+ *
+ * @example
+ * ```ts
+ * const router = createIngressRouter({
+ *   warmOnCreate: true,
+ *   runtime: ingressMetrics?.runtime,
+ *   routes: {
+ *     '/health': { read: true, options: { parseCookies: false, parseQuery: false } },
+ *     '/api/users': {
+ *       read: true,
+ *       write: true,
+ *       options: { parseCookies: true, parseQuery: true, schema: USER_SCHEMA_BYTES },
+ *     },
+ *     '/metrics': { raw: metricsHandler(ingressMetrics) },
+ *   },
+ * })
+ * const server = Bun.serve({ routes: router.routes }) // or router.fetch
+ * ```
+ */
+export function createIngressRouter(options: CreateIngressRouterOptions): IngressRouter {
+  const runtime = options.runtime ?? {}
+
+  // Per-route compiled handlers + the BakedRoute table the shared wiring reads.
+  const compiled: Record<string, OptimizedIngressHandler> = {}
+  const bakedRoutes: Record<string, BakedRoute> = {}
+  const baseOpts: {
+    getIp?: (req: Request, srv: unknown) => string | undefined
+    copyBody?: boolean
+  } = {}
+  if (options.getIp !== undefined) baseOpts.getIp = options.getIp
+  if (options.copyBody !== undefined) baseOpts.copyBody = options.copyBody
+
+  for (const [path, spec] of Object.entries(options.routes)) {
+    if (spec.raw) {
+      // Raw handler: served directly, outside the pipeline.
+      bakedRoutes[path] = { read: spec.raw as RouteHandler }
+      continue
+    }
+    // Compile a dedicated native instance for this route's options.
+    const handler = createIngressHandler(spec.options ?? {}, runtime)
+    compiled[path] = handler
+
+    if (spec.responder) {
+      // Responder route: native decides + rejects; JS builds the 2xx.
+      bakedRoutes[path] = {
+        responder: {
+          ingress: handler,
+          handler: spec.responder.handler,
+          methods: spec.responder.methods,
+          terminalStyle: spec.terminalStyle ?? options.terminalStyle,
+          readBody: spec.responder.readBody,
+        },
+        maxBodyBytes: spec.maxBodyBytes,
+        bodyTimeoutMs: spec.bodyTimeoutMs,
+      }
+      continue
+    }
+
+    const routeSpec: BakedRoute = {
+      read: spec.read ? handler : undefined,
+      write: spec.write ? handler : undefined,
+      echo: spec.echo ? handler : undefined,
+      cookies: spec.cookies ? handler : undefined,
+      delete: spec.delete ? handler : undefined,
+      maxBodyBytes: spec.maxBodyBytes,
+      bodyTimeoutMs: spec.bodyTimeoutMs,
+    }
+    bakedRoutes[path] = routeSpec
+  }
+
+  const { routes } = buildRouteHandlers({ ...baseOpts, routes: bakedRoutes })
+  const matcher = buildPathMatcher(routes)
+
+  const prewarm = (): void => {
+    // Run one probe GET through each compiled handler so the packed pipeline,
+    // header plan and FFI ingress call are JIT-warmed before the first real
+    // request. `run` never throws for a bad request (native failures become a
+    // 500 via setInternalError), so this is safe on any handler.
+    for (const handler of Object.values(compiled)) {
+      const probe = new Request('http://localhost:0/prewarm', { method: 'GET' })
+      handler.run<unknown>(
+        probe,
+        '127.0.0.1',
+        null,
+        (_result: BakedIngressResult, _ctx: BakedContext) => 0,
+      )
+    }
+  }
+
+  if (options.warmOnCreate === true) {
+    prewarm()
+  }
+
+  const fetch = (req: Request, srv?: unknown): Response | Promise<Response> => {
+    let pathname: string
+    try {
+      pathname = new URL(req.url).pathname
+    } catch {
+      return new Response('Bad Request', { status: 400 })
+    }
+    const matched = matcher(pathname)
+    if (!matched) {
+      return new Response('Not Found', { status: 404 })
+    }
+    const methodHandler = matched.methods[req.method]
+    if (typeof methodHandler === 'function') {
+      return (methodHandler as RouteHandler)(req, srv, matched.params)
+    }
+    // A route matched but this method isn't wired — 405, or a bare OPTIONS 204
+    // when the route answers preflights.
+    if (req.method === 'OPTIONS' && typeof matched.methods.OPTIONS === 'function') {
+      return (matched.methods.OPTIONS as RouteHandler)(req, srv, matched.params)
+    }
+    return new Response('Method Not Allowed', { status: 405 })
+  }
+
+  return { routeHandlers: compiled, routes, match: matcher, fetch, prewarm }
+}

package/src/ingress/routes/common.ts

@@ -1,6 +1,8 @@
 // src/ingress/routes/common.ts — Shared route-handler options + helpers.
 
-import type { OptimizedIngressHandler } from '../types'
+import type { BakedContext, OptimizedIngressHandler } from '../types'
+import type { BakedIngressResult } from '../decode/baked-result'
+import { secondsFromMs } from '../shared'
 
 /** Options accepted by the pre-baked route factories. */
 export interface BakedHandlerOptions {
@@ -36,3 +38,42 @@ export function resolveIp(
 ): string | undefined {
   return opts.getIp ? opts.getIp(req, srv) : undefined
 }
+
+/**
+ * Build the success `ResponseInit` (status + ratelimit headers) shared by
+ * every pre-baked success path. A plain function call, so the hot path keeps
+ * its single init-object allocation and nothing else.
+ *
+ * @param status Success status; defaults to 200.
+ */
+export function buildSuccessInit(
+  ingress: OptimizedIngressHandler,
+  result: BakedIngressResult,
+  ctx: BakedContext,
+  status = 200,
+): ResponseInit {
+  return {
+    status,
+    headers: ingress.responseHeaders(
+      result.headerVariant,
+      ctx.requestIdHeader,
+      ctx.origin,
+      result.rateRemaining,
+      result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined,
+    ),
+  }
+}
+
+/**
+ * Wrap a `(result, ctx) => Response` responder in the shared sync route
+ * runner: resolve the client IP once and dispatch through the native pipeline
+ * (`ingress.run` with a null body). Used by the read / head / fallback route
+ * factories whose responder never needs the request object.
+ */
+export function runBaked(
+  ingress: OptimizedIngressHandler,
+  opts: BakedHandlerOptions,
+  respond: (result: BakedIngressResult, ctx: BakedContext) => Response,
+): (req: Request, srv?: unknown) => Response {
+  return (req, srv) => ingress.run<Response>(req, resolveIp(req, srv, opts), null, respond)
+}

package/src/ingress/routes/fallback.ts

@@ -2,7 +2,7 @@
 
 import type { BakedContext, OptimizedIngressHandler } from '../types'
 import type { BakedIngressResult } from '../decode/baked-result'
-import { resolveIp, type BakedHandlerOptions } from './common'
+import { runBaked, type BakedHandlerOptions } from './common'
 
 /**
  * Pre-baked fallback handler: 404 for unmatched routes / OPTIONS.
@@ -19,5 +19,5 @@ export function fallbackHandler(
     return ingress.errorResponse(undefined, result, 404, 'not_found', 'Not found', ctx)
   }
 
-  return (req, srv) => ingress.run<Response>(req, resolveIp(req, srv, opts), null, respond)
+  return runBaked(ingress, opts, respond)
 }

package/src/ingress/routes/head.ts

@@ -2,8 +2,7 @@
 
 import type { BakedContext, OptimizedIngressHandler } from '../types'
 import type { BakedIngressResult } from '../decode/baked-result'
-import { resolveIp, type BakedHandlerOptions } from './common'
-import { secondsFromMs } from '../shared'
+import { buildSuccessInit, runBaked, type BakedHandlerOptions } from './common'
 
 /**
  * Pre-baked HEAD read handler: headers only, no body.
@@ -21,17 +20,8 @@ export function headHandler(
       return ingress.internalErrorResponse(ctx, result)
     }
 
-    return new Response(null, {
-      status: 200,
-      headers: ingress.responseHeaders(
-        result.headerVariant,
-        ctx.requestIdHeader,
-        ctx.origin,
-        result.rateRemaining,
-        result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined,
-      ),
-    })
+    return new Response(null, buildSuccessInit(ingress, result, ctx))
   }
 
-  return (req, srv) => ingress.run<Response>(req, resolveIp(req, srv, opts), null, respond)
+  return runBaked(ingress, opts, respond)
 }

package/src/ingress/routes/index.ts

@@ -1,10 +1,11 @@
 // src/ingress/routes/index.ts — Route-handler factory composer.
 
 export * from './common'
-export * from './read'
+export * from './delete'
+export * from './echo'
+export * from './fallback'
 export * from './head'
 export * from './json-write'
-export * from './echo'
-export * from './delete'
 export * from './options'
-export * from './fallback'
+export * from './read'
+export * from './responder'

package/src/ingress/routes/json-write.ts

@@ -2,8 +2,8 @@
 // (POST/PUT/PATCH).
 
 import type { OptimizedIngressHandler } from '../types'
-import { resolveIp, type BakedHandlerOptions } from './common'
-import { DEFAULT_MAX_BODY_BYTES, DEFAULT_BODY_TIMEOUT_MS, secondsFromMs } from '../shared'
+import { buildSuccessInit, resolveIp, type BakedHandlerOptions } from './common'
+import { DEFAULT_MAX_BODY_BYTES, DEFAULT_BODY_TIMEOUT_MS } from '../shared'
 import { readBodyWithLimit } from '../body'
 import { getAddon } from '../../native'
 import { getBunFFI } from '../../native/ffi'
@@ -60,25 +60,10 @@ export function jsonWriteHandler(
       })
     }
 
-    const contentLengthHeader = req.headers.get('content-length')
-    const contentLength = contentLengthHeader === null ? NaN : Number(contentLengthHeader)
-
-    if (Number.isFinite(contentLength) && contentLength > maxBodyBytes) {
-      return fallback.run(req, ip, null, (result, ctx) => {
-        const terminal = fallback.terminalResponse(req, result, ctx)
-        if (terminal) return terminal
-
-        return fallback.errorResponse(
-          req,
-          result,
-          413,
-          'body_too_large',
-          'Request body is too large',
-          ctx,
-        )
-      })
-    }
-
+    // Content-Length / body-size enforcement happens INSIDE readBodyWithLimit
+    // (guard on): the declared length is checked before reading and re-checked
+    // after, so a client lying about Content-Length still gets a 413. Not
+    // re-reading the header here saves a per-POST headers.get on the hot path.
     let bodyBytes: Uint8Array
     try {
       // Stream-read with the limit enforced WHILE reading — a body that
@@ -134,16 +119,7 @@ export function jsonWriteHandler(
         return ingress.errorResponse(req, result, 400, 'invalid_json', 'Invalid JSON body', ctx)
       }
 
-      const init: ResponseInit = {
-        status: 200,
-        headers: ingress.responseHeaders(
-          result.headerVariant,
-          ctx.requestIdHeader,
-          ctx.origin,
-          result.rateRemaining,
-          result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined,
-        ),
-      }
+      const init = buildSuccessInit(ingress, result, ctx)
 
       return copyBody
         ? new Response(result.bodyJson(true), init)