castrum 0.9.0 → 0.9.2

package/src/ingress/types.ts

@@ -4,8 +4,8 @@
 // helpers in ./context.ts, so the implementation modules never need to import
 // the public barrel.
 
-import type { IngressFastOptions } from './options'
 import type { BakedIngressResult } from './decode/baked-result'
+import type { IngressFastOptions } from './options'
 
 /** Public ingress options (extends the fast-path options). */
 export interface IngressOptions extends IngressFastOptions {
@@ -147,6 +147,15 @@ export interface OptimizedIngressHandler {
 
   withContentType(headers: ReadonlyArray<[string, string]>, contentType: string): [string, string][]
 
+  /**
+   * Zero-DOM JSON-validity check bound to this handler's native transport
+   * (bun:ffi primary, napi fallback). Provided so the pure route factories
+   * (`routes/*`) can validate request bodies via dependency injection without
+   * importing the native layer. Always present on handlers from
+   * `createIngressHandler`; optional so hand-rolled mocks need not provide it.
+   */
+  jsonValid?: (bytes: Uint8Array) => boolean
+
   /**
    * Build a zero-copy `Response` whose body is the request's pooled output
    * slice. The pooled buffer is returned to its pool once the body has been
@@ -155,3 +164,37 @@ export interface OptimizedIngressHandler {
    */
   zeroCopyResponse(result: BakedIngressResult, ctx: BakedContext, init: ResponseInit): Response
 }
+
+// ── Responder bridge (native decides, JS formats the 2xx) ─────────
+
+/** Terminal (rejection) response envelope style for responder routes.
+ *  `"castrum"` (default) emits the pre-baked `ok:false`/`ratelimit-*` wire;
+ *  `"ignex"` emits the ignex framework envelope (`{error,status,code}` +
+ *  `x-frame-options`/`nosniff`/`referrer-policy` security headers). Additive —
+ *  castrum's own wire formats are untouched. */
+export type TerminalStyle = 'castrum' | 'ignex'
+
+/**
+ * Decoded request context handed to a {@link NativeResponder} after the native
+ * pipeline succeeded (non-terminal). The native pipeline owns parse/validate/
+ * CORS/rate-limit + terminal rejections; the responder builds the 2xx body
+ * (async OK). Fields are captured INSIDE the sync `run()` callback, so the
+ * pooled output buffer is never aliased after it is released.
+ */
+export interface NativeRequestContext {
+  readonly requestId: string
+  readonly status: number
+  readonly rateLimited: boolean
+  readonly retryAfterMs: number
+  /** Parsed query object (last-wins per key) — `{}` when `parseQuery` is off. */
+  readonly query: Record<string, string | string[]>
+  /** Parsed cookie object (last-wins per key) — `{}` when `parseCookies` is off. */
+  readonly cookies: Record<string, string>
+  /** Request body bytes when read for native validation, else empty. */
+  readonly body: Uint8Array
+  readonly ip: string | undefined
+  readonly req: Request
+}
+
+/** A JS 2xx builder invoked after the native pipeline succeeds (async OK). */
+export type NativeResponder = (snap: NativeRequestContext) => Response | Promise<Response>

package/src/integration/pipeline.ts

@@ -45,6 +45,7 @@ export interface PipelineContext {
   readonly locals: Map<string, unknown>
 }
 
+/** Result of running `preprocess`: terminal short-circuit or pass-through. */
 export interface PreprocessOutcome {
   /** True when the pipeline short-circuited (error/denied) — serve `response`. */
   readonly terminal: boolean
@@ -53,6 +54,7 @@ export interface PreprocessOutcome {
   readonly ctx: PipelineContext
 }
 
+/** Options for `createPipeline`. */
 export interface CreatePipelineOptions {
   /** Ingress options (same surface as `createIngressHandler`). */
   options?: IngressHandlerOptions
@@ -74,6 +76,7 @@ export interface CreatePipelineOptions {
   render?: (result: PipelineResult, ctx: PipelineContext) => Response | Promise<Response>
 }
 
+/** The composed ingress pipeline: preprocess / handleRequest / readBody. */
 export interface IngressPipeline {
   /** The underlying pre-baked handler (custom route factories / responses). */
   readonly ingress: OptimizedIngressHandler

package/src/integration/streaming.ts

@@ -1,8 +1,8 @@
 // src/integration/streaming.ts — SSE response helper.
 
 import { rust } from '../rust-ffi'
-
-export interface SseEvent {
+import { encoder } from '../shared/bytes'
+/** One SSE event to frame via `sseResponse` (event/id/retry/data). */ export interface SseEvent {
   /** Optional `event:` field. */
   event?: string | null
   /** Optional `id:` field. */
@@ -34,7 +34,6 @@ export function sseResponse(
   events: AsyncIterable<SseEvent> | Iterable<SseEvent>,
   init: ResponseInit = {},
 ): Response {
-  const encoder = new TextEncoder()
   const stream = new ReadableStream<Uint8Array>({
     async start(controller) {
       try {

package/src/integration/websocket.ts

@@ -1,12 +1,13 @@
 // src/integration/websocket.ts — WebSocket upgrade handshake helper.
 
+import { isBun } from '../shared/runtime'
 import { rust } from '../rust-ffi'
-
-export interface WebSocketUpgradeOptions {
+/** Options for `createWebSocketUpgrade` (supported subprotocols). */export interface WebSocketUpgradeOptions {
   /** Subprotocols this server supports; the first client-requested match wins. */
   protocols?: ReadonlyArray<string>
 }
 
+/** The WebSocket upgrade handshake result (101 response + negotiation info). */
 export interface WebSocketUpgradeResult {
   /** The 101 Switching Protocols response — return it from your fetch handler. */
   readonly response: Response
@@ -69,7 +70,7 @@ export function createWebSocketUpgrade(
   // Bun permits it. This helper produces a Bun.serve-compatible 101 Response,
   // so on Node throw a clear error pointing at the Node adapter's `upgrade`
   // option (which writes the RFC 6455 handshake head directly).
-  if (typeof Bun === 'undefined') {
+  if (!isBun()) {
     throw new Error(
       "createWebSocketUpgrade is Bun-only: Node's Response cannot carry status 101. " +
         "On Node, use createIngressServerNode's `upgrade` option and compute the " +

package/src/loader/batch.ts

@@ -94,6 +94,10 @@ export interface TickCoalescer {
   readonly pending: number
 }
 
+/**
+ * Create a microtask-based coalescer: `enqueue` schedules one flush that
+ * drains ALL pending ops; each op group is delivered to `flush` once.
+ */
 export function createTickCoalescer(
   flush: (op: string, requests: LoadRequest[]) => void,
 ): TickCoalescer {

package/src/loader/cost.ts

@@ -50,6 +50,7 @@ export const nowNs: () => number =
     ? () => Number(process.hrtime.bigint())
     : () => performance.now() * 1e6
 
+/** Options for `createCostModel` (adaptive batch-threshold learning). */
 export interface CostModelOptions {
   /** Allow the model to adjust `batchMin` from measurement. Default true. */
   adaptive?: boolean

package/src/loader/index.ts

@@ -18,247 +18,58 @@
 //   - caching      → bounded LRU ("Hot Function Cache"), default key =
 //                    fnv1a64(input) (skipped for sustained-unique workloads),
 //                    opt-in per call via `{ key, cache }`
+//
+// Structure: this file is the DISPATCH CORE + factory. The pure pieces live
+// beside it: `types.ts` (public type surface), `state.ts` (internal dispatch
+// state), `ops.ts` (op registry), `cost.ts` (adaptive cost model), `batch.ts`
+// (LRU cache + tick coalescer). Public types are re-exported below.
 
+import { rust } from '../rust-ffi'
+import { encoder, viewForArrayBuffer } from '../shared/bytes'
+import type { SchemaValidator } from '../shared/packed'
+import {
+  createLruCache,
+  createTickCoalescer,
+  type LoadRequest,
+} from './batch'
+import { createCostModel, nowNs } from './cost'
 import {
-  LOADER_OPS,
   fnvBatchKeysInto,
-  type LoaderBulkArgs,
-  type LoaderOpArgs,
+  LOADER_OPS,
   type LoaderOpName,
   type LoaderOpSpec,
   type LoaderScalar,
-  type LoaderBulk,
 } from './ops'
-import { createCostModel, nowNs, type LoaderCostModel } from './cost'
-import {
-  createLruCache,
-  createTickCoalescer,
-  type LoaderCache,
-  type LoadRequest,
-  type TickCoalescer,
-} from './batch'
-import { rust } from '../rust-ffi'
-import { viewForArrayBuffer } from '../shared/bytes'
-import type { SchemaValidator } from '../shared/packed'
+import type { LoaderState, OpDispatchCtx, OpFnEntry } from './state'
+import { KEY_SEP } from './state'
+import type {
+  LoadableName,
+  Loader,
+  LoaderOpFn,
+  LoaderOpStats,
+  LoaderOptions,
+  LoaderSchemaFn,
+  LoaderStats,
+  LoadOptions,
+} from './types'
 
 // Re-export the op registry + types for introspection and authoring.
 export {
-  LOADER_OPS,
+  type BulkResult,
   LOADER_OP_NAMES,
-  type LoaderOpName,
-  type LoaderOpArgs,
-  type LoaderBulkArgs,
+  LOADER_OPS,
   type LoaderBulk,
-  type LoaderScalar,
+  type LoaderBulkArgs,
+  type LoaderOpArgs,
+  type LoaderOpName,
   type LoaderResultKind,
+  type LoaderScalar,
   type ScalarResult,
-  type BulkResult,
 } from './ops'
 
-// ── Public types ────────────────────────────────────────────────────────────
-
-/** Options for `createLoader()` / `loader.configure()`. */
-export interface LoaderOptions {
-  /** Let each op adapt `batchMin` from measured dispatch cost. Default true. */
-  adaptive?: boolean
-  /** Initial batch threshold in [2, 8]. Default 2 (batch wins for n >= 2). */
-  batchMin?: number
-  /** Max cached keys (bounded LRU). 0 disables caching. Default 256. */
-  maxCacheKeys?: number
-  /** Default `cache` behavior for `load()`. Default true. */
-  caching?: boolean
-  /** Sample timing every N dispatches (hot-path cost control). Default 32. */
-  sampleEvery?: number
-  /**
-   * `load()` dispatch strategy. `"auto"` (default) switches each op between
-   * `"single"` (low load → direct scalar call, no coalescer) and
-   * `"coalesce"` (rising load → one packed batch call) from observed load.
-   */
-  loadStrategy?: LoadStrategy
-}
-
-/** Options for `load()` / `opFn.load()`. */
-export interface LoadOptions {
-  /**
-   * Explicit cache key. When omitted (and caching is on) the default key is
-   * `fnv1a64(input)` — which costs one extra native call per load.
-   */
-  key?: string
-  /** Override the loader-wide caching toggle for this call. Default true. */
-  cache?: boolean
-}
-
-/** Per-op counters exposed on `opFn.stats`. */
-export interface LoaderOpStats {
-  scalarCalls: number
-  batchCalls: number
-  itemsDispatched: number
-  cachedHits: number
-  /** Current learned batch threshold for this op. */
-  batchMin: number
-  /** Current `load()` strategy: "single" (low load) or "coalesce" (bulk). */
-  mode: 'single' | 'coalesce'
-}
-
-/** Aggregate loader statistics. */
-export interface LoaderStats {
-  scalarCalls: number
-  batchCalls: number
-  itemsDispatched: number
-  flushes: number
-  cachedHits: number
-  cacheSize: number
-  cacheEvictions: number
-}
-
-/** A specialized, pre-bound op function returned by `loader(op)`. */
-export interface LoaderOpFn<K extends LoaderOpName> {
-  /** Single item → scalar result. */
-  (input: Uint8Array, ...rest: LoaderOpArgs[K]): LoaderScalar<K>
-  /** Bulk items → ONE packed batch call; same shape as `rust.batch.<op>`. */
-  (inputs: Uint8Array[], ...rest: LoaderBulkArgs<K>): LoaderBulk<K>
-  readonly name: K
-  readonly stats: LoaderOpStats
-  clear(): void
-  /** Sync cache peek (default key `fnv1a64(input)` unless `key` given). */
-  cache(input: Uint8Array, key?: string): LoaderScalar<K> | undefined
-  /**
-   * Coalesced, cache-aware load. Unavailable (`undefined`) on ops that require
-   * extra arguments (e.g. `hmacSha256`, `signCookie`) — use `run` for those.
-   */
-  load: K extends LoadableName ? LoaderLoadFn<K> : undefined
-}
-
-type LoaderLoadFn<K extends LoaderOpName> = (
-  input: Uint8Array,
-  opts?: LoadOptions,
-) => Promise<LoaderScalar<K>>
-
-/** Ops whose extra args are all optional/empty → they support `load()`. */
-type LoadableName = {
-  [K in LoaderOpName]: LoaderOpArgs[K] extends
-    | []
-    | [unknown?]
-    | [unknown?, unknown?]
-    | [unknown?, unknown?, unknown?]
-    ? K
-    : never
-}[LoaderOpName]
-
-/** A validator-bound helper returned by `loader.schema(validator)`. */
-export interface LoaderSchemaFn {
-  /** Single JSON document → valid? */
-  (input: Uint8Array): boolean
-  /** Bulk JSON documents → bitset (1 per doc). */
-  (inputs: Uint8Array[]): Uint8Array
-  /** Count how many bulk documents are valid. */
-  count(inputs: Uint8Array[]): number
-}
-
-/** The global callable loader. */
-export interface Loader {
-  /** Higher-order function: `loader(op)` → specialized hot op function. */
-  <K extends LoaderOpName>(op: K): LoaderOpFn<K>
-  /** Single-item dispatch. */
-  run<K extends LoaderOpName>(op: K, input: Uint8Array, ...rest: LoaderOpArgs[K]): LoaderScalar<K>
-  /** Bulk dispatch (one packed batch call, or adaptive scalar loop). */
-  run<K extends LoaderOpName>(
-    op: K,
-    inputs: Uint8Array[],
-    ...rest: LoaderBulkArgs<K>
-  ): LoaderBulk<K>
-  /** Coalesced, cache-aware load (ops with required extra args throw). */
-  load<K extends LoadableName>(
-    op: K,
-    input: Uint8Array,
-    opts?: LoadOptions,
-  ): Promise<LoaderScalar<K>>
-  /** Sync cache peek. */
-  cache<K extends LoaderOpName>(op: K, input: Uint8Array, key?: string): LoaderScalar<K> | undefined
-  /**
-   * Bind a `SchemaValidator` for repeated single/bulk JSON-schema validation
-   * plus a whole-batch `count`. The returned callable uses the loader's normal
-   * dispatch machinery (cost model + counters).
-   */
-  schema(validator: SchemaValidator): LoaderSchemaFn
-  /** Clear the shared cache (pending coalesced loads still flush). */
-  clear(): void
-  /** Update options at runtime. */
-  configure(options: LoaderOptions): void
-  readonly stats: LoaderStats
-  readonly opNames: LoaderOpName[]
-}
-
-// ── Internal state ──────────────────────────────────────────────────────────
-
-interface OpCounters {
-  scalarCalls: number
-  batchCalls: number
-  itemsDispatched: number
-  cachedHits: number
-}
-
-/** Load-dispatch strategy selector for `load()`. */
-type LoadStrategy = 'auto' | 'single' | 'coalesce'
-
-/**
- * Pre-bound per-op dispatch context — avoids Map lookups on the hot path.
- * Holds the load-aware `load()` strategy plus its cheap integer signals so
- * the single-vs-coalesce decision costs no Map lookup or allocation.
- */
-interface OpDispatchCtx {
-  cost: LoaderCostModel
-  counters: OpCounters
-  sampleEvery: number
-  /** Per-op sample tick counter (advances on every dispatch). */
-  counter: number
-  /** Current `load()` strategy for this op. */
-  mode: 'single' | 'coalesce'
-  /** Consecutive single-load flushes observed (coalesce mode only). */
-  singleStreak: number
-  /** A single-mode load is waiting on its microtask to dispatch. */
-  pendingSingle: boolean
-  pendingInput: Uint8Array | null
-  pendingResolve: ((value: unknown) => void) | null
-  pendingReject: ((error: unknown) => void) | null
-  pendingKey: string | undefined
-  /** Default-key attempts (adaptive key computation). */
-  keyAttempts: number
-  /** Default-key cache hits observed. */
-  keyHits: number
-  /** Periodic re-probe counter for skipped default keys. */
-  keyProbeCounter: number
-}
-
-/** A memoized op fn plus a hook to rebind its dispatch context on configure. */
-interface OpFnEntry {
-  op: LoaderOpName
-  fn: LoaderOpFn<LoaderOpName>
-  /** Rebind to a fresh context after `configure()` so dispatch + stats stay current. */
-  rebind(ctx: OpDispatchCtx): void
-}
-
-interface LoaderState {
-  options: Required<
-    Pick<
-      LoaderOptions,
-      'adaptive' | 'batchMin' | 'maxCacheKeys' | 'caching' | 'sampleEvery' | 'loadStrategy'
-    >
-  >
-  ctxs: Map<LoaderOpName, OpDispatchCtx>
-  cache: LoaderCache
-  coalescer: TickCoalescer
-  opFns: Map<LoaderOpName, OpFnEntry>
-  flushes: number
-  /** Reusable packed-input scratch for the zero-alloc fast flush (grows). */
-  packScratch: Uint8Array
-  /** Reusable packed-output buffer for the zero-alloc fast flush (grows). */
-  outScratch: Uint8Array
-  /** Reusable packed-key output buffer for the batched default-key flush. */
-  keyScratch: Uint8Array
-}
-
-const KEY_SEP = '\u0000'
+// Re-export the public type surface so `import type { LoaderOptions } from
+// '../loader'` keeps working (existing call sites).
+export * from './types'
 
 // ── Load-aware `load()` strategy + adaptive-key tuning ──
 /** Consecutive single-load flushes before an op drops the coalescer. */
@@ -268,7 +79,6 @@ const KEY_WARMUP = 8
 /** After warm-up with zero hits, re-probe the default key every N loads. */
 const KEY_PROBE_EVERY = 64
 
-/** Get (or lazily create) the dispatch context for an op. */
 function ctxFor(state: LoaderState, op: LoaderOpName): OpDispatchCtx {
   let ctx = state.ctxs.get(op)
   if (!ctx) {
@@ -299,6 +109,11 @@ function ctxFor(state: LoaderState, op: LoaderOpName): OpDispatchCtx {
   return ctx
 }
 
+/** Normalize a loader scalar result to bytes (the string-returning rust.* ops
+ * return strings on the Bun path — the loader's BYTES contract stays bytes). */
+const asBytes = (v: unknown): Uint8Array =>
+  typeof v === 'string' ? encoder.encode(v) : (v as Uint8Array)
+
 /** Build a bulk-shaped result by looping scalar calls (the adaptive fallback). */
 function scalarLoopBulk(spec: LoaderOpSpec, items: Uint8Array[], rest: unknown[]): unknown {
   const n = items.length
@@ -345,7 +160,7 @@ function scalarLoopBulk(spec: LoaderOpSpec, items: Uint8Array[], rest: unknown[]
       const out = new Array<Uint8Array>(n)
       let i = 0
       for (const item of items) {
-        out[i] = spec.scalar(item, ...itemRest(i)) as Uint8Array
+        out[i] = asBytes(spec.scalar(item, ...itemRest(i)))
         i++
       }
       return out
@@ -364,7 +179,7 @@ function dispatchSingle(
   c.scalarCalls++
   c.itemsDispatched++
   const t = ++ctx.counter % ctx.sampleEvery === 0 ? nowNs() : 0
-  const out = rest.length === 0 ? spec.scalar(input) : spec.scalar(input, ...rest)
+  const out = asBytes(rest.length === 0 ? spec.scalar(input) : spec.scalar(input, ...rest))
   if (t !== 0) ctx.cost.recordScalar(1, nowNs() - t)
   return out
 }

package/src/loader/state.ts

@@ -0,0 +1,84 @@
+// src/loader/state.ts — internal loader dispatch state (pure types).
+//
+// The per-op dispatch context, memoized op-fn entry, and the aggregate
+// `LoaderState` shared by the dispatch core (index.ts). `KEY_SEP` is the
+// cache-key separator for `op + '\0' + key`.
+
+import type { LoaderCache, TickCoalescer } from './batch'
+import type { LoaderCostModel } from './cost'
+import type { LoaderOpName } from './ops'
+import type { LoaderOpFn, LoaderOptions } from './types'
+
+// ── Internal state ──────────────────────────────────────────────────────────
+
+/** Per-op dispatch counters: scalar calls, batch calls, items dispatched, and
+ * cache hits. Advanced on every dispatch and exposed via `loader.stats()`. */
+export interface OpCounters {
+  scalarCalls: number
+  batchCalls: number
+  itemsDispatched: number
+  cachedHits: number
+}
+
+/**
+ * Pre-bound per-op dispatch context — avoids Map lookups on the hot path.
+ * Holds the load-aware `load()` strategy plus its cheap integer signals so
+ * the single-vs-coalesce decision costs no Map lookup or allocation.
+ */
+export interface OpDispatchCtx {
+  cost: LoaderCostModel
+  counters: OpCounters
+  sampleEvery: number
+  /** Per-op sample tick counter (advances on every dispatch). */
+  counter: number
+  /** Current `load()` strategy for this op. */
+  mode: 'single' | 'coalesce'
+  /** Consecutive single-load flushes observed (coalesce mode only). */
+  singleStreak: number
+  /** A single-mode load is waiting on its microtask to dispatch. */
+  pendingSingle: boolean
+  pendingInput: Uint8Array | null
+  pendingResolve: ((value: unknown) => void) | null
+  pendingReject: ((error: unknown) => void) | null
+  pendingKey: string | undefined
+  /** Default-key attempts (adaptive key computation). */
+  keyAttempts: number
+  /** Default-key cache hits observed. */
+  keyHits: number
+  /** Periodic re-probe counter for skipped default keys. */
+  keyProbeCounter: number
+}
+
+/** A memoized op fn plus a hook to rebind its dispatch context on configure. */
+export interface OpFnEntry {
+  op: LoaderOpName
+  fn: LoaderOpFn<LoaderOpName>
+  /** Rebind to a fresh context after `configure()` so dispatch + stats stay current. */
+  rebind(ctx: OpDispatchCtx): void
+}
+
+/** Aggregate loader state shared by the dispatch core (index.ts): the resolved
+ * options, per-op dispatch contexts, the LRU cache + tick coalescer, memoized
+ * op fns, and the reusable zero-alloc pack/out/key scratch buffers. */
+export interface LoaderState {
+  options: Required<
+    Pick<
+      LoaderOptions,
+      'adaptive' | 'batchMin' | 'maxCacheKeys' | 'caching' | 'sampleEvery' | 'loadStrategy'
+    >
+  >
+  ctxs: Map<LoaderOpName, OpDispatchCtx>
+  cache: LoaderCache
+  coalescer: TickCoalescer
+  opFns: Map<LoaderOpName, OpFnEntry>
+  flushes: number
+  /** Reusable packed-input scratch for the zero-alloc fast flush (grows). */
+  packScratch: Uint8Array
+  /** Reusable packed-output buffer for the zero-alloc fast flush (grows). */
+  outScratch: Uint8Array
+  /** Reusable packed-key output buffer for the batched default-key flush. */
+  keyScratch: Uint8Array
+}
+
+/** NUL separator used to join composite cache keys (never appears in keys). */
+export const KEY_SEP = '\u0000'