castrum 0.7.0 → 0.9.1

package/src/selection.json

@@ -0,0 +1,194 @@
+{
+  "generatedAt": "2026-08-13T09:13:26.107Z",
+  "note": "Auto-selected by `bun scripts/select-native.ts --write` from measurements of the castrum addon vs representative pure-TS implementations. Do NOT hand-edit — regenerate with the benchmark script. The public API reads this via `opImpl(op)` and binds each op to a fixed impl (native or js) at load time.",
+  "ops": {
+    "fnv1a64": {
+      "impl": "native",
+      "nativeRatio": 12.603
+    },
+    "crc32": {
+      "impl": "js",
+      "nativeRatio": 0.659
+    },
+    "hmacSha256": {
+      "impl": "native",
+      "nativeRatio": 1.212
+    },
+    "hmacSha256Verify": {
+      "impl": "native",
+      "nativeRatio": 9.028
+    },
+    "signCookie": {
+      "impl": "native",
+      "nativeRatio": 3.64
+    },
+    "verifyCookie": {
+      "impl": "native",
+      "nativeRatio": 1.772
+    },
+    "csrfToken": {
+      "impl": "native",
+      "nativeRatio": 12.671
+    },
+    "csrfVerify": {
+      "impl": "native",
+      "nativeRatio": 12.458
+    },
+    "randomToken": {
+      "impl": "native",
+      "nativeRatio": 9.546
+    },
+    "passwordHash": {
+      "impl": "native",
+      "nativeRatio": 1.657
+    },
+    "aeadEncrypt": {
+      "impl": "native",
+      "nativeRatio": 1.288
+    },
+    "aeadDecrypt": {
+      "impl": "native",
+      "nativeRatio": 1.108
+    },
+    "queryPairs": {
+      "impl": "js",
+      "nativeRatio": 0.279
+    },
+    "cookiePairs": {
+      "impl": "js",
+      "nativeRatio": 0.105
+    },
+    "formPairs": {
+      "impl": "js",
+      "nativeRatio": 0.328
+    },
+    "etag": {
+      "impl": "js",
+      "nativeRatio": 0.187
+    },
+    "parseMediaType": {
+      "impl": "js",
+      "nativeRatio": 0.378
+    },
+    "parseAcceptEncoding": {
+      "impl": "js",
+      "nativeRatio": 0.367
+    },
+    "createConditionalRequest": {
+      "impl": "js",
+      "nativeRatio": 0.275
+    },
+    "createAcceptNegotiator": {
+      "impl": "native",
+      "nativeRatio": 2.01
+    },
+    "multipartParse": {
+      "impl": "js",
+      "nativeRatio": null
+    },
+    "jsonValid": {
+      "impl": "js",
+      "nativeRatio": 0.749
+    },
+    "jsonPatch": {
+      "impl": "js",
+      "nativeRatio": 0.014
+    },
+    "gzipCompress": {
+      "impl": "native",
+      "nativeRatio": 22.132
+    },
+    "gzipDecompress": {
+      "impl": "native",
+      "nativeRatio": 61.039
+    },
+    "brotliCompress": {
+      "impl": "native",
+      "nativeRatio": 9.983
+    },
+    "brotliDecompress": {
+      "impl": "native",
+      "nativeRatio": 33.327
+    },
+    "sseEncode": {
+      "impl": "js",
+      "nativeRatio": 0.586
+    },
+    "wsFrameEncode": {
+      "impl": "js",
+      "nativeRatio": 0.152
+    },
+    "wsFrameDecode": {
+      "impl": "js",
+      "nativeRatio": 0.988
+    },
+    "wsAcceptKey": {
+      "impl": "js",
+      "nativeRatio": 0.939
+    },
+    "validateEmail": {
+      "impl": "js",
+      "nativeRatio": 0.007
+    },
+    "validateUuid": {
+      "impl": "js",
+      "nativeRatio": 0.008
+    },
+    "validateIpv4": {
+      "impl": "js",
+      "nativeRatio": 0.012
+    },
+    "validateIpv6": {
+      "impl": "js",
+      "nativeRatio": 0.078
+    },
+    "createRateLimiter": {
+      "impl": "js",
+      "nativeRatio": 0.061
+    },
+    "renderTemplate": {
+      "impl": "js",
+      "nativeRatio": 0.141
+    },
+    "xxh3": {
+      "impl": "native",
+      "nativeRatio": null
+    },
+    "urlEncode": {
+      "impl": "js",
+      "nativeRatio": 0.214
+    },
+    "urlDecode": {
+      "impl": "js",
+      "nativeRatio": 0.092
+    },
+    "base64Encode": {
+      "impl": "js",
+      "nativeRatio": 0.376
+    },
+    "httpDate": {
+      "impl": "js",
+      "nativeRatio": 0.401
+    },
+    "jwtSign": {
+      "impl": "native",
+      "nativeRatio": null
+    },
+    "jwtVerify": {
+      "impl": "native",
+      "nativeRatio": null
+    },
+    "passwordVerify": {
+      "impl": "native",
+      "nativeRatio": null
+    },
+    "createTemplate": {
+      "impl": "native",
+      "nativeRatio": null
+    },
+    "createSchemaValidator": {
+      "impl": "native",
+      "nativeRatio": null
+    }
+  }
+}

package/src/selection.ts

@@ -0,0 +1,73 @@
+// src/selection.ts — native-vs-JS selection surface (OWNED BY CASTRUM).
+//
+// The decision of whether an operation should use the Rust addon ("native")
+// or a pure-JS implementation ("js") is a property of this library, not of
+// any consumer. The single source of truth is `rust/selection.rs`
+// (benchmark-driven, audited by `scripts/select-native.ts --check`); this
+// module is its TS projection and the API consumers call ONCE at load time.
+//
+// Consumers bind each operation to a fixed implementation at startup by
+// reading `opImpl(op)` here — they do NOT swap native↔js per call.
+//
+// The baked default comes from the PROVEN SELECTION registry
+// (`src/shared/proven.ts`, `PROVEN_SELECTION`): for each op the
+// benchmark-proven winner is 'native' | 'js' | 'bun' (Bun built-in
+// delegation). Bun built-in delegation is runtime-aware via the adapter's
+// `builtins` registry (`runtimeNative.builtins.has(op)` — empty under Node).
+// `test/unit/shared/proven.test.ts` verifies this baked registry matches the
+// live wiring, so it can't drift.
+
+import { getAddon, lazyAddon } from './native'
+import { provenImpl } from './shared/proven'
+import { runtimeNative } from './runtime/native'
+
+/** Recommended implementation for an operation. */
+export type OpImpl = 'native' | 'js'
+
+/** A selection decision: recommended implementation + rationale note. */
+export interface OpDecision {
+  /** The recommended implementation when the addon is available. */
+  readonly impl: OpImpl
+  /** Why this decision (measured ratio / rationale). */
+  readonly note?: string
+}
+
+// Lazy: importing this module does NOT dlopen the addon; `opImpl` reads the
+// baked decision from Rust on first call.
+const addon = lazyAddon(getAddon)
+
+/**
+ * The benchmark-driven native-vs-JS decision for `op` — runtime-aware.
+ *
+ * Returns `"native"` when the Rust addon is the recommended implementation,
+ * `"js"` when a pure-JS (or Bun built-in) implementation wins, or `null` for
+ * unknown ops (or when the addon is unavailable — with no addon there is no
+ * "native" choice). Under Bun, ops in the adapter's builtins registry resolve
+ * to `"js"` so the consumer's JS path delegates to the faster Bun built-in.
+ *
+ * The default is the BAKED proven selection (`src/shared/proven.ts`):
+ * `native` / `js` directly, `bun` resolves to `"js"` via the builtins check
+ * above. Unknown ops (and `bun` entries on a non-Bun runtime, where no
+ * built-in exists) fall back to the addon's embedded decision
+ * (`rust/selection.rs` ← `src/selection.json`).
+ */
+export const opImpl = (op: string): OpImpl | null => {
+  // Bun built-in delegation (runtime-aware — the registry is empty under Node).
+  if (runtimeNative.builtins.has(op)) return 'js'
+  // Baked proven winners are the default selection.
+  const proven = provenImpl(op)
+  if (proven === 'native') return 'native'
+  if (proven === 'js') return 'js'
+  // 'bun' on a non-Bun runtime (no built-in) or unknown ops → addon decision.
+  return addon.opImpl(op)
+}
+
+/** `true` when the Rust addon is the recommended impl for `op`. */
+export const isNativeOp = (op: string): boolean => opImpl(op) === 'native'
+
+/** The decision record for `op`, or `null` when unknown. */
+export const opDecision = (op: string): OpDecision | null => {
+  const impl = opImpl(op)
+  if (impl === null) return null
+  return { impl }
+}

package/src/shared/adaptive.ts

@@ -0,0 +1,67 @@
+// src/shared/adaptive.ts — Reusable EWMA adaptive-estimate utility.
+//
+// The loader's cost model (src/loader/cost.ts) learns per-op dispatch costs at
+// runtime with an exponential moving average (EWMA). This is that same
+// machinery, extracted as a tiny reusable class so OTHER subsystems can
+// self-optimize without re-implementing the math — e.g. BufferPool learns the
+// observed request size to pre-size future buffers (`adaptive` option), and
+// consumers can drive their own runtime decisions (batch-vs-loop, delegate
+// vs-native, cache-size) with a bounded, noise-smoothed estimate.
+/** Options for an `AdaptiveEstimate`: EWMA smoothing, bounds, starting value. */ export interface AdaptiveEstimateOptions {
+  /**
+   * EWMA smoothing factor in (0, 1]. Higher reacts faster to new samples;
+   * lower smooths more. Default: 0.25.
+   */
+  alpha?: number
+  /** Starting estimate. Default 0 (the first sample wins). */
+  initial?: number
+  /** Clamp the estimate to at least this. Default 0. */
+  min?: number
+  /** Clamp the estimate to at most this (bounds memory / resources). Default Infinity. */
+  max?: number
+}
+
+/**
+ * A bounded exponential-moving-average estimate of an observed quantity.
+ *
+ * `sample(x)` folds a new observation into the running estimate; `estimate`
+ * reads the current value. The estimate is clamped to `[min, max]`, so it is
+ * safe to drive resource sizing (buffer pools, batch thresholds) with it —
+ * a single outlier cannot blow up the estimate, and it decays toward recent
+ * observations.
+ */
+export class AdaptiveEstimate {
+  private readonly alpha: number
+  private readonly min: number
+  private readonly max: number
+  private readonly initial: number
+  private value: number
+
+  constructor(options: AdaptiveEstimateOptions = {}) {
+    const alpha = options.alpha ?? 0.25
+    if (!Number.isFinite(alpha) || alpha <= 0 || alpha > 1) {
+      throw new RangeError(`AdaptiveEstimate: alpha must be in (0,1], got ${alpha}`)
+    }
+    this.alpha = alpha
+    this.min = Math.max(0, options.min ?? 0)
+    this.max = options.max ?? Number.POSITIVE_INFINITY
+    this.initial = options.initial ?? 0
+    this.value = this.initial
+  }
+
+  /** Fold a new observation into the running estimate. */
+  sample(x: number): void {
+    const v = this.value === 0 ? x : this.value * (1 - this.alpha) + x * this.alpha
+    this.value = v < this.min ? this.min : v > this.max ? this.max : v
+  }
+
+  /** Current estimate (clamped to `[min, max]`). */
+  get estimate(): number {
+    return this.value
+  }
+
+  /** Reset the estimate (back to `initial`). */
+  reset(): void {
+    this.value = this.initial
+  }
+}

package/src/shared/buffer-pool.ts

@@ -0,0 +1,264 @@
+// src/shared/buffer-pool.ts — generic reusable byte-buffer pool for hot-path FFI calls.
+//
+// Hot native-FFI paths (e.g. the ingress pipeline) write into large output
+// buffers. Allocating a fresh buffer per call is a measurable cost at high
+// request rates. This pool hands out buffers that are returned to the pool
+// once the consumer is done with them, eliminating steady-state allocation.
+//
+// It is deliberately generic: it works with any `Uint8Array` consumer, is safe
+// for a single-threaded event loop, and supports both eager release (callers
+// that copy out immediately) and in-flight borrowing (zero-copy callers that
+// hold the buffer past the call). Memory is bounded by `maxBuffers` retained
+// buffers; under heavy concurrency, extra temporary buffers are allocated and
+// discarded on release.
+/** Options for configuring a reusable byte-buffer pool. */ export interface BufferPoolOptions {
+  /**
+   * Initial buffer size in bytes. Default: 131072.
+   */
+  initialSize?: number
+  /**
+   * Upper bound on buffers retained by the pool. When this is reached and no
+   * free buffer is large enough, the largest free buffer is grown in place
+   * (replaced) so memory stays bounded. If the pool is fully in-flight, a
+   * temporary buffer is allocated and discarded on release. Default: 16.
+   */
+  maxBuffers?: number
+  /**
+   * Hard cap on the number of buffers simultaneously in flight (acquired but
+   * not yet released). When exceeded, `acquire()` throws a `RangeError` — a
+   * backpressure signal for zero-copy responses consumed too slowly. 0
+   * (default) is unlimited: when the retained set is exhausted, temporary
+   * buffers are allocated and discarded on release (unbounded under a slow
+   * zero-copy consumer — set this to bound it).
+   */
+  maxInFlight?: number
+  /**
+   * When true, learn the observed request size (EWMA over `minSize` at each
+   * take) and pre-size new buffers to at least the learned estimate (bounded
+   * by `maxBuffers` retention). Helps workloads with varying request sizes
+   * converge on one buffer size instead of re-growing each time. Default false.
+   */
+  adaptive?: boolean
+}
+
+/** A borrowed buffer handle handed out by a pool; `release()` returns it. */
+export interface PooledBuffer {
+  /**
+   * The underlying buffer. Its byteLength is guaranteed to be at least the
+   * `minSize` requested at acquire time.
+   */
+  readonly buffer: Uint8Array
+  /**
+   * Whether this handle has already been returned to the pool.
+   */
+  readonly released: boolean
+  /**
+   * Return the buffer to the pool for reuse. Safe to call more than once;
+   * subsequent calls are no-ops.
+   */
+  release(): void
+}
+
+/**
+ * Concrete `PooledBuffer` handle.
+ *
+ * Implemented as a class (not a per-acquire object literal with a getter +
+ * closure) so that `acquire()` allocates a single small object instead of an
+ * object + getter + closure per request. The hot ingress `run()` path
+ * acquires/releases once per request, so this removes one object allocation
+ * and one closure allocation from the per-request cost. `release()` lives on
+ * the prototype; `pool`/`buffer` are the only per-instance fields.
+ *
+ * Handles are RECYCLED by the pool (see `BufferPool.freeHandles`): a released
+ * handle object is re-pointed at a fresh buffer on the next `acquire()` so the
+ * steady state allocates zero handle objects. `buffer` and `released` are the
+ * only fields that change across a recycle. Recycling is safe because it only
+ * happens after `release()` and every internal + documented usage releases
+ * each checkout exactly once; the `released` guard still makes a double
+ * release within a single checkout a no-op.
+ */
+class PooledBufferHandle implements PooledBuffer {
+  readonly pool: BufferPool
+  buffer: Uint8Array
+  released = false
+
+  constructor(pool: BufferPool, buffer: Uint8Array) {
+    this.pool = pool
+    this.buffer = buffer
+  }
+
+  release(): void {
+    if (this.released) {
+      return
+    }
+    this.released = true
+    this.pool.returnHandle(this)
+  }
+}
+
+import { AdaptiveEstimate } from './adaptive'
+
+/**
+ * A pool of reusable `Uint8Array` buffers.
+ *
+ * @example
+ * ```ts
+ * const pool = new BufferPool({ initialSize: 131072 });
+ *
+ * const handle = pool.acquire(131072);
+ * try {
+ *   // write into handle.buffer ...
+ *   useBytes(handle.buffer.subarray(0, written));
+ * } finally {
+ *   handle.release();
+ * }
+ * ```
+ */
+export class BufferPool {
+  private readonly free: Uint8Array[] = []
+  /** Released handle objects available for recycling (bounded — see `maxHandles`). */
+  private readonly freeHandles: PooledBufferHandle[] = []
+  private readonly initialSize: number
+  private readonly maxBuffers: number
+  private readonly maxInFlight: number
+  /** Upper bound on recycled handle objects retained (peak concurrency). */
+  private readonly maxHandles: number
+  private readonly estimate: AdaptiveEstimate | null
+  private created = 0
+  private inFlight = 0
+
+  constructor(options: BufferPoolOptions = {}) {
+    this.initialSize = Math.max(1, Math.floor(options.initialSize ?? 131_072))
+    this.maxBuffers = Math.max(1, Math.floor(options.maxBuffers ?? 16))
+    this.maxInFlight = Math.max(0, Math.floor(options.maxInFlight ?? 0))
+    this.maxHandles = this.maxBuffers + Math.max(1, this.maxInFlight)
+    this.estimate =
+      options.adaptive === true
+        ? new AdaptiveEstimate({ alpha: 0.25, min: this.initialSize })
+        : null
+    this.free.push(new Uint8Array(this.initialSize))
+    this.created = 1
+  }
+
+  /** Number of buffers currently available for immediate reuse. */
+  get freeCount(): number {
+    return this.free.length
+  }
+
+  /** Total number of buffers this pool has allocated (monotonic). */
+  get createdCount(): number {
+    return this.created
+  }
+
+  /**
+   * Acquire a buffer of at least `minSize` bytes. The returned handle must be
+   * released (directly, or via a zero-copy Response) once the caller is done.
+   *
+   * @param minSize - Minimum buffer size in bytes. Default: 0 (any free buffer).
+   * @throws RangeError when `maxInFlight` is set and that many buffers are
+   *   already borrowed (never released).
+   */
+  acquire(minSize = 0): PooledBuffer {
+    if (this.maxInFlight > 0 && this.inFlight >= this.maxInFlight) {
+      throw new RangeError(
+        `BufferPool: maxInFlight (${this.maxInFlight}) exceeded — too many ` +
+          'buffers borrowed at once (unreleased zero-copy responses?). ' +
+          'Raise maxInFlight or consume/release responses faster.',
+      )
+    }
+    const buffer = this.take(Math.max(0, Math.floor(minSize)))
+    this.inFlight++
+    // Recycle a released handle object in the steady state instead of
+    // allocating a fresh one per acquire (removes one per-request object from
+    // the hot ingress `run()` path). Safe: handles enter `freeHandles` only
+    // after `release()`, and each checkout is released exactly once by every
+    // internal + documented usage. `buffer`/`released` are the only fields
+    // that change across a recycle.
+    const handle = this.freeHandles.pop()
+    if (handle !== undefined) {
+      handle.buffer = buffer
+      handle.released = false
+      return handle
+    }
+    return new PooledBufferHandle(this, buffer)
+  }
+
+  /**
+   * Return a borrowed handle's buffer to the pool (called by
+   * `PooledBufferHandle.release`). Internal to the pool — do not call from
+   * outside.
+   */
+  returnHandle(handle: PooledBufferHandle): void {
+    this.inFlight--
+    this.releaseBuffer(handle.buffer)
+    // Recycle the handle object for a later acquire, bounding retention so
+    // memory stays proportional to concurrency (peak in-flight), not the
+    // cumulative number of acquisitions.
+    if (this.freeHandles.length < this.maxHandles) {
+      this.freeHandles.push(handle)
+    }
+  }
+
+  /** Take a buffer of at least `minSize` bytes out of circulation. */
+  private take(minSize: number): Uint8Array {
+    // 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.
+    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)
+        return candidate
+      }
+    }
+
+    const target = this.nextSize(minSize)
+
+    // 2) No free buffer is large enough: grow the largest free buffer in place
+    //    to keep the number of retained buffers bounded.
+    let largestBuf: Uint8Array | null = null
+    let largest = -1
+    for (let i = 0; i < this.free.length; i++) {
+      const candidate = this.free[i] as Uint8Array
+      if (largestBuf === null || candidate.byteLength > largestBuf.byteLength) {
+        largestBuf = candidate
+        largest = i
+      }
+    }
+    if (largestBuf !== null) {
+      this.free.splice(largest, 1)
+      this.created++
+      return new Uint8Array(target)
+    }
+
+    // 3) Pool exhausted (all buffers in flight): allocate a fresh buffer.
+    this.created++
+    return new Uint8Array(target)
+  }
+
+  /** Return a buffer to the free list, bounding total retained memory. */
+  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
+          smallest = i
+        }
+      }
+      this.free.splice(smallest, 1)
+    }
+    this.free.push(buffer)
+  }
+
+  private nextSize(minSize: number): number {
+    const floor = this.estimate
+      ? Math.max(this.initialSize, Math.ceil(this.estimate.estimate))
+      : this.initialSize
+    return Math.max(floor, minSize)
+  }
+}