castrum 0.9.7 → 0.9.8

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

@@ -24,6 +24,7 @@ import {
   HV_RATE_LIMITED,
 } from '../constants'
 import type { BakedIngressResult } from '../decode/baked-result'
+import { memoizedHeaders } from '../headers/memoized-headers'
 import { secondsFromMs } from '../shared'
 import { safeTerminalStatus } from '../status'
 import type { BakedContext, OptimizedIngressHandler } from '../types'
@@ -31,6 +32,14 @@ import { ERROR_BODIES, ERROR_CODE_BODIES, rateLimitedBody } from './error-bodies
 
 const EMPTY_BODY = new Uint8Array(0)
 
+/**
+ * Upper bound on the per-`(variant, origin)` memoized header arrays. Under
+ * wildcard CORS EVERY Origin is allowed, so this cache is attacker-keyed —
+ * without a cap a stream of distinct Origins grows it without bound (remote
+ * memory exhaustion). Evicts the oldest entry (Map preserves insertion order).
+ */
+export const ORIGIN_HEADER_CACHE_MAX = 64
+
 /** 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). */
@@ -55,6 +64,33 @@ export interface BakedResponseBuildersDeps {
   state: BakedResponseState
 }
 
+/**
+ * Pre-warm the per-origin header-array cache AND the memoized `Headers`
+ * `WeakMap` for the configured exact allow-origins at the success `variant`.
+ *
+ * `variant` MUST be the one the success path actually returns
+ * (`HV_JSON | HV_CORS_SIMPLE`, plus `HV_RATE_ACTIVE` when rate limiting is
+ * enabled). Warming a different variant populates an unreachable cache entry
+ * and buys nothing.
+ *
+ * @param responseHeaders The handler's header builder (from this module).
+ * @param origins Exact, concrete allow-origins (wildcards excluded by caller).
+ * @param variant The success header variant to warm.
+ */
+export function prewarmOriginHeaders(
+  responseHeaders: (
+    variant: number,
+    requestIdHeader: string | null,
+    origin: string | null,
+  ) => [string, string][],
+  origins: readonly string[],
+  variant: number,
+): void {
+  for (const origin of origins) {
+    memoizedHeaders(responseHeaders(variant, null, origin))
+  }
+}
+
 /**
  * Build the seven response-builder methods of `OptimizedIngressHandler`
  * (everything except `run`), bound to this handler's header templates and
@@ -73,6 +109,72 @@ export function buildBakedResponseBuilders(
     state,
   } = deps
 
+  /**
+   * The cacheable base entries for a `(variant, origin)`: the baked template
+   * plus the reflected `access-control-allow-origin`. Memoized per 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 alternated between allowed origins). Bounded by
+   * `ORIGIN_HEADER_CACHE_MAX`.
+   */
+  function originBaseEntries(variant: number, origin: string): [string, string][] {
+    const key = `${variant & 31}\u0000${origin}`
+    const cached = originHeaderCache.get(key)
+    if (cached !== undefined) {
+      return cached
+    }
+    const template = headerTemplates[variant & 31] ?? headerTemplates[0] ?? []
+    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]
+    if (originHeaderCache.size >= ORIGIN_HEADER_CACHE_MAX) {
+      const oldest = originHeaderCache.keys().next().value
+      if (oldest !== undefined) originHeaderCache.delete(oldest)
+    }
+    originHeaderCache.set(key, entries)
+    return entries
+  }
+
+  /**
+   * Success-path headers as a `Headers` instance. Uses the memoized base
+   * (template + reflected origin) so the memoized-`Headers` fast path is kept
+   * even when per-request rate / request-id extras are present — a fresh array
+   * there would force a `new Headers` on every response. Extras are applied to
+   * a CLONE of the base, so the memoized instance is never mutated.
+   */
+  function successHeaders(
+    variant: number,
+    requestIdHeader: string | null,
+    origin: string | null,
+    rateRemaining?: number,
+    rateResetSecs?: number,
+  ): Headers {
+    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 base = needsOrigin
+      ? memoizedHeaders(originBaseEntries(variant, origin as string))
+      : memoizedHeaders(headerTemplates[variant & 31] ?? headerTemplates[0] ?? [])
+
+    if (!needsRequestId && !needsRate) {
+      return base
+    }
+    const headers = new Headers(base)
+    if (needsRequestId) {
+      headers.set('x-request-id', requestIdHeader as string)
+    }
+    if (needsRate) {
+      headers.set('ratelimit-remaining', String(rateRemaining ?? 0))
+      headers.set('ratelimit-reset', String(rateResetSecs ?? 0))
+    }
+    return headers
+  }
+
   function responseHeaders(
     variant: number,
     requestIdHeader: string | null,
@@ -97,24 +199,7 @@ export function buildBakedResponseBuilders(
     }
 
     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
+      return originBaseEntries(variant, origin as string)
     }
 
     let extra = 0
@@ -210,13 +295,15 @@ export function buildBakedResponseBuilders(
     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,
+        headers: memoizedHeaders(
+          responseHeaders(
+            result.headerVariant,
+            ctx.requestIdHeader,
+            ctx.origin,
+            result.rateRemaining,
+            result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined,
+            result.retryAfterMs > 0 ? secondsFromMs(result.retryAfterMs) : undefined,
+          ),
         ),
       })
     }
@@ -230,7 +317,7 @@ export function buildBakedResponseBuilders(
 
     return new Response(body, {
       status,
-      headers: terminalHeaders(result.headerVariant, ctx, result),
+      headers: memoizedHeaders(terminalHeaders(result.headerVariant, ctx, result)),
     })
   }
 
@@ -247,14 +334,16 @@ export function buildBakedResponseBuilders(
 
     return new Response(body, {
       status,
-      headers: terminalHeaders(result?.headerVariant ?? HV_JSON, ctx, result),
+      headers: memoizedHeaders(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),
+      headers: memoizedHeaders(
+        terminalHeaders(result?.headerVariant ?? HV_JSON, ctx, result ?? null),
+      ),
     })
   }
 
@@ -292,6 +381,7 @@ export function buildBakedResponseBuilders(
 
   return {
     responseHeaders,
+    successHeaders,
     terminalHeaders,
     terminalResponse,
     errorResponse,

package/src/ingress/router.ts

@@ -22,9 +22,9 @@
 // the deleted dead wire).
 
 import type { BakedIngressResult } from './decode/baked-result'
-import { type BakedIngressRuntime, createIngressHandler } from './handlers'
+import { type BakedIngressRuntime, createIngressHandler, RATE_LIMIT_U32_MAX } from './handlers'
 import type { NativeRoutePlan } from './native-route'
-import type { IngressHandlerOptions } from './options'
+import { type IngressHandlerOptions, warnRateLimitWithoutGetIp } from './options'
 import type { PathMatch } from './path-matcher'
 import { buildPathMatcher } from './path-matcher'
 import type { BakedRoute, RouteHandler } from './server'
@@ -199,6 +199,18 @@ export function createIngressRouter(options: CreateIngressRouterOptions): Ingres
     const handler = createIngressHandler(spec.options ?? {}, runtime)
     compiled[path] = handler
 
+    // Rate limiting without a getIp resolver collapses every client into ONE
+    // bucket; warn once (a global bucket can be deliberate, so don't fail).
+    const routeLimit = (spec.options?.rateLimit as { limit?: number } | undefined)?.limit
+    if (
+      typeof routeLimit === 'number' &&
+      routeLimit > 0 &&
+      routeLimit !== RATE_LIMIT_U32_MAX &&
+      options.getIp === undefined
+    ) {
+      warnRateLimitWithoutGetIp()
+    }
+
     if (spec.responder) {
       // Responder route: native decides + rejects; JS builds the 2xx.
       bakedRoutes[path] = {

package/src/ingress/routes/common.ts

@@ -1,6 +1,7 @@
 // src/ingress/routes/common.ts — Shared route-handler options + helpers.
 
 import type { BakedIngressResult } from '../decode/baked-result'
+import { memoizedHeaders } from '../headers/memoized-headers'
 import { secondsFromMs } from '../shared'
 import type { BakedContext, OptimizedIngressHandler } from '../types'
 
@@ -52,6 +53,10 @@ export function resolveIp(
  * every pre-baked success path. A plain function call, so the hot path keeps
  * its single init-object allocation and nothing else.
  *
+ * The header array is wrapped in a memoized `Headers` (see
+ * `headers/memoized-headers.ts`) — identical bytes on the wire, ~4x cheaper
+ * Response construction for the recurring header sets.
+ *
  * @param status Success status; defaults to 200.
  */
 export function buildSuccessInit(
@@ -60,16 +65,27 @@ export function buildSuccessInit(
   ctx: BakedContext,
   status = 200,
 ): ResponseInit {
-  return {
-    status,
-    headers: ingress.responseHeaders(
-      result.headerVariant,
-      ctx.requestIdHeader,
-      ctx.origin,
-      result.rateRemaining,
-      result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined,
-    ),
-  }
+  const rateResetSecs = result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined
+  // Prefer the `Headers`-producing path (keeps the memoized base even with
+  // per-request extras); mocks that only implement `responseHeaders` fall back.
+  const headers = ingress.successHeaders
+    ? ingress.successHeaders(
+        result.headerVariant,
+        ctx.requestIdHeader,
+        ctx.origin,
+        result.rateRemaining,
+        rateResetSecs,
+      )
+    : memoizedHeaders(
+        ingress.responseHeaders(
+          result.headerVariant,
+          ctx.requestIdHeader,
+          ctx.origin,
+          result.rateRemaining,
+          rateResetSecs,
+        ),
+      )
+  return { status, headers }
 }
 
 /**

package/src/ingress/routes/echo.ts

@@ -7,9 +7,40 @@ import { DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES, secondsFromMs } from '
 import type { OptimizedIngressHandler } from '../types'
 import { type BakedHandlerOptions, resolveIp } from './common'
 
+/**
+ * Content types safe to echo back for an attacker-supplied body. Anything else
+ * — notably `text/html`, `application/xhtml+xml`, `image/svg+xml` and XML — is
+ * coerced to `application/octet-stream`: reflecting an active type would let a
+ * `POST /echo` execute the request body as script in a browser.
+ */
+const SAFE_ECHO_CONTENT_TYPES = new Set([
+  'application/json',
+  'application/octet-stream',
+  'text/plain',
+])
+
+/** Lowercased media type with parameters stripped (`text/html; charset=x` → `text/html`). */
+function echoMediaTypeOf(contentType: string): string {
+  const semi = contentType.indexOf(';')
+  return (semi >= 0 ? contentType.slice(0, semi) : contentType).trim().toLowerCase()
+}
+
+/**
+ * Coerce a client Content-Type into a type that is safe to echo back.
+ *
+ * @param contentType - The raw request `Content-Type` header value.
+ * @returns The value unchanged when it is a safe non-active type, else
+ *   `application/octet-stream`.
+ */
+export function safeEchoContentType(contentType: string): string {
+  return SAFE_ECHO_CONTENT_TYPES.has(echoMediaTypeOf(contentType))
+    ? contentType
+    : 'application/octet-stream'
+}
+
 /**
  * Pre-baked echo handler: streams the request body back with the client's
- * Content-Type, bounded by `maxBodyBytes`.
+ * Content-Type (coerced to a non-active type), bounded by `maxBodyBytes`.
  */
 export function echoHandler(
   ingress: OptimizedIngressHandler,
@@ -50,7 +81,19 @@ export function echoHandler(
 
     const baseHeaders: ReadonlyArray<[string, string]> = prep.headers ?? []
 
-    const requestedContentType = req.headers.get('content-type') ?? 'application/octet-stream'
+    const requestedContentType = safeEchoContentType(
+      req.headers.get('content-type') ?? 'application/octet-stream',
+    )
+
+    // Content-Type + `nosniff` (unless the security config already emitted it),
+    // so the echoed body can never be sniffed into an active type.
+    const withEchoHeaders = (contentType: string): [string, string][] => {
+      const headers = ingress.withContentType(baseHeaders, contentType)
+      if (!headers.some(([name]) => name.toLowerCase() === 'x-content-type-options')) {
+        headers.push(['x-content-type-options', 'nosniff'])
+      }
+      return headers
+    }
 
     const contentLengthHeader = req.headers.get('content-length')
     const contentLength = contentLengthHeader === null ? NaN : Number(contentLengthHeader)
@@ -59,20 +102,20 @@ export function echoHandler(
       if (contentLength > maxBodyBytes) {
         return new Response(ERROR_BODIES.body_too_large, {
           status: 413,
-          headers: ingress.withContentType(baseHeaders, 'application/json'),
+          headers: withEchoHeaders('application/json'),
         })
       }
 
       if (contentLength <= 0 || req.body === null) {
         return new Response(null, {
           status: 200,
-          headers: ingress.withContentType(baseHeaders, requestedContentType),
+          headers: withEchoHeaders(requestedContentType),
         })
       }
 
       return new Response(req.body, {
         status: 200,
-        headers: ingress.withContentType(baseHeaders, requestedContentType),
+        headers: withEchoHeaders(requestedContentType),
       })
     }
 
@@ -84,7 +127,7 @@ export function echoHandler(
 
       return new Response(bodyBytes.byteLength > 0 ? bodyBytes : null, {
         status: 200,
-        headers: ingress.withContentType(baseHeaders, requestedContentType),
+        headers: withEchoHeaders(requestedContentType),
       })
     } catch (err) {
       const code = (err as { code?: string } | null)?.code
@@ -99,7 +142,7 @@ export function echoHandler(
             : ERROR_BODIES.bad_request,
         {
           status: isTooLarge ? 413 : isTimeout ? 408 : 400,
-          headers: ingress.withContentType(baseHeaders, 'application/json'),
+          headers: withEchoHeaders('application/json'),
         },
       )
     }

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

@@ -23,6 +23,18 @@ function defaultJsonValid(bytes: Uint8Array): boolean {
   }
 }
 
+/**
+ * Whether a `Content-Type` header denotes JSON: the media type (the part before
+ * any parameters) is exactly `application/json`, or a `+json` structured suffix
+ * (e.g. `application/vnd.api+json`). A plain substring test would wrongly
+ * accept `text/plain; application/json`.
+ */
+function isJsonContentType(contentType: string): boolean {
+  const semi = contentType.indexOf(';')
+  const mediaType = (semi >= 0 ? contentType.slice(0, semi) : contentType).trim().toLowerCase()
+  return mediaType === 'application/json' || mediaType.endsWith('+json')
+}
+
 /**
  * Pre-baked JSON-write handler (POST/PUT/PATCH): enforces Content-Type,
  * content-length/body-size limits, JSON validity and (optionally) schema
@@ -47,20 +59,21 @@ export function jsonWriteHandler(
     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(
+    if (!isJsonContentType(contentType)) {
+      // Always 415 for an unsupported media type. Do NOT short-circuit on the
+      // native terminal first: running with no body yields a "body required"
+      // 400, which previously masked the 415 (the native pipeline still applied
+      // rate limiting / CORS headers to this run).
+      return fallback.run(req, ip, null, (result, ctx) =>
+        fallback.errorResponse(
           req,
           result,
           415,
           'unsupported_media_type',
           'Content-Type must be application/json',
           ctx,
-        )
-      })
+        ),
+      )
     }
 
     // Content-Length / body-size enforcement happens INSIDE readBodyWithLimit

package/src/ingress/routes/responder.ts

@@ -45,7 +45,7 @@ export interface ResponderRouteOptions extends BakedHandlerOptions {
 }
 
 /** ignex framework security posture for terminal responses. */
-const IGNGEX_SECURITY_HEADERS: [string, string][] = [
+const IGNEX_SECURITY_HEADERS: [string, string][] = [
   ['x-frame-options', 'DENY'],
   ['x-content-type-options', 'nosniff'],
   ['referrer-policy', 'no-referrer'],
@@ -55,7 +55,7 @@ const IGNGEX_SECURITY_HEADERS: [string, string][] = [
 function buildIgngexTerminal(result: BakedIngressResult, _ctx: BakedContext): Response {
   const preflightAllowed = result.isPreflight && result.corsAllowed
   if (preflightAllowed) {
-    return new Response(null, { status: 204, headers: IGNGEX_SECURITY_HEADERS })
+    return new Response(null, { status: 204, headers: IGNEX_SECURITY_HEADERS })
   }
   const status = safeTerminalStatus(result)
   const body = JSON.stringify({
@@ -63,7 +63,7 @@ function buildIgngexTerminal(result: BakedIngressResult, _ctx: BakedContext): Re
     status,
     code: errorCodeName(result.errorCode),
   })
-  const headers = new Headers(IGNGEX_SECURITY_HEADERS)
+  const headers = new Headers(IGNEX_SECURITY_HEADERS)
   headers.set('content-type', 'application/json; charset=utf-8')
   return new Response(body, { status, headers })
 }
@@ -112,7 +112,7 @@ export function nativeResponderRoute(
         const code = (err as Error & { code?: string }).code
         const status = code === 'REQUEST_TIMEOUT' ? 408 : code === 'BODY_TOO_LARGE' ? 413 : 400
         const payload = JSON.stringify({ error: 'Bad Request', status, code: 'BAD_REQUEST' })
-        const headers = new Headers(IGNGEX_SECURITY_HEADERS)
+        const headers = new Headers(IGNEX_SECURITY_HEADERS)
         headers.set('content-type', 'application/json; charset=utf-8')
         return new Response(payload, { status, headers })
       }

package/src/ingress/server-node.ts

@@ -73,8 +73,7 @@ function nodeRequestToWebRequest(req: IncomingMessage): Request {
   // request actually carries one (content-length > 0 or chunked), so DELETE/
   // OPTIONS-with-a-body are no longer dropped.
   const bodyForbidden = method === 'GET' || method === 'HEAD'
-  const hasBody =
-    Number(req.headers['content-length'] ?? 0) > 0 || req.headers['transfer-encoding'] !== undefined
+  const hasBody = requestHasBody(req)
 
   const init: RequestInit & { duplex?: 'half' } = { method, headers }
 
@@ -143,7 +142,7 @@ async function writeResponse(res: ServerResponse, response: Response): Promise<v
  */
 function drainUnreadBody(res: ServerResponse): void {
   const req = res.req
-  if (req !== undefined && req !== null && !req.complete && hasBody(req)) {
+  if (req !== undefined && req !== null && !req.complete && requestHasBody(req)) {
     req.resume()
     // Only force-close when the request actually carried a body that was not
     // consumed. A bodiless GET/HEAD is always safe to keep alive (bun's
@@ -156,7 +155,7 @@ function drainUnreadBody(res: ServerResponse): void {
 }
 
 /** Whether an incoming request carried a body (content-length or chunked). */
-function hasBody(req: IncomingMessage): boolean {
+function requestHasBody(req: IncomingMessage): boolean {
   return (
     Number(req.headers['content-length'] ?? 0) > 0 || req.headers['transfer-encoding'] !== undefined
   )
@@ -254,6 +253,35 @@ function makeRequestListener(
  * (which owns the frame codec — e.g. the `ws` library). Previously a 101 was
  * written as a normal response and the connection never became a socket.
  */
+/** RFC 6455 subprotocol is an HTTP token (no separators / control bytes). */
+const WS_PROTOCOL_TOKEN = /^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/
+
+/**
+ * Build the RFC 6455 `101 Switching Protocols` response head for a hijacked
+ * socket. `protocol` is emitted only when it is a valid HTTP token, so a caller
+ * that reflects an untrusted `Sec-WebSocket-Protocol` cannot inject CRLF or
+ * extra headers.
+ *
+ * @param accept - The `Sec-WebSocket-Accept` value (must contain no CR/LF).
+ * @param protocol - Optional negotiated subprotocol.
+ * @returns The raw response head, terminated by a blank line.
+ * @throws If `accept` contains a CR/LF.
+ */
+export function formatWebSocketHandshake(accept: string, protocol?: string | null): string {
+  if (/[\r\n]/.test(accept)) {
+    throw new Error('invalid Sec-WebSocket-Accept value')
+  }
+  let raw =
+    'HTTP/1.1 101 Switching Protocols\r\n' +
+    'Upgrade: websocket\r\n' +
+    'Connection: Upgrade\r\n' +
+    `Sec-WebSocket-Accept: ${accept}\r\n`
+  if (protocol && WS_PROTOCOL_TOKEN.test(protocol)) {
+    raw += `Sec-WebSocket-Protocol: ${protocol}\r\n`
+  }
+  return `${raw}\r\n`
+}
+
 function makeUpgradeListener(
   options: CreateIngressServerOptions,
 ): (req: IncomingMessage, socket: Duplex, head: Buffer) => Promise<void> {
@@ -268,16 +296,7 @@ function makeUpgradeListener(
       }
 
       // Complete the RFC 6455 handshake on the hijacked socket.
-      let raw =
-        'HTTP/1.1 101 Switching Protocols\r\n' +
-        'Upgrade: websocket\r\n' +
-        'Connection: Upgrade\r\n' +
-        `Sec-WebSocket-Accept: ${handshake.accept}\r\n`
-      if (handshake.protocol) {
-        raw += `Sec-WebSocket-Protocol: ${handshake.protocol}\r\n`
-      }
-      raw += '\r\n'
-      socket.write(raw)
+      socket.write(formatWebSocketHandshake(handshake.accept, handshake.protocol))
 
       // Hand the upgraded socket to the caller (frame codec / message loop).
       options.onUpgrade?.(socket, req, head)

package/src/ingress/server.ts

@@ -339,11 +339,10 @@ export function buildRouteHandlers(options: BuildRouteHandlersOptions): {
 }
 
 // ── Path matching (shared with server-node.ts + router.ts) ─────────
-// `buildPathMatcher` / `PathMatch` / `safeDecode` live in path-matcher.ts;
-// re-exported here for back-compat (they were historically exported from this
-// module).
+// `PathMatch` / `safeDecode` live in path-matcher.ts and are not part of this
+// module's surface; only `buildPathMatcher` is re-exported for back-compat.
 
-export { buildPathMatcher, type PathMatch, safeDecode } from './path-matcher'
+export { buildPathMatcher } from './path-matcher'
 
 /** Typed options forwarded to `Bun.serve`. */
 interface BunServerOptions {

package/src/ingress/shared.ts

@@ -36,7 +36,7 @@ export const DEFAULT_BAKED_OUTPUT_BUFFER_SIZE = 131_072
  * (`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
+const MAX_OUTPUT_BUFFER_SIZE = 64 * 1024 * 1024
 
 /**
  * Clamp an ingress output-buffer size into `[min, MAX_OUTPUT_BUFFER_SIZE]` so

package/src/ingress/types.ts

@@ -120,6 +120,21 @@ export interface OptimizedIngressHandler {
     retryAfterSecs?: number,
   ): [string, string][]
 
+  /**
+   * Success-path headers as a ready `Headers` instance: the memoized base
+   * (template + reflected origin) plus per-request rate/request-id extras,
+   * without rebuilding `Headers` from an array on every response. Optional so
+   * hand-rolled mocks need not provide it; callers fall back to
+   * `memoizedHeaders(responseHeaders(...))`.
+   */
+  successHeaders?(
+    variant: number,
+    requestIdHeader: string | null,
+    origin: string | null,
+    rateRemaining?: number,
+    rateResetSecs?: number,
+  ): Headers
+
   terminalHeaders(
     variant: number,
     ctx: BakedContext,

package/src/loader/ops.ts

@@ -26,7 +26,7 @@ import { decoder } from '../shared/bytes'
 import type { SchemaValidator } from '../shared/packed'
 
 /** Empty bytes sentinel for skip-on-error scalar parity (e.g. AEAD decrypt). */
-export const EMPTY_BYTES = new Uint8Array(0)
+const EMPTY_BYTES = new Uint8Array(0)
 
 /** Result kinds supported by the loader (mirrors the packed batch wire shapes). */
 export type LoaderResultKind = 'boolean' | 'number' | 'bigint' | 'bytes'