castrum 0.9.8 → 0.9.10

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