castrum 0.7.0 → 0.9.0

package/src/rust-ffi/scalar/factories.ts

@@ -0,0 +1,233 @@
+// src/rust-ffi/scalar/factories.ts — Compiled-once instance factories + rayon runtime.
+//
+// Every `create*` here constructs a compiled-once native instance (key / schema
+// / template precompiled at construction) plus the rayon thread-pool controls.
+
+import { asNumber } from '../options'
+import { getBunFFI, type BunFFI } from '../../native/ffi'
+import type { RustClientContext } from '../context'
+import type {
+  HmacSignerInstance,
+  SchemaValidatorInstance,
+  TemplateRendererInstance,
+  FormParserInstance,
+  MediaTypeParserInstance,
+  MediaTypeMatcherInstance,
+  ConditionalRequestInstance,
+  AcceptNegotiatorInstance,
+  Base64CodecInstance,
+  CookieSignerInstance,
+  CsrfProtectorInstance,
+  UrlBuilderInstance,
+  JwtSignerInstance,
+  AeadCipherInstance,
+  Argon2HasherInstance,
+  RateLimiterInstance,
+  PasswordHashOptions,
+} from '../../native'
+
+// ── FFI-backed instance wrappers ───────────────────────────────────────────
+// On Bun, instances whose methods have a STATELESS C-ABI sibling are backed by
+// the `bun:ffi` fast path instead of a NAPI instance — cutting the per-call
+// NAPI crossing (~300ns) to ~20ns. The precompiled-state benefit is mostly
+// lost (e.g. the HMAC key is rebuilt per call, ~100ns), but that is still far
+// cheaper than a NAPI crossing, so these win under Bun. Byte-for-byte output is
+// guaranteed by the ffi cross-check suite. NAPI instances remain the fallback
+// (Node / CASTRUM_FFI_MODE=napi / failed self-test). Instances with genuinely
+// stateful precompiled cores (SchemaValidator, TemplateRenderer,
+// AcceptNegotiator, ConditionalRequest, MediaTypeMatcher/Parser, UrlBuilder,
+// RateLimiter) stay NAPI — they need opaque handles (deferred).
+
+function ffiHmacSigner(key: Uint8Array, ffi: BunFFI): HmacSignerInstance {
+  return {
+    sign(data) {
+      return ffi.hmacSha256(key, data)
+    },
+    verify(data, sig) {
+      return ffi.hmacSha256Verify(key, data, sig)
+    },
+  }
+}
+
+function ffiBase64Codec(
+  urlSafe: boolean | undefined,
+  padding: boolean | undefined,
+  ffi: BunFFI,
+): Base64CodecInstance {
+  return {
+    encode(input) {
+      return ffi.base64Encode(input, urlSafe, padding)
+    },
+    decode(input) {
+      return ffi.base64Decode(input, urlSafe, padding)
+    },
+  }
+}
+
+function ffiCookieSigner(secret: Uint8Array, ffi: BunFFI): CookieSignerInstance {
+  return {
+    sign(value) {
+      return ffi.signCookie(value, secret)
+    },
+    verify(signed) {
+      return ffi.verifyCookie(signed, secret)
+    },
+  }
+}
+
+function ffiCsrfProtector(secret: Uint8Array, ffi: BunFFI): CsrfProtectorInstance {
+  return {
+    create() {
+      return ffi.csrfToken(secret)
+    },
+    verify(token) {
+      return ffi.csrfVerify(token, secret)
+    },
+  }
+}
+
+function ffiArgon2Hasher(
+  options: PasswordHashOptions | null | undefined,
+  ffi: BunFFI,
+): Argon2HasherInstance {
+  // Resolve the napi defaults (rust/crypto/argon2.rs resolve_opts) — mirrors
+  // the scalar passwordHash FFI wrapper (crypto.ts).
+  const o = options ?? {}
+  const mCost = o.mCost ?? 19456
+  const tCost = o.tCost ?? 2
+  const pCost = o.pCost ?? 1
+  const outLen = o.outLen ?? 32
+  return {
+    hash(password, salt) {
+      return ffi.passwordHash(password, salt, mCost, tCost, pCost, outLen)
+    },
+    verify(password, phc) {
+      return ffi.passwordVerify(password, phc)
+    },
+  }
+}
+
+function ffiAeadCipher(
+  key: Uint8Array,
+  algorithm: string | undefined,
+  ffi: BunFFI,
+): AeadCipherInstance {
+  // Mirror the napi constructor's validation (rust/crypto/aead.rs
+  // `resolve_algorithm`): only aes-256-gcm (default) and chacha20-poly1305 are
+  // accepted; anything else throws at construction, NOT at first use.
+  if (algorithm !== undefined && algorithm !== 'aes-256-gcm' && algorithm !== 'chacha20-poly1305') {
+    throw new Error(
+      `unsupported aead algorithm: ${algorithm} (expected aes-256-gcm | chacha20-poly1305)`,
+    )
+  }
+  const alg = algorithm === 'chacha20-poly1305' ? 1 : 0
+  return {
+    encrypt(nonce, plaintext) {
+      return ffi.aeadEncrypt(key, nonce, plaintext, alg)
+    },
+    decrypt(nonce, ciphertext) {
+      return ffi.aeadDecrypt(key, nonce, ciphertext, alg)
+    },
+  }
+}
+
+function ffiFormParser(ffi: BunFFI): FormParserInstance {
+  return {
+    parse(input) {
+      // Sizing matches the scalar formParsePacked path (Rust allocator bound
+      // `input.len() * 9 + 16`).
+      const out = new Uint8Array(input.length * 9 + 16)
+      const w = ffi.formParsePackedInto(input, out)
+      return out.subarray(0, w)
+    },
+    parseInto(input, output) {
+      return ffi.formParsePackedInto(input, output)
+    },
+  }
+}
+
+/** Compiled-once factory + runtime-control methods (`Pick<RustScalar, ...>`). */
+export function buildFactories(ctx: RustClientContext) {
+  const { addon } = ctx
+
+  return {
+    createSchemaValidator(schema: Uint8Array): SchemaValidatorInstance {
+      return new addon.SchemaValidator(schema)
+    },
+    createHmacSigner(key: Uint8Array): HmacSignerInstance {
+      const ffi = getBunFFI()
+      if (ffi) return ffiHmacSigner(key, ffi)
+      return new addon.HmacSigner(key)
+    },
+    createTemplateRenderer(source: string): TemplateRendererInstance {
+      return new addon.TemplateRenderer(source)
+    },
+    createFormParser(capacity?: number): FormParserInstance {
+      const ffi = getBunFFI()
+      if (ffi) return ffiFormParser(ffi)
+      return new addon.FormParser(capacity)
+    },
+    createMediaTypeParser(): MediaTypeParserInstance {
+      return new addon.MediaTypeParser()
+    },
+    createConditionalRequest(
+      etagValue: Uint8Array,
+      lastModifiedSecs?: number,
+    ): ConditionalRequestInstance {
+      return new addon.ConditionalRequest(etagValue, lastModifiedSecs ?? undefined)
+    },
+    createAcceptNegotiator(supported: string[]): AcceptNegotiatorInstance {
+      return new addon.AcceptNegotiator(supported)
+    },
+    createBase64Codec(urlSafe?: boolean, padding?: boolean): Base64CodecInstance {
+      const ffi = getBunFFI()
+      if (ffi) return ffiBase64Codec(urlSafe, padding, ffi)
+      return new addon.Base64Codec(urlSafe ?? undefined, padding ?? undefined)
+    },
+    createCookieSigner(secret: Uint8Array): CookieSignerInstance {
+      const ffi = getBunFFI()
+      if (ffi) return ffiCookieSigner(secret, ffi)
+      return new addon.CookieSigner(secret)
+    },
+    createCsrfProtector(secret: Uint8Array): CsrfProtectorInstance {
+      const ffi = getBunFFI()
+      if (ffi) return ffiCsrfProtector(secret, ffi)
+      return new addon.CsrfProtector(secret)
+    },
+    createUrlBuilder(base: Uint8Array): UrlBuilderInstance {
+      return new addon.UrlBuilder(base)
+    },
+    createJwtSigner(secret: Uint8Array, ttlSeconds?: number): JwtSignerInstance {
+      return new addon.JwtSigner(secret, ttlSeconds ?? undefined)
+    },
+    createAeadCipher(key: Uint8Array, algorithm?: string): AeadCipherInstance {
+      const ffi = getBunFFI()
+      if (ffi) return ffiAeadCipher(key, algorithm, ffi)
+      return new addon.AeadCipher(key, algorithm ?? undefined)
+    },
+    createArgon2Hasher(options?: PasswordHashOptions | null): Argon2HasherInstance {
+      const ffi = getBunFFI()
+      if (ffi) return ffiArgon2Hasher(options, ffi)
+      return new addon.Argon2Hasher(options ?? undefined)
+    },
+    createMediaTypeMatcher(expected: Uint8Array): MediaTypeMatcherInstance {
+      return new addon.MediaTypeMatcher(expected)
+    },
+    createRateLimiter(
+      limit: number,
+      windowMs: number,
+      maxEntries?: number | null,
+    ): RateLimiterInstance {
+      return new addon.RateLimiter(limit, windowMs, maxEntries ?? undefined)
+    },
+    initThreadPool(threads?: number): void {
+      // Explicit user call also establishes the pool state locally.
+      ctx.markPoolInitialized()
+      if (threads !== undefined) ctx.setPendingThreads(threads)
+      addon.initThreadPool(threads)
+    },
+    rayonNumThreads(): number {
+      return asNumber(addon.rayonNumThreads() as unknown)
+    },
+  }
+}

package/src/rust-ffi/scalar/hashing.ts

@@ -0,0 +1,72 @@
+// src/rust-ffi/scalar/hashing.ts — Hashing scalar methods.
+//
+// Mirrors rust/crypto/hashing.rs + hmac_sha256.rs: crc32 / fnv1a64 / HMAC.
+// (HMAC reuses the context-cached signer to avoid re-constructing the key.)
+
+import { asBigInt, asNumber } from '../options'
+import { resolveNative, type RustClientContext } from '../context'
+import { getBunFFI } from '../../native/ffi'
+import { isBun } from '../../shared/runtime'
+
+const hexEncoder = new TextEncoder()
+
+/** Hashing scalar methods (`Pick<RustScalar, ...>`). */
+export function buildHashing(ctx: RustClientContext) {
+  // Bun fast path: `bun:ffi` JIT-calls the C ABI exports with ~1/4 the crossing
+  // cost of napi for these sub-µs hashes. `getBunFFI()` is lazy (binds on first
+  // use, ~2ns cached check) and null when unavailable / self-test fails.
+  return {
+    crc32(input: Uint8Array): number {
+      // Optimal by default under Bun: `Bun.hash.crc32` (native SIMD) beats the
+      // rust+FFI crossing (~2.8-8.4x, decision matrix) and matches the
+      // `BUN_WINS`/`opImpl` recommendation. Node keeps the addon.
+      // `>>> 0` preserves the unsigned-32 contract.
+      if (isBun()) return Bun.hash.crc32(input) >>> 0
+      const ffi = getBunFFI()
+      if (ffi) return ffi.crc32(input)
+      return asNumber(resolveNative(ctx, 'crc32')(input)) >>> 0
+    },
+    fnv1a64(input: Uint8Array): bigint {
+      const ffi = getBunFFI()
+      if (ffi) return ffi.fnv1a64(input)
+      return asBigInt(resolveNative(ctx, 'fnv1a64')(input))
+    },
+    xxh3(input: Uint8Array): bigint {
+      // Optimal by default under Bun: `Bun.hash.xxHash3` beats the rust+FFI
+      // crossing (~4x, decision matrix). Node keeps the addon.
+      if (isBun()) return Bun.hash.xxHash3(input)
+      const ffi = getBunFFI()
+      if (ffi) return ffi.xxh3(input)
+      return asBigInt(resolveNative(ctx, 'xxh3')(input))
+    },
+    hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array {
+      // Optimal by default under Bun: `Bun.CryptoHasher` (native) beats the
+      // rust+FFI crossing (~1.2x, decision matrix). Re-encoded to hex to match
+      // castrum's hex-return contract (64 lowercase-hex bytes — same as the
+      // addon). Node keeps the FFI path (`hmacSha256` is classified "proven"
+      // vs the node:crypto baseline). Napi fallback keeps the precompiled-key
+      // `HmacSigner` (identity semantics).
+      if (isBun()) {
+        const hasher = new Bun.CryptoHasher('sha256', key)
+        hasher.update(data)
+        return hexEncoder.encode(Buffer.from(hasher.digest()).toString('hex'))
+      }
+      const ffi = getBunFFI()
+      if (ffi) return ffi.hmacSha256(key, data)
+      return ctx.hmacSigner(key).sign(data)
+    },
+    hmacSha256Into(key: Uint8Array, data: Uint8Array, output: Uint8Array): number {
+      const ffi = getBunFFI()
+      if (ffi) return ffi.hmacSha256Into(key, data, output)
+      const bytes = ctx.hmacSigner(key).sign(data)
+      if (output.length < bytes.length) throw new Error('hmac sha256: output buffer too small')
+      output.set(bytes)
+      return bytes.length
+    },
+    hmacSha256Verify(key: Uint8Array, data: Uint8Array, sig: Uint8Array): boolean {
+      const ffi = getBunFFI()
+      if (ffi) return ffi.hmacSha256Verify(key, data, sig)
+      return ctx.hmacSigner(key).verify(data, sig)
+    },
+  }
+}

package/src/rust-ffi/scalar/http.ts

@@ -0,0 +1,206 @@
+// src/rust-ffi/scalar/http.ts — HTTP wire-format + parsing scalar methods.
+//
+// Mirrors rust/http/* (packed parsers, media type, etag, HTTP dates,
+// Accept-Encoding, URL codec/join, MIME lookup) plus the `util/validation`
+// validators and the WebSocket accept-key.
+
+import type { EncodingPrefResult, MediaTypeResult } from '../../native'
+import { getBunFFI } from '../../native/ffi'
+import { decoder, encoder } from '../../shared/bytes'
+import { isBun } from '../../shared/runtime'
+import { type RustClientContext, resolveNative } from '../context'
+
+// Mirror napi `url_decode`'s UTF-8 validation (rust/http/url_codec.rs): only
+// validate when a high byte is present (the ASCII fast path skips it — same as
+// Rust's saw_high check). `url_decode_bytes` / `url_decode_into` skip the check
+// entirely, so those ffi bindings are byte-faithful with no extra work.
+const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true })
+function ensureValidUtf8(bytes: Uint8Array): void {
+  for (let i = 0; i < bytes.length; i++) {
+    if ((bytes[i] ?? 0) >= 0x80) {
+      try {
+        FATAL_UTF8.decode(bytes)
+      } catch {
+        throw new Error('url decode: invalid UTF-8 in decoded output')
+      }
+      return
+    }
+  }
+}
+
+/** HTTP / parsing scalar methods (`Pick<RustScalar, ...>`). */
+export function buildHttp(ctx: RustClientContext) {
+  // Resolve the native fns through the shared first-use cache so the hot
+  // scalar path skips the lazy-addon Proxy get on every call.
+  const n = (name: string) => resolveNative(ctx, name)
+
+  return {
+    mimeFromExtension(ext: Uint8Array): Uint8Array {
+      return ctx.cachedMime(ext)
+    },
+    urlEncode(input: Uint8Array): Uint8Array {
+      // Under Bun, Bun's native `encodeURIComponent` beats the rust+FFI/NAPI
+      // crossing (~4x on the string path, ~1.3x on bytes) and skips the C-ABI
+      // call entirely — see docs/bun-builtins-decision-matrix.md. Parity is
+      // pinned by test/unit/features/url.test.ts (byte-for-byte, incl.
+      // unicode/emoji); `urlEncode` is always applied to text, so the
+      // bytes→string→encode→bytes round-trip is lossless.
+      if (isBun()) return encoder.encode(encodeURIComponent(decoder.decode(input)))
+      const ffi = getBunFFI()
+      if (ffi) return ffi.urlEncode(input)
+      return n('urlEncode')(input) as Uint8Array
+    },
+    urlDecode(input: Uint8Array): Uint8Array {
+      // Same rationale as `urlEncode`; the strict `urlDecode` already throws on
+      // invalid UTF-8 (ensureValidUtf8 below), matching decodeURIComponent's
+      // URIError (a subclass of Error), so the JS path is behavior-equivalent.
+      if (isBun()) return encoder.encode(decodeURIComponent(decoder.decode(input)))
+      const ffi = getBunFFI()
+      if (ffi) {
+        const out = ffi.urlDecode(input)
+        // napi `url_decode` validates UTF-8 (only when a high byte is present);
+        // `url_decode_bytes`/`url_decode_into` do not. This is the strict one.
+        ensureValidUtf8(out)
+        return out
+      }
+      return n('urlDecode')(input) as Uint8Array
+    },
+    urlDecodeBytes(input: Uint8Array): Uint8Array {
+      const ffi = getBunFFI()
+      if (ffi) return ffi.urlDecode(input) // byte semantics match url_decode_bytes
+      return n('urlDecodeBytes')(input) as Uint8Array
+    },
+    urlEncodeInto(input: Uint8Array, output: Uint8Array): number {
+      const ffi = getBunFFI()
+      if (ffi) return ffi.urlEncodeInto(input, output)
+      return n('urlEncodeInto')(input, output) as number
+    },
+    urlDecodeInto(input: Uint8Array, output: Uint8Array): number {
+      const ffi = getBunFFI()
+      if (ffi) return ffi.urlDecodeInto(input, output) // no UTF-8 check, matches napi
+      return n('urlDecodeInto')(input, output) as number
+    },
+    validateEmail(input: Uint8Array): boolean {
+      const ffi = getBunFFI()
+      if (ffi) return ffi.validateEmail(input)
+      return n('validateEmail')(input) as boolean
+    },
+    validateUuid(input: Uint8Array): boolean {
+      const ffi = getBunFFI()
+      if (ffi) return ffi.validateUuid(input)
+      return n('validateUuid')(input) as boolean
+    },
+    validateIpv4(input: Uint8Array): boolean {
+      const ffi = getBunFFI()
+      if (ffi) return ffi.validateIpv4(input)
+      return n('validateIpv4')(input) as boolean
+    },
+    validateIpv6(input: Uint8Array): boolean {
+      const ffi = getBunFFI()
+      if (ffi) return ffi.validateIpv6(input)
+      return n('validateIpv6')(input) as boolean
+    },
+    wsAcceptKey(key: Uint8Array): Uint8Array {
+      const ffi = getBunFFI()
+      if (ffi) return ffi.wsAcceptKey(key)
+      return n('wsAcceptKey')(key) as Uint8Array
+    },
+    httpParseRequestPacked(input: Uint8Array): Uint8Array {
+      const ffi = getBunFFI()
+      if (ffi) {
+        const out = new Uint8Array(input.length * 9 + 16)
+        const w = ffi.httpParseRequestPackedInto(input, out)
+        return out.subarray(0, w)
+      }
+      return n('httpParseRequestPacked')(input) as Uint8Array
+    },
+    httpParseRequestPackedInto(input: Uint8Array, output: Uint8Array): number {
+      const ffi = getBunFFI()
+      if (ffi) return ffi.httpParseRequestPackedInto(input, output)
+      return n('httpParseRequestPackedInto')(input, output) as number
+    },
+    queryParsePacked(input: Uint8Array): Uint8Array {
+      const ffi = getBunFFI()
+      if (ffi) {
+        const out = new Uint8Array(input.length * 9 + 16)
+        const w = ffi.queryParsePackedInto(input, out)
+        return out.subarray(0, w)
+      }
+      return n('queryParsePacked')(input) as Uint8Array
+    },
+    queryParsePackedInto(input: Uint8Array, output: Uint8Array): number {
+      const ffi = getBunFFI()
+      if (ffi) return ffi.queryParsePackedInto(input, output)
+      return n('queryParsePackedInto')(input, output) as number
+    },
+    cookieParsePacked(input: Uint8Array): Uint8Array {
+      const ffi = getBunFFI()
+      if (ffi) {
+        const out = new Uint8Array(input.length * 9 + 16)
+        const w = ffi.cookieParsePackedInto(input, out)
+        return out.subarray(0, w)
+      }
+      return n('cookieParsePacked')(input) as Uint8Array
+    },
+    cookieParsePackedInto(input: Uint8Array, output: Uint8Array): number {
+      const ffi = getBunFFI()
+      if (ffi) return ffi.cookieParsePackedInto(input, output)
+      return n('cookieParsePackedInto')(input, output) as number
+    },
+    formParsePacked(input: Uint8Array): Uint8Array {
+      const ffi = getBunFFI()
+      if (ffi) {
+        // x-www-form-urlencoded uses the SAME packed-pairs core as query parse.
+        const out = new Uint8Array(input.length * 9 + 16)
+        const w = ffi.formParsePackedInto(input, out)
+        return out.subarray(0, w)
+      }
+      return n('formParsePacked')(input) as Uint8Array
+    },
+    parseMediaType(input: Uint8Array): MediaTypeResult {
+      const r = n('parseMediaType')(input) as MediaTypeResult
+      // napi serializes Option fields as undefined; normalize to null to match
+      // the declared `string | null` public type.
+      return {
+        mediaType: r.mediaType,
+        charset: r.charset ?? null,
+        boundary: r.boundary ?? null,
+        params: r.params,
+      }
+    },
+    etag(data: Uint8Array, weak?: boolean): Uint8Array {
+      const ffi = getBunFFI()
+      if (ffi) return ffi.etag(data, weak)
+      return n('etag')(data, weak ?? undefined) as Uint8Array
+    },
+    etagInto(data: Uint8Array, output: Uint8Array, weak?: boolean): number {
+      const ffi = getBunFFI()
+      if (ffi) return ffi.etagInto(data, output, weak)
+      return n('etagInto')(data, output, weak ?? undefined) as number
+    },
+    httpDate(secs?: number): Uint8Array {
+      // Bun's Date.toUTCString (RFC 1123 IMF-fixdate) beats the rust+FFI
+      // crossing (~3.7x, measured); output is byte-identical for HTTP timestamps.
+      if (isBun()) {
+        const t = secs ?? Math.floor(Date.now() / 1000)
+        return encoder.encode(new Date(t * 1000).toUTCString())
+      }
+      return n('httpDate')(secs ?? undefined) as Uint8Array
+    },
+    httpDateInto(secs: number | undefined, output: Uint8Array): number {
+      return n('httpDateInto')(secs ?? undefined, output) as number
+    },
+    parseHttpDate(input: Uint8Array): bigint | null {
+      return n('parseHttpDate')(input) as bigint | null
+    },
+    parseAcceptEncoding(input: Uint8Array): EncodingPrefResult[] {
+      return n('parseAcceptEncoding')(input) as EncodingPrefResult[]
+    },
+    urlResolve(base: Uint8Array, reference: Uint8Array): Uint8Array {
+      return n('urlResolve')(base, reference) as Uint8Array
+    },
+    urlEncodeQuery(params: Record<string, string>): Uint8Array {
+      return n('urlEncodeQuery')(params) as Uint8Array
+    },
+  }
+}

package/src/rust-ffi/scalar/index.ts

@@ -0,0 +1,31 @@
+// src/rust-ffi/scalar/index.ts — Scalar + feature FFI methods (barrel).
+//
+// The byte-level single-value methods of the Rust client (crc32, hmac, json,
+// jwt, password, aead, compress, ... plus the class factories and runtime
+// controls). Composed into the client by ./client.ts.
+//
+// The `RustScalar` interface (the public surface, with its perf JSDoc) lives
+// in `interface.ts`; the implementation is split into domain builders mirroring
+// `rust/` (hashing, json, http, crypto, payload, factories).
+
+import type { RustClientContext } from '../context'
+import { buildHashing } from './hashing'
+import { buildJson } from './json'
+import { buildHttp } from './http'
+import { buildCrypto } from './crypto'
+import { buildPayload } from './payload'
+import { buildFactories } from './factories'
+
+export type { RustScalar } from './interface'
+
+/** Build the scalar/feature method set for a client context. */
+export function buildScalar(ctx: RustClientContext): import('./interface').RustScalar {
+  return {
+    ...buildHashing(ctx),
+    ...buildJson(ctx),
+    ...buildHttp(ctx),
+    ...buildCrypto(ctx),
+    ...buildPayload(ctx),
+    ...buildFactories(ctx),
+  }
+}