castrum 0.9.7 → 0.9.8

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. |

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.