castrum 0.9.1 → 0.9.2

package/src/ingress/path-matcher.ts

@@ -0,0 +1,115 @@
+// src/ingress/path-matcher.ts — `:param` / `*` path matching for pre-baked routes
+//
+// The dynamic-path matcher shared by the Node adapter (server-node.ts) and the
+// router (router.ts). Bun's native router matches dynamic paths itself, so this
+// only runs on Node / route-manager paths. The ingress pipeline does not echo
+// path params in its response, so matching only selects the handler.
+
+/** A matched dynamic route: the handler map + the extracted path params. */
+export interface PathMatch {
+  methods: Record<string, unknown>
+  params: Record<string, string>
+}
+
+interface CompiledDynamicPattern {
+  re: RegExp
+  paramNames: string[]
+  rest: boolean
+  methods: Record<string, unknown>
+  /** Number of literal (static) segments — used to prefer the most specific pattern. */
+  staticSegments: number
+}
+
+/**
+ * Build a path matcher over a route map, supporting `:param` and `*` (rest)
+ * segments. Exact (static) paths always win over dynamic patterns; dynamic
+ * patterns are ordered most-specific-first (most static segments, then fewest
+ * params). Used by `createIngressServerNode` (Bun's native router already
+ * matches dynamic patterns itself). The ingress pipeline does not echo path
+ * params in its response, so matching only selects the handler.
+ *
+ * @param routes the built route map (`path` → `method` → handler)
+ * @returns a matcher: `pathname` → `{ methods, params }` or `undefined`
+ */
+export function buildPathMatcher(
+  routes: Record<string, Record<string, unknown>>,
+): (pathname: string) => PathMatch | undefined {
+  const exact = new Map<string, Record<string, unknown>>()
+  const dynamic: CompiledDynamicPattern[] = []
+
+  for (const [path, methods] of Object.entries(routes)) {
+    const hasParam = path.indexOf(':') !== -1
+    const hasRest = path.indexOf('*') !== -1
+    if (!hasParam && !hasRest) {
+      exact.set(path, methods)
+      continue
+    }
+
+    const paramNames: string[] = []
+    let rest = false
+    let staticSegments = 0
+    const parts = path.split('/').filter((s) => s.length > 0)
+    const source = parts
+      .map((seg) => {
+        if (seg === '*') {
+          rest = true
+          return '(.*)'
+        }
+        if (seg.startsWith(':')) {
+          paramNames.push(seg.slice(1))
+          return '([^/]+)'
+        }
+        staticSegments++
+        return seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      })
+      .join('/')
+
+    dynamic.push({
+      re: new RegExp(`^/${source}${rest ? '' : '/?$'}`),
+      paramNames,
+      rest,
+      methods,
+      staticSegments,
+    })
+  }
+
+  dynamic.sort(
+    (a, b) => b.staticSegments - a.staticSegments || a.paramNames.length - b.paramNames.length,
+  )
+
+  return (pathname: string) => {
+    const exactHit = exact.get(pathname)
+    if (exactHit !== undefined) {
+      return { methods: exactHit, params: {} }
+    }
+    for (const d of dynamic) {
+      const m = d.re.exec(pathname)
+      if (m !== null) {
+        const params: Record<string, string> = {}
+        for (let i = 0; i < d.paramNames.length; i++) {
+          const raw = m[i + 1]
+          if (raw !== undefined) params[d.paramNames[i] ?? ''] = safeDecode(raw)
+        }
+        if (d.rest) {
+          const restRaw = m[d.paramNames.length + 1]
+          if (restRaw !== undefined) params['*'] = safeDecode(restRaw)
+        }
+        return { methods: d.methods, params }
+      }
+    }
+    return undefined
+  }
+}
+
+/**
+ * Percent-decode a matched path segment, tolerating malformed escapes: a bad
+ * `%` sequence is returned raw rather than throwing, so the matcher never
+ * rejects a request over a decode error.
+ */
+export function safeDecode(value: string): string {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}

package/src/ingress/response/baked-response.ts

@@ -0,0 +1,302 @@
+// src/ingress/response/baked-response.ts — pre-baked response builders (path 2)
+//
+// The seven response-builder methods of `OptimizedIngressHandler`, extracted
+// from createIngressHandler (handlers.ts) so the factory stays focused on
+// packing + pooling. Mirrors fast.ts's response/terminal.ts split — but emits
+// the BENCH wire format (`{"ok":false,"error":{...}}` + `ratelimit-*` headers),
+// NOT the fast path's `x-ratelimit-*` shape (see AGENTS.md — do not unify).
+//
+// The builders are bound to a handler's configuration (header templates,
+// request-id emission, CORS cache) plus a shared mutable `BakedResponseState`
+// that `run()` in handlers.ts owns: `zeroCopyResponse` marks the pooled
+// output buffer as borrowed so `run()` does not release it before the body is
+// consumed.
+
+import type { PooledBuffer } from '../../shared/buffer-pool'
+import { encoder } from '../../shared/bytes'
+import { pooledBodyResponse } from '../../shared/response'
+import {
+  ERR_CODE_RATE_LIMITED as ERROR_CODE_RATE_LIMITED,
+  HV_CORS_PREFLIGHT,
+  HV_CORS_SIMPLE,
+  HV_JSON,
+  HV_RATE_ACTIVE,
+  HV_RATE_LIMITED,
+} from '../constants'
+import type { BakedIngressResult } from '../decode/baked-result'
+import { secondsFromMs } from '../shared'
+import { safeTerminalStatus } from '../status'
+import type { BakedContext, OptimizedIngressHandler } from '../types'
+import { ERROR_BODIES, ERROR_CODE_BODIES, rateLimitedBody } from './error-bodies'
+
+const EMPTY_BODY = new Uint8Array(0)
+
+/** Shared per-request state between `run()` (handlers.ts) and the builders. */
+export interface BakedResponseState {
+  /** The pooled output buffer backing the current `run()` (null outside one). */
+  currentHandle: PooledBuffer | null
+  /** True when a zero-copy Response claimed the buffer (run() must not release). */
+  responseBorrowsBuffer: boolean
+}
+
+/** Configuration the builder factory needs from a handler. */
+export interface BakedResponseBuildersDeps {
+  /** Variant-indexed pre-baked header templates (regular responses). */
+  headerTemplates: ReadonlyArray<ReadonlyArray<[string, string]>>
+  /** Variant-indexed pre-baked terminal templates (JSON + no-store). */
+  terminalTemplates: ReadonlyArray<ReadonlyArray<[string, string]>>
+  /** Emit an `x-request-id` header on responses. */
+  emitRequestIdHeader: boolean
+  /** Abandonment guard (ms) for zero-copy responses. */
+  zeroCopyTimeoutMs: number
+  /** Cache of Origin-augmented header arrays keyed by `variant\u0000origin`. */
+  originHeaderCache: Map<string, [string, string][]>
+  /** Shared per-request state (owned by `run()` in handlers.ts). */
+  state: BakedResponseState
+}
+
+/**
+ * Build the seven response-builder methods of `OptimizedIngressHandler`
+ * (everything except `run`), bound to this handler's header templates and
+ * request-id policy. The returned methods are the exact bodies that lived in
+ * `createIngressHandler`.
+ */
+export function buildBakedResponseBuilders(
+  deps: BakedResponseBuildersDeps,
+): Omit<OptimizedIngressHandler, 'run'> {
+  const {
+    headerTemplates,
+    terminalTemplates,
+    emitRequestIdHeader,
+    zeroCopyTimeoutMs,
+    originHeaderCache,
+    state,
+  } = deps
+
+  function responseHeaders(
+    variant: number,
+    requestIdHeader: string | null,
+    origin: string | null,
+    rateRemaining?: number,
+    rateResetSecs?: number,
+    retryAfterSecs?: number,
+  ): [string, string][] {
+    const template: ReadonlyArray<[string, string]> =
+      headerTemplates[variant & 31] ?? headerTemplates[0] ?? []
+
+    const needsRequestId = emitRequestIdHeader && requestIdHeader !== null
+    const needsOrigin =
+      ((variant & HV_CORS_SIMPLE) !== 0 || (variant & HV_CORS_PREFLIGHT) !== 0) && origin !== null
+    const needsRate = (variant & HV_RATE_ACTIVE) !== 0
+    const needsRetry = (variant & HV_RATE_LIMITED) !== 0
+
+    if (!needsRequestId && !needsOrigin && !needsRate && !needsRetry) {
+      // Frozen-readonly → mutable: callers only ever read the baked template
+      // (zero-copy steady-state path), so the widening is safe in practice.
+      return template as unknown as [string, string][]
+    }
+
+    if (!needsRequestId && !needsRate && !needsRetry && needsOrigin) {
+      // Steady-state CORS: only the origin varies — cache the augmented array
+      // per (variant, origin) so the Origin-present case (the common
+      // browser/bench case) stays allocation-free after the first hit for EACH
+      // distinct origin (a single-slot memo thrashed when clients alternate
+      // between allowed origins, allocating a fresh array on every switch).
+      const key = `${variant & 31}\u0000${origin as string}`
+      const cached = originHeaderCache.get(key)
+      if (cached !== undefined) {
+        return cached
+      }
+      const entries = new Array<[string, string]>(template.length + 1)
+      let i = 0
+      for (const pair of template) {
+        entries[i++] = pair
+      }
+      entries[i] = ['access-control-allow-origin', origin as string]
+      originHeaderCache.set(key, entries)
+      return entries
+    }
+
+    let extra = 0
+    if (needsRequestId) extra++
+    if (needsOrigin) extra++
+    if (needsRate) extra += 2
+    if (needsRetry) extra++
+
+    const entries = new Array<[string, string]>(template.length + extra)
+    let i = 0
+
+    for (const pair of template) {
+      entries[i++] = pair
+    }
+
+    if (needsRequestId) {
+      entries[i++] = ['x-request-id', requestIdHeader as string]
+    }
+
+    if (needsOrigin) {
+      entries[i++] = ['access-control-allow-origin', origin as string]
+    }
+
+    if (needsRate) {
+      entries[i++] = ['ratelimit-remaining', String(rateRemaining ?? 0)]
+      entries[i++] = ['ratelimit-reset', String(rateResetSecs ?? 0)]
+    }
+
+    if (needsRetry) {
+      entries[i++] = ['retry-after', String(retryAfterSecs ?? 0)]
+    }
+
+    return entries
+  }
+
+  function terminalHeaders(
+    variant: number,
+    ctx: BakedContext,
+    result: BakedIngressResult | null,
+  ): [string, string][] {
+    const v = variant | HV_JSON
+    const requestIdHeader = ctx.requestIdHeader
+    const origin = ctx.origin
+    const rateResetSecs =
+      result && result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined
+    const retryAfterSecs =
+      result && result.retryAfterMs > 0 ? secondsFromMs(result.retryAfterMs) : undefined
+
+    const needsRequestId = emitRequestIdHeader && requestIdHeader !== null
+    const needsOrigin =
+      ((v & HV_CORS_SIMPLE) !== 0 || (v & HV_CORS_PREFLIGHT) !== 0) && origin !== null
+    const needsRate = (v & HV_RATE_ACTIVE) !== 0
+    const needsRetry = (v & HV_RATE_LIMITED) !== 0
+
+    // Steady state: no request-id/origin/rate extras — serve the pre-baked
+    // terminal template (JSON + `cache-control: no-store`) directly with zero
+    // per-response array allocation/copy.
+    if (!needsRequestId && !needsOrigin && !needsRate && !needsRetry) {
+      // Frozen-readonly → mutable: the baked terminal template is only read.
+      return terminalTemplates[v & 31] as unknown as [string, string][]
+    }
+
+    // Rare path: extras appended after the baked entries, then `cache-control`.
+    const base = responseHeaders(
+      v,
+      requestIdHeader,
+      origin,
+      result?.rateRemaining,
+      rateResetSecs,
+      retryAfterSecs,
+    )
+
+    const out = new Array<[string, string]>(base.length + 1)
+    let i = 0
+    for (const pair of base) {
+      out[i++] = pair
+    }
+    out[base.length] = ['cache-control', 'no-store']
+    return out
+  }
+
+  function terminalResponse(
+    _req: Request | undefined,
+    result: BakedIngressResult,
+    ctx: BakedContext,
+  ): Response | null {
+    if (!result.terminal) {
+      return null
+    }
+
+    const preflightAllowed = result.isPreflight && result.corsAllowed
+
+    if (preflightAllowed) {
+      return new Response(null, {
+        status: 204,
+        headers: responseHeaders(
+          result.headerVariant,
+          ctx.requestIdHeader,
+          ctx.origin,
+          result.rateRemaining,
+          result.rateResetMs > 0 ? secondsFromMs(result.rateResetMs) : undefined,
+          result.retryAfterMs > 0 ? secondsFromMs(result.retryAfterMs) : undefined,
+        ),
+      })
+    }
+
+    const status = safeTerminalStatus(result)
+
+    const body: Uint8Array =
+      result.errorCode === ERROR_CODE_RATE_LIMITED
+        ? rateLimitedBody(result.retryAfterMs)
+        : (ERROR_CODE_BODIES[result.errorCode] ?? ERROR_BODIES.internal ?? EMPTY_BODY)
+
+    return new Response(body, {
+      status,
+      headers: terminalHeaders(result.headerVariant, ctx, result),
+    })
+  }
+
+  function errorResponse(
+    _req: Request | undefined,
+    result: BakedIngressResult | null,
+    status: number,
+    code: string,
+    message: string,
+    ctx: BakedContext,
+  ): Response {
+    const body =
+      ERROR_BODIES[code] ?? encoder.encode(JSON.stringify({ ok: false, error: { code, message } }))
+
+    return new Response(body, {
+      status,
+      headers: terminalHeaders(result?.headerVariant ?? HV_JSON, ctx, result),
+    })
+  }
+
+  function internalErrorResponse(ctx: BakedContext, result?: BakedIngressResult): Response {
+    return new Response(ERROR_BODIES.internal, {
+      status: 500,
+      headers: terminalHeaders(result?.headerVariant ?? HV_JSON, ctx, result ?? null),
+    })
+  }
+
+  function withContentType(
+    headers: ReadonlyArray<[string, string]>,
+    contentType: string,
+  ): [string, string][] {
+    const out = new Array<[string, string]>(headers.length + 1)
+    let i = 0
+    for (const pair of headers) {
+      out[i++] = pair
+    }
+    out[headers.length] = ['content-type', contentType]
+    return out
+  }
+
+  function zeroCopyResponse(
+    result: BakedIngressResult,
+    _ctx: BakedContext,
+    init: ResponseInit,
+  ): Response {
+    if (state.currentHandle === null) {
+      // `zeroCopyResponse` must only run inside a live `run()` callback (a
+      // pooled output buffer must be in flight). Called outside `run()` the
+      // result has already been invalidated and `result.bodyJson` is empty —
+      // throw instead of silently serving an empty body.
+      throw new Error(
+        'zeroCopyResponse() can only be called from within a run() callback ' +
+          '(the pooled output buffer is only live during run()).',
+      )
+    }
+    state.responseBorrowsBuffer = true
+    return pooledBodyResponse(state.currentHandle, result.bodyJson(false), init, zeroCopyTimeoutMs)
+  }
+
+  return {
+    responseHeaders,
+    terminalHeaders,
+    terminalResponse,
+    errorResponse,
+    internalErrorResponse,
+    withContentType,
+    zeroCopyResponse,
+  }
+}

package/src/ingress/router.ts

@@ -23,9 +23,12 @@
 
 import type { BakedIngressResult } from './decode/baked-result'
 import { type BakedIngressRuntime, createIngressHandler } from './handlers'
+import type { NativeRoutePlan } from './native-route'
 import type { IngressHandlerOptions } from './options'
-import type { BakedRoute, PathMatch, RouteHandler } from './server'
-import { buildPathMatcher, buildRouteHandlers } from './server'
+import type { PathMatch } from './path-matcher'
+import { buildPathMatcher } from './path-matcher'
+import type { BakedRoute, RouteHandler } from './server'
+import { buildRouteHandlers } from './server'
 import type { BakedContext, NativeResponder, OptimizedIngressHandler, TerminalStyle } from './types'
 
 /** Per-route spec for {@link createIngressRouter}. */
@@ -60,6 +63,28 @@ export interface RouterRouteSpec {
     /** Read the body for native validation (default false — framework owns it). */
     readBody?: boolean
   }
+  /**
+   * A LEAN native-stack responder route: the route-wire v3 per-route stack
+   * (`createNativeRoute` over `castrum_route_*`) runs ONLY the stages in
+   * `plan` (parseQuery/parseCookies/requireJsonBody/validateBody) in ONE
+   * native call — no CORS/rate-limit/security/IP/metadata envelope. On a
+   * verdict failure the route rejects (400 non-JSON / 422 schema); on success
+   * the responder builds the 2xx from the decoded snapshot. Measured ~580ns
+   * cheaper per request than the full-pipeline responder on a
+   * parseQuery+parseCookies route (bench/cost/native-route-vs-router.ts).
+   * Wired for `methods` (default `['GET']`). When set, `read`/`write`/etc.
+   * for this route are ignored.
+   */
+  native?: {
+    /** The route-wire v3 plan (parse/validate stages + limits). */
+    plan: NativeRoutePlan
+    /** The JS 2xx builder (receives the decoded query/cookies/body snapshot). */
+    handler: NativeResponder
+    /** HTTP methods to wire (default `['GET']`). */
+    methods?: ReadonlyArray<string>
+    /** Read the body for `requireJsonBody`/`validateBody` (default false). */
+    readBody?: boolean
+  }
   /** Terminal envelope style for this route's responder (default: router-level
    *  `terminalStyle` or `'castrum'`). */
   terminalStyle?: TerminalStyle
@@ -155,6 +180,21 @@ export function createIngressRouter(options: CreateIngressRouterOptions): Ingres
       bakedRoutes[path] = { read: spec.raw as RouteHandler }
       continue
     }
+    if (spec.native) {
+      // LEAN native-stack responder route: the route-wire v3 stack runs ONLY
+      // the plan's stages (no full IngressInner, no CORS/rate-limit/security).
+      bakedRoutes[path] = {
+        native: {
+          plan: spec.native.plan,
+          handler: spec.native.handler,
+          methods: spec.native.methods,
+          readBody: spec.native.readBody,
+        },
+        maxBodyBytes: spec.maxBodyBytes,
+        bodyTimeoutMs: spec.bodyTimeoutMs,
+      }
+      continue
+    }
     // Compile a dedicated native instance for this route's options.
     const handler = createIngressHandler(spec.options ?? {}, runtime)
     compiled[path] = handler

package/src/ingress/routes/common.ts

@@ -1,8 +1,8 @@
 // src/ingress/routes/common.ts — Shared route-handler options + helpers.
 
-import type { BakedContext, OptimizedIngressHandler } from '../types'
 import type { BakedIngressResult } from '../decode/baked-result'
 import { secondsFromMs } from '../shared'
+import type { BakedContext, OptimizedIngressHandler } from '../types'
 
 /** Options accepted by the pre-baked route factories. */
 export interface BakedHandlerOptions {
@@ -20,6 +20,14 @@ export interface BakedHandlerOptions {
   bodyTimeoutMs?: number
   /** Fallback handler used for write error paths. Defaults to the write ingress. */
   fallback?: OptimizedIngressHandler
+  /**
+   * Zero-DOM JSON-validity check for the write-route fallback validation
+   * (`jsonWriteHandler` when neither `requireJsonBody` nor a `schema` is
+   * configured). Injected so the pure route factories never import the native
+   * layer (dependency injection across the purity boundary). Defaults to the
+   * `ingress.jsonValid` capability that `createIngressHandler` provides.
+   */
+  jsonValid?: (bytes: Uint8Array) => boolean
   /**
    * When true, route the JSON-validity fallback check through the higher-order
    * loader (`loader("jsonValid")`) instead of the direct native call —

package/src/ingress/routes/json-write.ts

@@ -1,27 +1,26 @@
 // src/ingress/routes/json-write.ts — Pre-baked JSON-write handler
 // (POST/PUT/PATCH).
 
-import type { OptimizedIngressHandler } from '../types'
-import { buildSuccessInit, resolveIp, type BakedHandlerOptions } from './common'
-import { DEFAULT_MAX_BODY_BYTES, DEFAULT_BODY_TIMEOUT_MS } from '../shared'
+import { decodeUtf8 } from '../../shared/codec'
 import { readBodyWithLimit } from '../body'
-import { getAddon } from '../../native'
-import { getBunFFI } from '../../native/ffi'
+import { DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES } from '../shared'
+import type { OptimizedIngressHandler } from '../types'
+import { type BakedHandlerOptions, buildSuccessInit, resolveIp } from './common'
 
 /**
- * Zero-DOM JSON-validity check — the same native fast path the ingress
- * pipeline uses internally (`json_valid_bytes`).
- *
- * Used by `jsonWriteHandler` as a fallback when the pipeline skipped JSON
- * validation because neither `requireJsonBody` nor a `schema` is configured
- * on the ingress (see the `bodyValidJson` handling in the route).
- *
- * bun:ffi is primary on Bun; the napi addon is the fallback (Node, forced
- * `CASTRUM_FFI_MODE=napi`, or a failed ffi self-test).
+ * Pure JSON-validity fallback used ONLY for hand-rolled
+ * `OptimizedIngressHandler` mocks that carry no native `jsonValid` capability.
+ * Real handlers from `createIngressHandler` always provide the zero-DOM native
+ * check (`ingress.jsonValid`), so this never runs on the hot path — it exists
+ * to keep the security property (invalid JSON must be rejected) for mocks.
  */
-function isValidJsonBytes(bytes: Uint8Array): boolean {
-  const ffi = getBunFFI()
-  return ffi ? ffi.jsonValid(bytes) : getAddon().jsonValid(bytes)
+function defaultJsonValid(bytes: Uint8Array): boolean {
+  try {
+    JSON.parse(decodeUtf8(bytes))
+    return true
+  } catch {
+    return false
+  }
 }
 
 /**
@@ -39,6 +38,10 @@ export function jsonWriteHandler(
   // Non-zero default: protect against slowloris / trickling bodies. Set
   // `bodyTimeoutMs: 0` to disable.
   const bodyTimeoutMs = opts.bodyTimeoutMs ?? DEFAULT_BODY_TIMEOUT_MS
+  // JSON-validity check via DI across the purity boundary: an explicit option
+  // wins, otherwise the handler's own native capability (from
+  // `createIngressHandler`), otherwise the pure mock fallback.
+  const jsonValid = opts.jsonValid ?? ingress.jsonValid ?? defaultJsonValid
 
   return async (req, srv) => {
     const ip = resolveIp(req, srv, opts)
@@ -115,7 +118,7 @@ export function jsonWriteHandler(
             ctx,
           )
         }
-      } else if (!isValidJsonBytes(bodyBytes)) {
+      } else if (!jsonValid(bodyBytes)) {
         return ingress.errorResponse(req, result, 400, 'invalid_json', 'Invalid JSON body', ctx)
       }