castrum 0.9.0 → 0.9.2

package/src/ingress/index.ts

@@ -1,182 +1,58 @@
-// src/ingress/index.ts — Public ingress API (barrel + sync/async factories)
+// src/ingress/index.ts — Public ingress API (barrel).
 //
-// All constants come from Rust via src/ingress/constants.ts.
-// For maximum performance, use createIngressFast() from ./fast.ts directly.
-// This module wraps createIngressFast with convenience async API (createIngress).
-
-import { decoder } from '../shared/bytes'
-import { generateRequestId } from '../shared/request-id'
-import { assertSyncCallback, DEFAULT_MAX_BODY_BYTES, DEFAULT_BODY_TIMEOUT_MS } from './shared'
-import { createIngressFast } from './fast'
-import { buildResponseContext } from './headers/fast-templates'
-import { buildTerminalResponse } from './response/terminal'
-import { snapshotResult, syntheticContext, internalContext } from './context'
-import { readRequestBodyOnce } from './body'
-import { ERR_CODE_BODY_TOO_LARGE, ERR_CODE_REQUEST_TIMEOUT } from './constants'
-import type { IngressOptions, IngressContext, SyncIngressHandler, IngressHandler } from './types'
-
+// All constants come from Rust via src/ingress/constants.ts. For maximum
+// performance use createIngressFast() from ./fast.ts directly. The convenience
+// factories (`createIngressSync` / `createIngress`) live in ./sync.ts and are
+// re-exported here so this barrel stays a pure re-export hub.
+
+// Runtime-driven server factory: picks Bun.serve on Bun and the node:http
+// adapter on Node via the runtime adapter (src/runtime/server.ts). This
+// explicit re-export SHADOWS the Bun-only `createIngressServer` from
+// './server' (re-exported via './handlers' below) so the public API serves
+// one backend per runtime. `createIngressServerNode` remains exported for
+// consumers who want the Node backend pinned.
+export { createIngressServer } from '../runtime/index'
+export { generateRequestId } from '../shared/request-id'
+export type { TraceContext } from '../shared/trace'
+// W3C trace context helpers (parse `traceparent` for log/hook correlation).
+export {
+  createSpanId,
+  createTraceId,
+  parseTraceParent,
+  serializeTraceParent,
+} from '../shared/trace'
 // ── Re-export the full public ingress API ─────────────────────────
 export * from './constants'
-export * from './status'
 export * from './errors'
-export * from './handlers'
 export { createIngressFast, FastIngressResult } from './fast'
-export { buildTerminalResponse } from './response/terminal'
+export * from './handlers'
+export type { CorsOptions, CorsStaticStrings } from './headers/cors'
+export type { HeaderTemplate, ResponseBuildContext } from './headers/fast-templates'
 export { buildResponseContext, headersForResult } from './headers/fast-templates'
-export { generateRequestId } from '../shared/request-id'
-export { METHOD_KIND, DEFAULT_MAX_BODY_BYTES, DEFAULT_BODY_TIMEOUT_MS } from './shared'
-export type { HeaderPlan } from './shared'
-export type { ResponseBuildContext, HeaderTemplate } from './headers/fast-templates'
-export type { CorsStaticStrings, CorsOptions } from './headers/cors'
 export type { SecurityHeadersOptions } from './headers/hsts'
-export type { IngressFastHandler, IngressFastOptions } from './options'
+export { healthHandler, livenessHandler, readinessHandler } from './health'
+export type { IngressMetrics } from './metrics'
 // ── Observability (zero-dep): metrics, health probes ─────────────
 export { createIngressMetrics, metricsHandler } from './metrics'
-export type { IngressMetrics } from './metrics'
-export { livenessHandler, readinessHandler, healthHandler } from './health'
-// W3C trace context helpers (parse `traceparent` for log/hook correlation).
-export {
-  parseTraceParent,
-  createTraceId,
-  createSpanId,
-  serializeTraceParent,
-} from '../shared/trace'
-export type { TraceContext } from '../shared/trace'
+export type { NativeRoute, NativeRoutePlan } from './native-route'
+export { createNativeRoute } from './native-route'
+// ── Route-wire v3 byte contract (PURE wire helpers) ───────────────
+export * from './packing/route-wire'
+export type { IngressFastHandler, IngressFastOptions } from './options'
+export { buildTerminalResponse } from './response/terminal'
+export type { CreateIngressRouterOptions, IngressRouter, RouterRouteSpec } from './router'
+export { createIngressRouter } from './router'
+export type { HeaderPlan } from './shared'
+export { DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES, METHOD_KIND } from './shared'
+export * from './status'
+// ── Convenience factories (see ./sync.ts) ────────────────────────
+export { createIngress, createIngressSync } from './sync'
 export type {
-  IngressOptions,
   IngressContext,
-  SyncIngressHandler,
   IngressHandler,
+  IngressOptions,
+  NativeRequestContext,
+  NativeResponder,
+  SyncIngressHandler,
+  TerminalStyle,
 } from './types'
-
-// ── Sync factory ─────────────────────────────────────────────────
-
-/**
- * Synchronous convenience wrapper over `createIngressFast` (path 1).
- *
- * The callback runs on the fast-path result and MUST be synchronous. Use
- * {@link createIngress} when you want automatic body reading + error contexts.
- */
-export function createIngressSync(options: IngressOptions = {}): SyncIngressHandler {
-  const fast = createIngressFast(options)
-
-  return {
-    run(req, ip, body, requestId, fn) {
-      return fast.run(req, ip, body, requestId, (result) => {
-        const out = fn(result)
-        assertSyncCallback(out, 'createIngressSync().run()')
-        return out
-      })
-    },
-  }
-}
-
-// ── Async factory ────────────────────────────────────────────────
-
-/**
- * Return a copy of `options` without the security-header keys.
- *
- * `createIngress` applies security headers itself (via `buildResponseContext`),
- * so they must not be forwarded to the underlying fast handler, which rejects
- * them (see `createIngressFast`).
- */
-function stripSecurityOptions(options: IngressOptions): IngressOptions {
-  const copy = { ...options }
-  delete copy.security
-  delete copy.enableSecurityHeaders
-  return copy
-}
-
-/**
- * Async ingress factory: reads the request body (size guard + deadline) and
- * returns a snapshot `IngressContext` with a terminal `Response`.
- *
- * Recommended default for serverless/edge-style `fetch` handlers. For maximum
- * throughput use `createIngressFast` / `createIngressSync` directly.
- */
-export function createIngress(options: IngressOptions = {}): IngressHandler {
-  const sync = createIngressSync(stripSecurityOptions(options))
-
-  const guard = options.enableBodySizeGuard !== false
-  const max = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
-  const bodyTimeoutMs = options.bodyTimeoutMs ?? DEFAULT_BODY_TIMEOUT_MS
-
-  const wantsBody =
-    options.readBody === true ||
-    options.requireJsonBody === true ||
-    options.schema != null ||
-    (options.readBody !== false && guard)
-
-  const responseCtx = buildResponseContext(options)
-
-  return async function ingressAsync(req: Request, ip?: string): Promise<IngressContext> {
-    const requestId = options.enableRequestIds === false ? '' : decoder.decode(generateRequestId())
-    options.onRequest?.(req, requestId, ip)
-
-    // Every terminal outcome (success, 413, 408, 500) flows through here so a
-    // hook consumer sees exactly one onResponse per request.
-    const emitResponse = (context: IngressContext): IngressContext => {
-      options.onResponse?.(req, context, context.status, requestId)
-      return context
-    }
-
-    try {
-      if (guard) {
-        const rawLen = req.headers.get('content-length')
-        const contentLength = Number(rawLen ?? '0')
-
-        if (Number.isFinite(contentLength) && contentLength > max) {
-          return emitResponse(
-            syntheticContext(req, requestId, options, responseCtx, 413, ERR_CODE_BODY_TOO_LARGE),
-          )
-        }
-      }
-
-      let body: Uint8Array | null = null
-
-      if (wantsBody && req.body !== null) {
-        try {
-          body = await readRequestBodyOnce(req, max, guard, bodyTimeoutMs)
-        } catch (err) {
-          const code = (err as { code?: string } | null)?.code
-
-          if (code === 'BODY_TOO_LARGE') {
-            return emitResponse(
-              syntheticContext(req, requestId, options, responseCtx, 413, ERR_CODE_BODY_TOO_LARGE),
-            )
-          }
-
-          if (code === 'REQUEST_TIMEOUT') {
-            // Match the pre-baked route factories: a body-read deadline is a
-            // 408, not a 500 (was silently swallowed as 500 before).
-            return emitResponse(
-              syntheticContext(req, requestId, options, responseCtx, 408, ERR_CODE_REQUEST_TIMEOUT),
-            )
-          }
-
-          // Unknown body-read failure: surface to onError, then fall through
-          // to the internal-error context below.
-          options.onError?.(err instanceof Error ? err : new Error(String(err)))
-          throw err
-        }
-      }
-
-      return emitResponse(
-        sync.run(req, ip, body, requestId, (r) => {
-          const snapshot = snapshotResult(r)
-          const response = buildTerminalResponse(responseCtx, snapshot, req, requestId)
-
-          return {
-            ...snapshot,
-            response,
-          }
-        }),
-      )
-    } catch (err) {
-      // Native/other failures: never silent — report to onError and emit a
-      // structured 500 context so the request still completes observably.
-      options.onError?.(err instanceof Error ? err : new Error(String(err)))
-      return emitResponse(internalContext(req, requestId, options, responseCtx))
-    }
-  }
-}

package/src/ingress/native-route.ts

@@ -0,0 +1,182 @@
+// src/ingress/native-route.ts — public per-route native stack factory.
+//
+// `createNativeRoute` compiles a route-wire v3 descriptor ONCE (via the
+// `castrum_route_*` C-ABI / napi `Route` surface over `rust/ingress/
+// native_route.rs`) and runs each request frame in ONE native call — the same
+// lean per-route stack `@ignex/native`'s `createNativeRoute` consumes. This
+// brings that stack into castrum itself: routes that only need query/cookie
+// parse + `requireJsonBody`/`validateBody` verdicts (no CORS/rate-limit/
+// security/IP/metadata envelope) get the leanest possible per-request path —
+// measured `bench/cost/native-route-vs-router.ts`: ~551ns full JS-glue path
+// vs ~1131ns router `run()` on a parseQuery+parseCookies route (−580ns).
+//
+// IMPURE by design (dlopen + FFI): it lives at the boundary like
+// `handlers.ts`/`server.ts`; the byte wire helpers it uses are the PURE
+// `src/ingress/packing/route-wire.ts`.
+
+import { getBunFFI } from '../native/ffi'
+import { getAddon } from '../native'
+import type { BunFFI } from '../native/ffi/types'
+import {
+  ROUTE_PART,
+  ROUTE_STAGE,
+  decodeRouteResult,
+  encodeRouteDescriptor,
+  packRouteFrame,
+  type RouteStageTag,
+  type RouteWireLimits,
+  type RouteWireResult,
+} from './packing/route-wire'
+
+/** Plan for a compiled native route (the stage/limit/schema surface). */
+export interface NativeRoutePlan {
+  /** Parse + lenient-decode the query string into pairs (stage 0). */
+  parseQuery?: boolean
+  /** Parse + lenient-decode the Cookie header into pairs (stage 1). */
+  parseCookies?: boolean
+  /** Reject a missing / non-JSON body with 400 (stage 5, first-failure-wins). */
+  requireJsonBody?: boolean
+  /** Validate the body against `schema` with 422 on failure (stage 4). */
+  validateBody?: boolean
+  /** Draft-07 JSON schema bytes for the body (`validateBody`). */
+  schema?: Uint8Array
+  /** Max body bytes before `requireJsonBody`/`validateBody` fail (default 2 MiB). */
+  maxBodyBytes?: number
+  /** Max query bytes before the parse VALID bit clears (default 8192). */
+  maxQueryBytes?: number
+  /** Max cookie bytes before the parse VALID bit clears (default 8192). */
+  maxCookieBytes?: number
+  /** Max pairs per section (0 = unlimited; default 0). */
+  maxPairs?: number
+}
+
+/** A compiled per-route native stack (route-wire v3). */
+export interface NativeRoute {
+  /** Whether the plan compiled `parseQuery` (the result carries a query section). */
+  readonly parseQuery: boolean
+  /** Whether the plan compiled `parseCookies` (the result carries a cookie section). */
+  readonly parseCookies: boolean
+  /**
+   * Run one request frame through the compiled stack and return the decoded
+   * verdict. The frame is `[flags u32][qLen][query][cLen][cookie]([bLen][body])`
+   * — build it with {@link packRouteFrame}. Reuses one growable output buffer
+   * (the needed-size convention: `0` = real error → throws; `> out.length` =
+   * exact required size → retry once).
+   */
+  runFrame(frame: Uint8Array): RouteWireResult
+  /** Convenience: pack a `(query, cookie, body)` frame then {@link runFrame}. */
+  run(query: string, cookie: string, body: Uint8Array | null): RouteWireResult
+  /** Free the native handle (idempotent; safe to call once at shutdown). */
+  destroy(): void
+}
+
+/**
+ * Compile a per-route native stack from a plan. Returns a compiled route whose
+ * `run`/`runFrame` perform the parse + verdict in ONE native call.
+ *
+ * @example
+ * ```ts
+ * const route = createNativeRoute({ parseQuery: true, parseCookies: true })
+ * const result = route.run('page=1&limit=20', 'session=abc', null)
+ * // result.flags & ROUTE_FLAG.OK → parse succeeded; result.query = [['page','1'],…]
+ * ```
+ */
+export function createNativeRoute(plan: NativeRoutePlan = {}): NativeRoute {
+  const limits: RouteWireLimits = {
+    maxBodyBytes: plan.maxBodyBytes ?? 2 * 1024 * 1024,
+    maxQueryBytes: plan.maxQueryBytes ?? 8192,
+    maxCookieBytes: plan.maxCookieBytes ?? 8192,
+    maxPairs: plan.maxPairs ?? 0,
+  }
+
+  // Stage order is first-failure-wins on the native side, so the descriptor
+  // pipeline mirrors the plan's semantics: parse stages first, then body
+  // verdicts (validateBody before requireJsonBody per the Rust compile — it
+  // emits requireJsonBody first defensively; the native side treats the pair
+  // as "require then validate" and the compiler guarantees the order).
+  const stages: RouteStageTag[] = []
+  if (plan.parseQuery) stages.push(ROUTE_STAGE.parseQuery)
+  if (plan.parseCookies) stages.push(ROUTE_STAGE.parseCookies)
+  if (plan.validateBody) stages.push(ROUTE_STAGE.validateBody)
+  if (plan.requireJsonBody) stages.push(ROUTE_STAGE.requireJsonBody)
+
+  const schemas: Array<{ part: number; bytes: Uint8Array }> = []
+  if (plan.validateBody && plan.schema) {
+    schemas.push({ part: ROUTE_PART.body, bytes: plan.schema })
+  }
+
+  const descriptor = encodeRouteDescriptor(stages, schemas, limits)
+  const parseQuery = plan.parseQuery === true
+  const parseCookies = plan.parseCookies === true
+
+  // Transport: bun:ffi PRIMARY on Bun; napi `Route` on Node / fallback. The
+  // compiled route owns exactly one handle; `destroy` frees it.
+  const bunFFI: BunFFI | null = getBunFFI()
+  const ffiHandle = bunFFI !== null ? compileFfi(bunFFI, descriptor) : 0
+  const napiRoute = bunFFI === null ? compileNapi(descriptor) : null
+
+  // Reusable output buffer for the needed-size convention (grow once, retry).
+  let out = new Uint8Array(256)
+
+  const runFrame = (frame: Uint8Array): RouteWireResult => {
+    let written: number
+    if (ffiHandle !== 0 && bunFFI !== null) {
+      written = bunFFI.routeRun(ffiHandle, frame, out)
+      if (written > out.byteLength) {
+        // Exact required size reported — grow and retry once.
+        out = new Uint8Array(written)
+        written = bunFFI.routeRun(ffiHandle, frame, out)
+        if (written > out.byteLength) {
+          throw new Error('native route: output still too small after grow')
+        }
+      }
+    } else if (napiRoute !== null) {
+      written = napiRoute.run(frame, out)
+      if (written > out.byteLength) {
+        out = new Uint8Array(written)
+        written = napiRoute.run(frame, out)
+        if (written > out.byteLength) {
+          throw new Error('native route: output still too small after grow')
+        }
+      }
+    } else {
+      throw new Error('native route: no active transport')
+    }
+    return decodeRouteResult(out.subarray(0, written), { query: parseQuery, cookie: parseCookies })
+  }
+
+  return {
+    parseQuery,
+    parseCookies,
+    runFrame,
+    run: (query, cookie, body) => runFrame(packRouteFrame(query, cookie, body)),
+    destroy: () => {
+      if (ffiHandle !== 0 && bunFFI !== null) {
+        bunFFI.routeDestroy(ffiHandle)
+      }
+    },
+  }
+}
+
+/** Compile through bun:ffi (`castrum_route_compile`), returning the handle (0 = error). */
+function compileFfi(bunFFI: BunFFI, descriptor: Uint8Array): number {
+  try {
+    return bunFFI.routeCompile(descriptor)
+  } catch {
+    return 0 // routeCompile throws on an invalid descriptor; treat as no-handle
+  }
+}
+
+/** Compile through the napi `Route` class (Node / fallback transport). */
+function compileNapi(descriptor: Uint8Array): { run: (frame: Uint8Array, out: Uint8Array) => number } | null {
+  const addon = getAddon()
+  const Route = (addon as { Route?: new (d: Uint8Array) => { run: (f: Uint8Array, o: Uint8Array) => number } }).Route
+  if (typeof Route !== 'function') {
+    return null // addon without the route stack (pre-rebuild) — caller falls back
+  }
+  try {
+    return new Route(descriptor)
+  } catch {
+    return null
+  }
+}

package/src/ingress/packing/gather-raw-headers.ts

@@ -7,10 +7,10 @@
 // guards so oversized values are dropped rather than forwarded.
 
 import type { HeaderPlan } from '../shared'
+import { METHOD_KIND } from '../shared'
 import { writeHeaderPair } from './header-packing'
-import { forEachSelectedHeader } from './select-headers'
-import { getHeaderBuf } from './scratch'
-import { decoder } from '../../shared/bytes'
+import { forEachSelectedHeader, HDR_ORIGIN } from './select-headers'
+import { getHeaderBuf, MAX_SMALL_HEADER_BYTES } from './scratch'
 
 // Shared per-header size guards (single source of truth in scratch.ts).
 // Re-exported for back-compat with imports that referenced them here.
@@ -20,32 +20,29 @@ export {
   MAX_XFF_HEADER_BYTES,
 } from './scratch'
 
-/**
- * Gather the request headers selected by `plan` as a `[name, value][]` array.
- * `methodKind` is the native method-kind enum (see `METHOD_KIND`).
- */
-export function gatherRawHeaders(
-  req: Request,
-  plan: HeaderPlan,
-  methodKind: number,
-): [string, string][] {
-  const headers: [string, string][] = []
-  forEachSelectedHeader(req, plan, methodKind, undefined, (name, value) => {
-    headers.push([decoder.decode(name), value])
-  })
-  return headers
-}
-
 /**
  * Gather the request headers selected by `plan` as a packed byte block
  * (`[u16 count] { [u16 name_len][name][u32 val_len][value] }`) written into a
  * reusable thread-local buffer.
  *
- * This is the zero-intermediate-string equivalent of [`gatherRawHeaders`] for
- * the packed-input pipeline: identical header selection and per-header size
+ * This is the zero-intermediate-string equivalent of the legacy string-array
+ * header gathering (a test-local reference in header-packing.test.ts) for the
+ * packed-input pipeline: identical header selection and per-header size
  * guards, but no `[string, string][]` array and no napi string marshaling.
  * The returned view is valid only until the next call on this call site.
  *
+ * A plan that selects NO headers (no cookie/cors/proxy/proto) short-circuits
+ * to a shared empty block — skipping the scratch-buffer round-robin, the
+ * `setUint16` and the per-call `subarray` entirely (the common minimal-route
+ * case).
+ *
+ * A CORS-ONLY plan on a non-preflight request (the dominant minimal-route
+ * case, e.g. the benchmark server) produces a block that depends ONLY on the
+ * `Origin` header value — which is constant per deployment. Such blocks are
+ * cached keyed by origin, so the per-request UTF-8 encode of the origin (the
+ * largest single JS packing cost) and the scratch write are skipped entirely;
+ * the cache is bounded (FIFO eviction) so multi-origin deployments stay safe.
+ *
  * @param originValue - When provided (non-undefined), the already-fetched
  *   `Origin` header value to pack, avoiding a second `req.headers.get('origin')`
  *   native→JS string conversion per request on the hot path (the caller, e.g.
@@ -59,6 +56,48 @@ export function gatherRawHeadersPacked(
   methodKind: number,
   originValue?: string | null,
 ): Uint8Array {
+  if (!plan.cookie && !plan.cors && !plan.proxy && !plan.proto) {
+    return EMPTY_HEADERS_BLOCK
+  }
+
+  const nonPreflight = methodKind !== METHOD_KIND.OPTIONS
+
+  // CORS-only fast path: the only selected header is the (typically constant)
+  // Origin, so the whole packed block is a pure function of the origin string.
+  // Skip the per-request encode + scratch write by returning the cached block.
+  // Preflight (OPTIONS) is excluded — it also packs ACRM/ACRH and must take
+  // the general path. The MAX_SMALL_HEADER_BYTES guard mirrors the general
+  // path (an oversized origin is dropped → empty block, not cached).
+  if (plan.cors && !plan.cookie && !plan.proxy && !plan.proto && nonPreflight) {
+    const origin = originValue !== undefined ? originValue : req.headers.get('origin')
+    if (origin === null || origin.length > MAX_SMALL_HEADER_BYTES) {
+      return EMPTY_HEADERS_BLOCK
+    }
+    return cachedOriginBlock(origin)
+  }
+
+  // cookie+cors fast path: when the request carries NO cookie header (the
+  // dominant API/bench case), the packed block is still origin-only, so the
+  // (typically constant) origin can reuse the cached block instead of being
+  // UTF-8 re-encoded + re-packed on every request. Byte-identical to the
+  // general path, which would visit ONLY the origin when the cookie is absent:
+  //   - cookie null + origin present → `[u16 1][origin pair]`  (cached block)
+  //   - cookie null + origin absent → `[u16 0]`               (EMPTY block)
+  //   - cookie null + origin oversized → dropped → `[u16 0]`  (EMPTY block)
+  // When a cookie IS present, fall through to the general path but hand the
+  // already-fetched value down (no second `req.headers.get('cookie')`).
+  let preFetchedCookie: string | null | undefined
+  if (plan.cors && plan.cookie && !plan.proxy && !plan.proto && nonPreflight) {
+    preFetchedCookie = req.headers.get('cookie')
+    if (preFetchedCookie === null) {
+      const origin = originValue !== undefined ? originValue : req.headers.get('origin')
+      if (origin === null || origin.length > MAX_SMALL_HEADER_BYTES) {
+        return EMPTY_HEADERS_BLOCK
+      }
+      return cachedOriginBlock(origin)
+    }
+  }
+
   let [buf, view] = getHeaderBuf()
   let pos = 2
   let count = 0
@@ -68,8 +107,57 @@ export function gatherRawHeadersPacked(
     count++
   }
 
-  forEachSelectedHeader(req, plan, methodKind, originValue, write)
+  forEachSelectedHeader(req, plan, methodKind, originValue, write, preFetchedCookie)
+
+  // No selected header was actually present (e.g. a route with cookie+cors in
+  // its plan but a request that sends neither) — return the shared empty block
+  // instead of touching the scratch buffer again (setUint16 + subarray) on the
+  // hot path.
+  if (count === 0) {
+    return EMPTY_HEADERS_BLOCK
+  }
 
   view.setUint16(0, count, true)
   return buf.subarray(0, pos)
 }
+
+/** Shared `[0, 0]` (zero headers) block — returned when a plan selects nothing.
+ *  Callers treat the result as read-only (the packers copy it verbatim). */
+const EMPTY_HEADERS_BLOCK = new Uint8Array(2)
+
+/**
+ * Cached packed blocks for the CORS-only case, keyed by origin string.
+ * Bounded (FIFO eviction) — a multi-origin deployment never grows it
+ * unboundedly, and a single-origin deployment hits a stable single entry.
+ * Module state is per-thread in Bun workers, so no cross-thread aliasing.
+ */
+const ORIGIN_BLOCK_CACHE = new Map<string, Uint8Array>()
+const ORIGIN_CACHE_MAX = 8
+
+/**
+ * Return (building and caching on first use) the packed header block for a
+ * CORS-only plan whose only selected header is `origin`.
+ *
+ * The block is byte-identical to what the general path would produce
+ * (`[u16 1][u16 name_len]['origin'][u32 val_len][value]`), built once with the
+ * shared `writeHeaderPair` and copied out of the scratch buffer into a stable
+ * allocation — never aliased to the round-robin scratch, so it stays valid
+ * across subsequent gathers.
+ */
+function cachedOriginBlock(origin: string): Uint8Array {
+  const hit = ORIGIN_BLOCK_CACHE.get(origin)
+  if (hit !== undefined) return hit
+
+  let [buf, view] = getHeaderBuf()
+  let pos = 2
+  ;[pos, buf, view] = writeHeaderPair(buf, view, pos, HDR_ORIGIN, origin)
+  view.setUint16(0, 1, true)
+  const block = buf.slice(0, pos)
+
+  if (ORIGIN_BLOCK_CACHE.size >= ORIGIN_CACHE_MAX) {
+    const firstKey = ORIGIN_BLOCK_CACHE.keys().next().value
+    if (firstKey !== undefined) ORIGIN_BLOCK_CACHE.delete(firstKey)
+  }
+  ORIGIN_BLOCK_CACHE.set(origin, block)
+  return block
+}

package/src/ingress/packing/header-packing.ts

@@ -5,12 +5,11 @@
 // scratch buffers keeps this allocation-free on the hot path while isolating
 // the buffers per call-site sequence.
 
-import { METHOD_KIND, METHOD_KIND_UNKNOWN, type HeaderPlan } from '../shared'
+import { encodeUtf8Into } from '../../shared/codec'
+import { type HeaderPlan, METHOD_KIND, METHOD_KIND_UNKNOWN } from '../shared'
 import { getHeaderBuf } from './scratch'
 import { forEachSelectedHeader } from './select-headers'
 
-const encoder = new TextEncoder()
-
 /**
  * Write one header pair into `buf`/`view`, growing them if needed.
  *
@@ -43,8 +42,9 @@ export function writeHeaderPair(
   const valueLenPos = pos
   pos += 4
 
-  const dest = buf.subarray(pos)
-  const { written } = encoder.encodeInto(value, dest)
+  // Number-returning codec write directly at `pos` (no `{read, written}`
+  // object, no intermediate `subarray` — both were per-header allocations).
+  const written = encodeUtf8Into(value, buf, pos)
 
   view.setUint32(valueLenPos, written, true)
   pos += written

package/src/ingress/packing/input-packer.ts

@@ -4,7 +4,8 @@
 // headers) into a single growable Uint8Array in the layout the native
 // `Ingress.handleRequestPacked` expects.
 
-const encoder = new TextEncoder()
+import { encoder } from '../../shared/bytes'
+
 const EMPTY_BYTES = new Uint8Array(0)
 const EMPTY_IP_BYTES = encoder.encode('0.0.0.0')
 
@@ -12,6 +13,10 @@ const EMPTY_IP_BYTES = encoder.encode('0.0.0.0')
 export class IngressInputPacker {
   private buf: Uint8Array
   private view: DataView
+  /** Cached zero-copy `Buffer` view over `buf`'s backing store (invalidated
+   *  when `buf` grows). `Buffer.write` needs a Buffer; caching it here avoids
+   *  a per-string view/`Buffer.from` allocation on the hot pack path. */
+  private bufView: Buffer | null = null
   private pos = 0
 
   constructor(initialSize = 65536) {
@@ -33,6 +38,7 @@ export class IngressInputPacker {
 
     this.buf = next
     this.view = new DataView(next.buffer)
+    this.bufView = null
   }
 
   private writeU8(value: number): void {
@@ -76,8 +82,16 @@ export class IngressInputPacker {
     this.ensure(4 + value.length * 3)
     const valueLenPos = this.pos
     this.pos += 4
-    const dest = this.buf.subarray(this.pos)
-    const { written } = encoder.encodeInto(value, dest)
+    // Reused `Buffer` view over this buffer: `Buffer.write` encodes the string
+    // in place at the current position and returns bytes written — no
+    // `{read, written}` object, no `Buffer.from`/subarray per string (those
+    // were per-request allocations on this hot path).
+    let view = this.bufView
+    if (view === null) {
+      view = Buffer.from(this.buf.buffer, this.buf.byteOffset, this.buf.byteLength)
+      this.bufView = view
+    }
+    const written = view.write(value, this.pos, 'utf8')
     this.view.setUint32(valueLenPos, written, true)
     this.pos += written
   }