castrum 0.9.7 → 0.9.8

package/rust/ingress/native_route.rs

@@ -224,9 +224,11 @@ impl NativeRoute {
         if self.require_json_body || self.validate_body {
             if !has_body || body.len() > self.max_body_bytes {
                 body_valid_json = false;
-                if self.require_json_body {
-                    error_code = ERR_BODY_NOT_JSON;
-                }
+                // Inside `require_json_body || validate_body`: an absent or
+                // oversized body can never satisfy either constraint, so fail
+                // closed. (Pre-fix a validateBody-only route returned OK with
+                // error_code 0 and skipped schema validation entirely.)
+                error_code = ERR_BODY_NOT_JSON;
             } else {
                 body_valid_json = crate::json::json_ops::json_valid_bytes(body);
                 if self.require_json_body && !body_valid_json {
@@ -732,6 +734,22 @@ mod tests {
         assert_eq!(flags & ROUTE_RESULT_FLAG_OK, 0);
     }
 
+    #[test]
+    fn validate_body_without_require_json_fails_closed_on_absent_body() {
+        let schema = br#"{"type":"object","required":["x"],"properties":{"x":{"type":"number"}}}"#;
+        // Deliberately NO requireJsonBody stage: a route that only declares
+        // validateBody must still reject a missing body. Pre-fix this returned
+        // OK with error_code 0 and skipped schema validation entirely.
+        let d = descriptor(&[STAGE_VALIDATE_BODY], &[(PART_BODY, schema)]);
+        let r = NativeRoute::compile(&d).unwrap();
+        let mut out = vec![0u8; 64];
+        r.run(&frame(b"", b"", None), &mut out).unwrap();
+        let flags = u32::from_le_bytes(out[0..4].try_into().unwrap());
+        let code = u32::from_le_bytes(out[4..8].try_into().unwrap());
+        assert_eq!(code, 400);
+        assert_eq!(flags & ROUTE_RESULT_FLAG_OK, 0);
+    }
+
     #[test]
     fn body_only_route_is_bare_header() {
         let d = descriptor(&[STAGE_REQUIRE_JSON_BODY], &[]);

package/rust/task/completion.rs

@@ -54,6 +54,13 @@ pub fn set_doorbell(cb: usize) {
     DOORBELL.store(cb, Ordering::Release);
 }
 
+/// Disable the doorbell trampoline (`0`). Called on shutdown BEFORE the JS
+/// owner closes the `JSCallback`, so a completion that lands late can never
+/// call a freed trampoline (poll-only mode drains it instead).
+pub fn clear_doorbell() {
+    DOORBELL.store(0, Ordering::Release);
+}
+
 /// Push a completion and ring the doorbell at most once per armed window.
 ///
 /// The ring lock is released BEFORE the trampoline is called: the JS callback

package/rust/task/mod.rs

@@ -22,7 +22,7 @@ pub mod runtime;
 #[cfg(test)]
 mod tests;
 
-pub use completion::{drain, pending, set_doorbell};
+pub use completion::{clear_doorbell, drain, pending, set_doorbell};
 pub use ops::{mark_cancelled, STATUS_CANCELLED, STATUS_ERROR, STATUS_OK};
 pub use runtime::{init, shutdown, threads};
 

package/rust/task/tests.rs

@@ -223,6 +223,36 @@ fn doorbell_coalesces_a_batch() {
     completion::clear();
 }
 
+#[test]
+fn clear_doorbell_suppresses_the_ring() {
+    let _g = LOCK.lock();
+    completion::clear();
+    completion::set_doorbell(bell as *const () as usize);
+    BELLS.store(0, Ordering::SeqCst);
+    completion::push(Completion {
+        id: 1,
+        status: STATUS_OK,
+        body: vec![0],
+    });
+    assert_eq!(BELLS.load(Ordering::SeqCst), 1);
+    // Disarm by draining, then clear the trampoline. A later completion must
+    // NOT call the (now closed) trampoline address.
+    let mut buf = vec![0u8; 4096];
+    completion::drain(&mut buf);
+    completion::clear_doorbell();
+    completion::push(Completion {
+        id: 2,
+        status: STATUS_OK,
+        body: vec![0],
+    });
+    assert_eq!(
+        BELLS.load(Ordering::SeqCst),
+        1,
+        "a cleared doorbell must never be called"
+    );
+    completion::clear();
+}
+
 #[test]
 fn pool_starts_with_a_nonzero_thread_count() {
     let _g = LOCK.lock();

package/src/ingress/decode/baked-result.ts

@@ -36,12 +36,12 @@ import { IngressResultBase } from './result-base'
 
 /** Zero-alloc, reusable result decoder for the pre-baked handler path. */
 export class BakedIngressResult extends IngressResultBase {
-  refresh(buf: Uint8Array, body: Uint8Array, view: DataView): void {
+  refresh(buf: Uint8Array, body: Uint8Array, view: DataView, len: number = buf.byteLength): void {
     // Defensive: the native core always writes the full fixed header
     // (>= OUT_DATA_START bytes) before returning `written`. The cached
     // whole-buffer DataView (see viewForArrayBuffer) would otherwise decode
     // stale bytes if this contract is ever violated — treat as internal error.
-    if (buf.byteLength < OUT_DATA_START) {
+    if (len < OUT_DATA_START) {
       this.setInternalError()
       return
     }
@@ -59,7 +59,7 @@ export class BakedIngressResult extends IngressResultBase {
 
     // Bounds-checked section offsets shared with the fast decoder: a
     // malformed/truncated buffer can never produce slices past its end.
-    const layout = sectionLayout(buf.byteLength, cookiesLenRaw, queryLenRaw, bodyJsonLenRaw)
+    const layout = sectionLayout(len, cookiesLenRaw, queryLenRaw, bodyJsonLenRaw)
 
     if (h0 === 0 && h1 === 0) {
       this.verdict = 1
@@ -85,7 +85,7 @@ export class BakedIngressResult extends IngressResultBase {
 
     // The baked path trusts the already-clamped section lengths, so pass the
     // safe body len here (the fast path re-checks bounds on read instead).
-    this.setSections(buf, layout, layout.safeBodyJsonLen)
+    this.setSections(buf, layout, layout.safeBodyJsonLen, len)
 
     this.updateOkTerminal()
 
@@ -115,7 +115,15 @@ export class BakedIngressResult extends IngressResultBase {
   }
 
   bodyJson(copy: boolean): Uint8Array {
+    if (copy) {
+      // Copy directly out of the buffer — `buffer.slice(begin, end)` avoids the
+      // intermediate `subarray()` view that `bodyJsonSlice().slice()` created.
+      if (this._bodyJsonLen === 0) return this._buf.slice(0, 0)
+      const end = this._bodyJsonStart + this._bodyJsonLen
+      if (end > this._len) return this._buf.slice(0, 0)
+      return this._buf.slice(this._bodyJsonStart, end)
+    }
     const slice = this.bodyJsonSlice()
-    return (copy ? slice.slice() : slice) as Uint8Array
+    return slice as Uint8Array
   }
 }

package/src/ingress/decode/fast-result.ts

@@ -127,7 +127,7 @@ export class FastIngressResult extends IngressResultBase {
     // Store slices for lazy decode instead of eagerly decoding strings. The
     // fast path trusts the RAW declared body length and re-checks bounds on
     // read (bodyJson()), so pass the raw declared length here.
-    this.setSections(buf, layout, bodyJsonLen)
+    this.setSections(buf, layout, bodyJsonLen, buf.byteLength)
 
     // Parity with the baked decoder: any declared section (cookies, query,
     // OR body) that overran the buffer counts as truncated.

package/src/ingress/decode/result-base.ts

@@ -62,6 +62,13 @@ export abstract class IngressResultBase {
   body: Uint8Array = EMPTY_BODY
 
   protected _buf: Uint8Array = EMPTY_BODY
+  /**
+   * Valid byte length of `_buf` (the native `written` count). `_buf` may be the
+   * WHOLE pooled output buffer (`outputBufferSize` bytes), so bounds checks must
+   * use this, not `_buf.byteLength` — that lets `run()` skip a per-request
+   * `buffer.subarray(0, written)` view.
+   */
+  protected _len = 0
   protected _bodyJsonStart = OUT_DATA_START
   protected _bodyJsonLen = 0
   private _cookiesBuf: Uint8Array | null = null
@@ -89,6 +96,7 @@ export abstract class IngressResultBase {
     this.bodyTruncated = false
     this.body = EMPTY_BODY
     this._buf = EMPTY_BODY
+    this._len = 0
     this._bodyJsonStart = OUT_DATA_START
     this._bodyJsonLen = 0
     this._cookiesBuf = null
@@ -134,8 +142,14 @@ export abstract class IngressResultBase {
    * baked path passes the already-clamped `layout.safeBodyJsonLen`. Sections
    * are stored as slices and decoded lazily by `cookiesJson()`/`queryJson()`.
    */
-  protected setSections(buf: Uint8Array, layout: PackedSectionLayout, bodyJsonLen: number): void {
+  protected setSections(
+    buf: Uint8Array,
+    layout: PackedSectionLayout,
+    bodyJsonLen: number,
+    len: number = buf.byteLength,
+  ): void {
     this._buf = buf
+    this._len = len
     this._bodyJsonStart = layout.bodyJsonStart
     this._bodyJsonLen = bodyJsonLen
     this._cookiesBuf =
@@ -174,7 +188,7 @@ export abstract class IngressResultBase {
   protected bodyJsonSlice(): Uint8Array {
     if (this._bodyJsonLen === 0) return EMPTY_BODY
     const end = this._bodyJsonStart + this._bodyJsonLen
-    if (end > this._buf.byteLength) return EMPTY_BODY
+    if (end > this._len) return EMPTY_BODY
     return this._buf.subarray(this._bodyJsonStart, end)
   }
 }

package/src/ingress/handlers.ts

@@ -44,7 +44,7 @@ import { BufferPool, type PooledBuffer } from '../shared/buffer-pool'
 import { decoder, viewForArrayBuffer } from '../shared/bytes'
 import { createStructuredLogger } from '../shared/log'
 import { generateRequestId } from '../shared/request-id'
-import { OUT_DATA_START } from './constants'
+import { OUT_DATA_START, HV_CORS_SIMPLE, HV_JSON, HV_RATE_ACTIVE } from './constants'
 import { BakedIngressResult } from './decode/baked-result'
 import { buildBakedHeaderTemplates } from './headers/baked-templates'
 import { buildBakedSecurityEntries } from './headers/security'
@@ -54,9 +54,13 @@ import {
   type IngressHandlerOptions,
   warnTrustProxyDeprecated,
 } from './options'
-import { gatherRawHeadersPacked } from './packing/gather-raw-headers'
+import { gatherRawHeadersPacked, prewarmOriginBlocks } from './packing/gather-raw-headers'
 import { IngressInputPacker } from './packing/input-packer'
-import { type BakedResponseState, buildBakedResponseBuilders } from './response/baked-response'
+import {
+  type BakedResponseState,
+  buildBakedResponseBuilders,
+  prewarmOriginHeaders,
+} from './response/baked-response'
 import {
   assertSyncCallback,
   buildHeaderPlan,
@@ -110,6 +114,22 @@ export const RATE_LIMIT_U32_MAX = 4_294_967_295
  */
 const MAX_FFI_FAILURES = 3
 
+/**
+ * Number of output buffers pre-allocated into the handler's pool at
+ * construction (`prefill`), so the first burst wave never pays per-request
+ * `new Uint8Array` + GC. Memory trade: `outputBufferSize` × this many bytes
+ * retained per handler (bounded by the pool's `maxBuffers` cap).
+ */
+const PREWARM_POOL_BUFFERS = 16
+
+/**
+ * Byte budget for the pool prefill. `createIngressRouter` builds one handler
+ * (and therefore one pool) per route, so an unbounded `prefill × outputBufferSize`
+ * could reach ~1 GiB per route at the 64 MiB output clamp. This caps the
+ * per-handler up-front allocation at 4 MiB regardless of buffer size.
+ */
+const PREWARM_POOL_BYTES = 4 * 1024 * 1024
+
 /**
  * Best-effort URL pathname extraction for log/error lines.
  *
@@ -285,12 +305,24 @@ export function createIngressHandler(
     logger
   )
 
+  // Hoisted observer-presence flags: the hot path skips the response-status
+  // computation (an `instanceof` + `safeTerminalStatus`) and the per-request
+  // hook call entirely when nothing observes the outcome.
+  const hasOnRequest = runtime.onRequest !== undefined
+  const hasOnResponse = runtime.onResponse !== undefined
+
   // Reusable output-buffer pool: eliminates the per-request output-buffer
   // allocation by reusing buffers across requests.
   // `maxInFlight` (when set) bounds zero-copy borrowing under slow consumers.
+  // `prefill` spends up-front memory (`outputBufferSize` × 16 per handler) so
+  // a burst ramp never allocates during its first wave — the packaged
+  // load-test flow, where the pool would otherwise go 1 buffered → allocate
+  // under a 2000-connection flood.
   const outputPool = new BufferPool({
     initialSize: outputBufferSize,
     maxInFlight: runtime.maxInFlight,
+    prefill: PREWARM_POOL_BUFFERS,
+    prefillBytes: PREWARM_POOL_BYTES,
   })
 
   // Reusable packed-input builder (same zero-alloc discipline as the fast
@@ -313,16 +345,24 @@ export function createIngressHandler(
   // flaky FFI path degrades to a correct response instead of a failure storm.
   let ffiFailures = 0
   let ffiDisabled = false
+  // Cold path only (called from a `catch`): counts a recurrence and trips the
+  // circuit breaker. Defined once at construction, so it adds nothing per call.
+  const noteFfiFailure = (): void => {
+    ffiFailures++
+    if (ffiFailures >= MAX_FFI_FAILURES) {
+      ffiDisabled = true
+    }
+  }
 
   // Cache Origin-augmented header arrays keyed by `variant\u0000origin` (the
   // steady-state CORS case: the pre-baked template + one
   // `access-control-allow-origin` row). Callers treat the returned array as
   // read-only (the `Headers`/`Response` constructors copy entries), so every
   // distinct (variant, origin) is reused after its first hit — removing the
-  // per-request array alloc + copy when an Origin header is present. Only
-  // ALLOWED origins reach the CORS-allowed path (the native pipeline gates the
-  // variant on CORS approval), so the map stays bounded by the configured
-  // allow-origin list (+ a couple of preflight variants).
+  // per-request array alloc + copy when an Origin header is present. The map is
+  // bounded by `ORIGIN_HEADER_CACHE_MAX` in baked-response.ts: with wildcard
+  // CORS the Origin is attacker-controlled, so an unbounded map would be a
+  // remote memory-exhaustion vector.
   const originHeaderCache = new Map<string, [string, string][]>()
 
   // ── Variant-indexed header templates (precomputed once) ──
@@ -379,6 +419,34 @@ export function createIngressHandler(
     state: responseState,
   })
 
+  // Pre-warm the CORS caches for the configured exact allow-origins
+  // (load-time-for-RPS trade): the FIRST request from each known origin then
+  // hits the baked origin-packed header block AND the cached
+  // origin-augmented header array + memoized `Headers` instead of building
+  // them. Wildcard/pattern entries (e.g. `https://*.example.com`) are skipped
+  // — the concrete resolved origin differs from the pattern string, so
+  // caching the pattern would only waste a slot.
+  if (headerPlan.cors && typeof cors?.allowOrigin === 'object') {
+    const exactOrigins: string[] = []
+    for (const origin of cors.allowOrigin) {
+      if (
+        typeof origin === 'string' &&
+        origin.length > 0 &&
+        origin.length <= 512 &&
+        !origin.includes('*')
+      ) {
+        exactOrigins.push(origin)
+      }
+    }
+    prewarmOriginBlocks(exactOrigins)
+    // Warm the SUCCESS variant the native pipeline actually returns for an
+    // allowed CORS JSON response (HV_JSON | HV_CORS_SIMPLE, plus HV_RATE_ACTIVE
+    // when rate limiting is on) — not HV_CORS_SIMPLE alone, which is a
+    // different cache key and left the warmed entry unreachable.
+    const successVariant = HV_JSON | HV_CORS_SIMPLE | (rateEnabled ? HV_RATE_ACTIVE : 0)
+    prewarmOriginHeaders(responseBuilders.responseHeaders, exactOrigins, successVariant)
+  }
+
   const result = new BakedIngressResult()
   const ctx: BakedContext = {
     requestIdHeader: null,
@@ -399,7 +467,7 @@ export function createIngressHandler(
     ctx.requestIdHeader = emitRequestIdHeader ? requestIdStr : null
     ctx.origin = headerPlan.cors ? req.headers.get('origin') : null
 
-    runtime.onRequest?.(req, requestIdStr, ip)
+    if (hasOnRequest) runtime.onRequest?.(req, requestIdStr, ip)
 
     const ipStr = ip ?? EMPTY_IP
 
@@ -463,10 +531,7 @@ export function createIngressHandler(
             )
             ffiFailures = 0
           } catch {
-            ffiFailures++
-            if (ffiFailures >= MAX_FFI_FAILURES) {
-              ffiDisabled = true
-            }
+            noteFfiFailure()
             // napi re-run: crash-safe (napi-rs catch_unwind) and semantically
             // identical — a transient ffi panic still serves the request. The
             // packed frame respects the same url/ip minimal-processing.
@@ -485,10 +550,7 @@ export function createIngressHandler(
             written = bunFFI.ingressHandlePacked(ingressPtr, input, body, handle.buffer)
             ffiFailures = 0
           } catch {
-            ffiFailures++
-            if (ffiFailures >= MAX_FFI_FAILURES) {
-              ffiDisabled = true
-            }
+            noteFfiFailure()
             // napi re-run: crash-safe (napi-rs catch_unwind) and semantically
             // identical — a transient ffi panic still serves the request.
             written = handler.handleRequestPacked(input, body, handle.buffer)
@@ -498,9 +560,16 @@ export function createIngressHandler(
           written = handler.handleRequestPacked(input, body, handle.buffer)
         }
 
-        const used = handle.buffer.subarray(0, written)
-        // Cached per-ArrayBuffer DataView: no per-request view allocation.
-        result.refresh(used, body ?? EMPTY_BODY, viewForArrayBuffer(used.buffer, used.byteOffset))
+        // Pass the WHOLE pooled buffer + the written length instead of a
+        // per-request `buffer.subarray(0, written)` view (a ~35ns allocation in
+        // Bun); the decoder bounds-checks against the length. Same DataView
+        // (cached per-ArrayBuffer, offset unchanged).
+        result.refresh(
+          handle.buffer,
+          body ?? EMPTY_BODY,
+          viewForArrayBuffer(handle.buffer.buffer, handle.buffer.byteOffset),
+          written,
+        )
       } catch (err) {
         result.setInternalError()
         const error = err instanceof Error ? err : new Error(String(err))
@@ -522,18 +591,21 @@ export function createIngressHandler(
         assertSyncCallback(out, 'createIngressHandler().run()')
         // Report observability for every outcome. Non-Response callbacks
         // (e.g. echoHandler's object return) fall back to the decoded terminal
-        // status so they are not silently invisible to onResponse/logging.
-        const status = out instanceof Response ? out.status : safeTerminalStatus(result)
-        runtime.onResponse?.(req, result, status, requestIdStr)
-        if (logger) {
-          logger.request({
-            requestId: requestIdStr,
-            method: req.method,
-            path: pathForLog(req),
-            status,
-            durationMs: Math.round((performance.now() - startedAt) * 1000) / 1000,
-            ip: ipStr,
-          })
+        // status so they are not silently invisible to onResponse/logging. The
+        // status is computed ONLY when something observes it.
+        if (hasOnResponse || logger !== null) {
+          const status = out instanceof Response ? out.status : safeTerminalStatus(result)
+          if (hasOnResponse) runtime.onResponse?.(req, result, status, requestIdStr)
+          if (logger !== null) {
+            logger.request({
+              requestId: requestIdStr,
+              method: req.method,
+              path: pathForLog(req),
+              status,
+              durationMs: Math.round((performance.now() - startedAt) * 1000) / 1000,
+              ip: ipStr,
+            })
+          }
         }
         return out
       } finally {

package/src/ingress/headers/memoized-headers.ts

@@ -0,0 +1,40 @@
+// src/ingress/headers/memoized-headers.ts — memoized `Headers` for baked header arrays.
+//
+// `new Response(body, { headers })` copies its headers either way, but Bun
+// re-parses an array-of-pairs on every construction whereas a persistent
+// `Headers` instance is copied directly — measured ~1.4 µs cheaper per response
+// with the full security + CORS set (398 ns vs 1832 ns), the single largest
+// per-request JS cost on the success path.
+//
+// The arrays the ingress builds are themselves cached (the pre-baked templates
+// and the per-origin cache return the SAME array instance across requests), so
+// this memo hits on the steady state. Fresh per-request arrays (rate-limit /
+// request-id extras) are simply never retained — a `WeakMap` lets them be
+// collected, so the cache cannot grow without bound.
+//
+// The returned `Headers` is treated as IMMUTABLE: it is only ever handed to a
+// `Response` constructor, which copies it. Verified: mutating the source array
+// after construction, or one served response's headers, never leaks into
+// another response.
+
+/** Memoized `Headers` keyed by the identity of the baked header array. */
+const CACHE = new WeakMap<readonly [string, string][], Headers>()
+
+/**
+ * Return a memoized `Headers` for a baked header array.
+ *
+ * @param entries Header pairs from a handler header builder (baked template,
+ *   per-origin cache, or a fresh extras array).
+ * @returns A `Headers` instance safe to pass to a `Response` constructor.
+ * @example
+ * ```ts
+ * new Response(body, { status: 200, headers: memoizedHeaders(pairs) })
+ * ```
+ */
+export function memoizedHeaders(entries: readonly [string, string][]): Headers {
+  const existing = CACHE.get(entries)
+  if (existing !== undefined) return existing
+  const built = new Headers(entries as [string, string][])
+  CACHE.set(entries, built)
+  return built
+}

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)
+    }
+  }
+}