castrum 0.7.0 → 0.9.0

package/src/ingress/types.ts

@@ -0,0 +1,157 @@
+// src/ingress/types.ts — Public API types for the ingress module.
+//
+// Shared by the sync/async factories in ./index.ts and the result/context
+// 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'
+
+/** Public ingress options (extends the fast-path options). */
+export interface IngressOptions extends IngressFastOptions {
+  enableRequestIds?: boolean
+  /**
+   * Invoked before a request is processed (for tracing/context hooks).
+   * Only used by the async `createIngress` path.
+   */
+  onRequest?: (req: Request, requestId: string, ip: string | undefined) => void
+  /**
+   * Invoked after a terminal context (and its `Response`) is produced, for
+   * metrics/logging hooks. Only used by the async `createIngress` path.
+   */
+  onResponse?: (req: Request, result: IngressContext, status: number, requestId: string) => void
+}
+
+/**
+ * Readonly structural view of a decoded ingress result.
+ *
+ * Note: the exported `FastIngressResult` class is the zero-alloc implementation;
+ * this interface is the readonly view used by the public sync/async handlers.
+ */
+export interface IngressResult {
+  readonly status: number
+  readonly verdict: number
+  readonly flags: number
+  readonly errorCode: number
+  readonly terminal: boolean
+  readonly ok: boolean
+  readonly https: boolean
+  readonly trustedProxy: boolean
+  readonly hasCookies: boolean
+  readonly hasQuery: boolean
+  readonly bodyValidJson: boolean
+  readonly schemaValid: boolean
+  readonly corsAllowed: boolean
+  readonly isPreflight: boolean
+  readonly rateLimited: boolean
+  readonly rateLimit: number
+  readonly rateRemaining: number
+  readonly rateResetMs: number
+  readonly retryAfterMs: number
+  readonly body: Uint8Array
+  readonly headerVariant: number
+  readonly requestId: string
+  readonly bodyTruncated: boolean
+
+  cookiesJson(): string
+  queryJson(): string
+  bodyJson(): Uint8Array
+}
+
+/** A result plus the terminal Response computed for it. */
+export interface IngressContext extends IngressResult {
+  response: Response | null
+}
+
+/**
+ * Synchronous ingress handler.
+ *
+ * The callback runs on the zero-alloc result object and MUST be synchronous:
+ * returning a Promise (or any thenable) throws. The result is invalidated after
+ * `run()` returns, so capture the fields you need inside the callback (or use
+ * the async {@link IngressHandler} which snapshots for you).
+ */
+export interface SyncIngressHandler {
+  run<T>(
+    req: Request,
+    ip: string | undefined,
+    body: Uint8Array | null,
+    requestId: string,
+    fn: (result: IngressResult) => T,
+  ): T
+}
+
+/** Async ingress handler (wraps {@link SyncIngressHandler} with body reading). */
+export type IngressHandler = (req: Request, ip?: string) => Promise<IngressContext>
+
+// ── Pre-baked (handlers.ts) shared types ────────────────────────────
+// These live here (not in ./handlers.ts) so the route factories in
+// ./routes/* can import them without a type-only cycle back into the factory
+// module that aggregates them. `handlers.ts` re-exports them for back-compat.
+
+/** Mutable per-request context threaded through the pre-baked handler run. */
+export interface BakedContext {
+  /** The request-id string (null when `emitRequestIdHeader` is off). */
+  requestIdHeader: string | null
+  /** The `Origin` request header when CORS extraction is enabled. */
+  origin: string | null
+}
+
+/**
+ * An optimized ingress handler. `run()` is the zero-alloc pipeline entry
+ * point; the response-builder methods are pre-baked and bound to this
+ * handler's configuration, so consumers can build custom routes without
+ * touching header templates or error bodies.
+ */
+export interface OptimizedIngressHandler {
+  run<T>(
+    req: Request,
+    ip: string | undefined,
+    body: Uint8Array | null,
+    fn: (result: BakedIngressResult, ctx: BakedContext) => T,
+  ): T
+
+  responseHeaders(
+    variant: number,
+    requestIdHeader: string | null,
+    origin: string | null,
+    rateRemaining?: number,
+    rateResetSecs?: number,
+    retryAfterSecs?: number,
+  ): [string, string][]
+
+  terminalHeaders(
+    variant: number,
+    ctx: BakedContext,
+    result: BakedIngressResult | null,
+  ): [string, string][]
+
+  /** `req` is accepted for back-compat but unused by the baked terminal path. */
+  terminalResponse(
+    req: Request | undefined,
+    result: BakedIngressResult,
+    ctx: BakedContext,
+  ): Response | null
+
+  /** `req` is accepted for back-compat but unused by the baked error path. */
+  errorResponse(
+    req: Request | undefined,
+    result: BakedIngressResult | null,
+    status: number,
+    code: string,
+    message: string,
+    ctx: BakedContext,
+  ): Response
+
+  internalErrorResponse(ctx: BakedContext, result?: BakedIngressResult): Response
+
+  withContentType(headers: ReadonlyArray<[string, string]>, contentType: string): [string, string][]
+
+  /**
+   * 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
+   * consumed (stream closed) or the request aborted. Use when `copyBody` is
+   * `false`; otherwise a copied body is released eagerly at the end of `run()`.
+   */
+  zeroCopyResponse(result: BakedIngressResult, ctx: BakedContext, init: ResponseInit): Response
+}

package/src/integration/batch.ts

@@ -0,0 +1,58 @@
+// src/integration/batch.ts — Loader-backed bulk processing helpers.
+//
+// The higher-order loader (`castrum.loader`, src/loader) is built for BULK /
+// coalesced work: many same-tick items dispatch as ONE packed native batch
+// call instead of N native crossings, and expensive same-tick `load()`s
+// coalesce into one packed flush. These helpers surface that machinery through
+// the integration layer so the loader is actually USED at runtime — not just
+// exported and benchmarked — for the workloads it genuinely serves.
+//
+// Honest guidance: for ONE item per request the loader's dispatch adds a small
+// constant tax (~1.04–1.29x of a direct scalar call). Batching pays off when
+// you process many items together (validating/hashing a list, batch schema
+// checks) — exactly the pattern these helpers exist for.
+
+import {
+  loader,
+  type LoaderBulk,
+  type LoaderBulkArgs,
+  type LoaderOpArgs,
+  type LoaderOpName,
+  type LoaderScalar,
+} from '../loader'
+import type { SchemaValidator } from '../shared/packed'
+
+/**
+ * Batch-validate JSON documents against a schema through the loader's bulk
+ * `schemaValidate` path. Returns a bitset — byte `i` is 1 when document `i`
+ * is valid (same shape as `rust.batch.schemaValidate`).
+ */
+export function validateMany(validator: SchemaValidator, docs: Uint8Array[]): Uint8Array {
+  return loader.schema(validator)(docs)
+}
+
+/** Count how many of `docs` validate against `validator` (one packed call). */
+export function validateCount(validator: SchemaValidator, docs: Uint8Array[]): number {
+  return loader.schema(validator).count(docs)
+}
+
+/**
+ * Generic loader bulk dispatch: `loader.run(op, items, ...rest)` → one packed
+ * batch native call (or the adaptive scalar loop for tiny batches).
+ */
+export function runMany<K extends LoaderOpName>(
+  op: K,
+  items: Uint8Array[],
+  ...rest: LoaderBulkArgs<K>
+): LoaderBulk<K> {
+  return loader.run(op, items, ...rest)
+}
+
+/** Single-item loader dispatch — pairs with `runMany` for mixed workloads. */
+export function runOne<K extends LoaderOpName>(
+  op: K,
+  item: Uint8Array,
+  ...rest: LoaderOpArgs[K]
+): LoaderScalar<K> {
+  return loader.run(op, item, ...rest)
+}

package/src/integration/index.ts

@@ -0,0 +1,29 @@
+// src/integration/index.ts — framework-agnostic integration helpers.
+//
+// These helpers let any Bun backend framework (Hono, Elysia, or plain
+// Bun.serve) embed castrum as a request stage:
+//   - createPipeline   → run the ingress pipeline (rate-limit/CORS/schema/body)
+//                        and either short-circuit or hand a context to the app
+//   - createWebSocketUpgrade → RFC 6455 101 upgrade handshake
+//   - sseResponse      → server-sent-events response framed on the fast path
+
+export {
+  createPipeline,
+  type IngressPipeline,
+  type PipelineResult,
+  type PipelineContext,
+  type PreprocessOutcome,
+  type CreatePipelineOptions,
+} from './pipeline'
+export {
+  createWebSocketUpgrade,
+  type WebSocketUpgradeOptions,
+  type WebSocketUpgradeResult,
+} from './websocket'
+export { sseResponse, type SseEvent } from './streaming'
+export {
+  validateMany,
+  validateCount,
+  runMany,
+  runOne,
+} from './batch'

package/src/integration/pipeline.ts

@@ -0,0 +1,217 @@
+// src/integration/pipeline.ts — framework-agnostic ingress pipeline adapter.
+//
+// Embeds the pre-baked ingress pipeline as a request stage that ANY Bun
+// backend framework can use: Hono middleware, Elysia onRequest, or a plain
+// Bun.serve `fetch`. `preprocess` runs the rate-limit / CORS / schema / body
+// logic and either short-circuits (terminal) or hands a snapshotted result +
+// context to the app's own handler. `handleRequest` is a fetch-compatible
+// convenience that serves the terminal response or a rendered OK response.
+
+import {
+  createIngressHandler,
+  type BakedIngressRuntime,
+  type OptimizedIngressHandler,
+} from '../ingress/handlers'
+import type { BakedContext } from '../ingress/types'
+import type { IngressHandlerOptions } from '../ingress/options'
+import { readBodyWithLimit } from '../ingress/body'
+import { DEFAULT_MAX_BODY_BYTES, DEFAULT_BODY_TIMEOUT_MS } from '../ingress/shared'
+import { generateRequestId } from '../shared/request-id'
+import { decoder } from '../shared/bytes'
+import type { BakedIngressResult } from '../ingress/decode/baked-result'
+
+/** Readonly snapshot of the ingress decision, safe after `run()` returns. */
+export interface PipelineResult {
+  readonly ok: boolean
+  readonly status: number
+  readonly errorCode: number
+  readonly terminal: boolean
+  readonly rateLimited: boolean
+  readonly bodyValidJson: boolean
+  readonly schemaValid: boolean
+  readonly bodyTruncated: boolean
+  readonly requestId: string
+  /** The raw request body the pipeline saw (read-only; aliases the request body). */
+  readonly body: Uint8Array
+  /** The ingress metadata JSON body (when `emitMetadataJson` is on), else empty. */
+  readonly metadataJson: Uint8Array
+}
+
+/** Per-request context threaded into the app's handler. */
+export interface PipelineContext {
+  readonly requestId: string
+  readonly ip: string | undefined
+  /** Mutable per-request storage for middleware/user state. */
+  readonly locals: Map<string, unknown>
+}
+
+export interface PreprocessOutcome {
+  /** True when the pipeline short-circuited (error/denied) — serve `response`. */
+  readonly terminal: boolean
+  readonly response: Response | null
+  readonly result: PipelineResult | null
+  readonly ctx: PipelineContext
+}
+
+export interface CreatePipelineOptions {
+  /** Ingress options (same surface as `createIngressHandler`). */
+  options?: IngressHandlerOptions
+  /** Runtime hooks: onRequest/onResponse/onError, logging, pool sizing. */
+  runtime?: BakedIngressRuntime
+  /** Body limit for `readBody`/`preprocess`. Default: 1 MiB. */
+  maxBodyBytes?: number
+  /** Body-read deadline (ms) for `readBody`/`preprocess`. Default: 30s. */
+  bodyTimeoutMs?: number
+  /**
+   * When true (default), `preprocess` reads a request body (guarded) so the
+   * result carries it. Set false when the app handler owns the body.
+   */
+  readBody?: boolean
+  /**
+   * Optional renderer for the OK (non-terminal) case of `handleRequest`.
+   * Defaults to a minimal `{"ok":true,"requestId":...}` JSON body.
+   */
+  render?: (result: PipelineResult, ctx: PipelineContext) => Response | Promise<Response>
+}
+
+export interface IngressPipeline {
+  /** The underlying pre-baked handler (custom route factories / responses). */
+  readonly ingress: OptimizedIngressHandler
+  /** Run the pipeline for a middleware/framework. */
+  preprocess(req: Request, ip?: string): Promise<PreprocessOutcome>
+  /** Fetch-compatible handler: terminal response or the renderer's response. */
+  handleRequest(req: Request, ip?: string): Promise<Response>
+  /** Stream-read a request body with the configured limits. */
+  readBody(req: Request, maxBytes?: number, timeoutMs?: number): Promise<Uint8Array>
+}
+
+function snapshotResult(result: BakedIngressResult, requestId: string): PipelineResult {
+  return {
+    ok: result.ok,
+    status: result.status,
+    errorCode: result.errorCode,
+    terminal: result.terminal,
+    rateLimited: result.rateLimited,
+    bodyValidJson: result.bodyValidJson,
+    schemaValid: result.schemaValid,
+    bodyTruncated: result.bodyTruncated,
+    requestId,
+    body: result.body,
+    metadataJson: result.bodyJson(true) as Uint8Array,
+  }
+}
+
+/** Build a terminal error response for a body-read failure (413/408/400). */
+function bodyErrorResponse(
+  ingress: OptimizedIngressHandler,
+  req: Request,
+  requestId: string,
+  err: unknown,
+): Response {
+  const ctx: BakedContext = {
+    requestIdHeader: requestId,
+    origin: req.headers.get('origin'),
+  }
+  const code = (err as { code?: string } | null)?.code
+  if (code === 'BODY_TOO_LARGE') {
+    return ingress.errorResponse(req, null, 413, 'body_too_large', 'Request body is too large', ctx)
+  }
+  if (code === 'REQUEST_TIMEOUT') {
+    return ingress.errorResponse(
+      req,
+      null,
+      408,
+      'request_timeout',
+      'Request body read timed out',
+      ctx,
+    )
+  }
+  return ingress.errorResponse(req, null, 400, 'bad_request', 'Bad request', ctx)
+}
+
+/**
+ * Create a framework-agnostic ingress pipeline.
+ *
+ * @example
+ * ```ts
+ * // Plain Bun.serve fetch handler
+ * const pipeline = createPipeline({ options: { parseCookies: true } });
+ * Bun.serve({ port: 3000, fetch: (req) => pipeline.handleRequest(req) });
+ *
+ * // Hono-style middleware: short-circuit on terminal, else handle the app route
+ * app.use("*", async (c, next) => {
+ *   const { terminal, response, ctx } = await pipeline.preprocess(c.req.raw);
+ *   if (terminal && response) return response;
+ *   c.set("ingress", ctx); // pass requestId / locals into the app handler
+ *   await next();
+ * });
+ * ```
+ */
+export function createPipeline(opts: CreatePipelineOptions = {}): IngressPipeline {
+  const ingress = createIngressHandler(opts.options ?? {}, opts.runtime ?? {})
+  const maxBodyBytes = opts.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
+  const bodyTimeoutMs = opts.bodyTimeoutMs ?? DEFAULT_BODY_TIMEOUT_MS
+  const readBodyEnabled = opts.readBody !== false
+  const render =
+    opts.render ??
+    ((result: PipelineResult): Response =>
+      new Response(JSON.stringify({ ok: true, requestId: result.requestId }), {
+        status: result.status,
+        headers: { 'content-type': 'application/json; charset=utf-8' },
+      }))
+
+  async function preprocess(req: Request, ip?: string): Promise<PreprocessOutcome> {
+    const requestId = decoder.decode(generateRequestId())
+    const ctx: PipelineContext = { requestId, ip, locals: new Map() }
+
+    let body: Uint8Array | null = null
+    if (readBodyEnabled && req.body !== null) {
+      try {
+        body = await readBodyWithLimit(req, maxBodyBytes, true, bodyTimeoutMs)
+      } catch (err) {
+        return {
+          terminal: true,
+          response: bodyErrorResponse(ingress, req, requestId, err),
+          result: null,
+          ctx,
+        }
+      }
+    }
+
+    return ingress.run<PreprocessOutcome>(req, ip, body, (result, ingressCtx) => {
+      if (result.terminal) {
+        return {
+          terminal: true,
+          response: ingress.terminalResponse(req, result, ingressCtx),
+          result: null,
+          ctx,
+        }
+      }
+      return {
+        terminal: false,
+        response: null,
+        result: snapshotResult(result, requestId),
+        ctx,
+      }
+    })
+  }
+
+  async function handleRequest(req: Request, ip?: string): Promise<Response> {
+    const outcome = await preprocess(req, ip)
+    if (outcome.terminal && outcome.response) {
+      return outcome.response
+    }
+    const result = outcome.result as PipelineResult
+    return render(result, outcome.ctx)
+  }
+
+  function readBody(
+    req: Request,
+    maxBytes: number = maxBodyBytes,
+    timeoutMs: number = bodyTimeoutMs,
+  ): Promise<Uint8Array> {
+    return readBodyWithLimit(req, maxBytes, true, timeoutMs)
+  }
+
+  return { ingress, preprocess, handleRequest, readBody }
+}

package/src/integration/streaming.ts

@@ -0,0 +1,79 @@
+// src/integration/streaming.ts — SSE response helper.
+
+import { rust } from '../rust-ffi'
+
+export interface SseEvent {
+  /** Optional `event:` field. */
+  event?: string | null
+  /** Optional `id:` field. */
+  id?: string | null
+  /** Optional `retry:` field (ms). */
+  retry?: number | null
+  /** Event data. */
+  data: string | Uint8Array
+}
+
+/**
+ * Build a `text/event-stream` Response from an (async) iterable of events.
+ *
+ * Each event is framed with the native `rust.sseEncodeEvent` (zero-DOM, byte
+ * parity with the FFI primitive), so SSE stays on the fast path:
+ *
+ * @example
+ * ```ts
+ * async function* tick() {
+ *   for (let i = 0; i < 5; i++) {
+ *     await Bun.sleep(250);
+ *     yield { event: "tick", data: String(i) };
+ *   }
+ * }
+ * return sseResponse(tick(), { headers: { "x-request-id": rid } });
+ * ```
+ */
+export function sseResponse(
+  events: AsyncIterable<SseEvent> | Iterable<SseEvent>,
+  init: ResponseInit = {},
+): Response {
+  const encoder = new TextEncoder()
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      try {
+        for await (const ev of events) {
+          const data = typeof ev.data === 'string' ? encoder.encode(ev.data) : ev.data
+          controller.enqueue(
+            rust.sseEncodeEvent(ev.event ?? null, data, ev.id ?? null, ev.retry ?? null),
+          )
+        }
+      } finally {
+        controller.close()
+      }
+    },
+  })
+
+  // Merge caller headers without relying on a specific `HeadersInit` type
+  // (Bun vs undici global type drift), then force the SSE headers.
+  const merged: Record<string, string> = {}
+  const provided = init.headers
+  if (provided) {
+    if (provided instanceof Headers) {
+      provided.forEach((value, key) => {
+        merged[key] = value
+      })
+    } else if (Array.isArray(provided)) {
+      for (const [key, value] of provided) {
+        merged[key] = String(value)
+      }
+    } else {
+      Object.assign(merged, provided)
+    }
+  }
+  merged['content-type'] = 'text/event-stream'
+  merged['cache-control'] = 'no-cache'
+  merged.connection = 'keep-alive'
+
+  return new Response(stream, {
+    status: init.status,
+    statusText: init.statusText,
+    headers: merged,
+  })
+}

package/src/integration/websocket.ts

@@ -0,0 +1,92 @@
+// src/integration/websocket.ts — WebSocket upgrade handshake helper.
+
+import { rust } from '../rust-ffi'
+
+export interface WebSocketUpgradeOptions {
+  /** Subprotocols this server supports; the first client-requested match wins. */
+  protocols?: ReadonlyArray<string>
+}
+
+export interface WebSocketUpgradeResult {
+  /** The 101 Switching Protocols response — return it from your fetch handler. */
+  readonly response: Response
+  /** The client's `Sec-WebSocket-Key` (handy for connection logging). */
+  readonly key: string
+  /** The negotiated subprotocol, if any. */
+  readonly protocol: string | null
+}
+
+/**
+ * Build a WebSocket 101 upgrade handshake response for a request.
+ *
+ * Validates `Sec-WebSocket-Key` presence and computes the RFC 6455 accept key
+ * via the native `rust.wsAcceptKey`, optionally negotiates a subprotocol, and
+ * returns a ready-to-serve `Response`. Returns `null` when the request is not a
+ * valid upgrade (missing/empty key).
+ *
+ * This only produces the handshake — pair it with your framework's own
+ * WebSocket server (Bun.serve's `websocket` handler, or a WS library), which
+ * owns the subsequent frames:
+ *
+ * @example
+ * ```ts
+ * const srv = Bun.serve({
+ *   port: 3000,
+ *   fetch(req, server) {
+ *     const up = createWebSocketUpgrade(req, { protocols: ["chat"] });
+ *     if (up && server.upgrade(req, { data: { protocol: up.protocol } })) {
+ *       return up.response;
+ *     }
+ *     return new Response("Not a websocket", { status: 400 });
+ *   },
+ *   websocket: {
+ *     message(ws, msg) { ws.send(msg); },
+ *   },
+ * });
+ * ```
+ */
+export function createWebSocketUpgrade(
+  req: Request,
+  opts: WebSocketUpgradeOptions = {},
+): WebSocketUpgradeResult | null {
+  const key = req.headers.get('sec-websocket-key')
+  if (!key || key.length === 0) return null
+
+  const accept = rust.text.wsAcceptKey(key)
+
+  let protocol: string | null = null
+  const offered = opts.protocols ?? []
+  const requested = req.headers.get('sec-websocket-protocol')
+  if (requested && offered.length > 0) {
+    const wanted = requested
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean)
+    protocol = offered.find((p) => wanted.some((w) => w.toLowerCase() === p.toLowerCase())) ?? null
+  }
+
+  // Node's fetch `Response` rejects status 101 (undici allows only 200-599);
+  // 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') {
+    throw new Error(
+      "createWebSocketUpgrade is Bun-only: Node's Response cannot carry status 101. " +
+        "On Node, use createIngressServerNode's `upgrade` option and compute the " +
+        'accept key with rust.text.wsAcceptKey().',
+    )
+  }
+
+  const headers: Record<string, string> = {
+    'sec-websocket-accept': accept,
+  }
+  if (protocol) {
+    headers['sec-websocket-protocol'] = protocol
+  }
+
+  return {
+    response: new Response(null, { status: 101, headers }),
+    key,
+    protocol,
+  }
+}