castrum 0.7.0 → 0.9.1

package/src/ingress/handlers.ts

@@ -1,7 +1,7 @@
 // src/ingress/handlers.ts — Pre-baked ingress handler functions
 //
 // A ready-to-use convenience layer for consuming the optimized ingress pipeline
-// (native Ingress.handleRequestFullSync) with zero boilerplate. Any system can
+// (native Ingress.handleRequestPacked) with zero boilerplate. Any system can
 // wire up ingress in a few lines:
 //
 //   import {
@@ -27,443 +27,378 @@
 // This module deliberately keeps the benchmark's wire format ({"ok":false,
 // "error":{...}} bodies, `ratelimit-*` headers). It does NOT reuse fast.ts's
 // response builders because those emit a different payload shape.
-
-import addon from "../native";
+//
+// The pre-baked pipeline is decomposed into task-focused submodules:
+//   - decode/baked-result.ts       BakedIngressResult (zero-alloc decode)
+//   - response/error-bodies.ts     pre-encoded error bodies
+//   - headers/baked-templates.ts   ratelimit-* header templates
+//   - packing/gather-raw-headers.ts raw header gathering
+//   - routes/*                     route factories
+//   - server.ts                    Bun.serve builder
+
+import { getAddon } from '../native'
+import { getBunFFI } from '../native/ffi'
+import { BufferPool, type PooledBuffer } from '../shared/buffer-pool'
+import { decoder, encoder, viewForArrayBuffer } from '../shared/bytes'
+import { createStructuredLogger } from '../shared/log'
+import { generateRequestId } from '../shared/request-id'
+import { pooledBodyResponse } from '../shared/response'
 import {
-  OUT_VERDICT,
-  OUT_FLAGS,
-  OUT_RATE_LIMIT,
-  OUT_RATE_REMAINING,
-  OUT_RATE_RESET,
-  OUT_RETRY_AFTER,
-  OUT_COOKIES_JSON_LEN,
-  OUT_QUERY_JSON_LEN,
-  OUT_HEADER_VARIANT,
-  OUT_BODY_JSON_LEN,
-  OUT_DATA_START,
-  FLAG_BODY_VALID_JSON,
-  FLAG_SCHEMA_VALID,
-  FLAG_CORS_ALLOWED,
-  FLAG_IS_PREFLIGHT,
-  FLAG_RATE_LIMITED,
-  FLAG_TRUSTED_PROXY,
-  FLAG_BODY_TRUNCATED,
-  HV_JSON,
-  HV_CORS_SIMPLE,
+  ERR_CODE_RATE_LIMITED as ERROR_CODE_RATE_LIMITED,
   HV_CORS_PREFLIGHT,
+  HV_CORS_SIMPLE,
+  HV_JSON,
   HV_RATE_ACTIVE,
   HV_RATE_LIMITED,
-  ERR_CODE_CORS_PREFLIGHT as ERROR_CODE_CORS_PREFLIGHT,
-  ERR_CODE_RATE_LIMITED as ERROR_CODE_RATE_LIMITED,
-  ERR_CODE_BODY_TOO_LARGE as ERROR_CODE_BODY_TOO_LARGE,
-  ERR_CODE_INVALID_JSON as ERROR_CODE_INVALID_JSON,
-  ERR_CODE_SCHEMA_VALIDATION as ERROR_CODE_SCHEMA_VALIDATION,
-  ERR_CODE_BAD_REQUEST as ERROR_CODE_BAD_REQUEST,
-  ERR_CODE_REQUEST_TOO_LARGE as ERROR_CODE_REQUEST_TOO_LARGE,
-  ERR_CODE_INTERNAL as ERROR_CODE_INTERNAL,
-} from "./constants";
+  OUT_DATA_START,
+} from './constants'
+import { BakedIngressResult } from './decode/baked-result'
+import { buildBakedHeaderTemplates } from './headers/baked-templates'
+import type { SecurityHeadersOptions } from './headers/hsts'
+import { buildSecurityPairs } from './headers/hsts'
 import {
-  METHOD_KIND,
-  generateRequestId,
-  safeTerminalStatus,
-  DEFAULT_MAX_BODY_BYTES,
+  assertIngressOptionValues,
+  assertKnownIngressOptions,
+  type IngressHandlerOptions,
+  warnTrustProxyDeprecated,
+} from './options'
+import { gatherRawHeadersPacked } from './packing/gather-raw-headers'
+import { IngressInputPacker } from './packing/input-packer'
+import { ERROR_BODIES, ERROR_CODE_BODIES, rateLimitedBody } from './response/error-bodies'
+import {
+  assertSyncCallback,
+  buildHeaderPlan,
+  clampIngressBufferSize,
+  DEFAULT_BAKED_OUTPUT_BUFFER_SIZE,
   type HeaderPlan,
-} from "./fast";
-
-const encoder = new TextEncoder();
-const decoder = new TextDecoder();
-const EMPTY_BODY = new Uint8Array(0);
-const EMPTY_IP = "0.0.0.0";
+  METHOD_KIND,
+  METHOD_KIND_UNKNOWN,
+  secondsFromMs,
+} from './shared'
+import { safeTerminalStatus } from './status'
+import type { BakedContext, OptimizedIngressHandler } from './types'
+
+// ── Re-exports (back-compat: preserve handlers.ts's original public surface) ──
+export { BakedIngressResult } from './decode/baked-result'
+export type { IngressHandlerOptions } from './options'
+export { ERROR_BODIES } from './response/error-bodies'
+export type { BakedHandlerOptions } from './routes'
+export {
+  deleteHandler,
+  echoHandler,
+  fallbackHandler,
+  headHandler,
+  jsonWriteHandler,
+  nativeResponderRoute,
+  optionsHandler,
+  readHandler,
+} from './routes'
+export type {
+  BakedRoute,
+  BakedServer,
+  CreateIngressServerOptions,
+  GracefulShutdownOptions,
+  ServerHandle,
+} from './server'
+export { createIngressServer, gracefulShutdown } from './server'
+export type { RouteHandler as IngressNodeRouteHandler } from './server-node'
+// Node.js HTTP adapter (same pre-baked route handlers, node:http backend).
+export { createIngressServerNode } from './server-node'
+
+const EMPTY_BODY = new Uint8Array(0)
+const EMPTY_IP = '0.0.0.0'
 
 /** Sentinel value used by Rust to mean "rate limiting disabled". */
-export const RATE_LIMIT_U32_MAX = 4_294_967_295;
-
-const DEFAULT_OUTPUT_BUF_SIZE = 131_072;
-
-const MAX_COOKIE_HEADER_BYTES = 8192;
-const MAX_SMALL_HEADER_BYTES = 2048;
-const MAX_XFF_HEADER_BYTES = 8192;
+export const RATE_LIMIT_U32_MAX = 4_294_967_295
 
-// ── Static error bodies ──
-function staticErrorBody(code: string, message: string): Uint8Array {
-  return encoder.encode(
-    `{"ok":false,"error":{"code":"${code}","message":"${message}"}}`,
-  );
-}
-
-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"),
-  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"),
-};
-
-const ERROR_CODE_BODIES: (Uint8Array | undefined)[] = [];
-ERROR_CODE_BODIES[ERROR_CODE_CORS_PREFLIGHT] =
-  ERROR_BODIES.cors_preflight_not_allowed;
-ERROR_CODE_BODIES[ERROR_CODE_RATE_LIMITED] = ERROR_BODIES.rate_limited;
-ERROR_CODE_BODIES[ERROR_CODE_BODY_TOO_LARGE] = ERROR_BODIES.body_too_large;
-ERROR_CODE_BODIES[ERROR_CODE_INVALID_JSON] = ERROR_BODIES.invalid_json;
-ERROR_CODE_BODIES[ERROR_CODE_SCHEMA_VALIDATION] =
-  ERROR_BODIES.schema_validation_failed;
-ERROR_CODE_BODIES[ERROR_CODE_BAD_REQUEST] = ERROR_BODIES.bad_request;
-ERROR_CODE_BODIES[ERROR_CODE_REQUEST_TOO_LARGE] =
-  ERROR_BODIES.request_too_large;
-ERROR_CODE_BODIES[ERROR_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("}}");
-
-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;
-}
-
-// ── Zero-alloc result wrapper ──
-export class BakedIngressResult {
-  status = 0;
-  verdict = 0;
-  errorCode = 0;
-  headerVariant = 0;
-  rateRemaining = 0;
-  rateResetMs = 0;
-  retryAfterMs = 0;
-  terminal = true;
-  ok = false;
-  isPreflight = false;
-  corsAllowed = false;
-  rateLimited = false;
-  trustedProxy = false;
-  bodyValidJson = false;
-  schemaValid = false;
-  bodyTruncated = false;
-  body: Uint8Array = EMPTY_BODY;
-
-  private _buf: Uint8Array = EMPTY_BODY;
-  private _bodyJsonStart = OUT_DATA_START;
-  private _bodyJsonLen = 0;
-
-  refresh(buf: Uint8Array, body: Uint8Array, view: DataView): void {
-    this._buf = buf;
-    this.body = body;
-
-    const h0 = view.getUint32(OUT_VERDICT, true);
-    const h1 = view.getUint32(OUT_FLAGS, true);
-    const h2 = view.getUint32(OUT_RATE_LIMIT, true);
-    const h3 = view.getUint32(OUT_RATE_REMAINING, true);
-
-    const cookiesLenRaw = view.getUint32(OUT_COOKIES_JSON_LEN, true);
-    const queryLenRaw = view.getUint32(OUT_QUERY_JSON_LEN, true);
-    const headerVariant = view.getUint8(OUT_HEADER_VARIANT);
-    const bodyJsonLenRaw = view.getUint32(OUT_BODY_JSON_LEN, true);
-
-    const safeCookiesLen =
-      OUT_DATA_START + cookiesLenRaw <= buf.byteLength ? cookiesLenRaw : 0;
-    const queryStart = OUT_DATA_START + safeCookiesLen;
-    const safeQueryLen =
-      queryStart + queryLenRaw <= buf.byteLength ? queryLenRaw : 0;
-    const bodyJsonStart = queryStart + safeQueryLen;
-    const safeBodyJsonLen =
-      bodyJsonStart + bodyJsonLenRaw <= buf.byteLength ? bodyJsonLenRaw : 0;
-
-    if (h0 === 0 && h1 === 0) {
-      this.verdict = 1;
-      this.errorCode = ERROR_CODE_INTERNAL;
-      this.status = 500;
-    } else {
-      this.verdict = h0 & 0xff;
-      this.errorCode = (h0 >>> 8) & 0xff;
-
-      const rawStatus = (h0 >>> 16) & 0xffff;
-      const validStatus =
-        rawStatus === 101 || (rawStatus >= 200 && rawStatus <= 599);
-      this.status = validStatus ? rawStatus : 500;
-    }
-
-    const flags = h1;
-
-    this.rateRemaining = h3;
-
-    if (h2 > 0 || (flags & FLAG_RATE_LIMITED) !== 0) {
-      this.rateResetMs = Number(view.getBigUint64(OUT_RATE_RESET, true));
-      this.retryAfterMs = Number(view.getBigUint64(OUT_RETRY_AFTER, true));
-    } else {
-      this.rateResetMs = 0;
-      this.retryAfterMs = 0;
-    }
-
-    this.headerVariant = headerVariant;
-    this._bodyJsonStart = bodyJsonStart;
-    this._bodyJsonLen = safeBodyJsonLen;
-
-    this.terminal = this.verdict !== 0 || this.status >= 400;
-    this.ok = this.verdict === 0 && this.status >= 200 && this.status < 400;
-
-    this.isPreflight = (flags & FLAG_IS_PREFLIGHT) !== 0;
-    this.corsAllowed = (flags & FLAG_CORS_ALLOWED) !== 0;
-    this.rateLimited = (flags & FLAG_RATE_LIMITED) !== 0;
-    this.trustedProxy = (flags & FLAG_TRUSTED_PROXY) !== 0;
-    this.bodyValidJson = (flags & FLAG_BODY_VALID_JSON) !== 0;
-    this.schemaValid = (flags & FLAG_SCHEMA_VALID) !== 0;
-
-    this.bodyTruncated =
-      (flags & FLAG_BODY_TRUNCATED) !== 0 ||
-      safeCookiesLen !== cookiesLenRaw ||
-      safeQueryLen !== queryLenRaw ||
-      safeBodyJsonLen !== bodyJsonLenRaw;
-  }
-
-  invalidate(): void {
-    this.status = 0;
-    this.verdict = 0;
-    this.errorCode = 0;
-    this.headerVariant = 0;
-    this.rateRemaining = 0;
-    this.rateResetMs = 0;
-    this.retryAfterMs = 0;
-    this.terminal = true;
-    this.ok = false;
-    this.isPreflight = false;
-    this.corsAllowed = false;
-    this.rateLimited = false;
-    this.trustedProxy = false;
-    this.bodyValidJson = false;
-    this.schemaValid = false;
-    this.bodyTruncated = false;
-    this.body = EMPTY_BODY;
-    this._buf = EMPTY_BODY;
-    this._bodyJsonStart = OUT_DATA_START;
-    this._bodyJsonLen = 0;
-  }
+/**
+ * Consecutive `bun:ffi` ingress failures before this handler permanently
+ * falls back to the napi addon (a panic that `panic_guard` contained, or a
+ * bun:ffi regression that throws). Low enough to recover fast from a flaky
+ * transport, high enough that a single transient failure never flips it.
+ */
+const MAX_FFI_FAILURES = 3
 
-  setInternalError(): void {
-    this.invalidate();
-    this.status = 500;
-    this.verdict = 1;
-    this.errorCode = ERROR_CODE_INTERNAL;
-    this.headerVariant = HV_JSON;
-    this.terminal = true;
-    this.ok = false;
+/**
+ * Best-effort URL pathname extraction for log/error lines.
+ *
+ * This runs inside catch/finally paths, so a malformed `req.url` must never
+ * throw out of the handler (an uncaught error here would bypass `onError`).
+ * Falls back to the raw URL string when parsing fails.
+ */
+function pathForLog(req: Request): string {
+  try {
+    return new URL(req.url).pathname
+  } catch {
+    return req.url
   }
+}
 
-  bodyJson(copy: boolean): Uint8Array {
-    if (this._bodyJsonLen === 0) {
-      return EMPTY_BODY;
-    }
-
-    const end = this._bodyJsonStart + this._bodyJsonLen;
-    if (end > this._buf.byteLength) {
-      return EMPTY_BODY;
-    }
-
-    const slice = this._buf.subarray(this._bodyJsonStart, end);
-    return (copy ? slice.slice() : slice) as Uint8Array;
-  }
+/**
+ * Merge structured `options.security` (SecurityHeadersOptions) with raw
+ * `runtime.securityHeaders` pairs into the ordered entries the baked templates
+ * prepend to every response variant. Raw pairs win on name conflicts; names are
+ * lowercased for the template merge.
+ *
+ * The structured defaults (nosniff/DENY/no-referrer) are ONLY applied when the
+ * user explicitly opted into security on this path (`security !== undefined`) —
+ * the baked path's long-standing default is no security headers, and silently
+ * adding them would change every response.
+ */
+function buildBakedSecurityEntries(
+  security: SecurityHeadersOptions | undefined,
+  https: boolean | undefined,
+  raw: ReadonlyArray<[string, string]> | undefined,
+): Array<[string, string]> {
+  const structured = security === undefined ? [] : buildSecurityPairs(security, https, true)
+
+  if (raw === undefined || raw.length === 0) return structured
+
+  const byName = new Map<string, string>()
+  for (const [k, v] of structured) byName.set(k, v)
+  for (const [k, v] of raw) byName.set(k.toLowerCase(), v)
+  return [...byName.entries()]
 }
 
 // ── Types ────────────────────────────────────────────────────────
-export interface BakedContext {
-  requestIdHeader: string | null;
-  origin: string | null;
-}
+// `BakedContext` and `OptimizedIngressHandler` are defined in ./types.ts
+// (shared with the route factories) and re-exported here for back-compat.
+export type { BakedContext, OptimizedIngressHandler } from './types'
 
+/** Runtime configuration for the pre-baked handler path (`createIngressHandler`). */
 export interface BakedIngressRuntime {
   /** Emit an `x-request-id` header on responses. Default: false. */
-  emitRequestIdHeader?: boolean;
+  emitRequestIdHeader?: boolean
   /** Enable security headers on responses. Default: true. */
-  enableSecurityHeaders?: boolean;
-  /** Ordered `[name, value]` security headers (names are lowercased). */
-  securityHeaders?: ReadonlyArray<[string, string]>;
+  enableSecurityHeaders?: boolean
+  /**
+   * Ordered `[name, value]` security headers (names are lowercased).
+   * NOTE: this PRE-BAKED path takes RAW `[name, value]` pairs here; the
+   * fast/async paths (`createIngressFast`/`createIngress`) instead take a
+   * structured `security: SecurityHeadersOptions` object (CSP/HSTS builders).
+   * The two paths intentionally use different option shapes (see
+   * docs/INGRESS.md).
+   */
+  securityHeaders?: ReadonlyArray<[string, string]>
   /** Native output buffer size in bytes. Default: 131072. */
-  outputBufferSize?: number;
+  outputBufferSize?: number
+  /** Invoked before a request is processed (for tracing/context hooks). */
+  onRequest?: (req: Request, requestId: string, ip: string | undefined) => void
   /** Invoked after a Response is produced (for metrics/logging hooks). */
-  onResponse?: (
-    req: Request,
-    result: BakedIngressResult,
-    status: number,
-    requestId: string,
-  ) => void;
+  onResponse?: (req: Request, result: BakedIngressResult, status: number, requestId: string) => void
+  /**
+   * Invoked when the native pipeline fails (the request becomes a 500).
+   * Native failures are otherwise silent — wire this to your error tracker.
+   */
+  onError?: (req: Request, requestId: string, error: Error) => void
+  /**
+   * Emit one structured JSON line per request/error via the built-in logger
+   * (gated by `CASTRUM_LOG_LEVEL`). Default: false.
+   */
+  structuredLog?: boolean
+  /**
+   * Custom structured logger (e.g. with a custom stream or extra fields).
+   * When provided, request/error lines go here instead of the built-in stderr
+   * logger and `structuredLog` is implicitly enabled.
+   */
+  logger?: ReturnType<typeof createStructuredLogger>
+  /**
+   * Hard cap on concurrently borrowed output buffers (zero-copy responses not
+   * yet consumed). Bounds memory when zero-copy responses are consumed
+   * slowly; when exceeded, requests fail with a 500 (pool exhaustion) instead
+   * of allocating unbounded temporaries. 0 (default) is unlimited — see
+   * `BufferPool.maxInFlight`.
+   */
+  maxInFlight?: number
+  /**
+   * Abandonment guard (ms) for zero-copy responses: if a response body is
+   * neither pulled nor cancelled within this window, its pooled buffer is
+   * released and the stream closed. Bounds memory under abandoned (unread)
+   * zero-copy responses. 0 (default) disables it — see `pooledBodyResponse`.
+   */
+  zeroCopyTimeoutMs?: number
 }
 
+// ── Optimized ingress factory ─────────────────────────────────────
+
 /**
- * An optimized ingress handler. `run()` is the zero-alloc pipeline entry
- * point; the response-builder methods are pre-baked and bound to this
- * handler's configuration, so consumers can build custom routes without
- * touching header templates or error bodies.
+ * Create a pre-baked ingress handler (path 2).
+ *
+ * The request frame (url/ip/rid/headers) is packed in JS via `IngressInputPacker`
+ * + `gatherRawHeadersPacked` and driven through the same native core as the
+ * fast path (`Ingress.handleRequestPacked`), writing into a pooled output
+ * buffer (no per-request allocation). Responses use the benchmark wire format
+ * (`{"ok":false,"error":{...}}` + `ratelimit-*` headers) — see AGENTS.md for
+ * why this differs from `createIngressFast`.
+ *
+ * Returns an `OptimizedIngressHandler` whose response-builder methods are
+ * bound to this handler's configuration. Pair it with the route factories
+ * (`readHandler`, `jsonWriteHandler`, ...) or `createIngressServer`.
  */
-export interface OptimizedIngressHandler {
-  run<T>(
-    req: Request,
-    ip: string | undefined,
-    body: Uint8Array | null,
-    fn: (result: BakedIngressResult, ctx: BakedContext) => T,
-  ): T;
-
-  responseHeaders(
-    variant: number,
-    requestIdHeader: string | null,
-    origin: string | null,
-    rateRemaining?: number,
-    rateResetSecs?: number,
-    retryAfterSecs?: number,
-  ): [string, string][];
-
-  terminalHeaders(
-    variant: number,
-    ctx: BakedContext,
-    result: BakedIngressResult | null,
-  ): [string, string][];
-
-  terminalResponse(
-    req: Request,
-    result: BakedIngressResult,
-    ctx: BakedContext,
-  ): Response | null;
-
-  errorResponse(
-    req: Request,
-    result: BakedIngressResult | null,
-    status: number,
-    code: string,
-    message: string,
-    ctx: BakedContext,
-  ): Response;
-
-  internalErrorResponse(ctx: BakedContext, result?: BakedIngressResult): Response;
-
-  withContentType(
-    headers: ReadonlyArray<[string, string]>,
-    contentType: string,
-  ): [string, string][];
-}
-
-// ── Optimized ingress factory ─────────────────────────────────────
 export function createIngressHandler(
-  options: Record<string, unknown>,
+  options: IngressHandlerOptions = {},
   runtime: BakedIngressRuntime = {},
 ): OptimizedIngressHandler {
-  const NativeIngress = (addon as any).Ingress;
-  if (typeof NativeIngress !== "function") {
-    throw new Error("Native Ingress class missing. Rebuild the Rust addon.");
+  // Fail fast on a misspelled option key — same guard as the fast path.
+  assertKnownIngressOptions(options, 'createIngressHandler')
+  assertIngressOptionValues(options, 'createIngressHandler')
+  if (options.trustProxy === true) {
+    warnTrustProxyDeprecated()
   }
-
-  const handler = new NativeIngress(options);
-  if (typeof handler.handleRequestFullSync !== "function") {
-    throw new Error(
-      "Native Ingress.handleRequestFullSync missing. Rebuild the Rust addon.",
-    );
+  // Lazy: the native addon is only needed once a handler is created.
+  const addon = getAddon()
+  const NativeIngress = addon.Ingress
+  if (typeof NativeIngress !== 'function') {
+    throw new Error('Native Ingress class missing. Rebuild the Rust addon.')
   }
 
-  const trust = options.trustProxy === true;
-  const rateLimit = options.rateLimit as { limit?: number } | undefined;
-  const limit = rateLimit?.limit;
-  const rateEnabled =
-    typeof limit === "number" && limit !== RATE_LIMIT_U32_MAX && limit > 0;
-
-  const headerPlan: HeaderPlan = {
-    cookie: options.parseCookies === true,
-    cors: options.cors != null,
-    proxy: trust && rateEnabled,
-    proto: trust && options.https === undefined,
-  };
+  const handler = new NativeIngress(options)
+  if (typeof handler.handleRequestPacked !== 'function') {
+    throw new Error('Native Ingress.handleRequestPacked missing. Rebuild the Rust addon.')
+  }
 
-  const emitRequestIdHeader = runtime.emitRequestIdHeader === true;
-  const outputBufferSize = runtime.outputBufferSize ?? DEFAULT_OUTPUT_BUF_SIZE;
+  // Bun fast path: drive the SAME native pipeline through `bun:ffi` (opaque
+  // inner handle from `ingressInnerPtr`), cutting the per-request N-API
+  // crossing. The handle is valid only while `handler` is alive — this closure
+  // holds `handler` for the handler's lifetime, so it can never dangle. Falls
+  // back to napi when ffi is unavailable, the addon lacks the pointer method,
+  // or the handle is 0 (i.e. the state was dropped).
+  const bunFFI = getBunFFI()
+  // The opaque handle is a u64 under the 2^53 number range, so convert it to a
+  // plain JS number ONCE here — bun:ffi converts a BigInt argument to a number
+  // on every call anyway (and docs note BigInt is slower), so passing a number
+  // removes that per-request conversion on the hottest path.
+  const ingressPtr =
+    bunFFI !== null && typeof handler.ingressInnerPtr === 'function'
+      ? Number(handler.ingressInnerPtr())
+      : 0
+
+  const rateLimit = options.rateLimit as { limit?: number } | undefined
+  const limit = rateLimit?.limit
+  const rateEnabled = typeof limit === 'number' && limit !== RATE_LIMIT_U32_MAX && limit > 0
+
+  // Minimal-processing flags: skip per-request JS UTF-8 encoding of the URL/IP
+  // when the native pipeline (rust/ingress/pipeline.rs) provably cannot read
+  // them — mirror its consumption exactly, and KEEP IN SYNC:
+  //   - URL is consumed iff parseQuery (extract_query), emitMetadataJson
+  //     (extract_path into the envelope) or https is unpinned (detect_https
+  //     scans the scheme prefix). Otherwise an empty URL section is safe.
+  //   - IP is consumed iff rate limiting is active (resolve_client_ip /
+  //     rate_key) or a proxy-trust mode is configured (socket_is_trusted
+  //     parses it). Otherwise the IP is dropped from the frame (logs/hooks
+  //     still see the real `ip` — this only skips the frame encode).
+  const trustEnabled = options.trustProxy === true || options.trustedProxies?.enabled === true
+  const urlNeeded =
+    options.parseQuery === true || options.emitMetadataJson === true || options.https === undefined
+  const ipNeeded = rateEnabled || trustEnabled
+
+  // Shared with the fast path — proxy extraction is driven by trust config
+  // (trustProxy / trustedProxies), not by whether rate limiting is enabled.
+  const headerPlan: HeaderPlan = buildHeaderPlan(options)
+
+  const emitRequestIdHeader = runtime.emitRequestIdHeader === true
+  const zeroCopyTimeoutMs = runtime.zeroCopyTimeoutMs ?? 0
+  const outputBufferSize = clampIngressBufferSize(
+    runtime.outputBufferSize ?? DEFAULT_BAKED_OUTPUT_BUFFER_SIZE,
+    OUT_DATA_START,
+  )
+
+  // Built-in structured logger (opt-in; gated by CASTRUM_LOG_LEVEL). A custom
+  // `runtime.logger` overrides it and implies structuredLog:true.
+  const logger =
+    runtime.logger ?? (runtime.structuredLog === true ? createStructuredLogger() : null)
+
+  // Only materialize the request-id string when a consumer needs it, avoiding
+  // one string allocation + UTF-8 decode per request in deployments with no
+  // hooks/logging. The bench wires `onResponse`, so the decode stays hot there;
+  // lean servers with no hooks skip it entirely.
+  const needRequestIdString = !!(
+    emitRequestIdHeader ||
+    runtime.onRequest ||
+    runtime.onError ||
+    runtime.onResponse ||
+    logger
+  )
+
+  // 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.
+  const outputPool = new BufferPool({
+    initialSize: outputBufferSize,
+    maxInFlight: runtime.maxInFlight,
+  })
+
+  // Reusable packed-input builder (same zero-alloc discipline as the fast
+  // path): the per-request frame is packed into this buffer instead of paying
+  // the napi `Vec<Vec<String>>` header marshaling of the full_sync family.
+  const inputPacker = new IngressInputPacker()
+
+  // Per-call state: the output handle backing the current `run()`'s result,
+  // and whether a zero-copy Response claimed it (so `run()` must not release
+  // it back to the pool before the body is consumed).
+  let currentHandle: PooledBuffer | null = null
+  let responseBorrowsBuffer = false
+
+  // FFI circuit breaker (defense-in-depth): the raw C ABI cannot contain
+  // non-panic UB (a segfault still crashes the process), but a RECURRING
+  // observable failure — a panic that `panic_guard` turned into 0 → throw, or
+  // a bun:ffi regression that throws — is caught here and permanently
+  // re-routed to the napi fallback (crash-safe via napi-rs catch_unwind), so a
+  // flaky FFI path degrades to a correct response instead of a failure storm.
+  let ffiFailures = 0
+  let ffiDisabled = false
+
+  // 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).
+  const originHeaderCache = new Map<string, [string, string][]>()
 
   // ── Variant-indexed header templates (precomputed once) ──
   const cors = options.cors as
     | {
-        allowOrigin?: string[];
-        allowMethods?: string[];
-        allowHeaders?: string[];
-        exposeHeaders?: string[];
-        allowCredentials?: boolean;
-        maxAge?: number;
+        allowOrigin?: string[]
+        allowMethods?: string[]
+        allowHeaders?: string[]
+        exposeHeaders?: string[]
+        allowCredentials?: boolean
+        maxAge?: number
       }
-    | undefined;
-
+    | undefined
+
+  // Security headers: honor the STRUCTURED `options.security`
+  // (SecurityHeadersOptions — the same shape `createIngress` honors) merged
+  // with raw `runtime.securityHeaders` pairs (raw wins on name conflicts).
+  // This closes the historic gotcha where `options.security` was silently
+  // ignored on the pre-baked path. When neither is provided, no security
+  // headers are emitted (the baked path's long-standing default).
   const securityEntries: ReadonlyArray<[string, string]> =
     runtime.enableSecurityHeaders === false
       ? Object.freeze([] as [string, string][])
       : Object.freeze(
-          (runtime.securityHeaders ?? []).map(
-            ([k, v]) => [k.toLowerCase(), v] as [string, string],
-          ),
-        );
-
-  const corsAllowMethods = cors?.allowMethods?.join(", ") ?? "";
-  const corsAllowHeaders = cors?.allowHeaders?.join(", ") ?? "";
-  const corsExposeHeaders = cors?.exposeHeaders?.join(", ") ?? "";
-  const corsMaxAge = cors?.maxAge != null ? String(cors.maxAge) : "";
-  const rateLimitStr = rateEnabled ? String(limit) : "";
-
-  const headerTemplates: ReadonlyArray<ReadonlyArray<[string, string]>> =
-    Object.freeze(
-      Array.from({ length: 32 }, (_, variant) => {
-        const entries: [string, string][] = [...securityEntries];
-
-        if ((variant & HV_JSON) !== 0) {
-          entries.push(["content-type", "application/json"]);
-        }
-
-        if ((variant & HV_CORS_SIMPLE) !== 0) {
-          entries.push(["vary", "Origin"]);
-          if (cors?.allowCredentials) {
-            entries.push(["access-control-allow-credentials", "true"]);
-          }
-          if (corsExposeHeaders.length > 0) {
-            entries.push(["access-control-expose-headers", corsExposeHeaders]);
-          }
-        }
-
-        if ((variant & HV_CORS_PREFLIGHT) !== 0) {
-          entries.push([
-            "vary",
-            "Origin, Access-Control-Request-Method, Access-Control-Request-Headers",
-          ]);
-          if (cors?.allowCredentials) {
-            entries.push(["access-control-allow-credentials", "true"]);
-          }
-          entries.push(["access-control-allow-methods", corsAllowMethods]);
-          entries.push(["access-control-allow-headers", corsAllowHeaders]);
-          entries.push(["access-control-max-age", corsMaxAge]);
-        }
-
-        if ((variant & HV_RATE_ACTIVE) !== 0) {
-          entries.push(["ratelimit-limit", rateLimitStr]);
-        }
-
-        return Object.freeze(entries);
-      }),
-    );
+          buildBakedSecurityEntries(options.security, options.https, runtime.securityHeaders),
+        )
+
+  const corsAllowMethods = cors?.allowMethods?.join(', ') ?? ''
+  const corsAllowHeaders = cors?.allowHeaders?.join(', ') ?? ''
+  const corsExposeHeaders = cors?.exposeHeaders?.join(', ') ?? ''
+  const corsMaxAge = cors?.maxAge != null ? String(cors.maxAge) : ''
+  const rateLimitStr = rateEnabled ? String(limit) : ''
+
+  const { regular: headerTemplates, terminal: terminalTemplates } = buildBakedHeaderTemplates({
+    securityEntries,
+    cors,
+    corsAllowMethods,
+    corsAllowHeaders,
+    corsExposeHeaders,
+    corsMaxAge,
+    rateLimitStr,
+  })
 
   function responseHeaders(
     variant: number,
@@ -474,51 +409,72 @@ export function createIngressHandler(
     retryAfterSecs?: number,
   ): [string, string][] {
     const template: ReadonlyArray<[string, string]> =
-      headerTemplates[variant & 31] ?? headerTemplates[0] ?? [];
+      headerTemplates[variant & 31] ?? headerTemplates[0] ?? []
 
-    const needsRequestId = emitRequestIdHeader && requestIdHeader !== null;
+    const needsRequestId = emitRequestIdHeader && requestIdHeader !== null
     const needsOrigin =
-      ((variant & HV_CORS_SIMPLE) !== 0 ||
-        (variant & HV_CORS_PREFLIGHT) !== 0) &&
-      origin !== null;
-    const needsRate = (variant & HV_RATE_ACTIVE) !== 0;
-    const needsRetry = (variant & HV_RATE_LIMITED) !== 0;
+      ((variant & HV_CORS_SIMPLE) !== 0 || (variant & HV_CORS_PREFLIGHT) !== 0) && origin !== null
+    const needsRate = (variant & HV_RATE_ACTIVE) !== 0
+    const needsRetry = (variant & HV_RATE_LIMITED) !== 0
 
     if (!needsRequestId && !needsOrigin && !needsRate && !needsRetry) {
-      return template as unknown as [string, string][];
+      // Frozen-readonly → mutable: callers only ever read the baked template
+      // (zero-copy steady-state path), so the widening is safe in practice.
+      return template as unknown as [string, string][]
+    }
+
+    if (!needsRequestId && !needsRate && !needsRetry && needsOrigin) {
+      // Steady-state CORS: only the origin varies — cache the augmented array
+      // per (variant, origin) so the Origin-present case (the common
+      // browser/bench case) stays allocation-free after the first hit for EACH
+      // distinct origin (a single-slot memo thrashed when clients alternate
+      // between allowed origins, allocating a fresh array on every switch).
+      const key = `${variant & 31}\u0000${origin as string}`
+      const cached = originHeaderCache.get(key)
+      if (cached !== undefined) {
+        return cached
+      }
+      const entries = new Array<[string, string]>(template.length + 1)
+      let i = 0
+      for (const pair of template) {
+        entries[i++] = pair
+      }
+      entries[i] = ['access-control-allow-origin', origin as string]
+      originHeaderCache.set(key, entries)
+      return entries
     }
 
-    let extra = 0;
-    if (needsRequestId) extra++;
-    if (needsOrigin) extra++;
-    if (needsRate) extra += 2;
-    if (needsRetry) extra++;
+    let extra = 0
+    if (needsRequestId) extra++
+    if (needsOrigin) extra++
+    if (needsRate) extra += 2
+    if (needsRetry) extra++
 
-    const entries = new Array<[string, string]>(template.length + extra);
-    let i = 0;
+    const entries = new Array<[string, string]>(template.length + extra)
+    let i = 0
 
-    for (; i < template.length; i++) {
-      entries[i] = template[i]!;
+    for (const pair of template) {
+      entries[i++] = pair
     }
 
     if (needsRequestId) {
-      entries[i++] = ["x-request-id", requestIdHeader as string];
+      entries[i++] = ['x-request-id', requestIdHeader as string]
     }
 
     if (needsOrigin) {
-      entries[i++] = ["access-control-allow-origin", origin as string];
+      entries[i++] = ['access-control-allow-origin', origin as string]
     }
 
     if (needsRate) {
-      entries[i++] = ["ratelimit-remaining", String(rateRemaining ?? 0)];
-      entries[i++] = ["ratelimit-reset", String(rateResetSecs ?? 0)];
+      entries[i++] = ['ratelimit-remaining', String(rateRemaining ?? 0)]
+      entries[i++] = ['ratelimit-reset', String(rateResetSecs ?? 0)]
     }
 
     if (needsRetry) {
-      entries[i++] = ["retry-after", String(retryAfterSecs ?? 0)];
+      entries[i++] = ['retry-after', String(retryAfterSecs ?? 0)]
     }
 
-    return entries;
+    return entries
   }
 
   function terminalHeaders(
@@ -526,37 +482,57 @@ export function createIngressHandler(
     ctx: BakedContext,
     result: BakedIngressResult | null,
   ): [string, string][] {
+    const v = variant | HV_JSON
+    const requestIdHeader = ctx.requestIdHeader
+    const origin = ctx.origin
+    const rateResetSecs =
+      result && result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined
+    const retryAfterSecs =
+      result && result.retryAfterMs > 0 ? secondsFromMs(result.retryAfterMs) : undefined
+
+    const needsRequestId = emitRequestIdHeader && requestIdHeader !== null
+    const needsOrigin =
+      ((v & HV_CORS_SIMPLE) !== 0 || (v & HV_CORS_PREFLIGHT) !== 0) && origin !== null
+    const needsRate = (v & HV_RATE_ACTIVE) !== 0
+    const needsRetry = (v & HV_RATE_LIMITED) !== 0
+
+    // Steady state: no request-id/origin/rate extras — serve the pre-baked
+    // terminal template (JSON + `cache-control: no-store`) directly with zero
+    // per-response array allocation/copy.
+    if (!needsRequestId && !needsOrigin && !needsRate && !needsRetry) {
+      // Frozen-readonly → mutable: the baked terminal template is only read.
+      return terminalTemplates[v & 31] as unknown as [string, string][]
+    }
+
+    // Rare path: extras appended after the baked entries, then `cache-control`.
     const base = responseHeaders(
-      variant | HV_JSON,
-      ctx.requestIdHeader,
-      ctx.origin,
+      v,
+      requestIdHeader,
+      origin,
       result?.rateRemaining,
-      result && result.rateResetMs > 0
-        ? Math.ceil(result.rateResetMs / 1000)
-        : undefined,
-      result && result.retryAfterMs > 0
-        ? Math.ceil(result.retryAfterMs / 1000)
-        : undefined,
-    );
-
-    const out = new Array<[string, string]>(base.length + 1);
-    for (let i = 0; i < base.length; i++) {
-      out[i] = base[i]!;
+      rateResetSecs,
+      retryAfterSecs,
+    )
+
+    const out = new Array<[string, string]>(base.length + 1)
+    let i = 0
+    for (const pair of base) {
+      out[i++] = pair
     }
-    out[base.length] = ["cache-control", "no-store"];
-    return out;
+    out[base.length] = ['cache-control', 'no-store']
+    return out
   }
 
   function terminalResponse(
-    _req: Request,
+    _req: Request | undefined,
     result: BakedIngressResult,
     ctx: BakedContext,
   ): Response | null {
     if (!result.terminal) {
-      return null;
+      return null
     }
 
-    const preflightAllowed = result.isPreflight && result.corsAllowed;
+    const preflightAllowed = result.isPreflight && result.corsAllowed
 
     if (preflightAllowed) {
       return new Response(null, {
@@ -566,31 +542,27 @@ export function createIngressHandler(
           ctx.requestIdHeader,
           ctx.origin,
           result.rateRemaining,
-          result.rateResetMs > 0
-            ? Math.ceil(result.rateResetMs / 1000)
-            : undefined,
-          result.retryAfterMs > 0
-            ? Math.ceil(result.retryAfterMs / 1000)
-            : undefined,
+          result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined,
+          result.retryAfterMs > 0 ? secondsFromMs(result.retryAfterMs) : undefined,
         ),
-      });
+      })
     }
 
-    const status = safeTerminalStatus(result);
+    const status = safeTerminalStatus(result)
 
     const body: Uint8Array =
       result.errorCode === ERROR_CODE_RATE_LIMITED
         ? rateLimitedBody(result.retryAfterMs)
-        : (ERROR_CODE_BODIES[result.errorCode] ?? ERROR_BODIES.internal!);
+        : (ERROR_CODE_BODIES[result.errorCode] ?? ERROR_BODIES.internal ?? EMPTY_BODY)
 
     return new Response(body, {
       status,
       headers: terminalHeaders(result.headerVariant, ctx, result),
-    });
+    })
   }
 
   function errorResponse(
-    _req: Request,
+    _req: Request | undefined,
     result: BakedIngressResult | null,
     status: number,
     code: string,
@@ -598,46 +570,58 @@ export function createIngressHandler(
     ctx: BakedContext,
   ): Response {
     const body =
-      ERROR_BODIES[code] ??
-      encoder.encode(JSON.stringify({ ok: false, error: { code, message } }));
+      ERROR_BODIES[code] ?? encoder.encode(JSON.stringify({ ok: false, error: { code, message } }))
 
     return new Response(body, {
       status,
       headers: terminalHeaders(result?.headerVariant ?? HV_JSON, ctx, result),
-    });
+    })
   }
 
-  function internalErrorResponse(
-    ctx: BakedContext,
-    result?: BakedIngressResult,
-  ): Response {
+  function internalErrorResponse(ctx: BakedContext, result?: BakedIngressResult): Response {
     return new Response(ERROR_BODIES.internal, {
       status: 500,
-      headers: terminalHeaders(
-        result?.headerVariant ?? HV_JSON,
-        ctx,
-        result ?? null,
-      ),
-    });
+      headers: terminalHeaders(result?.headerVariant ?? HV_JSON, ctx, result ?? null),
+    })
   }
 
   function withContentType(
     headers: ReadonlyArray<[string, string]>,
     contentType: string,
   ): [string, string][] {
-    const out = new Array<[string, string]>(headers.length + 1);
-    for (let i = 0; i < headers.length; i++) {
-      out[i] = headers[i]!;
+    const out = new Array<[string, string]>(headers.length + 1)
+    let i = 0
+    for (const pair of headers) {
+      out[i++] = pair
     }
-    out[headers.length] = ["content-type", contentType];
-    return out;
+    out[headers.length] = ['content-type', contentType]
+    return out
   }
 
-  const result = new BakedIngressResult();
+  function zeroCopyResponse(
+    result: BakedIngressResult,
+    _ctx: BakedContext,
+    init: ResponseInit,
+  ): Response {
+    if (currentHandle === null) {
+      // `zeroCopyResponse` must only run inside a live `run()` callback (a
+      // pooled output buffer must be in flight). Called outside `run()` the
+      // result has already been invalidated and `result.bodyJson` is empty —
+      // throw instead of silently serving an empty body.
+      throw new Error(
+        'zeroCopyResponse() can only be called from within a run() callback ' +
+          '(the pooled output buffer is only live during run()).',
+      )
+    }
+    responseBorrowsBuffer = true
+    return pooledBodyResponse(currentHandle, result.bodyJson(false), init, zeroCopyTimeoutMs)
+  }
+
+  const result = new BakedIngressResult()
   const ctx: BakedContext = {
     requestIdHeader: null,
     origin: null,
-  };
+  }
 
   function run<T>(
     req: Request,
@@ -645,98 +629,201 @@ export function createIngressHandler(
     body: Uint8Array | null,
     fn: (result: BakedIngressResult, ctx: BakedContext) => T,
   ): T {
-    const methodKind = METHOD_KIND[req.method] ?? 7;
-    const ridBytes = generateRequestId();
-    const requestIdStr = decoder.decode(ridBytes);
-
-    ctx.requestIdHeader = emitRequestIdHeader ? requestIdStr : null;
-    ctx.origin = headerPlan.cors ? req.headers.get("origin") : null;
-
-    // Gather raw headers as [name, value][] — no binary packing in JS.
-    // handleRequestFullSync packs them internally in Rust synchronously,
-    // eliminating both JS-side encoding and async overhead.
-    const headers: [string, string][] = [];
-    const h = req.headers;
-
-    if (headerPlan.cookie) {
-      const v = h.get("cookie");
-      if (v !== null && v.length <= MAX_COOKIE_HEADER_BYTES) {
-        headers.push(["cookie", v]);
-      }
-    }
+    const startedAt = logger ? performance.now() : 0
+    const methodKind = METHOD_KIND[req.method] ?? METHOD_KIND_UNKNOWN
+    const ridBytes = generateRequestId()
+    const requestIdStr = needRequestIdString ? decoder.decode(ridBytes) : ''
 
-    if (headerPlan.cors) {
-      const originV = h.get("origin");
-      if (originV !== null && originV.length <= MAX_SMALL_HEADER_BYTES) {
-        headers.push(["origin", originV]);
-      }
+    ctx.requestIdHeader = emitRequestIdHeader ? requestIdStr : null
+    ctx.origin = headerPlan.cors ? req.headers.get('origin') : null
 
-      if (methodKind === 6) {
-        const acrm = h.get("access-control-request-method");
-        if (acrm !== null && acrm.length <= MAX_SMALL_HEADER_BYTES) {
-          headers.push(["access-control-request-method", acrm]);
-        }
+    runtime.onRequest?.(req, requestIdStr, ip)
 
-        const acrh = h.get("access-control-request-headers");
-        if (acrh !== null && acrh.length <= MAX_SMALL_HEADER_BYTES) {
-          headers.push(["access-control-request-headers", acrh]);
-        }
-      }
-    }
+    const ipStr = ip ?? EMPTY_IP
 
-    if (headerPlan.proxy) {
-      const xff = h.get("x-forwarded-for");
-      if (xff !== null && xff.length <= MAX_XFF_HEADER_BYTES) {
-        headers.push(["x-forwarded-for", xff]);
-      }
+    // Pack the request frame in JS (reusing the fast path's zero-alloc packer
+    // discipline) and drive the same native core as `handleRequestPacked`.
+    // This removes the per-request `[name, value][]` header marshaling + napi
+    // `Vec<Vec<String>>` and the request-id string re-encode that the
+    // full_sync family paid on every request. The response wire format is
+    // unchanged because both entries run the identical `handle_packed` core.
+    let handle: PooledBuffer | null = null
+    currentHandle = null
+    responseBorrowsBuffer = false
 
-      const xri = h.get("x-real-ip");
-      if (xri !== null && xri.length <= MAX_SMALL_HEADER_BYTES) {
-        headers.push(["x-real-ip", xri]);
-      }
-    }
+    try {
+      // Pack the request frame (inside the try: an unexpected packing failure
+      // is reported by the escaping-error catch below — it must never leak the
+      // request without accounting). `ctx.origin` was already fetched once
+      // above, so pass it in to avoid a second `req.headers.get('origin')`
+      // native→JS string conversion on the hot path.
+      const packedHeaders = gatherRawHeadersPacked(req, headerPlan, methodKind, ctx.origin)
+      // Minimal processing: when the native pipeline cannot read the URL/IP
+      // (see `urlNeeded`/`ipNeeded`), pass an empty URL / omit the IP so we
+      // skip the per-request JS UTF-8 encode entirely (the frame still carries
+      // a valid 0-length section the native bounds-checks).
+      const packUrl = urlNeeded ? req.url : ''
+      const packIp = ipNeeded ? ip : undefined
 
-    if (headerPlan.proto) {
-      const xfp = h.get("x-forwarded-proto");
-      if (xfp !== null && xfp.length <= MAX_SMALL_HEADER_BYTES) {
-        headers.push(["x-forwarded-proto", xfp]);
-      }
-    }
+      try {
+        // Acquire inside the try: pool exhaustion (maxInFlight) becomes a 500
+        // via setInternalError — never an uncaught exception out of run().
+        handle = outputPool.acquire(outputBufferSize)
+        currentHandle = handle
+
+        // Write into the pooled buffer — no per-request allocation. Bun
+        // PRIMARY: the raw-components C-ABI (`castrum_ingress_handle_components`)
+        // passes `url`/`ip` as `bun:ffi` `cstring` args — the engine transcodes
+        // the JS strings to call-scoped UTF-8 in-engine, so we skip the JS
+        // frame assembly + `Buffer.write` encode for the URL/IP (same wire
+        // format: both paths run the shared `handle_components` core). Falls
+        // back to the packed frame (FFI or napi) on any failure / stale addon.
+        // If an ffi call throws (native reported 0 = error, or a panic
+        // `panic_guard` contained), re-dispatch through napi once and, after
+        // repeated failures, permanently disable ffi for this handler.
+        let written: number
+        if (
+          bunFFI !== null &&
+          ingressPtr !== 0 &&
+          !ffiDisabled &&
+          typeof bunFFI.ingressHandleComponents === 'function'
+        ) {
+          try {
+            written = bunFFI.ingressHandleComponents(
+              ingressPtr,
+              methodKind,
+              packUrl,
+              packIp ?? '',
+              ridBytes,
+              packedHeaders,
+              body,
+              handle.buffer,
+            )
+            ffiFailures = 0
+          } catch {
+            ffiFailures++
+            if (ffiFailures >= MAX_FFI_FAILURES) {
+              ffiDisabled = true
+            }
+            // 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.
+            const input = inputPacker.packParts(
+              methodKind,
+              packUrl,
+              packIp,
+              ridBytes,
+              packedHeaders,
+            )
+            written = handler.handleRequestPacked(input, body, handle.buffer)
+          }
+        } else if (bunFFI !== null && ingressPtr !== 0 && !ffiDisabled) {
+          const input = inputPacker.packParts(
+            methodKind,
+            packUrl,
+            packIp,
+            ridBytes,
+            packedHeaders,
+          )
+          try {
+            written = bunFFI.ingressHandlePacked(ingressPtr, input, body, handle.buffer)
+            ffiFailures = 0
+          } catch {
+            ffiFailures++
+            if (ffiFailures >= MAX_FFI_FAILURES) {
+              ffiDisabled = true
+            }
+            // 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)
+          }
+        } else {
+          const input = inputPacker.packParts(
+            methodKind,
+            packUrl,
+            packIp,
+            ridBytes,
+            packedHeaders,
+          )
+          written = handler.handleRequestPacked(input, body, handle.buffer)
+        }
 
-    const ipStr = ip ?? EMPTY_IP;
+        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))
+      } catch (err) {
+        result.setInternalError()
+        const error = err instanceof Error ? err : new Error(String(err))
+        runtime.onError?.(req, requestIdStr, error)
+        logger?.error({
+          requestId: requestIdStr,
+          method: req.method,
+          path: pathForLog(req),
+          code: 'internal',
+          message: error.message,
+        })
+      }
 
-    try {
-      const outputBuf = handler.handleRequestFullSync(
-        methodKind,
-        req.url,
-        ipStr,
-        requestIdStr,
-        headers,
-        body,
-        outputBufferSize,
-      );
-
-      const outputView = new DataView(
-        outputBuf.buffer,
-        outputBuf.byteOffset,
-        outputBuf.byteLength,
-      );
-
-      result.refresh(outputBuf, body ?? EMPTY_BODY, outputView);
+      try {
+        const out = fn(result, ctx)
+        // The ingress result is invalidated when run() returns, so an async
+        // callback would observe a stale/zeroed result — reject it up front
+        // (parity with the fast path / createIngressSync).
+        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,
+          })
+        }
+        return out
+      } finally {
+        result.invalidate()
+        ctx.requestIdHeader = null
+        ctx.origin = null
+      }
     } catch (err) {
-      result.setInternalError();
-    }
-
-    try {
-      const out = fn(result, ctx);
-      if (out instanceof Response) {
-        runtime.onResponse?.(req, result, out.status, requestIdStr);
+      // An unexpected error escaped run() after onRequest (a packing failure
+      // before the native call, or a throwing route callback). Report it so
+      // request accounting completes (metrics in_flight must not leak), then
+      // rethrow for the caller. The native-failure path above does NOT rethrow,
+      // so this fires at most once per request.
+      if (responseBorrowsBuffer && handle !== null) {
+        // `zeroCopyResponse` was called but the Response never escaped (the
+        // callback threw): the stream that would release the pooled buffer was
+        // never delivered. Release it here so the buffer isn't stuck in flight
+        // forever.
+        handle.release()
+        handle = null
+        responseBorrowsBuffer = false
       }
-      return out;
+      const error = err instanceof Error ? err : new Error(String(err))
+      runtime.onError?.(req, requestIdStr, error)
+      logger?.error({
+        requestId: requestIdStr,
+        method: req.method,
+        path: pathForLog(req),
+        code: 'internal',
+        message: error.message,
+      })
+      throw error
     } finally {
-      result.invalidate();
-      ctx.requestIdHeader = null;
-      ctx.origin = null;
+      // A zero-copy Response owns the handle until its body is consumed; in
+      // every other case (copy mode, terminal/error responses) the buffer is
+      // safe to return to the pool immediately.
+      if (handle !== null && !responseBorrowsBuffer) {
+        handle.release()
+      }
+      currentHandle = null
     }
   }
 
@@ -748,455 +835,6 @@ export function createIngressHandler(
     errorResponse,
     internalErrorResponse,
     withContentType,
-  };
-}
-
-// ── Route-handler factories ───────────────────────────────────────
-export interface BakedHandlerOptions {
-  /** Resolve the client IP from the server object (e.g. `srv.requestIP`). */
-  getIp?: (req: Request, srv: unknown) => string | undefined;
-  /** Copy body slices instead of sharing the native buffer. Default: true (safe). */
-  copyBody?: boolean;
-  /** Maximum request body bytes for write/echo handlers. Default: 1 MiB. */
-  maxBodyBytes?: number;
-  /** Fallback handler used for write error paths. Defaults to the write ingress. */
-  fallback?: OptimizedIngressHandler;
-}
-
-function resolveIp(
-  req: Request,
-  srv: unknown,
-  opts: BakedHandlerOptions,
-): string | undefined {
-  return opts.getIp ? opts.getIp(req, srv) : undefined;
-}
-
-/** Pre-baked GET read handler: returns the ingress body JSON on success. */
-export function readHandler(
-  ingress: OptimizedIngressHandler,
-  opts: BakedHandlerOptions = {},
-): (req: Request, srv?: unknown) => Response {
-  const copyBody = opts.copyBody !== false;
-
-  return (req, srv) =>
-    ingress.run<Response>(req, resolveIp(req, srv, opts), null, (result, ctx) => {
-      const terminal = ingress.terminalResponse(req, result, ctx);
-      if (terminal) return terminal;
-
-      if (result.bodyTruncated) {
-        return ingress.internalErrorResponse(ctx, result);
-      }
-
-      return new Response(result.bodyJson(copyBody), {
-        status: 200,
-        headers: ingress.responseHeaders(
-          result.headerVariant,
-          ctx.requestIdHeader,
-          ctx.origin,
-          result.rateRemaining,
-          result.rateResetMs > 0
-            ? Math.ceil(result.rateResetMs / 1000)
-            : undefined,
-        ),
-      });
-    });
-}
-
-/** Pre-baked HEAD read handler: headers only, no body. */
-export function headHandler(
-  ingress: OptimizedIngressHandler,
-  opts: BakedHandlerOptions = {},
-): (req: Request, srv?: unknown) => Response {
-  return (req, srv) =>
-    ingress.run<Response>(req, resolveIp(req, srv, opts), null, (result, ctx) => {
-      const terminal = ingress.terminalResponse(req, result, ctx);
-      if (terminal) return terminal;
-
-      if (result.bodyTruncated) {
-        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
-            ? Math.ceil(result.rateResetMs / 1000)
-            : undefined,
-        ),
-      });
-    });
-}
-
-/**
- * Pre-baked JSON-write handler (POST/PUT/PATCH): enforces Content-Type,
- * content-length/body-size limits, JSON validity and (optionally) schema
- * validation, then returns the ingress body JSON on success.
- */
-export function jsonWriteHandler(
-  ingress: OptimizedIngressHandler,
-  opts: BakedHandlerOptions = {},
-): (req: Request, srv?: unknown) => Promise<Response> {
-  const maxBodyBytes = opts.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
-  const fallback = opts.fallback ?? ingress;
-  const copyBody = opts.copyBody !== false;
-
-  return async (req, srv) => {
-    const ip = resolveIp(req, srv, opts);
-
-    const contentType = req.headers.get("content-type") ?? "";
-    if (!contentType.includes("application/json")) {
-      return fallback.run(req, ip, null, (result, ctx) => {
-        const terminal = fallback.terminalResponse(req, result, ctx);
-        if (terminal) return terminal;
-
-        return fallback.errorResponse(
-          req,
-          result,
-          415,
-          "unsupported_media_type",
-          "Content-Type must be application/json",
-          ctx,
-        );
-      });
-    }
-
-    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,
-        );
-      });
-    }
-
-    let bodyBytes: Uint8Array;
-    try {
-      bodyBytes = new Uint8Array(await req.arrayBuffer());
-    } catch {
-      return fallback.run(req, ip, null, (result, ctx) => {
-        const terminal = fallback.terminalResponse(req, result, ctx);
-        if (terminal) return terminal;
-
-        return fallback.errorResponse(
-          req,
-          result,
-          400,
-          "bad_request",
-          "Unable to read request body",
-          ctx,
-        );
-      });
-    }
-
-    if (bodyBytes.byteLength > 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,
-        );
-      });
-    }
-
-    return ingress.run(req, ip, bodyBytes, (result, ctx) => {
-      const terminal = ingress.terminalResponse(req, result, ctx);
-      if (terminal) return terminal;
-
-      if (result.bodyTruncated) {
-        return ingress.internalErrorResponse(ctx, result);
-      }
-
-      if (!result.bodyValidJson) {
-        return ingress.errorResponse(
-          req,
-          result,
-          400,
-          "invalid_json",
-          "Invalid JSON body",
-          ctx,
-        );
-      }
-
-      if (!result.schemaValid) {
-        return ingress.errorResponse(
-          req,
-          result,
-          422,
-          "schema_validation_failed",
-          "Request body failed schema validation",
-          ctx,
-        );
-      }
-
-      return new Response(result.bodyJson(copyBody), {
-        status: 200,
-        headers: ingress.responseHeaders(
-          result.headerVariant,
-          ctx.requestIdHeader,
-          ctx.origin,
-          result.rateRemaining,
-          result.rateResetMs > 0
-            ? Math.ceil(result.rateResetMs / 1000)
-            : undefined,
-        ),
-      });
-    });
-  };
-}
-
-/**
- * Pre-baked echo handler: streams the request body back with the client's
- * Content-Type, bounded by `maxBodyBytes`.
- */
-export function echoHandler(
-  ingress: OptimizedIngressHandler,
-  opts: BakedHandlerOptions = {},
-): (req: Request, srv?: unknown) => Promise<Response> {
-  const maxBodyBytes = opts.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
-
-  return async (req, srv) => {
-    const ip = resolveIp(req, srv, opts);
-
-    const prep = ingress.run<{
-      terminal?: Response;
-      headers?: ReadonlyArray<[string, string]>;
-    }>(req, ip, null, (result, ctx) => {
-      const terminal = ingress.terminalResponse(req, result, ctx);
-      if (terminal) return { terminal };
-
-      if (result.bodyTruncated) {
-        return { terminal: ingress.internalErrorResponse(ctx, result) };
-      }
-
-      const hv = result.headerVariant & ~HV_JSON;
-
-      return {
-        headers: ingress.responseHeaders(
-          hv,
-          ctx.requestIdHeader,
-          ctx.origin,
-          result.rateRemaining,
-          result.rateResetMs > 0
-            ? Math.ceil(result.rateResetMs / 1000)
-            : undefined,
-        ),
-      };
-    });
-
-    if (prep.terminal) return prep.terminal;
-
-    const baseHeaders: ReadonlyArray<[string, string]> = prep.headers ?? [];
-
-    const requestedContentType =
-      req.headers.get("content-type") ?? "application/octet-stream";
-
-    const contentLengthHeader = req.headers.get("content-length");
-    const contentLength =
-      contentLengthHeader === null ? NaN : Number(contentLengthHeader);
-
-    if (Number.isFinite(contentLength)) {
-      if (contentLength > maxBodyBytes) {
-        return new Response(ERROR_BODIES.body_too_large, {
-          status: 413,
-          headers: ingress.withContentType(baseHeaders, "application/json"),
-        });
-      }
-
-      if (contentLength <= 0 || req.body === null) {
-        return new Response(null, {
-          status: 200,
-          headers: ingress.withContentType(baseHeaders, requestedContentType),
-        });
-      }
-
-      return new Response(req.body, {
-        status: 200,
-        headers: ingress.withContentType(baseHeaders, requestedContentType),
-      });
-    }
-
-    try {
-      const bodyBytes = new Uint8Array(await req.arrayBuffer());
-
-      if (bodyBytes.byteLength > maxBodyBytes) {
-        return new Response(ERROR_BODIES.body_too_large, {
-          status: 413,
-          headers: ingress.withContentType(baseHeaders, "application/json"),
-        });
-      }
-
-      return new Response(bodyBytes.byteLength > 0 ? bodyBytes : null, {
-        status: 200,
-        headers: ingress.withContentType(baseHeaders, requestedContentType),
-      });
-    } catch {
-      return new Response(ERROR_BODIES.bad_request, {
-        status: 400,
-        headers: ingress.withContentType(baseHeaders, "application/json"),
-      });
-    }
-  };
-}
-
-/** Pre-baked fallback handler: 404 for unmatched routes / OPTIONS. */
-export function fallbackHandler(
-  ingress: OptimizedIngressHandler,
-  opts: BakedHandlerOptions = {},
-): (req: Request, srv?: unknown) => Response {
-  return (req, srv) =>
-    ingress.run<Response>(req, resolveIp(req, srv, opts), null, (result, ctx) => {
-      const terminal = ingress.terminalResponse(req, result, ctx);
-      if (terminal) return terminal;
-
-      return ingress.errorResponse(
-        req,
-        result,
-        404,
-        "not_found",
-        "Not found",
-        ctx,
-      );
-    });
-}
-
-// ── Bun.serve builder ─────────────────────────────────────────────
-export interface BakedRoute {
-  /** Wires GET + HEAD read handlers. */
-  read?: OptimizedIngressHandler;
-  /** Wires POST/PUT/PATCH JSON-write handlers (and OPTIONS fallback). */
-  write?: OptimizedIngressHandler;
-  /** Wires a POST echo handler. */
-  echo?: OptimizedIngressHandler;
-  /** Wires a GET read handler (cookies-style route). */
-  cookies?: OptimizedIngressHandler;
-  /** Overrides `maxBodyBytes` for this route's write/echo handlers. */
-  maxBodyBytes?: number;
-}
-
-export interface CreateIngressServerOptions {
-  port: number;
-  hostname?: string;
-  idleTimeout?: number;
-  maxRequestBodySize?: number;
-  reusePort?: boolean;
-  copyBody?: boolean;
-  getIp?: (req: Request, srv: unknown) => string | undefined;
-  routes: Record<string, BakedRoute>;
-  fallback?: OptimizedIngressHandler;
-}
-
-export interface BakedServer {
-  server: ReturnType<typeof Bun.serve>;
-  stop(): void;
-  port: number;
-}
-
-/** Build a Bun.serve config from pre-baked route handlers. */
-export function createIngressServer(
-  options: CreateIngressServerOptions,
-): BakedServer {
-  const baseOpts: BakedHandlerOptions = {
-    getIp: options.getIp,
-    copyBody: options.copyBody,
-  };
-
-  const serverRoutes: Record<string, Record<string, unknown>> = {};
-
-  for (const [path, spec] of Object.entries(options.routes)) {
-    const routeOpts: BakedHandlerOptions = {
-      ...baseOpts,
-      maxBodyBytes: spec.maxBodyBytes,
-    };
-    const methods: Record<string, unknown> = {};
-
-    if (spec.read) {
-      methods.GET = readHandler(spec.read, routeOpts);
-      methods.HEAD = headHandler(spec.read, routeOpts);
-    }
-
-    if (spec.write) {
-      const writeOpts: BakedHandlerOptions = {
-        ...routeOpts,
-        fallback: options.fallback ?? spec.write,
-      };
-      methods.POST = jsonWriteHandler(spec.write, writeOpts);
-      methods.PUT = jsonWriteHandler(spec.write, writeOpts);
-      methods.PATCH = jsonWriteHandler(spec.write, writeOpts);
-      if (options.fallback) {
-        methods.OPTIONS = fallbackHandler(options.fallback, routeOpts);
-      }
-    }
-
-    if (spec.echo) {
-      methods.POST = echoHandler(spec.echo, routeOpts);
-    }
-
-    if (spec.cookies) {
-      methods.GET = readHandler(spec.cookies, routeOpts);
-    }
-
-    serverRoutes[path] = methods;
-  }
-
-  const serverOptions: Record<string, unknown> = {
-    hostname: options.hostname ?? "0.0.0.0",
-    port: options.port,
-    idleTimeout: options.idleTimeout ?? 30,
-    routes: serverRoutes,
-  };
-
-  if (options.maxRequestBodySize !== undefined) {
-    serverOptions.maxRequestBodySize = options.maxRequestBodySize;
-  }
-  if (options.reusePort) {
-    serverOptions.reusePort = true;
+    zeroCopyResponse,
   }
-  if (options.fallback) {
-    serverOptions.fetch = fallbackHandler(options.fallback, baseOpts);
-  }
-
-  let server: ReturnType<typeof Bun.serve>;
-  try {
-    server = Bun.serve(serverOptions as any);
-  } catch (err) {
-    if (options.reusePort) {
-      delete serverOptions.reusePort;
-      server = Bun.serve(serverOptions as any);
-    } else {
-      throw err;
-    }
-  }
-
-  return {
-    server,
-    stop: () => {
-      try {
-        server.stop(true);
-      } catch {
-        // already stopped
-      }
-    },
-    port: options.port,
-  };
 }