castrum 0.9.0 → 0.9.1

package/src/ingress/body.ts

@@ -1,8 +1,50 @@
 // src/ingress/body.ts — Streaming request-body reading for the async ingress
 // API.
 
+import { isBun } from '../shared/runtime'
+
 const EMPTY_BODY = new Uint8Array(0)
 
+/**
+ * Read the request body as bytes. Bun's `req.bytes()` returns a `Uint8Array`
+ * directly (no `ArrayBuffer` → view wrapper and no copy) — feature-detected so
+ * Node (which lacks `Response.bytes()` on some versions) falls back to
+ * `arrayBuffer()` + a zero-copy view. This is the hot-path body read for every
+ * write route.
+ */
+async function readBodyBytes(req: Request): Promise<Uint8Array> {
+  const bytes = (req as { bytes?: () => Promise<Uint8Array> }).bytes
+  if (typeof bytes === 'function') {
+    return bytes.call(req)
+  }
+  return new Uint8Array(await req.arrayBuffer())
+}
+
+/**
+ * Bun-only synchronous peek of an already-buffered body.
+ *
+ * Under Bun a body fully received during HTTP parsing resolves `req.bytes()`
+ * IMMEDIATELY — `Bun.peek` hands back the `Uint8Array` without awaiting, so a
+ * declared-Content-Length write route can read the body with no deadline race,
+ * no watchdog entry and no microtask turn (the common small-body case).
+ *
+ * Returns:
+ * - `{ bytes }` — already buffered; the caller reads it synchronously and
+ *   must NOT pay the deadline race (the body is already here).
+ * - `Promise<Uint8Array>` — the read is still pending (slow/trickling body);
+ *   the caller MUST still enforce its deadline against this promise.
+ * - `false` — no `req.bytes()` on this runtime (Node); the caller falls back
+ *   to the async `readBodyBytes` + race as before.
+ */
+function peekBufferedBody(req: Request): { bytes: Uint8Array } | Promise<Uint8Array> | false {
+  const bytes = (req as { bytes?: () => Promise<Uint8Array> }).bytes
+  if (typeof bytes !== 'function') return false
+  const pending = bytes.call(req)
+  if (!isBun()) return pending
+  const peeked = Bun.peek(pending)
+  return peeked instanceof Promise ? peeked : { bytes: peeked }
+}
+
 /** Read the request body once, enforcing the size guard when enabled. */
 export function readRequestBodyOnce(
   req: Request,
@@ -23,6 +65,77 @@ function bodyTooLargeError(): Error & { code?: string } {
   return err
 }
 
+// ── Shared body-read deadline watchdog ──────────────────────────────────────
+// One interval timer sweeps ALL in-flight body reads that carry a deadline,
+// replacing a per-request `setTimeout` + `clearTimeout` + `timer.unref` on
+// every write-route body read (that per-request timer alloc is measurable in
+// the POST micro-bench — ~800ns of the ~2.3µs body read). Abort semantics are
+// unchanged: a read that outlives its deadline rejects with REQUEST_TIMEOUT.
+// Entries are removed on completion or when the deadline fires; the interval
+// only runs while at least one read is pending.
+const bodyWatchdog = (() => {
+  const inflight = new Set<WatchdogEntry>()
+  let timer: ReturnType<typeof setInterval> | null = null
+  const SWEEP_MS = 250
+
+  function sweep() {
+    const now = Date.now()
+    for (const entry of inflight) {
+      if (entry.settled) {
+        inflight.delete(entry)
+        continue
+      }
+      if (now >= entry.deadlineWall) {
+        entry.settled = true
+        inflight.delete(entry)
+        entry.reject(timeoutError())
+      }
+    }
+    if (inflight.size === 0 && timer !== null) {
+      clearInterval(timer)
+      timer = null
+    }
+  }
+
+  function track(entry: WatchdogEntry) {
+    inflight.add(entry)
+    if (timer === null) {
+      timer = setInterval(sweep, SWEEP_MS)
+    }
+  }
+
+  function untrack(entry: WatchdogEntry) {
+    entry.settled = true
+    inflight.delete(entry)
+    if (inflight.size === 0 && timer !== null) {
+      clearInterval(timer)
+      timer = null
+    }
+  }
+
+  return { track, untrack }
+})()
+
+interface WatchdogEntry {
+  deadlineWall: number
+  settled: boolean
+  reject: (err: Error) => void
+}
+
+/** Create a deadline tracked by the shared watchdog (no per-read setTimeout). */
+function createDeadline(deadlineMs: number): { promise: Promise<never>; cancel: () => void } {
+  const entry: WatchdogEntry = {
+    deadlineWall: Date.now() + deadlineMs,
+    settled: false,
+    reject: () => {},
+  }
+  const promise = new Promise<never>((_resolve, reject) => {
+    entry.reject = reject
+  })
+  bodyWatchdog.track(entry)
+  return { promise, cancel: () => bodyWatchdog.untrack(entry) }
+}
+
 /**
  * Stream-read the request body, enforcing the size guard when enabled and an
  * optional overall deadline.
@@ -39,30 +152,16 @@ export async function readBodyWithLimit(
   guard: boolean,
   timeoutMs?: number,
 ): Promise<Uint8Array> {
-  const body = req.body
-
-  if (!body) {
-    return EMPTY_BODY
-  }
-
   const deadline = timeoutMs && timeoutMs > 0 ? timeoutMs : 0
-  let timer: ReturnType<typeof setTimeout> | undefined
-  const timeout = new Promise<never>((_resolve, reject) => {
-    if (deadline <= 0) return
-    timer = setTimeout(() => reject(timeoutError()), deadline)
-    // Don't let a pending body timeout keep the event loop alive once the
-    // request has otherwise completed (Node; a no-op under Bun).
-    timer.unref?.()
-  })
 
   // Fast path: a declared Content-Length lets us PROVE the body fits the
-  // guard before reading, so one native `arrayBuffer()` read replaces the
-  // reader + per-chunk `Promise.race` + `concatUint8Arrays` churn (the bench
-  // POSTs are single-shot bodies — this removes ~4-6 allocations per write
-  // request). The deadline (when set) is still enforced with a single race,
-  // not one per chunk. `req.arrayBuffer()` is bounded by the server's
-  // `maxRequestBodySize`, and the post-read length re-check catches a client
-  // that lies about Content-Length.
+  // guard before reading, so one native `bytes()`/`arrayBuffer()` read
+  // replaces the reader + per-chunk `Promise.race` + `concatUint8Arrays`
+  // churn (the bench POSTs are single-shot bodies — this removes ~4-6
+  // allocations per write request). The deadline (when set) is still enforced
+  // with a single race, not one per chunk. The read is bounded by the
+  // server's `maxRequestBodySize`, and the post-read length re-check catches
+  // a client that lies about Content-Length.
   const declared = req.headers.get('content-length')
   if (declared !== null) {
     const declaredLen = Number(declared)
@@ -70,20 +169,60 @@ export async function readBodyWithLimit(
       if (guard && declaredLen > maxBytes) {
         throw bodyTooLargeError()
       }
+      // `req.body` (the stream getter) is deliberately NOT touched on this
+      // path — `req.bytes()` (Bun) / `arrayBuffer()` (Node) read the buffered
+      // body directly, avoiding a lazily-constructed stream per write request.
+      if (deadline <= 0) {
+        const bytes = await readBodyBytes(req)
+        if (guard && bytes.byteLength > maxBytes) {
+          throw bodyTooLargeError()
+        }
+        return bytes
+      }
+      // Deadline path. Under Bun, a small declared-length body is usually
+      // already buffered — `Bun.peek` returns the bytes synchronously, so we
+      // skip the deadline race + watchdog + microtask entirely for the common
+      // case. Only a genuinely pending read (slow/trickling body) pays the
+      // race; non-Bun runtimes keep the previous behavior.
+      const buffered = peekBufferedBody(req)
+      if (buffered === false) {
+        const dl = createDeadline(deadline)
+        try {
+          const bytes = await Promise.race([readBodyBytes(req), dl.promise])
+          if (guard && bytes.byteLength > maxBytes) {
+            throw bodyTooLargeError()
+          }
+          return bytes
+        } finally {
+          dl.cancel()
+        }
+      }
+      if ('bytes' in buffered) {
+        if (guard && buffered.bytes.byteLength > maxBytes) {
+          throw bodyTooLargeError()
+        }
+        return buffered.bytes
+      }
+      const dl = createDeadline(deadline)
       try {
-        const buf =
-          deadline > 0 ? await Promise.race([req.arrayBuffer(), timeout]) : await req.arrayBuffer()
-        const bytes = new Uint8Array(buf)
+        const bytes = await Promise.race([buffered, dl.promise])
         if (guard && bytes.byteLength > maxBytes) {
           throw bodyTooLargeError()
         }
         return bytes
       } finally {
-        clearTimeout(timer)
+        dl.cancel()
       }
     }
   }
 
+  // No (usable) Content-Length: fall back to the streaming reader. `req.body`
+  // is only touched here — the declared-length fast path never needs it.
+  const body = req.body
+  if (!body) {
+    return EMPTY_BODY
+  }
+
   const reader = body.getReader()
   const chunks: Uint8Array[] = []
   let total = 0
@@ -91,11 +230,12 @@ export async function readBodyWithLimit(
   // already closed, so the `cancel()` in `finally` is a wasted async round-trip
   // per request. It is still required when the loop exits early (timeout/error).
   let completed = false
+  const dl = deadline > 0 ? createDeadline(deadline) : null
 
   try {
     for (;;) {
       const { done, value } =
-        deadline > 0 ? await Promise.race([reader.read(), timeout]) : await reader.read()
+        dl !== null ? await Promise.race([reader.read(), dl.promise]) : await reader.read()
 
       if (done) {
         completed = true
@@ -112,7 +252,7 @@ export async function readBodyWithLimit(
       chunks.push(value)
     }
   } finally {
-    clearTimeout(timer)
+    dl?.cancel()
     // Release the underlying stream. Cancelling while a read() is still
     // pending (the timeout case) can resolve that pending read() as `done`
     // and RACE the timeout rejection — so reject first, cancel only AFTER

package/src/ingress/handlers.ts

@@ -39,7 +39,7 @@
 import { getAddon } from '../native'
 import { getBunFFI } from '../native/ffi'
 import { BufferPool, type PooledBuffer } from '../shared/buffer-pool'
-import { decoder, viewForArrayBuffer } from '../shared/bytes'
+import { decoder, encoder, viewForArrayBuffer } from '../shared/bytes'
 import { createStructuredLogger } from '../shared/log'
 import { generateRequestId } from '../shared/request-id'
 import { pooledBodyResponse } from '../shared/response'
@@ -54,6 +54,8 @@ import {
 } from './constants'
 import { BakedIngressResult } from './decode/baked-result'
 import { buildBakedHeaderTemplates } from './headers/baked-templates'
+import type { SecurityHeadersOptions } from './headers/hsts'
+import { buildSecurityPairs } from './headers/hsts'
 import {
   assertIngressOptionValues,
   assertKnownIngressOptions,
@@ -62,8 +64,6 @@ import {
 } from './options'
 import { gatherRawHeadersPacked } from './packing/gather-raw-headers'
 import { IngressInputPacker } from './packing/input-packer'
-import { buildSecurityPairs } from './headers/hsts'
-import type { SecurityHeadersOptions } from './headers/hsts'
 import { ERROR_BODIES, ERROR_CODE_BODIES, rateLimitedBody } from './response/error-bodies'
 import {
   assertSyncCallback,
@@ -84,10 +84,13 @@ export type { IngressHandlerOptions } from './options'
 export { ERROR_BODIES } from './response/error-bodies'
 export type { BakedHandlerOptions } from './routes'
 export {
+  deleteHandler,
   echoHandler,
   fallbackHandler,
   headHandler,
   jsonWriteHandler,
+  nativeResponderRoute,
+  optionsHandler,
   readHandler,
 } from './routes'
 export type {
@@ -102,7 +105,6 @@ export type { RouteHandler as IngressNodeRouteHandler } from './server-node'
 // Node.js HTTP adapter (same pre-baked route handlers, node:http backend).
 export { createIngressServerNode } from './server-node'
 
-const encoder = new TextEncoder()
 const EMPTY_BODY = new Uint8Array(0)
 const EMPTY_IP = '0.0.0.0'
 
@@ -163,6 +165,7 @@ function buildBakedSecurityEntries(
 // (shared with the route factories) and re-exported here for back-compat.
 export type { BakedContext, OptimizedIngressHandler } from './types'
 
+/** Runtime configuration for the pre-baked handler path (`createIngressHandler`). */
 export interface BakedIngressRuntime {
   /** Emit an `x-request-id` header on responses. Default: false. */
   emitRequestIdHeader?: boolean
@@ -274,6 +277,21 @@ export function createIngressHandler(
   const limit = rateLimit?.limit
   const rateEnabled = typeof limit === 'number' && limit !== RATE_LIMIT_U32_MAX && limit > 0
 
+  // Minimal-processing flags: skip per-request JS UTF-8 encoding of the URL/IP
+  // when the native pipeline (rust/ingress/pipeline.rs) provably cannot read
+  // them — mirror its consumption exactly, and KEEP IN SYNC:
+  //   - URL is consumed iff parseQuery (extract_query), emitMetadataJson
+  //     (extract_path into the envelope) or https is unpinned (detect_https
+  //     scans the scheme prefix). Otherwise an empty URL section is safe.
+  //   - IP is consumed iff rate limiting is active (resolve_client_ip /
+  //     rate_key) or a proxy-trust mode is configured (socket_is_trusted
+  //     parses it). Otherwise the IP is dropped from the frame (logs/hooks
+  //     still see the real `ip` — this only skips the frame encode).
+  const trustEnabled = options.trustProxy === true || options.trustedProxies?.enabled === true
+  const urlNeeded =
+    options.parseQuery === true || options.emitMetadataJson === true || options.https === undefined
+  const ipNeeded = rateEnabled || trustEnabled
+
   // Shared with the fast path — proxy extraction is driven by trust config
   // (trustProxy / trustedProxies), not by whether rate limiting is enabled.
   const headerPlan: HeaderPlan = buildHeaderPlan(options)
@@ -400,6 +418,8 @@ export function createIngressHandler(
     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][]
     }
 
@@ -480,6 +500,7 @@ export function createIngressHandler(
     // 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][]
     }
 
@@ -637,10 +658,12 @@ export function createIngressHandler(
       // above, so pass it in to avoid a second `req.headers.get('origin')`
       // native→JS string conversion on the hot path.
       const packedHeaders = gatherRawHeadersPacked(req, headerPlan, methodKind, ctx.origin)
-      // url/ip are encoded directly into the packer buffer (no intermediate
-      // `encoder.encode` Uint8Array + copy); requestId/headers are byte slices
-      // copied verbatim (no decode→re-encode of the pre-encoded request id).
-      const input = inputPacker.packParts(methodKind, req.url, ip, ridBytes, packedHeaders)
+      // Minimal processing: when the native pipeline cannot read the URL/IP
+      // (see `urlNeeded`/`ipNeeded`), pass an empty URL / omit the IP so we
+      // skip the per-request JS UTF-8 encode entirely (the frame still carries
+      // a valid 0-length section the native bounds-checks).
+      const packUrl = urlNeeded ? req.url : ''
+      const packIp = ipNeeded ? ip : undefined
 
       try {
         // Acquire inside the try: pool exhaustion (maxInFlight) becomes a 500
@@ -648,14 +671,60 @@ export function createIngressHandler(
         handle = outputPool.acquire(outputBufferSize)
         currentHandle = handle
 
-        // Write into the pooled buffer — no per-request allocation. Under Bun
-        // with a live ffi handle this runs the pipeline through `bun:ffi`
-        // (identical packed wire format); otherwise the napi call. If the ffi
-        // call throws (native reported 0 = error, or a panic `panic_guard`
-        // contained), re-dispatch through napi once and, after repeated
-        // failures, permanently disable ffi for this handler.
+        // Write into the pooled buffer — no per-request allocation. Bun
+        // PRIMARY: the raw-components C-ABI (`castrum_ingress_handle_components`)
+        // passes `url`/`ip` as `bun:ffi` `cstring` args — the engine transcodes
+        // the JS strings to call-scoped UTF-8 in-engine, so we skip the JS
+        // frame assembly + `Buffer.write` encode for the URL/IP (same wire
+        // format: both paths run the shared `handle_components` core). Falls
+        // back to the packed frame (FFI or napi) on any failure / stale addon.
+        // If an ffi call throws (native reported 0 = error, or a panic
+        // `panic_guard` contained), re-dispatch through napi once and, after
+        // repeated failures, permanently disable ffi for this handler.
         let written: number
-        if (bunFFI !== null && ingressPtr !== 0 && !ffiDisabled) {
+        if (
+          bunFFI !== null &&
+          ingressPtr !== 0 &&
+          !ffiDisabled &&
+          typeof bunFFI.ingressHandleComponents === 'function'
+        ) {
+          try {
+            written = bunFFI.ingressHandleComponents(
+              ingressPtr,
+              methodKind,
+              packUrl,
+              packIp ?? '',
+              ridBytes,
+              packedHeaders,
+              body,
+              handle.buffer,
+            )
+            ffiFailures = 0
+          } catch {
+            ffiFailures++
+            if (ffiFailures >= MAX_FFI_FAILURES) {
+              ffiDisabled = true
+            }
+            // napi re-run: crash-safe (napi-rs catch_unwind) and semantically
+            // identical — a transient ffi panic still serves the request. The
+            // packed frame respects the same url/ip minimal-processing.
+            const input = inputPacker.packParts(
+              methodKind,
+              packUrl,
+              packIp,
+              ridBytes,
+              packedHeaders,
+            )
+            written = handler.handleRequestPacked(input, body, handle.buffer)
+          }
+        } else if (bunFFI !== null && ingressPtr !== 0 && !ffiDisabled) {
+          const input = inputPacker.packParts(
+            methodKind,
+            packUrl,
+            packIp,
+            ridBytes,
+            packedHeaders,
+          )
           try {
             written = bunFFI.ingressHandlePacked(ingressPtr, input, body, handle.buffer)
             ffiFailures = 0
@@ -669,6 +738,13 @@ export function createIngressHandler(
             written = handler.handleRequestPacked(input, body, handle.buffer)
           }
         } else {
+          const input = inputPacker.packParts(
+            methodKind,
+            packUrl,
+            packIp,
+            ridBytes,
+            packedHeaders,
+          )
           written = handler.handleRequestPacked(input, body, handle.buffer)
         }
 

package/src/ingress/health.ts

@@ -15,6 +15,7 @@
 // The readiness probe runs the optional `check` (deps up? -> 200/503).
 // The health probe is an alias of liveness (process up) plus optional check.
 
+/** Outcome of a readiness check: HTTP status + plain-text body. */
 export interface ReadinessResult {
   status: number
   body: string

package/src/ingress/index.ts

@@ -6,47 +6,59 @@
 
 import { decoder } from '../shared/bytes'
 import { generateRequestId } from '../shared/request-id'
-import { assertSyncCallback, DEFAULT_MAX_BODY_BYTES, DEFAULT_BODY_TIMEOUT_MS } from './shared'
+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 { snapshotResult, syntheticContext, internalContext } from './context'
-import { readRequestBodyOnce } from './body'
-import { ERR_CODE_BODY_TOO_LARGE, ERR_CODE_REQUEST_TIMEOUT } from './constants'
-import type { IngressOptions, IngressContext, SyncIngressHandler, IngressHandler } from './types'
-
+import { assertSyncCallback, DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES } from './shared'
+import type { IngressContext, IngressHandler, IngressOptions, SyncIngressHandler } from './types'
+
+// Runtime-driven server factory: picks Bun.serve on Bun and the node:http
+// adapter on Node via the runtime adapter (src/runtime/server.ts). This
+// explicit re-export SHADOWS the Bun-only `createIngressServer` from
+// './server' (re-exported via './handlers' above) so the public API serves
+// one backend per runtime. `createIngressServerNode` remains exported for
+// consumers who want the Node backend pinned.
+export { createIngressServer } from '../runtime/index'
+export { generateRequestId } from '../shared/request-id'
+export type { TraceContext } from '../shared/trace'
+// W3C trace context helpers (parse `traceparent` for log/hook correlation).
+export {
+  createSpanId,
+  createTraceId,
+  parseTraceParent,
+  serializeTraceParent,
+} from '../shared/trace'
 // ── Re-export the full public ingress API ─────────────────────────
 export * from './constants'
-export * from './status'
 export * from './errors'
-export * from './handlers'
 export { createIngressFast, FastIngressResult } from './fast'
-export { buildTerminalResponse } from './response/terminal'
+export * from './handlers'
+export type { CorsOptions, CorsStaticStrings } from './headers/cors'
+export type { HeaderTemplate, ResponseBuildContext } from './headers/fast-templates'
 export { buildResponseContext, headersForResult } from './headers/fast-templates'
-export { generateRequestId } from '../shared/request-id'
-export { METHOD_KIND, DEFAULT_MAX_BODY_BYTES, DEFAULT_BODY_TIMEOUT_MS } from './shared'
-export type { HeaderPlan } from './shared'
-export type { ResponseBuildContext, HeaderTemplate } from './headers/fast-templates'
-export type { CorsStaticStrings, CorsOptions } from './headers/cors'
 export type { SecurityHeadersOptions } from './headers/hsts'
-export type { IngressFastHandler, IngressFastOptions } from './options'
+export { healthHandler, livenessHandler, readinessHandler } from './health'
+export type { IngressMetrics } from './metrics'
 // ── Observability (zero-dep): metrics, health probes ─────────────
 export { createIngressMetrics, metricsHandler } from './metrics'
-export type { IngressMetrics } from './metrics'
-export { livenessHandler, readinessHandler, healthHandler } from './health'
-// W3C trace context helpers (parse `traceparent` for log/hook correlation).
-export {
-  parseTraceParent,
-  createTraceId,
-  createSpanId,
-  serializeTraceParent,
-} from '../shared/trace'
-export type { TraceContext } from '../shared/trace'
+export type { IngressFastHandler, IngressFastOptions } from './options'
+export { buildTerminalResponse } from './response/terminal'
+export type { CreateIngressRouterOptions, IngressRouter, RouterRouteSpec } from './router'
+export { createIngressRouter } from './router'
+export type { HeaderPlan } from './shared'
+export { DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES, METHOD_KIND } from './shared'
+export * from './status'
 export type {
-  IngressOptions,
   IngressContext,
-  SyncIngressHandler,
   IngressHandler,
+  IngressOptions,
+  NativeRequestContext,
+  NativeResponder,
+  SyncIngressHandler,
+  TerminalStyle,
 } from './types'
 
 // ── Sync factory ─────────────────────────────────────────────────