castrum 0.7.0 → 0.9.0

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

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

@@ -0,0 +1,38 @@
+// src/ingress/routes/common.ts — Shared route-handler options + helpers.
+
+import type { OptimizedIngressHandler } from '../types'
+
+/** Options accepted by the pre-baked route 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
+  /**
+   * Overall deadline (ms) for reading the request body. Default: 30s
+   * (`DEFAULT_BODY_TIMEOUT_MS`). Set `0` to disable. Protects against
+   * slowloris / trickling bodies.
+   */
+  bodyTimeoutMs?: number
+  /** Fallback handler used for write error paths. Defaults to the write ingress. */
+  fallback?: OptimizedIngressHandler
+  /**
+   * When true, route the JSON-validity fallback check through the higher-order
+   * loader (`loader("jsonValid")`) instead of the direct native call —
+   * exercising the loader's dispatch + counters on the real request path.
+   * Default: false (the direct call is marginally faster for a single request;
+   * the loader pays off for same-tick bursts / bulk work, see src/integration/batch.ts).
+   */
+  enableLoader?: boolean
+}
+
+/** Resolve the client IP for a route request via the configured getter. */
+export function resolveIp(
+  req: Request,
+  srv: unknown,
+  opts: BakedHandlerOptions,
+): string | undefined {
+  return opts.getIp ? opts.getIp(req, srv) : undefined
+}

package/src/ingress/routes/delete.ts

@@ -0,0 +1,14 @@
+// src/ingress/routes/delete.ts — Pre-baked DELETE handler.
+
+import { readHandler } from './read'
+
+/**
+ * Pre-baked DELETE handler: DELETE is a read-style method (no request body is
+ * read), so it shares the exact pipeline flow of {@link readHandler} — it
+ * returns the ingress body JSON on success and the terminal/error responses
+ * otherwise. Reusing the read factory keeps the two handlers byte-identical
+ * and avoids a copy-pasted variant.
+ *
+ * Wire it via the `delete` key of a `BakedRoute` (see `createIngressServer`).
+ */
+export const deleteHandler = readHandler

package/src/ingress/routes/echo.ts

@@ -0,0 +1,107 @@
+// src/ingress/routes/echo.ts — Pre-baked echo handler.
+
+import type { OptimizedIngressHandler } from '../types'
+import { resolveIp, type BakedHandlerOptions } from './common'
+import { DEFAULT_MAX_BODY_BYTES, DEFAULT_BODY_TIMEOUT_MS, secondsFromMs } from '../shared'
+import { HV_JSON } from '../constants'
+import { ERROR_BODIES } from '../response/error-bodies'
+import { readBodyWithLimit } from '../body'
+
+/**
+ * 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
+  // Non-zero default: protect against slowloris / trickling bodies.
+  const bodyTimeoutMs = opts.bodyTimeoutMs ?? DEFAULT_BODY_TIMEOUT_MS
+
+  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 ? secondsFromMs(result.rateResetMs) : 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 {
+      // Chunked / unknown-length body: stream-read with the limit enforced
+      // WHILE reading and an overall deadline — never fully buffer an
+      // oversized or trickling body before rejecting it.
+      const bodyBytes = await readBodyWithLimit(req, maxBodyBytes, true, bodyTimeoutMs)
+
+      return new Response(bodyBytes.byteLength > 0 ? bodyBytes : null, {
+        status: 200,
+        headers: ingress.withContentType(baseHeaders, requestedContentType),
+      })
+    } catch (err) {
+      const code = (err as { code?: string } | null)?.code
+      const isTooLarge = code === 'BODY_TOO_LARGE'
+      const isTimeout = code === 'REQUEST_TIMEOUT'
+
+      return new Response(
+        isTooLarge
+          ? ERROR_BODIES.body_too_large
+          : isTimeout
+            ? ERROR_BODIES.request_timeout
+            : ERROR_BODIES.bad_request,
+        {
+          status: isTooLarge ? 413 : isTimeout ? 408 : 400,
+          headers: ingress.withContentType(baseHeaders, 'application/json'),
+        },
+      )
+    }
+  }
+}

package/src/ingress/routes/fallback.ts

@@ -0,0 +1,23 @@
+// src/ingress/routes/fallback.ts — Pre-baked fallback handler.
+
+import type { BakedContext, OptimizedIngressHandler } from '../types'
+import type { BakedIngressResult } from '../decode/baked-result'
+import { resolveIp, type BakedHandlerOptions } from './common'
+
+/**
+ * Pre-baked fallback handler: 404 for unmatched routes / OPTIONS.
+ */
+export function fallbackHandler(
+  ingress: OptimizedIngressHandler,
+  opts: BakedHandlerOptions = {},
+): (req: Request, srv?: unknown) => Response {
+  // Result→Response callback, built ONCE per handler (no per-request closure).
+  const respond = (result: BakedIngressResult, ctx: BakedContext): Response => {
+    const terminal = ingress.terminalResponse(undefined, result, ctx)
+    if (terminal) return terminal
+
+    return ingress.errorResponse(undefined, result, 404, 'not_found', 'Not found', ctx)
+  }
+
+  return (req, srv) => ingress.run<Response>(req, resolveIp(req, srv, opts), null, respond)
+}

package/src/ingress/routes/head.ts

@@ -0,0 +1,37 @@
+// src/ingress/routes/head.ts — Pre-baked HEAD read handler.
+
+import type { BakedContext, OptimizedIngressHandler } from '../types'
+import type { BakedIngressResult } from '../decode/baked-result'
+import { resolveIp, type BakedHandlerOptions } from './common'
+import { secondsFromMs } from '../shared'
+
+/**
+ * Pre-baked HEAD read handler: headers only, no body.
+ */
+export function headHandler(
+  ingress: OptimizedIngressHandler,
+  opts: BakedHandlerOptions = {},
+): (req: Request, srv?: unknown) => Response {
+  // Result→Response callback, built ONCE per handler (no per-request closure).
+  const respond = (result: BakedIngressResult, ctx: BakedContext): Response => {
+    const terminal = ingress.terminalResponse(undefined, 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 ? secondsFromMs(result.rateResetMs) : undefined,
+      ),
+    })
+  }
+
+  return (req, srv) => ingress.run<Response>(req, resolveIp(req, srv, opts), null, respond)
+}

package/src/ingress/routes/index.ts

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

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

@@ -0,0 +1,153 @@
+// src/ingress/routes/json-write.ts — Pre-baked JSON-write handler
+// (POST/PUT/PATCH).
+
+import type { OptimizedIngressHandler } from '../types'
+import { resolveIp, type BakedHandlerOptions } from './common'
+import { DEFAULT_MAX_BODY_BYTES, DEFAULT_BODY_TIMEOUT_MS, secondsFromMs } from '../shared'
+import { readBodyWithLimit } from '../body'
+import { getAddon } from '../../native'
+import { getBunFFI } from '../../native/ffi'
+
+/**
+ * Zero-DOM JSON-validity check — the same native fast path the ingress
+ * pipeline uses internally (`json_valid_bytes`).
+ *
+ * Used by `jsonWriteHandler` as a fallback when the pipeline skipped JSON
+ * validation because neither `requireJsonBody` nor a `schema` is configured
+ * on the ingress (see the `bodyValidJson` handling in the route).
+ *
+ * bun:ffi is primary on Bun; the napi addon is the fallback (Node, forced
+ * `CASTRUM_FFI_MODE=napi`, or a failed ffi self-test).
+ */
+function isValidJsonBytes(bytes: Uint8Array): boolean {
+  const ffi = getBunFFI()
+  return ffi ? ffi.jsonValid(bytes) : getAddon().jsonValid(bytes)
+}
+
+/**
+ * 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
+  // Non-zero default: protect against slowloris / trickling bodies. Set
+  // `bodyTimeoutMs: 0` to disable.
+  const bodyTimeoutMs = opts.bodyTimeoutMs ?? DEFAULT_BODY_TIMEOUT_MS
+
+  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 {
+      // Stream-read with the limit enforced WHILE reading — a body that
+      // exceeds maxBodyBytes is rejected as soon as the limit is crossed,
+      // never fully buffered first.
+      bodyBytes = await readBodyWithLimit(req, maxBodyBytes, true, bodyTimeoutMs)
+    } catch (err) {
+      const code = (err as { code?: string } | null)?.code
+      const isTooLarge = code === 'BODY_TOO_LARGE'
+      return fallback.run(req, ip, null, (result, ctx) => {
+        const terminal = fallback.terminalResponse(req, result, ctx)
+        if (terminal) return terminal
+
+        return fallback.errorResponse(
+          req,
+          result,
+          isTooLarge ? 413 : 408,
+          isTooLarge ? 'body_too_large' : 'request_timeout',
+          isTooLarge ? 'Request body is too large' : 'Request body read timed out',
+          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)
+      }
+
+      // `bodyValidJson`/`schemaValid` are only computed when the pipeline ran
+      // JSON validation — i.e. when `requireJsonBody` is set or a `schema` is
+      // configured on the ingress. When `bodyValidJson` is false here,
+      // validation was skipped entirely (a genuine validation failure already
+      // short-circuits as a terminal 400 above). In that case enforce validity
+      // with the same zero-DOM native check, and schema validation trivially
+      // passes because no schema was configured (had one been, the pipeline
+      // would have run and set the flags).
+      if (result.bodyValidJson) {
+        if (!result.schemaValid) {
+          return ingress.errorResponse(
+            req,
+            result,
+            422,
+            'schema_validation_failed',
+            'Request body failed schema validation',
+            ctx,
+          )
+        }
+      } else if (!isValidJsonBytes(bodyBytes)) {
+        return ingress.errorResponse(req, result, 400, 'invalid_json', 'Invalid JSON body', ctx)
+      }
+
+      const init: ResponseInit = {
+        status: 200,
+        headers: ingress.responseHeaders(
+          result.headerVariant,
+          ctx.requestIdHeader,
+          ctx.origin,
+          result.rateRemaining,
+          result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined,
+        ),
+      }
+
+      return copyBody
+        ? new Response(result.bodyJson(true), init)
+        : ingress.zeroCopyResponse(result, ctx, init)
+    })
+  }
+}

package/src/ingress/routes/options.ts

@@ -0,0 +1,36 @@
+// src/ingress/routes/options.ts — Pre-baked OPTIONS handler (CORS preflight).
+
+import type { OptimizedIngressHandler } from '../types'
+import { resolveIp, type BakedHandlerOptions } from './common'
+import { secondsFromMs } from '../shared'
+
+/**
+ * Pre-baked OPTIONS handler: serves the native pipeline's CORS preflight
+ * decision — 204 when the preflight is allowed, 403 (terminal) when denied —
+ * and a plain 204 for non-preflight OPTIONS.
+ *
+ * `createIngressServer` wires this for EVERY route that has a handler, so
+ * read-only routes also answer preflights (previously OPTIONS only reached the
+ * pipeline on write routes that also configured a fallback).
+ */
+export function optionsHandler(
+  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 new Response(null, {
+        status: 204,
+        headers: ingress.responseHeaders(
+          result.headerVariant,
+          ctx.requestIdHeader,
+          ctx.origin,
+          result.rateRemaining,
+          result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined,
+        ),
+      })
+    })
+}