castrum 0.7.0 → 0.9.1

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,139 @@
+// 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 { METHOD_KIND } from '../shared'
+import { writeHeaderPair } from './header-packing'
+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.
+export {
+  MAX_COOKIE_HEADER_BYTES,
+  MAX_SMALL_HEADER_BYTES,
+  MAX_XFF_HEADER_BYTES,
+} from './scratch'
+
+/**
+ * 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 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.
+ *   `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 {
+  if (!plan.cookie && !plan.cors && !plan.proxy && !plan.proto) {
+    return EMPTY_HEADERS_BLOCK
+  }
+
+  // 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 && methodKind !== METHOD_KIND.OPTIONS) {
+    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
+
+  const write = (name: Uint8Array, value: string): void => {
+    ;[pos, buf, view] = writeHeaderPair(buf, view, pos, name, value)
+    count++
+  }
+
+  forEachSelectedHeader(req, plan, methodKind, originValue, write)
+
+  // 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

@@ -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 { encodeUtf8Into } from '../../shared/codec'
+import { type HeaderPlan, METHOD_KIND, METHOD_KIND_UNKNOWN } from '../shared'
+import { getHeaderBuf } from './scratch'
+import { forEachSelectedHeader } from './select-headers'
+
+/**
+ * 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
+
+  // 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
+
+  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)
+}