castrum 0.7.0 → 0.9.0

package/src/ingress/metrics.ts

@@ -0,0 +1,132 @@
+// src/ingress/metrics.ts — Ingress observability wiring (zero-dep).
+//
+// `createIngressMetrics()` builds a {@link MetricsRegistry} and returns the
+// `onRequest`/`onResponse`/`onError` hooks to pass into `createIngressHandler`'s
+// runtime, so every request is counted + latency-histogrammed. Expose the
+// numbers at a `/metrics` endpoint with {@link metricsHandler} (Prometheus text
+// format), served by both `createIngressServer` (Bun) and
+// `createIngressServerNode` (Node).
+//
+//   const m = createIngressMetrics();
+//   const ingress = createIngressHandler(options, { ...m.runtime });
+//   const srv = createIngressServer({ routes: {
+//     "/health": { read: livenessHandler() },
+//     "/metrics": { read: metricsHandler(m) },
+//   }});
+
+import { createMetrics, DEFAULT_BUCKETS, type MetricsRegistry } from '../shared/metrics'
+import type { BakedIngressResult } from './decode/baked-result'
+import type { BakedIngressRuntime } from './handlers'
+
+/** The runtime hooks + registry for ingress metrics. */
+export interface IngressMetrics {
+  registry: MetricsRegistry
+  /** Pass as the runtime to `createIngressHandler`. */
+  runtime: Pick<BakedIngressRuntime, 'onRequest' | 'onResponse' | 'onError'>
+  /** Render the Prometheus exposition. */
+  render(): string
+}
+
+/**
+ * Build ingress request/error/latency metrics wired to the pre-baked handler
+ * runtime hooks. Metric names follow the Prometheus `castrum_http_*` scheme.
+ */
+export function createIngressMetrics(): IngressMetrics {
+  const registry = createMetrics()
+
+  const requestsTotal = registry.counter(
+    'castrum_http_requests_total',
+    'Total ingress requests processed.',
+    ['method', 'status'],
+  )
+  const requestDuration = registry.histogram(
+    'castrum_http_request_duration_seconds',
+    'Ingress request latency in seconds.',
+    DEFAULT_BUCKETS,
+    ['method', 'status'],
+  )
+  const errorsTotal = registry.counter(
+    'castrum_http_errors_total',
+    'Total internal/terminal errors.',
+    ['code'],
+  )
+  const rateLimitedTotal = registry.counter(
+    'castrum_http_rate_limited_total',
+    'Total requests rejected by the rate limiter (429).',
+  )
+  const inFlight = registry.gauge(
+    'castrum_http_in_flight_requests',
+    'Requests currently being processed.',
+  )
+
+  const statusLabel = (status: number): string => String(status)
+
+  // Per-request in-flight accounting keyed by the request id (also surfaced in
+  // logs/metrics). This makes the gauge EXACTLY-ONCE per request, which matters
+  // because the baked handler can fire both `onError` and `onResponse` for the
+  // same request (native pipeline failure), or only `onError` (a throwing route
+  // callback). Without it the gauge either double-decrements or leaks, and the
+  // latency histogram reads 0 (result.startTime was never set anywhere).
+  // NOTE: error-ended requests (onError fired) are counted via requestsTotal +
+  // errorsTotal but not latency-sampled — the duration histogram only observes
+  // requests that complete through onResponse.
+  const active = new Map<string, number>()
+
+  return {
+    registry,
+    runtime: {
+      onRequest(_req, requestId, _ip) {
+        if (requestId) {
+          active.set(requestId, performance.now())
+        }
+        inFlight.inc()
+      },
+      onResponse(req, result: BakedIngressResult, status, requestId) {
+        const method = req.method ?? 'unknown'
+        const statusKey = statusLabel(status)
+        requestsTotal.inc({ method, status: statusKey })
+        // Only a request that has not already ended (via onError) records its
+        // latency and decrements the gauge here.
+        const started = requestId ? active.get(requestId) : undefined
+        if (started !== undefined) {
+          active.delete(requestId)
+          inFlight.dec()
+          requestDuration.observe(Math.max(performance.now() - started, 0) / 1000, {
+            method,
+            status: statusKey,
+          })
+        }
+        if (result.rateLimited) rateLimitedTotal.inc()
+      },
+      onError(_req, requestId, error) {
+        // Ends the request's gauge accounting exactly once (a later onResponse
+        // for the same request id becomes a no-op for the gauge). When only
+        // onError fires (throwing callback), this is what un-leaks inFlight.
+        if (requestId && active.delete(requestId)) {
+          inFlight.dec()
+        }
+        errorsTotal.inc({ code: error?.name ?? 'internal' })
+      },
+    },
+    render() {
+      return registry.render()
+    },
+  }
+}
+
+/**
+ * Route handler exposing the registry in Prometheus text format
+ * (`content-type: text/plain; version=0.0.4`). Serve it as a `read` route:
+ *
+ *   createIngressServer({ routes: { "/metrics": { read: metricsHandler(m) } } })
+ */
+export function metricsHandler(metrics: IngressMetrics) {
+  return (_req: Request): Response =>
+    new Response(metrics.render(), {
+      status: 200,
+      headers: {
+        'content-type': 'text/plain; version=0.0.4; charset=utf-8',
+        'cache-control': 'no-store',
+      },
+    })
+}

package/src/ingress/options.ts

@@ -0,0 +1,197 @@
+// src/ingress/options.ts — IngressFast option types + fail-fast validation.
+//
+// Options are forwarded to the native addon as a plain object; a misspelled
+// key would otherwise be silently ignored. Validation against the known key
+// set makes misconfiguration fail loudly at construction time.
+
+/** Options accepted by `createIngressFast` / `createIngress`. */
+export interface IngressFastOptions {
+  trustProxy?: boolean
+  trustedProxies?: { enabled?: boolean; networks?: string[] }
+  parseCookies?: boolean
+  parseQuery?: boolean
+  requireJsonBody?: boolean
+  schema?: Uint8Array
+  cors?: CorsOptions
+  rateLimit?: { limit?: number; windowMs?: number; maxEntries?: number }
+  /**
+   * Structured security-header options (CSP/HSTS) — honored by the fast/async
+   * paths (`createIngressFast` throws on it; `createIngress` applies it via
+   * `buildResponseContext`). The PRE-BAKED path (`createIngressHandler`)
+   * instead takes raw `securityHeaders: [name, value][]` pairs. The two paths
+   * intentionally use different option shapes (see docs/INGRESS.md).
+   */
+  security?: SecurityHeadersOptions
+  https?: boolean
+  maxBodyBytes?: number
+  enableSecurityHeaders?: boolean
+  enableRequestIds?: boolean
+  enableBodySizeGuard?: boolean
+  emitMetadataJson?: boolean
+  readBody?: boolean
+  outputBufferSize?: number
+  /**
+   * Overall deadline (ms) for reading a request body in the async
+   * `createIngress` path. 0 disables. Default: `DEFAULT_BODY_TIMEOUT_MS` (30s).
+   * Ignored by the sync `createIngressFast` (it does not read bodies).
+   */
+  bodyTimeoutMs?: number
+  /**
+   * Invoked when the native pipeline throws (the request becomes a 500).
+   * Native failures are otherwise silent in the fast path. Never throws.
+   */
+  onError?: (error: Error) => void
+  /**
+   * When true, run one probe GET at construction so the `run()` closure,
+   * packed pipeline and FFI ingress call are JIT-warmed before the first real
+   * request (cuts cold-invocation tail latency in serverless-style
+   * deployments). Opt-in; default false. Not forwarded to the native addon.
+   */
+  warmOnCreate?: boolean
+  limits?: {
+    maxUrlBytes?: number
+    maxQueryBytes?: number
+    maxCookieBytes?: number
+    maxHeadersBytes?: number
+    maxHeaders?: number
+    maxPairs?: number
+  }
+}
+
+/** The zero-alloc sync handler returned by `createIngressFast`. */
+export interface IngressFastHandler {
+  run<T>(
+    req: Request,
+    ip: string | undefined,
+    body: Uint8Array | null,
+    requestId: string,
+    fn: (result: FastIngressResult) => T,
+  ): T
+}
+
+/**
+ * Options accepted by `createIngressHandler` (path 2).
+ *
+ * Same native option surface as the fast path, minus `onError` — path 2
+ * reports native failures through `BakedIngressRuntime.onError` instead of the
+ * options bag.
+ */
+export type IngressHandlerOptions = Omit<IngressFastOptions, 'onError'>
+
+import type { CorsOptions } from './headers/cors'
+import type { SecurityHeadersOptions } from './headers/hsts'
+import type { FastIngressResult } from './decode/fast-result'
+
+const KNOWN_INGRESS_OPTION_KEYS: ReadonlySet<string> = new Set([
+  'trustProxy',
+  'trustedProxies',
+  'parseCookies',
+  'parseQuery',
+  'requireJsonBody',
+  'schema',
+  'cors',
+  'rateLimit',
+  'security',
+  'https',
+  'maxBodyBytes',
+  'enableSecurityHeaders',
+  'enableRequestIds',
+  'enableBodySizeGuard',
+  'emitMetadataJson',
+  'readBody',
+  'outputBufferSize',
+  'bodyTimeoutMs',
+  'onError',
+  'onRequest',
+  'onResponse',
+  'limits',
+  'warmOnCreate',
+])
+
+/**
+ * Throw if `options` contains a key the ingress pipeline does not know.
+ *
+ * `label` names the calling factory in the error so a typo is easy to map
+ * back to the call site (both `createIngressFast` and `createIngressHandler`
+ * validate the same option surface).
+ */
+export function assertKnownIngressOptions(
+  options: IngressFastOptions,
+  label = 'createIngressFast',
+): void {
+  for (const key of Object.keys(options)) {
+    if (!KNOWN_INGRESS_OPTION_KEYS.has(key)) {
+      throw new TypeError(
+        `${label}: unknown option '${key}'. ` +
+          `Known options: ${[...KNOWN_INGRESS_OPTION_KEYS].sort().join(', ')}`,
+      )
+    }
+  }
+}
+
+/** Numeric options that must be finite and non-negative (0 is meaningful, e.g.
+ * `rateLimit.limit: 0` disables the limiter). Dotted = nested option. */
+const NON_NEGATIVE_NUMBER_OPTIONS: ReadonlyArray<readonly [path: string, root: string]> = [
+  ['maxBodyBytes', 'maxBodyBytes'],
+  ['bodyTimeoutMs', 'bodyTimeoutMs'],
+  ['outputBufferSize', 'outputBufferSize'],
+  ['rateLimit.limit', 'rateLimit'],
+  ['rateLimit.windowMs', 'rateLimit'],
+  ['rateLimit.maxEntries', 'rateLimit'],
+  ['limits.maxUrlBytes', 'limits'],
+  ['limits.maxQueryBytes', 'limits'],
+  ['limits.maxCookieBytes', 'limits'],
+  ['limits.maxHeadersBytes', 'limits'],
+  ['limits.maxHeaders', 'limits'],
+  ['limits.maxPairs', 'limits'],
+]
+
+function assertNonNegativeNumber(value: unknown, path: string, label: string): void {
+  if (typeof value === 'number' && (!Number.isFinite(value) || value < 0)) {
+    throw new TypeError(
+      `${label}: option '${path}' must be a finite, non-negative number (got ${value}).`,
+    )
+  }
+}
+
+/**
+ * Fail-fast on non-finite / negative numeric option values. `assertKnownIngressOptions`
+ * only checks the key set; a misconfigured negative value (e.g. `maxBodyBytes: -1`)
+ * would otherwise silently corrupt the pipeline (a napi marshal error or an
+ * always-rejecting limit).
+ */
+export function assertIngressOptionValues(
+  options: IngressFastOptions,
+  label = 'createIngressFast',
+): void {
+  for (const [path, root] of NON_NEGATIVE_NUMBER_OPTIONS) {
+    if (path.includes('.')) {
+      const [, inner] = path.split('.')
+      const obj = (options as Record<string, unknown>)[root] as Record<string, unknown> | undefined
+      assertNonNegativeNumber(obj?.[inner ?? ''], path, label)
+    } else {
+      assertNonNegativeNumber((options as Record<string, unknown>)[path], path, label)
+    }
+  }
+}
+
+let trustProxyWarned = false
+
+/**
+ * Warn once (per process) when the legacy `trustProxy: true` boolean is used.
+ *
+ * `trustProxy: true` makes the pipeline trust EVERY hop of
+ * `X-Forwarded-For`/`X-Real-IP`, so a client can forge its IP and bypass
+ * IP-based rate limiting. Prefer the `trustedProxies` network-list API and
+ * only enable proxy trust behind a trusted edge.
+ */
+export function warnTrustProxyDeprecated(): void {
+  if (trustProxyWarned) return
+  trustProxyWarned = true
+  console.warn(
+    '[castrum] WARN: `trustProxy: true` is deprecated and trusts EVERY hop — ' +
+      'clients can spoof X-Forwarded-For / X-Real-IP to bypass IP-based rate ' +
+      'limiting. Use `trustedProxies: { enabled: true, networks: [...] }` and ' +
+      'only enable proxy trust behind a trusted edge.',
+  )
+}

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

@@ -0,0 +1,75 @@
+// src/ingress/packing/gather-raw-headers.ts — Raw header gathering (pre-baked
+// path).
+//
+// The pre-baked path passes headers to the native addon as a plain
+// [name, value][] array (the addon packs them internally in Rust). This module
+// extracts exactly the headers selected by a HeaderPlan, with per-header size
+// guards so oversized values are dropped rather than forwarded.
+
+import type { HeaderPlan } from '../shared'
+import { writeHeaderPair } from './header-packing'
+import { forEachSelectedHeader } from './select-headers'
+import { getHeaderBuf } from './scratch'
+import { decoder } from '../../shared/bytes'
+
+// Shared per-header size guards (single source of truth in scratch.ts).
+// Re-exported for back-compat with imports that referenced them here.
+export {
+  MAX_COOKIE_HEADER_BYTES,
+  MAX_SMALL_HEADER_BYTES,
+  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
+ * 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.
+ *
+ * @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.
+ *   `handlers.ts::run`, already fetched it once for `ctx.origin`). When
+ *   omitted, the origin is fetched here as before (back-compat). The same
+ *   `MAX_SMALL_HEADER_BYTES` size guard still applies either way.
+ */
+export function gatherRawHeadersPacked(
+  req: Request,
+  plan: HeaderPlan,
+  methodKind: number,
+  originValue?: string | null,
+): Uint8Array {
+  let [buf, view] = getHeaderBuf()
+  let pos = 2
+  let count = 0
+
+  const write = (name: Uint8Array, value: string): void => {
+    ;[pos, buf, view] = writeHeaderPair(buf, view, pos, name, value)
+    count++
+  }
+
+  forEachSelectedHeader(req, plan, methodKind, originValue, write)
+
+  view.setUint16(0, count, true)
+  return buf.subarray(0, pos)
+}

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

@@ -0,0 +1,75 @@
+// src/ingress/packing/header-packing.ts — Binary header packing (fast path).
+//
+// Packs the request headers selected by a HeaderPlan directly into a reusable
+// Uint8Array with no intermediate strings. A bounded thread-local pool of
+// 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 { getHeaderBuf } from './scratch'
+import { forEachSelectedHeader } from './select-headers'
+
+const encoder = new TextEncoder()
+
+/**
+ * Write one header pair into `buf`/`view`, growing them if needed.
+ *
+ * IMPORTANT: the header block can exceed `HEADER_BUF_SIZE` (e.g. a very large
+ * cookie or origin header). When that happens `buf`/`view` are replaced by a
+ * larger buffer, so the (possibly grown) buffer + view are returned alongside
+ * the new position. Callers MUST thread the returned buffer/view back into
+ * subsequent writes — otherwise the grown bytes are written into a discarded
+ * array and the packed output is silently corrupted.
+ */
+export function writeHeaderPair(
+  buf: Uint8Array,
+  view: DataView,
+  pos: number,
+  name: Uint8Array,
+  value: string,
+): [pos: number, buf: Uint8Array, view: DataView] {
+  const needed = 2 + name.length + 4 + value.length * 3
+  if (pos + needed > buf.length) {
+    const next = new Uint8Array(Math.max(buf.length * 2, pos + needed))
+    next.set(buf.subarray(0, pos))
+    buf = next
+    view = new DataView(buf.buffer)
+  }
+
+  view.setUint16(pos, name.length, true)
+  buf.set(name, pos + 2)
+  pos += 2 + name.length
+
+  const valueLenPos = pos
+  pos += 4
+
+  const dest = buf.subarray(pos)
+  const { written } = encoder.encodeInto(value, dest)
+
+  view.setUint32(valueLenPos, written, true)
+  pos += written
+
+  return [pos, buf, view]
+}
+
+/** Pack the headers selected by `plan` into a reusable Uint8Array. */
+export function packHeaders(req: Request, plan: HeaderPlan): Uint8Array {
+  let [buf, view] = getHeaderBuf()
+  let pos = 2
+  let count = 0
+
+  // Selection rules + per-header size guards live in forEachSelectedHeader
+  // (single source of truth shared with the pre-baked path): an oversized
+  // value is dropped rather than forwarded so the packed block can never
+  // exceed the native `max_headers_bytes` (65536) and 500.
+  const write = (name: Uint8Array, value: string): void => {
+    ;[pos, buf, view] = writeHeaderPair(buf, view, pos, name, value)
+    count++
+  }
+
+  const methodKind = METHOD_KIND[req.method] ?? METHOD_KIND_UNKNOWN
+  forEachSelectedHeader(req, plan, methodKind, undefined, write)
+
+  view.setUint16(0, count, true)
+  return buf.subarray(0, pos)
+}

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

@@ -0,0 +1,150 @@
+// src/ingress/packing/input-packer.ts — Binary-packed ingress input builder.
+//
+// Packs the per-request inputs (method kind + url + ip + request id + packed
+// headers) into a single growable Uint8Array in the layout the native
+// `Ingress.handleRequestPacked` expects.
+
+const encoder = new TextEncoder()
+const EMPTY_BYTES = new Uint8Array(0)
+const EMPTY_IP_BYTES = encoder.encode('0.0.0.0')
+
+/** Growable packer for the fast-path packed input buffer. */
+export class IngressInputPacker {
+  private buf: Uint8Array
+  private view: DataView
+  private pos = 0
+
+  constructor(initialSize = 65536) {
+    this.buf = new Uint8Array(Math.max(1024, initialSize))
+    this.view = new DataView(this.buf.buffer)
+  }
+
+  private ensure(additional: number): void {
+    const needed = this.pos + additional
+    if (needed <= this.buf.byteLength) return
+
+    let nextSize = this.buf.byteLength * 2
+    while (nextSize < needed) {
+      nextSize *= 2
+    }
+
+    const next = new Uint8Array(nextSize)
+    next.set(this.buf.subarray(0, this.pos))
+
+    this.buf = next
+    this.view = new DataView(next.buffer)
+  }
+
+  private writeU8(value: number): void {
+    this.ensure(1)
+    this.buf[this.pos++] = value & 0xff
+  }
+
+  private writeLenPrefixed(bytes: Uint8Array): void {
+    this.ensure(4 + bytes.byteLength)
+
+    this.view.setUint32(this.pos, bytes.byteLength, true)
+    this.pos += 4
+
+    this.buf.set(bytes, this.pos)
+    this.pos += bytes.byteLength
+  }
+
+  /** Pack the request inputs; the returned view is valid until the next pack. */
+  pack(
+    methodKind: number,
+    urlBytes: Uint8Array,
+    ipBytes: Uint8Array,
+    requestIdBytes: Uint8Array,
+    headers: Uint8Array,
+  ): Uint8Array {
+    this.pos = 0
+
+    this.writeU8(methodKind)
+    this.writeLenPrefixed(urlBytes)
+    this.writeLenPrefixed(ipBytes)
+    this.writeLenPrefixed(requestIdBytes)
+    this.writeLenPrefixed(headers)
+
+    return this.buf.subarray(0, this.pos)
+  }
+
+  /** Encode `value` directly into the buffer, length-prefixed (zero-copy). */
+  private writeStringLenPrefixed(value: string): void {
+    // 3 bytes per UTF-16 code unit is a safe upper bound (BMP non-ASCII);
+    // surrogate pairs encode to fewer bytes per code unit.
+    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)
+    this.view.setUint32(valueLenPos, written, true)
+    this.pos += written
+  }
+
+  /**
+   * Pack the request inputs from raw strings, encoding url/ip/requestId
+   * directly into the internal buffer via `encodeInto` — three fewer
+   * intermediate `Uint8Array` allocations + copies per request vs [`pack`].
+   * The returned view is valid until the next pack.
+   */
+  packFromStrings(
+    methodKind: number,
+    url: string,
+    ip: string | undefined,
+    requestId: string | undefined,
+    headers: Uint8Array,
+  ): Uint8Array {
+    this.pos = 0
+
+    this.writeU8(methodKind)
+    this.writeStringLenPrefixed(url)
+    if (ip && ip.length > 0) {
+      this.writeStringLenPrefixed(ip)
+    } else {
+      this.writeLenPrefixed(EMPTY_IP_BYTES)
+    }
+    if (requestId) {
+      this.writeStringLenPrefixed(requestId)
+    } else {
+      this.writeLenPrefixed(EMPTY_BYTES)
+    }
+    this.writeLenPrefixed(headers)
+
+    return this.buf.subarray(0, this.pos)
+  }
+
+  /**
+   * Pack the request inputs with a mixed strategy: `url`/`ip` are encoded
+   * directly from strings via `encodeInto` (no intermediate `Uint8Array`),
+   * while `requestId`/`headers` are already-encoded byte slices copied in
+   * verbatim.
+   *
+   * This removes the two `encoder.encode` allocations + copies per request
+   * that [`pack`] pays for URL/IP, while keeping the pre-encoded request-id
+   * bytes untouched (no decode-to-string → re-encode round trip, which
+   * `packFromStrings` would incur when a request id was already generated as
+   * bytes). The returned view is valid until the next pack.
+   */
+  packParts(
+    methodKind: number,
+    url: string,
+    ip: string | undefined,
+    requestId: Uint8Array,
+    headers: Uint8Array,
+  ): Uint8Array {
+    this.pos = 0
+
+    this.writeU8(methodKind)
+    this.writeStringLenPrefixed(url)
+    if (ip && ip.length > 0) {
+      this.writeStringLenPrefixed(ip)
+    } else {
+      this.writeLenPrefixed(EMPTY_IP_BYTES)
+    }
+    this.writeLenPrefixed(requestId)
+    this.writeLenPrefixed(headers)
+
+    return this.buf.subarray(0, this.pos)
+  }
+}

package/src/ingress/packing/scratch.ts

@@ -0,0 +1,50 @@
+// src/ingress/packing/scratch.ts — Shared thread-local scratch header buffers.
+//
+// Both the fast path (`packHeaders` in header-packing.ts) and the pre-baked
+// path (`gatherRawHeadersPacked` in gather-raw-headers.ts) pack request
+// headers into a reusable Uint8Array. This thread-local pool isolates the
+// buffer per call-site sequence and bounds the number of cached buffers,
+// keeping the hot path allocation-free.
+
+/** Scratch capacity for the reusable packed-header buffer. */
+export const HEADER_BUF_SIZE = 8192
+
+// ── Per-header size guards (SHARED by BOTH packing paths) ─────────
+// A header value larger than the bound below is dropped BEFORE packing rather
+// than forwarded. Without guards the fast path (`packHeaders`) forwarded any
+// size, so an oversized cookie/xff/origin could push the packed block past the
+// native `max_headers_bytes` (65536) and fail with a 500, while the pre-baked
+// path silently dropped the same header. Both paths must share ONE policy;
+// keep the Rust `max_headers_bytes` bound in mind when changing these.
+/** Upper bound for the `cookie` header value. */
+export const MAX_COOKIE_HEADER_BYTES = 8192
+/** Upper bound for small single-value headers (origin, ACRM, ACRH, ...). */
+export const MAX_SMALL_HEADER_BYTES = 2048
+/** Upper bound for the `x-forwarded-for` header value. */
+export const MAX_XFF_HEADER_BYTES = 8192
+
+// Thread-local header buffer for per-call isolation (round-robin over a
+// bounded pool; each buffer is only borrowed for the duration of one
+// pack/gather call).
+const [getHeaderBuf] = (() => {
+  const tls: [Uint8Array, DataView][] = []
+  const MAX_CACHED = 256
+  let tlsIdx = 0
+
+  function acquire(): [Uint8Array, DataView] {
+    const cached = tls[tlsIdx]
+    tlsIdx = (tlsIdx + 1) % MAX_CACHED
+    if (cached) return cached
+
+    const buf = new Uint8Array(HEADER_BUF_SIZE)
+    const view = new DataView(buf.buffer)
+    const pair: [Uint8Array, DataView] = [buf, view]
+    tls.push(pair)
+    return pair
+  }
+
+  return [acquire]
+})()
+
+/** Acquire the next scratch header buffer + view from the thread-local pool. */
+export { getHeaderBuf }