castrum 0.9.7 → 0.9.9

package/docs/BENCHMARKS.md

@@ -162,6 +162,19 @@ Current medians (static path, 2000 connections, pipelining 1, single instance):
   per-request `ReadableStream` construction is the cost, not the native body
   write. Both servers default to copy mode; `INGRESS_ZERO_COPY=1` opts back in
   for large-payload deployments.
+- **Response construction dominates the JS-side cost — and is now memoized.**
+  A Bun CPU profile of the ingress route under load attributed ~80% of sampled
+  JS time to `new Response(...)` (the whole `run()` ~7%, the FFI pipeline call
+  ~4%): passing an array-of-pairs makes Bun re-parse every header on every
+  response, measured **1832 ns vs 398 ns** for a persistent `Headers` instance
+  with the full security + CORS set. `buildSuccessInit` and the terminal
+  builders now pass a memoized `Headers`
+  (`src/ingress/headers/memoized-headers.ts`, keyed by the header array's
+  identity; the baked templates and per-origin cache return the same array
+  across requests, fresh per-request arrays are never retained). Interleaved
+  autocannon A/B (static `GET /api/users`, 8 workers, 2000 connections, three
+  independent runs): **+14.3% / +15.6% / +23.1% median RPS**, p50 −15%,
+  p99 −9…−24%, 0 errors, wire output byte-identical.
 - Per-request cost breakdown (`bun bench/cost/router-cost.ts` +
   `router-minimal-breakdown.ts`, min-of-5): the router's minimal route `run()`
   is ~310ns (native pruned pipeline ~115ns + response/run machinery ~150ns +

package/docs/CASE_STUDY.md

@@ -58,7 +58,7 @@ The addon is built with napi-rs (so Node can load it), but it *also* exports
 
 ```mermaid
 flowchart LR
-    TS["TypeScript (index.ts)"] -->|"bun:ffi · 85 C-ABI symbols · ~10–20 ns"| RUST["Rust cdylib (rust/ffi/)"]
+    TS["TypeScript (index.ts)"] -->|"bun:ffi · 121 C-ABI symbols · ~10–20 ns"| RUST["Rust cdylib (rust/ffi/)"]
     TS -.->|"NAPI fallback (Node / self-test failure)"| RUST
     RUST --> PIPELINE["8-stage ingress pipeline"]
     TS --> PACKED["Packed, length-prefixed buffers (zero-copy)"]

package/docs/ENVIRONMENT.md

@@ -10,7 +10,7 @@ warned about and replaced with the documented default.
 |----------|------|---------|-------------|
 | `INGRESS_TRUST_PROXY` | bool | `false` | **Opt-in.** When `true`, honors `X-Forwarded-For` / `X-Real-IP` for client-IP resolution. Keep **off** unless the server sits behind a trusted edge that strips these headers, otherwise clients can spoof arbitrary IPs for IP-based rate limiting. |
 | `INGRESS_REQUEST_ID_HEADER` | bool | `false` | Emit an `x-request-id` response header per request. The request ID is always generated internally; this only controls whether it is echoed to clients. |
-| `INGRESS_ZERO_COPY` | bool | `false` | Enable zero-copy response bodies (legacy alias `INGRESS_UNSAFE_ZERO_COPY` still honored). **Not recommended** unless per-response output buffers are implemented; leave off for safety (bodies are copied by default). |
+| `INGRESS_ZERO_COPY` | bool | `false` | Enable zero-copy response bodies (legacy alias `INGRESS_UNSAFE_ZERO_COPY` still honored). Off by default; when on, the handler serves a pooled output buffer via `pooledBodyResponse` (per-response output buffers are implemented — `src/shared/buffer-pool.ts`, `baked-response.ts::zeroCopyResponse`). Bound the borrowed set with `maxInFlight`. |
 | `INGRESS_ZERO_COPY_MAX_IN_FLIGHT` | int | `128` | Max pooled output buffers kept in flight for zero-copy responses (min `1`). |
 | `INGRESS_ZERO_COPY_TIMEOUT_MS` | int | `1000` | Timeout before a zero-copy pooled buffer is force-released (min `0`). |
 | `INGRESS_OUTPUT_BUF_BYTES` | int | `131072` | Size of the Rust output buffer (min `65536`). If cookies + query + metadata JSON exceed this, `FLAG_BODY_TRUNCATED` is set and the request fails closed. |
@@ -38,8 +38,15 @@ for false; anything else is warned about and falls back to the default.
 | Variable | Type | Default | Description |
 |----------|------|---------|-------------|
 | `CASTRUM_TASK_THREADS` | int | `max(1, cores-1)` | Worker threads for the off-thread task runtime (castrum Tasks). Read when the pool first starts — the pool is process-wide and cannot be resized afterwards (`tasks.stats().threads` reports the live count). |
+| `CASTRUM_TASK_QUEUE_MAX` | int | `4096` | Admission bound on the off-thread task work queue. Read when the pool first starts (minimum 1). A submit that would exceed it is rejected rather than growing memory: the native submit returns `2` and the task promise rejects with a typed `OVERLOADED` error. |
 | `CASTRUM_TASK_PIN_CORES` | (presence) | — | When set (Linux), pin each task worker to its own core (core 0 is skipped so the JS event loop keeps it). `CASTRUM_PIN_CORES` enables it too. Off by default: pinning competes with the JS/rayon threads for the same box. |
 
+## Compiled-schema cache (`rust/ingress/schema_cache.rs`)
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `CASTRUM_SCHEMA_CACHE_MAX` | int | `128` | Max distinct request-body schemas retained process-wide. `Ingress`/`NativeRoute` share one compiled `IngressSchema` per distinct schema byte string; this bounds that LRU. Read at first schema compile (the cache is process-wide and cannot be resized afterwards). Values below 1 (unset, unparseable, `0`) fall back to the default; values are clamped to `4096`. Call `flushMemory()` to drop the cache explicitly. |
+
 ## Native transport selection (`src/native/ffi.ts`)
 
 `bun:ffi` is the PRIMARY transport under Bun; NAPI is the fallback (Node,

package/docs/FFI_BUN_GUIDE.md

@@ -492,7 +492,7 @@ a type error, not a behavior change.
 **Verify after any FFI change**:
 
 ```bash
-nm -D --defined-only <addon> | grep -c castrum_   # = 109
+nm -D --defined-only <addon> | grep -c castrum_   # = 121 (109 direct extern fns)
 bun run bench:http:smoke                           # after touching decoders/handlers
 bun test test/unit/native/ffi.test.ts            # FFI↔napi parity + self-test
 bun test test/unit/native/ffi-symbol-parity.test.ts

package/docs/INGRESS.md

@@ -415,14 +415,14 @@ interface SyncIngressHandler {
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `trustProxy` | `boolean` | `false` | Trust `X-Forwarded-For` and `X-Real-IP` headers |
+| `trustProxy` | `boolean` | `false` | Trust `X-Forwarded-For` and `X-Real-IP` headers. Duplicate `X-Forwarded-For` lines: only the **last** is read (warning in `rust/http/headers.rs`) |
 | `trustedProxies` | `{ enabled, networks? }` | — | Fine-grained proxy trust with optional network whitelist |
 | `parseCookies` | `boolean` | `false` | Parse `Cookie` header into structured JSON |
 | `parseQuery` | `boolean` | `false` | Parse URL query string into structured JSON |
 | `requireJsonBody` | `boolean` | `false` | Require body to be valid JSON |
 | `schema` | `Uint8Array` | — | JSON Schema (as UTF-8 bytes) for body validation |
-| `cors` | `CorsOptions` | — | CORS configuration |
-| `rateLimit` | `{ limit, windowMs, maxEntries }` | — | Rate limiting configuration |
+| `cors` | `CorsOptions` | — | CORS configuration. A present-but-empty `{}` (no `allowOrigin`) resolves to wildcard allow-all |
+| `rateLimit` | `{ limit, windowMs, maxEntries }` | — | Rate limiting configuration. Without a `getIp` resolver every client shares ONE bucket (warns once at router construction) |
 | `security` | `SecurityHeadersOptions` | — | Security headers configuration |
 | `https` | `boolean` | — | Force HTTPS detection (overrides auto-detection) |
 | `maxBodyBytes` | `number` | 1,048,576 | Maximum body size (1 MB) |
@@ -438,7 +438,7 @@ interface SyncIngressHandler {
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `allowOrigin` | `string[]` | — | Allowed origins (empty or `["*"]` = wildcard) |
+| `allowOrigin` | `string[]` | — | Allowed origins. Absent, empty, or `["*"]` = wildcard allow-all; list exact origins (or patterns) to narrow |
 | `allowMethods` | `string[]` | `["GET", "HEAD", "POST"]` | Allowed HTTP methods |
 | `allowHeaders` | `string[]` | — | Allowed request headers |
 | `exposeHeaders` | `string[]` | — | Exposed response headers |

package/docs/REPO_MAP.md

@@ -37,11 +37,11 @@ Bun is the primary runtime; Node.js ≥20.3 is supported via a compiled ESM entr
 | Build Rust addon (LOCAL max perf) | `bun run build:perf` | x86-64-v3 + AVX2 — **never for publish** |
 | Build Rust addon (debug) | `bun run build:debug` | |
 | Build compiled JS entry (Node) | `bun run build:js` | bundle + types → `dist/` (gitignored) |
-| TS unit tests | `bun test` | ~760 tests, `test/unit/**` |
-| Rust unit tests | `bun run test:rust` | `cargo test`, ~440 tests |
+| TS unit tests | `bun test test/unit test/property test/compat` | 838 tests (paths are explicit — a bare `bun test` pulls in the Node `.mjs` suites that need `dist/`) |
+| Rust unit tests | `bun run test:rust` | `cargo test`, 628 tests |
 | Node smoke tests | `bun run test:node` | explicit `.mjs` paths (Node 24 rejects dir arg) |
 | Installed-tarball e2e | `bun run verify:install` | pack → install → import from `node_modules` |
-| Typecheck | `bun run typecheck` | `bunx tsc --noEmit` (only `index.ts`, `bench.ts`, `src/`) |
+| Typecheck | `bun run typecheck` | `bunx tsc --noEmit` (`index.ts`, `bench.ts`, `src/`, `bench/`) |
 | CPU benchmark + correctness | `bun run check` | == `bun bench.ts`; writes `bench/results/cpu/` |
 | HTTP bench (all servers) | `bun run bench:http` | |
 | HTTP smoke (fast sanity) | `bun run bench:http:smoke` | **the wire-format guard** (CI-gated) |
@@ -131,7 +131,7 @@ src/
     shared.ts             JS constants + buildHeaderPlan + assertSyncCallback (shared by both paths).
     constants.ts          Binary-layout constants read from Rust at runtime (SINGLE SOURCE).
     status.ts / errors.ts / options.ts / types.ts / body.ts / context.ts
-    packing/              header-packing.ts, input-packer.ts, gather-raw-headers.ts
+    packing/              header-packing.ts, input-packer.ts, gather-raw-headers.ts, select-headers.ts, scratch.ts
     headers/              cors.ts, hsts.ts, security.ts (baked security merge), fast-templates.ts, baked-templates.ts
     decode/               fast-result.ts, baked-result.ts   (TWO decoders — see §4.2)
     response/             terminal.ts, error-bodies.ts, baked-response.ts (pre-baked response builders)
@@ -294,7 +294,9 @@ consumed.
 - **Multi-platform (recommended)**: push a `v*` tag → `.github/workflows/ci.yml`
   builds each platform addon, the `publish` job downloads them into
   `./artifacts`, stages them, and runs `npm publish` (npm Trusted Publishing /
-  OIDC — no token secret; needs the Trusted Publisher configured on npmjs.com).
+  OIDC — preferred, no long-lived token; the job also targets the `NPM_TOKEN`
+  environment as a fallback secret. Needs the Trusted Publisher configured on
+  npmjs.com).
 - **Manual single-platform**: `bun run release:manual`
   (syncs package.json ↔ Cargo.toml ↔ CHANGELOG, tags, builds, publishes with
   `CASTRUM_PUBLISH_ALLOW_PARTIAL=1`). `--dry-run` plans only.

package/docs/RND-CONCURRENCY.md

@@ -69,7 +69,8 @@ documented `JSTypedArrayBytesDeallocator` hook crashes the process (fault at
 
 ```
 rust/task/runtime.rs     condvar pool, N = cores−1 (CASTRUM_TASK_THREADS), auto-start on submit,
-                         batch dequeue + bounded spin-then-park, optional core pinning
+                         batch dequeue + bounded spin-then-park, optional core pinning,
+                         HARD admission bound on the queue (CASTRUM_TASK_QUEUE_MAX)
 rust/task/completion.rs  result ring + ARMED coalescing doorbell + needed-size drain layout
 rust/task/ops.rs         op dispatch (header + payload split), cancellation set, catch_unwind
                          containment, `_into` (zero-copy output) and slice (zero-copy input) forms
@@ -121,6 +122,17 @@ right one is picked per op:
    copied and the payload is read in place, so a large argument never crosses the
    boundary. This one was forced by a measurement, not symmetry (§7b).
 
+**Bounded admission (backpressure).** The work queue is HARD-bounded by
+`CASTRUM_TASK_QUEUE_MAX` (default 4096, minimum 1; read once when the pool is
+created). A submit that would exceed the bound is rejected instead of growing
+memory: `castrum_task_submit{,_out,_slice}` return `2 = overloaded`, and the JS
+runtime rejects the task promise with a typed `code: 'OVERLOADED'` error. The
+existing return meanings are unchanged — `1` accepted, `0` invalid args / panic.
+A rejected zero-copy submit drops its `output`/`keep` reference exactly like any
+other rejection, so a full queue cannot leak buffers. (The richer M2 design — a
+`WouldBlock` + re-queue-behind-drain policy and priority levels — remains a
+later milestone; v1 is a hard cap with a distinct overload outcome.)
+
 **Measured comparison** (`bun run bench:task`, Bun 1.4.2, 12 cores):
 
 | variant | time | loop stall | note |
@@ -466,9 +478,12 @@ rust/task/
   as in rayon/Go. Deliberately **separate from the rayon global pool**: rayon
   stays the batch executor for `par_iter`; the task runtime owns offloaded ops.
   `CASTRUM_TASK_THREADS` sizes it (default `cores − 1`).
-- **Admission/backpressure**: bounded queue (`CASTRUM_TASK_QUEUE_MAX`, default
-  4× threads). `submit` returns `WouldBlock` when full; JS resolves by queueing
-  behind a `drain` promise — no unbounded growth (fixes F6).
+- **Admission/backpressure** (v1 shipped): the queue is hard-bounded by
+  `CASTRUM_TASK_QUEUE_MAX` (default 4096, min 1, read once at pool creation).
+  `submit` returns `false` when full; the C ABI reports `2 = overloaded` and JS
+  rejects that promise with a typed `OVERLOADED` error — no unbounded growth
+  (fixes F6). M2 replaces this hard cap with `WouldBlock` + requeue-behind-drain
+  and priority levels; v1 has neither.
 - **Cancellation**: each task carries an `Arc<CancelToken>` (atomic + reason).
   Ops check it at safepoints (between chunks: gzip blocks, schema subtrees,
   Argon2 is atomic and reports "not cancellable"). Scope cancellation cascades
@@ -618,6 +633,7 @@ Each of these removes syscalls, lock traffic, or reallocations from the hot path
 | **Zero-copy INPUT** (`castrum_task_submit_slice` + the header/payload split in `ops.rs`) | Forced by a measurement: packing the payload into the args blob copied the whole input on the JS thread, making offloaded `gzipCompress` of 24 MiB **18.6 ms / 11.7 ms stall against 5.6 ms synchronous** — a net loss on both axes. Reading the payload in place: **7.3 ms / 2.1 ms**. The split also simplified every op arm (no more `args[4..]` offset arithmetic). |
 | **No BigInt, no per-completion DataView** | The drain loop reads ids and lengths as two `u32` reads at an offset — `getBigUint64` boxes a BigInt and `readU64` allocated a DataView *per completion*. Exact for any value under 2^53 (ids are a JS counter, sizes are byte counts). A zero-copy completion's body is never materialized at all. |
 | **Reusable args scratch** (copy path only) | Rust copies args on submit, so one growable buffer serves every synchronous submission. Deliberately NOT used for secret-bearing ops (pbkdf2/argon2) — a shared buffer would keep plaintext passwords alive far longer than a per-call allocation — nor for zero-copy retries, which re-submit after an `await` and must own their memory. |
+| **Bounded admission** (`CASTRUM_TASK_QUEUE_MAX`, default 4096) | A hard cap turns sustained overload into an explicit rejection (`2 = overloaded` → typed `OVERLOADED`) instead of unbounded queue/`inflight` growth. The bound is a length check inside the same lock that pushes, so it is one comparison on a path that already locks. |
 
 ---