castrum 0.7.0

package/rust/json_ser.rs

@@ -0,0 +1,429 @@
+// rust/json_ser.rs — JSON serialization helpers extracted from ingress.rs
+// Zero-alloc JSON escaping, cookie→JSON and query→JSON conversion
+// Uses memchr-based skip for bulk unescaped bytes (~95% path)
+
+use crate::util::trim_ascii_whitespace;
+use napi::{Error, Result};
+
+const JSON_HEX_LOWER: &[u8; 16] = b"0123456789abcdef";
+
+/// Determine whether bytes are valid UTF-8 (cached via a bit check).
+#[inline(always)]
+fn is_valid_utf8(bytes: &[u8]) -> bool {
+    // Fast path: small ASCII-only strings are very common
+    if bytes.is_empty() {
+        return true;
+    }
+    // Check first byte — if >= 0x80, we need a real check
+    // For pure ASCII we can skip the full simdutf8 check
+    if bytes.iter().all(|&b| b < 0x80) {
+        return true;
+    }
+    std::str::from_utf8(bytes).is_ok()
+}
+
+/// Compute the JSON-escaped length without writing.
+/// Uses memchr to find special characters in bulk.
+#[inline(always)]
+pub fn json_escaped_len(bytes: &[u8]) -> usize {
+    if is_valid_utf8(bytes) {
+        json_escaped_len_impl(bytes)
+    } else {
+        bytes.len().saturating_mul(6)
+    }
+}
+
+/// Inner: assumes valid UTF-8, uses memchr for skip.
+#[inline(always)]
+fn json_escaped_len_impl(bytes: &[u8]) -> usize {
+    let mut total = bytes.len(); // start with all bytes as 1
+    let mut offset = 0;
+
+    // Use memchr3 to find any of the special chars: ", \, \n
+    while let Some(pos) = memchr::memchr3(b'"', b'\\', b'\n', &bytes[offset..]) {
+        let abs = offset + pos;
+        let b = bytes[abs];
+        offset = abs + 1;
+
+        total += match b {
+            b'\\' | b'"' | b'\n' => 1, // 2 bytes instead of 1 → +1
+            _ => {
+                // \r, \t, \x08, \x0c: also 2 bytes
+                if b == b'\r' || b == b'\t' || b == 0x08 || b == 0x0c {
+                    1
+                } else if b < 0x20 {
+                    // \uXXXX → 6 bytes instead of 1 → +5
+                    5
+                } else {
+                    0
+                }
+            }
+        };
+    }
+
+    // Now check for remaining control characters (<0x20) that memchr3 missed
+    // (tab and \r are 0x09 and 0x0d which are < 0x20 but already handled above)
+    for &b in &bytes[offset..] {
+        if b < 0x20 && b != b'\n' && b != b'\r' && b != b'\t' && b != 0x08 && b != 0x0c {
+            total += 5; // \uXXXX
+        }
+    }
+
+    total
+}
+
+/// Write JSON-escaped bytes into the buffer at the current position.
+/// Returns the number of bytes written.
+#[inline(always)]
+pub fn write_json_escaped(out: &mut [u8], pos: &mut usize, bytes: &[u8]) -> usize {
+    let start = *pos;
+    if is_valid_utf8(bytes) {
+        write_json_escaped_utf8(out, pos, bytes);
+    } else {
+        // Binary: escape every byte as \u00XX
+        for &b in bytes {
+            out[*pos] = b'\\';
+            out[*pos + 1] = b'u';
+            out[*pos + 2] = b'0';
+            out[*pos + 3] = b'0';
+            out[*pos + 4] = JSON_HEX_LOWER[(b >> 4) as usize];
+            out[*pos + 5] = JSON_HEX_LOWER[(b & 0x0f) as usize];
+            *pos += 6;
+        }
+    }
+    *pos - start
+}
+
+/// Write escaped bytes for valid UTF-8 input.
+#[inline(always)]
+fn write_json_escaped_utf8(out: &mut [u8], pos: &mut usize, bytes: &[u8]) {
+    let mut offset = 0usize;
+
+    while let Some(mut idx) = memchr::memchr3(b'"', b'\\', b'\n', &bytes[offset..]) {
+        idx += offset;
+
+        // Copy unescaped bytes before the special character
+        let unescaped = &bytes[offset..idx];
+        if !unescaped.is_empty() {
+            out[*pos..*pos + unescaped.len()].copy_from_slice(unescaped);
+            *pos += unescaped.len();
+        }
+
+        let b = bytes[idx];
+        match b {
+            b'"' | b'\\' | b'\n' | b'\r' | b'\t' | 0x08 | 0x0c => {
+                let esc = match b {
+                    b'"' => b'"',
+                    b'\\' => b'\\',
+                    b'\n' => b'n',
+                    b'\r' => b'r',
+                    b'\t' => b't',
+                    0x08 => b'b',
+                    0x0c => b'f',
+                    _ => unreachable!(),
+                };
+                out[*pos] = b'\\';
+                out[*pos + 1] = esc;
+                *pos += 2;
+            }
+            _ => {
+                // Control character (< 0x20) → \u00XX
+                out[*pos] = b'\\';
+                out[*pos + 1] = b'u';
+                out[*pos + 2] = b'0';
+                out[*pos + 3] = b'0';
+                out[*pos + 4] = JSON_HEX_LOWER[(b >> 4) as usize];
+                out[*pos + 5] = JSON_HEX_LOWER[(b & 0x0f) as usize];
+                *pos += 6;
+            }
+        }
+
+        offset = idx + 1;
+    }
+
+    // Copy remaining
+    let remaining = &bytes[offset..];
+    if !remaining.is_empty() {
+        // Check for remaining low control chars that memchr3 missed (\r, \t, etc.)
+        let mut i = 0;
+        while i < remaining.len() {
+            let b = remaining[i];
+            match b {
+                b'\r' | b'\t' | 0x08 | 0x0c => {
+                    let esc = match b {
+                        b'\r' => b'r',
+                        b'\t' => b't',
+                        0x08 => b'b',
+                        0x0c => b'f',
+                        _ => unreachable!(),
+                    };
+                    out[*pos] = b'\\';
+                    out[*pos + 1] = esc;
+                    *pos += 2;
+                    i += 1;
+                }
+                b if b < 0x20 => {
+                    out[*pos] = b'\\';
+                    out[*pos + 1] = b'u';
+                    out[*pos + 2] = b'0';
+                    out[*pos + 3] = b'0';
+                    out[*pos + 4] = JSON_HEX_LOWER[(b >> 4) as usize];
+                    out[*pos + 5] = JSON_HEX_LOWER[(b & 0x0f) as usize];
+                    *pos += 6;
+                    i += 1;
+                }
+                _ => {
+                    // Bulk copy of safe bytes up to next special char
+                    let remaining_slice = &remaining[i..];
+                    let next_special = remaining_slice.iter().position(|&c| {
+                        c < 0x20
+                    });
+                    match next_special {
+                        Some(n) => {
+                            out[*pos..*pos + n].copy_from_slice(&remaining_slice[..n]);
+                            *pos += n;
+                            i += n;
+                        }
+                        None => {
+                            out[*pos..*pos + remaining_slice.len()].copy_from_slice(remaining_slice);
+                            *pos += remaining_slice.len();
+                            i = remaining.len();
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// Parse cookies from `input` and write JSON to `out` with max_pairs limit.
+#[inline]
+pub fn cookie_json_into_slice(input: &[u8], out: &mut [u8], max_pairs: usize) -> Result<usize> {
+    if out.len() < 2 {
+        return Err(Error::from_reason("output buffer too small for cookie JSON"));
+    }
+
+    out[0] = b'{';
+    let mut pos = 1usize;
+    let mut count = 0usize;
+
+    for pair in input.split(|&b| b == b';') {
+        let pair = trim_ascii_whitespace(pair);
+        if pair.is_empty() {
+            continue;
+        }
+
+        let (name, value) = match pair.iter().position(|&b| b == b'=') {
+            Some(eq) => (&pair[..eq], &pair[eq + 1..]),
+            None => (pair, &[][..]),
+        };
+
+        let name = trim_ascii_whitespace(name);
+        let value = trim_ascii_whitespace(value);
+
+        if name.is_empty() {
+            continue;
+        }
+
+        if count >= max_pairs {
+            break;
+        }
+
+        let needed = (if count == 0 { 0 } else { 1 })
+            + 5
+            + json_escaped_len(name)
+            + json_escaped_len(value);
+
+        if needed > out.len().saturating_sub(pos) {
+            return Err(Error::from_reason("output buffer too small for cookie JSON"));
+        }
+
+        if count != 0 {
+            out[pos] = b',';
+            pos += 1;
+        }
+
+        out[pos] = b'"';
+        pos += 1;
+        write_json_escaped(out, &mut pos, name);
+        out[pos] = b'"';
+        pos += 1;
+        out[pos] = b':';
+        pos += 1;
+        out[pos] = b'"';
+        pos += 1;
+        write_json_escaped(out, &mut pos, value);
+        out[pos] = b'"';
+        pos += 1;
+
+        count += 1;
+    }
+
+    if pos + 1 > out.len() {
+        return Err(Error::from_reason("output buffer too small for cookie JSON"));
+    }
+
+    out[pos] = b'}';
+    pos += 1;
+    Ok(pos)
+}
+
+/// Parse packed query pairs and write JSON to `out` with max_pairs limit.
+#[inline]
+pub fn packed_pairs_to_json_into_slice(
+    packed: &[u8],
+    out: &mut [u8],
+    max_pairs: usize,
+) -> Result<usize> {
+    if out.len() < 2 {
+        return Err(Error::from_reason("output buffer too small for packed pairs JSON"));
+    }
+
+    if packed.len() < 4 {
+        out[0..2].copy_from_slice(b"{}");
+        return Ok(2);
+    }
+
+    let count = crate::util::read_u32_le(packed, 0)? as usize;
+
+    out[0] = b'{';
+    let mut pos = 1usize;
+    let mut src = 4usize;
+    let mut written_pairs = 0usize;
+
+    for _ in 0..count {
+        if written_pairs >= max_pairs {
+            break;
+        }
+
+        let key_len = crate::util::read_u32_le(packed, src)? as usize;
+        src += 4;
+
+        if src + key_len > packed.len() {
+            return Err(Error::from_reason("packed pairs: truncated key"));
+        }
+
+        let key = &packed[src..src + key_len];
+        src += key_len;
+
+        let val_len = crate::util::read_u32_le(packed, src)? as usize;
+        src += 4;
+
+        if src + val_len > packed.len() {
+            return Err(Error::from_reason("packed pairs: truncated value"));
+        }
+
+        let val = &packed[src..src + val_len];
+        src += val_len;
+
+        let needed = (if written_pairs == 0 { 0 } else { 1 })
+            + 5
+            + json_escaped_len(key)
+            + json_escaped_len(val);
+
+        if needed > out.len().saturating_sub(pos) {
+            return Err(Error::from_reason("output buffer too small for packed pairs JSON"));
+        }
+
+        if written_pairs != 0 {
+            out[pos] = b',';
+            pos += 1;
+        }
+
+        out[pos] = b'"';
+        pos += 1;
+        write_json_escaped(out, &mut pos, key);
+        out[pos] = b'"';
+        pos += 1;
+        out[pos] = b':';
+        pos += 1;
+        out[pos] = b'"';
+        pos += 1;
+        write_json_escaped(out, &mut pos, val);
+        out[pos] = b'"';
+        pos += 1;
+
+        written_pairs += 1;
+    }
+
+    if pos + 1 > out.len() {
+        return Err(Error::from_reason("output buffer too small for packed pairs JSON"));
+    }
+
+    out[pos] = b'}';
+    pos += 1;
+    Ok(pos)
+}
+
+/// Write the full metadata JSON envelope (requestId, path, cookies, query).
+#[inline]
+pub fn write_full_body_json(
+    out: &mut [u8],
+    pos: usize,
+    request_id: &[u8],
+    path: &[u8],
+    cookies_start: usize,
+    cookies_len: usize,
+    query_start: usize,
+    query_len: usize,
+) -> usize {
+    const P1: &[u8] = b"{\"ok\":true,\"requestId\":\"";
+    const P2: &[u8] = b"\",\"path\":\"";
+    const P3: &[u8] = b"\",\"cookies\":";
+    const P4: &[u8] = b",\"query\":";
+
+    let cookies_eff_len = if cookies_len > 0 { cookies_len } else { 2 };
+    let query_eff_len = if query_len > 0 { query_len } else { 2 };
+
+    let required = P1.len()
+        + json_escaped_len(request_id)
+        + P2.len()
+        + json_escaped_len(path)
+        + P3.len()
+        + cookies_eff_len
+        + P4.len()
+        + query_eff_len
+        + 1;
+
+    let end = match pos.checked_add(required) {
+        Some(v) => v,
+        None => return 0,
+    };
+
+    if end > out.len() {
+        return 0;
+    }
+
+    let mut wp = pos;
+    out[wp..wp + P1.len()].copy_from_slice(P1);
+    wp += P1.len();
+    write_json_escaped(out, &mut wp, request_id);
+    out[wp..wp + P2.len()].copy_from_slice(P2);
+    wp += P2.len();
+    write_json_escaped(out, &mut wp, path);
+    out[wp..wp + P3.len()].copy_from_slice(P3);
+    wp += P3.len();
+
+    if cookies_len > 0 {
+        out.copy_within(cookies_start..cookies_start + cookies_len, wp);
+        wp += cookies_len;
+    } else {
+        out[wp..wp + 2].copy_from_slice(b"{}");
+        wp += 2;
+    }
+
+    out[wp..wp + P4.len()].copy_from_slice(P4);
+    wp += P4.len();
+
+    if query_len > 0 {
+        out.copy_within(query_start..query_start + query_len, wp);
+        wp += query_len;
+    } else {
+        out[wp..wp + 2].copy_from_slice(b"{}");
+        wp += 2;
+    }
+
+    out[wp] = b'}';
+    wp += 1;
+    wp - pos
+}

package/rust/lib.rs

@@ -0,0 +1,48 @@
+#![allow(clippy::not_unsafe_ptr_arg_deref)]
+
+use mimalloc::MiMalloc;
+
+#[global_allocator]
+static GLOBAL: MiMalloc = MiMalloc;
+
+// ── napi-rs addon modules ─────────────────────────────────────────
+// Each module is exported to JS via #[napi]. Modules keep a pure-Rust
+// core (no napi types in signatures) so they stay testable and
+// composable; only the entry points use napi types.
+pub mod output;
+pub mod method;
+pub mod headers;
+pub mod json_ser;
+pub mod cors;
+pub mod proxy;
+pub mod terminal;
+
+pub mod util;
+
+pub mod ip_trust;
+pub mod rate_limit;
+
+pub mod json_schema;
+
+pub mod cookie_parser;
+pub mod hashing;
+pub mod hmac_sha256;
+pub mod http_parser;
+pub mod json_ops;
+pub mod json_patch_ops;
+pub mod mime_lookup;
+pub mod query_parser;
+pub mod random_token;
+pub mod url_codec;
+pub mod validation;
+pub mod websocket;
+
+pub mod batch;
+
+pub mod ingress_constants;
+
+pub mod ingress;
+
+// ── Unit tests (cargo test) ───────────────────────────────────────
+#[cfg(test)]
+mod unit_tests;

package/rust/method.rs

@@ -0,0 +1,141 @@
+// rust/method.rs — Extracted HTTP method classification
+// Optimized for Bun 1.4: uses u64 word-at-a-time comparison with zero allocation
+
+#[inline(always)]
+fn load_u64_padded(bytes: &[u8]) -> u64 {
+    let mut buf = [0u8; 8];
+    let len = bytes.len().min(8);
+    buf[..len].copy_from_slice(&bytes[..len]);
+    u64::from_le_bytes(buf)
+}
+
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub enum MethodKind {
+    Get,
+    Head,
+    Post,
+    Put,
+    Patch,
+    Delete,
+    Options,
+    Other,
+}
+
+const METHOD_GET: u64 = u64::from_le_bytes(*b"GET\0\0\0\0\0");
+const METHOD_HEAD: u64 = u64::from_le_bytes(*b"HEAD\0\0\0\0");
+const METHOD_POST: u64 = u64::from_le_bytes(*b"POST\0\0\0\0");
+const METHOD_PUT: u64 = u64::from_le_bytes(*b"PUT\0\0\0\0\0");
+const METHOD_PATCH: u64 = u64::from_le_bytes(*b"PATCH\0\0\0");
+const METHOD_DELETE: u64 = u64::from_le_bytes(*b"DELETE\0\0");
+const METHOD_OPTIONS: u64 = u64::from_le_bytes(*b"OPTIONS\0");
+
+impl MethodKind {
+    /// Classify HTTP method from a &str.
+    #[inline(always)]
+    pub fn from_str(method: &str) -> Self {
+        let bytes = method.as_bytes();
+        let loaded = load_u64_padded(bytes);
+
+        match bytes.len() {
+            3 if loaded == METHOD_GET => Self::Get,
+            3 if loaded == METHOD_PUT => Self::Put,
+            4 if loaded == METHOD_POST => Self::Post,
+            4 if loaded == METHOD_HEAD => Self::Head,
+            5 if loaded == METHOD_PATCH => Self::Patch,
+            6 if loaded == METHOD_DELETE => Self::Delete,
+            7 if loaded == METHOD_OPTIONS => Self::Options,
+            _ => Self::Other,
+        }
+    }
+
+    /// Classify HTTP method from raw bytes with case-insensitive comparison.
+    /// Avoids heap allocation from to_ascii_uppercase().
+    #[inline(always)]
+    pub fn from_bytes_ignore_case(bytes: &[u8]) -> Self {
+        let len = bytes.len();
+        if len > 7 {
+            return Self::Other;
+        }
+
+        let loaded = load_u64_padded(bytes);
+
+        // Mask the 5th bit (0x20) of all alphabetic bytes for case-insensitive comparison.
+        let lower = loaded | 0x2020_2020_2020_2020;
+
+        // Zero the bytes beyond `len` on BOTH operands. The mask must be applied
+        // to the reference constants too, otherwise the padding bytes (0x20 after
+        // the OR above) never match and every method classifies as Other.
+        let mask = match len {
+            3 => 0x00FF_FFFF_FFFF_FFFFu64,
+            4 => 0x0000_FFFF_FFFF_FFFFu64,
+            5 => 0x0000_00FF_FFFF_FFFFu64,
+            6 => 0x0000_0000_FFFF_FFFFu64,
+            7 => 0x0000_0000_00FF_FFFFu64,
+            _ => 0,
+        };
+
+        let lower_masked = lower & mask;
+        let get = (METHOD_GET | 0x2020_2020_2020_2020) & mask;
+        let put = (METHOD_PUT | 0x2020_2020_2020_2020) & mask;
+        let post = (METHOD_POST | 0x2020_2020_2020_2020) & mask;
+        let head = (METHOD_HEAD | 0x2020_2020_2020_2020) & mask;
+        let patch = (METHOD_PATCH | 0x2020_2020_2020_2020) & mask;
+        let delete = (METHOD_DELETE | 0x2020_2020_2020_2020) & mask;
+        let options = (METHOD_OPTIONS | 0x2020_2020_2020_2020) & mask;
+
+        match len {
+            3 if lower_masked == get => Self::Get,
+            3 if lower_masked == put => Self::Put,
+            4 if lower_masked == post => Self::Post,
+            4 if lower_masked == head => Self::Head,
+            5 if lower_masked == patch => Self::Patch,
+            6 if lower_masked == delete => Self::Delete,
+            7 if lower_masked == options => Self::Options,
+            _ => Self::Other,
+        }
+    }
+
+    /// Classify from u8 discriminator (0-6).
+    #[inline(always)]
+    pub fn from_u8(v: u8) -> Self {
+        match v {
+            0 => Self::Get,
+            1 => Self::Head,
+            2 => Self::Post,
+            3 => Self::Put,
+            4 => Self::Patch,
+            5 => Self::Delete,
+            6 => Self::Options,
+            _ => Self::Other,
+        }
+    }
+
+    /// Returns true if the method may carry a body.
+    #[inline(always)]
+    pub fn may_have_body(&self) -> bool {
+        matches!(self, Self::Post | Self::Put | Self::Patch | Self::Delete)
+    }
+
+    /// Returns u8 discriminant for packed format.
+    #[inline(always)]
+    pub fn to_u8(&self) -> u8 {
+        match self {
+            Self::Get => 0,
+            Self::Head => 1,
+            Self::Post => 2,
+            Self::Put => 3,
+            Self::Patch => 4,
+            Self::Delete => 5,
+            Self::Options => 6,
+            Self::Other => 7,
+        }
+    }
+}
+
+impl MethodKind {
+    /// Bitmask representation for fast CORS method matching.
+    #[inline(always)]
+    pub fn bit(&self) -> u16 {
+        1u16 << (self.to_u8() as u16)
+    }
+}

package/rust/mime_lookup.rs

@@ -0,0 +1,76 @@
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+use phf::{phf_map, Map};
+
+const OCTET_STREAM: &str = "application/octet-stream";
+
+static MIME_TABLE: Map<&'static str, &'static str> = phf_map! {
+    "json" => "application/json",
+    "js" => "text/javascript",
+    "mjs" => "text/javascript",
+    "cjs" => "text/javascript",
+    "html" => "text/html",
+    "htm" => "text/html",
+    "css" => "text/css",
+    "csv" => "text/csv",
+    "xml" => "application/xml",
+    "txt" => "text/plain",
+    "png" => "image/png",
+    "jpg" => "image/jpeg",
+    "jpeg" => "image/jpeg",
+    "gif" => "image/gif",
+    "webp" => "image/webp",
+    "avif" => "image/avif",
+    "svg" => "image/svg+xml",
+    "ico" => "image/x-icon",
+    "pdf" => "application/pdf",
+    "zip" => "application/zip",
+    "gz" => "application/gzip",
+    "wasm" => "application/wasm",
+    "map" => "application/json",
+    "woff" => "font/woff",
+    "woff2" => "font/woff2",
+    "ttf" => "font/ttf",
+    "otf" => "font/otf",
+    "mp4" => "video/mp4",
+    "webm" => "video/webm",
+    "mp3" => "audio/mpeg",
+    "ogg" => "audio/ogg",
+};
+
+#[napi]
+pub fn mime_from_extension(ext: Uint8Array) -> Buffer {
+    let bytes = ext.as_ref();
+
+    let text = match std::str::from_utf8(bytes) {
+        Ok(text) => text,
+        Err(_) => return Buffer::from(OCTET_STREAM.as_bytes().to_vec()),
+    };
+
+    let text = text.trim_start_matches('.');
+
+    let mut stack = [0u8; 64];
+
+    let lower_owned: String;
+
+    let lower: &str = if text.len() <= stack.len() {
+        for (i, b) in text.bytes().enumerate() {
+            stack[i] = b.to_ascii_lowercase();
+        }
+
+        match std::str::from_utf8(&stack[..text.len()]) {
+            Ok(s) => s,
+            Err(_) => return Buffer::from(OCTET_STREAM.as_bytes().to_vec()),
+        }
+    } else {
+        lower_owned = text.to_ascii_lowercase();
+        &lower_owned
+    };
+
+    if let Some(mime) = MIME_TABLE.get(lower) {
+        return Buffer::from(mime.as_bytes().to_vec());
+    }
+
+    let guessed = mime_guess::from_ext(lower).first_or_octet_stream();
+    Buffer::from(guessed.essence_str().as_bytes().to_vec())
+}