castrum 0.9.2 → 0.9.4

package/rust/http/query_parser.rs

@@ -0,0 +1,180 @@
+// rust/http/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::write_u32_le;
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+/// 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)?;
+    // The decoded length never exceeds `src.len()`; the shared decoder checks
+    // the remaining buffer against the ACTUAL decoded length (so a `%XX`-heavy
+    // component only needs room for its decoded form, matching the pre-refactor
+    // behavior where a buffer sized to the decoded length succeeds).
+    let written = crate::util::bytes::decode_form_component_into(src, &mut out[*pos..]).map_err(
+        |e| match e {
+            crate::util::bytes::FormDecodeError::Malformed => {
+                Error::from_reason("invalid %-encoding: malformed %XX sequence")
+            }
+            crate::util::bytes::FormDecodeError::BufferTooSmall => {
+                Error::from_reason("packed output: buffer too small")
+            }
+        },
+    )?;
+    *pos += written;
+    let decoded_len = written 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)
+}
+
+/// Compute the EXACT packed output size for `input` WITHOUT writing — the
+/// "needed-size" pass for the C-ABI convention. Mirrors
+/// [`query_parse_packed_into_slice`]'s structure exactly (split on `&`, skip
+/// empty pairs, split at `=`), so the reported size is byte-exact and a
+/// malformed `%XX` still surfaces as `Err` (caller → `0`).
+#[inline]
+pub fn query_parse_packed_size(input: &[u8]) -> Result<usize> {
+    let mut size = 4usize; // count prefix
+    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, &[][..]),
+        };
+        size += 4 + crate::util::bytes::decode_form_component_len(key)
+            .map_err(|_| Error::from_reason("invalid %-encoding: malformed %XX sequence"))?;
+        size += 4 + crate::util::bytes::decode_form_component_len(value)
+            .map_err(|_| Error::from_reason("invalid %-encoding: malformed %XX sequence"))?;
+    }
+    Ok(size)
+}
+
+/// 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)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::query_parse_packed_vec;
+    use crate::test_support::decode_packed_pairs;
+
+    #[test]
+    fn query_parse_basic_pairs() {
+        let packed = query_parse_packed_vec(b"a=1&b=2").unwrap();
+        let pairs = decode_packed_pairs(&packed);
+        assert_eq!(pairs.len(), 2);
+        assert_eq!(pairs[0], (b"a".to_vec(), b"1".to_vec()));
+        assert_eq!(pairs[1], (b"b".to_vec(), b"2".to_vec()));
+    }
+
+    #[test]
+    fn query_parse_percent_and_plus_decoding() {
+        let packed = query_parse_packed_vec(b"name=John%20Doe&q=a+b").unwrap();
+        let pairs = decode_packed_pairs(&packed);
+        assert_eq!(pairs.len(), 2);
+        assert_eq!(pairs[0], (b"name".to_vec(), b"John Doe".to_vec()));
+        assert_eq!(pairs[1], (b"q".to_vec(), b"a b".to_vec()));
+    }
+
+    #[test]
+    fn query_parse_empty_value() {
+        let packed = query_parse_packed_vec(b"flag").unwrap();
+        let pairs = decode_packed_pairs(&packed);
+        assert_eq!(pairs.len(), 1);
+        assert_eq!(pairs[0], (b"flag".to_vec(), b"".to_vec()));
+    }
+
+    #[test]
+    fn query_parse_invalid_percent_rejected() {
+        assert!(query_parse_packed_vec(b"a=%ZZ").is_err());
+    }
+
+    #[test]
+    fn query_parse_empty_input() {
+        let packed = query_parse_packed_vec(b"").unwrap();
+        let pairs = decode_packed_pairs(&packed);
+        assert!(pairs.is_empty());
+    }
+
+    #[test]
+    fn query_parse_null_byte_preserved() {
+        // `%00` decodes to a NUL byte inside the value (byte-oriented parser).
+        let packed = query_parse_packed_vec(b"a=%00b").unwrap();
+        let pairs = decode_packed_pairs(&packed);
+        assert_eq!(pairs.len(), 1);
+        assert_eq!(pairs[0], (b"a".to_vec(), b"\x00b".to_vec()));
+    }
+
+    #[test]
+    fn query_parse_semicolon_is_data() {
+        // In a query string `&` separates pairs; `;` is ordinary data.
+        let packed = query_parse_packed_vec(b"a=1;b=2").unwrap();
+        let pairs = decode_packed_pairs(&packed);
+        assert_eq!(pairs.len(), 1);
+        assert_eq!(pairs[0], (b"a".to_vec(), b"1;b=2".to_vec()));
+    }
+
+    #[test]
+    fn query_parse_non_utf8_byte_passthrough() {
+        // `%FF` decodes to a raw 0xFF byte; the parser does not require valid
+        // UTF-8 in query values (callers must handle it when they do).
+        let packed = query_parse_packed_vec(b"a=%FF").unwrap();
+        let pairs = decode_packed_pairs(&packed);
+        assert_eq!(pairs.len(), 1);
+        assert_eq!(pairs[0], (b"a".to_vec(), vec![0xFF]));
+    }
+}

package/rust/http/url_codec.rs

@@ -0,0 +1,296 @@
+// rust/http/url_codec.rs — URL percent-encoding
+use crate::util::bytes::{decode_percent_at, HEX_UPPER};
+use crate::util::{ensure_capacity, write_bytes};
+use memchr::memchr;
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+const fn is_unreserved_char(b: u8) -> bool {
+    matches!(b,
+        b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9'
+        | b'-' | b'_' | b'.' | b'!' | b'~' | b'*' | 0x27 | b'(' | b')'
+    )
+}
+
+/// 256-entry lookup for RFC 3986 unreserved characters — one table load per
+/// byte instead of a chain of range compares on the hot encoding loop.
+static UNRESERVED_LUT: [bool; 256] = {
+    let mut t = [false; 256];
+    let mut i = 0usize;
+    while i < 256 {
+        t[i] = is_unreserved_char(i as u8);
+        i += 1;
+    }
+    t
+};
+
+#[inline(always)]
+fn is_unreserved(b: u8) -> bool {
+    UNRESERVED_LUT[b as usize]
+}
+
+/// Percent-encode a raw byte slice (RFC 3986 unreserved set). Shared by the
+/// scalar napi path and the packed batch path.
+fn url_encode_bytes(input: &[u8]) -> Vec<u8> {
+    // Exact-size allocation: count bytes needing %XX in one pass, then size the
+    // Vec precisely so the write loop never reallocates. Saturating math keeps
+    // this overflow-safe under `overflow-checks = true`.
+    let reserved = input.iter().filter(|&&b| !is_unreserved(b)).count();
+    let mut out = Vec::with_capacity(input.len().saturating_add(reserved.saturating_mul(2)));
+    let mut start = 0usize;
+
+    for (i, &b) in input.iter().enumerate() {
+        if !is_unreserved(b) {
+            out.extend_from_slice(&input[start..i]);
+            // ⭐ Batch the 3-byte %XX write — one extend instead of 3 pushes.
+            let mut encoded = [b'%', 0, 0];
+            encoded[1] = HEX_UPPER[(b >> 4) as usize];
+            encoded[2] = HEX_UPPER[(b & 0x0f) as usize];
+            out.extend_from_slice(&encoded);
+            start = i + 1;
+        }
+    }
+
+    out.extend_from_slice(&input[start..]);
+    out
+}
+
+#[napi]
+pub fn url_encode(input: Uint8Array) -> Buffer {
+    Buffer::from(url_encode_bytes(input.as_ref()))
+}
+
+/// Percent-encode a JS string directly → encoded string. Skips the Uint8Array
+/// round-trip of `url_encode` for string callers. Percent-encoded output is
+/// always ASCII, so no UTF-8 validation is needed.
+#[napi]
+pub fn url_encode_str(input: String) -> String {
+    let bytes = url_encode_bytes(input.as_bytes());
+    // SAFETY: percent-encoded output is ASCII (unreserved chars + %XX hex), so
+    // the bytes are valid UTF-8 by construction.
+    unsafe { String::from_utf8_unchecked(bytes) }
+}
+
+/// Percent-decode a JS string → decoded string. Equivalent to `url_decode` on
+/// the string's UTF-8 bytes; invalid UTF-8 output throws.
+#[napi]
+pub fn url_decode_str(input: String) -> Result<String> {
+    let (out, saw_high) = url_decode_bytes_vec(input.as_bytes())?;
+    if saw_high {
+        simdutf8::basic::from_utf8(&out).map_err(|e| Error::from_reason(e.to_string()))?;
+    }
+    // SAFETY: either the output is pure ASCII (no high bit observed) or it was
+    // validated by simdutf8 above.
+    Ok(unsafe { String::from_utf8_unchecked(out) })
+}
+
+/// Packed percent-encode batch: `[u32 count]{[u32 len][data]}` in →
+/// `[u32 count]{[u32 len][encoded]}` out.
+#[napi]
+pub fn url_encode_batch_packed(input: Uint8Array) -> Result<Buffer> {
+    crate::util::run_packed_batch(input.as_ref(), url_encode_bytes).map(Buffer::from)
+}
+
+#[napi]
+pub fn url_decode(input: Uint8Array) -> Result<Buffer> {
+    let (out, saw_high) = url_decode_bytes_vec(input.as_ref())?;
+    // The single decode pass already told us whether any output byte is
+    // >= 0x80. ASCII output is trivially valid UTF-8, so the full simdutf8
+    // validation pass is only needed when a high bit was observed.
+    if saw_high {
+        simdutf8::basic::from_utf8(&out).map_err(|e| Error::from_reason(e.to_string()))?;
+    }
+    Ok(Buffer::from(out))
+}
+
+/// Packed percent-decode batch (UTF-8 validated). Items that fail decoding
+/// (malformed %XX or invalid UTF-8) yield an empty result — skip-on-error,
+/// matching the other decode batches.
+#[napi]
+pub fn url_decode_batch_packed(input: Uint8Array) -> Result<Buffer> {
+    crate::util::run_packed_batch(input.as_ref(), |v| match url_decode_bytes_vec(v) {
+        Ok((out, saw_high)) => {
+            if saw_high && simdutf8::basic::from_utf8(&out).is_err() {
+                Vec::new()
+            } else {
+                out
+            }
+        }
+        Err(_) => Vec::new(),
+    })
+    .map(Buffer::from)
+}
+
+/// Packed strict percent-decode batch (no UTF-8 validation).
+#[napi]
+pub fn url_decode_bytes_batch_packed(input: Uint8Array) -> Result<Buffer> {
+    crate::util::run_packed_batch(input.as_ref(), |v| {
+        url_decode_bytes_vec(v)
+            .map(|(out, _)| out)
+            .unwrap_or_default()
+    })
+    .map(Buffer::from)
+}
+
+pub fn url_encode_into_slice(input: &[u8], out: &mut [u8]) -> Result<usize> {
+    let mut pos = 0usize;
+    let mut start = 0usize;
+
+    for (i, &b) in input.iter().enumerate() {
+        if !is_unreserved(b) {
+            write_bytes(out, &mut pos, &input[start..i])?;
+            ensure_capacity(out, pos, 3)?;
+            out[pos] = b'%';
+            out[pos + 1] = HEX_UPPER[(b >> 4) as usize];
+            out[pos + 2] = HEX_UPPER[(b & 0x0f) as usize];
+            pos += 3;
+            start = i + 1;
+        }
+    }
+
+    write_bytes(out, &mut pos, &input[start..])?;
+    Ok(pos)
+}
+
+#[napi]
+pub fn url_encode_into(input: Uint8Array, mut output: Uint8Array) -> Result<u32> {
+    crate::util::run_packed_into(&input, &mut output, url_encode_into_slice)
+}
+
+#[inline]
+fn url_decode_bytes_vec(input: &[u8]) -> Result<(Vec<u8>, bool)> {
+    let mut out = Vec::with_capacity(input.len());
+    let mut pos = 0usize;
+    let mut saw_high = false;
+
+    while let Some(rel) = memchr(b'%', &input[pos..]) {
+        let i = pos + rel;
+        let run = &input[pos..i];
+        // Copied runs are passed through verbatim; check them for high bytes.
+        if !run.is_ascii() {
+            saw_high = true;
+        }
+        out.extend_from_slice(run);
+
+        let (byte, next) = decode_percent_at(input, i)
+            .ok_or_else(|| Error::from_reason("invalid %-encoding: malformed %XX sequence"))?;
+        // `%XX` can decode to a non-ASCII byte (e.g. `%C3%A9`); track it.
+        if byte >= 0x80 {
+            saw_high = true;
+        }
+        out.push(byte);
+        pos = next;
+    }
+
+    let tail = &input[pos..];
+    if !tail.is_ascii() {
+        saw_high = true;
+    }
+    out.extend_from_slice(tail);
+    Ok((out, saw_high))
+}
+
+#[napi]
+pub fn url_decode_bytes(input: Uint8Array) -> Result<Buffer> {
+    let (out, _saw_high) = url_decode_bytes_vec(input.as_ref())?;
+    Ok(Buffer::from(out))
+}
+
+pub fn url_decode_into_slice(input: &[u8], out: &mut [u8]) -> Result<usize> {
+    let mut pos = 0usize;
+    let mut src_pos = 0usize;
+
+    while let Some(rel) = memchr(b'%', &input[src_pos..]) {
+        let i = src_pos + rel;
+        write_bytes(out, &mut pos, &input[src_pos..i])?;
+
+        let (byte, next) = decode_percent_at(input, i)
+            .ok_or_else(|| Error::from_reason("invalid %-encoding: malformed %XX sequence"))?;
+
+        ensure_capacity(out, pos, 1)?;
+        out[pos] = byte;
+        pos += 1;
+        src_pos = next;
+    }
+
+    write_bytes(out, &mut pos, &input[src_pos..])?;
+    Ok(pos)
+}
+
+#[napi]
+pub fn url_decode_into(input: Uint8Array, mut output: Uint8Array) -> Result<u32> {
+    crate::util::run_packed_into(&input, &mut output, url_decode_into_slice)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn url_encode_reserved_and_unreserved() {
+        let mut out = vec![0u8; 64];
+        let n = url_encode_into_slice(b"/a b?c=d", &mut out).unwrap();
+        // '/', space, '?', '=' are all percent-encoded; alphanumerics are not.
+        assert_eq!(&out[..n], b"%2Fa%20b%3Fc%3Dd");
+    }
+
+    #[test]
+    fn url_decode_roundtrip() {
+        let mut out = vec![0u8; 64];
+        let n = url_decode_into_slice(b"%2Fa%20b%3Fc%3Dd", &mut out).unwrap();
+        assert_eq!(&out[..n], b"/a b?c=d");
+    }
+
+    #[test]
+    fn url_decode_rejects_malformed_percent() {
+        let mut out = vec![0u8; 64];
+        assert!(url_decode_into_slice(b"%ZZ", &mut out).is_err());
+        assert!(url_decode_into_slice(b"%2", &mut out).is_err());
+    }
+
+    #[test]
+    fn url_encode_allocating_matches_into_slice() {
+        for input in [
+            b"hello world & foo=bar".as_slice(),
+            b"%2Fa%20b%3Fc%3Dd",
+            b"a%20b%20c%20d",
+            b"".as_slice(),
+            b"!~*'()",
+            b"\xff\x00\x80",
+        ] {
+            let allocating = url_encode_bytes(input);
+            let mut out = vec![0u8; input.len() * 3 + 1];
+            let n = url_encode_into_slice(input, &mut out).unwrap();
+            assert_eq!(allocating, &out[..n], "input: {:?}", input);
+        }
+    }
+    #[test]
+    fn url_encode_str_matches_bytes_path() {
+        for s in [
+            "hello world & foo=bar",
+            "!~*'()",
+            "",
+            "h%C3%A9llo",
+            "a/b?c=d#e",
+        ] {
+            let encoded = url_encode_str(s.to_string());
+            assert_eq!(
+                encoded.as_bytes(),
+                url_encode_bytes(s.as_bytes()),
+                "input: {s}"
+            );
+        }
+    }
+
+    #[test]
+    fn url_encode_str_roundtrips() {
+        let s = "hello world & foo=bar";
+        assert_eq!(url_decode_str(url_encode_str(s.to_string())).unwrap(), s);
+    }
+
+    #[test]
+    fn url_decode_str_rejects_invalid_utf8() {
+        // Decoded %FF is a lone high byte — not valid UTF-8.
+        assert!(url_decode_str("%FF".to_string()).is_err());
+    }
+}