castrum 0.9.7 → 0.9.9

package/src/ingress/index.ts

@@ -22,6 +22,8 @@ export {
   serializeTraceParent,
 } from '../shared/trace'
 // ── Re-export the full public ingress API ─────────────────────────
+// Request cancellation helpers (client-disconnect → 499).
+export { ABORT_CODE, abortResponse, isAbortError } from './abort'
 export * from './constants'
 export * from './errors'
 export { createIngressFast, FastIngressResult } from './fast'
@@ -30,7 +32,7 @@ export type { CorsOptions, CorsStaticStrings } from './headers/cors'
 export type { HeaderTemplate, ResponseBuildContext } from './headers/fast-templates'
 export { buildResponseContext, headersForResult } from './headers/fast-templates'
 export type { SecurityHeadersOptions } from './headers/hsts'
-export { healthHandler, livenessHandler, readinessHandler } from './health'
+export { healthHandler, livenessHandler, readinessHandler, staticLiveness } from './health'
 export type { IngressMetrics } from './metrics'
 // ── Observability (zero-dep): metrics, health probes ─────────────
 export { createIngressMetrics, metricsHandler } from './metrics'

package/src/ingress/native-route.ts

@@ -66,7 +66,11 @@ export interface NativeRoute {
   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). */
+  /**
+   * Free the native handle. Idempotent: a second call is a no-op. After it,
+   * {@link runFrame}/{@link run} throw rather than pass a freed handle into the
+   * native stack.
+   */
   destroy(): void
 }
 
@@ -109,16 +113,21 @@ export function createNativeRoute(plan: NativeRoutePlan = {}): NativeRoute {
   const parseQuery = plan.parseQuery === true
   const parseCookies = plan.parseCookies === true
 
-  // Transport: bun:ffi PRIMARY on Bun; napi `Route` on Node / fallback. The
+  // Transport: bun:ffi PRIMARY on Bun; napi `Route` on Node / fallback. An FFI
+  // compile failure (invalid/unsupported descriptor) ALSO falls back to napi so
+  // the route stays usable instead of throwing "no active transport". 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
+  let ffiHandle = bunFFI !== null ? compileFfi(bunFFI, descriptor) : 0
+  let napiRoute = bunFFI === null || ffiHandle === 0 ? compileNapi(descriptor) : null
 
   // Reusable output buffer for the needed-size convention (grow once, retry).
   let out = new Uint8Array(256)
 
   const runFrame = (frame: Uint8Array): RouteWireResult => {
+    if (ffiHandle === 0 && napiRoute === null) {
+      throw new Error('native route: already destroyed')
+    }
     let written: number
     if (ffiHandle !== 0 && bunFFI !== null) {
       written = bunFFI.routeRun(ffiHandle, frame, out)
@@ -153,7 +162,10 @@ export function createNativeRoute(plan: NativeRoutePlan = {}): NativeRoute {
     destroy: () => {
       if (ffiHandle !== 0 && bunFFI !== null) {
         bunFFI.routeDestroy(ffiHandle)
+        ffiHandle = 0
       }
+      napiRoute?.destroy?.()
+      napiRoute = null
     },
   }
 }
@@ -170,10 +182,17 @@ function compileFfi(bunFFI: BunFFI, descriptor: Uint8Array): number {
 /** Compile through the napi `Route` class (Node / fallback transport). */
 function compileNapi(
   descriptor: Uint8Array,
-): { run: (frame: Uint8Array, out: Uint8Array) => number } | null {
+): { run: (frame: Uint8Array, out: Uint8Array) => number; destroy?: () => void } | null {
   const addon = getAddon()
   const Route = (
-    addon as { Route?: new (d: Uint8Array) => { run: (f: Uint8Array, o: Uint8Array) => number } }
+    addon as {
+      Route?: new (
+        d: Uint8Array,
+      ) => {
+        run: (f: Uint8Array, o: Uint8Array) => number
+        destroy?: () => void
+      }
+    }
   ).Route
   if (typeof Route !== 'function') {
     return null // addon without the route stack (pre-rebuild) — caller falls back

package/src/ingress/options.ts

@@ -184,6 +184,10 @@ let trustProxyWarned = false
  * `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.
+ *
+ * Precedence: when `trustedProxies` is also set it wins, so
+ * `{ trustProxy: true, trustedProxies: { enabled: false } }` trusts NOTHING —
+ * the safer mode, not the "trust everything" this warning describes.
  */
 export function warnTrustProxyDeprecated(): void {
   if (trustProxyWarned) return
@@ -191,7 +195,27 @@ export function warnTrustProxyDeprecated(): void {
   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.',
+      'limiting. Use `trustedProxies: { enabled: true, networks: [...] }` ' +
+      '(which takes precedence) and only enable proxy trust behind a trusted edge.',
+  )
+}
+
+let rateLimitNoIpWarned = false
+
+/**
+ * Warn once (per process) when rate limiting is enabled without a `getIp`
+ * resolver. The native pipeline then resolves an empty client IP, so EVERY
+ * client shares one bucket — one attacker can exhaust it and 429 everyone.
+ *
+ * A single global bucket is a legitimate choice, so this warns rather than
+ * fails; provide `getIp` for per-client isolation.
+ */
+export function warnRateLimitWithoutGetIp(): void {
+  if (rateLimitNoIpWarned) return
+  rateLimitNoIpWarned = true
+  console.warn(
+    '[castrum] WARN: rate limiting is enabled without `getIp` — every client ' +
+      'shares ONE bucket, so one client can exhaust it for everyone. Provide ' +
+      '`getIp` for per-client limits (or use a global limit deliberately).',
   )
 }

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

@@ -12,14 +12,6 @@ import { writeHeaderPair } from './header-packing'
 import { getHeaderBuf, MAX_SMALL_HEADER_BYTES } from './scratch'
 import { forEachSelectedHeader, HDR_ORIGIN } from './select-headers'
 
-// 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
@@ -161,3 +153,27 @@ function cachedOriginBlock(origin: string): Uint8Array {
   ORIGIN_BLOCK_CACHE.set(origin, block)
   return block
 }
+
+/**
+ * Pre-warm the origin-packed-block cache for the configured exact
+ * `allow-origin` values (load-time-for-RPS trade): the FIRST request from each
+ * known origin then skips the shared encode + pack + scratch write entirely,
+ * like every later request does. Oversized values are skipped (they map to the
+ * EMPTY block anyway) and wildcard/pattern values are skipped (they never
+ * resolve to their own literal origin), while the module-level cache stays
+ * bounded by `ORIGIN_CACHE_MAX`. No-op for any plan that never consults it.
+ */
+export function prewarmOriginBlocks(origins: readonly string[]): void {
+  for (const origin of origins) {
+    if (
+      typeof origin === 'string' &&
+      origin.length > 0 &&
+      origin.length <= MAX_SMALL_HEADER_BYTES &&
+      // A wildcard/pattern never resolves to its own literal origin string, so
+      // caching it would only burn a slot (the handler filters these too).
+      !origin.includes('*')
+    ) {
+      cachedOriginBlock(origin)
+    }
+  }
+}

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,12 +22,12 @@
 // 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'
+import type { BakedRoute, RouteHandler, StaticRoute } from './server'
 import { buildRouteHandlers } from './server'
 import type { BakedContext, NativeResponder, OptimizedIngressHandler, TerminalStyle } from './types'
 
@@ -88,6 +88,20 @@ export interface RouterRouteSpec {
   /** Terminal envelope style for this route's responder (default: router-level
    *  `terminalStyle` or `'castrum'`). */
   terminalStyle?: TerminalStyle
+  /**
+   * A prebuilt constant response served directly for GET, OUTSIDE the ingress
+   * pipeline (static route promotion). Like `raw`, it OWNS THE WHOLE SPEC: the
+   * router compiles no `IngressInner` for a `static` route, so `read`/`write`/
+   * `echo`/etc. on the same spec are ignored.
+   *
+   * This differs from `BakedRoute.static` in src/ingress/server.ts, where
+   * `static` only takes GET precedence and leaves `write`/`echo`/`delete`
+   * wired — the router cannot mirror that because a `static`-only spec has no
+   * compiled ingress to hand those methods. Do not unify the two semantics.
+   *
+   * See `BakedRoute.static` for the one-shot-body contract.
+   */
+  static?: StaticRoute
   /**
    * A raw request→Response handler served directly for GET, OUTSIDE the
    * ingress pipeline (health/metrics probes, /metrics). When set, `read`/
@@ -175,6 +189,17 @@ export function createIngressRouter(options: CreateIngressRouterOptions): Ingres
   if (options.copyBody !== undefined) baseOpts.copyBody = options.copyBody
 
   for (const [path, spec] of Object.entries(options.routes)) {
+    if (spec.static !== undefined) {
+      // Static promotion: a prebuilt constant response owns the route. Placed
+      // verbatim so Bun.serve can serve it from its native table (a bare
+      // Response) with zero JS.
+      bakedRoutes[path] = {
+        static: spec.static,
+        maxBodyBytes: spec.maxBodyBytes,
+        bodyTimeoutMs: spec.bodyTimeoutMs,
+      }
+      continue
+    }
     if (spec.raw) {
       // Raw handler: served directly, outside the pipeline.
       bakedRoutes[path] = { read: spec.raw as RouteHandler }
@@ -199,6 +224,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] = {
@@ -265,6 +302,16 @@ export function createIngressRouter(options: CreateIngressRouterOptions): Ingres
     if (typeof methodHandler === 'function') {
       return (methodHandler as RouteHandler)(req, srv, matched.params)
     }
+    if (methodHandler instanceof Response) {
+      // Static route (bare Response value). `instanceof Response` assumes the
+      // value was built with the global `Response` constructor (the one this
+      // router also uses). `clone()` tees the body without consuming the
+      // original, so every request gets a fresh, complete body. A `static`
+      // factory is a function and is handled above. The cast bridges Bun's
+      // `Response.clone()` return type (which resolves against the bundled
+      // fetch types) to this module's global `Response`.
+      return methodHandler.clone() as unknown as Response
+    }
     // A route matched but this method isn't wired — 405, or a bare OPTIONS 204
     // when the route answers preflights.
     if (req.method === 'OPTIONS' && typeof matched.methods.OPTIONS === 'function') {

package/src/ingress/routes/common.ts

@@ -1,6 +1,8 @@
 // src/ingress/routes/common.ts — Shared route-handler options + helpers.
 
+import { abortResponse } from '../abort'
 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 +54,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 +66,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 }
 }
 
 /**
@@ -77,11 +94,18 @@ export function buildSuccessInit(
  * runner: resolve the client IP once and dispatch through the native pipeline
  * (`ingress.run` with a null body). Used by the read / head / fallback route
  * factories whose responder never needs the request object.
+ *
+ * A disconnected client (`req.signal?.aborted`) short-circuits to the 499
+ * cancelled response BEFORE `ingress.run`, so no pooled output buffer is
+ * acquired for a request that can no longer be delivered.
  */
 export function runBaked(
   ingress: OptimizedIngressHandler,
   opts: BakedHandlerOptions,
   respond: (result: BakedIngressResult, ctx: BakedContext) => Response,
 ): (req: Request, srv?: unknown) => Response {
-  return (req, srv) => ingress.run<Response>(req, resolveIp(req, srv, opts), null, respond)
+  return (req, srv) => {
+    if (req.signal?.aborted) return abortResponse()
+    return ingress.run<Response>(req, resolveIp(req, srv, opts), null, respond)
+  }
 }