castrum 0.9.6 → 0.9.8

package/docs/ARCHITECTURE.md

@@ -31,7 +31,7 @@ The bridge between TypeScript and Rust has **two transports**, both loading the
 cdylib (built with napi-rs):
 
 - **`bun:ffi` (PRIMARY on Bun)** — `src/native/ffi.ts` `dlopen`s the addon's
-  `extern "C"` exports (`rust/ffi/`, 119 `castrum_*` symbols — 107 direct + 4
+  `extern "C"` exports (`rust/ffi/`, 121 `castrum_*` symbols — 109 direct + 4
   `validator_c_abi!` + 4 `validator_bytes_c_abi!` + 4 `compress_to_out!`,
   parity guarded by
   `test/unit/native/ffi-symbol-parity.test.ts`) and Bun JIT-calls them

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

@@ -44,7 +44,7 @@ as a pre-baked pipeline, and still be usable from both runtimes.
 ### 2.1 One cdylib, two transports
 
 The addon is built with napi-rs (so Node can load it), but it *also* exports
-`extern "C"` symbols (`rust/ffi/`, **119 `castrum_*` symbols** — 107 direct + 4
+`extern "C"` symbols (`rust/ffi/`, **121 `castrum_*` symbols** — 109 direct + 4
 `validator_c_abi!` + 4 `validator_bytes_c_abi!` + 4 `compress_to_out!`) so Bun can
 `dlopen` it directly:
 
@@ -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. |

package/docs/FFI_BUN_GUIDE.md

@@ -240,6 +240,18 @@ measuring the bare binding suggested the opposite. **Measure through the functio
 users call, not the binding** — the guard itself costs ~4 ns, so guarding is
 cheap and routing everything through bytes is not always a win.
 
+**A second measured instance: the session seal/open siblings (0.9.7).** They
+land in the same place, and the hinge is the caller's own encode. Through the
+real call path, 200k calls, ns/call: one short-string `TextEncoder.encode`
+costs 45.4; `session_seal` is 613.5 via `cstring` versus 557.8 via
+`castrum_session_seal_bytes` when every argument is ALREADY bytes (−9.1%), but
+620.6 when the caller re-encodes its JS strings per call (**+1.2%, slower**).
+`session_open` mirrors it: 568.5 / 501.1 (−11.9%) / 579.5 (+1.9%). So ~45 ns of
+encode against ~45–67 ns of transcode: the byte form pays only for a caller that
+already holds bytes. Byte-identical tokens between the two forms was asserted at
+runtime (`parity: true`), so the siblings are a correctness escape hatch — the
+NUL case, or a caller that already owns buffers — never a blanket migration.
+
 **Rule**: a `cstring` ARG is only correct when truncation cannot change the
 answer — i.e. the string is developer-supplied config or NUL-free by
 construction (a MIME extension, a base64 key, a header name). Anything
@@ -480,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/HOW_TO_ADD_AN_OP.md

@@ -13,6 +13,30 @@ guards fail.
 
 ---
 
+### ⚠️ Rebuild BOTH binaries before binding anything
+
+`bun run build` writes the **baseline** addon only. The loader CPU-detects and
+PREFERS the x86-64-v3 SIMD variant (`castrum.linux-x64-v3-gnu.node`, built by
+`bun run build:v3`) on any AVX2 host — i.e. essentially every modern x86-64
+machine, including CI runners.
+
+A stale v3 binary therefore ships the OLD symbol table, and the failure mode is
+**not** a clean "missing symbol" error: `bun:ffi` binds against it, the first call
+jumps through a missing symbol, and the process **SIGSEGVs** — often at teardown,
+with every test passing. Observed while adding
+`castrum_session_{seal,open}_bytes`: `test/compat` printed `9 pass / 0 fail` and
+then died, `gdb` showing the fault inside `castrum.linux-x64-v3-gnu.node`.
+
+So: after adding or changing ANY `castrum_*` export, rebuild with
+`bun run build:all` (baseline + v3). If you hit a segfault with no failing test,
+check this FIRST — it is much cheaper than bisecting the ABI:
+
+```bash
+nm -D --defined-only castrum.linux-x64-v3-gnu.node | grep <your_symbol>
+```
+
+---
+
 ## 0. The six wiring points at a glance
 
 | # | File | What you add |

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)
@@ -178,7 +178,7 @@ rust/                     ONE cdylib crate (Cargo [lib] → lib.rs).
                           CASTRUM_TASK_THREADS, batch dequeue + spin-then-park + optional
                           CASTRUM_TASK_PIN_CORES), result ring + batched thread-safe doorbell,
                           op dispatch + cancel + catch_unwind containment + `_into` ops.
-  ffi/                    #[no_mangle] extern "C" exports (119 castrum_* symbols — 107 direct + 4
+  ffi/                    #[no_mangle] extern "C" exports (121 castrum_* symbols — 109 direct + 4
                           validator_c_abi! + 4 validator_bytes_c_abi! + 4 compress_to_out!; parity guarded by
                           test/unit/native/ffi-symbol-parity.test.ts) for Bun's bun:ffi
                           primary transport, incl. castrum_ingress_layout (the layout blob).
@@ -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.