castrum 0.7.0 → 0.9.1

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

@@ -0,0 +1,164 @@
+// src/ingress/packing/input-packer.ts — Binary-packed ingress input builder.
+//
+// Packs the per-request inputs (method kind + url + ip + request id + packed
+// headers) into a single growable Uint8Array in the layout the native
+// `Ingress.handleRequestPacked` expects.
+
+import { encoder } from '../../shared/bytes'
+
+const EMPTY_BYTES = new Uint8Array(0)
+const EMPTY_IP_BYTES = encoder.encode('0.0.0.0')
+
+/** Growable packer for the fast-path packed input buffer. */
+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) {
+    this.buf = new Uint8Array(Math.max(1024, initialSize))
+    this.view = new DataView(this.buf.buffer)
+  }
+
+  private ensure(additional: number): void {
+    const needed = this.pos + additional
+    if (needed <= this.buf.byteLength) return
+
+    let nextSize = this.buf.byteLength * 2
+    while (nextSize < needed) {
+      nextSize *= 2
+    }
+
+    const next = new Uint8Array(nextSize)
+    next.set(this.buf.subarray(0, this.pos))
+
+    this.buf = next
+    this.view = new DataView(next.buffer)
+    this.bufView = null
+  }
+
+  private writeU8(value: number): void {
+    this.ensure(1)
+    this.buf[this.pos++] = value & 0xff
+  }
+
+  private writeLenPrefixed(bytes: Uint8Array): void {
+    this.ensure(4 + bytes.byteLength)
+
+    this.view.setUint32(this.pos, bytes.byteLength, true)
+    this.pos += 4
+
+    this.buf.set(bytes, this.pos)
+    this.pos += bytes.byteLength
+  }
+
+  /** Pack the request inputs; the returned view is valid until the next pack. */
+  pack(
+    methodKind: number,
+    urlBytes: Uint8Array,
+    ipBytes: Uint8Array,
+    requestIdBytes: Uint8Array,
+    headers: Uint8Array,
+  ): Uint8Array {
+    this.pos = 0
+
+    this.writeU8(methodKind)
+    this.writeLenPrefixed(urlBytes)
+    this.writeLenPrefixed(ipBytes)
+    this.writeLenPrefixed(requestIdBytes)
+    this.writeLenPrefixed(headers)
+
+    return this.buf.subarray(0, this.pos)
+  }
+
+  /** Encode `value` directly into the buffer, length-prefixed (zero-copy). */
+  private writeStringLenPrefixed(value: string): void {
+    // 3 bytes per UTF-16 code unit is a safe upper bound (BMP non-ASCII);
+    // surrogate pairs encode to fewer bytes per code unit.
+    this.ensure(4 + value.length * 3)
+    const valueLenPos = this.pos
+    this.pos += 4
+    // 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
+  }
+
+  /**
+   * Pack the request inputs from raw strings, encoding url/ip/requestId
+   * directly into the internal buffer via `encodeInto` — three fewer
+   * intermediate `Uint8Array` allocations + copies per request vs [`pack`].
+   * The returned view is valid until the next pack.
+   */
+  packFromStrings(
+    methodKind: number,
+    url: string,
+    ip: string | undefined,
+    requestId: string | undefined,
+    headers: Uint8Array,
+  ): Uint8Array {
+    this.pos = 0
+
+    this.writeU8(methodKind)
+    this.writeStringLenPrefixed(url)
+    if (ip && ip.length > 0) {
+      this.writeStringLenPrefixed(ip)
+    } else {
+      this.writeLenPrefixed(EMPTY_IP_BYTES)
+    }
+    if (requestId) {
+      this.writeStringLenPrefixed(requestId)
+    } else {
+      this.writeLenPrefixed(EMPTY_BYTES)
+    }
+    this.writeLenPrefixed(headers)
+
+    return this.buf.subarray(0, this.pos)
+  }
+
+  /**
+   * Pack the request inputs with a mixed strategy: `url`/`ip` are encoded
+   * directly from strings via `encodeInto` (no intermediate `Uint8Array`),
+   * while `requestId`/`headers` are already-encoded byte slices copied in
+   * verbatim.
+   *
+   * This removes the two `encoder.encode` allocations + copies per request
+   * that [`pack`] pays for URL/IP, while keeping the pre-encoded request-id
+   * bytes untouched (no decode-to-string → re-encode round trip, which
+   * `packFromStrings` would incur when a request id was already generated as
+   * bytes). The returned view is valid until the next pack.
+   */
+  packParts(
+    methodKind: number,
+    url: string,
+    ip: string | undefined,
+    requestId: Uint8Array,
+    headers: Uint8Array,
+  ): Uint8Array {
+    this.pos = 0
+
+    this.writeU8(methodKind)
+    this.writeStringLenPrefixed(url)
+    if (ip && ip.length > 0) {
+      this.writeStringLenPrefixed(ip)
+    } else {
+      this.writeLenPrefixed(EMPTY_IP_BYTES)
+    }
+    this.writeLenPrefixed(requestId)
+    this.writeLenPrefixed(headers)
+
+    return this.buf.subarray(0, this.pos)
+  }
+}

package/src/ingress/packing/scratch.ts

@@ -0,0 +1,50 @@
+// src/ingress/packing/scratch.ts — Shared thread-local scratch header buffers.
+//
+// Both the fast path (`packHeaders` in header-packing.ts) and the pre-baked
+// path (`gatherRawHeadersPacked` in gather-raw-headers.ts) pack request
+// headers into a reusable Uint8Array. This thread-local pool isolates the
+// buffer per call-site sequence and bounds the number of cached buffers,
+// keeping the hot path allocation-free.
+
+/** Scratch capacity for the reusable packed-header buffer. */
+export const HEADER_BUF_SIZE = 8192
+
+// ── Per-header size guards (SHARED by BOTH packing paths) ─────────
+// A header value larger than the bound below is dropped BEFORE packing rather
+// than forwarded. Without guards the fast path (`packHeaders`) forwarded any
+// size, so an oversized cookie/xff/origin could push the packed block past the
+// native `max_headers_bytes` (65536) and fail with a 500, while the pre-baked
+// path silently dropped the same header. Both paths must share ONE policy;
+// keep the Rust `max_headers_bytes` bound in mind when changing these.
+/** Upper bound for the `cookie` header value. */
+export const MAX_COOKIE_HEADER_BYTES = 8192
+/** Upper bound for small single-value headers (origin, ACRM, ACRH, ...). */
+export const MAX_SMALL_HEADER_BYTES = 2048
+/** Upper bound for the `x-forwarded-for` header value. */
+export const MAX_XFF_HEADER_BYTES = 8192
+
+// Thread-local header buffer for per-call isolation (round-robin over a
+// bounded pool; each buffer is only borrowed for the duration of one
+// pack/gather call).
+const [getHeaderBuf] = (() => {
+  const tls: [Uint8Array, DataView][] = []
+  const MAX_CACHED = 256
+  let tlsIdx = 0
+
+  function acquire(): [Uint8Array, DataView] {
+    const cached = tls[tlsIdx]
+    tlsIdx = (tlsIdx + 1) % MAX_CACHED
+    if (cached) return cached
+
+    const buf = new Uint8Array(HEADER_BUF_SIZE)
+    const view = new DataView(buf.buffer)
+    const pair: [Uint8Array, DataView] = [buf, view]
+    tls.push(pair)
+    return pair
+  }
+
+  return [acquire]
+})()
+
+/** Acquire the next scratch header buffer + view from the thread-local pool. */
+export { getHeaderBuf }

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

@@ -0,0 +1,102 @@
+// src/ingress/packing/select-headers.ts — Shared header-selection iterator.
+//
+// Single source of truth for "which headers does a HeaderPlan select" across
+// 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)
+//
+// 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 { 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'
+
+// ── 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')
+
+/**
+ * Visit every request header selected by `plan` (cookie, origin + CORS
+ * preflight method/headers, proxy XFF/XRI, proto XFP), applying the shared
+ * per-header size guards from scratch.ts. Callers supply `visit(name, value)`
+ * with the pre-encoded header-name bytes; no intermediate array is allocated.
+ *
+ * @param originValue - When provided (non-undefined), the already-fetched
+ *   `Origin` header value, avoiding a second `req.headers.get('origin')`
+ *   native→JS conversion on the hot path (the caller, e.g. `handlers.ts::run`,
+ *   already fetched it once for `ctx.origin`). When omitted, the origin is
+ *   fetched here. The same `MAX_SMALL_HEADER_BYTES` guard applies either way.
+ * @param visit - Invoked once per selected header with the pre-encoded name
+ *   bytes and the raw value string.
+ */
+export function forEachSelectedHeader(
+  req: Request,
+  plan: HeaderPlan,
+  methodKind: number,
+  originValue: string | null | undefined,
+  visit: (name: Uint8Array, value: string) => void,
+): void {
+  const h = req.headers
+
+  if (plan.cookie) {
+    const v = h.get('cookie')
+    if (v !== null && v.length <= MAX_COOKIE_HEADER_BYTES) {
+      visit(HDR_COOKIE, v)
+    }
+  }
+
+  if (plan.cors) {
+    const originV = originValue !== undefined ? originValue : h.get('origin')
+    if (originV !== null && originV.length <= MAX_SMALL_HEADER_BYTES) {
+      visit(HDR_ORIGIN, originV)
+    }
+
+    if (methodKind === METHOD_KIND.OPTIONS) {
+      const acrm = h.get('access-control-request-method')
+      if (acrm !== null && acrm.length <= MAX_SMALL_HEADER_BYTES) {
+        visit(HDR_ACRM, acrm)
+      }
+
+      const acrh = h.get('access-control-request-headers')
+      if (acrh !== null && acrh.length <= MAX_SMALL_HEADER_BYTES) {
+        visit(HDR_ACRH, acrh)
+      }
+    }
+  }
+
+  if (plan.proxy) {
+    const xff = h.get('x-forwarded-for')
+    if (xff !== null && xff.length <= MAX_XFF_HEADER_BYTES) {
+      visit(HDR_XFF, xff)
+    }
+
+    const xri = h.get('x-real-ip')
+    if (xri !== null && xri.length <= MAX_SMALL_HEADER_BYTES) {
+      visit(HDR_XRI, xri)
+    }
+  }
+
+  if (plan.proto) {
+    const xfp = h.get('x-forwarded-proto')
+    if (xfp !== null && xfp.length <= MAX_SMALL_HEADER_BYTES) {
+      visit(HDR_XFP, xfp)
+    }
+  }
+}

package/src/ingress/response/error-bodies.ts

@@ -0,0 +1,75 @@
+// src/ingress/response/error-bodies.ts — Pre-encoded static error bodies
+// (pre-baked path).
+//
+// The pre-baked path emits the benchmark wire format:
+//   {"ok":false,"error":{"code":"...","message":"..."}}
+// These bodies are encoded once at module load so error responses never
+// re-allocate or re-serialize on the hot path.
+
+import { encoder } from '../../shared/bytes'
+import {
+  ERR_CODE_CORS_PREFLIGHT,
+  ERR_CODE_RATE_LIMITED,
+  ERR_CODE_BODY_TOO_LARGE,
+  ERR_CODE_INVALID_JSON,
+  ERR_CODE_SCHEMA_VALIDATION,
+  ERR_CODE_BAD_REQUEST,
+  ERR_CODE_REQUEST_TOO_LARGE,
+  ERR_CODE_INTERNAL,
+} from '../constants'
+
+function staticErrorBody(code: string, message: string): Uint8Array {
+  return encoder.encode(`{"ok":false,"error":{"code":"${code}","message":"${message}"}}`)
+}
+
+/** Pre-encoded static error bodies, keyed by error-code string name. */
+export const ERROR_BODIES: Record<string, Uint8Array> = {
+  not_found: staticErrorBody('not_found', 'Not found'),
+  unsupported_media_type: staticErrorBody(
+    'unsupported_media_type',
+    'Content-Type must be application/json',
+  ),
+  body_too_large: staticErrorBody('body_too_large', 'Request body is too large'),
+  request_timeout: staticErrorBody('request_timeout', 'Request body read timed out'),
+  invalid_json: staticErrorBody('invalid_json', 'Invalid JSON body'),
+  schema_validation_failed: staticErrorBody(
+    'schema_validation_failed',
+    'Request body failed schema validation',
+  ),
+  cors_preflight_not_allowed: staticErrorBody(
+    'cors_preflight_not_allowed',
+    'CORS preflight not allowed',
+  ),
+  bad_request: staticErrorBody('bad_request', 'Bad request'),
+  request_too_large: staticErrorBody('request_too_large', 'Request too large'),
+  rate_limited: staticErrorBody('rate_limited', 'Too Many Requests'),
+  internal: staticErrorBody('internal_error', 'Internal server error'),
+}
+
+/** Error bodies indexed by numeric native error code. */
+export const ERROR_CODE_BODIES: (Uint8Array | undefined)[] = []
+ERROR_CODE_BODIES[ERR_CODE_CORS_PREFLIGHT] = ERROR_BODIES.cors_preflight_not_allowed
+ERROR_CODE_BODIES[ERR_CODE_RATE_LIMITED] = ERROR_BODIES.rate_limited
+ERROR_CODE_BODIES[ERR_CODE_BODY_TOO_LARGE] = ERROR_BODIES.body_too_large
+ERROR_CODE_BODIES[ERR_CODE_INVALID_JSON] = ERROR_BODIES.invalid_json
+ERROR_CODE_BODIES[ERR_CODE_SCHEMA_VALIDATION] = ERROR_BODIES.schema_validation_failed
+ERROR_CODE_BODIES[ERR_CODE_BAD_REQUEST] = ERROR_BODIES.bad_request
+ERROR_CODE_BODIES[ERR_CODE_REQUEST_TOO_LARGE] = ERROR_BODIES.request_too_large
+ERROR_CODE_BODIES[ERR_CODE_INTERNAL] = ERROR_BODIES.internal
+
+const RATE_LIMIT_BODY_PREFIX = encoder.encode(
+  '{"ok":false,"error":{"code":"rate_limited","message":"Too Many Requests","retry_after_ms":',
+)
+const RATE_LIMIT_BODY_SUFFIX = encoder.encode('}}')
+
+/** Build a rate-limited error body with the retry-after value inlined. */
+export function rateLimitedBody(retryAfterMs: number): Uint8Array {
+  const digits = encoder.encode(String(Math.max(0, Math.floor(retryAfterMs))))
+  const out = new Uint8Array(
+    RATE_LIMIT_BODY_PREFIX.byteLength + digits.byteLength + RATE_LIMIT_BODY_SUFFIX.byteLength,
+  )
+  out.set(RATE_LIMIT_BODY_PREFIX, 0)
+  out.set(digits, RATE_LIMIT_BODY_PREFIX.byteLength)
+  out.set(RATE_LIMIT_BODY_SUFFIX, RATE_LIMIT_BODY_PREFIX.byteLength + digits.byteLength)
+  return out
+}

package/src/ingress/response/terminal.ts

@@ -0,0 +1,59 @@
+// src/ingress/response/terminal.ts — Terminal (error) response builder (fast
+// path).
+//
+// Builds the fast-path terminal response: {"error":{code,status,message,
+// requestId}} with x-ratelimit-* headers. This is the fast-path wire format;
+// the pre-baked path has its own builders (see ./handlers.ts) — do not unify
+// them (see AGENTS.md).
+
+import { headersForResult, type ResponseBuildContext } from '../headers/fast-templates'
+import { safeTerminalStatus } from '../status'
+import { errorCodeName, errorMessage } from '../errors'
+
+/**
+ * Build a terminal response for a result, or `null` when the result is not
+ * terminal (the caller should serve the body instead).
+ */
+export function buildTerminalResponse(
+  ctx: ResponseBuildContext,
+  r: {
+    readonly terminal: boolean
+    readonly isPreflight: boolean
+    readonly corsAllowed: boolean
+    readonly errorCode: number
+    readonly status: number
+    readonly headerVariant: number
+    readonly https: boolean
+    readonly rateLimit: number
+    readonly rateRemaining: number
+    readonly rateResetMs: number
+    readonly retryAfterMs: number
+  },
+  req: Request,
+  requestId: string,
+): Response | null {
+  if (!r.terminal) return null
+
+  const preflightAllowed = r.isPreflight && r.corsAllowed
+  const headers = headersForResult(ctx, r, req, requestId)
+
+  if (preflightAllowed) {
+    return new Response(null, { status: 204, headers })
+  }
+
+  const status = safeTerminalStatus(r)
+
+  headers.set('content-type', 'application/json; charset=utf-8')
+  headers.set('cache-control', 'no-store')
+
+  const payload = JSON.stringify({
+    error: {
+      code: errorCodeName(r.errorCode),
+      status,
+      message: errorMessage(status, r.errorCode),
+      requestId: requestId || undefined,
+    },
+  })
+
+  return new Response(payload, { status, headers })
+}

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 }
+}