castrum 0.7.0 → 0.9.1

package/src/ingress/index.ts

@@ -1,457 +1,194 @@
-// src/ingress/index.ts — Public ingress API
+// src/ingress/index.ts — Public ingress API (barrel + sync/async factories)
 //
 // All constants come from Rust via src/ingress/constants.ts.
 // For maximum performance, use createIngressFast() from ./fast.ts directly.
 // This module wraps createIngressFast with convenience async API (createIngress).
 
-import addon from "../native";
-import { decoder } from "../shared/bytes";
-import {
-  OUT_VERDICT, OUT_ERROR_CODE, OUT_STATUS, OUT_FLAGS,
-  OUT_RATE_LIMIT, OUT_RATE_REMAINING, OUT_RATE_RESET, OUT_RETRY_AFTER,
-  OUT_COOKIES_JSON_LEN, OUT_QUERY_JSON_LEN, OUT_HEADER_VARIANT, OUT_BODY_JSON_LEN,
-  OUT_DATA_START,
-  FLAG_HAS_COOKIES, FLAG_HAS_QUERY,
-  FLAG_BODY_VALID_JSON, FLAG_SCHEMA_VALID,
-  FLAG_CORS_ALLOWED, FLAG_IS_PREFLIGHT, FLAG_RATE_LIMITED,
-  FLAG_HTTPS, FLAG_TRUSTED_PROXY, FLAG_BODY_TRUNCATED,
-  HV_JSON, HV_CORS_SIMPLE, HV_CORS_PREFLIGHT, HV_RATE_ACTIVE, HV_RATE_LIMITED,
-  HV_COUNT,
-  ERR_CODE_NONE, ERR_CODE_CORS_PREFLIGHT, ERR_CODE_RATE_LIMITED,
-  ERR_CODE_BODY_TOO_LARGE, ERR_CODE_INVALID_JSON, ERR_CODE_SCHEMA_VALIDATION,
-  ERR_CODE_BAD_REQUEST, ERR_CODE_REQUEST_TOO_LARGE, ERR_CODE_INTERNAL,
-} from "./constants";
-import {
-  createIngressFast,
-  FastIngressResult,
-  buildResponseContext,
-  buildTerminalResponse,
-  headersForResult,
-  safeTerminalStatus,
-  statusForErrorCode,
-  isValidResponseStatus,
-  normalizeResponseStatus,
-  errorCodeName,
-  errorMessage,
-  type IngressFastOptions,
-  type IngressFastHandler,
-  type ResponseBuildContext,
-  type HeaderTemplate,
-  type HeaderPlan,
-  type CorsStaticStrings,
-  type SecurityHeadersOptions,
-  type CorsOptions,
-  generateRequestId,
-  METHOD_KIND,
-  DEFAULT_MAX_BODY_BYTES,
-} from "./fast";
-
-// ── Re-export types from constants ──────────────────────────────
+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'
+
+// 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 {
-  OUT_VERDICT, OUT_ERROR_CODE, OUT_STATUS, OUT_FLAGS,
-  OUT_RATE_LIMIT, OUT_RATE_REMAINING, OUT_RATE_RESET, OUT_RETRY_AFTER,
-  OUT_COOKIES_JSON_LEN, OUT_QUERY_JSON_LEN, OUT_HEADER_VARIANT, OUT_BODY_JSON_LEN,
-  OUT_DATA_START,
-  FLAG_HAS_COOKIES, FLAG_HAS_QUERY,
-  FLAG_BODY_VALID_JSON, FLAG_SCHEMA_VALID,
-  FLAG_CORS_ALLOWED, FLAG_IS_PREFLIGHT, FLAG_RATE_LIMITED,
-  FLAG_HTTPS, FLAG_TRUSTED_PROXY, FLAG_BODY_TRUNCATED,
-  HV_JSON, HV_CORS_SIMPLE, HV_CORS_PREFLIGHT, HV_RATE_ACTIVE, HV_RATE_LIMITED,
-  HV_COUNT,
-  ERR_CODE_NONE, ERR_CODE_CORS_PREFLIGHT, ERR_CODE_RATE_LIMITED,
-  ERR_CODE_BODY_TOO_LARGE, ERR_CODE_INVALID_JSON, ERR_CODE_SCHEMA_VALIDATION,
-  ERR_CODE_BAD_REQUEST, ERR_CODE_REQUEST_TOO_LARGE, ERR_CODE_INTERNAL,
-};
-
-// ── Public option types ──────────────────────────────────────────
-export type { SecurityHeadersOptions, CorsOptions };
-
-export interface IngressOptions extends IngressFastOptions {
-  enableRequestIds?: boolean;
-}
-
-// ── Result types ─────────────────────────────────────────────────
-// Note: the exported `FastIngressResult` class (from fast.ts) is the zero-alloc
-// implementation; this `IngressResult` interface is the readonly structural view
-// used by the public sync/async handler types.
-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;
+  createSpanId,
+  createTraceId,
+  parseTraceParent,
+  serializeTraceParent,
+} from '../shared/trace'
+// ── Re-export the full public ingress API ─────────────────────────
+export * from './constants'
+export * from './errors'
+export { createIngressFast, FastIngressResult } from './fast'
+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 type { SecurityHeadersOptions } from './headers/hsts'
+export { healthHandler, livenessHandler, readinessHandler } from './health'
+export type { IngressMetrics } from './metrics'
+// ── Observability (zero-dep): metrics, health probes ─────────────
+export { createIngressMetrics, metricsHandler } from './metrics'
+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 {
+  IngressContext,
+  IngressHandler,
+  IngressOptions,
+  NativeRequestContext,
+  NativeResponder,
+  SyncIngressHandler,
+  TerminalStyle,
+} from './types'
 
-  cookiesJson(): string;
-  queryJson(): string;
-  bodyJson(): Uint8Array;
-}
-
-export interface IngressContext extends IngressResult {
-  response: Response | null;
-}
+// ── Sync factory ─────────────────────────────────────────────────
 
 /**
- * Synchronous ingress handler.
+ * Synchronous convenience wrapper over `createIngressFast` (path 1).
  *
- * 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 createIngress} which snapshots for you).
+ * The callback runs on the fast-path result and MUST be synchronous. Use
+ * {@link createIngress} when you want automatic body reading + error contexts.
  */
-export interface SyncIngressHandler {
-  run<T>(
-    req: Request,
-    ip: string | undefined,
-    body: Uint8Array | null,
-    requestId: string,
-    fn: (result: IngressResult) => T,
-  ): T;
-}
-
-export interface IngressHandler {
-  (req: Request, ip?: string): Promise<IngressContext>;
-}
-
-// ── HTTP status helpers (re-exported from fast.ts) ──────────────
-export { isValidResponseStatus, statusForErrorCode, normalizeResponseStatus, safeTerminalStatus };
-
-// ── Header template system (re-exported from fast.ts) ────────────
-export { buildResponseContext, headersForResult };
-export type { ResponseBuildContext, HeaderTemplate, CorsStaticStrings };
-
-// ── Pre-baked handler functions (route factories + Bun.serve builder) ──
-export * from "./handlers";
-
-// ── Constants ────────────────────────────────────────────────────
-const EMPTY_BODY = new Uint8Array(0);
-
-// ── Sync factory ─────────────────────────────────────────────────
-export function createIngressSync(
-  options: IngressOptions = {},
-): SyncIngressHandler {
-  const fast = createIngressFast(options);
+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);
-
-        if (
-          out !== null &&
-          (typeof out === "object" || typeof out === "function") &&
-          typeof (out as any).then === "function"
-        ) {
-          throw new Error("createIngressSync().run() callback must be synchronous.");
-        }
-
-        return out;
-      });
+        const out = fn(result)
+        assertSyncCallback(out, 'createIngressSync().run()')
+        return out
+      })
     },
-  };
-}
-
-// ── Body reading helpers (used by async API) ────────────────────
-function readRequestBodyOnce(
-  req: Request,
-  maxBytes: number,
-  guard: boolean,
-): Promise<Uint8Array> {
-  if (req.body === null) {
-    return Promise.resolve(EMPTY_BODY);
-  }
-
-  return readBodyWithLimit(req, maxBytes, guard);
-}
-
-async function readBodyWithLimit(
-  req: Request,
-  maxBytes: number,
-  guard: boolean,
-): Promise<Uint8Array> {
-  const body = req.body;
-
-  if (!body) {
-    return EMPTY_BODY;
-  }
-
-  const reader = body.getReader();
-  const chunks: Uint8Array[] = [];
-  let total = 0;
-
-  for (;;) {
-    const { done, value } = await reader.read();
-
-    if (done) break;
-    if (!value) continue;
-
-    total += value.byteLength;
-
-    if (guard && total > maxBytes) {
-      await reader.cancel().catch(() => {});
-
-      const err = new Error("BODY_TOO_LARGE");
-      (err as any).code = "BODY_TOO_LARGE";
-
-      throw err;
-    }
-
-    chunks.push(value);
   }
-
-  return concatUint8Arrays(chunks, total);
 }
 
-function concatUint8Arrays(
-  chunks: Uint8Array[],
-  total: number,
-): Uint8Array {
-  if (chunks.length === 0) return EMPTY_BODY;
-  if (chunks.length === 1) return chunks[0]!;
-
-  const out = new Uint8Array(total);
-  let offset = 0;
-
-  for (const chunk of chunks) {
-    out.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
+// ── Async factory ────────────────────────────────────────────────
 
-  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 factory ────────────────────────────────────────────────
+/**
+ * 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.
+ */
 export function createIngress(options: IngressOptions = {}): IngressHandler {
-  const sync = createIngressSync(options);
+  const sync = createIngressSync(stripSecurityOptions(options))
 
-  const guard = options.enableBodySizeGuard !== false;
-  const max = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+  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);
+    (options.readBody !== false && guard)
 
-  const responseCtx = buildResponseContext(options);
+  const responseCtx = buildResponseContext(options)
 
-  return async function ingressAsync(
-    req: Request,
-    ip?: string,
-  ): Promise<IngressContext> {
-    const requestId =
-      options.enableRequestIds === false ? "" : decoder.decode(generateRequestId());
+  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");
+        const rawLen = req.headers.get('content-length')
+        const contentLength = Number(rawLen ?? '0')
 
         if (Number.isFinite(contentLength) && contentLength > max) {
-          return syntheticContext(
-            req,
-            requestId,
-            options,
-            responseCtx,
-            413,
-            ERR_CODE_BODY_TOO_LARGE,
-          );
+          return emitResponse(
+            syntheticContext(req, requestId, options, responseCtx, 413, ERR_CODE_BODY_TOO_LARGE),
+          )
         }
       }
 
-      let body: Uint8Array | null = null;
+      let body: Uint8Array | null = null
 
       if (wantsBody && req.body !== null) {
         try {
-          body = await readRequestBodyOnce(req, max, guard);
+          body = await readRequestBodyOnce(req, max, guard, bodyTimeoutMs)
         } catch (err) {
-          if ((err as any)?.code === "BODY_TOO_LARGE") {
-            return syntheticContext(
-              req,
-              requestId,
-              options,
-              responseCtx,
-              413,
-              ERR_CODE_BODY_TOO_LARGE,
-            );
+          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),
+            )
           }
 
-          throw err;
+          // 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 sync.run(req, ip, body, requestId, (r) => {
-        const snapshot = snapshotResult(r);
-        const response = buildTerminalResponse(
-          responseCtx,
-          snapshot,
-          req,
-          requestId,
-        );
+      return emitResponse(
+        sync.run(req, ip, body, requestId, (r) => {
+          const snapshot = snapshotResult(r)
+          const response = buildTerminalResponse(responseCtx, snapshot, req, requestId)
 
-        return {
-          ...snapshot,
-          response,
-        };
-      });
-    } catch {
-      return internalContext(req, requestId, options, responseCtx);
+          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))
     }
-  };
-}
-
-// ── Result helpers ───────────────────────────────────────────────
-function snapshotResult(r: IngressResult): IngressResult {
-  const cookies = r.cookiesJson();
-  const query = r.queryJson();
-  const bodyJson = r.bodyJson().slice();
-  const body = r.body;
-
-  return {
-    status: r.status,
-    verdict: r.verdict,
-    flags: r.flags,
-    errorCode: r.errorCode,
-    terminal: r.terminal,
-    ok: r.ok,
-    https: r.https,
-    trustedProxy: r.trustedProxy,
-    hasCookies: r.hasCookies,
-    hasQuery: r.hasQuery,
-    bodyValidJson: r.bodyValidJson,
-    schemaValid: r.schemaValid,
-    corsAllowed: r.corsAllowed,
-    isPreflight: r.isPreflight,
-    rateLimited: r.rateLimited,
-    rateLimit: r.rateLimit,
-    rateRemaining: r.rateRemaining,
-    rateResetMs: r.rateResetMs,
-    retryAfterMs: r.retryAfterMs,
-    body,
-    headerVariant: r.headerVariant,
-    requestId: r.requestId,
-    bodyTruncated: r.bodyTruncated,
-
-    cookiesJson: () => cookies,
-    queryJson: () => query,
-    bodyJson: () => bodyJson,
-  };
-}
-
-function syntheticContext(
-  req: Request,
-  requestId: string,
-  options: IngressOptions,
-  responseCtx: ResponseBuildContext,
-  status: number,
-  errorCode: number,
-): IngressContext {
-  const corsAllowed = staticCorsAllowed(options, req);
-  const variant = HV_JSON | (corsAllowed ? HV_CORS_SIMPLE : 0);
-
-  const base: IngressResult = {
-    status,
-    verdict: 1,
-    flags: 0,
-    errorCode,
-    terminal: true,
-    ok: false,
-    https: options.https === true,
-    trustedProxy:
-      options.trustProxy === true ||
-      options.trustedProxies?.enabled === true,
-    hasCookies: false,
-    hasQuery: false,
-    bodyValidJson: false,
-    schemaValid: false,
-    corsAllowed,
-    isPreflight: false,
-    rateLimited: errorCode === ERR_CODE_RATE_LIMITED,
-    rateLimit: options.rateLimit?.limit ?? 0,
-    rateRemaining: 0,
-    rateResetMs: 0,
-    retryAfterMs: 0,
-    body: EMPTY_BODY,
-    headerVariant: variant,
-    requestId,
-    bodyTruncated: false,
-
-    cookiesJson: () => "{}",
-    queryJson: () => "{}",
-    bodyJson: () => EMPTY_BODY,
-  };
-
-  return {
-    ...base,
-    response: buildTerminalResponse(responseCtx, base, req, requestId),
-  };
-}
-
-function internalContext(
-  req: Request,
-  requestId: string,
-  options: IngressOptions,
-  responseCtx: ResponseBuildContext,
-): IngressContext {
-  return syntheticContext(
-    req,
-    requestId,
-    options,
-    responseCtx,
-    500,
-    ERR_CODE_INTERNAL,
-  );
-}
-
-function staticCorsAllowed(options: IngressOptions, req: Request): boolean {
-  const cors = options.cors;
-  if (!cors) return false;
-
-  const origin = req.headers.get("origin");
-  if (!origin) return false;
-
-  const list = cors.allowOrigin;
-
-  if (!list || list.length === 0) {
-    return cors.allowCredentials !== true;
   }
-
-  if (list.includes("*")) {
-    return cors.allowCredentials !== true;
-  }
-
-  return list.includes(origin);
 }
-
-// ── Re-export fast.ts API for direct use ─────────────────────────
-// Error helpers (errorCodeName/errorMessage/buildTerminalResponse), METHOD_KIND
-// and DEFAULT_MAX_BODY_BYTES were previously internal-only; exposing them makes
-// the numeric verdict/errorCode contract usable without reaching into internals.
-export {
-  createIngressFast,
-  FastIngressResult,
-  errorCodeName,
-  errorMessage,
-  buildTerminalResponse,
-  generateRequestId,
-  METHOD_KIND,
-  DEFAULT_MAX_BODY_BYTES,
-};
-export type { IngressFastHandler, IngressFastOptions, HeaderPlan };