castrum 0.9.2 → 0.9.4

package/rust/http/http_parser.rs

@@ -0,0 +1,252 @@
+// rust/http/http_parser.rs
+use crate::util::{write_bytes, write_u32_le};
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+pub fn http_parse_request_packed_into_slice(input: &[u8], out: &mut [u8]) -> Result<usize> {
+    let mut headers = [httparse::EMPTY_HEADER; 64];
+    let mut req = httparse::Request::new(&mut headers);
+
+    match req.parse(input) {
+        Ok(httparse::Status::Complete(_)) => {}
+        Ok(_) => return Err(Error::new(Status::InvalidArg, "incomplete HTTP request")),
+        Err(e) => return Err(Error::new(Status::InvalidArg, e.to_string())),
+    }
+
+    let method = req
+        .method
+        .ok_or_else(|| Error::new(Status::InvalidArg, "missing HTTP method"))?
+        .as_bytes();
+
+    let path = req
+        .path
+        .ok_or_else(|| Error::new(Status::InvalidArg, "missing HTTP path"))?
+        .as_bytes();
+
+    let version: &[u8] = match req.version {
+        Some(0) => b"HTTP/1.0",
+        Some(1) => b"HTTP/1.1",
+        _ => b"HTTP/1.1",
+    };
+
+    let mut pos = 0usize;
+
+    write_u32_le(out, &mut pos, method.len() as u32)?;
+    write_bytes(out, &mut pos, method)?;
+
+    write_u32_le(out, &mut pos, path.len() as u32)?;
+    write_bytes(out, &mut pos, path)?;
+
+    write_u32_le(out, &mut pos, version.len() as u32)?;
+    write_bytes(out, &mut pos, version)?;
+
+    write_u32_le(out, &mut pos, req.headers.len() as u32)?;
+
+    for header in req.headers.iter() {
+        let name = header.name.as_bytes();
+        let value = header.value;
+
+        write_u32_le(out, &mut pos, name.len() as u32)?;
+        crate::util::write_bytes_lowercase(out, &mut pos, name)?;
+
+        write_u32_le(out, &mut pos, value.len() as u32)?;
+        crate::util::write_bytes(out, &mut pos, value)?;
+    }
+
+    Ok(pos)
+}
+
+/// Allocating, zero-copy-input, non-zeroing-output parser.
+///
+/// Delegates to [`http_parse_request_packed_into_slice`] so the httparse→
+/// packed-write logic lives in exactly one place (`_vec` and `_into_slice` can
+/// never drift — see the `into_slice_and_vec_agree` parity test).
+pub fn http_parse_request_packed_vec(input: &[u8]) -> Result<Vec<u8>> {
+    // Metadata overhead bound: 16 bytes of section headers + 8 bytes per
+    // header length prefix (max 64 headers) = 16 + 64 * 8 = 528.
+    let mut out = vec![0u8; input.len().saturating_add(528)];
+    let written = http_parse_request_packed_into_slice(input, &mut out)?;
+    out.truncate(written);
+    Ok(out)
+}
+
+#[napi]
+pub fn http_parse_request_packed(input: Uint8Array) -> Result<Buffer> {
+    Ok(Buffer::from(http_parse_request_packed_vec(input.as_ref())?))
+}
+
+#[napi]
+pub fn http_parse_request_packed_into(input: Uint8Array, mut output: Uint8Array) -> Result<u32> {
+    crate::util::run_packed_into(&input, &mut output, http_parse_request_packed_into_slice)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Decode the packed request layout produced by
+    /// [`http_parse_request_packed_into_slice`]:
+    /// `[u32 method_len][method][u32 path_len][path][u32 version_len][version]
+    /// [u32 header_count]{ [u32 name_len][name][u32 value_len][value] }`.
+    #[allow(clippy::type_complexity)]
+    fn decode_packed(packed: &[u8]) -> (Vec<u8>, Vec<u8>, Vec<u8>, Vec<(Vec<u8>, Vec<u8>)>) {
+        let mut pos = 0usize;
+        fn take_len(p: &[u8], pos: &mut usize) -> usize {
+            let n = u32::from_le_bytes([p[*pos], p[*pos + 1], p[*pos + 2], p[*pos + 3]]) as usize;
+            *pos += 4;
+            n
+        }
+        fn take<'a>(p: &'a [u8], pos: &mut usize, n: usize) -> &'a [u8] {
+            let s = &p[*pos..*pos + n];
+            *pos += n;
+            s
+        }
+        let method = {
+            let n = take_len(packed, &mut pos);
+            take(packed, &mut pos, n).to_vec()
+        };
+        let path = {
+            let n = take_len(packed, &mut pos);
+            take(packed, &mut pos, n).to_vec()
+        };
+        let version = {
+            let n = take_len(packed, &mut pos);
+            take(packed, &mut pos, n).to_vec()
+        };
+        let count = take_len(packed, &mut pos);
+        let mut headers = Vec::with_capacity(count);
+        for _ in 0..count {
+            let name = {
+                let n = take_len(packed, &mut pos);
+                take(packed, &mut pos, n).to_vec()
+            };
+            let value = {
+                let n = take_len(packed, &mut pos);
+                take(packed, &mut pos, n).to_vec()
+            };
+            headers.push((name, value));
+        }
+        (method, path, version, headers)
+    }
+
+    #[allow(clippy::type_complexity)]
+    fn parse_once(
+        input: &[u8],
+    ) -> std::result::Result<(Vec<u8>, Vec<u8>, Vec<u8>, Vec<(Vec<u8>, Vec<u8>)>), napi::Error>
+    {
+        let mut out = vec![0u8; 4096];
+        let written = http_parse_request_packed_into_slice(input, &mut out)?;
+        Ok(decode_packed(&out[..written]))
+    }
+
+    #[test]
+    fn basic_get_parse_and_lowercase() {
+        let (method, path, version, headers) = parse_once(
+            b"GET /api/users?page=2 HTTP/1.1\r\nHost: Example.COM\r\nX-Custom-Header: v\r\n\r\n",
+        )
+        .unwrap();
+        assert_eq!(method, b"GET");
+        assert_eq!(path, b"/api/users?page=2");
+        assert_eq!(version, b"HTTP/1.1");
+        assert_eq!(
+            headers,
+            vec![
+                (b"host".to_vec(), b"Example.COM".to_vec()),
+                (b"x-custom-header".to_vec(), b"v".to_vec()),
+            ]
+        );
+    }
+
+    #[test]
+    fn http10_maps_version() {
+        let (_, _, version, _) = parse_once(b"GET / HTTP/1.0\r\n\r\n").unwrap();
+        assert_eq!(version, b"HTTP/1.0");
+    }
+
+    #[test]
+    fn incomplete_request_is_error() {
+        // No terminating blank line → httparse returns Partial → error.
+        assert!(parse_once(b"GET / HTTP/1.1\r\nHost: a").is_err());
+        assert!(parse_once(b"").is_err());
+    }
+
+    #[test]
+    fn too_many_headers_is_error() {
+        // The parser's header array is sized 64; httparse refuses more.
+        let mut req = String::from("GET / HTTP/1.1\r\n");
+        for i in 0..80 {
+            req.push_str(&format!("h{i}: v\r\n"));
+        }
+        req.push_str("\r\n");
+        assert!(parse_once(req.as_bytes()).is_err());
+    }
+
+    #[test]
+    fn header_value_whitespace_preserved() {
+        let (_, _, _, headers) = parse_once(
+            b"GET / HTTP/1.1\r\nAccept: text/html, application/json\r\nX-B: a   b\r\n\r\n",
+        )
+        .unwrap();
+        assert_eq!(
+            headers[0],
+            (b"accept".to_vec(), b"text/html, application/json".to_vec())
+        );
+        assert_eq!(headers[1], (b"x-b".to_vec(), b"a   b".to_vec()));
+    }
+
+    #[test]
+    fn absolute_form_target_preserved() {
+        let (_, path, _, _) =
+            parse_once(b"GET http://example.com/path?q=1 HTTP/1.1\r\nHost: example.com\r\n\r\n")
+                .unwrap();
+        assert_eq!(path, b"http://example.com/path?q=1");
+    }
+
+    #[test]
+    fn missing_method_is_error() {
+        assert!(parse_once(b"HTTP/1.1\r\n\r\n").is_err());
+    }
+
+    #[test]
+    fn null_byte_in_header_rejected() {
+        assert!(parse_once(b"GET / HTTP/1.1\r\nX: a\x00b\r\n\r\n").is_err());
+    }
+
+    #[test]
+    fn duplicate_headers_all_preserved() {
+        let (_, _, _, headers) = parse_once(
+            b"GET / HTTP/1.1\r\nHost: a\r\nHost: b\r\nSet-Cookie: x=1\r\nSet-Cookie: y=2\r\n\r\n",
+        )
+        .unwrap();
+        assert_eq!(headers[0], (b"host".to_vec(), b"a".to_vec()));
+        assert_eq!(headers[1], (b"host".to_vec(), b"b".to_vec()));
+        assert_eq!(headers[2], (b"set-cookie".to_vec(), b"x=1".to_vec()));
+        assert_eq!(headers[3], (b"set-cookie".to_vec(), b"y=2".to_vec()));
+    }
+
+    #[test]
+    fn content_length_and_transfer_encoding_pass_through() {
+        // The parser is format-only: it must not interpret or drop either
+        // header (semantic conflict resolution is a later pipeline concern).
+        let (_, _, _, headers) = parse_once(
+            b"POST / HTTP/1.1\r\nContent-Length: 5\r\nTransfer-Encoding: chunked\r\n\r\n",
+        )
+        .unwrap();
+        assert_eq!(headers[0], (b"content-length".to_vec(), b"5".to_vec()));
+        assert_eq!(
+            headers[1],
+            (b"transfer-encoding".to_vec(), b"chunked".to_vec())
+        );
+    }
+
+    #[test]
+    fn into_slice_and_vec_agree() {
+        // Parity guard: the allocating and slice writers must emit identical
+        // bytes (keeps the dedup refactor of `_vec` → `_into_slice` honest).
+        let input = b"GET /a?b=c HTTP/1.1\r\nHost: x\r\nX-Mixed: V\r\n\r\n";
+        let mut out = vec![0u8; 4096];
+        let written = http_parse_request_packed_into_slice(input, &mut out).unwrap();
+        let vec_out = http_parse_request_packed_vec(input).unwrap();
+        assert_eq!(&out[..written], vec_out.as_slice());
+    }
+}

package/rust/http/media_type.rs

@@ -0,0 +1,355 @@
+// rust/http/media_type.rs — Content-Type / media type parser.
+//
+// Parses `type/subtype; param=value; ...` per RFC 7231 §3.1.1.1: lowercased
+// type/subtype, token + quoted-string params (charset, boundary). Pure-Rust
+// core (`parse_media_type_core`) stays napi-free for testability; only the
+// entry points use napi types.
+
+use std::collections::HashMap;
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+use crate::util::bytes::trim_ascii_whitespace;
+
+/// RFC 7230 `tchar` (tokens used in media-type names/params).
+#[inline]
+fn is_token_char(b: u8) -> bool {
+    matches!(
+        b,
+        b'a'..=b'z'
+            | b'A'..=b'Z'
+            | b'0'..=b'9'
+            | b'!'
+            | b'#'
+            | b'$'
+            | b'%'
+            | b'&'
+            | b'\''
+            | b'*'
+            | b'+'
+            | b'-'
+            | b'.'
+            | b'^'
+            | b'_'
+            | b'`'
+            | b'|'
+            | b'~'
+    )
+}
+
+/// A parsed media type (pure-Rust core type).
+pub struct ParsedMediaType {
+    pub ty: String,
+    pub subtype: String,
+    pub params: Vec<(String, String)>,
+}
+
+/// Decode a quoted-string param value (`"..."`, backslash escapes).
+fn parse_quoted(raw: &[u8]) -> std::result::Result<String, &'static str> {
+    let mut out = Vec::with_capacity(raw.len());
+    let mut i = 1;
+    while i < raw.len() {
+        match raw[i] {
+            b'"' => return String::from_utf8(out).map_err(|_| "invalid UTF-8 in quoted string"),
+            b'\\' if i + 1 < raw.len() => {
+                out.push(raw[i + 1]);
+                i += 2;
+            }
+            b => {
+                out.push(b);
+                i += 1;
+            }
+        }
+    }
+    Err("unterminated quoted string")
+}
+
+/// Parse `type/subtype; param=value` (params may be quoted or token values).
+pub fn parse_media_type_core(input: &[u8]) -> std::result::Result<ParsedMediaType, &'static str> {
+    let semi = input.iter().position(|&b| b == b';');
+    let (main, rest) = match semi {
+        Some(i) => (&input[..i], &input[i + 1..]),
+        None => (input, &[][..]),
+    };
+
+    let main = trim_ascii_whitespace(main);
+    let slash = main
+        .iter()
+        .position(|&b| b == b'/')
+        .ok_or("missing '/' in media type")?;
+    // Single-pass lowercase: `to_ascii_lowercase()` into a Vec, then
+    // `String::from_utf8` wraps it without a second copy (the old
+    // `from_utf8_lossy(...).into_owned()` copied twice). Input is
+    // token-validated below, so invalid UTF-8 is rejected either way.
+    let ty = String::from_utf8(main[..slash].to_ascii_lowercase())
+        .map_err(|_| "invalid UTF-8 in media type")?;
+    let subtype = String::from_utf8(main[slash + 1..].to_ascii_lowercase())
+        .map_err(|_| "invalid UTF-8 in media type")?;
+    if ty.is_empty() || subtype.is_empty() {
+        return Err("empty type or subtype");
+    }
+    if !ty.bytes().all(is_token_char) || !subtype.bytes().all(is_token_char) {
+        return Err("invalid type/subtype token");
+    }
+
+    let mut params = Vec::new();
+    for param in rest.split(|&b| b == b';') {
+        let param = trim_ascii_whitespace(param);
+        if param.is_empty() {
+            continue;
+        }
+        let eq = param
+            .iter()
+            .position(|&b| b == b'=')
+            .ok_or("media-type param missing '='")?;
+        let name = String::from_utf8_lossy(&param[..eq])
+            .trim()
+            .to_ascii_lowercase();
+        if name.is_empty() {
+            continue;
+        }
+        let raw_val = trim_ascii_whitespace(&param[eq + 1..]);
+        let value = if raw_val.first() == Some(&b'"') {
+            parse_quoted(raw_val)?
+        } else {
+            let v = trim_ascii_whitespace(raw_val);
+            if v.is_empty() {
+                return Err("empty media-type param value");
+            }
+            String::from_utf8_lossy(v).into_owned()
+        };
+        params.push((name, value));
+    }
+
+    Ok(ParsedMediaType {
+        ty,
+        subtype,
+        params,
+    })
+}
+
+/// napi-projected structured result (snake_case → camelCase in JS).
+#[napi(object)]
+pub struct MediaTypeResult {
+    /// Lowercased `type/subtype`.
+    pub media_type: String,
+    pub charset: Option<String>,
+    pub boundary: Option<String>,
+    pub params: HashMap<String, String>,
+}
+
+#[napi]
+pub fn parse_media_type(input: Uint8Array) -> Result<MediaTypeResult> {
+    let parsed =
+        parse_media_type_core(input.as_ref()).map_err(|e| Error::from_reason(e.to_string()))?;
+    let mut params = HashMap::with_capacity(parsed.params.len());
+    for (k, v) in parsed.params {
+        params.insert(k, v);
+    }
+    Ok(MediaTypeResult {
+        charset: params.get("charset").cloned(),
+        boundary: params.get("boundary").cloned(),
+        media_type: format!("{}/{}", parsed.ty, parsed.subtype),
+        params,
+    })
+}
+
+/// Zero-alloc media-type split: returns the `(type, subtype)` byte slices from
+/// `input`, replicating `parse_media_type_core`'s type/subtype acceptance
+/// rules (parameters stripped, whitespace-trimmed, non-empty, RFC 7230 token
+/// chars) WITHOUT building the lowercase `String`s or the params `Vec`. The
+/// caller compares case-insensitively against a precompiled lowercase expected
+/// side. Any non-token byte (including non-ASCII / invalid UTF-8) is rejected,
+/// exactly like the parser.
+#[inline]
+fn split_type_subtype(input: &[u8]) -> Option<(&[u8], &[u8])> {
+    let semi = memchr::memchr(b';', input);
+    let main = match semi {
+        Some(i) => &input[..i],
+        None => input,
+    };
+    let main = trim_ascii_whitespace(main);
+    let slash = memchr::memchr(b'/', main)?;
+    let ty = &main[..slash];
+    let subtype = &main[slash + 1..];
+    if ty.is_empty() || subtype.is_empty() {
+        return None;
+    }
+    if !ty.iter().all(|&b| is_token_char(b)) || !subtype.iter().all(|&b| is_token_char(b)) {
+        return None;
+    }
+    Some((ty, subtype))
+}
+
+/// Higher-order instance: provides a reusable `matches` (wildcard negotiation)
+/// helper and a consistent instance-based API for content-type handling.
+#[napi]
+pub struct MediaTypeParser;
+
+impl Default for MediaTypeParser {
+    fn default() -> Self {
+        Self
+    }
+}
+
+#[napi]
+impl MediaTypeParser {
+    #[napi(constructor)]
+    pub fn new() -> Self {
+        Self
+    }
+
+    #[napi]
+    pub fn parse(&self, input: Uint8Array) -> Result<MediaTypeResult> {
+        parse_media_type(input)
+    }
+}
+
+/// Higher-order instance: precompiles the EXPECTED media type once at
+/// construction (type/subtype lowercased), so every `matches` call only parses
+/// the ACTUAL header — the expected side never re-parses.
+#[napi]
+pub struct MediaTypeMatcher {
+    expected_ty: String,
+    expected_subtype: String,
+}
+
+#[napi]
+impl MediaTypeMatcher {
+    /// Precompile `expected` (`*/*`, `type/*`, or `type/subtype`).
+    #[napi(constructor)]
+    pub fn new(expected: Uint8Array) -> Result<Self> {
+        let parsed = parse_media_type_core(expected.as_ref())
+            .map_err(|e| Error::from_reason(e.to_string()))?;
+        Ok(Self {
+            expected_ty: parsed.ty,
+            expected_subtype: parsed.subtype,
+        })
+    }
+
+    /// Wildcard match against the precompiled expected type. Only `actual` is
+    /// inspected per call — `expected` was normalized once at construction, and
+    /// the actual side is split into byte slices (no String / params-Vec alloc).
+    #[napi]
+    pub fn matches(&self, actual: Uint8Array) -> bool {
+        let Some((ty, subtype)) = split_type_subtype(actual.as_ref()) else {
+            return false;
+        };
+        let ty_ok = self.expected_ty == "*"
+            || crate::util::bytes::ascii_eq_ignore_case(ty, self.expected_ty.as_bytes());
+        let st_ok = self.expected_subtype == "*"
+            || crate::util::bytes::ascii_eq_ignore_case(subtype, self.expected_subtype.as_bytes());
+        ty_ok && st_ok
+    }
+
+    /// Opaque handle to the precompiled expected type, for the `bun:ffi` C-ABI
+    /// fast path (`castrum_media_type_matcher_matches` in rust/ffi.rs). Only
+    /// valid while THIS instance is alive; the JS wrapper holds the instance.
+    #[napi]
+    pub fn inner_ptr(&self) -> u64 {
+        self as *const MediaTypeMatcher as u64
+    }
+}
+
+/// C-ABI support: wildcard match against the precompiled expected type.
+///
+/// # Safety
+/// `p` must be a valid `*const MediaTypeMatcher` from `inner_ptr`, alive for
+/// the call (the JS wrapper holds the napi instance).
+pub(crate) unsafe fn media_type_matcher_matches_core(
+    p: *const MediaTypeMatcher,
+    actual: &[u8],
+) -> bool {
+    let this = &*p;
+    let Some((ty, subtype)) = split_type_subtype(actual) else {
+        return false;
+    };
+    let ty_ok = this.expected_ty == "*"
+        || crate::util::bytes::ascii_eq_ignore_case(ty, this.expected_ty.as_bytes());
+    let st_ok = this.expected_subtype == "*"
+        || crate::util::bytes::ascii_eq_ignore_case(subtype, this.expected_subtype.as_bytes());
+    ty_ok && st_ok
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn parse(s: &str) -> ParsedMediaType {
+        parse_media_type_core(s.as_bytes()).unwrap()
+    }
+
+    #[test]
+    fn parses_basic_json() {
+        let m = parse("application/json; charset=utf-8");
+        assert_eq!(m.ty, "application");
+        assert_eq!(m.subtype, "json");
+        assert_eq!(m.params, vec![("charset".to_string(), "utf-8".to_string())]);
+    }
+
+    #[test]
+    fn parses_multipart_boundary() {
+        let m = parse("multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW");
+        assert_eq!(m.ty, "multipart");
+        assert_eq!(m.subtype, "form-data");
+        assert_eq!(m.params[0].0, "boundary");
+        assert_eq!(m.params[0].1, "----WebKitFormBoundary7MA4YWxkTrZu0gW");
+    }
+
+    #[test]
+    fn lowercases_type_and_subtype() {
+        let m = parse("Application/JSON; Charset=UTF-8");
+        assert_eq!(m.ty, "application");
+        assert_eq!(m.subtype, "json");
+        assert_eq!(m.params[0], ("charset".to_string(), "UTF-8".to_string()));
+    }
+
+    #[test]
+    fn parses_quoted_param_with_escape() {
+        let m = parse("text/plain; filename=\"a\\\"b.txt\"");
+        assert_eq!(
+            m.params[0],
+            ("filename".to_string(), "a\"b.txt".to_string())
+        );
+    }
+
+    #[test]
+    fn trims_whitespace_and_skips_empty() {
+        let m = parse("  text/html ; charset=utf-8 ;;  q=1 ");
+        assert_eq!(m.ty, "text");
+        assert_eq!(m.subtype, "html");
+        assert_eq!(m.params.len(), 2);
+    }
+
+    #[test]
+    fn matcher_precompiles_expected() {
+        // The precompiled instance only parses `actual` per call — expected is
+        // normalized once at construction. Behavior must match MediaTypeParser.
+        let m = MediaTypeMatcher::new(Uint8Array::new(b"Application/JSON".to_vec())).unwrap();
+        assert!(m.matches(Uint8Array::new(b"application/json".to_vec())));
+        assert!(!m.matches(Uint8Array::new(b"text/html".to_vec())));
+
+        let any = MediaTypeMatcher::new(Uint8Array::new(b"*/*".to_vec())).unwrap();
+        assert!(any.matches(Uint8Array::new(b"text/html".to_vec())));
+        assert!(any.matches(Uint8Array::new(b"application/json".to_vec())));
+
+        let subtype = MediaTypeMatcher::new(Uint8Array::new(b"application/*".to_vec())).unwrap();
+        assert!(subtype.matches(Uint8Array::new(b"application/xml".to_vec())));
+        assert!(!subtype.matches(Uint8Array::new(b"text/xml".to_vec())));
+
+        // Malformed actual → false (never panics).
+        assert!(!m.matches(Uint8Array::new(b"no-slash".to_vec())));
+
+        // Malformed expected → construction error.
+        assert!(MediaTypeMatcher::new(Uint8Array::new(b"no-slash".to_vec())).is_err());
+    }
+
+    #[test]
+    fn rejects_malformed() {
+        assert!(parse_media_type_core(b"application").is_err());
+        assert!(parse_media_type_core(b"application/").is_err());
+        assert!(parse_media_type_core(b"a/b; x=\"unterminated").is_err());
+        assert!(parse_media_type_core(b"a b/c").is_err());
+    }
+}