castrum 0.9.1 → 0.9.3

package/README.md

@@ -168,7 +168,7 @@ isEmail([a, b, c]);               // one packed batch call
 ## Testing
 
 ```bash
-bun test                  # TypeScript unit tests (~540)
+bun test                  # TypeScript unit tests (~760)
 bun run test:rust         # Rust unit tests (cargo test)
 bun run typecheck         # TypeScript typecheck
 bun run test:node         # Node.js integration tests (run `bun run build:js` first)

package/dist/index.d.ts

@@ -96,6 +96,11 @@ export interface EncodingPrefResult {
 export interface AcceptNegotiatorInstance {
 	/** Best supported encoding for `header`, or null for identity. */
 	negotiate(header: Uint8Array): string | null;
+	/** Best supported encoding for `header` with SERVER-preference tie-breaking
+	 * (RFC 7231 server semantics — the supported list's order breaks q-value
+	 * ties), or null for identity. On the napi fallback this is the projected
+	 * `negotiate_server_preference` method. */
+	negotiateServerPreference(header: Uint8Array): string | null;
 	/** Opaque handle (bun:ffi fast path) — `castrum_accept_negotiator_negotiate`. */
 	innerPtr?(): bigint;
 }
@@ -573,6 +578,14 @@ export interface OptimizedIngressHandler {
 		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
@@ -626,6 +639,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 —
@@ -635,6 +656,142 @@ export interface BakedHandlerOptions {
 	 */
 	enableLoader?: boolean;
 }
+/** Route descriptor magic (`"ROUT"` LE). Must match `ROUTE_DESC_MAGIC` in Rust. */
+export declare const ROUTE_DESC_MAGIC = 1380930900;
+/** Wire version — bump on ANY descriptor/frame/result layout change. */
+export declare const ROUTE_DESC_VERSION = 3;
+/** Descriptor stage tags (the ordered pipeline a route instance runs). */
+export declare const ROUTE_STAGE: {
+	readonly parseQuery: 0;
+	readonly parseCookies: 1;
+	readonly validateQuery: 2;
+	readonly validateCookies: 3;
+	readonly validateBody: 4;
+	readonly requireJsonBody: 5;
+};
+/** A descriptor stage tag (`ROUTE_STAGE` values, must match Rust). */
+export type RouteStageTag = (typeof ROUTE_STAGE)[keyof typeof ROUTE_STAGE];
+/** Descriptor part tags (`RoutePartKind`): the schema-bearing request parts. */
+export declare const ROUTE_PART: {
+	readonly body: 3;
+};
+/** Result flag bits (`ROUTE_RESULT_FLAG_*` in Rust). */
+export declare const ROUTE_FLAG: {
+	readonly OK: number;
+	readonly BODY_VALID_JSON: number;
+	readonly QUERY_VALID: number;
+	readonly COOKIE_VALID: number;
+	readonly BODY_VALID: number;
+};
+/** Frame flag: the body section is present (bit 0 of the frame flags word). */
+export declare const ROUTE_FRAME_FLAG_HAS_BODY: number;
+/** Size limits a route descriptor carries. */
+export interface RouteWireLimits {
+	maxBodyBytes: number;
+	maxQueryBytes: number;
+	maxCookieBytes: number;
+	maxPairs: number;
+}
+/** A schema part carried by the descriptor (part tag + draft-07 JSON bytes). */
+export interface RouteWireSchema {
+	part: number;
+	bytes: Uint8Array;
+}
+/**
+ * Encode a route plan into the descriptor wire.
+ *
+ * Layout: `[magic u32][version u32][maxBody u32][maxQuery u32][maxCookie u32]
+ * [maxPairs u32][stageCount u32][stages u8…][schemaCount u32]
+ * { [part u8][len u32][schema] }…`
+ */
+export declare function encodeRouteDescriptor(pipeline: readonly RouteStageTag[], schemas: readonly RouteWireSchema[], limits: RouteWireLimits): Uint8Array;
+/**
+ * Encode a request frame: `[flags u32][qLen][query][cLen][cookie]([bLen][body])`.
+ * The `flags` word currently only carries `ROUTE_FRAME_FLAG_HAS_BODY`.
+ */
+export declare function packRouteFrame(query: string, cookie: string, body: Uint8Array | null): Uint8Array;
+/** A decoded `[name, value]` pair from a result section. */
+export type RouteWirePair = [
+	string,
+	string
+];
+/** The decoded route result: the verdict header + optional pair sections. */
+export interface RouteWireResult {
+	/** `ROUTE_FLAG_*` bits from the result header. */
+	flags: number;
+	/** `0` = ok; `400` = not-JSON under requireJsonBody; `422` = schema fail. */
+	errorCode: number;
+	/** Decoded query pairs (present iff the plan compiled `parseQuery`). */
+	query: RouteWirePair[];
+	/** Decoded cookie pairs (present iff the plan compiled `parseCookies`). */
+	cookie: RouteWirePair[];
+}
+/**
+ * Decode the result wire: `[flags u32][errorCode u32]` + a query pair section
+ * iff `query` and a cookie pair section iff `cookie` (the caller knows its own
+ * plan). Sections are `[count u32] { [nameLen u32][name][valueLen u32][value] }`.
+ */
+export declare function decodeRouteResult(buf: Uint8Array, opts: {
+	query: boolean;
+	cookie: boolean;
+}): RouteWireResult;
+/** Plan for a compiled native route (the stage/limit/schema surface). */
+export interface NativeRoutePlan {
+	/** Parse + lenient-decode the query string into pairs (stage 0). */
+	parseQuery?: boolean;
+	/** Parse + lenient-decode the Cookie header into pairs (stage 1). */
+	parseCookies?: boolean;
+	/** Reject a missing / non-JSON body with 400 (stage 5, first-failure-wins). */
+	requireJsonBody?: boolean;
+	/** Validate the body against `schema` with 422 on failure (stage 4). */
+	validateBody?: boolean;
+	/** Draft-07 JSON schema bytes for the body (`validateBody`). */
+	schema?: Uint8Array;
+	/** Max body bytes before `requireJsonBody`/`validateBody` fail (default 2 MiB). */
+	maxBodyBytes?: number;
+	/** Max query bytes before the parse VALID bit clears (default 8192). */
+	maxQueryBytes?: number;
+	/** Max cookie bytes before the parse VALID bit clears (default 8192). */
+	maxCookieBytes?: number;
+	/** Max pairs per section (0 = unlimited; default 0). */
+	maxPairs?: number;
+}
+/** A compiled per-route native stack (route-wire v3). */
+export interface NativeRoute {
+	/** Whether the plan compiled `parseQuery` (the result carries a query section). */
+	readonly parseQuery: boolean;
+	/** Whether the plan compiled `parseCookies` (the result carries a cookie section). */
+	readonly parseCookies: boolean;
+	/**
+	 * Run one request frame through the compiled stack and return the decoded
+	 * verdict. The frame is `[flags u32][qLen][query][cLen][cookie]([bLen][body])`
+	 * — build it with {@link packRouteFrame}. Reuses one growable output buffer
+	 * (the needed-size convention: `0` = real error → throws; `> out.length` =
+	 * exact required size → retry once).
+	 */
+	runFrame(frame: Uint8Array): RouteWireResult;
+	/** Convenience: pack a `(query, cookie, body)` frame then {@link runFrame}. */
+	run(query: string, cookie: string, body: Uint8Array | null): RouteWireResult;
+	/** Free the native handle (idempotent; safe to call once at shutdown). */
+	destroy(): void;
+}
+/**
+ * Compile a per-route native stack from a plan. Returns a compiled route whose
+ * `run`/`runFrame` perform the parse + verdict in ONE native call.
+ *
+ * @example
+ * ```ts
+ * const route = createNativeRoute({ parseQuery: true, parseCookies: true })
+ * const result = route.run('page=1&limit=20', 'session=abc', null)
+ * // result.flags & ROUTE_FLAG.OK → parse succeeded; result.query = [['page','1'],…]
+ * ```
+ */
+export declare function createNativeRoute(plan?: NativeRoutePlan): NativeRoute;
+/** A matched dynamic route: the handler map + the extracted path params. */
+export interface PathMatch {
+	methods: Record<string, unknown>;
+	params: Record<string, string>;
+}
 /** A raw web-standard route handler (`Request` → `Response`), e.g. the
  *  health/metrics probes (`livenessHandler`, `readinessHandler`,
  *  `healthHandler`, `metricsHandler`). Accepted as `BakedRoute.read` and
@@ -677,6 +834,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;
 	/**
@@ -770,11 +943,6 @@ export interface GracefulShutdownOptions {
  * `process.exit`) to tear down without hanging.
  */
 export declare function gracefulShutdown(handles: ReadonlyArray<ServerHandle>, options?: GracefulShutdownOptions): () => void;
-/** A matched dynamic route: the handler map + the extracted path params. */
-export interface PathMatch {
-	methods: Record<string, unknown>;
-	params: Record<string, string>;
-}
 /** Options for `createWebSocketUpgrade` (supported subprotocols). */ export interface WebSocketUpgradeOptions {
 	/** Subprotocols this server supports; the first client-requested match wins. */
 	protocols?: ReadonlyArray<string>;
@@ -894,15 +1062,25 @@ export interface RustBatch {
 }
 /** Raw packed-wire FFI namespace. */
 export interface RustPacked {
+	/** Packed CRC32 batch: packed `[u8[]]` items → packed u32 results. */
 	crc32BatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed JSON-validity batch: packed `[u8[]]` items → packed 0/1 bitset. */
 	jsonValidBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed email-validator batch: packed `[u8[]]` items → packed 0/1 bitset. */
 	validateEmailBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed UUID-validator batch: packed `[u8[]]` items → packed 0/1 bitset. */
 	validateUuidBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed IPv4-validator batch: packed `[u8[]]` items → packed 0/1 bitset. */
 	validateIpv4BatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed IPv6-validator batch: packed `[u8[]]` items → packed 0/1 bitset. */
 	validateIpv6BatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed JSON-sum batch: packed `[{id}]` docs → packed `[ok u8][sum i64 LE]`. */
 	jsonSumBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed query-string parser batch: packed `[u8[]]` queries → packed pair lists. */
 	queryParseBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed cookie-header parser batch: packed `[u8[]]` headers → packed pair lists. */
 	cookieParseBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed HTTP-request parser batch: packed `[u8[]]` requests → packed request sections. */
 	httpParseRequestBatchPacked(input: Uint8Array): Uint8Array;
 	/** Batch RFC 6902 JSON Patch (two packed lists, zipped) → packed results. */
 	jsonPatchBatchPacked(docs: Uint8Array, patches: Uint8Array): Uint8Array;
@@ -910,41 +1088,69 @@ export interface RustPacked {
 	fnv1A64BatchPacked(input: Uint8Array): Uint8Array;
 	/** Packed ETag batch (10 strong / 12 weak bytes per item). */
 	etagBatchPacked(input: Uint8Array, weak?: boolean | null): Uint8Array;
+	/** Packed percent-encoding batch: packed `[u8[]]` items → packed hex-percent bytes. */
 	urlEncodeBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed percent-decoding batch: packed `[u8[]]` items → packed decoded bytes (string-safe). */
 	urlDecodeBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed percent-decoding batch returning raw bytes (`%FF` preserved). */
 	urlDecodeBytesBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed MIME-lookup batch: packed `[u8[]]` extensions → packed media-type strings. */
 	mimeFromExtensionBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed WebSocket accept-key batch: packed `[u8[]]` keys → packed base64 SHA-1 results. */
 	wsAcceptKeyBatchPacked(input: Uint8Array): Uint8Array;
+	/** Valid JSON count in a packed JSON batch (0..n; invalid items not counted). */
 	jsonValidBatchCountPacked(input: Uint8Array): number;
+	/** Valid-email count in a packed email batch. */
 	validateEmailBatchCountPacked(input: Uint8Array): number;
+	/** Valid-UUID count in a packed UUID batch. */
 	validateUuidBatchCountPacked(input: Uint8Array): number;
+	/** Valid-IPv4 count in a packed IPv4 batch. */
 	validateIpv4BatchCountPacked(input: Uint8Array): number;
+	/** Valid-IPv6 count in a packed IPv6 batch. */
 	validateIpv6BatchCountPacked(input: Uint8Array): number;
+	/** Total `id` sum across a packed JSON batch (valid items only). */
 	jsonSumBatchTotalPacked(input: Uint8Array): number;
+	/** Total packed-output length (bytes) a query batch will produce. */
 	queryParseBatchTotalLenPacked(input: Uint8Array): number;
+	/** Total packed-output length (bytes) a cookie batch will produce. */
 	cookieParseBatchTotalLenPacked(input: Uint8Array): number;
+	/** Total packed-output length (bytes) an HTTP-request batch will produce. */
 	httpParseRequestBatchTotalLenPacked(input: Uint8Array): number;
+	/** Packed Argon2id-hash batch: packed `[u8[]]` passwords + shared salt → packed PHC strings. */
 	passwordHashBatchPacked(input: Uint8Array, salt: Uint8Array, options?: PasswordHashOptions | null): Uint8Array;
 	/** Packed password-verify batch (two packed lists, zipped) → bitset. */
 	passwordVerifyBatchPacked(passwords: Uint8Array, phcs: Uint8Array): Uint8Array;
 	/** Packed URL-resolve batch (two packed lists, zipped) → packed results. */
 	urlResolveBatchPacked(bases: Uint8Array, references: Uint8Array): Uint8Array;
+	/** Packed AEAD-encrypt batch (packed inputs + shared key/nonce) → packed ciphertexts. */
 	aeadEncryptBatchPacked(input: Uint8Array, key: Uint8Array, nonce: Uint8Array, algorithm?: string | null): Uint8Array;
+	/** Packed AEAD-decrypt batch (packed inputs + shared key/nonce) → packed plaintexts. */
 	aeadDecryptBatchPacked(input: Uint8Array, key: Uint8Array, nonce: Uint8Array, algorithm?: string | null): Uint8Array;
+	/** Packed gzip-compress batch: packed `[u8[]]` items → packed gzip streams. */
 	gzipCompressBatchPacked(input: Uint8Array, level?: number | null): Uint8Array;
+	/** Packed gzip-decompress batch (64 MiB cap per item) → packed plaintexts. */
 	gzipDecompressBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed brotli-compress batch: packed `[u8[]]` items → packed brotli streams. */
 	brotliCompressBatchPacked(input: Uint8Array, quality?: number | null): Uint8Array;
+	/** Packed brotli-decompress batch (64 MiB cap per item) → packed plaintexts. */
 	brotliDecompressBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed HS256 JWT-sign batch (packed claims + shared secret) → packed tokens. */
 	jwtSignBatchPacked(input: Uint8Array, secret: Uint8Array, ttlSeconds: number | null, nowSeconds: number): Uint8Array;
+	/** Packed HS256 JWT-verify batch (packed tokens + shared secret) → packed claims/validity. */
 	jwtVerifyBatchPacked(input: Uint8Array, secret: Uint8Array, nowSeconds: number): Uint8Array;
 	/** Batch HMAC-SHA256 sign (packed in → hex-signature byte results). */
 	hmacSha256BatchPacked(input: Uint8Array, key: Uint8Array): Uint8Array;
 	/** Batch HMAC-SHA256 verify (two packed lists: data + hex sigs, zipped) → bitset. */
 	hmacSha256VerifyBatchPacked(input: Uint8Array, sigs: Uint8Array, key: Uint8Array): Uint8Array;
+	/** Packed multipart/form-data parser batch (packed bodies + shared boundary) → packed parts. */
 	multipartParseBatchPacked(input: Uint8Array, boundary: Uint8Array): Uint8Array;
+	/** Packed minijinja template batch: packed contexts + shared source → packed renders. */
 	templateRenderBatchPacked(input: Uint8Array, source: string): Uint8Array;
+	/** Packed SSE-frame batch: packed data + shared event/id/retry → packed frames. */
 	sseEncodeBatchPacked(input: Uint8Array, event: string | null, id: string | null, retry: number | null): Uint8Array;
+	/** Packed WebSocket-frame encode batch: packed payloads + shared opcode/mask/fin → packed frames. */
 	wsFrameEncodeBatchPacked(input: Uint8Array, opcode: number, mask: boolean, fin: boolean): Uint8Array;
+	/** Packed WebSocket-frame decode batch: packed frames → packed (fin, opcode, payload) results. */
 	wsFrameDecodeBatchPacked(input: Uint8Array): Uint8Array;
 }
 /**
@@ -1902,6 +2108,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;
@@ -1981,6 +2209,9 @@ export declare function createIngressRouter(options: CreateIngressRouterOptions)
  *
  * 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 declare function createIngressSync(options?: IngressOptions): SyncIngressHandler;
 /**
@@ -1989,6 +2220,9 @@ export declare function createIngressSync(options?: IngressOptions): SyncIngress
  *
  * 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 declare function createIngress(options?: IngressOptions): IngressHandler;
 /** Readonly snapshot of the ingress decision, safe after `run()` returns. */