castrum 0.9.8 → 0.9.9

package/Cargo.lock

@@ -233,7 +233,7 @@ checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
 
 [[package]]
 name = "castrum"
-version = "0.9.8"
+version = "0.9.9"
 dependencies = [
  "argon2",
  "aws-lc-rs",

package/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "castrum"
 # Keep in sync with package.json "version" (single source of truth: the npm package).
-version = "0.9.8"
+version = "0.9.9"
 edition = "2021"
 # Keep in sync with package.json "license" (cargo-deny rejects a crate with no
 # license expression).

package/dist/index.d.ts

@@ -553,8 +553,45 @@ export interface PathMatch {
  *  adapter (Bun's native router handles matching; the ingress pipeline does
  *  not echo params in its response). */
 type RouteHandler = (req: Request, srv?: unknown, params?: Record<string, string>) => Response | Promise<Response>;
+/**
+ * A prebuilt constant response for static route promotion.
+ *
+ * Either a bare `Response` or a factory that builds a FRESH `Response` per
+ * request. Behavior differs by runtime:
+ *
+ * - **Bun**: a bare `Response` is snapshotted into `Bun.serve`'s native route
+ *   table at bind time (verified on Bun 1.4.2 — the body is NOT consumed by the
+ *   first request) and served on every request without entering JS.
+ * - **Node** (`createIngressServerNode`): the adapter reads the bare `Response`
+ *   body ONCE and materializes a fresh `Response` per request (a web body is
+ *   one-shot).
+ *
+ * A factory is invoked by the runtime on every request, so it MUST return a new
+ * `Response` each call. Returning the SAME already-sent instance fails on the
+ * second request with `ERR_BODY_ALREADY_USED` (Bun) / a consumed stream
+ * (Node) — use a factory only when the response genuinely varies per request.
+ */
+export type StaticRoute = Response | (() => Response);
 /** Route spec for the Bun.serve builder. */
 export interface BakedRoute {
+	/**
+	 * A prebuilt constant response served for GET, bypassing the ingress
+	 * pipeline entirely. Takes precedence over `read`/`cookies` for GET (the
+	 * pipeline handler is never wired); other methods (`write`/`echo`/`delete`)
+	 * are unaffected. See {@link StaticRoute} for the one-shot-body contract.
+	 *
+	 * HEAD is intentionally NOT wired for `static` (a bare `Response` carries a
+	 * body; static responses are probes/constants served over GET). This matches
+	 * the raw-`read` probe behavior — but note that a route which previously
+	 * served HEAD via a native `read` now 405s (Node) on HEAD once `static` is
+	 * set. When `static` is combined with `write`/`echo`/`delete`, those dynamic
+	 * methods remain wired.
+	 *
+	 * Runtime note: `createIngressRouter` treats `static` differently — there,
+	 * like `raw`, it OWNS THE WHOLE SPEC (the router has no compiled ingress for
+	 * the other methods; see `RouterRouteSpec.static` in src/ingress/router.ts).
+	 */
+	static?: StaticRoute;
 	/**
 	 * Wires GET + HEAD read handlers. Accepts an optimized ingress handler OR a
 	 * raw `RouteHandler` function (health/metrics probes are raw — see
@@ -631,14 +668,20 @@ export interface CreateIngressServerOptions {
 	routes: Record<string, BakedRoute>;
 	fallback?: OptimizedIngressHandler;
 	/**
-	 * Invoked when an unhandled error escapes a request handler (currently wired
-	 * on the Node adapter; the Bun path uses runtime.onResponse). Never throws —
-	 * hook failures are swallowed.
+	 * Invoked when an unhandled error escapes a request handler (raw `read`
+	 * functions, `responder`/`native` responders, or the Bun/Node adapter
+	 * catch-all). The error is masked to a generic 500 on the wire. Never
+	 * throws — hook failures are swallowed.
 	 */
 	onError?: (info: {
 		error: Error;
 		request?: Request;
 	}) => void;
+	/**
+	 * Optional structured-log sink for escaped handler errors (one JSON line per
+	 * masked 500, message only). Never throws.
+	 */
+	logger?: (line: string) => void;
 	/** Node adapter only: ms to receive the complete request (headers + body).
 	 *  Guards slowloris/trickling requests. Default: 30_000. */
 	requestTimeoutMs?: number;
@@ -1372,18 +1415,23 @@ export interface BunFFI {
 	regexEscapeStr(input: string): string | null;
 	/** Start the shared native task pool; 0 = started, 1 = already running. */
 	taskInit(threads: number): number;
-	/** Submit a task op with packed `args` under `taskId`; 1 = accepted. */
+	/**
+	 * Submit a task op with packed `args` under `taskId`. Returns `1` accepted,
+	 * `2` overloaded (bounded queue full), `0` invalid args.
+	 */
 	taskSubmit(op: number, args: Uint8Array, taskId: number): number;
 	/**
 	 * Zero-copy submit: the op writes its result DIRECTLY into `output` on the
 	 * pool thread. `output` must be a stable, caller-owned buffer that stays
 	 * alive (and untouched) until the completion is drained — the runtime holds
 	 * the reference. The completion body is the 8-byte LE written length.
+	 * Returns `1` accepted, `2` overloaded, `0` invalid args.
 	 */
 	taskSubmitOut(op: number, args: Uint8Array, taskId: number, output: Uint8Array): number;
 	/**
 	 * Zero-copy INPUT: only `hdr` is copied; `data` is read in place by the pool
 	 * thread, so the caller must keep it alive (and untouched) until completion.
+	 * Returns `1` accepted, `2` overloaded, `0` invalid args.
 	 */
 	taskSubmitSlice(op: number, hdr: Uint8Array, data: Uint8Array, taskId: number): number;
 	/**
@@ -1448,6 +1496,41 @@ export declare function createTraceId(): string;
 export declare function createSpanId(): string;
 /** Serialize a trace context back to a `traceparent` header value. */
 export declare function serializeTraceParent(ctx: TraceContext): string;
+/**
+ * The `err.code` value a body read carries when it is rejected because the
+ * client disconnected (`Request.signal` aborted).
+ */
+export declare const ABORT_CODE = "REQUEST_ABORTED";
+/**
+ * Whether a thrown value is the cancellation error produced when `req.signal`
+ * aborts during a body read (see `readBodyWithLimit` in `./body`).
+ *
+ * @param err - The caught value.
+ * @returns `true` when `err.code === 'REQUEST_ABORTED'`.
+ * @example
+ * ```ts
+ * try {
+ *   await readBodyWithLimit(req, 1 << 20, true)
+ * } catch (err) {
+ *   if (isAbortError(err)) return abortResponse()
+ *   throw err
+ * }
+ * ```
+ */
+export declare function isAbortError(err: unknown): boolean;
+/**
+ * Build the cancelled-client response: status **499** ("Client Closed
+ * Request", a de-facto nginx status) with no body. This is the only new
+ * outcome added by cancellation — it never replaces an existing success or
+ * error status.
+ *
+ * @returns A bodyless `Response` with status 499.
+ * @example
+ * ```ts
+ * if (req.signal?.aborted) return abortResponse()
+ * ```
+ */
+export declare function abortResponse(): Response;
 /** Offset of the verdict byte (0 = accepted, nonzero = terminal error). */
 export declare const OUT_VERDICT: number;
 /** Offset of the error-code byte (see ERR_CODE_* below). */
@@ -1829,6 +1912,20 @@ export declare function createIngressHandler(options?: IngressHandlerOptions, ru
  * Never touches dependencies.
  */
 export declare function livenessHandler(): (_req: Request) => Response;
+/**
+ * Liveness probe as a PREBUILT `Response`, for static route promotion.
+ *
+ * Wire it as `{ static: staticLiveness() }` so `Bun.serve` snapshots the
+ * constant body into its native route table and serves `/livez` without
+ * entering the JavaScript ingress pipeline at all (see `BakedRoute.static` in
+ * src/ingress/server.ts). On the node:http adapter the bare `Response` is
+ * re-materialized per request from cached body bytes, so the one-shot body is
+ * never replayed. Unlike {@link readinessHandler}, it never runs a dependency
+ * check.
+ *
+ * @returns A fresh 200 `{"status":"ok"}` `Response`.
+ */
+export declare function staticLiveness(): Response;
 /**
  * Readiness probe: runs the optional async `check` (dependency readiness).
  * Returns `200 {"status":"ready"}` when the check passes (or no check is
@@ -1955,6 +2052,20 @@ export interface RouterRouteSpec {
 	/** Terminal envelope style for this route's responder (default: router-level
 	 *  `terminalStyle` or `'castrum'`). */
 	terminalStyle?: TerminalStyle;
+	/**
+	 * A prebuilt constant response served directly for GET, OUTSIDE the ingress
+	 * pipeline (static route promotion). Like `raw`, it OWNS THE WHOLE SPEC: the
+	 * router compiles no `IngressInner` for a `static` route, so `read`/`write`/
+	 * `echo`/etc. on the same spec are ignored.
+	 *
+	 * This differs from `BakedRoute.static` in src/ingress/server.ts, where
+	 * `static` only takes GET precedence and leaves `write`/`echo`/`delete`
+	 * wired — the router cannot mirror that because a `static`-only spec has no
+	 * compiled ingress to hand those methods. Do not unify the two semantics.
+	 *
+	 * See `BakedRoute.static` for the one-shot-body contract.
+	 */
+	static?: StaticRoute;
 	/**
 	 * A raw request→Response handler served directly for GET, OUTSIDE the
 	 * ingress pipeline (health/metrics probes, /metrics). When set, `read`/
@@ -3292,6 +3403,20 @@ export interface RustScalar {
 	createMetricsRegistry(): MetricsRegistryInstance;
 	initThreadPool(rayonThreads?: number): void;
 	rayonNumThreads(): number;
+	/**
+	 * Drop the process-wide compiled request-body schema cache. Identical schema
+	 * bytes are compiled once and shared across `Ingress` / `NativeRoute`
+	 * instances; this releases those compiled validators (already-constructed
+	 * instances keep their own shared reference and are unaffected). Idempotent,
+	 * and a safe no-op when the native addon is absent or predates the symbol
+	 * (the public `flushMemory()` relies on that).
+	 *
+	 * Maintenance-only escape hatch — NOT a benchmarked op, so it is intentionally
+	 * exempt from `PROVEN_SELECTION` / `selection.json` (there is no native-vs-JS
+	 * winner to classify). `test/unit/contract/proven.test.ts` only requires
+	 * registry coverage for selection.json ops + Bun built-ins.
+	 */
+	clearSchemaCache(): void;
 	jwtSign(claims: Record<string, unknown>, secret: Uint8Array, ttlSeconds?: number | null, nowSeconds?: number): Uint8Array;
 	/**
 	 * Sign a JWT from pre-serialized claim JSON bytes — skips the napi
@@ -3694,6 +3819,41 @@ export declare const encoder: {
 export declare const decoder: {
 	decode(bytes: Uint8Array | string): string;
 };
+/** Options for {@link flushMemory}. */
+export interface FlushMemoryOptions {
+	/**
+	 * When true (the default), also request a full garbage collection from the
+	 * runtime: `Bun.gc(true)` on Bun, `globalThis.gc?.()` on Node when the
+	 * process runs with `--expose-gc`. Set false to flush caches only.
+	 */
+	gc?: boolean;
+}
+/**
+ * Flush process-level caches and (by default) request a full GC. Intended for
+ * explicit memory-pressure handling — e.g. after a burst or before a snapshot.
+ *
+ * Clears:
+ * - the global loader LRU cache (`loader.clear()`),
+ * - the process-wide MIME caches (`clearMimeCaches()`),
+ * - the native compiled-schema cache (`rust.clearSchemaCache()`).
+ *
+ * The metrics registry is intentionally left untouched.
+ *
+ * Idempotent, and safe to call before the native addon has ever been loaded
+ * (every cache starts empty, the loader cache is a plain Map, and the native
+ * schema-cache clear is a defensive no-op when the addon/symbol is absent).
+ *
+ * @param options - `gc: false` skips the runtime GC request. Defaults to `{}`
+ *   (GC requested).
+ * @example
+ * ```ts
+ * import { flushMemory } from 'castrum'
+ *
+ * flushMemory()            // drop caches + request GC
+ * flushMemory({ gc: false }) // drop caches only
+ * ```
+ */
+export declare function flushMemory(options?: FlushMemoryOptions): void;
 /**
  * Generate a UUIDv7 (time-ordered) string, preferring Bun's native built-in.
  * Under Node this falls back to `crypto.randomUUID` (v4).