castrum 0.7.0

package/rust/validation.rs

@@ -0,0 +1,107 @@
+// rust/validation.rs — v2: memchr for IPv4 dots
+
+#[cfg(not(feature = "fast-email"))]
+use email_address::EmailAddress;
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+use std::net::Ipv6Addr;
+
+#[cfg(feature = "fast-email")]
+#[inline]
+fn email_is_valid(s: &str) -> bool { fast_chemail::is_valid_email(s) }
+
+#[cfg(not(feature = "fast-email"))]
+#[inline]
+fn email_is_valid(s: &str) -> bool { EmailAddress::is_valid(s) }
+
+#[inline]
+pub fn validate_email_bytes(input: &[u8]) -> bool {
+    std::str::from_utf8(input).map(email_is_valid).unwrap_or(false)
+}
+
+#[inline]
+pub fn validate_uuid_bytes(input: &[u8]) -> bool {
+    let Ok(b) = <&[u8; 36]>::try_from(input) else { return false; };
+
+    // Unroll the dash positions check.
+    if b[8] != b'-' || b[13] != b'-' || b[18] != b'-' || b[23] != b'-' {
+        return false;
+    }
+    if b[14] != b'4' { return false; }
+    if !matches!(b[19], b'8' | b'9' | b'a' | b'b' | b'A' | b'B') { return false; }
+
+    // Validate hex digits at all other positions.
+    // Use a lookup table for speed.
+    const HEX: [bool; 256] = {
+        let mut t = [false; 256];
+        let mut i = 0;
+        while i < 256 {
+            t[i] = matches!(i as u8, b'0'..=b'9' | b'a'..=b'f' | b'A'..=b'F');
+            i += 1;
+        }
+        t
+    };
+
+    let mut i = 0usize;
+    while i < 36 {
+        if i == 8 || i == 13 || i == 18 || i == 23 { i += 1; continue; }
+        if i == 14 || i == 19 { i += 1; continue; }
+        if !HEX[b[i] as usize] { return false; }
+        i += 1;
+    }
+    true
+}
+
+#[inline]
+fn is_valid_ipv4(b: &[u8]) -> bool {
+    if b.is_empty() || b.len() > 15 { return false; }
+
+    let mut parts = 0u8;
+    let mut start = 0usize;
+
+    // Use memchr to find dots faster.
+    for dot_idx in b.iter().enumerate().filter_map(|(i, &c)| if c == b'.' { Some(i) } else { None }) {
+        let part = &b[start..dot_idx];
+        if !validate_ipv4_part(part) { return false; }
+        parts += 1;
+        start = dot_idx + 1;
+    }
+
+    // Last part.
+    if !validate_ipv4_part(&b[start..]) { return false; }
+    parts += 1;
+
+    parts == 4
+}
+
+#[inline(always)]
+fn validate_ipv4_part(part: &[u8]) -> bool {
+    if part.is_empty() || part.len() > 3 { return false; }
+    if part.len() > 1 && part[0] == b'0' { return false; }
+
+    let mut n = 0u16;
+    for &c in part {
+        if !c.is_ascii_digit() { return false; }
+        n = n * 10 + u16::from(c - b'0');
+    }
+    n <= 255
+}
+
+#[inline]
+pub fn validate_ipv4_bytes(input: &[u8]) -> bool {
+    is_valid_ipv4(input)
+}
+
+#[inline]
+pub fn validate_ipv6_bytes(input: &[u8]) -> bool {
+    simdutf8::basic::from_utf8(input)
+        .ok()
+        .and_then(|s| s.parse::<Ipv6Addr>().ok())
+        .is_some()
+}
+
+#[napi] pub fn validate_email(input: Uint8Array) -> bool { validate_email_bytes(input.as_ref()) }
+#[napi] pub fn validate_uuid(input: Uint8Array) -> bool { validate_uuid_bytes(input.as_ref()) }
+#[napi] pub fn validate_ipv4(input: Uint8Array) -> bool { validate_ipv4_bytes(input.as_ref()) }
+#[napi] pub fn validate_ipv6(input: Uint8Array) -> bool { validate_ipv6_bytes(input.as_ref()) }

package/rust/websocket.rs

@@ -0,0 +1,23 @@
+use base64::engine::general_purpose::STANDARD as BASE64;
+use base64::Engine;
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+use aws_lc_rs::digest;
+
+const WS_MAGIC: &[u8] = b"258EAFA5-E914-47DA-95CA-5AB5DC11BE85";
+
+#[napi]
+pub fn ws_accept_key(key: Uint8Array) -> Result<Buffer> {
+    let mut ctx = digest::Context::new(&digest::SHA1_FOR_LEGACY_USE_ONLY);
+    ctx.update(key.as_ref());
+    ctx.update(WS_MAGIC);
+
+    let hash = ctx.finish();
+
+    let mut out = [0u8; 28];
+    let n = BASE64
+        .encode_slice(hash.as_ref(), &mut out)
+        .map_err(|e| Error::from_reason(e.to_string()))?;
+
+    Ok(Buffer::from(out[..n].to_vec()))
+}

package/src/baseline/index.ts

@@ -0,0 +1,12 @@
+export * from "./tasks/json";
+export * from "./tasks/http";
+export * from "./tasks/query";
+export * from "./tasks/cookie";
+export * from "./tasks/token";
+export * from "./tasks/websocket";
+export * from "./tasks/json-patch";
+export * from "./tasks/hmac";
+export * from "./tasks/validation";
+export * from "./tasks/hashing";
+export * from "./tasks/mime";
+export * from "./tasks/url";

package/src/baseline/tasks/cookie.ts

@@ -0,0 +1,22 @@
+import { decoder } from "../../shared/bytes";
+import { packPairs } from "../../shared/packed";
+
+export function nativeCookieParsePacked(bytes: Uint8Array): Uint8Array {
+  const text = decoder.decode(bytes);
+  const pairs: Array<[string, string]> = [];
+
+  for (const rawPair of text.split(";")) {
+    const pair = rawPair.trim();
+    if (pair.length === 0) continue;
+
+    const eq = pair.indexOf("=");
+    const name = (eq >= 0 ? pair.slice(0, eq) : pair).trim();
+    const value = eq >= 0 ? pair.slice(eq + 1).trim() : "";
+
+    if (name.length === 0) continue;
+
+    pairs.push([name, value]);
+  }
+
+  return packPairs(pairs);
+}

package/src/baseline/tasks/hashing.ts

@@ -0,0 +1,18 @@
+import * as CRC32 from "crc-32";
+
+export function nativeCrc32(bytes: Uint8Array): number {
+  return CRC32.buf(bytes) >>> 0;
+}
+
+export function nativeFnv1a64(bytes: Uint8Array): bigint {
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  const mask = 0xffffffffffffffffn;
+
+  for (const byte of bytes) {
+    hash ^= BigInt(byte);
+    hash = (hash * prime) & mask;
+  }
+
+  return hash;
+}

package/src/baseline/tasks/hmac.ts

@@ -0,0 +1,38 @@
+import { Buffer } from "node:buffer";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { decoder, encoder } from "../../shared/bytes";
+
+export function nativeHmacSha256(
+  key: Uint8Array,
+  data: Uint8Array,
+): Uint8Array {
+  const hex = createHmac("sha256", Buffer.from(key))
+    .update(Buffer.from(data))
+    .digest("hex");
+
+  return encoder.encode(hex);
+}
+
+export function nativeHmacSha256Verify(
+  key: Uint8Array,
+  data: Uint8Array,
+  sig: Uint8Array,
+): boolean {
+  const expected = createHmac("sha256", Buffer.from(key))
+    .update(Buffer.from(data))
+    .digest();
+
+  const providedHex = decoder.decode(sig).trim();
+
+  if (!/^[0-9a-fA-F]*$/.test(providedHex)) {
+    return false;
+  }
+
+  const provided = Buffer.from(providedHex, "hex");
+
+  if (expected.length !== provided.length) {
+    return false;
+  }
+
+  return timingSafeEqual(expected, provided);
+}

package/src/baseline/tasks/http.ts

@@ -0,0 +1,62 @@
+import { decoder, encoder } from "../../shared/bytes";
+
+
+
+export function nativeHttpParseRequestPacked(bytes: Uint8Array): Uint8Array {
+  const text = decoder.decode(bytes);
+  const headerEnd = text.indexOf("\r\n\r\n");
+  const head = headerEnd >= 0 ? text.slice(0, headerEnd) : text;
+
+  const lines = head.split("\r\n");
+  const requestLine = lines[0] ?? "";
+  const [method = "", target = "", version = ""] = requestLine.split(" ");
+
+  const methodBytes = encoder.encode(method);
+  const pathBytes = encoder.encode(target);
+  const versionBytes = encoder.encode(version);
+
+  const headers: Array<[Uint8Array, Uint8Array]> = [];
+
+  for (const line of lines.slice(1)) {
+    const idx = line.indexOf(":");
+    if (idx > 0) {
+      const name = encoder.encode(line.slice(0, idx).trim().toLowerCase());
+      const value = encoder.encode(line.slice(idx + 1).trim());
+      headers.push([name, value]);
+    }
+  }
+
+  let total = 16;
+  total += methodBytes.byteLength;
+  total += pathBytes.byteLength;
+  total += versionBytes.byteLength;
+
+  for (const [name, value] of headers) {
+    total += 8 + name.byteLength + value.byteLength;
+  }
+
+  const out = new Uint8Array(total);
+  const dv = new DataView(out.buffer);
+  let offset = 0;
+
+  const writeBytes = (bytes: Uint8Array) => {
+    dv.setUint32(offset, bytes.byteLength, true);
+    offset += 4;
+    out.set(bytes, offset);
+    offset += bytes.byteLength;
+  };
+
+  writeBytes(methodBytes);
+  writeBytes(pathBytes);
+  writeBytes(versionBytes);
+
+  dv.setUint32(offset, headers.length, true);
+  offset += 4;
+
+  for (const [name, value] of headers) {
+    writeBytes(name);
+    writeBytes(value);
+  }
+
+  return out;
+}

package/src/baseline/tasks/json-patch.ts

@@ -0,0 +1,12 @@
+import { applyPatch, type Operation } from "fast-json-patch";
+import { decoder, encoder } from "../../shared/bytes";
+
+export function nativeJsonPatch(
+  docBytes: Uint8Array,
+  patchBytes: Uint8Array,
+): Uint8Array {
+  const doc = JSON.parse(decoder.decode(docBytes));
+  const patch = JSON.parse(decoder.decode(patchBytes)) as Operation[];
+  const result = applyPatch(doc, patch, true, false).newDocument;
+  return encoder.encode(JSON.stringify(result));
+}

package/src/baseline/tasks/json.ts

@@ -0,0 +1,50 @@
+// src/baseline/tasks/json.ts
+import { decoder, encoder } from "../../shared/bytes";
+
+/**
+ * Older Bun builds accepted Uint8Array directly in JSON.parse().
+ * Bun 1.4 canary builds may reject it.
+ *
+ * We feature-detect once. If byte parsing is supported, use it.
+ * Otherwise fall back to standard UTF-8 decode + JSON.parse.
+ */
+const JSON_PARSE_BYTES_SUPPORTED: boolean = (() => {
+  try {
+    JSON.parse(encoder.encode('{"a":1}') as any);
+    return true;
+  } catch {
+    return false;
+  }
+})();
+
+const parseJsonBytes: (bytes: Uint8Array) => unknown =
+  JSON_PARSE_BYTES_SUPPORTED
+    ? (bytes) => JSON.parse(bytes as any)
+    : (bytes) => JSON.parse(decoder.decode(bytes));
+
+export function nativeJsonValid(bytes: Uint8Array): boolean {
+  try {
+    parseJsonBytes(bytes);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function nativeJsonSum(bytes: Uint8Array): bigint {
+  const parsed = parseJsonBytes(bytes);
+
+  if (!Array.isArray(parsed)) {
+    return 0n;
+  }
+
+  let sum = 0n;
+
+  for (const row of parsed as Array<{ id?: unknown }>) {
+    if (typeof row.id === "number" && Number.isFinite(row.id)) {
+      sum += BigInt(Math.trunc(row.id));
+    }
+  }
+
+  return sum;
+}

package/src/baseline/tasks/mime.ts

@@ -0,0 +1,5 @@
+import mime from "mime-types";
+
+export function nativeMimeFromExtension(ext: string): string {
+  return mime.lookup(ext) || "application/octet-stream";
+}

package/src/baseline/tasks/query.ts

@@ -0,0 +1,14 @@
+import { decoder } from "../../shared/bytes";
+import { packPairs } from "../../shared/packed";
+
+export function nativeQueryParsePacked(bytes: Uint8Array): Uint8Array {
+  const query = decoder.decode(bytes);
+  const sp = new URLSearchParams(query);
+
+  const pairs: Array<[string, string]> = [];
+  for (const [key, value] of sp.entries()) {
+    pairs.push([key, value]);
+  }
+
+  return packPairs(pairs);
+}

package/src/baseline/tasks/token.ts

@@ -0,0 +1,15 @@
+const HEX = "0123456789abcdef";
+
+export function nativeRandomToken(byteLen: number): Uint8Array {
+  const bytes = new Uint8Array(byteLen);
+  crypto.getRandomValues(bytes);
+
+  const hex = new Uint8Array(byteLen * 2);
+
+  for (let i = 0; i < byteLen; i++) {
+    hex[i * 2] = HEX.charCodeAt(bytes[i]! >> 4);
+    hex[i * 2 + 1] = HEX.charCodeAt(bytes[i]! & 0x0f);
+  }
+
+  return hex;
+}

package/src/baseline/tasks/url.ts

@@ -0,0 +1,11 @@
+import { decoder } from "../../shared/bytes";
+
+export function nativeUrlEncode(input: string | Uint8Array): string {
+  const text = typeof input === "string" ? input : decoder.decode(input);
+  return encodeURIComponent(text);
+}
+
+export function nativeUrlDecode(input: string | Uint8Array): string {
+  const text = typeof input === "string" ? input : decoder.decode(input);
+  return decodeURIComponent(text);
+}

package/src/baseline/tasks/validation.ts

@@ -0,0 +1,19 @@
+import { isIP } from "node:net";
+import validator from "validator";
+import { decoder } from "../../shared/bytes";
+
+export function nativeValidateEmail(bytes: Uint8Array): boolean {
+  return validator.isEmail(decoder.decode(bytes));
+}
+
+export function nativeValidateUuid(bytes: Uint8Array): boolean {
+  return validator.isUUID(decoder.decode(bytes), 4);
+}
+
+export function nativeValidateIpv4(bytes: Uint8Array): boolean {
+  return validator.isIP(decoder.decode(bytes), 4);
+}
+
+export function nativeValidateIpv6(bytes: Uint8Array): boolean {
+  return isIP(decoder.decode(bytes)) === 6;
+}

package/src/baseline/tasks/websocket.ts

@@ -0,0 +1,14 @@
+import { Buffer } from "node:buffer";
+import { decoder, encoder, toPlainBuffer } from "../../shared/bytes";
+
+export function nativeWsAcceptKey(key: string | Uint8Array): Uint8Array {
+  const keyText = typeof key === "string" ? key : decoder.decode(key);
+  const magic = "258EAFA5-E914-47DA-95CA-5AB5DC11BE85";
+  const combined = encoder.encode(keyText + magic);
+
+  const hash = new Bun.CryptoHasher("sha1")
+    .update(toPlainBuffer(combined))
+    .digest();
+
+  return encoder.encode(Buffer.from(hash).toString("base64"));
+}

package/src/bench/assert.ts

@@ -0,0 +1,70 @@
+import { decoder } from "../shared/bytes";
+import { sortKeys } from "../shared/json";
+
+export function parseJsonBytes(bytes: Uint8Array): unknown {
+  return JSON.parse(decoder.decode(bytes));
+}
+
+function typeName(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (value instanceof Uint8Array) return "Uint8Array";
+  return typeof value;
+}
+
+/**
+ * Some Bun/NAPI builds return Rust i64/u64 as number when the value fits
+ * inside Number.MAX_SAFE_INTEGER, while baseline code returns bigint.
+ *
+ * For benchmark correctness checks, integer number and bigint should be
+ * treated as equal when their numeric value is the same.
+ */
+function normalizeScalar(value: unknown): unknown {
+  if (typeof value === "bigint") {
+    return value;
+  }
+
+  if (typeof value === "number" && Number.isFinite(value) && Number.isInteger(value)) {
+    return BigInt(Math.trunc(value));
+  }
+
+  return value;
+}
+
+export function assertEqual(
+  actual: unknown,
+  expected: unknown,
+  label: string,
+): void {
+  const a = normalizeScalar(actual);
+  const b = normalizeScalar(expected);
+
+  if (a !== b) {
+    console.error(`FAIL: ${label}`);
+    console.error(
+      `  actual:   ${String(actual)} (${typeName(actual)})`,
+    );
+    console.error(
+      `  expected: ${String(expected)} (${typeName(expected)})`,
+    );
+    process.exit(1);
+    throw new Error(`Assertion failed: ${label}`);
+  }
+}
+
+export function assertDeepEqual(
+  actual: unknown,
+  expected: unknown,
+  label: string,
+): void {
+  const a = JSON.stringify(sortKeys(actual));
+  const b = JSON.stringify(sortKeys(expected));
+
+  if (a !== b) {
+    console.error(`FAIL: ${label}`);
+    console.error(`  actual:   ${a}`);
+    console.error(`  expected: ${b}`);
+    process.exit(1);
+    throw new Error(`Assertion failed: ${label}`);
+  }
+}