castrum 0.9.7 → 0.9.8

package/src/rust-ffi/scalar/crypto.ts

@@ -12,6 +12,7 @@ import type { PasswordHashOptions } from '../../native'
 import { encoder } from '../../shared/bytes'
 import { memoizeFfi, type RustClientContext, resolveNative } from '../context'
 import { writeInto } from '../into'
+import { assertNonEmptySecret } from '../options'
 
 /** Auth / crypto scalar methods (`Pick<RustScalar, ...>`). */
 export function buildCrypto(ctx: RustClientContext) {
@@ -152,14 +153,17 @@ export function buildCrypto(ctx: RustClientContext) {
       return writeInto('verify cookie', output, value)
     },
     csrfToken(secret: Uint8Array): Uint8Array | string {
+      assertNonEmptySecret(secret, 'csrfToken')
       return resolveNative(ctx, 'csrfToken')(secret) as Uint8Array | string
     },
     csrfTokenInto(secret: Uint8Array, output: Uint8Array): number {
+      assertNonEmptySecret(secret, 'csrfTokenInto')
       const f = ffi()
       if (f) return f.csrfTokenInto(secret, output)
       return writeInto('csrf token', output, addon.csrfToken(secret))
     },
     csrfVerify(token: Uint8Array, secret: Uint8Array): boolean {
+      assertNonEmptySecret(secret, 'csrfVerify')
       return resolveNative(ctx, 'csrfVerify')(token, secret) as boolean
     },
     jwtSign(
@@ -175,6 +179,7 @@ export function buildCrypto(ctx: RustClientContext) {
       // preserves JS insertion order while napi's serde_json sorts keys — for
       // multi-key claims the two transports emit different-but-equally-valid
       // tokens (both verify; parity tests cross-verify semantically).
+      assertNonEmptySecret(secret, 'jwtSign')
       const f = ffi()
       if (f) {
         const token = f.jwtSignBytes(
@@ -198,6 +203,7 @@ export function buildCrypto(ctx: RustClientContext) {
       ttlSeconds?: number | null,
       nowSeconds?: number,
     ): Uint8Array | string {
+      assertNonEmptySecret(secret, 'jwtSignBytes')
       const f = ffi()
       if (f) {
         // The C-ABI `ttl <= 0` sentinel matches napi's Option<i64> (inject only
@@ -223,6 +229,7 @@ export function buildCrypto(ctx: RustClientContext) {
       ttlSeconds?: number | null,
       nowSeconds?: number,
     ): number {
+      assertNonEmptySecret(secret, 'jwtSignBytesInto')
       const f = ffi()
       if (f) {
         return f.jwtSignBytesInto(
@@ -245,6 +252,7 @@ export function buildCrypto(ctx: RustClientContext) {
       )
     },
     jwtVerify(token: Uint8Array, secret: Uint8Array, nowSeconds?: number): unknown {
+      assertNonEmptySecret(secret, 'jwtVerify')
       const f = ffi()
       if (f) {
         // Verify via the FFI cstring path (castrum_jwt_verify): the engine

package/src/rust-ffi/scalar/factories.ts

@@ -27,7 +27,20 @@ import type { BunFFI } from '../../native/ffi'
 import { encoder } from '../../shared/bytes'
 import { decodeUtf8, encodeUtf8 } from '../../shared/codec'
 import type { RustClientContext } from '../context'
-import { asNumber } from '../options'
+import { asNumber, assertNonEmptySecret } from '../options'
+
+/**
+ * Convert a napi `innerPtr()` (u64) into a JS number handle, rejecting values
+ * above `Number.MAX_SAFE_INTEGER`: the `Number()` conversion would silently
+ * round a high canonical address into a wild pointer.
+ */
+function handlePtr(inner: bigint | null | undefined): number {
+  const v = inner ?? 0n
+  if (v < 0n || v > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error('castrum: native handle exceeds Number.MAX_SAFE_INTEGER')
+  }
+  return Number(v)
+}
 
 // ── FFI-backed instance wrappers ───────────────────────────────────────────
 // On Bun, instances whose methods have a STATELESS C-ABI sibling are backed by
@@ -339,17 +352,24 @@ function ffiFormParser(ffi: BunFFI): FormParserInstance {
  * `values.join('\u001f')` — ZERO TextEncoder work (Bun 1.4 zero-copy text).
  */
 function ffiMetricsRegistry(ffi: BunFFI): MetricsRegistryInstance {
-  const handle = ffi.metricsCreate()
+  let handle = ffi.metricsCreate()
+  // Destroyed state is terminal: every method that would pass the handle to
+  // native memory throws instead of dereferencing a freed pointer, and a
+  // second destroy is a no-op (not a double-free).
+  const live = (): number => {
+    if (handle === 0) throw new Error('metrics registry: already destroyed')
+    return handle
+  }
   return {
     counter(name, labelKeys) {
-      return ffi.metricsCounter(handle, name, (labelKeys ?? []).join('\u001f'))
+      return ffi.metricsCounter(live(), name, (labelKeys ?? []).join('\u001f'))
     },
     gauge(name, labelKeys) {
-      return ffi.metricsGauge(handle, name, (labelKeys ?? []).join('\u001f'))
+      return ffi.metricsGauge(live(), name, (labelKeys ?? []).join('\u001f'))
     },
     histogram(name, labelKeys, buckets) {
       return ffi.metricsHistogram(
-        handle,
+        live(),
         name,
         (labelKeys ?? []).join('\u001f'),
         (buckets ?? []).join(','),
@@ -357,13 +377,13 @@ function ffiMetricsRegistry(ffi: BunFFI): MetricsRegistryInstance {
     },
     record(series, values, amount) {
       const joined = (values ?? []).join('\u001f')
-      if (!ffi.metricsRecordStr(handle, series, joined, amount ?? 1)) {
+      if (!ffi.metricsRecordStr(live(), series, joined, amount ?? 1)) {
         throw new Error('metrics record: unknown series / arity mismatch / invalid amount')
       }
     },
     gaugeSet(series, values, value) {
       const joined = (values ?? []).join('\u001f')
-      if (!ffi.metricsGaugeSetStr(handle, series, joined, value)) {
+      if (!ffi.metricsGaugeSetStr(live(), series, joined, value)) {
         throw new Error('metrics gauge set: unknown series / arity mismatch')
       }
     },
@@ -371,24 +391,27 @@ function ffiMetricsRegistry(ffi: BunFFI): MetricsRegistryInstance {
       // Probe large enough for typical registries (one native pass), then
       // grow exactly once if ever exceeded (needed-size convention).
       let out = new Uint8Array(8192)
-      let w = ffi.metricsRender(handle, out)
+      let w = ffi.metricsRender(live(), out)
       if (w > out.length) {
         out = new Uint8Array(w)
-        w = ffi.metricsRender(handle, out)
+        w = ffi.metricsRender(live(), out)
       }
       return decodeUtf8(out.subarray(0, w))
     },
     destroy() {
-      ffi.metricsDestroy(handle)
+      if (handle !== 0) {
+        ffi.metricsDestroy(handle)
+        handle = 0
+      }
     },
     snapshot() {
       // Packed v1 dump — decoded by consumers (the @ignex/native metrics
       // wrapper); probe large, grow exactly once.
       let out = new Uint8Array(4096)
-      let w = ffi.metricsSnapshot(handle, out)
+      let w = ffi.metricsSnapshot(live(), out)
       if (w > out.length) {
         out = new Uint8Array(w)
-        w = ffi.metricsSnapshot(handle, out)
+        w = ffi.metricsSnapshot(live(), out)
       }
       return out.subarray(0, w)
     },
@@ -405,11 +428,12 @@ export function buildFactories(ctx: RustClientContext) {
       const ffi = transport.ffi
       if (ffi) {
         const napi = new addon.SchemaValidator(schema)
-        return ffiSchemaValidator(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+        return ffiSchemaValidator(napi, handlePtr(napi.innerPtr?.()), ffi)
       }
       return new addon.SchemaValidator(schema)
     },
     createHmacSigner(key: Uint8Array): HmacSignerInstance {
+      assertNonEmptySecret(key, 'createHmacSigner')
       const ffi = transport.ffi
       if (ffi) return ffiHmacSigner(key, ffi)
       return new addon.HmacSigner(key)
@@ -418,7 +442,7 @@ export function buildFactories(ctx: RustClientContext) {
       const ffi = transport.ffi
       if (ffi) {
         const napi = new addon.TemplateRenderer(source)
-        return ffiTemplateRenderer(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+        return ffiTemplateRenderer(napi, handlePtr(napi.innerPtr?.()), ffi)
       }
       return new addon.TemplateRenderer(source)
     },
@@ -440,7 +464,7 @@ export function buildFactories(ctx: RustClientContext) {
       const ffi = transport.ffi
       if (ffi) {
         const napi = new addon.ConditionalRequest(etagValue, lastModifiedSecs ?? undefined)
-        return ffiConditionalRequest(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+        return ffiConditionalRequest(napi, handlePtr(napi.innerPtr?.()), ffi)
       }
       return new addon.ConditionalRequest(etagValue, lastModifiedSecs ?? undefined)
     },
@@ -448,7 +472,7 @@ export function buildFactories(ctx: RustClientContext) {
       const ffi = transport.ffi
       if (ffi) {
         const napi = new addon.AcceptNegotiator(supported)
-        return ffiAcceptNegotiator(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+        return ffiAcceptNegotiator(napi, handlePtr(napi.innerPtr?.()), ffi)
       }
       return new addon.AcceptNegotiator(supported)
     },
@@ -458,11 +482,13 @@ export function buildFactories(ctx: RustClientContext) {
       return new addon.Base64Codec(urlSafe ?? undefined, padding ?? undefined)
     },
     createCookieSigner(secret: Uint8Array): CookieSignerInstance {
+      assertNonEmptySecret(secret, 'createCookieSigner')
       const ffi = transport.ffi
       if (ffi) return ffiCookieSigner(secret, ffi)
       return new addon.CookieSigner(secret)
     },
     createCsrfProtector(secret: Uint8Array): CsrfProtectorInstance {
+      assertNonEmptySecret(secret, 'createCsrfProtector')
       const ffi = transport.ffi
       if (ffi) return ffiCsrfProtector(secret, ffi)
       return new addon.CsrfProtector(secret)
@@ -474,15 +500,16 @@ export function buildFactories(ctx: RustClientContext) {
       const ffi = transport.ffi
       if (ffi) {
         const napi = new addon.UrlBuilder(base)
-        return ffiUrlBuilder(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+        return ffiUrlBuilder(napi, handlePtr(napi.innerPtr?.()), ffi)
       }
       return new addon.UrlBuilder(base)
     },
     createJwtSigner(secret: Uint8Array, ttlSeconds?: number): JwtSignerInstance {
+      assertNonEmptySecret(secret, 'createJwtSigner')
       const ffi = transport.ffi
       if (ffi) {
         const napi = new addon.JwtSigner(secret, ttlSeconds ?? undefined)
-        return ffiJwtSigner(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+        return ffiJwtSigner(napi, handlePtr(napi.innerPtr?.()), ffi)
       }
       return new addon.JwtSigner(secret, ttlSeconds ?? undefined)
     },
@@ -500,7 +527,7 @@ export function buildFactories(ctx: RustClientContext) {
       const ffi = transport.ffi
       if (ffi) {
         const napi = new addon.MediaTypeMatcher(expected)
-        return ffiMediaTypeMatcher(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+        return ffiMediaTypeMatcher(napi, handlePtr(napi.innerPtr?.()), ffi)
       }
       return new addon.MediaTypeMatcher(expected)
     },
@@ -512,7 +539,7 @@ export function buildFactories(ctx: RustClientContext) {
       const ffi = transport.ffi
       if (ffi) {
         const napi = new addon.RateLimiter(limit, windowMs, maxEntries ?? undefined)
-        return ffiRateLimiter(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+        return ffiRateLimiter(napi, handlePtr(napi.innerPtr?.()), ffi)
       }
       return new addon.RateLimiter(limit, windowMs, maxEntries ?? undefined)
     },

package/src/rust-ffi/scalar/http.ts

@@ -12,7 +12,7 @@
 import type { EncodingPrefResult, MediaTypeResult } from '../../native'
 import type { BunFFI } from '../../native/ffi'
 import { decoder, hasNul } from '../../shared/bytes'
-import { decodeUtf8Fatal, decodeUtf8Range } from '../../shared/codec'
+import { decodeUtf8Fatal, decodeUtf8Range, decodeUtf8RangeView } from '../../shared/codec'
 import { packPairs } from '../../shared/packed'
 import { memoizeFfi, type RustClientContext, resolveNative } from '../context'
 import { writeInto } from '../into'
@@ -59,6 +59,19 @@ function u32LE(b: Uint8Array, off: number): number {
   )
 }
 
+/** ASCII byte form of the two known media-type param keys (byte-compare
+ * targets — avoids decoding the key string for every packed param). */
+const CHARSET_KEY_BYTES = new Uint8Array([0x63, 0x68, 0x61, 0x72, 0x73, 0x65, 0x74]) // 'charset'
+const BOUNDARY_KEY_BYTES = new Uint8Array([0x62, 0x6f, 0x75, 0x6e, 0x64, 0x61, 0x72, 0x79]) // 'boundary'
+
+/** Byte-equality of `b[off..off+len]` with the literal `lit` (no allocation). */
+function keyBytesEqual(b: Uint8Array, off: number, lit: Uint8Array): boolean {
+  for (let i = 0; i < lit.length; i++) {
+    if ((b[off + i] ?? 0) !== (lit[i] ?? 0)) return false
+  }
+  return true
+}
+
 /**
  * Unpack the `castrum_parse_media_type` verdict into the napi-shaped result.
  * Layout: `[u32 mediaTypeLen][mediaType][u32 charsetLen (0xFFFFFFFF = none)]
@@ -69,42 +82,75 @@ function u32LE(b: Uint8Array, off: number): number {
 function unpackMediaType(packed: Uint8Array): MediaTypeResult {
   // Ranged decode straight off the (pooled) packed buffer — no per-field
   // subarray views. ASCII fields take the latin1 fast path.
+  // ONE view per result: `decodeUtf8RangeView` decodes at absolute offsets
+  // into a bounded Buffer resolved once here — the per-field WeakMap lookup
+  // + offset arithmetic in `decodeUtf8Range` disappear (profile: unpackMediaType
+  // called the cached-view path 5x per result).
+  const view = Buffer.from(packed.buffer, packed.byteOffset, packed.byteLength)
   let off = 0
   const mtLen = u32LE(packed, off)
   off += 4
-  const mediaType = decodeUtf8Range(packed, off, off + mtLen)
+  const mediaType = decodeUtf8RangeView(view, off, off + mtLen)
   off += mtLen
   let charset: string | null = null
   const csLen = u32LE(packed, off)
   off += 4
   if (csLen !== 0xffffffff) {
-    charset = decodeUtf8Range(packed, off, off + csLen)
+    charset = decodeUtf8RangeView(view, off, off + csLen)
     off += csLen
   }
   let boundary: string | null = null
   const bLen = u32LE(packed, off)
   off += 4
   if (bLen !== 0xffffffff) {
-    boundary = decodeUtf8Range(packed, off, off + bLen)
+    boundary = decodeUtf8RangeView(view, off, off + bLen)
     off += bLen
   }
   const count = u32LE(packed, off)
   off += 4
   const params: Record<string, string> = {}
+  // The summary slots above hold the FIRST charset/boundary occurrence (the
+  // Rust core fills them via `params.iter().find(...)`), while `params` keeps
+  // the LAST duplicate (JS assignment order). Reusing the already-decoded
+  // summary string for the first matching param skips one redundant ranged
+  // decode per named field without changing any observable value.
+  let charsetTaken = charset === null
+  let boundaryTaken = boundary === null
   for (let i = 0; i < count; i++) {
     const kLen = u32LE(packed, off)
     off += 4
-    const key = decodeUtf8Range(packed, off, off + kLen)
+    // Byte-compare the param KEY against the ASCII literals BEFORE decoding:
+    // on a match the key decode is skipped (`params` is keyed by the identical
+    // literal) and the summary/decided-value path handles the value. A
+    // byte-match to 'charset'/'boundary' implies valid UTF-8 for those bytes,
+    // so the skipped decode was exact — observable behavior unchanged
+    // (non-matching keys decode normally, casing preserved).
+    let key: string
+    if (kLen === 7 && keyBytesEqual(packed, off, CHARSET_KEY_BYTES)) {
+      key = 'charset'
+    } else if (kLen === 8 && keyBytesEqual(packed, off, BOUNDARY_KEY_BYTES)) {
+      key = 'boundary'
+    } else {
+      key = decodeUtf8RangeView(view, off, off + kLen)
+    }
     off += kLen
     const vLen = u32LE(packed, off)
     off += 4
-    const val = decodeUtf8Range(packed, off, off + vLen)
+    let val: string
+    if (!charsetTaken && key === 'charset' && charset !== null) {
+      val = charset
+      charsetTaken = true
+    } else if (!boundaryTaken && key === 'boundary' && boundary !== null) {
+      val = boundary
+      boundaryTaken = true
+    } else {
+      val = decodeUtf8RangeView(view, off, off + vLen)
+    }
     off += vLen
     params[key] = val
   }
   return { mediaType, charset, boundary, params }
 }
-
 /** Unpack the `castrum_parse_accept_encoding` verdict (f32 q-values) into the
  * napi-shaped array. Layout: `[u32 count]{[u32 encLen][enc][f32 q][u32 order]}`.
  * Ranged decode off the pooled buffer + shared f32 bit-reinterpret views —
@@ -276,7 +322,11 @@ export function buildHttp(ctx: RustClientContext) {
     queryParsePacked(input: Uint8Array): Uint8Array {
       const f = ffi()
       if (f) {
-        const out = new Uint8Array(input.length * 9 + 16)
+        // For k nonempty pairs in n bytes, k <= (n + 1) / 2: each
+        // pair needs a byte and adjacent pairs need a separator. Packed size
+        // <= 4 + 8k + (n - k + 1) <= 5n + 8; decoding never expands bytes.
+        // Cookie/form siblings use the same bound and retain fresh ownership.
+        const out = new Uint8Array(input.length * 5 + 8)
         const w = f.queryParsePackedInto(input, out)
         return out.subarray(0, w)
       }
@@ -288,7 +338,7 @@ export function buildHttp(ctx: RustClientContext) {
     cookieParsePacked(input: Uint8Array): Uint8Array {
       const f = ffi()
       if (f) {
-        const out = new Uint8Array(input.length * 9 + 16)
+        const out = new Uint8Array(input.length * 5 + 8)
         const w = f.cookieParsePackedInto(input, out)
         return out.subarray(0, w)
       }
@@ -301,7 +351,7 @@ export function buildHttp(ctx: RustClientContext) {
       const f = ffi()
       if (f) {
         // x-www-form-urlencoded uses the SAME packed-pairs core as query parse.
-        const out = new Uint8Array(input.length * 9 + 16)
+        const out = new Uint8Array(input.length * 5 + 8)
         const w = f.formParsePackedInto(input, out)
         return out.subarray(0, w)
       }

package/src/rust-ffi/scalar/interface.ts

@@ -215,7 +215,10 @@ export interface RustScalar {
   createMediaTypeMatcher(expected: Uint8Array): MediaTypeMatcherInstance
   /**
    * Sharded fixed-window per-key rate limiter. `maxEntries` clamps internally
-   * (default 1,048,576). Each instance owns an independent budget.
+   * (default 1,048,576) and has an effective floor of 16,384
+   * (`max_per_shard = max(maxEntries / 256, 64)` × 256 shards) — values below
+   * that are silently raised, so don't rely on it to bound a tiny key space.
+   * Each instance owns an independent budget.
    * @remarks Scalar per-check cost: ~3-14x SLOWER than the JS Map baseline —
    * prefer the ingress pipeline (one FFI for all stages) for native rate
    * limiting in a request path. [measured 2026-08]

package/src/rust-ffi/scalar/payload.ts

@@ -72,6 +72,11 @@ export function buildPayload(ctx: RustClientContext) {
   // Lazy-memoized ffi surface: binds on first call, single local read after.
   const ffi = memoizeFfi(transport)
 
+  // Per-Worker reused scratch for the object-returning multipartParse (the
+  // packed bytes are consumed synchronously — data is copied out, so the
+  // scratch never escapes; NOT shared with the byte-returning packed paths).
+  let SCRATCH: Uint8Array | null = null
+
   return {
     gzipCompress(data: Uint8Array, level?: number | null): Uint8Array {
       // Optimal by default under Bun: `Bun.gzipSync` (native zlib) is ~2x
@@ -140,8 +145,29 @@ export function buildPayload(ctx: RustClientContext) {
     multipartParse(body: Uint8Array, boundary: Uint8Array): MultipartPart[] {
       // FFI-first: packed parts (castrum_multipart_parse_packed) → unpack to
       // the object shape. napi keeps its object path.
+      //
+      // REUSED SCRATCH: the unpack consumes the packed bytes synchronously and
+      // each part's `data` is COPIED out (napi parity) — nothing aliases the
+      // scratch after return, so the escaping-buffer rule does not apply here.
+      // Sizing matches the allocating sibling (body + boundary + 64).
       const f = ffi()
-      if (f) return unpackMultipart(f.multipartParsePacked(body, boundary))
+      if (f) {
+        const need = body.length + boundary.length + 64
+        // Keep retained scratch bounded; the allocating transport handles exact
+        // growth and the output cap for large uploads. The public Into wrapper
+        // THROWS on insufficient capacity, rather than returning a needed size.
+        if (need > 64 * 1024) return unpackMultipart(f.multipartParsePacked(body, boundary))
+        if (!SCRATCH || SCRATCH.length < need) SCRATCH = new Uint8Array(need)
+        let w: number
+        try {
+          w = f.multipartParsePackedInto(body, boundary, SCRATCH)
+        } catch {
+          // An estimate miss (e.g. UTF-8 replacement expansion) uses the same
+          // checked allocating path. Malformed input still fails there.
+          return unpackMultipart(f.multipartParsePacked(body, boundary))
+        }
+        return unpackMultipart(SCRATCH.subarray(0, w))
+      }
       // Normalize napi `Option<String>` (undefined) → null and expose the
       // camelCase `contentType` key (napi renames `content_type` to camelCase).
       return addon.multipartParse(body, boundary).map((p) => ({

package/src/shared/buffer-pool.ts

@@ -39,6 +39,21 @@
    * converge on one buffer size instead of re-growing each time. Default false.
    */
   adaptive?: boolean
+  /**
+   * Number of buffers (beyond the initial one) to ALLOCATE UP FRONT at
+   * construction, so a burst-ramp (e.g. a load-test connection flood) never
+   * pays per-request `new Uint8Array` + GC during its first wave. A pure
+   * memory-for-latency trade: retained memory becomes `prefill + 1` ×
+   * `initialSize` (still bounded by `maxBuffers`). Default 0.
+   */
+  prefill?: number
+  /**
+   * Byte budget for `prefill`: the prefilled count is additionally capped to
+   * `floor(prefillBytes / initialSize)`, so a large `initialSize` (e.g. a
+   * 64 MiB output buffer) cannot multiply into gigabytes when a router creates
+   * one pool per route. Default `Infinity` (only `prefill`/`maxBuffers` apply).
+   */
+  prefillBytes?: number
 }
 
 /** A borrowed buffer handle handed out by a pool; `release()` returns it. */
@@ -138,6 +153,22 @@ export class BufferPool {
         : null
     this.free.push(new Uint8Array(this.initialSize))
     this.created = 1
+    // Pre-fill (memory-for-latency trade, see `prefill` in BufferPoolOptions):
+    // spend up-front allocation so a burst ramp never allocates during its
+    // first wave. Capped at maxBuffers so the documented retention bound
+    // (free list ≤ maxBuffers) still holds, and by `prefillBytes` so a large
+    // `initialSize` cannot multiply into an unbounded up-front allocation.
+    const prefill = Math.min(
+      Math.max(0, Math.floor(options.prefill ?? 0)),
+      this.maxBuffers - 1,
+      options.prefillBytes !== undefined
+        ? Math.max(0, Math.floor(options.prefillBytes / this.initialSize))
+        : Number.POSITIVE_INFINITY,
+    )
+    for (let i = 0; i < prefill; i++) {
+      this.free.push(new Uint8Array(this.initialSize))
+      this.created++
+    }
   }
 
   /** Number of buffers currently available for immediate reuse. */
@@ -204,11 +235,14 @@ export class BufferPool {
     // Learn the observed demand so future allocations pre-size to it.
     this.estimate?.sample(minSize)
 
-    // 1) Reuse a free buffer that is already large enough.
+    // 1) Reuse a free buffer that is already large enough. Free-list ORDER is
+    //    irrelevant, so remove by swap-with-last (O(1), no splice compaction/
+    //    allocation) — this is a per-request hot path.
     for (let i = 0; i < this.free.length; i++) {
       const candidate = this.free[i] as Uint8Array
       if (candidate.byteLength >= minSize) {
-        this.free.splice(i, 1)
+        const last = this.free.pop() as Uint8Array
+        if (i < this.free.length) this.free[i] = last
         return candidate
       }
     }
@@ -227,7 +261,8 @@ export class BufferPool {
       }
     }
     if (largestBuf !== null) {
-      this.free.splice(largest, 1)
+      const last = this.free.pop() as Uint8Array
+      if (largest < this.free.length) this.free[largest] = last
       this.created++
       return new Uint8Array(target)
     }
@@ -241,16 +276,16 @@ export class BufferPool {
   private releaseBuffer(buffer: Uint8Array): void {
     if (this.free.length >= this.maxBuffers) {
       // Free list is full: drop the smallest retained buffer to stay bounded.
-      let smallestBuf: Uint8Array | null = null
       let smallest = 0
-      for (let i = 0; i < this.free.length; i++) {
-        const candidate = this.free[i] as Uint8Array
-        if (smallestBuf === null || candidate.byteLength < smallestBuf.byteLength) {
-          smallestBuf = candidate
+      for (let i = 1; i < this.free.length; i++) {
+        if (
+          (this.free[i] as Uint8Array).byteLength < (this.free[smallest] as Uint8Array).byteLength
+        ) {
           smallest = i
         }
       }
-      this.free.splice(smallest, 1)
+      const last = this.free.pop() as Uint8Array
+      if (smallest < this.free.length) this.free[smallest] = last
     }
     this.free.push(buffer)
   }

package/src/shared/codec.ts

@@ -79,6 +79,32 @@ export const decodeUtf8: (bytes: Uint8Array) => string = runtimeCodec.decodeUtf8
 export const decodeUtf8Range: (bytes: Uint8Array, start: number, end: number) => string =
   runtimeCodec.decodeUtf8Range
 
+/**
+ * Decode a range of a PREPARED bounded Buffer `view` (absolute offsets into
+ * the view) to a string — replacement mode on invalid. Companion to
+ * `decodeUtf8Range` for packed-wire unpackers that decode MANY fields from
+ * ONE packed result: the caller resolves the Buffer view once and every field
+ * decode skips the per-field cache lookup + offset arithmetic.
+ *
+ * Falls back to `decodeUtf8Range` when the runtime codec does not provide the
+ * view variant (older adapters / custom codecs).
+ *
+ * @param view - A bounded Buffer over the packed bytes.
+ * @param start - Range start (inclusive, relative to the view).
+ * @param end - Range end (exclusive, relative to the view).
+ * @returns The decoded string.
+ *
+ * @example
+ * ```ts
+ * const view = Buffer.from(packed.buffer, packed.byteOffset, packed.byteLength)
+ * decodeUtf8RangeView(view, 4, 24) // → 'multipart/form-data'
+ * ```
+ */
+export const decodeUtf8RangeView: (view: Buffer, start: number, end: number) => string =
+  runtimeCodec.decodeUtf8RangeView
+    ? runtimeCodec.decodeUtf8RangeView
+    : (view, start, end) => decodeUtf8Range(view, start, end)
+
 /**
  * Decode UTF-8 bytes to a string, throwing on invalid UTF-8.
  *

package/src/shared/packed/parsers.ts

@@ -4,28 +4,85 @@
 // don't have to hand-pack buffers or decode packed pairs:
 //   parseQueryString("a=1&b=2")    // { a: "1", b: "2" }
 //   parseCookieHeader("a=1; b=2")  // { a: "1", b: "2" }
+//
+// Transport: bun:ffi PRIMARY — the packed pairs are consumed SYNCHRONOUSLY
+// (readPairsPacked + pairsToObject materialize strings before return), so a
+// reused per-parser scratch is safe (same model as the scalar unpackers);
+// the bytes never escape. Node / `CASTRUM_FFI_MODE=napi` / bind failure fall
+// back to the napi addon (same wire output — pinned by packed-parsers-routing).
 
+import { getBunFFI } from '../../native/ffi'
 import { getAddon, lazyAddon } from '../../native'
 import { encoder } from '../bytes'
 import { pairsToObject, readPairsPacked } from './wire'
 
-// Lazy: importing this module does not dlopen the addon until first use.
+// Lazy: importing this module does not dlopen the addon until first use
+// (getBunFFI binds on first call; the napi proxy loads on first get).
 const addon = lazyAddon(getAddon)
 
+// FFI scratch (documented impure module state, per-Worker): grown lazily and
+// reused across calls — the parsed result is a JS object, the packed bytes
+// never escape.
+const ffiCaches: Record<'query' | 'cookie' | 'form', Uint8Array | null> = {
+  query: null,
+  cookie: null,
+  form: null,
+}
+function scratchFor(kind: 'query' | 'cookie' | 'form', input: Uint8Array): Uint8Array {
+  // Packed pairs worst case ≈ 9× input (u32 len + bytes per key/value) + header.
+  const need = input.length * 9 + 16
+  let s = ffiCaches[kind]
+  if (s === null || s.length < need) {
+    s = new Uint8Array(need)
+    ffiCaches[kind] = s
+  }
+  return s
+}
+
+function parsePackedInto(
+  kind: 'query' | 'cookie' | 'form',
+  input: Uint8Array,
+): Record<string, string | string[]> | null {
+  const f = getBunFFI()
+  if (!f) return null
+  const out = scratchFor(kind, input)
+  const w =
+    kind === 'query'
+      ? f.queryParsePackedInto(input, out)
+      : kind === 'cookie'
+        ? f.cookieParsePackedInto(input, out)
+        : f.formParsePackedInto(input, out)
+  if (w === 0 || w > out.length) return null
+  return pairsToObject(readPairsPacked(out.subarray(0, w)))
+}
+
+/** Shared FFI-first parse with an napi fallback (one encode, per kind). */
+function parseVia(
+  kind: 'query' | 'cookie' | 'form',
+  input: Uint8Array,
+): Record<string, string | string[]> {
+  const fast = parsePackedInto(kind, input)
+  if (fast) return fast
+  const packed =
+    kind === 'query'
+      ? addon.queryParsePacked(input)
+      : kind === 'cookie'
+        ? addon.cookieParsePacked(input)
+        : addon.formParsePacked(input)
+  return pairsToObject(readPairsPacked(packed))
+}
+
 /** Parse a query string (`a=1&b=2`) into an object via the native parser. */
 export function parseQueryString(query: string): Record<string, string | string[]> {
-  const packed = addon.queryParsePacked(encoder.encode(query))
-  return pairsToObject(readPairsPacked(packed))
+  return parseVia('query', encoder.encode(query))
 }
 
 /** Parse a cookie header (`a=1; b=2`) into an object via the native parser. */
 export function parseCookieHeader(header: string): Record<string, string | string[]> {
-  const packed = addon.cookieParsePacked(encoder.encode(header))
-  return pairsToObject(readPairsPacked(packed))
+  return parseVia('cookie', encoder.encode(header))
 }
 
 /** Parse an application/x-www-form-urlencoded body into a key/value object. */
 export function parseFormBody(body: Uint8Array): Record<string, string | string[]> {
-  const packed = addon.formParsePacked(body)
-  return pairsToObject(readPairsPacked(packed))
+  return parseVia('form', body)
 }