castrum 0.9.0 → 0.9.1

package/src/ingress/routes/options.ts

@@ -1,8 +1,7 @@
 // src/ingress/routes/options.ts — Pre-baked OPTIONS handler (CORS preflight).
 
 import type { OptimizedIngressHandler } from '../types'
-import { resolveIp, type BakedHandlerOptions } from './common'
-import { secondsFromMs } from '../shared'
+import { buildSuccessInit, resolveIp, type BakedHandlerOptions } from './common'
 
 /**
  * Pre-baked OPTIONS handler: serves the native pipeline's CORS preflight
@@ -22,15 +21,6 @@ export function optionsHandler(
       const terminal = ingress.terminalResponse(req, result, ctx)
       if (terminal) return terminal
 
-      return new Response(null, {
-        status: 204,
-        headers: ingress.responseHeaders(
-          result.headerVariant,
-          ctx.requestIdHeader,
-          ctx.origin,
-          result.rateRemaining,
-          result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined,
-        ),
-      })
+      return new Response(null, buildSuccessInit(ingress, result, ctx, 204))
     })
 }

package/src/ingress/routes/read.ts

@@ -2,8 +2,7 @@
 
 import type { BakedContext, OptimizedIngressHandler } from '../types'
 import type { BakedIngressResult } from '../decode/baked-result'
-import { resolveIp, type BakedHandlerOptions } from './common'
-import { secondsFromMs } from '../shared'
+import { buildSuccessInit, runBaked, type BakedHandlerOptions } from './common'
 
 /**
  * Pre-baked GET read handler: returns the ingress body JSON on success.
@@ -25,21 +24,12 @@ export function readHandler(
       return ingress.internalErrorResponse(ctx, result)
     }
 
-    const init: ResponseInit = {
-      status: 200,
-      headers: ingress.responseHeaders(
-        result.headerVariant,
-        ctx.requestIdHeader,
-        ctx.origin,
-        result.rateRemaining,
-        result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined,
-      ),
-    }
+    const init = buildSuccessInit(ingress, result, ctx)
 
     return copyBody
       ? new Response(result.bodyJson(true), init)
       : ingress.zeroCopyResponse(result, ctx, init)
   }
 
-  return (req, srv) => ingress.run<Response>(req, resolveIp(req, srv, opts), null, respond)
+  return runBaked(ingress, opts, respond)
 }

package/src/ingress/routes/responder.ts

@@ -0,0 +1,159 @@
+// src/ingress/routes/responder.ts — JS responder bridge over the native
+// pipeline ("native decides, JS formats the 2xx").
+//
+// The responder bridge is the castrum foundation for delegating a WHOLE
+// request to the per-route native `IngressInner` while keeping the 2xx body in
+// JS: the native pipeline runs parse/validate/CORS/rate-limit/limits and either
+// produces a terminal (rejection) response — in the configured envelope style —
+// or hands a decoded snapshot to a `NativeResponder` that builds the 2xx.
+//
+// The sync/async boundary is deliberate: `OptimizedIngressHandler.run()` is
+// SYNC-only (`assertSyncCallback` rejects thenables), so the factory captures
+// the decoded snapshot (requestId/query/cookies/body/verdicts) INSIDE the sync
+// callback and calls the async `responder` OUTSIDE it, after the pooled output
+// buffer has been released. `result.body` is the caller-provided request body
+// (never the pooled output buffer), so the snapshot's `body` is safe to hold.
+
+import { decoder } from '../../shared/bytes'
+import { generateRequestId } from '../../shared/request-id'
+import { readBodyWithLimit } from '../body'
+import type { BakedIngressResult } from '../decode/baked-result'
+import { errorCodeName, errorMessage } from '../errors'
+import type { RouteHandler } from '../server'
+import { DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES } from '../shared'
+import { safeTerminalStatus } from '../status'
+import type {
+  BakedContext,
+  NativeRequestContext,
+  NativeResponder,
+  OptimizedIngressHandler,
+  TerminalStyle,
+} from '../types'
+import { type BakedHandlerOptions, resolveIp } from './common'
+
+/** Options for {@link nativeResponderRoute}. */
+export interface ResponderRouteOptions extends BakedHandlerOptions {
+  /** Terminal envelope style. Default: `'castrum'` (the pre-baked wire). */
+  terminalStyle?: TerminalStyle
+  /**
+   * Read the request body and pass it to the native pipeline for validation
+   * (`requireJsonBody`/schema). Default `false` — the framework owns the body
+   * (the responder reads it via `ctx.body`); native only needs the bytes when
+   * a body stage is enabled in the route's `IngressHandlerOptions`.
+   */
+  readBody?: boolean
+}
+
+/** ignex framework security posture for terminal responses. */
+const IGNGEX_SECURITY_HEADERS: [string, string][] = [
+  ['x-frame-options', 'DENY'],
+  ['x-content-type-options', 'nosniff'],
+  ['referrer-policy', 'no-referrer'],
+]
+
+/** Build the ignex-framework terminal envelope (`{error,status,code}` + security headers). */
+function buildIgngexTerminal(result: BakedIngressResult, _ctx: BakedContext): Response {
+  const preflightAllowed = result.isPreflight && result.corsAllowed
+  if (preflightAllowed) {
+    return new Response(null, { status: 204, headers: IGNGEX_SECURITY_HEADERS })
+  }
+  const status = safeTerminalStatus(result)
+  const body = JSON.stringify({
+    error: errorMessage(status, result.errorCode),
+    status,
+    code: errorCodeName(result.errorCode),
+  })
+  const headers = new Headers(IGNGEX_SECURITY_HEADERS)
+  headers.set('content-type', 'application/json; charset=utf-8')
+  return new Response(body, { status, headers })
+}
+
+/** Parse a `queryJson()`/`cookiesJson()` section into an object (empty on failure). */
+function parseSection(json: string): Record<string, unknown> {
+  try {
+    const v: unknown = JSON.parse(json)
+    return v !== null && typeof v === 'object' && !Array.isArray(v)
+      ? (v as Record<string, unknown>)
+      : {}
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Build a responder route: native pipeline decides + rejects (terminal
+ * response in the chosen style); on success the JS `responder` builds the 2xx.
+ * Returns an async `RouteHandler` (`(req, srv?, params?) => Promise<Response>`).
+ */
+export function nativeResponderRoute(
+  ingress: OptimizedIngressHandler,
+  responder: NativeResponder,
+  opts: ResponderRouteOptions = {},
+): RouteHandler {
+  const terminalStyle: TerminalStyle = opts.terminalStyle ?? 'castrum'
+  const readBody = opts.readBody ?? false
+  const maxBodyBytes = opts.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
+  const bodyTimeoutMs = opts.bodyTimeoutMs ?? DEFAULT_BODY_TIMEOUT_MS
+
+  return async (req, srv, _params) => {
+    const ip = resolveIp(req, srv, opts)
+    // The request-id the framework surfaces (same source as the pre-baked path's
+    // `ctx.requestIdHeader`): the baked result does not carry it, so generate it
+    // here — the native pipeline uses the same rid for its internal frame.
+    const requestId = decoder.decode(generateRequestId())
+    // Read the body ONLY when native validation needs it (the framework owns
+    // the body otherwise). A `BODY_TOO_LARGE`/`REQUEST_TIMEOUT` throw becomes
+    // a terminal 413/408 from the native path.
+    let body: Uint8Array | null = null
+    if (readBody) {
+      try {
+        body = await readBodyWithLimit(req, maxBodyBytes, true, bodyTimeoutMs)
+      } catch (err) {
+        const code = (err as Error & { code?: string }).code
+        const status = code === 'REQUEST_TIMEOUT' ? 408 : code === 'BODY_TOO_LARGE' ? 413 : 400
+        const payload = JSON.stringify({ error: 'Bad Request', status, code: 'BAD_REQUEST' })
+        const headers = new Headers(IGNGEX_SECURITY_HEADERS)
+        headers.set('content-type', 'application/json; charset=utf-8')
+        return new Response(payload, { status, headers })
+      }
+    }
+
+    let terminal: Response | null = null
+    let snapshot: NativeRequestContext | null = null
+
+    // Sync callback (never returns a thenable). Captures the decoded snapshot
+    // or the terminal response, then the async responder runs outside `run()`.
+    ingress.run<null>(req, ip, body, (result, ctx) => {
+      if (result.terminal || !result.ok) {
+        terminal =
+          terminalStyle === 'ignex'
+            ? buildIgngexTerminal(result, ctx)
+            : ingress.terminalResponse(req, result, ctx)
+        return null
+      }
+      const query = parseSection(result.queryJson())
+      const cookies = parseSection(result.cookiesJson())
+      snapshot = {
+        requestId,
+        status: result.status,
+        rateLimited: result.rateLimited,
+        retryAfterMs: result.retryAfterMs,
+        query: query as Record<string, string | string[]>,
+        cookies: cookies as Record<string, string>,
+        body: body ?? new Uint8Array(0),
+        ip,
+        req,
+      }
+      return null
+    })
+
+    if (terminal !== null) {
+      return terminal
+    }
+    if (snapshot === null) {
+      // Native internal error (setInternalError) — the result was never OK.
+      return ingress.internalErrorResponse({ requestIdHeader: null, origin: null })
+    }
+    return responder(snapshot)
+  }
+}

package/src/ingress/server-node.ts

@@ -15,21 +15,20 @@
 
 import {
   createServer,
-  type IncomingMessage,
   type Server as HttpServer,
+  type IncomingMessage,
   type ServerResponse,
 } from 'node:http'
-import { Readable, type Duplex } from 'node:stream'
-
+import { type Duplex, Readable } from 'node:stream'
+import { fallbackHandler } from './routes'
 import {
+  type BakedServer,
   buildPathMatcher,
   buildRouteHandlers,
-  type BakedServer,
   type CreateIngressServerOptions,
-  type ServerHandle,
   type RouteHandler,
+  type ServerHandle,
 } from './server'
-import { fallbackHandler } from './routes'
 
 export type { RouteHandler } from './server'
 
@@ -41,6 +40,7 @@ export type { RouteHandler } from './server'
  * body-read loop after headers arrive.
  */
 const DEFAULT_SOCKET_TIMEOUT_MS = 30_000
+
 import type { BakedHandlerOptions } from './routes/common'
 
 /** A Node.js ingress server: {@link BakedServer} plus an async ready signal. */

package/src/ingress/server.ts

@@ -1,17 +1,18 @@
 // src/ingress/server.ts — Bun.serve builder over pre-baked route handlers.
 
+import { isBun } from '../shared/runtime'
 import {
-  readHandler,
-  headHandler,
-  jsonWriteHandler,
+  deleteHandler,
   echoHandler,
   fallbackHandler,
-  deleteHandler,
+  headHandler,
+  jsonWriteHandler,
   optionsHandler,
+  readHandler,
 } from './routes'
 import type { BakedHandlerOptions } from './routes/common'
-import type { OptimizedIngressHandler } from './types'
-import { isBun } from '../shared/runtime'
+import { nativeResponderRoute } from './routes/responder'
+import type { NativeResponder, OptimizedIngressHandler, TerminalStyle } from './types'
 
 /** Server-level default for the socket request-body cap (16 MiB). */
 export const DEFAULT_MAX_REQUEST_BODY_SIZE = 16 * 1024 * 1024
@@ -45,6 +46,24 @@ export interface BakedRoute {
   cookies?: OptimizedIngressHandler
   /** Wires a DELETE read-style handler. */
   delete?: OptimizedIngressHandler
+  /**
+   * A JS responder route: the native pipeline owns parse/validate/CORS/
+   * rate-limit + terminal rejections; the responder builds the 2xx body
+   * (async OK). Wired for `methods` (default GET). Built by
+   * `nativeResponderRoute` (src/ingress/routes/responder.ts).
+   */
+  responder?: {
+    /** The route's compiled native `IngressInner`. */
+    ingress: OptimizedIngressHandler
+    /** The JS 2xx builder. */
+    handler: NativeResponder
+    /** HTTP methods to wire (default `['GET']`). */
+    methods?: ReadonlyArray<string>
+    /** Terminal envelope style (`'castrum'` default / `'ignex'`). */
+    terminalStyle?: TerminalStyle
+    /** Read the body for native validation (default false — framework owns it). */
+    readBody?: boolean
+  }
   /** Overrides `maxBodyBytes` for this route's write/echo handlers. */
   maxBodyBytes?: number
   /**
@@ -124,6 +143,7 @@ export interface BakedServer {
   port: number
 }
 
+/** Options for `gracefulShutdown` (drain grace period + signals). */
 export interface GracefulShutdownOptions {
   /** Grace period (ms) to drain in-flight requests before force-closing. */
   timeoutMs?: number
@@ -182,13 +202,6 @@ export function gracefulShutdown(
   }
 }
 
-/**
- * Build the route → { method → handler } map from a server spec.
- *
- * Shared by `createIngressServer` (Bun.serve) and `createIngressServerNode`
- * (node:http) so both runtimes wire the exact same route handlers.
- */
-
 /** Options `buildRouteHandlers` actually consumes (a subset of the server
  *  options — it does not need `port` or the Node-only server fields). */
 export type BuildRouteHandlersOptions = Pick<
@@ -196,6 +209,12 @@ export type BuildRouteHandlersOptions = Pick<
   'routes' | 'fallback' | 'getIp' | 'copyBody'
 >
 
+/**
+ * Build the route → { method → handler } map from a server spec.
+ *
+ * Shared by `createIngressServer` (Bun.serve) and `createIngressServerNode`
+ * (node:http) so both runtimes wire the exact same route handlers.
+ */
 export function buildRouteHandlers(options: BuildRouteHandlersOptions): {
   routes: Record<string, Record<string, unknown>>
   baseOpts: BakedHandlerOptions
@@ -249,6 +268,19 @@ export function buildRouteHandlers(options: BuildRouteHandlersOptions): {
       methods.DELETE = deleteHandler(spec.delete, routeOpts)
     }
 
+    if (spec.responder) {
+      // JS responder route: native decides + rejects; JS builds the 2xx.
+      const responderRoute = nativeResponderRoute(spec.responder.ingress, spec.responder.handler, {
+        ...routeOpts,
+        terminalStyle: spec.responder.terminalStyle,
+        readBody: spec.responder.readBody,
+      })
+      const responderMethods = spec.responder.methods ?? ['GET']
+      for (const m of responderMethods) {
+        methods[m] = responderRoute
+      }
+    }
+
     // CORS preflight (OPTIONS) is served for EVERY route with a NATIVE handler
     // (not just write routes with a fallback), so read-only routes also answer
     // preflights with 204/403 from the native pipeline. Raw probe handlers

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 {
@@ -155,3 +155,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