castrum 0.7.0 → 0.9.1

package/src/ingress/server.ts

@@ -0,0 +1,475 @@
+// src/ingress/server.ts — Bun.serve builder over pre-baked route handlers.
+
+import { isBun } from '../shared/runtime'
+import {
+  deleteHandler,
+  echoHandler,
+  fallbackHandler,
+  headHandler,
+  jsonWriteHandler,
+  optionsHandler,
+  readHandler,
+} from './routes'
+import type { BakedHandlerOptions } from './routes/common'
+import { nativeResponderRoute } from './routes/responder'
+import type { NativeResponder, OptimizedIngressHandler, TerminalStyle } from './types'
+
+/** Server-level default for the socket request-body cap (16 MiB). */
+export const DEFAULT_MAX_REQUEST_BODY_SIZE = 16 * 1024 * 1024
+
+/** A raw web-standard route handler (`Request` → `Response`), e.g. the
+ *  health/metrics probes (`livenessHandler`, `readinessHandler`,
+ *  `healthHandler`, `metricsHandler`). Accepted as `BakedRoute.read` and
+ *  served for GET directly, outside the ingress pipeline. The optional third
+ *  arg carries the matched dynamic path params (`:param`/`*`) on the Node
+ *  adapter (Bun's native router handles matching; the ingress pipeline does
+ *  not echo params in its response). */
+export type RouteHandler = (
+  req: Request,
+  srv?: unknown,
+  params?: Record<string, string>,
+) => Response | Promise<Response>
+
+/** Route spec for the Bun.serve builder. */
+export interface BakedRoute {
+  /**
+   * Wires GET + HEAD read handlers. Accepts an optimized ingress handler OR a
+   * raw `RouteHandler` function (health/metrics probes are raw — see
+   * src/ingress/health.ts). A raw handler is served for GET only.
+   */
+  read?: OptimizedIngressHandler | RouteHandler
+  /** 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
+  /** Wires a DELETE read-style handler. */
+  delete?: OptimizedIngressHandler
+  /**
+   * A JS responder route: the native pipeline owns parse/validate/CORS/
+   * rate-limit + terminal rejections; the responder builds the 2xx body
+   * (async OK). Wired for `methods` (default GET). Built by
+   * `nativeResponderRoute` (src/ingress/routes/responder.ts).
+   */
+  responder?: {
+    /** The route's compiled native `IngressInner`. */
+    ingress: OptimizedIngressHandler
+    /** The JS 2xx builder. */
+    handler: NativeResponder
+    /** HTTP methods to wire (default `['GET']`). */
+    methods?: ReadonlyArray<string>
+    /** Terminal envelope style (`'castrum'` default / `'ignex'`). */
+    terminalStyle?: TerminalStyle
+    /** Read the body for native validation (default false — framework owns it). */
+    readBody?: boolean
+  }
+  /** Overrides `maxBodyBytes` for this route's write/echo handlers. */
+  maxBodyBytes?: number
+  /**
+   * Overall deadline (ms) for reading the request body on this route's
+   * write/echo handlers. Default: 30_000 (`DEFAULT_BODY_TIMEOUT_MS`).
+   * Set 0 to disable.
+   */
+  bodyTimeoutMs?: number
+}
+
+/** RFC 6455 handshake values returned by `CreateIngressServerOptions.upgrade`. */
+export interface NodeUpgradeHandshake {
+  /** `Sec-WebSocket-Accept` value (compute via `rust.text.wsAcceptKey`). */
+  accept: string
+  /** Optional negotiated subprotocol (`Sec-WebSocket-Protocol`). */
+  protocol?: string
+}
+
+/** Options for {@link createIngressServer}. */
+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
+  /**
+   * Invoked when an unhandled error escapes a request handler (currently wired
+   * on the Node adapter; the Bun path uses runtime.onResponse). Never throws —
+   * hook failures are swallowed.
+   */
+  onError?: (info: { error: Error; request?: Request }) => void
+  /** Node adapter only: ms to receive the complete request (headers + body).
+   *  Guards slowloris/trickling requests. Default: 30_000. */
+  requestTimeoutMs?: number
+  /** Node adapter only: ms to receive the request headers. Default: 30_000. */
+  headersTimeoutMs?: number
+  /** Node adapter only: max requests per keep-alive socket before Node forces
+   *  a fresh connection (bounds long-lived socket reuse). Default: 1000. */
+  maxRequestsPerSocket?: number
+  /** Node adapter only: optional WebSocket upgrade handler. Return the RFC 6455
+   *  handshake values (see {@link NodeUpgradeHandshake}) to complete the
+   *  handshake on the hijacked socket; return null/undefined to decline the
+   *  upgrade. Ignored by the Bun server. (`createWebSocketUpgrade` is Bun-only
+   *  — Node's Response cannot carry a 101.) */
+  upgrade?: (req: Request) => NodeUpgradeHandshake | null | undefined
+  /** Node adapter only: called after a WebSocket upgrade handshake completes
+   *  (the 101 response was accepted), with the hijacked socket so the caller
+   *  can attach a frame codec/message loop (e.g. the `ws` library). Ignored by
+   *  the Bun server. */
+  onUpgrade?: (socket: import('node:stream').Duplex, req: unknown, head: Buffer) => void
+}
+
+/**
+ * Minimal surface of the running server that castrum relies on.
+ *
+ * This is intentionally NOT `ReturnType<typeof Bun.serve>` so that the public
+ * types stay runtime-agnostic — Node.js TypeScript consumers don't need
+ * `@types/bun` just to import castrum's types. Bun's server exposes far more
+ * fields; treat the handle as opaque.
+ */
+export interface ServerHandle {
+  /** The port the server is bound to, when known (Bun exposes it; Node's
+   *  http.Server does not — use `BakedServer.port` instead). */
+  port?: number
+  /** Force-stop the server. Bun semantics: `true` drops active connections. */
+  stop(force?: boolean): void
+}
+
+/** A running server instance plus a stop helper. */
+export interface BakedServer {
+  server: ServerHandle
+  stop(): void
+  port: number
+}
+
+/** Options for `gracefulShutdown` (drain grace period + signals). */
+export interface GracefulShutdownOptions {
+  /** Grace period (ms) to drain in-flight requests before force-closing. */
+  timeoutMs?: number
+  /** Signals to listen for. Default: SIGTERM + SIGINT. */
+  signals?: NodeJS.Signals[]
+}
+
+/**
+ * Wire SIGTERM/SIGINT to a graceful shutdown: soft-stop (drain in-flight
+ * requests) then force-close after `timeoutMs`. Works with both the Bun and
+ * Node server handles (both expose `stop(force?)`).
+ *
+ * Returns a cleanup function that removes the signal listeners. Call it (or
+ * `process.exit`) to tear down without hanging.
+ */
+export function gracefulShutdown(
+  handles: ReadonlyArray<ServerHandle>,
+  options: GracefulShutdownOptions = {},
+): () => void {
+  const timeoutMs = options.timeoutMs ?? 5_000
+  const signals = options.signals ?? ['SIGTERM', 'SIGINT']
+
+  let shuttingDown = false
+  const handler = () => {
+    if (shuttingDown) return
+    shuttingDown = true
+    // Soft stop: stop accepting new work and drain in-flight requests.
+    for (const h of handles) {
+      try {
+        h.stop(false)
+      } catch {
+        // ignore already-stopped handles
+      }
+    }
+    // Force-close after the grace period.
+    const timer = setTimeout(() => {
+      for (const h of handles) {
+        try {
+          h.stop(true)
+        } catch {
+          // ignore
+        }
+      }
+    }, timeoutMs)
+    timer.unref?.()
+  }
+
+  for (const sig of signals) {
+    process.on(sig, handler)
+  }
+
+  return () => {
+    for (const sig of signals) {
+      process.removeListener(sig, handler)
+    }
+  }
+}
+
+/** Options `buildRouteHandlers` actually consumes (a subset of the server
+ *  options — it does not need `port` or the Node-only server fields). */
+export type BuildRouteHandlersOptions = Pick<
+  CreateIngressServerOptions,
+  'routes' | 'fallback' | 'getIp' | 'copyBody'
+>
+
+/**
+ * Build the route → { method → handler } map from a server spec.
+ *
+ * Shared by `createIngressServer` (Bun.serve) and `createIngressServerNode`
+ * (node:http) so both runtimes wire the exact same route handlers.
+ */
+export function buildRouteHandlers(options: BuildRouteHandlersOptions): {
+  routes: Record<string, Record<string, unknown>>
+  baseOpts: BakedHandlerOptions
+} {
+  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,
+      bodyTimeoutMs: spec.bodyTimeoutMs,
+    }
+    const methods: Record<string, unknown> = {}
+
+    if (spec.read) {
+      if (typeof spec.read === 'function') {
+        // Raw request→Response handler (probes, /metrics): serve GET directly,
+        // outside the ingress pipeline. HEAD is intentionally not wired (a raw
+        // handler returns a body; probes use GET).
+        methods.GET = spec.read
+      } else {
+        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 (spec.echo) {
+      methods.POST = echoHandler(spec.echo, routeOpts)
+    }
+
+    if (spec.cookies) {
+      methods.GET = readHandler(spec.cookies, routeOpts)
+    }
+
+    if (spec.delete) {
+      methods.DELETE = deleteHandler(spec.delete, routeOpts)
+    }
+
+    if (spec.responder) {
+      // JS responder route: native decides + rejects; JS builds the 2xx.
+      const responderRoute = nativeResponderRoute(spec.responder.ingress, spec.responder.handler, {
+        ...routeOpts,
+        terminalStyle: spec.responder.terminalStyle,
+        readBody: spec.responder.readBody,
+      })
+      const responderMethods = spec.responder.methods ?? ['GET']
+      for (const m of responderMethods) {
+        methods[m] = responderRoute
+      }
+    }
+
+    // CORS preflight (OPTIONS) is served for EVERY route with a NATIVE handler
+    // (not just write routes with a fallback), so read-only routes also answer
+    // preflights with 204/403 from the native pipeline. Raw probe handlers
+    // (plain functions) are excluded — browsers don't preflight probes.
+    const primary =
+      spec.delete ??
+      (spec.read && typeof spec.read !== 'function' ? spec.read : undefined) ??
+      spec.cookies ??
+      spec.write ??
+      spec.echo
+    if (primary) {
+      methods.OPTIONS = optionsHandler(primary, routeOpts)
+    }
+
+    serverRoutes[path] = methods
+  }
+
+  return { routes: serverRoutes, baseOpts }
+}
+
+/** A matched dynamic route: the handler map + the extracted path params. */
+export interface PathMatch {
+  methods: Record<string, unknown>
+  params: Record<string, string>
+}
+
+interface CompiledDynamicPattern {
+  re: RegExp
+  paramNames: string[]
+  rest: boolean
+  methods: Record<string, unknown>
+  /** Number of literal (static) segments — used to prefer the most specific pattern. */
+  staticSegments: number
+}
+
+/**
+ * Build a path matcher over a route map, supporting `:param` and `*` (rest)
+ * segments. Exact (static) paths always win over dynamic patterns; dynamic
+ * patterns are ordered most-specific-first (most static segments, then fewest
+ * params). Used by `createIngressServerNode` (Bun's native router already
+ * matches dynamic patterns itself). The ingress pipeline does not echo path
+ * params in its response, so matching only selects the handler.
+ */
+export function buildPathMatcher(
+  routes: Record<string, Record<string, unknown>>,
+): (pathname: string) => PathMatch | undefined {
+  const exact = new Map<string, Record<string, unknown>>()
+  const dynamic: CompiledDynamicPattern[] = []
+
+  for (const [path, methods] of Object.entries(routes)) {
+    const hasParam = path.indexOf(':') !== -1
+    const hasRest = path.indexOf('*') !== -1
+    if (!hasParam && !hasRest) {
+      exact.set(path, methods)
+      continue
+    }
+
+    const paramNames: string[] = []
+    let rest = false
+    let staticSegments = 0
+    const parts = path.split('/').filter((s) => s.length > 0)
+    const source = parts
+      .map((seg) => {
+        if (seg === '*') {
+          rest = true
+          return '(.*)'
+        }
+        if (seg.startsWith(':')) {
+          paramNames.push(seg.slice(1))
+          return '([^/]+)'
+        }
+        staticSegments++
+        return seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      })
+      .join('/')
+
+    dynamic.push({
+      re: new RegExp(`^/${source}${rest ? '' : '/?$'}`),
+      paramNames,
+      rest,
+      methods,
+      staticSegments,
+    })
+  }
+
+  dynamic.sort(
+    (a, b) => b.staticSegments - a.staticSegments || a.paramNames.length - b.paramNames.length,
+  )
+
+  return (pathname: string) => {
+    const exactHit = exact.get(pathname)
+    if (exactHit !== undefined) {
+      return { methods: exactHit, params: {} }
+    }
+    for (const d of dynamic) {
+      const m = d.re.exec(pathname)
+      if (m !== null) {
+        const params: Record<string, string> = {}
+        for (let i = 0; i < d.paramNames.length; i++) {
+          const raw = m[i + 1]
+          if (raw !== undefined) params[d.paramNames[i] ?? ''] = safeDecode(raw)
+        }
+        if (d.rest) {
+          const restRaw = m[d.paramNames.length + 1]
+          if (restRaw !== undefined) params['*'] = safeDecode(restRaw)
+        }
+        return { methods: d.methods, params }
+      }
+    }
+    return undefined
+  }
+}
+
+function safeDecode(value: string): string {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}
+
+/** Typed options forwarded to `Bun.serve`. */
+interface BunServerOptions {
+  hostname: string
+  port: number
+  idleTimeout: number
+  routes: Record<string, Record<string, unknown>>
+  maxRequestBodySize: number
+  reusePort?: boolean
+  fetch?: (req: Request) => Response | Promise<Response>
+}
+
+/** Build a Bun.serve config from pre-baked route handlers. */
+export function createIngressServer(options: CreateIngressServerOptions): BakedServer {
+  // Bun-only by design: this builder targets Bun.serve's Routes API. Node
+  // consumers use `createIngressServerNode` with the same route handlers
+  // (sharing `buildRouteHandlers`).
+  if (!isBun()) {
+    throw new TypeError(
+      'createIngressServer is Bun-only (it builds a Bun.serve config). ' +
+        'On Node.js use createIngressServerNode with the same route handlers.',
+    )
+  }
+  const { routes: serverRoutes, baseOpts } = buildRouteHandlers(options)
+
+  const serverOptions: BunServerOptions = {
+    hostname: options.hostname ?? '0.0.0.0',
+    port: options.port,
+    idleTimeout: options.idleTimeout ?? 30,
+    routes: serverRoutes,
+    // Socket-level request-size guard. Bun's default is ~128 MiB; we default
+    // to 16 MiB so an oversized request is rejected at the socket without ever
+    // being buffered (route handlers enforce the tighter `maxBodyBytes`).
+    maxRequestBodySize: options.maxRequestBodySize ?? DEFAULT_MAX_REQUEST_BODY_SIZE,
+  }
+  if (options.reusePort) {
+    serverOptions.reusePort = true
+  }
+  if (options.fallback) {
+    serverOptions.fetch = fallbackHandler(options.fallback, baseOpts)
+  }
+
+  // Narrow bridge to Bun's (version-dependent) Serve type — Bun's Routes /
+  // FetchHandler shapes are complex, so we cast once instead of `as any`.
+  let server: ReturnType<typeof Bun.serve>
+  const init = serverOptions as Parameters<typeof Bun.serve>[0]
+  try {
+    server = Bun.serve(init)
+  } catch (err) {
+    if (options.reusePort) {
+      delete serverOptions.reusePort
+      server = Bun.serve(serverOptions as Parameters<typeof Bun.serve>[0])
+    } else {
+      throw err
+    }
+  }
+
+  return {
+    server,
+    stop: () => {
+      try {
+        server.stop(true)
+      } catch {
+        // already stopped
+      }
+    },
+    // The ACTUAL bound port (not `options.port`): with `port: 0` Bun
+    // auto-assigns a free port, and consumers expect the real listening port
+    // (parity with the Node adapter's `ready`/port behavior).
+    port: typeof server.port === 'number' ? server.port : options.port,
+  }
+}

package/src/ingress/shared.ts

@@ -0,0 +1,132 @@
+// src/ingress/shared.ts — Constants and types shared by BOTH ingress paths
+// (the fast packed-input path and the pre-baked handler path).
+//
+// Binary-layout constants read from Rust live in ./constants.ts (the single
+// numeric source of truth). This module holds the JS-level constants and types
+// that both ingress paths rely on, so neither path needs to depend on the
+// other's implementation module.
+
+/** Default maximum request body size in bytes. */
+export const DEFAULT_MAX_BODY_BYTES = 1_048_576
+
+/**
+ * Default native ingress output-buffer size (bytes) for the FAST path
+ * (`createIngressFast`).
+ *
+ * The fast path allocates its output buffer ONCE in the factory and reuses it
+ * across `run()` calls, so this default sets headroom for large responses
+ * (avoiding per-request growth) rather than per-request allocation cost.
+ * Perf-sensitive — change only with benchmarking.
+ */
+export const DEFAULT_FAST_OUTPUT_BUFFER_SIZE = 262_144
+
+/**
+ * Default native ingress output-buffer size (bytes) for the PRE-BAKED path
+ * (`createIngressHandler`).
+ *
+ * The pre-baked path POOLS output buffers across requests (`BufferPool`), so
+ * a smaller default keeps peak memory lower. Perf-sensitive — change only
+ * with benchmarking. The two paths intentionally differ (see above).
+ */
+export const DEFAULT_BAKED_OUTPUT_BUFFER_SIZE = 131_072
+
+/**
+ * Upper bound on ingress native output buffers (64 MiB). A huge misconfigured
+ * `outputBufferSize` would otherwise trigger a multi-GB native allocation
+ * (`handle_request_full_sync` allocates `vec![0u8; output_size]`), OOM-ing the
+ * process. Callers that genuinely need more can raise it here.
+ */
+export const MAX_OUTPUT_BUFFER_SIZE = 64 * 1024 * 1024
+
+/**
+ * Clamp an ingress output-buffer size into `[min, MAX_OUTPUT_BUFFER_SIZE]` so
+ * a misconfigured (huge/negative/NaN) value can never reach the native layer.
+ */
+export function clampIngressBufferSize(size: number, min: number): number {
+  return Math.min(MAX_OUTPUT_BUFFER_SIZE, Math.max(min, Math.floor(size)))
+}
+
+/**
+ * Default overall deadline (ms) for reading a request body. Non-zero so the
+ * async `createIngress` / route handlers are protected against slowloris and
+ * trickling bodies by default. Set `bodyTimeoutMs: 0` to disable.
+ */
+export const DEFAULT_BODY_TIMEOUT_MS = 30_000
+
+/**
+ * Convert a millisecond duration to whole seconds, rounding UP.
+ *
+ * Used everywhere a `ratelimit-reset` / `Retry-After` value is emitted: the
+ * native pipeline reports millisecond resolution, and HTTP rate-limit headers
+ * are whole-second integers (a partial second must not report 0).
+ */
+export function secondsFromMs(ms: number): number {
+  return Math.ceil(ms / 1000)
+}
+
+/** Maps HTTP methods to the native Ingress method-kind enum. */
+export const METHOD_KIND: Record<string, number> = {
+  GET: 0,
+  HEAD: 1,
+  POST: 2,
+  PUT: 3,
+  PATCH: 4,
+  DELETE: 5,
+  OPTIONS: 6,
+}
+
+/** Method-kind value for methods not present in {@link METHOD_KIND}. */
+export const METHOD_KIND_UNKNOWN = 7
+
+/** Which request headers to extract into the packed input. */
+export interface HeaderPlan {
+  cookie: boolean
+  cors: boolean
+  proxy: boolean
+  proto: boolean
+}
+
+/**
+ * Build the `HeaderPlan` for an ingress options object. Shared by BOTH ingress
+ * paths (`createIngressFast` and `createIngressHandler`) so the cookie/cors/
+ * proxy/proto extraction decisions can never silently diverge between them.
+ *
+ * Proxy headers (X-Forwarded-For / X-Real-IP) are requested when either
+ * `trustProxy` is true or `trustedProxies.enabled` is true — this is driven by
+ * the trust configuration alone, NOT by whether rate limiting is enabled.
+ * `proto` (https detection) follows the same trust rule and only applies when
+ * `https` is not pinned explicitly.
+ */
+export function buildHeaderPlan(options: {
+  parseCookies?: boolean
+  cors?: unknown
+  trustProxy?: boolean
+  trustedProxies?: { enabled?: boolean }
+  https?: boolean
+}): HeaderPlan {
+  const trust = options.trustProxy === true || options.trustedProxies?.enabled === true
+  return {
+    cookie: options.parseCookies === true,
+    cors: options.cors != null,
+    proxy: trust,
+    proto: trust && options.https === undefined,
+  }
+}
+
+/**
+ * Assert that a handler callback returned a synchronous (non-thenable) value.
+ *
+ * The ingress result objects are invalidated once `run()` returns, so an async
+ * callback would observe a stale/zeroed result. Throw instead of silently
+ * returning a broken value. `label` is used in the error message, e.g.
+ * `"createIngressFast().run()"`.
+ */
+export function assertSyncCallback<T>(out: T, label: string): void {
+  if (
+    out !== null &&
+    (typeof out === 'object' || typeof out === 'function') &&
+    typeof (out as { then?: unknown }).then === 'function'
+  ) {
+    throw new Error(`${label} callback must be synchronous.`)
+  }
+}

package/src/ingress/status.ts

@@ -0,0 +1,97 @@
+// src/ingress/status.ts — HTTP status normalization helpers shared by both
+// ingress paths (the fast path and the pre-baked handler path both normalize
+// the raw status emitted by the native Ingress into a valid response status).
+//
+// These helpers operate on the numeric error-code contract defined in
+// ./constants.ts, so they live in one place and cannot drift.
+
+import {
+  ERR_CODE_NONE,
+  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_REQUEST_TIMEOUT,
+  ERR_CODE_INTERNAL,
+} from './constants'
+
+/**
+ * Whether a raw status is a legal HTTP response status for the ingress
+ * pipeline (101 switch-protocol or any 2xx–5xx).
+ */
+export function isValidResponseStatus(status: number): boolean {
+  return status === 101 || (status >= 200 && status <= 599)
+}
+
+/**
+ * Map a native ingress error code to the HTTP status that should be returned.
+ * A permitted CORS preflight always yields 204.
+ */
+export function statusForErrorCode(errorCode: number, isPreflightAllowed: boolean): number {
+  if (isPreflightAllowed) return 204
+
+  switch (errorCode) {
+    case ERR_CODE_CORS_PREFLIGHT:
+      return 403
+    case ERR_CODE_RATE_LIMITED:
+      return 429
+    case ERR_CODE_BODY_TOO_LARGE:
+      return 413
+    case ERR_CODE_INVALID_JSON:
+      return 400
+    case ERR_CODE_SCHEMA_VALIDATION:
+      return 422
+    case ERR_CODE_BAD_REQUEST:
+      return 400
+    case ERR_CODE_REQUEST_TOO_LARGE:
+      return 431
+    case ERR_CODE_REQUEST_TIMEOUT:
+      return 408
+    case ERR_CODE_INTERNAL:
+      return 500
+    default:
+      return 500
+  }
+}
+
+/**
+ * Normalize a raw status to a legal response status, falling back to the
+ * error-code mapping when the raw status is not legal.
+ */
+export function normalizeResponseStatus(
+  status: number,
+  errorCode: number,
+  isPreflightAllowed: boolean,
+): number {
+  if (isValidResponseStatus(status)) {
+    return status
+  }
+  return statusForErrorCode(errorCode, isPreflightAllowed)
+}
+
+/**
+ * Compute a safe terminal status for a result: a permitted CORS preflight
+ * yields 204, otherwise the normalized status (or the error-code mapping).
+ */
+export function safeTerminalStatus(r: {
+  readonly status: number
+  readonly errorCode: number
+  readonly isPreflight: boolean
+  readonly corsAllowed: boolean
+}): number {
+  const preflightAllowed = r.isPreflight && r.corsAllowed
+  if (preflightAllowed) return 204
+
+  const s = normalizeResponseStatus(r.status, r.errorCode, false)
+
+  if (s >= 400) return s
+
+  if (r.errorCode !== ERR_CODE_NONE) {
+    return statusForErrorCode(r.errorCode, false)
+  }
+
+  return 500
+}