castrum 0.7.0 → 0.9.1

package/src/shared/bytes.ts

@@ -1,16 +1,115 @@
+// src/shared/bytes.ts — shared UTF-8 / byte helpers (encoder, decoder, toBytes, toText).
+
+import { decodeUtf8, encodeUtf8, encodeUtf8Into } from './codec'
+
+/**
+ * Shared UTF-8 encoder (encode / encodeInto), backed by the runtime-native
+ * codec (`src/shared/codec.ts`): on Bun the work is done by Bun's native
+ * transfer machinery (`Bun.ArrayBufferSink` / a zero-copy `Buffer` view
+ * write); under Node it falls back to `TextEncoder`. Reusing a single object
+ * avoids allocation overhead in hot paths.
+ *
+ * `encode` accepts the string-or-bytes union the text-returning `rust.*` ops
+ * surface (Bun returns strings, Node returns bytes) and normalizes to bytes —
+ * a string is UTF-8 encoded, bytes pass through unchanged.
+ */
+export const encoder: {
+  encode(s: Uint8Array | string): Uint8Array
+  encodeInto(s: string, dest: Uint8Array): { read: number; written: number }
+} = {
+  encode(s) {
+    return typeof s === 'string' ? encodeUtf8(s) : s
+  },
+  encodeInto(s, dest) {
+    const written = encodeUtf8Into(s, dest)
+    // `read` mirrors `TextEncoder.encodeInto`'s shape; callers here only use
+    // `written` (a truncated write consumes the whole source in our call
+    // sites), so this is a documented approximation.
+    return { read: s.length, written }
+  },
+}
+
 /**
- * Shared TextEncoder instance for encoding strings to UTF-8 bytes.
+ * Shared UTF-8 decoder, backed by the runtime-native codec
+ * (`src/shared/codec.ts`): on Bun it uses `new CString(ptr, 0, len)` from
+ * `bun:ffi` (JSC-native, exact-length clone); under Node it falls back to
+ * `TextDecoder`. Reusing a single object avoids allocation overhead in hot
+ * paths.
  *
- * Reusing a single encoder avoids allocation overhead in hot paths.
+ * `decode` accepts the string-or-bytes union the text-returning `rust.*` ops
+ * surface and normalizes to a string — bytes are UTF-8 decoded, strings pass
+ * through unchanged.
  */
-export const encoder = new TextEncoder();
+export const decoder: {
+  decode(bytes: Uint8Array | string): string
+} = {
+  decode(bytes) {
+    return typeof bytes === 'string' ? bytes : decodeUtf8(bytes)
+  },
+}
 
 /**
- * Shared TextDecoder instance for decoding UTF-8 bytes to strings.
+ * Normalize the string-or-bytes union (the text-returning `rust.*` ops return
+ * STRINGS on the Bun path — native transfer — and bytes on the napi path) to
+ * bytes. Codec-backed — no `TextEncoder` runs on the Bun path.
  *
- * Reusing a single decoder avoids allocation overhead in hot paths.
+ * @param v - A string or UTF-8 byte buffer.
+ * @returns The UTF-8 bytes of `v` (identity when `v` is already bytes).
+ *
+ * @example
+ * ```ts
+ * toBytes('aGVsbG8=') // Uint8Array(8)
+ * ```
  */
-export const decoder = new TextDecoder();
+export function toBytes(v: Uint8Array | string): Uint8Array {
+  return typeof v === 'string' ? encodeUtf8(v) : v
+}
+
+/**
+ * Normalize the string-or-bytes union to a string. Codec-backed — no
+ * `TextDecoder` runs on the Bun path.
+ *
+ * @param v - A string or UTF-8 byte buffer.
+ * @returns The decoded string (identity when `v` is already a string).
+ *
+ * @example
+ * ```ts
+ * toText(new Uint8Array([104, 105])) // 'hi'
+ * ```
+ */
+export function toText(v: Uint8Array | string): string {
+  return typeof v === 'string' ? v : decodeUtf8(v)
+}
+
+/**
+ * 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 +129,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/codec.ts

@@ -0,0 +1,78 @@
+// src/shared/codec.ts — runtime-native UTF-8 codec (facade).
+//
+// The runtime-native UTF-8 codec (Bun transfer machinery vs
+// `TextEncoder`/`TextDecoder`) is implemented in `src/runtime/codec.ts` and
+// selected ONCE at module load by the runtime adapter. This module re-exports
+// it so existing callers are unchanged. The Bun/Node branches live in
+// `src/runtime/codec.ts` — do NOT add `TextEncoder`/`TextDecoder` or `bun:ffi`
+// calls here.
+
+import { runtimeCodec } from '../runtime/codec'
+
+/**
+ * Encode a string to UTF-8 bytes.
+ *
+ * On Bun this uses `Bun.ArrayBufferSink` (native UTF-8 writing — no
+ * `TextEncoder`). Under Node it falls back to the standard `TextEncoder`.
+ * The implementation is selected once at load via the runtime adapter.
+ *
+ * @param s - The string to encode to UTF-8 bytes.
+ * @returns A fresh `Uint8Array` of the UTF-8 encoding of `s`.
+ *
+ * @example
+ * ```ts
+ * encodeUtf8('hello') // Uint8Array [104, 101, 108, 108, 111]
+ * ```
+ */
+export const encodeUtf8: (s: string) => Uint8Array = runtimeCodec.encodeUtf8
+
+/**
+ * Encode a string into `dest` starting at `offset`, returning bytes written.
+ *
+ * On Bun this writes through a zero-copy `Buffer` view over `dest`'s backing
+ * store (native `.write` — never splits a multibyte character); under Node it
+ * uses `TextEncoder.prototype.encodeInto`.
+ *
+ * @param s - The string to encode.
+ * @param dest - The destination buffer.
+ * @param offset - Byte offset into `dest` at which to start writing. Default 0.
+ * @returns The number of UTF-8 bytes written.
+ *
+ * @example
+ * ```ts
+ * const out = new Uint8Array(8)
+ * encodeUtf8Into('hi', out) // 2; out[0..1] = 104, 105
+ * ```
+ */
+export const encodeUtf8Into: (s: string, dest: Uint8Array, offset?: number) => number =
+  runtimeCodec.encodeUtf8Into
+
+/**
+ * Decode UTF-8 bytes to a string.
+ *
+ * On Bun this uses `new CString(ptr(bytes), 0, len)` from `bun:ffi` (JSC-native
+ * exact-length clone); under Node it falls back to the standard `TextDecoder`.
+ *
+ * @param bytes - The UTF-8 bytes to decode.
+ * @returns The decoded string (invalid sequences decode to U+FFFD replacement
+ *   characters, matching `TextDecoder` replacement mode).
+ *
+ * @example
+ * ```ts
+ * decodeUtf8(new Uint8Array([104, 105])) // 'hi'
+ * ```
+ */
+export const decodeUtf8: (bytes: Uint8Array) => string = runtimeCodec.decodeUtf8
+
+/**
+ * Decode UTF-8 bytes to a string, throwing on invalid UTF-8.
+ *
+ * Under Node this uses a fatal `TextDecoder`. On Bun (whose `CString` is
+ * replacement-mode) strictness is normally enforced by the native
+ * `castrum_utf8_valid` C-ABI probe (callers check it first via the transport's
+ * ffi surface); this fallback uses the replacement-mode decode.
+ *
+ * @param bytes - The UTF-8 bytes to decode.
+ * @returns The decoded string (throws on invalid UTF-8 under Node).
+ */
+export const decodeUtf8Fatal: (bytes: Uint8Array) => string = runtimeCodec.decodeUtf8Fatal

package/src/shared/env.ts

@@ -0,0 +1,20 @@
+// src/shared/env.ts — Centralized environment-variable resolution.
+//
+// Runtime env vars use the `CASTRUM_*` prefix (plus the napi-rs standard
+// `NAPI_RS_NATIVE_LIBRARY_PATH`). All reads MUST go through `resolveEnvVar` so
+// they 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,75 @@
+// 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.
+
+/** Structured-logging severity levels (least to most severe). */
+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,
+  }
+}

package/src/shared/packed/index.ts

@@ -0,0 +1,10 @@
+// src/shared/packed/index.ts — Packed wire-format helpers (barrel).
+//
+// Re-exports the pure wire encode/decode helpers (./wire.ts), the native
+// JSON-Schema validator + batch helpers (./schema.ts), and the ergonomic
+// string parsers (./parsers.ts). Importing this barrel does NOT dlopen the
+// addon — only calling a parser in ./parsers.ts does (lazy).
+
+export * from './parsers'
+export * from './schema'
+export * from './wire'

package/src/shared/packed/parsers.ts

@@ -0,0 +1,31 @@
+// src/shared/packed/parsers.ts — High-level string parsers (convenience).
+//
+// Wrap the native packed parsers + decoders for ergonomic use, so consumers
+// 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" }
+
+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.
+const addon = lazyAddon(getAddon)
+
+/** 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))
+}
+
+/** 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))
+}
+
+/** 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))
+}

package/src/shared/packed/schema.ts

@@ -0,0 +1,23 @@
+// src/shared/packed/schema.ts — Native JSON-Schema validator + batch helpers.
+//
+// Thin wrapper over the native `SchemaValidator` instance: single-item handle
+// alias plus packed-batch validate helpers (bitset / count). The batch entry
+// points reuse the pure pack-scratch pool from ./wire.ts.
+
+import type { SchemaValidatorInstance } from '../../native'
+import { unpackBitset, withPackScratch } from './wire'
+
+/** Native JSON-Schema validator handle (see `createSchemaValidator`). */
+export type SchemaValidator = SchemaValidatorInstance
+
+/** Validate each item against `validator`; returns a packed validity bitset. */
+export function schemaValidateBatch(validator: SchemaValidator, items: Uint8Array[]): Uint8Array {
+  return withPackScratch(items, (packed) =>
+    unpackBitset(validator.validateBatchPackedBitset(packed)),
+  )
+}
+
+/** Validate each item against `validator`; returns the count of valid items. */
+export function schemaValidateBatchCount(validator: SchemaValidator, items: Uint8Array[]): number {
+  return withPackScratch(items, (packed) => validator.validateBatchPackedCount(packed))
+}