castrum 0.9.3 → 0.9.6

package/src/integration/index.ts

@@ -8,22 +8,22 @@
 //   - sseResponse      → server-sent-events response framed on the fast path
 
 export {
+  runMany,
+  runOne,
+  validateCount,
+  validateMany,
+} from './batch'
+export {
+  type CreatePipelineOptions,
   createPipeline,
   type IngressPipeline,
-  type PipelineResult,
   type PipelineContext,
+  type PipelineResult,
   type PreprocessOutcome,
-  type CreatePipelineOptions,
 } from './pipeline'
+export { type SseEvent, sseResponse } from './streaming'
 export {
   createWebSocketUpgrade,
   type WebSocketUpgradeOptions,
   type WebSocketUpgradeResult,
 } from './websocket'
-export { sseResponse, type SseEvent } from './streaming'
-export {
-  validateMany,
-  validateCount,
-  runMany,
-  runOne,
-} from './batch'

package/src/integration/pipeline.ts

@@ -7,18 +7,18 @@
 // context to the app's own handler. `handleRequest` is a fetch-compatible
 // convenience that serves the terminal response or a rendered OK response.
 
+import { readBodyWithLimit } from '../ingress/body'
+import type { BakedIngressResult } from '../ingress/decode/baked-result'
 import {
-  createIngressHandler,
   type BakedIngressRuntime,
+  createIngressHandler,
   type OptimizedIngressHandler,
 } from '../ingress/handlers'
-import type { BakedContext } from '../ingress/types'
 import type { IngressHandlerOptions } from '../ingress/options'
-import { readBodyWithLimit } from '../ingress/body'
-import { DEFAULT_MAX_BODY_BYTES, DEFAULT_BODY_TIMEOUT_MS } from '../ingress/shared'
-import { generateRequestId } from '../shared/request-id'
+import { DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES } from '../ingress/shared'
+import type { BakedContext } from '../ingress/types'
 import { decoder } from '../shared/bytes'
-import type { BakedIngressResult } from '../ingress/decode/baked-result'
+import { generateRequestId } from '../shared/request-id'
 
 /** Readonly snapshot of the ingress decision, safe after `run()` returns. */
 export interface PipelineResult {

package/src/integration/websocket.ts

@@ -1,8 +1,8 @@
 // src/integration/websocket.ts — WebSocket upgrade handshake helper.
 
-import { isBun } from '../shared/runtime'
 import { rust } from '../rust-ffi'
-/** Options for `createWebSocketUpgrade` (supported subprotocols). */export interface WebSocketUpgradeOptions {
+import { isBun } from '../shared/runtime'
+/** Options for `createWebSocketUpgrade` (supported subprotocols). */ export interface WebSocketUpgradeOptions {
   /** Subprotocols this server supports; the first client-requested match wins. */
   protocols?: ReadonlyArray<string>
 }

package/src/loader/index.ts

@@ -27,11 +27,7 @@
 import { rust } from '../rust-ffi'
 import { encoder, viewForArrayBuffer } from '../shared/bytes'
 import type { SchemaValidator } from '../shared/packed'
-import {
-  createLruCache,
-  createTickCoalescer,
-  type LoadRequest,
-} from './batch'
+import { createLruCache, createTickCoalescer, type LoadRequest } from './batch'
 import { createCostModel, nowNs } from './cost'
 import {
   fnvBatchKeysInto,

package/src/loader/ops.ts

@@ -19,10 +19,10 @@
 // the loader never pays a conversion cost on the hot path. This module is the
 // single source of truth for what the loader can dispatch.
 
+import type { PasswordHashOptions } from '../native'
 import { rust } from '../rust-ffi'
 import { addon } from '../rust-ffi/addon'
 import { decoder } from '../shared/bytes'
-import type { PasswordHashOptions } from '../native'
 import type { SchemaValidator } from '../shared/packed'
 
 /** Empty bytes sentinel for skip-on-error scalar parity (e.g. AEAD decrypt). */

package/src/native/ffi/build/codecs.ts

@@ -9,7 +9,7 @@ import { decodeUtf8, encodeUtf8 } from '../../../shared/codec'
 import { SELFTEST_HEX, SELFTEST_JSON } from '../constants'
 import type { BunFFI, Raw3, Raw4, Raw5, Raw6, Raw8, Raw9, Raw10, RawCStr } from '../types'
 import type { BuildCtx } from './util'
-import { argon2PhcLength, cstr, flag, growExact, writeOrThrow } from './util'
+import { allocOut, argon2PhcLength, cstr, flag, growExact, hasNul, writeOrThrow } from './util'
 
 /**
  * Build the codec/crypto/auth methods of the BunFFI surface. `ctx` is
@@ -34,7 +34,17 @@ export function buildCodecs(
   const validateUuid = sym.castrum_validate_uuid as (...a: unknown[]) => number | bigint
   const validateIpv4 = sym.castrum_validate_ipv4 as (...a: unknown[]) => number | bigint
   const validateIpv6 = sym.castrum_validate_ipv6 as (...a: unknown[]) => number | bigint
+  const validateEmailBytes = sym.castrum_validate_email_bytes as (
+    ...a: unknown[]
+  ) => number | bigint
+  const validateUuidBytes = sym.castrum_validate_uuid_bytes as (...a: unknown[]) => number | bigint
+  const validateIpv4Bytes = sym.castrum_validate_ipv4_bytes as (...a: unknown[]) => number | bigint
+  const validateIpv6Bytes = sym.castrum_validate_ipv6_bytes as (...a: unknown[]) => number | bigint
   const jsonSumRaw = sym.castrum_json_sum_ids as Raw4
+  const hexBatchRaw = sym.castrum_hex_validate_batch as Raw5
+  const hexBatchStrRaw = sym.castrum_hex_validate_batch_str as Raw4
+  const regexEscapeRaw = sym.castrum_regex_escape as Raw4
+  const regexEscapeStrRaw = sym.castrum_regex_escape_str as RawCStr
   const hmacVerify = sym.castrum_hmac_sha256_verify as Raw6
   const csrfVerify = sym.castrum_csrf_verify as Raw4
   const passwordVerify = sym.castrum_password_verify as Raw4
@@ -172,10 +182,67 @@ export function buildCodecs(
     },
     urlEncodeInto,
 
-    validateEmail: (input) => Number(validateEmail(input)) === 1,
-    validateUuid: (input) => Number(validateUuid(input)) === 1,
-    validateIpv4: (input) => Number(validateIpv4(input)) === 1,
-    validateIpv6: (input) => Number(validateIpv6(input)) === 1,
+    // Verdict guards: the `cstring` form would truncate at an embedded NUL, so
+    // `"a@b.com\0<script>"` would be reported VALID — a verdict callers act on.
+    // No address / UUID / IP contains U+0000, so short-circuit without an FFI
+    // call (one `indexOf` scan, far cheaper than the encode fallback).
+    validateEmail: (input) => !hasNul(input) && Number(validateEmail(input)) === 1,
+    validateUuid: (input) => !hasNul(input) && Number(validateUuid(input)) === 1,
+    validateIpv4: (input) => !hasNul(input) && Number(validateIpv4(input)) === 1,
+    validateIpv6: (input) => !hasNul(input) && Number(validateIpv6(input)) === 1,
+    // Byte-input validators: `(ptr,len)` — zero transcode (no CString decode
+    // + engine re-encode like the cstring-ARG string forms above).
+    validateEmailBytes: (input) => Number(oneArg(validateEmailBytes, input)) === 1,
+    validateUuidBytes: (input) => Number(oneArg(validateUuidBytes, input)) === 1,
+    validateIpv4Bytes: (input) => Number(oneArg(validateIpv4Bytes, input)) === 1,
+    validateIpv6Bytes: (input) => Number(oneArg(validateIpv6Bytes, input)) === 1,
+    hexValidateBatchInto(input, width, output) {
+      // Batch fixed-width hex validation: NEWLINE-separated lines in; one
+      // verdict byte (1/0) per line out. Needed-size convention: `0` = bad
+      // width / null pointers (real error → throw); `> output.length` = the
+      // exact required size (caller grows once and retries). Width is
+      // validated here so an empty input can't mask it.
+      if (width === 0 || width > 4096) {
+        throw new Error('hex validate batch: width must be 1..=4096')
+      }
+      const w = Number(hexBatchRaw(input, lenOrView(input), width >>> 0, output, lenOrView(output)))
+      return w
+    },
+    regexEscapeInto(input, output) {
+      const w = Number(regexEscapeRaw(input, lenOrView(input), output, lenOrView(output)))
+      if (w === 0) {
+        throw new Error('regex escape: output buffer too small')
+      }
+      return w
+    },
+    // Zero-copy text path: cstring ARG in (engine-transcoded), cstring return
+    // out (engine-cloned) — the JS side does zero encode AND zero decode. A NUL
+    // would truncate the INPUT, so that case routes to the `(ptr,len)` sibling
+    // (exact length) instead of returning a silently shortened string.
+    regexEscapeStr: (input) => {
+      if (!hasNul(input)) return regexEscapeStrRaw(input)
+      const bytes = encodeUtf8(input)
+      const escaped = growExact(
+        (out) => Number(regexEscapeRaw(bytes, lenOrView(bytes), out, lenOrView(out))),
+        16,
+        1 << 20,
+        'regex escape: output buffer too small',
+      )
+      return decodeUtf8(escaped)
+    },
+    hexValidateBatchStr(ids, width, output) {
+      if (width === 0 || width > 4096) {
+        throw new Error('hex validate batch: width must be 1..=4096')
+      }
+      // A NUL in the joined ids would truncate the line list, so a bad id could
+      // pass as its own prefix. Fall back to the byte form (exact length).
+      if (hasNul(ids)) {
+        const bytes = encodeUtf8(ids)
+        return Number(hexBatchRaw(bytes, lenOrView(bytes), width >>> 0, output, lenOrView(output)))
+      }
+      const w = Number(hexBatchStrRaw(ids, width >>> 0, output, lenOrView(output)))
+      return w
+    },
     jsonSumIds: (input) => {
       // Packed [u8 ok][i64 sum LE] output (9 B): ok=1 → valid array (the sum
       // may be 0); ok=0 → invalid input. Bytes written: 9/1/0 (0 = real error).
@@ -202,19 +269,19 @@ export function buildCodecs(
       Number(passwordVerifyBcrypt(password, lenOrView(password), phc)) === 1,
 
     hexDecode(input) {
-      const out = new Uint8Array(Math.floor(input.length / 2))
+      const out = allocOut(Math.floor(input.length / 2))
       const w = hexDecodeInto(input, out)
       return out.subarray(0, w)
     },
     hexDecodeInto,
     urlDecode(input) {
-      const out = new Uint8Array(input.length)
+      const out = allocOut(input.length)
       const w = urlDecodeInto(input, out)
       return out.subarray(0, w)
     },
     urlDecodeInto,
     base64Decode(input, urlSafe, padding) {
-      const out = new Uint8Array(Math.ceil((input.length * 3) / 4))
+      const out = allocOut(Math.ceil((input.length * 3) / 4))
       const w = base64DecodeInto(input, out, urlSafe, padding)
       return out.subarray(0, w)
     },
@@ -398,7 +465,7 @@ export function buildCodecs(
     },
     passwordHashBcrypt(password, cost) {
       // `$2b$CC$` + 22 salt chars + 31 hash chars = 60 chars.
-      const out = new Uint8Array(64)
+      const out = allocOut(64)
       const w = Number(passwordHashBcrypt(password, lenOrView(password), cost, out, lenOrView(out)))
       if (w === 0) {
         throw new Error('password hash bcrypt: output buffer too small')
@@ -409,7 +476,7 @@ export function buildCodecs(
       // Rust clamps dkLen to [1, 1MiB] (PBKDF2_MIN_LEN/MAX_LEN) AFTER sizing its
       // own buffer — so pre-clamp here so dkLen 0 still yields a 1-byte result.
       const dk = Math.min(Math.max(dkLen, 1), 1024 * 1024)
-      const out = new Uint8Array(dk)
+      const out = allocOut(dk)
       const w = Number(
         pbkdf2(
           password,
@@ -429,7 +496,7 @@ export function buildCodecs(
     },
     aeadEncrypt(key, nonce, plaintext, algorithm = 0) {
       // ciphertext + 16-byte auth tag.
-      const out = new Uint8Array(plaintext.length + 16)
+      const out = allocOut(plaintext.length + 16)
       const w = Number(
         aeadEncrypt(
           key,
@@ -472,7 +539,7 @@ export function buildCodecs(
       return w
     },
     aeadDecrypt(key, nonce, ciphertext, algorithm = 0) {
-      const out = new Uint8Array(ciphertext.length)
+      const out = allocOut(ciphertext.length)
       const w = Number(
         aeadDecrypt(
           key,
@@ -534,6 +601,17 @@ export function selfTestCodecs(b: BunFFI): boolean {
   ) {
     return false
   }
+  // Byte-input validator siblings: `(ptr,len)` parity with the string forms.
+  if (
+    !b.validateEmailBytes(enc.encode('a@b.com')) ||
+    !b.validateUuidBytes(enc.encode('550e8400-e29b-41d4-a716-446655440000')) ||
+    !b.validateIpv4Bytes(enc.encode('192.168.0.1')) ||
+    !b.validateIpv6Bytes(enc.encode('2001:db8::1')) ||
+    b.validateEmailBytes(enc.encode('not-an-email')) ||
+    b.validateIpv6Bytes(enc.encode('999'))
+  ) {
+    return false
+  }
   // Packed `[u8 ok][i64 sum LE]` ABI: legit zero-sum is ok, invalid input throws.
   if (b.jsonSumIds(enc.encode(`[{"id":1},{"id":2}]`)) !== 3n) return false
   if (b.jsonSumIds(enc.encode(`[{"id":0},{"id":0}]`)) !== 0n) return false
@@ -545,6 +623,46 @@ export function selfTestCodecs(b: BunFFI): boolean {
   }
   if (!sumInvalidThrew) return false
 
+  // Batch fixed-width hex validation (needed-size convention + verdicts).
+  {
+    const ids = enc.encode('507f1f77bcf86cd799439011\nzz\n507F1F77BCF86CD799439012')
+    const tiny = new Uint8Array(2)
+    const needed = b.hexValidateBatchInto(ids, 24, tiny)
+    if (needed !== 3) return false // exact required size on a too-small buffer
+    const out = new Uint8Array(needed)
+    if (b.hexValidateBatchInto(ids, 24, out) !== 3) return false
+    if (out[0] !== 1 || out[1] !== 0 || out[2] !== 1) return false
+    let widthThrew = false
+    try {
+      b.hexValidateBatchInto(ids, 0, new Uint8Array(3))
+    } catch {
+      widthThrew = true
+    }
+    if (!widthThrew) return false
+  }
+
+  // RegExp escaping: metachars get backslashes; plain text is untouched.
+  {
+    const out = new Uint8Array(64)
+    const w = b.regexEscapeInto(enc.encode('a.c(x)'), out)
+    if (w !== 9 || dec.decode(out.subarray(0, w)) !== 'a\\.c\\(x\\)') return false
+    const plain = new Uint8Array(16)
+    const wp = b.regexEscapeInto(enc.encode('hello'), plain)
+    if (wp !== 5 || dec.decode(plain.subarray(0, wp)) !== 'hello') return false
+    // too-small buffer reports the exact required size
+    if (b.regexEscapeInto(enc.encode('a.b'), new Uint8Array(2)) !== 4) return false
+    // zero-copy str sibling must produce the identical escaped string
+    if (b.regexEscapeStr('a.c(x)') !== 'a\\.c\\(x\\)') return false
+    if (b.regexEscapeStr('plain text') !== 'plain text') return false
+  }
+
+  // String-input batch hex validation (cstring ARG sibling).
+  {
+    const out = new Uint8Array(8)
+    const w = b.hexValidateBatchStr('507f1f77bcf86cd799439011\nzz', 24, out)
+    if (w !== 2 || out[0] !== 1 || out[1] !== 0) return false
+  }
+
   // HMAC RFC 4231 test case 1 (0x0b × 20 key, "Hi There" data).
   const hmacKey = new Uint8Array(20).fill(0x0b)
   const hmacData = enc.encode('Hi There')

package/src/native/ffi/build/compress.ts

@@ -29,7 +29,7 @@ export function buildCompress(
   sym: Record<string, (...a: unknown[]) => unknown>,
   ctx: BuildCtx,
 ): Partial<BunFFI> {
-  const { lenOrView } = ctx
+  const { lenOrView, scratchFor } = ctx
 
   const gzipCompress = sym.castrum_gzip_compress as Raw5
   const gzipDecompress = sym.castrum_gzip_decompress as Raw5
@@ -40,15 +40,19 @@ export function buildCompress(
 
   return {
     jsonPatch(doc, patch) {
-      return decodeUtf8(
-        growExact(
-          (out) =>
-            Number(jsonPatch(doc, lenOrView(doc), patch, lenOrView(patch), out, lenOrView(out))),
-          Math.min(Math.max(doc.length, patch.length) + 16, 64 * 1024),
-          MAX_JSON_PATCH_OUTPUT,
-          'json patch: output buffer too small or patch inapplicable',
-        ),
-      )
+      // Pooled scratch — the patched doc is decoded to an immutable string
+      // synchronously (same call-scope contract as the cstring returns), so
+      // the bytes never need a fresh buffer. One exact retry on miss.
+      let out = scratchFor(Math.min(Math.max(doc.length, patch.length) + 16, 64 * 1024))
+      let w = Number(jsonPatch(doc, lenOrView(doc), patch, lenOrView(patch), out, lenOrView(out)))
+      if (w > out.length && w <= MAX_JSON_PATCH_OUTPUT) {
+        out = new Uint8Array(w)
+        w = Number(jsonPatch(doc, lenOrView(doc), patch, lenOrView(patch), out, lenOrView(out)))
+      }
+      if (w === 0 || w > out.length) {
+        throw new Error('json patch: output buffer too small or patch inapplicable')
+      }
+      return decodeUtf8(out.subarray(0, w))
     },
     gzipCompress(data, level = 6) {
       // The C ABI streams the compressed output directly into `out` (no internal
@@ -113,6 +117,14 @@ export function buildCompress(
       }
       return w
     },
+    /**
+     * gzip ISIZE probe → uncompressed size for a single-member stream, or `0`
+     * when unknown. Used to PRE-SIZE a destination buffer for the zero-copy
+     * task path (one pass, no intermediate buffer, no retry in the common case).
+     */
+    gzipIsize(data) {
+      return Number(gzipIsize(data, lenOrView(data)))
+    },
     brotliCompress(data, quality = 5) {
       // Same cap rationale as gzipCompress (streaming core); growExact for
       // incompressible data.

package/src/native/ffi/build/instances.ts

@@ -8,9 +8,9 @@
 
 import { decodeUtf8, encodeUtf8 } from '../../../shared/codec'
 import { EMPTY_VIEW } from '../constants'
-import type { BunFFI, Raw2, Raw3, Raw5, Raw6, Raw7, Raw8, Raw12, RawCStr } from '../types'
+import type { BunFFI, Raw2, Raw3, Raw4, Raw5, Raw6, Raw7, Raw8, Raw12, RawCStr } from '../types'
 import type { BuildCtx } from './util'
-import { cstr, growExact, unpackRateCheck } from './util'
+import { cstr, growExact, hasNul, unpackRateCheck } from './util'
 
 /**
  * Build the opaque-handle methods of the BunFFI surface. `ctx` is destructured
@@ -25,8 +25,9 @@ export function buildInstances(
   const conditionalIsNotModifiedRaw = sym.castrum_conditional_is_not_modified as Raw6
   const mediaTypeMatcherMatchesRaw = sym.castrum_media_type_matcher_matches as Raw3
   const acceptNegotiatorNegotiateRaw = sym.castrum_accept_negotiator_negotiate as RawCStr
-  const acceptNegotiatorNegotiateServerRaw = sym
-    .castrum_accept_negotiator_negotiate_server as (...a: unknown[]) => string | null
+  const acceptNegotiatorNegotiateServerRaw = sym.castrum_accept_negotiator_negotiate_server as (
+    ...a: unknown[]
+  ) => string | null
   const ed25519GenerateKeypairRaw = sym.castrum_ed25519_generate_keypair as Raw2
   const ed25519SignRaw = sym.castrum_ed25519_sign as Raw6
   const ed25519VerifyRaw = sym.castrum_ed25519_verify as Raw6
@@ -36,6 +37,10 @@ export function buildInstances(
   const jwtSignerVerifyRaw = sym.castrum_jwt_signer_verify as Raw6
   const templateRenderRaw = sym.castrum_template_render as Raw5
   const schemaValidatorValidateRaw = sym.castrum_schema_validator_validate as Raw3
+  const queryValidateSym = sym.castrum_query_validate as (...a: unknown[]) => number | bigint
+  const cookieValidateSym = sym.castrum_cookie_validate as (...a: unknown[]) => number | bigint
+  const sessionSealSym = sym.castrum_session_seal as (...a: unknown[]) => string | null
+  const sessionOpenSym = sym.castrum_session_open as Raw4
   const rateLimiterCheckRaw = sym.castrum_rate_limiter_check as Raw5
   const rateLimiterCheckKeyRaw = sym.castrum_rate_limiter_check_key as Raw5
   const jwtSignBytes = sym.castrum_jwt_sign_bytes as RawCStr
@@ -138,6 +143,27 @@ export function buildInstances(
     schemaValidatorValidate(inner, doc) {
       return Number(schemaValidatorValidateRaw(inner, doc, lenOrView(doc))) === 1
     },
+    queryValidate(inner, qs) {
+      // `qs` is a cstring ARG — engine-transcoded (zero JS encode). A raw NUL is
+      // not a valid query byte, and it would TRUNCATE the arg so only a prefix
+      // got validated: a gate that says "this query passed" must not be foolable.
+      if (hasNul(qs)) return false
+      return Number(queryValidateSym(inner, qs)) === 1
+    },
+    cookieValidate(inner, header) {
+      // Same contract as `queryValidate`: a NUL would validate only a prefix.
+      if (hasNul(header)) return false
+      return Number(cookieValidateSym(inner, header)) === 1
+    },
+    sessionSeal(id, dataJson, expSecs, secret) {
+      // exp is an i64 C arg → BigInt.
+      return sessionSealSym(id, dataJson, BigInt(expSecs), secret)
+    },
+    sessionOpen(token, secret, output) {
+      // Needed-size convention; 0 = bad signature / malformed.
+      const w = Number(sessionOpenSym(token, secret, output, lenOrView(output)))
+      return w
+    },
     rateLimiterCheck(inner, key, nowMs) {
       // Packed [u8 allowed][u32 remaining LE][i64 reset_ms LE] (13 bytes).
       // Reused scratch + cached DataView (no per-call allocs). `key` is a
@@ -583,6 +609,22 @@ export function selfTestInstances(b: BunFFI): boolean {
   if (!urlBuilderThrew) {
     return false
   }
+  // Wire-validate: null inner (0) → false (ABI exercise); real parity lives
+  // in ffi.test.ts with a live compiled instance.
+  if (b.queryValidate(0, 'route=/a') !== false) return false
+  if (b.cookieValidate(0, 'route=/a') !== false) return false
+
+  // Session seal/open round trip through the C ABI.
+  {
+    const tok = b.sessionSeal('sess-9', '{"n":1}', 1234567, 'sekrit')
+    if (tok === null || !tok.includes('.') || !tok.startsWith('{"id":"sess-9"')) return false
+    const out = new Uint8Array(256)
+    const w = b.sessionOpen(tok, 'sekrit', out)
+    if (w <= 13 || out[0] !== 1) return false
+    // bad signature → 0
+    if (b.sessionOpen(tok, 'wrong', out) !== 0) return false
+  }
+
   // rateLimiterCheckKey: null (0) handle → throw (ABI exercise).
   let rlKeyThrew = false
   try {