castrum 0.7.0

package/rust/output.rs

@@ -0,0 +1,238 @@
+// rust/output.rs — Ingress output buffer layout and low-level write helpers
+// Extracted from ingress.rs for composability
+// Uses Buf as a lightweight slice cursor for zero-cost output serialization
+
+use std::ptr;
+
+// ── Output buffer binary layout ───────────────────────────────────
+pub const OUT_VERDICT: usize = 0;
+pub const OUT_ERROR_CODE: usize = 1;
+pub const OUT_STATUS: usize = 2;
+pub const OUT_FLAGS: usize = 4;
+pub const OUT_RATE_LIMIT: usize = 8;
+pub const OUT_RATE_REMAINING: usize = 12;
+pub const OUT_RATE_RESET: usize = 16;
+pub const OUT_RETRY_AFTER: usize = 24;
+pub const OUT_COOKIES_JSON_LEN: usize = 32;
+pub const OUT_QUERY_JSON_LEN: usize = 36;
+pub const OUT_HEADER_VARIANT: usize = 40;
+pub const OUT_BODY_JSON_LEN: usize = 44;
+pub const OUT_DATA_START: usize = 48;
+
+// ── Flags ─────────────────────────────────────────────────────────
+pub const FLAG_HAS_COOKIES: u32 = 1 << 0;
+pub const FLAG_HAS_QUERY: u32 = 1 << 1;
+pub const FLAG_BODY_VALID_JSON: u32 = 1 << 2;
+pub const FLAG_SCHEMA_VALID: u32 = 1 << 3;
+pub const FLAG_CORS_ALLOWED: u32 = 1 << 4;
+pub const FLAG_IS_PREFLIGHT: u32 = 1 << 5;
+pub const FLAG_RATE_LIMITED: u32 = 1 << 6;
+pub const FLAG_HTTPS: u32 = 1 << 7;
+pub const FLAG_TRUSTED_PROXY: u32 = 1 << 8;
+pub const FLAG_BODY_TRUNCATED: u32 = 1 << 9;
+
+// ── Header variant bits ───────────────────────────────────────────
+pub const HV_JSON: u8 = 1 << 0;
+pub const HV_CORS_SIMPLE: u8 = 1 << 1;
+pub const HV_CORS_PREFLIGHT: u8 = 1 << 2;
+pub const HV_RATE_ACTIVE: u8 = 1 << 3;
+pub const HV_RATE_LIMITED: u8 = 1 << 4;
+
+// ── Error codes ───────────────────────────────────────────────────
+pub const ERR_CODE_NONE: u8 = 0;
+pub const ERR_CODE_CORS_PREFLIGHT: u8 = 1;
+pub const ERR_CODE_RATE_LIMITED: u8 = 2;
+pub const ERR_CODE_BODY_TOO_LARGE: u8 = 3;
+pub const ERR_CODE_INVALID_JSON: u8 = 4;
+pub const ERR_CODE_SCHEMA_VALIDATION: u8 = 5;
+pub const ERR_CODE_BAD_REQUEST: u8 = 6;
+pub const ERR_CODE_REQUEST_TOO_LARGE: u8 = 7;
+
+// ── Unsafe output helpers ─────────────────────────────────────────
+
+/// Write a u16 at the given position in little-endian format.
+#[inline(always)]
+pub unsafe fn write_u16(out: &mut [u8], pos: usize, value: u16) {
+    ptr::copy_nonoverlapping(value.to_le_bytes().as_ptr(), out.as_mut_ptr().add(pos), 2);
+}
+
+/// Write a u32 at the given position in little-endian format.
+#[inline(always)]
+pub unsafe fn write_u32(out: &mut [u8], pos: usize, value: u32) {
+    ptr::copy_nonoverlapping(value.to_le_bytes().as_ptr(), out.as_mut_ptr().add(pos), 4);
+}
+
+/// Write a u64 at the given position in little-endian format.
+#[inline(always)]
+pub unsafe fn write_u64(out: &mut [u8], pos: usize, value: u64) {
+    ptr::copy_nonoverlapping(value.to_le_bytes().as_ptr(), out.as_mut_ptr().add(pos), 8);
+}
+
+// ── Slice cursor for sequential writing ───────────────────────────
+
+/// A lightweight zero-cost cursor over a mutable byte slice.
+/// Used for sequential writes without bounds checking (caller must ensure capacity).
+pub struct Buf<'a> {
+    slice: &'a mut [u8],
+    pos: usize,
+}
+
+impl<'a> Buf<'a> {
+    /// Create a new cursor starting at the beginning of the given slice.
+    #[inline(always)]
+    pub fn new(slice: &'a mut [u8]) -> Self {
+        Self { slice, pos: 0 }
+    }
+
+    /// The current write position.
+    #[inline(always)]
+    pub fn pos(&self) -> usize {
+        self.pos
+    }
+
+    /// Returns true if there is enough remaining capacity.
+    #[inline(always)]
+    pub fn can_write(&self, n: usize) -> bool {
+        self.pos + n <= self.slice.len()
+    }
+
+    /// Advance the cursor by `n` bytes (caller must have written to them).
+    #[inline(always)]
+    pub fn advance(&mut self, n: usize) {
+        self.pos += n;
+    }
+
+    /// Write a single byte.
+    #[inline(always)]
+    pub fn push(&mut self, b: u8) {
+        self.slice[self.pos] = b;
+        self.pos += 1;
+    }
+
+    /// Write a byte slice.
+    #[inline(always)]
+    pub fn write(&mut self, bytes: &[u8]) {
+        let end = self.pos + bytes.len();
+        self.slice[self.pos..end].copy_from_slice(bytes);
+        self.pos = end;
+    }
+
+    /// Write a u8 at the current position.
+    #[inline(always)]
+    pub fn write_u8(&mut self, value: u8) {
+        self.slice[self.pos] = value;
+        self.pos += 1;
+    }
+
+    /// Write a u16 in little-endian at the current position.
+    #[inline(always)]
+    pub fn write_u16(&mut self, value: u16) {
+        let end = self.pos + 2;
+        self.slice[self.pos..end].copy_from_slice(&value.to_le_bytes());
+        self.pos = end;
+    }
+
+    /// Write a u32 in little-endian at the current position.
+    #[inline(always)]
+    pub fn write_u32(&mut self, value: u32) {
+        let end = self.pos + 4;
+        self.slice[self.pos..end].copy_from_slice(&value.to_le_bytes());
+        self.pos = end;
+    }
+
+    /// Write a u32 at a specific position (patch).
+    #[inline(always)]
+    pub fn patch_u32(&mut self, pos: usize, value: u32) {
+        self.slice[pos..pos + 4].copy_from_slice(&value.to_le_bytes());
+    }
+
+    /// Get a mutable sub-slice starting at current position.
+    #[inline(always)]
+    pub fn remaining_mut(&mut self) -> &mut [u8] {
+        &mut self.slice[self.pos..]
+    }
+
+    /// Get a sub-slice of the written area.
+    #[inline(always)]
+    pub fn written(&self) -> &[u8] {
+        &self.slice[..self.pos]
+    }
+}
+
+// ── Output header writer ──────────────────────────────────────────
+
+/// Compute the header variant byte from booleans.
+#[inline(always)]
+pub fn compute_header_variant(
+    cors_ok: bool,
+    is_preflight: bool,
+    rate_active: bool,
+    rate_limited: bool,
+    wants_json: bool,
+) -> u8 {
+    let mut hv: u8 = 0;
+    if wants_json {
+        hv |= HV_JSON;
+    }
+    if cors_ok && !is_preflight {
+        hv |= HV_CORS_SIMPLE;
+    }
+    if is_preflight {
+        hv |= HV_CORS_PREFLIGHT;
+    }
+    if rate_active {
+        hv |= HV_RATE_ACTIVE;
+    }
+    if rate_limited {
+        hv |= HV_RATE_LIMITED;
+    }
+    hv
+}
+
+/// Write the output header into the buffer. Returns the total written bytes 
+/// (header + data payload sizes).
+#[inline(always)]
+pub fn write_output_header(
+    out: &mut [u8],
+    verdict: u8,
+    error_code: u8,
+    status: u16,
+    flags: u32,
+    rate_limit: u32,
+    rate_remaining: u32,
+    rate_reset_ms: u64,
+    retry_after_ms: u64,
+    cookies_json_len: u32,
+    query_json_len: u32,
+    header_variant: u8,
+    body_json_len: u32,
+) -> usize {
+    let status = if status == 101 || (200u16..=599u16).contains(&status) {
+        status
+    } else {
+        500
+    };
+
+    unsafe {
+        out[OUT_VERDICT] = verdict;
+        out[OUT_ERROR_CODE] = error_code;
+        write_u16(out, OUT_STATUS, status);
+        write_u32(out, OUT_FLAGS, flags);
+        write_u32(out, OUT_RATE_LIMIT, rate_limit);
+        write_u32(out, OUT_RATE_REMAINING, rate_remaining);
+        write_u64(out, OUT_RATE_RESET, rate_reset_ms);
+        write_u64(out, OUT_RETRY_AFTER, retry_after_ms);
+        write_u32(out, OUT_COOKIES_JSON_LEN, cookies_json_len);
+        write_u32(out, OUT_QUERY_JSON_LEN, query_json_len);
+        out[OUT_HEADER_VARIANT] = header_variant;
+        out[OUT_HEADER_VARIANT + 1] = 0;
+        out[OUT_HEADER_VARIANT + 2] = 0;
+        out[OUT_HEADER_VARIANT + 3] = 0;
+        write_u32(out, OUT_BODY_JSON_LEN, body_json_len);
+    }
+
+    OUT_DATA_START
+        + cookies_json_len as usize
+        + query_json_len as usize
+        + body_json_len as usize
+}

package/rust/proxy.rs

@@ -0,0 +1,90 @@
+// rust/proxy.rs — Proxy trust, IP resolution, and HTTPS detection
+// Extracted from ingress.rs for composability
+
+use crate::headers::HeaderRefs;
+use crate::ip_trust::ProxyTrustMode;
+use crate::util::trim_ascii_whitespace;
+
+/// Detect whether the request is HTTPS based on URL, proxy trust, and headers.
+#[inline]
+pub fn detect_https(
+    https_fixed: Option<bool>,
+    proxy_trust: &ProxyTrustMode,
+    url: &[u8],
+    headers: &HeaderRefs<'_>,
+    peer_trusted: bool,
+) -> bool {
+    if let Some(v) = https_fixed {
+        return v;
+    }
+
+    if url.starts_with(b"https://") || url.starts_with(b"wss://") {
+        return true;
+    }
+
+    if !proxy_trust.is_none() && peer_trusted && headers.has_xfp() {
+        if let Some(xfp) = headers.x_forwarded_proto() {
+            return trim_ascii_whitespace(xfp) == b"https";
+        }
+    }
+
+    false
+}
+
+/// Compute a rate-limiting key from the resolved IP.
+#[inline]
+pub fn rate_key_from_ip(ip: &crate::ip_trust::ResolvedIp, seed: u64) -> u64 {
+    ip.rate_key(seed)
+}
+
+// ── URL helpers ───────────────────────────────────────────────────
+
+/// Extract the path component from a URL.
+#[inline]
+pub fn extract_path(url: &[u8]) -> &[u8] {
+    let search_start = if url.starts_with(b"https://") {
+        8
+    } else if url.starts_with(b"http://") {
+        7
+    } else {
+        0
+    };
+
+    let search_space = &url[search_start..];
+
+    let path_start = match memchr::memchr(b'/', search_space) {
+        Some(i) => search_start + i,
+        None => return b"/",
+    };
+
+    let after_path = &url[path_start..];
+    let end = memchr::memchr2(b'?', b'#', after_path).unwrap_or(after_path.len());
+
+    &url[path_start..path_start + end]
+}
+
+/// Extract the query string from a URL (without the leading '?').
+#[inline]
+pub fn extract_query(url: &[u8]) -> &[u8] {
+    let search_start = if url.starts_with(b"https://") {
+        8
+    } else if url.starts_with(b"http://") {
+        7
+    } else {
+        0
+    };
+
+    let search_space = &url[search_start..];
+
+    if let Some(i) = memchr::memchr2(b'?', b'#', search_space) {
+        if search_space[i] == b'?' {
+            let after_q = &search_space[i + 1..];
+            let frag = memchr::memchr(b'#', after_q).unwrap_or(after_q.len());
+            &after_q[..frag]
+        } else {
+            &[]
+        }
+    } else {
+        &[]
+    }
+}

package/rust/query_parser.rs

@@ -0,0 +1,141 @@
+// rust/query_parser.rs — Unified zero-alloc query string parser
+// Single _into_slice code path with _vec wrapper for callers needing Vec.
+// Returns Cow<[u8]> when no decoding is needed (zero allocation).
+
+use crate::util::{ensure_capacity, hex_val, write_bytes, write_u32_le};
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+use std::borrow::Cow;
+
+/// Write a single URL-decoded form component into the output slice.
+#[inline]
+fn write_decoded_form_component(src: &[u8], out: &mut [u8], pos: &mut usize) -> Result<()> {
+    let len_pos = *pos;
+    write_u32_le(out, pos, 0)?;
+    let start = *pos;
+
+    if memchr::memchr2(b'+', b'%', src).is_none() {
+        write_bytes(out, pos, src)?;
+    } else {
+        let mut i = 0usize;
+        while i < src.len() {
+            match src[i] {
+                b'+' => {
+                    ensure_capacity(out, *pos, 1)?;
+                    out[*pos] = b' ';
+                    *pos += 1;
+                    i += 1;
+                }
+                b'%' => {
+                    if i + 2 >= src.len() {
+                        return Err(Error::from_reason("invalid %-encoding: missing bytes"));
+                    }
+                    let hi = hex_val(src[i + 1])
+                        .ok_or_else(|| Error::from_reason("invalid %-encoding: bad hi nibble"))?;
+                    let lo = hex_val(src[i + 2])
+                        .ok_or_else(|| Error::from_reason("invalid %-encoding: bad lo nibble"))?;
+                    ensure_capacity(out, *pos, 1)?;
+                    out[*pos] = (hi << 4) | lo;
+                    *pos += 1;
+                    i += 3;
+                }
+                b => {
+                    ensure_capacity(out, *pos, 1)?;
+                    out[*pos] = b;
+                    *pos += 1;
+                    i += 1;
+                }
+            }
+        }
+    }
+
+    let decoded_len = (*pos - start) as u32;
+    out[len_pos..len_pos + 4].copy_from_slice(&decoded_len.to_le_bytes());
+    Ok(())
+}
+
+/// Parse application/x-www-form-urlencoded into packed pairs.
+/// Output: [u32 count] repeated { [u32 dec_name_len] [decoded_name] [u32 dec_val_len] [decoded_val] }
+#[inline]
+pub fn query_parse_packed_into_slice(input: &[u8], out: &mut [u8]) -> Result<usize> {
+    let mut pos = 0usize;
+    write_u32_le(out, &mut pos, 0)?;
+    let mut count = 0u32;
+
+    for pair in input.split(|&b| b == b'&') {
+        if pair.is_empty() { continue; }
+        let (key, value) = match pair.iter().position(|&b| b == b'=') {
+            Some(eq) => (&pair[..eq], &pair[eq + 1..]),
+            None => (pair, &[][..]),
+        };
+        write_decoded_form_component(key, out, &mut pos)?;
+        write_decoded_form_component(value, out, &mut pos)?;
+        count += 1;
+    }
+
+    out[0..4].copy_from_slice(&count.to_le_bytes());
+    Ok(pos)
+}
+
+/// Allocating parser — conservative upper bound, no pre-scan.
+/// Returns `Cow::Owned(Vec<u8>)` when decoding is needed,
+/// `Cow::Borrowed(&[u8])` when input can be used as-is (no % or +).
+#[inline]
+pub fn query_parse_packed_cow(input: &[u8]) -> Result<Cow<'_, [u8]>> {
+    // Fast path: if no decoding is needed at all (no % or + anywhere),
+    // we can return the original input borrowed as a single-item packed result.
+    if memchr::memchr2(b'+', b'%', input).is_none() && memchr::memchr(b'&', input).is_none() {
+        // No special chars: encode as packed [1 item: input]
+        // Actually, query string might still have structure. Let's check if it's a single key=value
+        if input.is_empty() {
+            return Ok(Cow::Borrowed(b"\0\0\0\0")); // empty packed
+        }
+        // We still need to produce packed format, so we allocate a minimal buffer
+        let mut out = Vec::with_capacity(input.len() + 12);
+        out.extend_from_slice(&1u32.to_le_bytes()); // count = 1
+        // key
+        if let Some(eq) = input.iter().position(|&b| b == b'=') {
+            let key = &input[..eq];
+            out.extend_from_slice(&(key.len() as u32).to_le_bytes());
+            out.extend_from_slice(key);
+            let val = &input[eq + 1..];
+            out.extend_from_slice(&(val.len() as u32).to_le_bytes());
+            out.extend_from_slice(val);
+        } else {
+            out.extend_from_slice(&(input.len() as u32).to_le_bytes());
+            out.extend_from_slice(input);
+            out.extend_from_slice(&0u32.to_le_bytes()); // empty value
+        }
+        return Ok(Cow::Owned(out));
+    }
+
+    // Needs decoding — use the standard path with upper-bound allocation
+    query_parse_packed_vec(input).map(Cow::Owned)
+}
+
+/// Allocating parser — conservative upper bound, no pre-scan.
+#[inline]
+pub fn query_parse_packed_vec(input: &[u8]) -> Result<Vec<u8>> {
+    // Packed output is larger than input: each component gets 4-byte length prefix.
+    // Upper bound: 4 (count) + input.len() * 2 * 5 ≈ 10x for worst-case (many small pairs).
+    // Conservative: 9x + 16 (same as before).
+    let upper_bound = input.len().saturating_mul(9).saturating_add(16);
+    let mut out = vec![0u8; upper_bound];
+    match query_parse_packed_into_slice(input, &mut out) {
+        Ok(written) => {
+            out.truncate(written);
+            Ok(out)
+        }
+        Err(e) => Err(e),
+    }
+}
+
+#[napi]
+pub fn query_parse_packed(input: Uint8Array) -> Result<Buffer> {
+    Ok(Buffer::from(query_parse_packed_vec(input.as_ref())?))
+}
+
+#[napi]
+pub fn query_parse_packed_into(input: Uint8Array, mut output: Uint8Array) -> Result<u32> {
+    crate::util::run_packed_into(&input, &mut output, query_parse_packed_into_slice)
+}

package/rust/random_token.rs

@@ -0,0 +1,52 @@
+// rust/random_token.rs — v2: prefer stack buffer for common sizes
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+const HEX_LOWER: &[u8; 16] = b"0123456789abcdef";
+
+#[inline(always)]
+fn hex_encode(bytes: &[u8], out: &mut [u8]) {
+    for (i, &b) in bytes.iter().enumerate() {
+        out[2 * i] = HEX_LOWER[(b >> 4) as usize];
+        out[2 * i + 1] = HEX_LOWER[(b & 0x0f) as usize];
+    }
+}
+
+#[napi]
+pub fn random_token(byte_len: u32) -> Result<Buffer> {
+    let len = byte_len as usize;
+
+    // ⭐ Common sizes (16, 32, 64) use stack buffers — no heap alloc.
+    match len {
+        16 => {
+            let mut bytes = [0u8; 16];
+            getrandom::fill(&mut bytes).map_err(|e| Error::from_reason(e.to_string()))?;
+            let mut out = [0u8; 32];
+            hex_encode(&bytes, &mut out);
+            Ok(Buffer::from(out.to_vec()))
+        }
+        32 => {
+            let mut bytes = [0u8; 32];
+            getrandom::fill(&mut bytes).map_err(|e| Error::from_reason(e.to_string()))?;
+            let mut out = [0u8; 64];
+            hex_encode(&bytes, &mut out);
+            Ok(Buffer::from(out.to_vec()))
+        }
+        64 => {
+            let mut bytes = [0u8; 64];
+            getrandom::fill(&mut bytes).map_err(|e| Error::from_reason(e.to_string()))?;
+            let mut out = [0u8; 128];
+            hex_encode(&bytes, &mut out);
+            Ok(Buffer::from(out.to_vec()))
+        }
+        _ => {
+            let out_len = len.checked_mul(2)
+                .ok_or_else(|| Error::from_reason("byte_len too large"))?;
+            let mut bytes = vec![0u8; len];
+            getrandom::fill(&mut bytes).map_err(|e| Error::from_reason(e.to_string()))?;
+            let mut out = vec![0u8; out_len];
+            hex_encode(&bytes, &mut out);
+            Ok(Buffer::from(out))
+        }
+    }
+}