castrum 0.9.3 → 0.9.6

package/rust/http/headers.rs

@@ -0,0 +1,267 @@
+// rust/http/headers.rs — HeaderRefs: zero-alloc packed header parser
+// Uses the shared word-at-a-time comparator from `bytes.rs`.
+//
+// Pure core (no napi types): errors are plain `String` messages; the napi
+// boundary maps them to JS errors.
+
+use crate::util::bytes::ascii_eq_ignore_case;
+
+// ── Header presence flags ─────────────────────────────────────────
+const HAS_ORIGIN: u8 = 1 << 0;
+const HAS_XFF: u8 = 1 << 1;
+const HAS_X_REAL_IP: u8 = 1 << 2;
+const HAS_XFP: u8 = 1 << 3;
+const HAS_ACRM: u8 = 1 << 4;
+
+/// Zero-alloc reference-based representation of interesting headers.
+#[derive(Clone, Copy)]
+pub struct HeaderRefs<'a> {
+    origin: Option<&'a [u8]>,
+    cookie: Option<&'a [u8]>,
+    xff: Option<&'a [u8]>,
+    x_real_ip: Option<&'a [u8]>,
+    x_forwarded_proto: Option<&'a [u8]>,
+    acrm: Option<&'a [u8]>,
+    acrh: Option<&'a [u8]>,
+    flags: u8,
+}
+
+impl<'a> HeaderRefs<'a> {
+    #[inline(always)]
+    pub fn empty() -> Self {
+        Self {
+            origin: None,
+            cookie: None,
+            xff: None,
+            x_real_ip: None,
+            x_forwarded_proto: None,
+            acrm: None,
+            acrh: None,
+            flags: 0,
+        }
+    }
+
+    /// Parse packed headers from the input buffer.
+    /// Format: [u16 count] repeated { [u16 name_len] [name] [u32 value_len] [value] }
+    #[inline]
+    pub fn parse(
+        packed: &'a [u8],
+        is_options: bool,
+        max_headers: usize,
+    ) -> std::result::Result<Self, String> {
+        let mut h = Self::empty();
+
+        if packed.len() < 2 {
+            return Ok(h);
+        }
+
+        let count = u16::from_le_bytes([packed[0], packed[1]]) as usize;
+        if count > max_headers {
+            return Err("too many headers".to_string());
+        }
+
+        let mut pos = 2usize;
+
+        for _ in 0..count {
+            if pos + 2 > packed.len() {
+                return Err("malformed packed headers".to_string());
+            }
+
+            let name_len = u16::from_le_bytes([packed[pos], packed[pos + 1]]) as usize;
+            pos += 2;
+
+            if pos + name_len > packed.len() {
+                return Err("malformed packed header name".to_string());
+            }
+
+            let name = &packed[pos..pos + name_len];
+            pos += name_len;
+
+            if pos + 4 > packed.len() {
+                return Err("malformed packed header value length".to_string());
+            }
+
+            let value_len = u32::from_le_bytes([
+                packed[pos],
+                packed[pos + 1],
+                packed[pos + 2],
+                packed[pos + 3],
+            ]) as usize;
+            pos += 4;
+
+            if pos + value_len > packed.len() {
+                return Err("malformed packed header value".to_string());
+            }
+
+            let value = &packed[pos..pos + value_len];
+            pos += value_len;
+
+            if name.is_empty() {
+                continue;
+            }
+
+            let first = name[0] | 0x20;
+
+            // Fast path: dispatch based on first character + name length
+            if first == b'o' && name.len() == 6 {
+                if ascii_eq_ignore_case(name, b"origin") {
+                    h.flags |= HAS_ORIGIN;
+                    h.origin = Some(value);
+                }
+            } else if first == b'c' && name.len() == 6 {
+                if ascii_eq_ignore_case(name, b"cookie") {
+                    h.cookie = Some(value);
+                }
+            } else if first == b'x' {
+                let name_len = name.len();
+                if name_len == 15 && ascii_eq_ignore_case(name, b"x-forwarded-for") {
+                    h.flags |= HAS_XFF;
+                    h.xff = Some(value);
+                } else if name_len == 9 && ascii_eq_ignore_case(name, b"x-real-ip") {
+                    h.flags |= HAS_X_REAL_IP;
+                    h.x_real_ip = Some(value);
+                } else if name_len == 17 && ascii_eq_ignore_case(name, b"x-forwarded-proto") {
+                    h.flags |= HAS_XFP;
+                    h.x_forwarded_proto = Some(value);
+                }
+            } else if first == b'a' && is_options {
+                if name.len() == 29 && ascii_eq_ignore_case(name, b"access-control-request-method")
+                {
+                    h.flags |= HAS_ACRM;
+                    h.acrm = Some(value);
+                } else if name.len() == 30
+                    && ascii_eq_ignore_case(name, b"access-control-request-headers")
+                {
+                    h.acrh = Some(value);
+                }
+            }
+        }
+
+        Ok(h)
+    }
+
+    #[inline(always)]
+    pub fn origin(&self) -> Option<&[u8]> {
+        self.origin
+    }
+
+    #[inline(always)]
+    pub fn cookie(&self) -> Option<&[u8]> {
+        self.cookie
+    }
+
+    #[inline(always)]
+    pub fn xff(&self) -> Option<&[u8]> {
+        self.xff
+    }
+
+    #[inline(always)]
+    pub fn x_real_ip(&self) -> Option<&[u8]> {
+        self.x_real_ip
+    }
+
+    #[inline(always)]
+    pub fn x_forwarded_proto(&self) -> Option<&[u8]> {
+        self.x_forwarded_proto
+    }
+
+    #[inline(always)]
+    pub fn acrm(&self) -> Option<&[u8]> {
+        self.acrm
+    }
+
+    #[inline(always)]
+    pub fn acrh(&self) -> Option<&[u8]> {
+        self.acrh
+    }
+
+    #[inline(always)]
+    pub fn has_origin(&self) -> bool {
+        (self.flags & HAS_ORIGIN) != 0
+    }
+
+    #[inline(always)]
+    pub fn has_xfp(&self) -> bool {
+        (self.flags & HAS_XFP) != 0
+    }
+
+    #[inline(always)]
+    pub fn has_acrm(&self) -> bool {
+        (self.flags & HAS_ACRM) != 0
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::HeaderRefs;
+    use crate::test_support::pack_headers;
+
+    #[test]
+    fn headers_parse_empty_ok() {
+        let h = HeaderRefs::parse(b"", false, 100).unwrap();
+        assert!(h.origin().is_none());
+        assert!(h.cookie().is_none());
+    }
+
+    #[test]
+    fn headers_parse_presence_and_values() {
+        let packed = pack_headers([
+            ("Origin", "https://example.com"),
+            ("Cookie", "session=abc"),
+            ("X-Forwarded-For", "1.2.3.4"),
+        ]);
+        let h = HeaderRefs::parse(&packed, false, 100).unwrap();
+        assert_eq!(h.origin(), Some(&b"https://example.com"[..]));
+        assert_eq!(h.cookie(), Some(&b"session=abc"[..]));
+        assert_eq!(h.xff(), Some(&b"1.2.3.4"[..]));
+    }
+
+    #[test]
+    fn headers_parse_case_insensitive_names() {
+        let packed = pack_headers([("ORIGIN", "https://x.io")]);
+        let h = HeaderRefs::parse(&packed, false, 100).unwrap();
+        assert_eq!(h.origin(), Some(&b"https://x.io"[..]));
+    }
+
+    #[test]
+    fn headers_parse_acrm_only_for_options() {
+        let packed = pack_headers([
+            ("access-control-request-method", "POST"),
+            ("access-control-request-headers", "Content-Type"),
+        ]);
+        // Non-OPTIONS: ACRM/ACRH should not be captured.
+        let h = HeaderRefs::parse(&packed, false, 100).unwrap();
+        assert!(!h.has_acrm());
+        // OPTIONS: they should be captured.
+        let h2 = HeaderRefs::parse(&packed, true, 100).unwrap();
+        assert!(h2.has_acrm());
+        // ACRH value is captured on OPTIONS (no dedicated flag/method).
+        assert_eq!(h2.acrh(), Some(&b"Content-Type"[..]));
+    }
+
+    #[test]
+    fn headers_parse_too_many_headers_rejected() {
+        let mut pairs: Vec<(String, String)> = Vec::new();
+        for i in 0..10 {
+            pairs.push(("x".to_string(), format!("v{i}")));
+        }
+
+        let mut packed = Vec::new();
+        packed.extend_from_slice(&(pairs.len() as u16).to_le_bytes());
+        for (name, value) in &pairs {
+            packed.extend_from_slice(&(name.len() as u16).to_le_bytes());
+            packed.extend_from_slice(name.as_bytes());
+            packed.extend_from_slice(&(value.len() as u32).to_le_bytes());
+            packed.extend_from_slice(value.as_bytes());
+        }
+
+        assert!(HeaderRefs::parse(&packed, false, 5).is_err());
+    }
+
+    #[test]
+    fn headers_parse_malformed_rejected() {
+        // Declares a name_len that runs past the end of the buffer.
+        let packed = [2u8, 0, 0xFF, 0xFF, b'x'];
+        assert!(HeaderRefs::parse(&packed, false, 100).is_err());
+    }
+}

package/rust/http/http_date.rs

@@ -0,0 +1,286 @@
+// rust/http/http_date.rs — HTTP-date (IMF-fixdate) formatting + parsing.
+//
+// `Sun, 06 Nov 1994 08:49:37 GMT` → unix seconds and back, with a zero-alloc
+// fixed-width writer for hot loops. The date arithmetic uses Howard Hinnant's
+// days↔civil algorithms (epoch-correct). Extracted from `etag.rs` so the
+// HTTP cache semantics file owns only ETags + conditional requests.
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+const DAY_NAMES: [&str; 7] = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+const MONTH_NAMES: [&str; 12] = [
+    "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+];
+
+/// Days since epoch → civil (year, month, day) — Hinnant's algorithm.
+fn civil_from_days(z: i64) -> (i64, u32, u32) {
+    let z = z + 719_468;
+    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
+    let doe = (z - era * 146_097) as u64;
+    let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365;
+    let y = yoe as i64 + era * 400;
+    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
+    let mp = (5 * doy + 2) / 153;
+    let d = (doy - (153 * mp + 2) / 5 + 1) as u32;
+    let m = if mp < 10 { mp + 3 } else { mp - 9 } as u32;
+    let y = if m <= 2 { y + 1 } else { y };
+    (y, m, d)
+}
+
+/// Civil date → days since epoch — Hinnant's inverse algorithm.
+fn days_from_civil(y: i64, m: u32, d: u32) -> Option<i64> {
+    if !(1..=12).contains(&m) || d == 0 || d > 31 {
+        return None;
+    }
+    let y = if m <= 2 { y - 1 } else { y };
+    let era = if y >= 0 { y } else { y - 399 } / 400;
+    let yoe = (y - era * 400) as u64;
+    let mp = ((m as i64 + 9) % 12) as u64;
+    let doy = (153 * mp + 2) / 5 + (d - 1) as u64;
+    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
+    Some(era * 146_097 + doe as i64 - 719_468)
+}
+
+/// Format `value` as a zero-padded decimal of exactly `width` digits into
+/// `out`. `value` must fit in `width` digits.
+#[inline]
+fn write_padded(out: &mut [u8], mut value: u32, width: usize) {
+    for i in (0..width).rev() {
+        out[i] = b'0' + (value % 10) as u8;
+        value /= 10;
+    }
+}
+
+/// Parsed http-date components (computed once, shared by the allocating and
+/// pooled-output formatters).
+struct HttpDateParts {
+    y: i64,
+    m: u32,
+    d: u32,
+    hh: i64,
+    mm: i64,
+    ss: i64,
+    wd: usize,
+}
+
+fn http_date_parts(secs: i64) -> HttpDateParts {
+    let days = secs.div_euclid(86_400);
+    let rem = secs.rem_euclid(86_400);
+    let hh = rem / 3600;
+    let mm = (rem % 3600) / 60;
+    let ss = rem % 60;
+    let (y, m, d) = civil_from_days(days);
+    // 1970-01-01 was a Thursday; weekday Mon=0 → (days+3) mod 7.
+    let wd = ((days.rem_euclid(7) + 3) % 7) as usize;
+    HttpDateParts {
+        y,
+        m,
+        d,
+        hh,
+        mm,
+        ss,
+        wd,
+    }
+}
+
+/// Write the fixed-width `ddd, dd mmm yyyy hh:mm:ss GMT` layout into `out`
+/// (29 bytes, no heap allocation). `Err` only for years outside 0..=9999
+/// (where the fixed-width layout is undefined) or a too-small buffer.
+fn write_http_date_parts(
+    p: &HttpDateParts,
+    out: &mut [u8],
+) -> std::result::Result<usize, &'static str> {
+    // 3 + 2 (", ") + 2 + 1 (" ") + 3 + 1 (" ") + 4 + 1 (" ") + 2 + 1 (":") + 2
+    // + 1 (":") + 2 + 1 (" ") + 3 = 29
+    if out.len() < 29 {
+        return Err("http-date: output buffer too small");
+    }
+    if !(0..=9999).contains(&p.y) {
+        return Err("http-date: year out of range for fixed-width layout");
+    }
+    let mut i = 0usize;
+    out[i..i + 3].copy_from_slice(DAY_NAMES[p.wd].as_bytes());
+    i += 3;
+    out[i] = b',';
+    i += 1;
+    out[i] = b' ';
+    i += 1;
+    write_padded(&mut out[i..i + 2], p.d, 2);
+    i += 2;
+    out[i] = b' ';
+    i += 1;
+    out[i..i + 3].copy_from_slice(MONTH_NAMES[(p.m - 1) as usize].as_bytes());
+    i += 3;
+    out[i] = b' ';
+    i += 1;
+    write_padded(&mut out[i..i + 4], p.y as u32, 4);
+    i += 4;
+    out[i] = b' ';
+    i += 1;
+    write_padded(&mut out[i..i + 2], p.hh as u32, 2);
+    i += 2;
+    out[i] = b':';
+    i += 1;
+    write_padded(&mut out[i..i + 2], p.mm as u32, 2);
+    i += 2;
+    out[i] = b':';
+    i += 1;
+    write_padded(&mut out[i..i + 2], p.ss as u32, 2);
+    i += 2;
+    out[i] = b' ';
+    i += 1;
+    out[i..i + 3].copy_from_slice(b"GMT");
+    i += 3;
+    Ok(i)
+}
+
+/// Format a unix timestamp (seconds) as `Sun, 06 Nov 1994 08:49:37 GMT`.
+/// Written into a fixed 32-byte stack buffer — no `format!`/heap allocation.
+pub fn http_date_from_secs(secs: i64) -> String {
+    let p = http_date_parts(secs);
+    let mut buf = [0u8; 32];
+    match write_http_date_parts(&p, &mut buf) {
+        Ok(n) => String::from_utf8(buf[..n].to_vec()).expect("http-date is ASCII"),
+        Err(_) => {
+            // Year outside 0..=9999: HTTP-date is only well-defined for
+            // 0000-9999, but keep the exact `format!` fallback so behavior
+            // never changes from before the refactor.
+            format!(
+                "{}, {:02} {} {:04} {:02}:{:02}:{:02} GMT",
+                DAY_NAMES[p.wd],
+                p.d,
+                MONTH_NAMES[(p.m - 1) as usize],
+                p.y,
+                p.hh,
+                p.mm,
+                p.ss
+            )
+        }
+    }
+}
+
+/// Write an http-date directly into `out` (fixed 29 bytes, no heap alloc).
+/// Returns bytes written; errors on a too-small buffer or a year outside
+/// 0..=9999 (use the allocating `http_date` for that fallback).
+pub fn http_date_into_slice(secs: i64, out: &mut [u8]) -> Result<usize> {
+    let p = http_date_parts(secs);
+    write_http_date_parts(&p, out).map_err(|e| Error::from_reason(e.to_string()))
+}
+
+/// Parse `Sun, 06 Nov 1994 08:49:37 GMT` back to unix seconds.
+pub fn parse_http_date_secs(input: &[u8]) -> Option<i64> {
+    let s = std::str::from_utf8(input).ok()?.trim();
+    let comma = s.find(',')?;
+    let rest = s[comma + 1..].trim();
+    let mut parts = rest.split_whitespace();
+    let day: u32 = parts.next()?.parse().ok()?;
+    let mon = parts.next()?;
+    let year: i64 = parts.next()?.parse().ok()?;
+    let time = parts.next()?;
+    let month = MONTH_NAMES
+        .iter()
+        .position(|m| m.eq_ignore_ascii_case(mon))?
+        + 1;
+    let mut tp = time.split(':');
+    let hh: u32 = tp.next()?.parse().ok()?;
+    let mm: u32 = tp.next()?.parse().ok()?;
+    let ss: u32 = tp.next()?.parse().ok()?;
+    if hh > 23 || mm > 59 || ss > 60 {
+        return None;
+    }
+    let days = days_from_civil(year, month as u32, day)?;
+    Some(days * 86_400 + i64::from(hh) * 3600 + i64::from(mm) * 60 + i64::from(ss))
+}
+
+#[napi]
+pub fn http_date(secs: Option<f64>) -> Buffer {
+    let s = secs.map(|v| v as i64).unwrap_or(0);
+    Buffer::from(http_date_from_secs(s).into_bytes())
+}
+
+/// Pooled-output variant: writes the http-date into `output` and returns bytes
+/// written, so hot loops can reuse a buffer instead of allocating a fresh
+/// Buffer per call. Errors if `output` is too small or the year is outside the
+/// fixed-width range (use the allocating `http_date` for that fallback).
+#[napi]
+pub fn http_date_into(secs: Option<f64>, mut output: Uint8Array) -> Result<u32> {
+    let s = secs.map(|v| v as i64).unwrap_or(0);
+    // SAFETY: `http_date_into_slice` is capacity-checked (returns Err on a
+    // too-small buffer before writing), and no other reference to `output` is
+    // live while it runs.
+    let written = unsafe { http_date_into_slice(s, output.as_mut())? };
+    Ok(written as u32)
+}
+
+#[napi]
+pub fn parse_http_date(input: Uint8Array) -> Option<BigInt> {
+    parse_http_date_secs(input.as_ref()).map(BigInt::from)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn http_date_epoch() {
+        assert_eq!(http_date_from_secs(0), "Thu, 01 Jan 1970 00:00:00 GMT");
+        assert_eq!(
+            http_date_from_secs(978_307_200),
+            "Mon, 01 Jan 2001 00:00:00 GMT"
+        );
+        assert_eq!(
+            http_date_from_secs(784_111_777),
+            "Sun, 06 Nov 1994 08:49:37 GMT"
+        );
+    }
+
+    #[test]
+    fn http_date_roundtrip() {
+        for secs in [0i64, 1, 946_684_800, 784_111_777, 1_700_000_000] {
+            let s = http_date_from_secs(secs);
+            assert_eq!(parse_http_date_secs(s.as_bytes()), Some(secs));
+        }
+    }
+
+    #[test]
+    fn http_date_into_matches_allocating() {
+        for secs in [
+            0i64,
+            1,
+            946_684_800,
+            784_111_777,
+            1_700_000_000,
+            -1,
+            -86_400,
+        ] {
+            let expected = http_date_from_secs(secs);
+            let mut out = [0u8; 32];
+            let n = http_date_into_slice(secs, &mut out).unwrap();
+            assert_eq!(&out[..n], expected.as_bytes(), "secs: {secs}");
+        }
+    }
+
+    #[test]
+    fn http_date_into_rejects_small_buffer() {
+        let mut out = [0u8; 28];
+        assert!(http_date_into_slice(0, &mut out).is_err());
+    }
+
+    #[test]
+    fn http_date_into_out_of_range_year_falls_back() {
+        // Year 10000 (253_402_300_800s): the fixed-width pooled writer errors;
+        // the allocating path keeps the exact format! fallback.
+        let big = 253_402_300_800i64; // 10000-01-01T00:00:00Z
+        let mut out = [0u8; 32];
+        assert!(http_date_into_slice(big, &mut out).is_err());
+        assert!(http_date_from_secs(big).contains("01 Jan 10000"));
+    }
+
+    #[test]
+    fn parse_http_date_rejects_malformed() {
+        assert!(parse_http_date_secs(b"not a date").is_none());
+        assert!(parse_http_date_secs(b"Sun, 99 Nov 1994 08:49:37 GMT").is_none());
+        assert!(parse_http_date_secs(b"Sun, 06 Nov 1994 25:49:37 GMT").is_none());
+    }
+}