castrum 0.9.1 → 0.9.3

package/src/ingress/routes/native.ts

@@ -0,0 +1,130 @@
+// src/ingress/routes/native.ts — lean per-route native-stack route factory.
+//
+// A `RouteHandler` backed by the route-wire v3 stack (`createNativeRoute`)
+// instead of the full 8-stage `IngressInner`: the native side runs ONLY the
+// stages the plan compiled (parseQuery/parseCookies/requireJsonBody/
+// validateBody) and returns a packed verdict + pair sections; the responder
+// builds the 2xx from the decoded snapshot. This is the leanest per-request
+// path — measured `bench/cost/native-route-vs-router.ts`: ~551ns full JS-glue
+// path vs ~1131ns router `run()` on a parseQuery+parseCookies route (−580ns).
+//
+// PURE: the compiled `NativeRoute` is injected (dependency injection across
+// the purity boundary) — this factory never touches the dlopen layer itself;
+// the impure `createNativeRoute(plan)` call happens in the boundary
+// (`router.ts` / `server.ts` `buildRouteHandlers`).
+//
+// Trade-off (deliberate): the native route stack does NOT do CORS, rate
+// limiting, security headers, IP trust, or the castrum metadata envelope — a
+// route that needs those must use the full pipeline (`readHandler` /
+// `nativeResponderRoute`). This factory is for routes where the framework
+// owns the response body and only needs parse + verdict.
+
+import { decoder } from '../../shared/bytes'
+import { generateRequestId } from '../../shared/request-id'
+import { readBodyWithLimit } from '../body'
+import type { NativeRoute } from '../native-route'
+import type { RouteHandler } from '../server'
+import { DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES } from '../shared'
+import type { NativeRequestContext, NativeResponder } from '../types'
+import type { BakedHandlerOptions } from './common'
+import { resolveIp } from './common'
+
+/** Options for {@link nativeRouteHandler}. */
+export interface NativeRouteHandlerOptions extends BakedHandlerOptions {
+  /** Read the request body and pass it for `requireJsonBody`/`validateBody`. */
+  readBody?: boolean
+}
+
+/** The `+`-to-space / `%XX` decoding is done natively; keys are last-wins. */
+function pairsToRecord(pairs: ReadonlyArray<[string, string]>): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [k, v] of pairs) out[k] = v
+  return out
+}
+
+/**
+ * Build a lean native-stack route handler over a COMPILED route (injected —
+ * compile via `createNativeRoute` in the boundary, then pass the route here).
+ *
+ * Terminal verdicts (`errorCode !== 0`) become JSON rejections: 400 for
+ * `requireJsonBody` (missing / non-JSON body), 422 for `validateBody` schema
+ * failure. On success the responder builds the 2xx from the snapshot.
+ *
+ * @example
+ * ```ts
+ * const route = createNativeRoute({ parseQuery: true, parseCookies: true })
+ * const handler = nativeRouteHandler(route, (snap) =>
+ *   Response.json({ ok: true, query: snap.query, cookies: snap.cookies }),
+ * )
+ * ```
+ */
+export function nativeRouteHandler(
+  route: NativeRoute,
+  responder: NativeResponder,
+  opts: NativeRouteHandlerOptions = {},
+): RouteHandler {
+  const readBody = opts.readBody ?? false
+  const maxBodyBytes = opts.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
+  const bodyTimeoutMs = opts.bodyTimeoutMs ?? DEFAULT_BODY_TIMEOUT_MS
+  const parseQuery = route.parseQuery
+  const parseCookies = route.parseCookies
+
+  const terminal = (status: number, code: string, message: string): Response =>
+    Response.json(
+      { ok: false, error: { code, message } },
+      { status, headers: { 'content-type': 'application/json' } },
+    )
+
+  return async (req, srv, _params) => {
+    const ip = resolveIp(req, srv, opts)
+    const requestId = decoder.decode(generateRequestId())
+
+    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
+        return terminal(status, 'BAD_REQUEST', 'Request body read failed')
+      }
+    }
+
+    // Extract the query substring + Cookie header (the only request inputs the
+    // native stack reads) and run the tiny frame in ONE native call.
+    const url = req.url
+    const qIndex = url.indexOf('?')
+    const queryStr = qIndex >= 0 ? url.slice(qIndex + 1) : ''
+    const cookieStr = req.headers.get('cookie') ?? ''
+
+    let result
+    try {
+      result = route.run(queryStr, cookieStr, body)
+    } catch {
+      return terminal(500, 'INTERNAL', 'Native route run failed')
+    }
+
+    if (result.errorCode !== 0) {
+      if (result.errorCode === 400) {
+        return terminal(400, 'INVALID_JSON', 'Request body must be valid JSON')
+      }
+      if (result.errorCode === 422) {
+        return terminal(422, 'VALIDATION_FAILED', 'Request body failed schema validation')
+      }
+      return terminal(400, 'BAD_REQUEST', 'Bad request')
+    }
+
+    const snapshot: NativeRequestContext = {
+      requestId,
+      status: 200,
+      rateLimited: false,
+      retryAfterMs: 0,
+      query: parseQuery ? pairsToRecord(result.query) : {},
+      cookies: parseCookies ? pairsToRecord(result.cookie) : {},
+      body: body ?? new Uint8Array(0),
+      ip,
+      req,
+    }
+    return responder(snapshot)
+  }
+}

package/src/ingress/server-node.ts

@@ -20,10 +20,10 @@ import {
   type ServerResponse,
 } from 'node:http'
 import { type Duplex, Readable } from 'node:stream'
+import { buildPathMatcher } from './path-matcher'
 import { fallbackHandler } from './routes'
 import {
   type BakedServer,
-  buildPathMatcher,
   buildRouteHandlers,
   type CreateIngressServerOptions,
   type RouteHandler,

package/src/ingress/server.ts

@@ -11,7 +11,10 @@ import {
   readHandler,
 } from './routes'
 import type { BakedHandlerOptions } from './routes/common'
+import { nativeRouteHandler } from './routes/native'
 import { nativeResponderRoute } from './routes/responder'
+import { createNativeRoute } from './native-route'
+import type { NativeRoutePlan } from './native-route'
 import type { NativeResponder, OptimizedIngressHandler, TerminalStyle } from './types'
 
 /** Server-level default for the socket request-body cap (16 MiB). */
@@ -64,6 +67,22 @@ export interface BakedRoute {
     /** 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`) runs ONLY the plan's stages in ONE native call —
+   * no CORS/rate-limit/security/IP/metadata envelope. Wired for `methods`
+   * (default GET) by `nativeRouteHandler` (src/ingress/routes/native.ts).
+   */
+  native?: {
+    /** The route-wire v3 plan (parse/validate stages + limits). */
+    plan: NativeRoutePlan
+    /** The JS 2xx builder. */
+    handler: NativeResponder
+    /** HTTP methods to wire (default `['GET']`). */
+    methods?: ReadonlyArray<string>
+    /** Read the body for `requireJsonBody`/`validateBody` (default false). */
+    readBody?: boolean
+  }
   /** Overrides `maxBodyBytes` for this route's write/echo handlers. */
   maxBodyBytes?: number
   /**
@@ -281,6 +300,20 @@ export function buildRouteHandlers(options: BuildRouteHandlersOptions): {
       }
     }
 
+    if (spec.native) {
+      // LEAN native-stack responder route: route-wire v3 stack, no envelope.
+      // The compiled route is injected into the pure route factory (DI across
+      // the purity boundary — the compile touches the dlopen layer here).
+      const nativeRoute = nativeRouteHandler(createNativeRoute(spec.native.plan), spec.native.handler, {
+        ...routeOpts,
+        readBody: spec.native.readBody,
+      })
+      const nativeMethods = spec.native.methods ?? ['GET']
+      for (const m of nativeMethods) {
+        methods[m] = nativeRoute
+      }
+    }
+
     // 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
@@ -301,106 +334,12 @@ export function buildRouteHandlers(options: BuildRouteHandlersOptions): {
   return { routes: serverRoutes, baseOpts }
 }
 
-/** A matched dynamic route: the handler map + the extracted path params. */
-export interface PathMatch {
-  methods: Record<string, unknown>
-  params: Record<string, string>
-}
+// ── Path matching (shared with server-node.ts + router.ts) ─────────
+// `buildPathMatcher` / `PathMatch` / `safeDecode` live in path-matcher.ts;
+// re-exported here for back-compat (they were historically exported from this
+// module).
 
-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.
- */
-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
-  }
-}
-
-function safeDecode(value: string): string {
-  try {
-    return decodeURIComponent(value)
-  } catch {
-    return value
-  }
-}
+export { buildPathMatcher, type PathMatch, safeDecode } from './path-matcher'
 
 /** Typed options forwarded to `Bun.serve`. */
 interface BunServerOptions {

package/src/ingress/sync.ts

@@ -0,0 +1,151 @@
+// src/ingress/sync.ts — Sync + async convenience factories (path 1 wrappers)
+//
+// `createIngressSync` and `createIngress` wrap `createIngressFast` (path 1)
+// with the synchronous-callback guard / automatic body reading + error
+// contexts. Kept OUT of index.ts so the public barrel stays a pure re-export
+// hub. Runtime/server selection lives in src/runtime/server.ts — NOT here.
+
+import { decoder } from '../shared/bytes'
+import { generateRequestId } from '../shared/request-id'
+import { readRequestBodyOnce } from './body'
+import { ERR_CODE_BODY_TOO_LARGE, ERR_CODE_REQUEST_TIMEOUT } from './constants'
+import { internalContext, snapshotResult, syntheticContext } from './context'
+import { createIngressFast } from './fast'
+import { buildResponseContext } from './headers/fast-templates'
+import { buildTerminalResponse } from './response/terminal'
+import { assertSyncCallback, DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES } from './shared'
+import type { IngressContext, IngressHandler, IngressOptions, SyncIngressHandler } from './types'
+
+/**
+ * Synchronous convenience wrapper over `createIngressFast` (path 1).
+ *
+ * The callback runs on the fast-path result and MUST be synchronous. Use
+ * {@link createIngress} when you want automatic body reading + error contexts.
+ *
+ * @param options fast-path ingress options
+ * @returns a sync handler (callback must be synchronous)
+ */
+export function createIngressSync(options: IngressOptions = {}): SyncIngressHandler {
+  const fast = createIngressFast(options)
+
+  return {
+    run(req, ip, body, requestId, fn) {
+      return fast.run(req, ip, body, requestId, (result) => {
+        const out = fn(result)
+        assertSyncCallback(out, 'createIngressSync().run()')
+        return out
+      })
+    },
+  }
+}
+
+/**
+ * Return a copy of `options` without the security-header keys.
+ *
+ * `createIngress` applies security headers itself (via `buildResponseContext`),
+ * so they must not be forwarded to the underlying fast handler, which rejects
+ * them (see `createIngressFast`).
+ */
+function stripSecurityOptions(options: IngressOptions): IngressOptions {
+  const copy = { ...options }
+  delete copy.security
+  delete copy.enableSecurityHeaders
+  return copy
+}
+
+/**
+ * Async ingress factory: reads the request body (size guard + deadline) and
+ * returns a snapshot `IngressContext` with a terminal `Response`.
+ *
+ * Recommended default for serverless/edge-style `fetch` handlers. For maximum
+ * throughput use `createIngressFast` / `createIngressSync` directly.
+ *
+ * @param options fast-path ingress options (security applied here, not forwarded)
+ * @returns an async handler returning a snapshot context
+ */
+export function createIngress(options: IngressOptions = {}): IngressHandler {
+  const sync = createIngressSync(stripSecurityOptions(options))
+
+  const guard = options.enableBodySizeGuard !== false
+  const max = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
+  const bodyTimeoutMs = options.bodyTimeoutMs ?? DEFAULT_BODY_TIMEOUT_MS
+
+  const wantsBody =
+    options.readBody === true ||
+    options.requireJsonBody === true ||
+    options.schema != null ||
+    (options.readBody !== false && guard)
+
+  const responseCtx = buildResponseContext(options)
+
+  return async function ingressAsync(req: Request, ip?: string): Promise<IngressContext> {
+    const requestId = options.enableRequestIds === false ? '' : decoder.decode(generateRequestId())
+    options.onRequest?.(req, requestId, ip)
+
+    // Every terminal outcome (success, 413, 408, 500) flows through here so a
+    // hook consumer sees exactly one onResponse per request.
+    const emitResponse = (context: IngressContext): IngressContext => {
+      options.onResponse?.(req, context, context.status, requestId)
+      return context
+    }
+
+    try {
+      if (guard) {
+        const rawLen = req.headers.get('content-length')
+        const contentLength = Number(rawLen ?? '0')
+
+        if (Number.isFinite(contentLength) && contentLength > max) {
+          return emitResponse(
+            syntheticContext(req, requestId, options, responseCtx, 413, ERR_CODE_BODY_TOO_LARGE),
+          )
+        }
+      }
+
+      let body: Uint8Array | null = null
+
+      if (wantsBody && req.body !== null) {
+        try {
+          body = await readRequestBodyOnce(req, max, guard, bodyTimeoutMs)
+        } catch (err) {
+          const code = (err as { code?: string } | null)?.code
+
+          if (code === 'BODY_TOO_LARGE') {
+            return emitResponse(
+              syntheticContext(req, requestId, options, responseCtx, 413, ERR_CODE_BODY_TOO_LARGE),
+            )
+          }
+
+          if (code === 'REQUEST_TIMEOUT') {
+            // Match the pre-baked route factories: a body-read deadline is a
+            // 408, not a 500 (was silently swallowed as 500 before).
+            return emitResponse(
+              syntheticContext(req, requestId, options, responseCtx, 408, ERR_CODE_REQUEST_TIMEOUT),
+            )
+          }
+
+          // Unknown body-read failure: surface to onError, then fall through
+          // to the internal-error context below.
+          options.onError?.(err instanceof Error ? err : new Error(String(err)))
+          throw err
+        }
+      }
+
+      return emitResponse(
+        sync.run(req, ip, body, requestId, (r) => {
+          const snapshot = snapshotResult(r)
+          const response = buildTerminalResponse(responseCtx, snapshot, req, requestId)
+
+          return {
+            ...snapshot,
+            response,
+          }
+        }),
+      )
+    } catch (err) {
+      // Native/other failures: never silent — report to onError and emit a
+      // structured 500 context so the request still completes observably.
+      options.onError?.(err instanceof Error ? err : new Error(String(err)))
+      return emitResponse(internalContext(req, requestId, options, responseCtx))
+    }
+  }
+}

package/src/ingress/types.ts

@@ -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