castrum 0.9.0 → 0.9.2

package/src/ingress/packing/route-wire.ts

@@ -0,0 +1,197 @@
+// src/ingress/packing/route-wire.ts — route-wire v3 byte helpers (PURE).
+//
+// The per-route native stack (`rust/ingress/native_route.rs`,
+// `castrum_route_*` / napi `Route`) compiles a descriptor ONCE and runs each
+// request frame in ONE native call. This module owns the WIRE on the JS side:
+// descriptor encoding, frame packing, and result decoding — byte-layout
+// constants MUST match `rust/ingress/native_route.rs` and `@ignex/native`
+// `route-wire.ts` EXACTLY (`ROUTE_DESC_VERSION` bumps on any layout change; a
+// mismatched compiler/addon must be a hard reject, never a silent misparse).
+//
+// PURE: no addon import, no module state — safe for any consumer. The
+// addon-touching factory lives in `src/ingress/native-route.ts`.
+
+import { decoder, encoder } from '../../shared/bytes'
+
+/** Route descriptor magic (`"ROUT"` LE). Must match `ROUTE_DESC_MAGIC` in Rust. */
+export const ROUTE_DESC_MAGIC = 0x524f5554
+/** Wire version — bump on ANY descriptor/frame/result layout change. */
+export const ROUTE_DESC_VERSION = 3
+
+/** Descriptor stage tags (the ordered pipeline a route instance runs). */
+export const ROUTE_STAGE = {
+  parseQuery: 0,
+  parseCookies: 1,
+  validateQuery: 2,
+  validateCookies: 3,
+  validateBody: 4,
+  requireJsonBody: 5,
+} as const
+/** A descriptor stage tag (`ROUTE_STAGE` values, must match Rust). */
+export type RouteStageTag = (typeof ROUTE_STAGE)[keyof typeof ROUTE_STAGE]
+
+/** Descriptor part tags (`RoutePartKind`): the schema-bearing request parts. */
+export const ROUTE_PART = { body: 3 } as const
+
+/** Result flag bits (`ROUTE_RESULT_FLAG_*` in Rust). */
+export const ROUTE_FLAG = {
+  OK: 1 << 0,
+  BODY_VALID_JSON: 1 << 1,
+  QUERY_VALID: 1 << 2,
+  COOKIE_VALID: 1 << 3,
+  BODY_VALID: 1 << 4,
+} as const
+
+/** Frame flag: the body section is present (bit 0 of the frame flags word). */
+export const ROUTE_FRAME_FLAG_HAS_BODY = 1 << 0
+
+/** Size limits a route descriptor carries. */
+export interface RouteWireLimits {
+  maxBodyBytes: number
+  maxQueryBytes: number
+  maxCookieBytes: number
+  maxPairs: number
+}
+
+/** A schema part carried by the descriptor (part tag + draft-07 JSON bytes). */
+export interface RouteWireSchema {
+  part: number
+  bytes: Uint8Array
+}
+
+/**
+ * Encode a route plan into the descriptor wire.
+ *
+ * Layout: `[magic u32][version u32][maxBody u32][maxQuery u32][maxCookie u32]
+ * [maxPairs u32][stageCount u32][stages u8…][schemaCount u32]
+ * { [part u8][len u32][schema] }…`
+ */
+export function encodeRouteDescriptor(
+  pipeline: readonly RouteStageTag[],
+  schemas: readonly RouteWireSchema[],
+  limits: RouteWireLimits,
+): Uint8Array {
+  let total = 8 + 16 + 4 + pipeline.length + 4
+  for (const s of schemas) total += 1 + 4 + s.bytes.byteLength
+  const out = new Uint8Array(total)
+  const view = new DataView(out.buffer)
+  let pos = 0
+  view.setUint32(pos, ROUTE_DESC_MAGIC, true)
+  pos += 4
+  view.setUint32(pos, ROUTE_DESC_VERSION, true)
+  pos += 4
+  for (const v of [
+    limits.maxBodyBytes,
+    limits.maxQueryBytes,
+    limits.maxCookieBytes,
+    limits.maxPairs,
+  ]) {
+    view.setUint32(pos, v, true)
+    pos += 4
+  }
+  view.setUint32(pos, pipeline.length, true)
+  pos += 4
+  for (const stage of pipeline) {
+    out[pos] = stage
+    pos += 1
+  }
+  view.setUint32(pos, schemas.length, true)
+  pos += 4
+  for (const s of schemas) {
+    out[pos] = s.part
+    pos += 1
+    view.setUint32(pos, s.bytes.byteLength, true)
+    pos += 4
+    out.set(s.bytes, pos)
+    pos += s.bytes.byteLength
+  }
+  return out
+}
+
+/**
+ * Encode a request frame: `[flags u32][qLen][query][cLen][cookie]([bLen][body])`.
+ * The `flags` word currently only carries `ROUTE_FRAME_FLAG_HAS_BODY`.
+ */
+export function packRouteFrame(
+  query: string,
+  cookie: string,
+  body: Uint8Array | null,
+): Uint8Array {
+  const q = encoder.encode(query)
+  const c = encoder.encode(cookie)
+  const hasBody = body !== null && body.byteLength > 0
+  const total =
+    4 + 4 + q.byteLength + 4 + c.byteLength + (hasBody ? 4 + (body?.byteLength ?? 0) : 0)
+  const out = new Uint8Array(total)
+  const view = new DataView(out.buffer)
+  let pos = 0
+  view.setUint32(pos, hasBody ? ROUTE_FRAME_FLAG_HAS_BODY : 0, true)
+  pos += 4
+  view.setUint32(pos, q.byteLength, true)
+  pos += 4
+  out.set(q, pos)
+  pos += q.byteLength
+  view.setUint32(pos, c.byteLength, true)
+  pos += 4
+  out.set(c, pos)
+  pos += c.byteLength
+  if (hasBody && body) {
+    view.setUint32(pos, body.byteLength, true)
+    pos += 4
+    out.set(body, pos)
+  }
+  return out
+}
+
+/** A decoded `[name, value]` pair from a result section. */
+export type RouteWirePair = [string, string]
+
+/** The decoded route result: the verdict header + optional pair sections. */
+export interface RouteWireResult {
+  /** `ROUTE_FLAG_*` bits from the result header. */
+  flags: number
+  /** `0` = ok; `400` = not-JSON under requireJsonBody; `422` = schema fail. */
+  errorCode: number
+  /** Decoded query pairs (present iff the plan compiled `parseQuery`). */
+  query: RouteWirePair[]
+  /** Decoded cookie pairs (present iff the plan compiled `parseCookies`). */
+  cookie: RouteWirePair[]
+}
+
+/**
+ * Decode the result wire: `[flags u32][errorCode u32]` + a query pair section
+ * iff `query` and a cookie pair section iff `cookie` (the caller knows its own
+ * plan). Sections are `[count u32] { [nameLen u32][name][valueLen u32][value] }`.
+ */
+export function decodeRouteResult(
+  buf: Uint8Array,
+  opts: { query: boolean; cookie: boolean },
+): RouteWireResult {
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength)
+  const flags = view.getUint32(0, true)
+  const errorCode = view.getUint32(4, true)
+  let pos = 8
+  const readPairs = (): RouteWirePair[] => {
+    const count = view.getUint32(pos, true)
+    pos += 4
+    const out: RouteWirePair[] = []
+    for (let i = 0; i < count; i++) {
+      const nameLen = view.getUint32(pos, true)
+      pos += 4
+      const name = decoder.decode(buf.subarray(pos, pos + nameLen))
+      pos += nameLen
+      const valueLen = view.getUint32(pos, true)
+      pos += 4
+      const value = decoder.decode(buf.subarray(pos, pos + valueLen))
+      pos += valueLen
+      out.push([name, value])
+    }
+    return out
+  }
+  return {
+    flags,
+    errorCode,
+    query: opts.query ? readPairs() : [],
+    cookie: opts.cookie ? readPairs() : [],
+  }
+}

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

@@ -1,29 +1,35 @@
 // src/ingress/packing/select-headers.ts — Shared header-selection iterator.
 //
 // Single source of truth for "which headers does a HeaderPlan select" across
-// the THREE packing paths:
+// the TWO packing paths (a string-array reference variant lives test-local in
+// header-packing.test.ts):
 //   - `packHeaders`             (fast path, ./header-packing.ts)
 //   - `gatherRawHeadersPacked`  (pre-baked packed path, ./gather-raw-headers.ts)
-//   - `gatherRawHeaders`        (pre-baked string-array reference, ./gather-raw-headers.ts)
 //
-// All three apply the SAME selection rules and the SAME per-header size guards
+// Both apply the SAME selection rules and the SAME per-header size guards
 // (an oversized value is dropped rather than forwarded, so the packed block can
 // never exceed the native `max_headers_bytes` (65536) and 500). This module
 // owns that logic plus the pre-encoded header-name bytes, so a rule or size
 // change cannot drift between the paths.
 
-import { METHOD_KIND, type HeaderPlan } from '../shared'
+import { encoder } from '../../shared/bytes'
+import { type HeaderPlan, METHOD_KIND } from '../shared'
 import { MAX_COOKIE_HEADER_BYTES, MAX_SMALL_HEADER_BYTES, MAX_XFF_HEADER_BYTES } from './scratch'
 
-const encoder = new TextEncoder()
-
 // ── Header name constants (pre-encoded) ────────────────────────
+/** Pre-encoded `cookie` header name. */
 export const HDR_COOKIE = encoder.encode('cookie')
+/** Pre-encoded `origin` header name. */
 export const HDR_ORIGIN = encoder.encode('origin')
+/** Pre-encoded `access-control-request-method` header name. */
 export const HDR_ACRM = encoder.encode('access-control-request-method')
+/** Pre-encoded `access-control-request-headers` header name. */
 export const HDR_ACRH = encoder.encode('access-control-request-headers')
+/** Pre-encoded `x-forwarded-for` header name. */
 export const HDR_XFF = encoder.encode('x-forwarded-for')
+/** Pre-encoded `x-real-ip` header name. */
 export const HDR_XRI = encoder.encode('x-real-ip')
+/** Pre-encoded `x-forwarded-proto` header name. */
 export const HDR_XFP = encoder.encode('x-forwarded-proto')
 
 /**
@@ -39,6 +45,12 @@ export const HDR_XFP = encoder.encode('x-forwarded-proto')
  *   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.
+ * @param cookieValue - When provided (non-undefined), the already-fetched
+ *   `Cookie` header value, avoiding a second `req.headers.get('cookie')`
+ *   native→JS conversion (the caller's cookie+cors fast path already fetched
+ *   it once to decide between the cached origin block and the general path).
+ *   When omitted, the cookie is fetched here — so existing callers are
+ *   byte-for-byte unchanged.
  */
 export function forEachSelectedHeader(
   req: Request,
@@ -46,11 +58,12 @@ export function forEachSelectedHeader(
   methodKind: number,
   originValue: string | null | undefined,
   visit: (name: Uint8Array, value: string) => void,
+  cookieValue?: string | null,
 ): void {
   const h = req.headers
 
   if (plan.cookie) {
-    const v = h.get('cookie')
+    const v = cookieValue !== undefined ? cookieValue : h.get('cookie')
     if (v !== null && v.length <= MAX_COOKIE_HEADER_BYTES) {
       visit(HDR_COOKIE, v)
     }

package/src/ingress/path-matcher.ts

@@ -0,0 +1,115 @@
+// src/ingress/path-matcher.ts — `:param` / `*` path matching for pre-baked routes
+//
+// The dynamic-path matcher shared by the Node adapter (server-node.ts) and the
+// router (router.ts). Bun's native router matches dynamic paths itself, so this
+// only runs on Node / route-manager paths. The ingress pipeline does not echo
+// path params in its response, so matching only selects the handler.
+
+/** 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.
+ *
+ * @param routes the built route map (`path` → `method` → handler)
+ * @returns a matcher: `pathname` → `{ methods, params }` or `undefined`
+ */
+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
+  }
+}
+
+/**
+ * Percent-decode a matched path segment, tolerating malformed escapes: a bad
+ * `%` sequence is returned raw rather than throwing, so the matcher never
+ * rejects a request over a decode error.
+ */
+export function safeDecode(value: string): string {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}

package/src/ingress/response/baked-response.ts

@@ -0,0 +1,302 @@
+// src/ingress/response/baked-response.ts — pre-baked response builders (path 2)
+//
+// The seven response-builder methods of `OptimizedIngressHandler`, extracted
+// from createIngressHandler (handlers.ts) so the factory stays focused on
+// packing + pooling. Mirrors fast.ts's response/terminal.ts split — but emits
+// the BENCH wire format (`{"ok":false,"error":{...}}` + `ratelimit-*` headers),
+// NOT the fast path's `x-ratelimit-*` shape (see AGENTS.md — do not unify).
+//
+// The builders are bound to a handler's configuration (header templates,
+// request-id emission, CORS cache) plus a shared mutable `BakedResponseState`
+// that `run()` in handlers.ts owns: `zeroCopyResponse` marks the pooled
+// output buffer as borrowed so `run()` does not release it before the body is
+// consumed.
+
+import type { PooledBuffer } from '../../shared/buffer-pool'
+import { encoder } from '../../shared/bytes'
+import { pooledBodyResponse } from '../../shared/response'
+import {
+  ERR_CODE_RATE_LIMITED as ERROR_CODE_RATE_LIMITED,
+  HV_CORS_PREFLIGHT,
+  HV_CORS_SIMPLE,
+  HV_JSON,
+  HV_RATE_ACTIVE,
+  HV_RATE_LIMITED,
+} from '../constants'
+import type { BakedIngressResult } from '../decode/baked-result'
+import { secondsFromMs } from '../shared'
+import { safeTerminalStatus } from '../status'
+import type { BakedContext, OptimizedIngressHandler } from '../types'
+import { ERROR_BODIES, ERROR_CODE_BODIES, rateLimitedBody } from './error-bodies'
+
+const EMPTY_BODY = new Uint8Array(0)
+
+/** Shared per-request state between `run()` (handlers.ts) and the builders. */
+export interface BakedResponseState {
+  /** The pooled output buffer backing the current `run()` (null outside one). */
+  currentHandle: PooledBuffer | null
+  /** True when a zero-copy Response claimed the buffer (run() must not release). */
+  responseBorrowsBuffer: boolean
+}
+
+/** Configuration the builder factory needs from a handler. */
+export interface BakedResponseBuildersDeps {
+  /** Variant-indexed pre-baked header templates (regular responses). */
+  headerTemplates: ReadonlyArray<ReadonlyArray<[string, string]>>
+  /** Variant-indexed pre-baked terminal templates (JSON + no-store). */
+  terminalTemplates: ReadonlyArray<ReadonlyArray<[string, string]>>
+  /** Emit an `x-request-id` header on responses. */
+  emitRequestIdHeader: boolean
+  /** Abandonment guard (ms) for zero-copy responses. */
+  zeroCopyTimeoutMs: number
+  /** Cache of Origin-augmented header arrays keyed by `variant\u0000origin`. */
+  originHeaderCache: Map<string, [string, string][]>
+  /** Shared per-request state (owned by `run()` in handlers.ts). */
+  state: BakedResponseState
+}
+
+/**
+ * Build the seven response-builder methods of `OptimizedIngressHandler`
+ * (everything except `run`), bound to this handler's header templates and
+ * request-id policy. The returned methods are the exact bodies that lived in
+ * `createIngressHandler`.
+ */
+export function buildBakedResponseBuilders(
+  deps: BakedResponseBuildersDeps,
+): Omit<OptimizedIngressHandler, 'run'> {
+  const {
+    headerTemplates,
+    terminalTemplates,
+    emitRequestIdHeader,
+    zeroCopyTimeoutMs,
+    originHeaderCache,
+    state,
+  } = deps
+
+  function responseHeaders(
+    variant: number,
+    requestIdHeader: string | null,
+    origin: string | null,
+    rateRemaining?: number,
+    rateResetSecs?: number,
+    retryAfterSecs?: number,
+  ): [string, string][] {
+    const template: ReadonlyArray<[string, string]> =
+      headerTemplates[variant & 31] ?? headerTemplates[0] ?? []
+
+    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
+
+    if (!needsRequestId && !needsOrigin && !needsRate && !needsRetry) {
+      // 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++
+
+    const entries = new Array<[string, string]>(template.length + extra)
+    let i = 0
+
+    for (const pair of template) {
+      entries[i++] = pair
+    }
+
+    if (needsRequestId) {
+      entries[i++] = ['x-request-id', requestIdHeader as string]
+    }
+
+    if (needsOrigin) {
+      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)]
+    }
+
+    if (needsRetry) {
+      entries[i++] = ['retry-after', String(retryAfterSecs ?? 0)]
+    }
+
+    return entries
+  }
+
+  function terminalHeaders(
+    variant: number,
+    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(
+      v,
+      requestIdHeader,
+      origin,
+      result?.rateRemaining,
+      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
+  }
+
+  function terminalResponse(
+    _req: Request | undefined,
+    result: BakedIngressResult,
+    ctx: BakedContext,
+  ): Response | null {
+    if (!result.terminal) {
+      return null
+    }
+
+    const preflightAllowed = result.isPreflight && result.corsAllowed
+
+    if (preflightAllowed) {
+      return new Response(null, {
+        status: 204,
+        headers: responseHeaders(
+          result.headerVariant,
+          ctx.requestIdHeader,
+          ctx.origin,
+          result.rateRemaining,
+          result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined,
+          result.retryAfterMs > 0 ? secondsFromMs(result.retryAfterMs) : undefined,
+        ),
+      })
+    }
+
+    const status = safeTerminalStatus(result)
+
+    const body: Uint8Array =
+      result.errorCode === ERROR_CODE_RATE_LIMITED
+        ? rateLimitedBody(result.retryAfterMs)
+        : (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 | undefined,
+    result: BakedIngressResult | null,
+    status: number,
+    code: string,
+    message: string,
+    ctx: BakedContext,
+  ): Response {
+    const body =
+      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 {
+    return new Response(ERROR_BODIES.internal, {
+      status: 500,
+      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)
+    let i = 0
+    for (const pair of headers) {
+      out[i++] = pair
+    }
+    out[headers.length] = ['content-type', contentType]
+    return out
+  }
+
+  function zeroCopyResponse(
+    result: BakedIngressResult,
+    _ctx: BakedContext,
+    init: ResponseInit,
+  ): Response {
+    if (state.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()).',
+      )
+    }
+    state.responseBorrowsBuffer = true
+    return pooledBodyResponse(state.currentHandle, result.bodyJson(false), init, zeroCopyTimeoutMs)
+  }
+
+  return {
+    responseHeaders,
+    terminalHeaders,
+    terminalResponse,
+    errorResponse,
+    internalErrorResponse,
+    withContentType,
+    zeroCopyResponse,
+  }
+}