castrum 0.7.0 → 0.9.0

package/src/shared/buffer-pool.ts

@@ -0,0 +1,209 @@
+// 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.
+
+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
+}
+
+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
+}
+
+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[] = []
+  private readonly initialSize: number
+  private readonly maxBuffers: number
+  private readonly maxInFlight: 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.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++
+    let released = false
+
+    return {
+      buffer,
+      get released(): boolean {
+        return released
+      },
+      release: () => {
+        if (released) {
+          return
+        }
+        released = true
+        this.inFlight--
+        this.releaseBuffer(buffer)
+      },
+    }
+  }
+
+  /** 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)
+  }
+}

package/src/shared/bytes.ts

@@ -3,14 +3,44 @@
  *
  * Reusing a single encoder avoids allocation overhead in hot paths.
  */
-export const encoder = new TextEncoder();
+export const encoder = new TextEncoder()
 
 /**
  * Shared TextDecoder instance for decoding UTF-8 bytes to strings.
  *
  * Reusing a single decoder avoids allocation overhead in hot paths.
  */
-export const decoder = new TextDecoder();
+export const decoder = new TextDecoder()
+
+/**
+ * Cache of `DataView`s keyed by their backing buffer + creation offset.
+ */
+const dataViewCache = new WeakMap<ArrayBufferLike, { offset: number; view: DataView }>()
+
+/**
+ * Returns a `DataView` over `buffer` starting at `byteOffset`, creating and
+ * caching it once per (backing buffer, byteOffset) pair.
+ *
+ * Hot ingress paths decode the native packed output through a `DataView` on
+ * every request. The pooled/fixed output buffers are long-lived `Uint8Array`s
+ * over stable `ArrayBuffer`s at `byteOffset` 0, so a single view per buffer is
+ * reused across requests — eliminating one allocation per request. A
+ * nonzero-offset subarray (e.g. a written-prefix view over a shared backing
+ * buffer) gets its own view so reads stay aligned to the caller's start.
+ *
+ * @param buffer - The backing buffer to create (or reuse) a view for.
+ * @param byteOffset - The start of the view within `buffer`. Default 0.
+ * @returns A cached `DataView` over `buffer` starting at `byteOffset`.
+ */
+export function viewForArrayBuffer(buffer: ArrayBufferLike, byteOffset = 0): DataView {
+  const cached = dataViewCache.get(buffer)
+  if (cached !== undefined && cached.offset === byteOffset) {
+    return cached.view
+  }
+  const view = new DataView(buffer, byteOffset)
+  dataViewCache.set(buffer, { offset: byteOffset, view })
+  return view
+}
 
 /**
  * Creates an independent copy of a Uint8Array.
@@ -30,7 +60,7 @@ export const decoder = new TextDecoder();
  * ```
  */
 export function toPlainBuffer(bytes: Uint8Array): Uint8Array {
-  const copy = new Uint8Array(bytes.byteLength);
-  copy.set(bytes);
-  return copy;
+  const copy = new Uint8Array(bytes.byteLength)
+  copy.set(bytes)
+  return copy
 }

package/src/shared/env.ts

@@ -0,0 +1,20 @@
+// src/shared/env.ts — Centralized environment-variable resolution.
+//
+// Runtime env vars use the `CASTRUM_*` prefix; legacy `RUST_BENCH_*` / `RUST_*`
+// names are still read as aliases (see docs/ENVIRONMENT.md). All alias-chain
+// reads MUST go through `resolveEnvVar` so the chains can never drift apart
+// (they previously lived inline at several call sites with different shapes).
+
+/** First set value among `preferred` and its legacy aliases, or `undefined`. */
+export function resolveEnvVar(
+  preferred: string,
+  legacy: readonly string[] = [],
+): string | undefined {
+  const direct = process.env[preferred]
+  if (direct !== undefined) return direct
+  for (const alias of legacy) {
+    const aliasValue = process.env[alias]
+    if (aliasValue !== undefined) return aliasValue
+  }
+  return undefined
+}

package/src/shared/log.ts

@@ -0,0 +1,74 @@
+// src/shared/log.ts — lightweight structured logging for the ingress layer.
+//
+// No external dependencies. Emits one JSON object per line to a writable
+// stream (default stderr), gated by the `CASTRUM_LOG_LEVEL` env var. This
+// gives operators a zero-dependency way to correlate requests by request-id
+// without wiring OpenTelemetry. For full control, use the `onRequest` /
+// `onResponse` / `onError` runtime hooks instead.
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent'
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+  silent: 99,
+}
+
+function resolveLevel(envValue: string | undefined): LogLevel {
+  const v = envValue?.trim().toLowerCase()
+  if (v === 'debug') return 'debug'
+  if (v === 'warn' || v === 'warning') return 'warn'
+  if (v === 'error') return 'error'
+  if (v === 'silent' || v === 'off' || v === 'none') return 'silent'
+  return 'info'
+}
+
+/**
+ * A minimal structured logger. Emits `{ts, level, ...fields}` JSON lines to
+ * `stream` when `level` is enabled by the ambient `CASTRUM_LOG_LEVEL`.
+ */
+export function createStructuredLogger(
+  stream: Pick<NodeJS.WritableStream, 'write'> = process.stderr,
+  env: NodeJS.ProcessEnv = process.env,
+) {
+  const threshold = LEVEL_ORDER[resolveLevel(env.CASTRUM_LOG_LEVEL)] ?? LEVEL_ORDER.info
+
+  function emit(level: LogLevel, fields: Record<string, unknown>): void {
+    if (LEVEL_ORDER[level] < threshold) return
+    try {
+      const line = JSON.stringify({
+        ts: Date.now(),
+        level,
+        ...fields,
+      })
+      stream.write(`${line}\n`)
+    } catch {
+      // never throw from logging
+    }
+  }
+
+  return {
+    /** Record one completed request. */
+    request(info: {
+      requestId: string
+      method: string
+      path: string
+      status: number
+      durationMs: number
+      ip?: string
+    }): void {
+      emit('info', { event: 'request', ...info })
+    },
+    error(info: {
+      requestId?: string
+      method?: string
+      path?: string
+      code?: string
+      message: string
+    }): void {
+      emit('error', { event: 'error', ...info })
+    },
+  }
+}

package/src/shared/metrics.ts

@@ -0,0 +1,247 @@
+// src/shared/metrics.ts — Zero-dependency metrics registry (counters, gauges,
+// histograms) with Prometheus text-exposition rendering.
+//
+// This is the "enterprise observability" primitive: `createMetrics()` gives
+// operators counters/histograms they can expose at a `/metrics` endpoint
+// (see src/ingress/metrics.ts for the ingress wiring + route factory). No
+// external deps — matches the codebase's zero-runtime-dependency ethos; an
+// OpenTelemetry exporter can wrap the same registry later.
+
+/** Default histogram buckets (Prometheus-style, seconds). */
+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,
+]
+
+type LabelValues = readonly string[]
+type Labels = Readonly<Record<string, string>>
+
+/** Stable key for a label set (sorted for deterministic exposition). */
+function labelKey(names: readonly string[], values: LabelValues): string {
+  if (names.length === 0) return ''
+  const parts: string[] = []
+  for (let i = 0; i < names.length; i++) {
+    parts.push(`${names[i]}="${escapeLabel(values[i] ?? '')}"`)
+  }
+  return parts.join(',')
+}
+
+function escapeLabel(v: string): string {
+  return v.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n')
+}
+
+/** A single labelled counter value. */
+export interface Counter {
+  /** Increment by 1 (or `by`). `labels` must match the label names exactly. */
+  inc(labels?: Labels, by?: number): void
+}
+
+/** A single labelled gauge value (can go up and down). */
+export interface Gauge {
+  inc(labels?: Labels, by?: number): void
+  dec(labels?: Labels, by?: number): void
+  set(labels: Labels | undefined, value: number): void
+}
+
+/** A single labelled histogram. */
+export interface Histogram {
+  /** Record one observation. `labels` must match the label names exactly. */
+  observe(value: number, labels?: Labels): void
+}
+
+/** The metrics registry factory. */
+export interface MetricsRegistry {
+  /** Create (or fetch) a counter. `help` is only used on first creation. */
+  counter(name: string, help: string, labelNames?: readonly string[]): Counter
+  /** Create (or fetch) a gauge. */
+  gauge(name: string, help: string, labelNames?: readonly string[]): Gauge
+  /**
+   * Create (or fetch) a histogram. `buckets`/`help` only apply on first
+   * creation; later calls with the same name return the existing histogram.
+   */
+  histogram(
+    name: string,
+    help: string,
+    buckets?: readonly number[],
+    labelNames?: readonly string[],
+  ): Histogram
+  /** Render the Prometheus text exposition format. */
+  render(): string
+  /** Reset all metrics (for tests / interval rotation). */
+  reset(): void
+}
+
+interface CounterEntry {
+  name: string
+  help: string
+  labelNames: string[]
+  values: Map<string, number>
+}
+interface GaugeEntry {
+  name: string
+  help: string
+  labelNames: string[]
+  values: Map<string, number>
+}
+interface HistogramEntry {
+  name: string
+  help: string
+  labelNames: string[]
+  buckets: number[]
+  /** le bucket index -> cumulative count per label set. */
+  counts: Map<string, number[]>
+  sums: Map<string, number>
+}
+
+/** Create a fresh metrics registry. */
+export function createMetrics(): MetricsRegistry {
+  const counters = new Map<string, CounterEntry>()
+  const gauges = new Map<string, GaugeEntry>()
+  const histograms = new Map<string, HistogramEntry>()
+
+  const bucketUpper = (buckets: number[]): number[] => [
+    ...buckets.map((b) => b),
+    Number.POSITIVE_INFINITY,
+  ]
+
+  const renderCounter = (e: CounterEntry): string[] => {
+    const lines = [`# HELP ${e.name} ${e.help}`, `# TYPE ${e.name} counter`]
+    for (const [key, value] of e.values) {
+      lines.push(key ? `${e.name}{${key}} ${value}` : `${e.name} ${value}`)
+    }
+    return lines
+  }
+
+  const renderGauge = (e: GaugeEntry): string[] => {
+    const lines = [`# HELP ${e.name} ${e.help}`, `# TYPE ${e.name} gauge`]
+    for (const [key, value] of e.values) {
+      lines.push(key ? `${e.name}{${key}} ${value}` : `${e.name} ${value}`)
+    }
+    return lines
+  }
+
+  const renderHistogram = (e: HistogramEntry): string[] => {
+    const lines = [`# HELP ${e.name} ${e.help}`, `# TYPE ${e.name} histogram`]
+    const upper = bucketUpper(e.buckets)
+    for (const [key, counts] of e.counts) {
+      const sum = e.sums.get(key) ?? 0
+      const baseSuffix = key ? `{${key}}` : ''
+      for (let i = 0; i < upper.length; i++) {
+        const le = upper[i]
+        const leLabel = le === Number.POSITIVE_INFINITY ? '+Inf' : String(le)
+        const v = counts[i] ?? 0
+        // `le` merges INTO the label set (Prometheus requires one brace group).
+        const full = key ? `${key},le="${leLabel}"` : `le="${leLabel}"`
+        lines.push(`${e.name}_bucket{${full}} ${v}`)
+      }
+      lines.push(`${e.name}_sum${baseSuffix} ${sum}`)
+      lines.push(`${e.name}_count${baseSuffix} ${counts[counts.length - 1] ?? 0}`)
+    }
+    return lines
+  }
+
+  const render = (): string => {
+    const out: string[] = []
+    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))
+    return `${out.join('\n')}\n`
+  }
+
+  const reset = (): void => {
+    counters.clear()
+    gauges.clear()
+    histograms.clear()
+  }
+
+  return {
+    counter(name, help, labelNames = []) {
+      // Capture a guaranteed non-null entry (first creation wins; later calls
+      // with the same name return the existing counter).
+      const existing = counters.get(name)
+      const entry: CounterEntry = existing ?? {
+        name,
+        help,
+        labelNames: [...labelNames],
+        values: new Map(),
+      }
+      if (!existing) counters.set(name, entry)
+      const names = entry.labelNames
+      return {
+        inc(labels, by = 1) {
+          const key = labelKey(
+            names,
+            names.map((n) => labels?.[n] ?? ''),
+          )
+          entry.values.set(key, (entry.values.get(key) ?? 0) + by)
+        },
+      }
+    },
+
+    gauge(name, help, labelNames = []) {
+      const existing = gauges.get(name)
+      const entry: GaugeEntry = existing ?? {
+        name,
+        help,
+        labelNames: [...labelNames],
+        values: new Map(),
+      }
+      if (!existing) gauges.set(name, entry)
+      const names = entry.labelNames
+      const keyOf = (labels?: Labels): string =>
+        labelKey(
+          names,
+          names.map((n) => labels?.[n] ?? ''),
+        )
+      return {
+        inc(labels, by = 1) {
+          entry.values.set(keyOf(labels), (entry.values.get(keyOf(labels)) ?? 0) + by)
+        },
+        dec(labels, by = 1) {
+          entry.values.set(keyOf(labels), (entry.values.get(keyOf(labels)) ?? 0) - by)
+        },
+        set(labels, value) {
+          entry.values.set(keyOf(labels), value)
+        },
+      }
+    },
+
+    histogram(name, help, buckets = DEFAULT_BUCKETS, labelNames = []) {
+      const existing = histograms.get(name)
+      const entry: HistogramEntry = existing ?? {
+        name,
+        help,
+        labelNames: [...labelNames],
+        buckets: [...buckets].sort((a, b) => a - b),
+        counts: new Map(),
+        sums: new Map(),
+      }
+      if (!existing) histograms.set(name, entry)
+      const names = entry.labelNames
+      return {
+        observe(value, labels) {
+          const key = labelKey(
+            names,
+            names.map((n) => labels?.[n] ?? ''),
+          )
+          let counts = entry.counts.get(key)
+          if (!counts) {
+            // One slot per bucket PLUS the implicit +Inf slot.
+            counts = new Array<number>(entry.buckets.length + 1).fill(0)
+            entry.counts.set(key, counts)
+          }
+          // Cumulative count per upper bound, including the implicit +Inf
+          // bucket (every value falls in it).
+          for (let i = 0; i < counts.length; i++) {
+            const bound =
+              i < entry.buckets.length ? (entry.buckets[i] as number) : Number.POSITIVE_INFINITY
+            if (value <= bound) counts[i] = (counts[i] ?? 0) + 1
+          }
+          entry.sums.set(key, (entry.sums.get(key) ?? 0) + value)
+        },
+      }
+    },
+
+    render,
+    reset,
+  }
+}