castrum 0.9.8 → 0.9.9

package/src/native/types.ts

@@ -344,6 +344,12 @@ export interface NativeAddon {
 
   initThreadPool(rayonThreads?: number): void
   rayonNumThreads(): number
+  /**
+   * Drop the process-wide compiled request-body schema cache (identical schema
+   * bytes are compiled once and shared across ingress instances/routes).
+   * Maintenance hook for the public `flushMemory()`; idempotent.
+   */
+  clearSchemaCache(): void
 
   jsonValidBatchPacked(input: Uint8Array): Uint8Array
   validateEmailBatchPacked(input: Uint8Array): Uint8Array

package/src/runtime/detect.ts

@@ -27,6 +27,20 @@ export function isNodeRuntime(): boolean {
   return detectedRuntime === 'node'
 }
 
+/**
+ * Request a synchronous full garbage collection when the host runtime exposes
+ * one. On Bun this is `Bun.gc(true)`; on Node it is `globalThis.gc?.()`, which
+ * is only defined when the process runs with `--expose-gc`. A no-op otherwise.
+ */
+export function forceGc(): void {
+  if (detectedRuntime === 'bun') {
+    Bun.gc(true)
+    return
+  }
+  // Node only defines `globalThis.gc` under `--expose-gc`.
+  ;(globalThis as { gc?: () => void }).gc?.()
+}
+
 /** The Node.js major version when running under Node, otherwise `null`. */
 export function nodeMajorVersion(): number | null {
   if (detectedRuntime !== 'node') return null

package/src/rust-ffi/context.ts

@@ -21,6 +21,51 @@ import { normalizeExt, resolveRayonThreads } from './options'
 // batch.ts uses for its packed entries.
 const nativeFnCache = new Map<string, unknown>()
 
+/** Max entries retained per process-wide MIME cache (insertion-order eviction). */
+const MIME_CACHE_MAX = 1024
+
+/**
+ * Process-wide extension-bytes → MIME-bytes cache shared by every client
+ * context: the native addon is a process singleton, so `extension → MIME` is a
+ * global pure lookup. Bounded by `MIME_CACHE_MAX`; on overflow the oldest half
+ * is evicted via {@link evictOldestHalf}. Exported for the memory-flush path
+ * and tests — callers must NOT mutate the returned slices.
+ */
+export const mimeByText = new Map<string, Uint8Array>()
+
+/**
+ * Process-wide extension-string → MIME-string memo (the `text.mimeFromExtension`
+ * fast path). Bounded exactly like {@link mimeByText}.
+ */
+export const mimeStrCache = new Map<string, string>()
+
+/**
+ * Evict the oldest half of a cache map (insertion order) and return the keys
+ * dropped. Generational eviction — halving at the cap amortizes the cost rather
+ * than paying a delete per insertion. Returns an empty array below the cap.
+ */
+export function evictOldestHalf<K, V>(map: Map<K, V>): K[] {
+  if (map.size < MIME_CACHE_MAX) return []
+  const drop = Math.ceil(map.size / 2)
+  const dropped: K[] = []
+  for (const key of map.keys()) {
+    if (dropped.length >= drop) break
+    dropped.push(key)
+  }
+  for (const key of dropped) map.delete(key)
+  return dropped
+}
+
+/**
+ * Clear the process-wide MIME caches (both the bytes and string forms). This is
+ * the impure-boundary hook consumed by the public `flushMemory()`; safe to call
+ * at any time, including before the addon has ever been loaded.
+ */
+export function clearMimeCaches(): void {
+  mimeByText.clear()
+  mimeStrCache.clear()
+}
+
 /**
  * Resolve a native op on first use and cache it for all subsequent calls —
  * FFI-FIRST via the runtime adapter's transport (`bun:ffi` on Bun, napi
@@ -91,7 +136,6 @@ export interface RustClientContext {
   runtime: NativeRuntimeAdapter
   /** Per-instance toggles (mime/hmac caching). */
   state: { mimeCache: boolean; hmacCache: boolean }
-  mimeByText: Map<string, Uint8Array>
   hmacSigners: WeakMap<Uint8Array, HmacSignerInstance>
 
   /** Initialize the process-wide rayon pool exactly once (no-op after). */
@@ -110,7 +154,6 @@ export interface RustClientContext {
 
 /** Build a per-instance context from client options. */
 export function createContext(options: RustOptions): RustClientContext {
-  const mimeByText = new Map<string, Uint8Array>()
   const hmacSigners = new WeakMap<Uint8Array, HmacSignerInstance>()
   const state = {
     mimeCache: options.mimeCache !== false,
@@ -152,6 +195,7 @@ export function createContext(options: RustOptions): RustClientContext {
 
     let val = mimeByText.get(key)
     if (!val) {
+      evictOldestHalf(mimeByText)
       val = addon.mimeFromExtension(ext)
       mimeByText.set(key, val)
     }
@@ -181,7 +225,6 @@ export function createContext(options: RustOptions): RustClientContext {
     addon,
     runtime: runtimeNative,
     state,
-    mimeByText,
     hmacSigners,
     ensurePool,
     isPoolInitialized,

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

@@ -559,5 +559,11 @@ export function buildFactories(ctx: RustClientContext) {
     rayonNumThreads(): number {
       return asNumber(addon.rayonNumThreads() as unknown)
     },
+    clearSchemaCache(): void {
+      // Defensive: a stale addon built before this symbol, or a failed bind,
+      // must make this a no-op rather than a throw (flushMemory calls it).
+      const native = addon as unknown as { clearSchemaCache?: () => void }
+      native.clearSchemaCache?.()
+    },
   }
 }

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

@@ -237,6 +237,20 @@ export interface RustScalar {
   createMetricsRegistry(): MetricsRegistryInstance
   initThreadPool(rayonThreads?: number): void
   rayonNumThreads(): number
+  /**
+   * Drop the process-wide compiled request-body schema cache. Identical schema
+   * bytes are compiled once and shared across `Ingress` / `NativeRoute`
+   * instances; this releases those compiled validators (already-constructed
+   * instances keep their own shared reference and are unaffected). Idempotent,
+   * and a safe no-op when the native addon is absent or predates the symbol
+   * (the public `flushMemory()` relies on that).
+   *
+   * Maintenance-only escape hatch — NOT a benchmarked op, so it is intentionally
+   * exempt from `PROVEN_SELECTION` / `selection.json` (there is no native-vs-JS
+   * winner to classify). `test/unit/contract/proven.test.ts` only requires
+   * registry coverage for selection.json ops + Bun built-ins.
+   */
+  clearSchemaCache(): void
 
   // ── Backend-framework scalar features ──
   jwtSign(

package/src/rust-ffi/text.ts

@@ -14,7 +14,7 @@
 // napi fallback) — no inline `isBun()` / `getBunFFI()`.
 
 import { decoder, encoder, hasNul } from '../shared/bytes'
-import { type RustClientContext, resolveNative } from './context'
+import { evictOldestHalf, mimeStrCache, type RustClientContext, resolveNative } from './context'
 
 /**
  * Scratch for the byte-path `Sec-WebSocket-Accept` fallback (28 chars; the
@@ -67,9 +67,9 @@ export function buildText(ctx: RustClientContext): RustText {
   const { builtins, transport } = ctx.runtime
   // String memo: the byte path already caches the native bytes; this avoids the
   // encode → native lookup → slice → decode round-trip for repeated extension
-  // strings (the common case) — 0 allocations on a cache hit.
-  const mimeStrCache = new Map<string, string>()
-
+  // strings (the common case) — 0 allocations on a cache hit. The map is
+  // process-wide and bounded by `evictOldestHalf` (MIME_CACHE_MAX) — see
+  // ./context.ts.
   return {
     mimeFromExtension(ext) {
       let mime = mimeStrCache.get(ext)
@@ -81,6 +81,7 @@ export function buildText(ctx: RustClientContext): RustText {
         mime = f
           ? (f.mimeFromExtension(ext) ?? 'application/octet-stream')
           : decoder.decode(ctx.cachedMime(encoder.encode(ext)))
+        evictOldestHalf(mimeStrCache)
         mimeStrCache.set(ext, mime)
       }
       return mime

package/src/shared/buffer-pool.ts

@@ -181,6 +181,16 @@ export class BufferPool {
     return this.created
   }
 
+  /**
+   * Drop every retained free buffer. In-flight (borrowed) buffers are
+   * unaffected and return to an empty pool on `release()`, so the next
+   * `acquire()` allocates (or grows) as needed. Used by an explicit memory
+   * flush; the pool stays fully functional afterwards.
+   */
+  shrink(): void {
+    this.free.length = 0
+  }
+
   /**
    * 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.

package/src/shared/memory.ts

@@ -0,0 +1,68 @@
+// src/shared/memory.ts — Public memory-flush escape hatch.
+//
+// Impure boundary module: it owns no state of its own but reaches the cache
+// owners (the global loader LRU and the process-wide MIME caches) to drop their
+// retained entries, then optionally requests a runtime GC. The metrics registry
+// is deliberately NOT flushed — an observability registry is not a cache, and
+// clearing it would erase the counters an operator is watching.
+
+import { loader } from '../loader'
+import { rust } from '../rust-ffi'
+import { clearMimeCaches } from '../rust-ffi/context'
+import { forceGc } from './runtime'
+
+/** Options for {@link flushMemory}. */
+export interface FlushMemoryOptions {
+  /**
+   * When true (the default), also request a full garbage collection from the
+   * runtime: `Bun.gc(true)` on Bun, `globalThis.gc?.()` on Node when the
+   * process runs with `--expose-gc`. Set false to flush caches only.
+   */
+  gc?: boolean
+}
+
+/**
+ * Flush process-level caches and (by default) request a full GC. Intended for
+ * explicit memory-pressure handling — e.g. after a burst or before a snapshot.
+ *
+ * Clears:
+ * - the global loader LRU cache (`loader.clear()`),
+ * - the process-wide MIME caches (`clearMimeCaches()`),
+ * - the native compiled-schema cache (`rust.clearSchemaCache()`).
+ *
+ * The metrics registry is intentionally left untouched.
+ *
+ * Idempotent, and safe to call before the native addon has ever been loaded
+ * (every cache starts empty, the loader cache is a plain Map, and the native
+ * schema-cache clear is a defensive no-op when the addon/symbol is absent).
+ *
+ * @param options - `gc: false` skips the runtime GC request. Defaults to `{}`
+ *   (GC requested).
+ * @example
+ * ```ts
+ * import { flushMemory } from 'castrum'
+ *
+ * flushMemory()            // drop caches + request GC
+ * flushMemory({ gc: false }) // drop caches only
+ * ```
+ */
+export function flushMemory(options: FlushMemoryOptions = {}): void {
+  // Global loader LRU (createLoader() instances own their own caches and are
+  // not registered globally — flush the shared singleton only).
+  loader.clear()
+
+  // Process-wide MIME caches (bytes + string forms).
+  clearMimeCaches()
+
+  // Process-wide native compiled-schema cache. Defensive: an absent or stale
+  // addon (no `clearSchemaCache` symbol) must be a no-op, never a throw.
+  try {
+    rust.clearSchemaCache()
+  } catch {
+    // addon not loaded / stale build — nothing to clear.
+  }
+
+  if (options.gc !== false) {
+    forceGc()
+  }
+}

package/src/shared/metrics.ts

@@ -12,6 +12,27 @@ export const DEFAULT_BUCKETS: readonly number[] = [
   0.001, 0.0025, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10,
 ]
 
+/**
+ * Per-family cap on the number of distinct label sets (series) retained by a
+ * single counter/gauge/histogram. A metrics registry is keyed by caller-supplied
+ * label values, so an unbounded label (e.g. a raw path or user id) would grow a
+ * `Map` without limit. At the cap the oldest half of that family is evicted
+ * (insertion order) and the count is accumulated into the synthetic counter
+ * `castrum_metrics_series_dropped_total`, making the loss observable instead of
+ * silent. That name is RESERVED — a caller declaring a counter/gauge/histogram
+ * with it suppresses the synthetic emission (see {@link SERIES_DROPPED_METRIC}).
+ */
+export const MAX_SERIES_PER_METRIC = 10_000
+
+/**
+ * Reserved exposition name of the synthetic counter reporting series evicted by
+ * {@link MAX_SERIES_PER_METRIC}. Callers must not register a metric family with
+ * this name; if one exists, `render()` skips the synthetic emission so the
+ * scrape never carries two `# HELP`/`# TYPE` lines for one family (Prometheus
+ * rejects that).
+ */
+const SERIES_DROPPED_METRIC = 'castrum_metrics_series_dropped_total'
+
 type LabelValues = readonly string[]
 type Labels = Readonly<Record<string, string>>
 
@@ -29,6 +50,24 @@ function escapeLabel(v: string): string {
   return v.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n')
 }
 
+/**
+ * Once a series map is at {@link MAX_SERIES_PER_METRIC}, evict its oldest half
+ * (insertion order) and return the keys dropped; returns `[]` below the cap.
+ * Mirrors Elysia's `evictOldestHalf` generational policy: halving at the cap
+ * amortizes the eviction cost instead of paying a delete per insertion.
+ */
+function evictOldestHalf<K, V>(map: Map<K, V>): K[] {
+  if (map.size < MAX_SERIES_PER_METRIC) return []
+  const drop = Math.ceil(map.size / 2)
+  const dropped: K[] = []
+  for (const key of map.keys()) {
+    if (dropped.length >= drop) break
+    dropped.push(key)
+  }
+  for (const key of dropped) map.delete(key)
+  return dropped
+}
+
 /** A single labelled counter value. */
 export interface Counter {
   /** Increment by 1 (or `by`). `labels` must match the label names exactly. */
@@ -97,6 +136,8 @@ export function createMetrics(): MetricsRegistry {
   const counters = new Map<string, CounterEntry>()
   const gauges = new Map<string, GaugeEntry>()
   const histograms = new Map<string, HistogramEntry>()
+  /** Series evicted by the per-family cardinality cap, rendered as a counter. */
+  let seriesDropped = 0
 
   const bucketUpper = (buckets: number[]): number[] => [
     ...buckets.map((b) => b),
@@ -144,6 +185,22 @@ export function createMetrics(): MetricsRegistry {
     for (const e of counters.values()) out.push(...renderCounter(e))
     for (const e of gauges.values()) out.push(...renderGauge(e))
     for (const e of histograms.values()) out.push(...renderHistogram(e))
+    // Only emitted once a family has actually overflowed, so the output for a
+    // well-behaved registry is byte-identical to before the cap existed. Guard
+    // against a caller-registered family of the same (reserved) name — two
+    // `# HELP`/`# TYPE` lines for one family make the scrape invalid.
+    if (
+      seriesDropped > 0 &&
+      !counters.has(SERIES_DROPPED_METRIC) &&
+      !gauges.has(SERIES_DROPPED_METRIC) &&
+      !histograms.has(SERIES_DROPPED_METRIC)
+    ) {
+      out.push(
+        `# HELP ${SERIES_DROPPED_METRIC} Total metric series evicted by the per-family cardinality cap.`,
+      )
+      out.push(`# TYPE ${SERIES_DROPPED_METRIC} counter`)
+      out.push(`${SERIES_DROPPED_METRIC} ${seriesDropped}`)
+    }
     return `${out.join('\n')}\n`
   }
 
@@ -151,6 +208,7 @@ export function createMetrics(): MetricsRegistry {
     counters.clear()
     gauges.clear()
     histograms.clear()
+    seriesDropped = 0
   }
 
   return {
@@ -172,7 +230,14 @@ export function createMetrics(): MetricsRegistry {
             names,
             names.map((n) => labels?.[n] ?? ''),
           )
-          entry.values.set(key, (entry.values.get(key) ?? 0) + by)
+          const prev = entry.values.get(key)
+          if (prev === undefined) {
+            // New series: make room first (bounded family) and count evictions.
+            seriesDropped += evictOldestHalf(entry.values).length
+            entry.values.set(key, by)
+          } else {
+            entry.values.set(key, prev + by)
+          }
         },
       }
     },
@@ -192,14 +257,27 @@ export function createMetrics(): MetricsRegistry {
           names,
           names.map((n) => labels?.[n] ?? ''),
         )
+      const add = (labels: Labels | undefined, delta: number): void => {
+        const key = keyOf(labels)
+        const prev = entry.values.get(key)
+        if (prev === undefined) {
+          seriesDropped += evictOldestHalf(entry.values).length
+          entry.values.set(key, delta)
+        } else {
+          entry.values.set(key, prev + delta)
+        }
+      }
       return {
         inc(labels, by = 1) {
-          entry.values.set(keyOf(labels), (entry.values.get(keyOf(labels)) ?? 0) + by)
+          add(labels, by)
         },
         dec(labels, by = 1) {
-          entry.values.set(keyOf(labels), (entry.values.get(keyOf(labels)) ?? 0) - by)
+          add(labels, -by)
         },
         set(labels, value) {
+          if (!entry.values.has(keyOf(labels))) {
+            seriesDropped += evictOldestHalf(entry.values).length
+          }
           entry.values.set(keyOf(labels), value)
         },
       }
@@ -225,6 +303,11 @@ export function createMetrics(): MetricsRegistry {
           )
           let counts = entry.counts.get(key)
           if (!counts) {
+            // New series: bound the family and drop the matching sum entries
+            // (counts and sums always share the same key set).
+            const dropped = evictOldestHalf(entry.counts)
+            for (const k of dropped) entry.sums.delete(k)
+            seriesDropped += dropped.length
             // One slot per bucket PLUS the implicit +Inf slot.
             counts = new Array<number>(entry.buckets.length + 1).fill(0)
             entry.counts.set(key, counts)

package/src/shared/runtime.ts

@@ -7,6 +7,7 @@
 
 import {
   detectedRuntime,
+  forceGc as forceGcDetected,
   isBunRuntime,
   isNodeRuntime,
   nodeMajorVersion as nodeMajorVersionDetected,
@@ -27,3 +28,9 @@ export const runtimeName: () => RuntimeName = () => detectedRuntime
 
 /** The Node.js major version when running under Node, otherwise `null`. */
 export const nodeMajorVersion: () => number | null = nodeMajorVersionDetected
+
+/**
+ * Request a synchronous full GC when the runtime exposes one (`Bun.gc(true)` on
+ * Bun, `globalThis.gc?.()` under Node `--expose-gc`). A no-op otherwise.
+ */
+export const forceGc: () => void = forceGcDetected

package/src/task/runtime.ts

@@ -152,6 +152,37 @@ function cancelledError(): Error {
   return err
 }
 
+/** Native `taskSubmit*` return: the task was accepted onto the pool. */
+const TASK_SUBMIT_ACCEPTED = 1
+/** Native `taskSubmit*` return: the bounded work queue is full (overload). */
+const TASK_SUBMIT_OVERLOADED = 2
+
+/** Error raised when the bounded native task queue is at its admission bound. */
+interface TaskOverloadedError extends Error {
+  /** Stable discriminant so callers can branch on overload. */
+  code: 'OVERLOADED'
+}
+
+/**
+ * Map a native `taskSubmit*` return code to the reason a task promise should
+ * reject with, or `null` when the submission was accepted. Pure and exported
+ * for tests, so the rejection mapping can be checked without driving the native
+ * pool into a real overload.
+ *
+ * @param code Native submit return: `1` accepted, `2` overloaded, else rejected.
+ * @returns The typed overload error, the generic rejection, or `null`.
+ */
+export function taskSubmitError(code: number): Error | null {
+  if (code === TASK_SUBMIT_ACCEPTED) return null
+  if (code === TASK_SUBMIT_OVERLOADED) {
+    const err = new Error('task rejected: native work queue is full') as TaskOverloadedError
+    err.name = 'TaskOverloadedError'
+    err.code = 'OVERLOADED'
+    return err
+  }
+  return new Error('task rejected by the native runtime')
+}
+
 /** Bunny-shaped doorbell handle (structural, so it needs no bun-types dep). */
 interface Doorbell {
   ptr: number | null
@@ -361,10 +392,14 @@ export function createTaskRuntime(options: TaskRuntimeOptions = {}): TaskRuntime
     return new Promise<Uint8Array>((resolve, reject) => {
       inflight.set(id, { out: null, keep: null, resolve, reject })
       retain()
-      if (ffi.taskSubmit(op, args, id) === 0) {
+      const rejected = taskSubmitError(ffi.taskSubmit(op, args, id))
+      if (rejected) {
         inflight.delete(id)
-        release()
-        reject(new Error('task rejected by the native runtime'))
+        // Release the keep-alive only when this was the last in-flight task.
+        // An overload/invalid rejection must not tear down the interval (and
+        // its polling safety net) while other tasks are still pending.
+        if (inflight.size === 0) release()
+        reject(rejected)
         return
       }
       const signal = runOptions?.signal
@@ -394,10 +429,14 @@ export function createTaskRuntime(options: TaskRuntimeOptions = {}): TaskRuntime
     return new Promise<Uint8Array>((resolve, reject) => {
       inflight.set(id, { out: output, keep: null, resolve, reject })
       retain()
-      if (ffi.taskSubmitOut(op, args, id, output) === 0) {
+      const rejected = taskSubmitError(ffi.taskSubmitOut(op, args, id, output))
+      if (rejected) {
         inflight.delete(id)
-        release()
-        reject(new Error('task rejected by the native runtime'))
+        // Release the keep-alive only when this was the last in-flight task.
+        // An overload/invalid rejection must not tear down the interval (and
+        // its polling safety net) while other tasks are still pending.
+        if (inflight.size === 0) release()
+        reject(rejected)
         return
       }
       const signal = runOptions?.signal
@@ -428,10 +467,14 @@ export function createTaskRuntime(options: TaskRuntimeOptions = {}): TaskRuntime
     return new Promise<Uint8Array>((resolve, reject) => {
       inflight.set(id, { out: null, keep: data, resolve, reject })
       retain()
-      if (ffi.taskSubmitSlice(op, hdr, data, id) === 0) {
+      const rejected = taskSubmitError(ffi.taskSubmitSlice(op, hdr, data, id))
+      if (rejected) {
         inflight.delete(id)
-        release()
-        reject(new Error('task rejected by the native runtime'))
+        // Release the keep-alive only when this was the last in-flight task.
+        // An overload/invalid rejection must not tear down the interval (and
+        // its polling safety net) while other tasks are still pending.
+        if (inflight.size === 0) release()
+        reject(rejected)
         return
       }
       const signal = runOptions?.signal