castrum 0.9.3 → 0.9.4

package/rust/payload/ws_frames.rs

@@ -0,0 +1,354 @@
+// rust/payload/ws_frames.rs — RFC 6455 WebSocket frame encode/decode.
+//
+// Backend-framework feature: byte-level WebSocket framing (opcode, FIN, length
+// encoding, client masking). Bun already provides a full WebSocket server; this
+// is the low-level codec used when you need raw frame control or a benchmark
+// reference for the byte machinery. The default mask key is the RFC 6455 §5.7
+// example (`0x37 0xfa 0x21 0x3d`) so encode is deterministic and testable; real
+// clients should use a random key (pass a different one if desired).
+//
+// Pure-Rust core (no napi types) stays unit-testable; only the entry points
+// use napi types.
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+const DEFAULT_MASK: [u8; 4] = [0x37, 0xfa, 0x21, 0x3d];
+
+/// Word-at-a-time masked copy (RFC 6455 §5.3 masking): XOR `src` with the
+/// 4-byte `mask`, writing the result into `dst` (same length). Processes 8
+/// bytes per u64 XOR (guaranteed vectorizable), with 4-byte and byte tails.
+/// Exactly equivalent to the per-byte `b ^ mask[i & 3]` loop.
+#[inline]
+fn masked_copy(dst: &mut [u8], src: &[u8], mask: [u8; 4]) {
+    debug_assert_eq!(dst.len(), src.len());
+    // Replicate the 4-byte mask across the low/high 32 bits so one u64 word
+    // can be processed per iteration (2x the u32 throughput).
+    let mask64 = {
+        let m = u32::from_le_bytes(mask) as u64;
+        m | (m << 32)
+    };
+    let mut i = 0usize;
+    while i + 8 <= src.len() {
+        let mut w = [0u8; 8];
+        w.copy_from_slice(&src[i..i + 8]);
+        let x = u64::from_le_bytes(w) ^ mask64;
+        dst[i..i + 8].copy_from_slice(&x.to_le_bytes());
+        i += 8;
+    }
+    while i + 4 <= src.len() {
+        let w = u32::from_le_bytes([src[i], src[i + 1], src[i + 2], src[i + 3]]);
+        dst[i..i + 4].copy_from_slice(&(w ^ (mask64 as u32)).to_le_bytes());
+        i += 4;
+    }
+    // Tail: `i` is a multiple of 4 here, so `i & 3 == 0` and the mask phase
+    // matches the reference byte loop exactly.
+    while i < src.len() {
+        dst[i] = src[i] ^ mask[i & 3];
+        i += 1;
+    }
+}
+
+// ── Pure-Rust core ─────────────────────────────────────────────
+
+/// Encode a single WebSocket frame per RFC 6455 §5.2.
+pub fn encode_frame(opcode: u8, payload: &[u8], mask: bool, fin: bool) -> Vec<u8> {
+    let header_len =
+        2 + if payload.len() > 125 {
+            if payload.len() > 65_535 {
+                8
+            } else {
+                2
+            }
+        } else {
+            0
+        } + if mask { 4 } else { 0 };
+    let mut out = vec![0u8; header_len + payload.len()];
+    encode_frame_into(opcode, payload, mask, fin, &mut out).expect("exact-size frame buffer");
+    out
+}
+
+/// Zero-alloc core: encode a WebSocket frame directly into `out`. Returns the
+/// bytes written, or `None` when `out` is too small. Byte-identical to
+/// [`encode_frame`]; used by the C-ABI (`bun:ffi`) path to avoid the header
+/// Vec + copy.
+pub fn encode_frame_into(
+    opcode: u8,
+    payload: &[u8],
+    mask: bool,
+    fin: bool,
+    out: &mut [u8],
+) -> Option<usize> {
+    let header_len =
+        2 + if payload.len() > 125 {
+            if payload.len() > 65_535 {
+                8
+            } else {
+                2
+            }
+        } else {
+            0
+        } + if mask { 4 } else { 0 };
+    let need = header_len + payload.len();
+    if out.len() < need {
+        return None;
+    }
+    let mut pos = 0usize;
+    out[pos] = (if fin { 0x80 } else { 0 }) | (opcode & 0x0f);
+    pos += 1;
+
+    let len = payload.len();
+    let mask_bit = if mask { 0x80 } else { 0 };
+    if len <= 125 {
+        out[pos] = mask_bit | len as u8;
+        pos += 1;
+    } else if len <= 65_535 {
+        out[pos] = mask_bit | 126;
+        pos += 1;
+        out[pos..pos + 2].copy_from_slice(&(len as u16).to_be_bytes());
+        pos += 2;
+    } else {
+        out[pos] = mask_bit | 127;
+        pos += 1;
+        out[pos..pos + 8].copy_from_slice(&(len as u64).to_be_bytes());
+        pos += 8;
+    }
+
+    if mask {
+        out[pos..pos + 4].copy_from_slice(&DEFAULT_MASK);
+        pos += 4;
+        masked_copy(&mut out[pos..pos + payload.len()], payload, DEFAULT_MASK);
+        pos += payload.len();
+    } else {
+        out[pos..pos + payload.len()].copy_from_slice(payload);
+        pos += payload.len();
+    }
+    Some(pos)
+}
+
+/// A decoded WebSocket frame.
+pub struct Frame {
+    pub fin: bool,
+    pub opcode: u8,
+    pub payload: Vec<u8>,
+}
+
+/// Decode a single WebSocket frame (RFC 6455 §5.2). Returns `None` on any
+/// malformed / truncated input. Server→client frames are unmasked here.
+pub fn decode_frame(data: &[u8]) -> Option<Frame> {
+    if data.len() < 2 {
+        return None;
+    }
+    let fin = data[0] & 0x80 != 0;
+    let opcode = data[0] & 0x0f;
+    let masked = data[1] & 0x80 != 0;
+    let mut len = (data[1] & 0x7f) as u64;
+    let mut pos = 2usize;
+
+    if len == 126 {
+        if data.len() < pos + 2 {
+            return None;
+        }
+        len = u16::from_be_bytes([data[pos], data[pos + 1]]) as u64;
+        pos += 2;
+    } else if len == 127 {
+        if data.len() < pos + 8 {
+            return None;
+        }
+        let mut arr = [0u8; 8];
+        arr.copy_from_slice(&data[pos..pos + 8]);
+        len = u64::from_be_bytes(arr);
+        pos += 8;
+    }
+
+    let mut mask = [0u8; 4];
+    if masked {
+        if data.len() < pos + 4 {
+            return None;
+        }
+        mask.copy_from_slice(&data[pos..pos + 4]);
+        pos += 4;
+    }
+
+    let payload = data.get(pos..pos + len as usize)?;
+    let payload = if masked {
+        let mut v = vec![0u8; payload.len()];
+        masked_copy(&mut v, payload, mask);
+        v
+    } else {
+        payload.to_vec()
+    };
+
+    Some(Frame {
+        fin,
+        opcode,
+        payload,
+    })
+}
+
+// ── NAPI entry points ──────────────────────────────────────────
+
+#[napi(object)]
+pub struct WsFrame {
+    pub fin: bool,
+    pub opcode: u32,
+    pub payload: Buffer,
+}
+
+/// Encode a WebSocket frame. `opcode`: 1=text, 2=binary, 8=close, 9=ping,
+/// 10=pong. `mask` applies client masking (RFC 6455 requires clients to mask).
+#[napi]
+pub fn ws_frame_encode(opcode: u32, payload: Uint8Array, mask: bool, fin: bool) -> Buffer {
+    Buffer::from(encode_frame(opcode as u8, payload.as_ref(), mask, fin))
+}
+
+/// Decode a WebSocket frame. Returns `null` on malformed input.
+#[napi]
+pub fn ws_frame_decode(data: Uint8Array) -> Option<WsFrame> {
+    decode_frame(data.as_ref()).map(|f| WsFrame {
+        fin: f.fin,
+        opcode: f.opcode as u32,
+        payload: Buffer::from(f.payload),
+    })
+}
+
+/// Parallel frame-encode batch: packed `[u32 count]{[u32 len][payload]}` in →
+/// packed `[u32 count]{[u32 len][frame]}` out (same opcode/mask/fin for all).
+#[napi]
+pub fn ws_frame_encode_batch_packed(
+    data: Uint8Array,
+    opcode: u32,
+    mask: bool,
+    fin: bool,
+) -> Result<Buffer> {
+    let items = crate::util::unpack(data.as_ref())?;
+
+    let mut out = Vec::with_capacity(4 + items.len() * 24);
+    out.extend_from_slice(&(items.len() as u32).to_le_bytes());
+
+    for p in items {
+        let r = encode_frame(opcode as u8, p, mask, fin);
+        out.extend_from_slice(&(r.len() as u32).to_le_bytes());
+        out.extend_from_slice(&r);
+    }
+
+    Ok(Buffer::from(out))
+}
+
+/// Parallel frame-decode batch: packed frames in → packed `[u32 count]{
+/// [u32 len][payload]}` out (opcodes/flags dropped; failed items → empty).
+#[napi]
+pub fn ws_frame_decode_batch_packed(data: Uint8Array) -> Result<Buffer> {
+    let items = crate::util::unpack(data.as_ref())?;
+
+    let mut out = Vec::with_capacity(4 + items.len() * 24);
+    out.extend_from_slice(&(items.len() as u32).to_le_bytes());
+
+    for f in items {
+        let r = decode_frame(f).map(|f| f.payload).unwrap_or_default();
+        out.extend_from_slice(&(r.len() as u32).to_le_bytes());
+        out.extend_from_slice(&r);
+    }
+
+    Ok(Buffer::from(out))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn encode_short_unmasked() {
+        // RFC 6455 §5.7: 0x81 0x05 0x48 0x65 0x6c 0x6c 0x6f
+        assert_eq!(encode_frame(0x1, b"Hello", false, true), b"\x81\x05Hello");
+    }
+
+    #[test]
+    fn encode_masked_uses_rfc_example_key() {
+        // RFC 6455 §5.7 example: masked "Hello" with key 0x37 0xfa 0x21 0x3d
+        let expected = b"\x81\x85\x37\xfa\x21\x3d\x7f\x9f\x4d\x51\x58";
+        assert_eq!(encode_frame(0x1, b"Hello", true, true), expected);
+    }
+
+    #[test]
+    fn decode_unmasked_roundtrip() {
+        let frame = encode_frame(0x2, b"binary payload", false, true);
+        let decoded = decode_frame(&frame).unwrap();
+        assert!(decoded.fin);
+        assert_eq!(decoded.opcode, 0x2);
+        assert_eq!(decoded.payload, b"binary payload");
+    }
+
+    #[test]
+    fn decode_masked_roundtrip() {
+        let frame = encode_frame(0x1, b"Hello", true, true);
+        let decoded = decode_frame(&frame).unwrap();
+        assert_eq!(decoded.payload, b"Hello");
+    }
+
+    #[test]
+    fn decode_medium_and_long_lengths() {
+        let medium: Vec<u8> = vec![0xAA; 300];
+        let frame = encode_frame(0x2, &medium, false, true);
+        assert_eq!(decode_frame(&frame).unwrap().payload, medium);
+
+        let long: Vec<u8> = vec![0xBB; 70_000];
+        let frame = encode_frame(0x2, &long, false, true);
+        assert_eq!(decode_frame(&frame).unwrap().payload, long);
+    }
+
+    #[test]
+    fn decode_rejects_truncated() {
+        assert!(decode_frame(b"").is_none());
+        assert!(decode_frame(b"\x81").is_none());
+        let frame = encode_frame(0x1, b"Hello", false, true);
+        assert!(decode_frame(&frame[..frame.len() - 1]).is_none());
+    }
+
+    #[test]
+    fn fin_and_opcode_are_preserved() {
+        let frame = encode_frame(0x9, b"ping", false, false); // ping, not final
+        let decoded = decode_frame(&frame).unwrap();
+        assert!(!decoded.fin);
+        assert_eq!(decoded.opcode, 0x9);
+    }
+
+    #[test]
+    fn masked_copy_matches_byte_loop_for_all_lengths() {
+        // Property test: for every length 0..=64 plus a large payload, the
+        // word-masked copy must equal the reference byte loop.
+        let mask = DEFAULT_MASK;
+        for len in 0..=64usize {
+            let src: Vec<u8> = (0..len as u8).collect();
+            let expected: Vec<u8> = src
+                .iter()
+                .enumerate()
+                .map(|(i, &b)| b ^ mask[i & 3])
+                .collect();
+            let mut got = vec![0u8; len];
+            masked_copy(&mut got, &src, mask);
+            assert_eq!(got, expected, "len {len}");
+        }
+        let big: Vec<u8> = (0..10_000u32).map(|i| (i % 251) as u8).collect();
+        let expected: Vec<u8> = big
+            .iter()
+            .enumerate()
+            .map(|(i, &b)| b ^ mask[i & 3])
+            .collect();
+        let mut got = vec![0u8; big.len()];
+        masked_copy(&mut got, &big, mask);
+        assert_eq!(got, expected);
+    }
+
+    #[test]
+    fn encode_decode_masked_all_lengths() {
+        // Masked round-trips straddling the 4-byte word boundary (incl. empty,
+        // 1..8, the 125-byte short limit, and a >125 medium payload).
+        for len in [0usize, 1, 2, 3, 4, 5, 6, 7, 8, 125, 126, 127, 300] {
+            let payload: Vec<u8> = (0..len).map(|i| (i % 256) as u8).collect();
+            let frame = encode_frame(0x2, &payload, true, true);
+            let decoded = decode_frame(&frame).unwrap();
+            assert_eq!(decoded.payload, payload, "len {len}");
+        }
+    }
+}

package/rust/proptest_suite.rs

@@ -0,0 +1,139 @@
+//! Property-based tests (proptest) — adversarial inputs for the wire parsers.
+//!
+//! Complements the deterministic xorshift corpus in `test_support.rs` with
+//! randomized, auto-shrinking inputs. The core property for a security-sensitive
+//! native parser is: **given arbitrary (possibly hostile) bytes, it returns a
+//! Result/answer WITHOUT panicking and never reads out of bounds.** Run with
+//! `cargo test`. proptest is a dev-dependency only — it never ships.
+
+#![cfg(test)]
+
+use proptest::prelude::*;
+
+use crate::http::cookie_parser::cookie_parse_packed_vec;
+use crate::http::form::form_parse_packed_vec;
+use crate::http::headers::HeaderRefs;
+use crate::http::media_type::parse_media_type_core;
+use crate::http::query_parser::query_parse_packed_vec;
+use crate::json::fast_schema::compile;
+use crate::util::bytes::decode_percent_at;
+
+proptest! {
+    /// HeaderRefs::parse must never panic on arbitrary (possibly truncated,
+    /// forged length-field) packed header bytes.
+    #[test]
+    fn header_refs_parse_never_panics(
+        packed in prop::collection::vec(any::<u8>(), 0..1024),
+        is_options in any::<bool>(),
+        max_headers in 0usize..256usize,
+    ) {
+        let _ = HeaderRefs::parse(&packed, is_options, max_headers);
+    }
+
+    /// query_parse_packed_vec must never panic on arbitrary bytes.
+    #[test]
+    fn query_parse_never_panics(input in prop::collection::vec(any::<u8>(), 0..1024)) {
+        let _ = query_parse_packed_vec(&input);
+    }
+
+    /// decode_percent_at must never panic for any index, and must never
+    /// "succeed" past the end of the input.
+    #[test]
+    fn decode_percent_at_never_panics(
+        src in prop::collection::vec(any::<u8>(), 0..512),
+        i in 0usize..600usize,
+    ) {
+        if i >= src.len() {
+            prop_assert!(decode_percent_at(&src, i).is_none());
+        } else {
+            let _ = decode_percent_at(&src, i);
+        }
+    }
+
+    /// The zero-DOM fast-schema validator must never panic on arbitrary bytes
+    /// (the schema shape mirrors the hot ingress schema).
+    #[test]
+    fn fast_schema_never_panics(input in prop::collection::vec(any::<u8>(), 0..2048)) {
+        let schema = serde_json::json!({
+            "type": "object",
+            "properties": {
+                "id": { "type": "number" },
+                "name": { "type": "string", "minLength": 1 },
+                "tags": { "type": "array", "items": { "type": "string" } },
+            },
+            "required": ["id"],
+            "additionalProperties": false
+        });
+        let fast = compile(&schema).expect("schema must compile on the fast path");
+        let _ = fast.is_valid_bytes(&input);
+    }
+
+    /// cookie_parse_packed_vec must never panic on arbitrary bytes (forged
+    /// length prefixes, raw NULs, truncated pairs).
+    #[test]
+    fn cookie_parse_never_panics(input in prop::collection::vec(any::<u8>(), 0..1024)) {
+        let _ = cookie_parse_packed_vec(&input);
+    }
+
+    /// form_parse_packed_vec must never panic on arbitrary bytes (raw %, +/-
+    /// handling, control chars).
+    #[test]
+    fn form_parse_never_panics(input in prop::collection::vec(any::<u8>(), 0..1024)) {
+        let _ = form_parse_packed_vec(&input);
+    }
+
+    /// parse_media_type_core must never panic on arbitrary bytes.
+    #[test]
+    fn media_type_parse_never_panics(input in prop::collection::vec(any::<u8>(), 0..512)) {
+        let _ = parse_media_type_core(&input);
+    }
+
+    /// RFC 3986 percent-encode → decode must be the identity for EVERY byte
+    /// (the encode set here mirrors url_codec.rs's unreserved set).
+    #[test]
+    fn percent_encode_decode_roundtrip(input in prop::collection::vec(any::<u8>(), 0..256)) {
+        const HEX: &[u8; 16] = b"0123456789abcdef";
+        let mut encoded = Vec::with_capacity(input.len() * 3);
+        for &b in &input {
+            let unreserved = matches!(b,
+                b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9'
+                | b'-' | b'_' | b'.' | b'!' | b'~' | b'*' | 0x27 | b'(' | b')'
+            );
+            if unreserved {
+                encoded.push(b);
+            } else {
+                encoded.push(b'%');
+                encoded.push(HEX[(b >> 4) as usize]);
+                encoded.push(HEX[(b & 0x0f) as usize]);
+            }
+        }
+        let mut decoded = Vec::with_capacity(input.len());
+        let mut i = 0usize;
+        while i < encoded.len() {
+            if encoded[i] == b'%' {
+                prop_assert!(i + 2 < encoded.len(), "%XX truncated at {i}");
+                // decode_percent_at returns the ABSOLUTE next index (i + 3).
+                let (byte, next) = decode_percent_at(&encoded, i).unwrap_or_else(|| {
+                    panic!("decode_percent_at failed at {i} in {:?}", &encoded[i..])
+                });
+                decoded.push(byte);
+                i = next;
+            } else {
+                decoded.push(encoded[i]);
+                i += 1;
+            }
+        }
+        prop_assert_eq!(decoded, input);
+    }
+}
+
+/// decode_percent_at round-trips a manually percent-encoded byte (`%HH`).
+#[test]
+fn decode_percent_at_roundtrip_encoded_byte() {
+    const HEX: &[u8; 16] = b"0123456789abcdef";
+    for b in 0u16..256u16 {
+        let byte = b as u8;
+        let enc = [b'%', HEX[(byte >> 4) as usize], HEX[(byte & 0xf) as usize]];
+        assert_eq!(decode_percent_at(&enc, 0), Some((byte, 3)));
+    }
+}

package/rust/selection.rs

@@ -0,0 +1,95 @@
+//! # Selection — which ops the public API should back with native vs TS code.
+//!
+//! This is the SINGLE SOURCE OF TRUTH for the native-vs-TS decision, owned by
+//! the castrum library itself (not by consumers). It is **auto-selected by the
+//! benchmark script**: `scripts/select-native.ts` measures the addon against a
+//! representative pure-TS implementation for every op on the target machine and
+//! writes the winning implementation to `src/selection.json` (committed,
+//! generated — NOT hand-maintained). This module embeds that generated data at
+//! build time (`include_str!`) and serves it through `#[napi] op_impl`.
+//!
+//! Flow:
+//!   bun scripts/select-native.ts --write   # auto-select → writes src/selection.json
+//!   bun run build                          # embeds the selected decisions into the .node
+//!   bun scripts/select-native.ts --check   # CI gate: fail on decisive drift
+//!
+//! Consumers read `opImpl(op)` ONCE at load time and bind each operation to a
+//! fixed implementation (TS or native) — they do NOT swap underneath at runtime.
+
+use std::collections::HashMap;
+use std::sync::OnceLock;
+
+use napi_derive::napi;
+
+/// The generated benchmark data (see `src/selection.json`). Embedded at build
+/// time so the `.node` ships the decisions without a runtime file read.
+const SELECTION_JSON: &str = include_str!("../src/selection.json");
+
+/// `op name → "native" | "js"`, parsed once from the generated JSON.
+fn selection_map() -> &'static HashMap<String, String> {
+    static MAP: OnceLock<HashMap<String, String>> = OnceLock::new();
+    MAP.get_or_init(|| {
+        let value: serde_json::Value =
+            serde_json::from_str(SELECTION_JSON).expect("selection.json must be valid JSON");
+        let mut map = HashMap::new();
+        if let Some(ops) = value.get("ops").and_then(serde_json::Value::as_object) {
+            for (op, decision) in ops {
+                if let Some(impl_name) = decision.get("impl").and_then(serde_json::Value::as_str) {
+                    map.insert(op.clone(), impl_name.to_string());
+                }
+            }
+        }
+        map
+    })
+}
+
+/// The auto-selected native-vs-TS decision for `op`.
+///
+/// Returns `"native"` when the public API should back `op` with the Rust addon,
+/// `"js"` when it should run the pure-TS implementation, or `None` for unknown
+/// ops. The data comes from `src/selection.json` — generated by
+/// `scripts/select-native.ts --write`, never hand-written here.
+#[napi]
+pub fn op_impl(op: String) -> Option<String> {
+    selection_map().get(&op).cloned()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn map_is_populated_from_generated_json() {
+        let map = selection_map();
+        assert!(!map.is_empty(), "selection.json must contain ops");
+    }
+
+    #[test]
+    fn every_entry_is_native_or_js() {
+        let map = selection_map();
+        for (op, impl_name) in map {
+            assert!(
+                impl_name == "native" || impl_name == "js",
+                "op {op} has invalid impl {impl_name}"
+            );
+        }
+    }
+
+    #[test]
+    fn unknown_op_is_none() {
+        assert_eq!(op_impl("doesNotExist".to_string()), None);
+        assert_eq!(op_impl("".to_string()), None);
+    }
+
+    #[test]
+    fn well_established_decisions_hold() {
+        // These just pin the direction of the auto-selected data so a bad
+        // regeneration is caught; the values themselves come from the bench.
+        assert_eq!(op_impl("fnv1a64".to_string()).as_deref(), Some("native"));
+        assert_eq!(op_impl("validateEmail".to_string()).as_deref(), Some("js"));
+        assert_eq!(
+            op_impl("gzipDecompress".to_string()).as_deref(),
+            Some("native")
+        );
+    }
+}