castrum 0.9.0 → 0.9.2

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

@@ -3,28 +3,30 @@
 // 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,
+  AeadCipherInstance,
+  Argon2HasherInstance,
   Base64CodecInstance,
+  ConditionalRequestInstance,
   CookieSignerInstance,
   CsrfProtectorInstance,
-  UrlBuilderInstance,
+  FormParserInstance,
+  HmacSignerInstance,
   JwtSignerInstance,
-  AeadCipherInstance,
-  Argon2HasherInstance,
-  RateLimiterInstance,
+  MediaTypeMatcherInstance,
+  MediaTypeParserInstance,
   PasswordHashOptions,
+  RateLimiterInstance,
+  SchemaValidatorInstance,
+  TemplateRendererInstance,
+  UrlBuilderInstance,
 } from '../../native'
+import type { BunFFI } from '../../native/ffi'
+import { encoder } from '../../shared/bytes'
+import { decodeUtf8, encodeUtf8 } from '../../shared/codec'
+import type { RustClientContext } from '../context'
+import { asNumber } from '../options'
 
 // ── FFI-backed instance wrappers ───────────────────────────────────────────
 // On Bun, instances whose methods have a STATELESS C-ABI sibling are backed by
@@ -41,7 +43,12 @@ import type {
 function ffiHmacSigner(key: Uint8Array, ffi: BunFFI): HmacSignerInstance {
   return {
     sign(data) {
-      return ffi.hmacSha256(key, data)
+      // Pooled `hmacSha256Into`: writes the 64 hex chars directly into a fresh
+      // buffer — no cstring return → no string clone → no encodeUtf8 round-trip
+      // (the old path cloned the hex string then re-encoded it to bytes).
+      const out = new Uint8Array(64)
+      const w = ffi.hmacSha256Into(key, data, out)
+      return out.subarray(0, w)
     },
     verify(data, sig) {
       return ffi.hmacSha256Verify(key, data, sig)
@@ -56,7 +63,11 @@ function ffiBase64Codec(
 ): Base64CodecInstance {
   return {
     encode(input) {
-      return ffi.base64Encode(input, urlSafe, padding)
+      // Pooled `base64EncodeInto`: writes the base64 bytes directly into a
+      // fresh buffer sized for the input — no cstring return / re-encode.
+      const out = new Uint8Array(Math.ceil(input.length / 3) * 4 + 3)
+      const w = ffi.base64EncodeInto(input, out, urlSafe, padding)
+      return out.subarray(0, w)
     },
     decode(input) {
       return ffi.base64Decode(input, urlSafe, padding)
@@ -67,10 +78,178 @@ function ffiBase64Codec(
 function ffiCookieSigner(secret: Uint8Array, ffi: BunFFI): CookieSignerInstance {
   return {
     sign(value) {
-      return ffi.signCookie(value, secret)
+      // Pooled `signCookieInto`: writes `value.<64-hex>` directly into a fresh
+      // buffer — no cstring return / re-encode round-trip.
+      const out = new Uint8Array(value.length + 65)
+      const w = ffi.signCookieInto(value, secret, out)
+      return out.subarray(0, w)
     },
     verify(signed) {
-      return ffi.verifyCookie(signed, secret)
+      // Pooled `verifyCookieInto`: writes the verified value directly (the
+      // value is a substring of `signed`, so `signed.length + 1` always fits).
+      const out = new Uint8Array(signed.length + 1)
+      const w = ffi.verifyCookieInto(signed, secret, out)
+      return w === null ? null : out.subarray(0, w)
+    },
+  }
+}
+
+/**
+ * Opaque-handle `ConditionalRequest`: the napi instance compiles the resource
+ * state once (construction); per-call `isNotModified` evaluates it through the
+ * C-ABI (`castrum_conditional_is_not_modified`) via the inner handle — no napi
+ * crossing. The napi instance MUST stay alive for the handle's lifetime (same
+ * contract as the ingress handler / `Ingress::inner_ptr`) — `keepAlive` is
+ * referenced by the returned method so the native state is never GC'd while
+ * the handle is in use.
+ */
+function ffiConditionalRequest(
+  napi: ConditionalRequestInstance,
+  inner: number,
+  ffi: BunFFI,
+): ConditionalRequestInstance {
+  // Referenced by the method below → captured → prevents GC of the native
+  // state the opaque handle points into.
+  const keepAlive = napi
+  return {
+    isNotModified(ifNoneMatch, ifModifiedSince) {
+      void keepAlive
+      return ffi.conditionalIsNotModified(inner, ifNoneMatch ?? null, ifModifiedSince ?? null)
+    },
+  }
+}
+
+/**
+ * Opaque-handle `UrlBuilder`: the napi instance parses the base ONCE; per-call
+ * `resolve` evaluates it through the C-ABI (`castrum_url_builder_resolve`) via
+ * the inner handle — no napi crossing. `keepAlive` references the napi instance
+ * so the precompiled base is never GC'd while the handle is in use.
+ */
+function ffiUrlBuilder(napi: UrlBuilderInstance, inner: number, ffi: BunFFI): UrlBuilderInstance {
+  const keepAlive = napi
+  return {
+    resolve(reference) {
+      void keepAlive
+      return ffi.urlBuilderResolve(inner, reference)
+    },
+  }
+}
+
+/** Opaque-handle `MediaTypeMatcher` (expected precompiled once). */
+function ffiMediaTypeMatcher(
+  napi: MediaTypeMatcherInstance,
+  inner: number,
+  ffi: BunFFI,
+): MediaTypeMatcherInstance {
+  const keepAlive = napi
+  return {
+    matches(actual) {
+      void keepAlive
+      return ffi.mediaTypeMatcherMatches(inner, actual)
+    },
+  }
+}
+
+/** Opaque-handle `AcceptNegotiator` (supported list precompiled once). */
+function ffiAcceptNegotiator(
+  napi: AcceptNegotiatorInstance,
+  inner: number,
+  ffi: BunFFI,
+): AcceptNegotiatorInstance {
+  const keepAlive = napi
+  return {
+    negotiate(header) {
+      void keepAlive
+      return ffi.acceptNegotiatorNegotiate(inner, header)
+    },
+    negotiateServerPreference(header) {
+      void keepAlive
+      return ffi.acceptNegotiatorNegotiateServer(inner, header)
+    },
+  }
+}
+
+/** Opaque-handle `JwtSigner` (HS256 key + ttl precompiled once). */
+function ffiJwtSigner(napi: JwtSignerInstance, inner: number, ffi: BunFFI): JwtSignerInstance {
+  const keepAlive = napi
+  return {
+    sign(claims, nowSeconds) {
+      void keepAlive
+      return ffi.jwtSignerSign(inner, encoder.encode(JSON.stringify(claims)), nowSeconds)
+    },
+    signBytes(claimsJson, nowSeconds) {
+      void keepAlive
+      return ffi.jwtSignerSign(inner, claimsJson, nowSeconds)
+    },
+    verify(token, nowSeconds) {
+      void keepAlive
+      const claims = ffi.jwtSignerVerify(inner, token, nowSeconds)
+      return claims === null ? null : (JSON.parse(decodeUtf8(claims)) as unknown)
+    },
+  }
+}
+
+/** Opaque-handle `TemplateRenderer` (template compiled once). */
+function ffiTemplateRenderer(
+  napi: TemplateRendererInstance,
+  inner: number,
+  ffi: BunFFI,
+): TemplateRendererInstance {
+  const keepAlive = napi
+  return {
+    render(context) {
+      void keepAlive
+      return ffi.templateRender(inner, encoder.encode(JSON.stringify(context)))
+    },
+    renderBytes(contextJson) {
+      void keepAlive
+      return ffi.templateRender(inner, contextJson)
+    },
+    renderBatchPacked(data) {
+      void keepAlive
+      return napi.renderBatchPacked(data)
+    },
+  }
+}
+
+/** Opaque-handle `SchemaValidator` (schema compiled once); the hot `validate`
+ * is a C-ABI eval; the detailed/batch/derive ops stay on the napi instance. */
+function ffiSchemaValidator(
+  napi: SchemaValidatorInstance,
+  inner: number,
+  ffi: BunFFI,
+): SchemaValidatorInstance {
+  const keepAlive = napi
+  return {
+    validate(input) {
+      void keepAlive
+      return ffi.schemaValidatorValidate(inner, input)
+    },
+    validateDetailed: napi.validateDetailed.bind(napi),
+    validateFirstError: napi.validateFirstError.bind(napi),
+    validateBatchPackedCount: napi.validateBatchPackedCount.bind(napi),
+    validateBatchPackedBitset: napi.validateBatchPackedBitset.bind(napi),
+    derive: napi.derive.bind(napi),
+  }
+}
+
+/** Opaque-handle `RateLimiter` (sharded state compiled once). */
+function ffiRateLimiter(
+  napi: RateLimiterInstance,
+  inner: number,
+  ffi: BunFFI,
+): RateLimiterInstance {
+  const keepAlive = napi
+  return {
+    check(key, nowMs) {
+      void keepAlive
+      // `key` is a `cstring` ARG — the engine transcodes the rate-limit key
+      // in-engine (no JS-side encode).
+      return ffi.rateLimiterCheck(inner, key, nowMs)
+    },
+    checkKey(key, nowMs) {
+      void keepAlive
+      return ffi.rateLimiterCheckKey(inner, key, nowMs)
     },
   }
 }
@@ -78,7 +257,11 @@ function ffiCookieSigner(secret: Uint8Array, ffi: BunFFI): CookieSignerInstance
 function ffiCsrfProtector(secret: Uint8Array, ffi: BunFFI): CsrfProtectorInstance {
   return {
     create() {
-      return ffi.csrfToken(secret)
+      // Pooled `csrfTokenInto`: writes the 129-char `hex.hex` directly into a
+      // fresh buffer — no cstring return / re-encode round-trip.
+      const out = new Uint8Array(129)
+      const w = ffi.csrfTokenInto(secret, out)
+      return out.subarray(0, w)
     },
     verify(token) {
       return ffi.csrfVerify(token, secret)
@@ -99,7 +282,7 @@ function ffiArgon2Hasher(
   const outLen = o.outLen ?? 32
   return {
     hash(password, salt) {
-      return ffi.passwordHash(password, salt, mCost, tCost, pCost, outLen)
+      return encodeUtf8(ffi.passwordHash(password, salt, mCost, tCost, pCost, outLen))
     },
     verify(password, phc) {
       return ffi.passwordVerify(password, phc)
@@ -148,22 +331,33 @@ function ffiFormParser(ffi: BunFFI): FormParserInstance {
 
 /** Compiled-once factory + runtime-control methods (`Pick<RustScalar, ...>`). */
 export function buildFactories(ctx: RustClientContext) {
+  const { transport } = ctx.runtime
   const { addon } = ctx
 
   return {
     createSchemaValidator(schema: Uint8Array): SchemaValidatorInstance {
+      const ffi = transport.ffi
+      if (ffi) {
+        const napi = new addon.SchemaValidator(schema)
+        return ffiSchemaValidator(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+      }
       return new addon.SchemaValidator(schema)
     },
     createHmacSigner(key: Uint8Array): HmacSignerInstance {
-      const ffi = getBunFFI()
+      const ffi = transport.ffi
       if (ffi) return ffiHmacSigner(key, ffi)
       return new addon.HmacSigner(key)
     },
     createTemplateRenderer(source: string): TemplateRendererInstance {
+      const ffi = transport.ffi
+      if (ffi) {
+        const napi = new addon.TemplateRenderer(source)
+        return ffiTemplateRenderer(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+      }
       return new addon.TemplateRenderer(source)
     },
     createFormParser(capacity?: number): FormParserInstance {
-      const ffi = getBunFFI()
+      const ffi = transport.ffi
       if (ffi) return ffiFormParser(ffi)
       return new addon.FormParser(capacity)
     },
@@ -174,43 +368,74 @@ export function buildFactories(ctx: RustClientContext) {
       etagValue: Uint8Array,
       lastModifiedSecs?: number,
     ): ConditionalRequestInstance {
+      // FFI-first via the opaque inner handle (the napi instance compiles the
+      // state once; per-call `isNotModified` is a C-ABI eval). The wrapper
+      // holds the napi instance for the handle's lifetime.
+      const ffi = transport.ffi
+      if (ffi) {
+        const napi = new addon.ConditionalRequest(etagValue, lastModifiedSecs ?? undefined)
+        return ffiConditionalRequest(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+      }
       return new addon.ConditionalRequest(etagValue, lastModifiedSecs ?? undefined)
     },
     createAcceptNegotiator(supported: string[]): AcceptNegotiatorInstance {
+      const ffi = transport.ffi
+      if (ffi) {
+        const napi = new addon.AcceptNegotiator(supported)
+        return ffiAcceptNegotiator(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+      }
       return new addon.AcceptNegotiator(supported)
     },
     createBase64Codec(urlSafe?: boolean, padding?: boolean): Base64CodecInstance {
-      const ffi = getBunFFI()
+      const ffi = transport.ffi
       if (ffi) return ffiBase64Codec(urlSafe, padding, ffi)
       return new addon.Base64Codec(urlSafe ?? undefined, padding ?? undefined)
     },
     createCookieSigner(secret: Uint8Array): CookieSignerInstance {
-      const ffi = getBunFFI()
+      const ffi = transport.ffi
       if (ffi) return ffiCookieSigner(secret, ffi)
       return new addon.CookieSigner(secret)
     },
     createCsrfProtector(secret: Uint8Array): CsrfProtectorInstance {
-      const ffi = getBunFFI()
+      const ffi = transport.ffi
       if (ffi) return ffiCsrfProtector(secret, ffi)
       return new addon.CsrfProtector(secret)
     },
     createUrlBuilder(base: Uint8Array): UrlBuilderInstance {
+      // FFI-first via the opaque inner handle (the napi instance parses the
+      // base ONCE; per-call `resolve` is a C-ABI eval). The wrapper holds the
+      // napi instance for the handle's lifetime.
+      const ffi = transport.ffi
+      if (ffi) {
+        const napi = new addon.UrlBuilder(base)
+        return ffiUrlBuilder(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+      }
       return new addon.UrlBuilder(base)
     },
     createJwtSigner(secret: Uint8Array, ttlSeconds?: number): JwtSignerInstance {
+      const ffi = transport.ffi
+      if (ffi) {
+        const napi = new addon.JwtSigner(secret, ttlSeconds ?? undefined)
+        return ffiJwtSigner(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+      }
       return new addon.JwtSigner(secret, ttlSeconds ?? undefined)
     },
     createAeadCipher(key: Uint8Array, algorithm?: string): AeadCipherInstance {
-      const ffi = getBunFFI()
+      const ffi = transport.ffi
       if (ffi) return ffiAeadCipher(key, algorithm, ffi)
       return new addon.AeadCipher(key, algorithm ?? undefined)
     },
     createArgon2Hasher(options?: PasswordHashOptions | null): Argon2HasherInstance {
-      const ffi = getBunFFI()
+      const ffi = transport.ffi
       if (ffi) return ffiArgon2Hasher(options, ffi)
       return new addon.Argon2Hasher(options ?? undefined)
     },
     createMediaTypeMatcher(expected: Uint8Array): MediaTypeMatcherInstance {
+      const ffi = transport.ffi
+      if (ffi) {
+        const napi = new addon.MediaTypeMatcher(expected)
+        return ffiMediaTypeMatcher(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+      }
       return new addon.MediaTypeMatcher(expected)
     },
     createRateLimiter(
@@ -218,6 +443,11 @@ export function buildFactories(ctx: RustClientContext) {
       windowMs: number,
       maxEntries?: number | null,
     ): RateLimiterInstance {
+      const ffi = transport.ffi
+      if (ffi) {
+        const napi = new addon.RateLimiter(limit, windowMs, maxEntries ?? undefined)
+        return ffiRateLimiter(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+      }
       return new addon.RateLimiter(limit, windowMs, maxEntries ?? undefined)
     },
     initThreadPool(threads?: number): void {

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

@@ -2,71 +2,73 @@
 //
 // Mirrors rust/crypto/hashing.rs + hmac_sha256.rs: crc32 / fnv1a64 / HMAC.
 // (HMAC reuses the context-cached signer to avoid re-constructing the key.)
+//
+// Runtime dispatch is centralized in the adapter (`ctx.runtime`): the Bun
+// built-in delegations (crc32/xxh3/hmacSha256) come from `builtins.has(op)`
+// and the native call from `transport.resolve(op)` / `transport.ffi`
+// (bun:ffi first, napi fallback) — no inline `isBun()` / `getBunFFI()`.
 
+import { toBytes } from '../../shared/bytes'
+import { writeInto } from '../into'
+import { memoizeFfi, type RustClientContext, resolveNative } from '../context'
 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.
+  const { builtins, transport } = ctx.runtime
+  // Hoist the immutable per-runtime builtin-delegation decisions into a
+  // bind-time map (BUILTIN_OPS is a module constant — never mutated after
+  // load) so the hot path reads object properties instead of `Set.has`.
+  const HAS = {
+    crc32: builtins.has('crc32'),
+    xxh3: builtins.has('xxh3'),
+    hmacSha256: builtins.has('hmacSha256'),
+  }
+  // Lazy-memoized ffi surface: binds on first call, single local read after.
+  const ffi = memoizeFfi(transport)
+  // bun:ffi JIT-calls the C ABI exports with ~1/4 the crossing cost of napi
+  // for these sub-µs hashes; the transport resolves ffi-first and caches.
   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)
+      // `opImpl` recommendation. Node keeps the addon.
+      if (HAS.crc32) return builtins.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)
+      if (HAS.xxh3) return builtins.xxh3(input)
       return asBigInt(resolveNative(ctx, 'xxh3')(input))
     },
-    hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array {
+    hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array | string {
       // 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)
+      // rust+FFI crossing (~1.2x, decision matrix). Bun returns the 64-char
+      // lowercase-hex STRING (native transfer — no TextEncoder round-trip); the
+      // addon returns the same hex as bytes. Node keeps the FFI path.
+      if (HAS.hmacSha256) return builtins.hmacSha256(key, data)
+      const f = ffi()
+      if (f) return f.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
+      const f = ffi()
+      if (f) return f.hmacSha256Into(key, data, output)
+      return writeInto('hmac sha256', output, ctx.hmacSigner(key).sign(data))
     },
-    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)
+    hmacSha256Verify(key: Uint8Array, data: Uint8Array, sig: Uint8Array | string): boolean {
+      // `hmacSha256` returns the signature as a hex STRING under Bun (built-in
+      // delegation / cstring) and as hex bytes under napi. The verifier accepts
+      // both — normalize the string to hex bytes so the ffi/napi cores see the
+      // same input (sign → verify is self-consistent on every transport).
+      const sigBytes = toBytes(sig)
+      const f = ffi()
+      if (f) return f.hmacSha256Verify(key, data, sigBytes)
+      return ctx.hmacSigner(key).verify(data, sigBytes)
     },
   }
 }