castrum 0.9.2 → 0.9.4

package/rust/payload/sse.rs

@@ -0,0 +1,214 @@
+// rust/payload/sse.rs — Server-Sent Events framing.
+//
+// Backend-framework feature: SSE response framing. Encodes a single SSE event
+// per the WHATWG SSE spec: optional `id:`, `event:`, `retry:` lines followed by
+// one `data:` line per input line and a terminating blank line. Pure byte work
+// with no allocation beyond the output buffer.
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+// ── Pure-Rust core ─────────────────────────────────────────────
+
+/// Digits in the base-10 decimal form of a `u64` (for the `retry:` line —
+/// avoids `retry.to_string()`'s heap allocation).
+#[inline]
+fn u64_digits(mut n: u64) -> usize {
+    let mut c = 1;
+    while n >= 10 {
+        n /= 10;
+        c += 1;
+    }
+    c
+}
+
+/// Exact encoded size of one SSE event (no allocation).
+#[inline]
+pub fn encode_event_size(
+    event: Option<&str>,
+    data: &[u8],
+    id: Option<&str>,
+    retry: Option<u64>,
+) -> usize {
+    let mut need = 0usize;
+    if let Some(id) = id {
+        need += 5 + id.len(); // "id: " + id + "\n"
+    }
+    if let Some(event) = event {
+        need += 8 + event.len(); // "event: " + event + "\n"
+    }
+    if let Some(retry) = retry {
+        need += 8 + u64_digits(retry); // "retry: " + digits + "\n"
+    }
+    // One `data: ` (6) + `\n` (1) per input line, the line bytes themselves,
+    // then the terminating blank `\n`.
+    let line_count = data.iter().filter(|&&b| b == b'\n').count() + 1;
+    need + line_count * 7 + data.len() + 1
+}
+
+/// Encode one SSE event into `out`, returning bytes written. Zero-alloc (no
+/// `retry.to_string()`, no output `Vec`). Errors (`&'static str`) if `out` is
+/// too small — nothing is written on error.
+pub fn encode_event_into_slice(
+    event: Option<&str>,
+    data: &[u8],
+    id: Option<&str>,
+    retry: Option<u64>,
+    out: &mut [u8],
+) -> std::result::Result<usize, &'static str> {
+    let need = encode_event_size(event, data, id, retry);
+    if need > out.len() {
+        return Err("sse encode: output buffer too small");
+    }
+    let mut w = 0usize;
+    if let Some(id) = id {
+        out[w..w + 4].copy_from_slice(b"id: ");
+        w += 4;
+        out[w..w + id.len()].copy_from_slice(id.as_bytes());
+        w += id.len();
+        out[w] = b'\n';
+        w += 1;
+    }
+    if let Some(event) = event {
+        out[w..w + 7].copy_from_slice(b"event: ");
+        w += 7;
+        out[w..w + event.len()].copy_from_slice(event.as_bytes());
+        w += event.len();
+        out[w] = b'\n';
+        w += 1;
+    }
+    if let Some(retry) = retry {
+        out[w..w + 7].copy_from_slice(b"retry: ");
+        w += 7;
+        let mut digits = [0u8; 20];
+        let mut n = retry;
+        let mut i = 0;
+        loop {
+            digits[i] = b'0' + (n % 10) as u8;
+            n /= 10;
+            i += 1;
+            if n == 0 {
+                break;
+            }
+        }
+        for &d in digits[..i].iter().rev() {
+            out[w] = d;
+            w += 1;
+        }
+        out[w] = b'\n';
+        w += 1;
+    }
+    for line in data.split(|&b| b == b'\n') {
+        out[w..w + 6].copy_from_slice(b"data: ");
+        w += 6;
+        out[w..w + line.len()].copy_from_slice(line);
+        w += line.len();
+        out[w] = b'\n';
+        w += 1;
+    }
+    out[w] = b'\n';
+    w += 1;
+    Ok(w)
+}
+
+/// Encode one SSE event. Multi-line `data` is emitted as repeated `data:` lines.
+pub fn encode_event(
+    event: Option<&str>,
+    data: &[u8],
+    id: Option<&str>,
+    retry: Option<u64>,
+) -> Vec<u8> {
+    let mut out = vec![0u8; encode_event_size(event, data, id, retry)];
+    let w = encode_event_into_slice(event, data, id, retry, &mut out)
+        .expect("output sized to the exact encoded length");
+    out.truncate(w);
+    out
+}
+
+// ── NAPI entry points ──────────────────────────────────────────
+
+/// Encode a single SSE event → bytes.
+#[napi]
+pub fn sse_encode_event(
+    event: Option<String>,
+    data: Uint8Array,
+    id: Option<String>,
+    retry: Option<u32>,
+) -> Buffer {
+    Buffer::from(encode_event(
+        event.as_deref(),
+        data.as_ref(),
+        id.as_deref(),
+        retry.map(u64::from),
+    ))
+}
+
+/// Parallel SSE batch: packed `[u32 count]{[u32 len][data]}` in → packed
+/// `[u32 count]{[u32 len][event]}` out (same event/id/retry for all items).
+#[napi]
+pub fn sse_encode_batch_packed(
+    data: Uint8Array,
+    event: Option<String>,
+    id: Option<String>,
+    retry: Option<u32>,
+) -> Result<Buffer> {
+    let encode_one =
+        |d: &[u8]| encode_event(event.as_deref(), d, id.as_deref(), retry.map(u64::from));
+    crate::util::run_packed_batch(data.as_ref(), encode_one).map(Buffer::from)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn encodes_basic_event() {
+        assert_eq!(encode_event(None, b"hello", None, None), b"data: hello\n\n");
+    }
+
+    #[test]
+    fn encodes_multiline_data() {
+        assert_eq!(
+            encode_event(None, b"line1\nline2", None, None),
+            b"data: line1\ndata: line2\n\n"
+        );
+    }
+
+    #[test]
+    fn encodes_named_event_with_id_and_retry() {
+        assert_eq!(
+            encode_event(Some("update"), b"payload", Some("42"), Some(3000)),
+            b"id: 42\nevent: update\nretry: 3000\ndata: payload\n\n"
+        );
+    }
+
+    #[test]
+    fn empty_data_still_terminates() {
+        assert_eq!(encode_event(None, b"", None, None), b"data: \n\n");
+    }
+
+    #[test]
+    fn into_slice_matches_allocating() {
+        type SseCase<'a> = (Option<&'a str>, &'a [u8], Option<&'a str>, Option<u64>);
+        let cases: &[SseCase] = &[
+            (None, b"hello", None, None),
+            (Some("update"), b"payload", Some("42"), Some(3000)),
+            (None, b"line1\nline2\nline3", None, None),
+            (Some("ev"), b"", Some("id"), Some(0)),
+            (Some(""), b"x", None, None),
+        ];
+        for &(event, data, id, retry) in cases {
+            let expected = encode_event(event, data, id, retry);
+            let mut out = vec![0u8; expected.len() + 8];
+            let w = encode_event_into_slice(event, data, id, retry, &mut out).unwrap();
+            assert_eq!(w, expected.len());
+            assert_eq!(&out[..w], &expected[..]);
+        }
+    }
+
+    #[test]
+    fn into_slice_rejects_too_small() {
+        let mut out = [0u8; 3];
+        assert!(encode_event_into_slice(Some("update"), b"payload", None, None, &mut out).is_err());
+    }
+}

package/rust/payload/template.rs

@@ -0,0 +1,253 @@
+// rust/payload/template.rs — HTML/text templating via minijinja.
+//
+// Backend-framework feature: server-side templating. minijinja is a fast, safe,
+// Jinja2-compatible engine (no eval, no unsafe). Templates are compiled once and
+// cached inside the `Environment`. The napi JS-object `render` accepts a
+// `serde_json::Value` (marshal from JS); the pre-serialized byte paths
+// (`render_bytes` / batch / C-ABI) parse straight into `sonic_rs::Value`
+// (compact, zero per-key heap `String`) — both render via the `Serialize`
+// trait, so behavior is identical.
+//
+// The napi class keeps an owned `Environment<'static>` (templates added via
+// `add_template_owned`), so it is `Send + Sync` and safe to hold across calls.
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+/// A compiled template renderer. Construct once per template, render many times
+/// with different contexts.
+#[napi]
+pub struct TemplateRenderer {
+    // Owns the compiled template state (templates added via add_template_owned).
+    env: minijinja::Environment<'static>,
+}
+
+#[napi]
+impl TemplateRenderer {
+    #[napi(constructor)]
+    pub fn new(source: String) -> Result<Self> {
+        let mut env = minijinja::Environment::new();
+        env.add_template_owned("main", source)
+            .map_err(|e| Error::from_reason(format!("template compile failed: {e}")))?;
+        Ok(Self { env })
+    }
+
+    /// Opaque handle to the compiled template, for the `bun:ffi` C-ABI fast
+    /// path (`castrum_template_render` 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 TemplateRenderer as u64
+    }
+
+    /// Render the template with the given JSON context → UTF-8 bytes.
+    #[napi]
+    pub fn render(&self, context: serde_json::Value) -> Result<Buffer> {
+        let tpl = self
+            .env
+            .get_template("main")
+            .map_err(|e| Error::from_reason(format!("template compile failed: {e}")))?;
+        let out = tpl
+            .render(&context)
+            .map_err(|e| Error::from_reason(format!("template render failed: {e}")))?;
+        Ok(Buffer::from(out.into_bytes()))
+    }
+
+    /// Render the template with a PRE-SERIALIZED JSON context (bytes) → UTF-8
+    /// bytes. Avoids the napi `serde_json::Value` DOM marshal of `render` for
+    /// callers that already hold the context bytes (same core as the packed
+    /// batch path). The context is parsed straight into a `sonic_rs::Value`
+    /// (compact, no per-key heap `String`) instead of `serde_json::Value`.
+    #[napi]
+    pub fn render_bytes(&self, context_json: Uint8Array) -> Result<Buffer> {
+        let tpl = self
+            .env
+            .get_template("main")
+            .map_err(|e| Error::from_reason(format!("template compile failed: {e}")))?;
+        let context: sonic_rs::Value = sonic_rs::from_slice(context_json.as_ref())
+            .map_err(|e| Error::from_reason(format!("template context is not valid JSON: {e}")))?;
+        let out = tpl
+            .render(&context)
+            .map_err(|e| Error::from_reason(format!("template render failed: {e}")))?;
+        Ok(Buffer::from(out.into_bytes()))
+    }
+
+    /// Parallel render batch: packed `[u32 count]{[u32 len][context-json]}` in
+    /// → packed `[u32 count]{[u32 len][rendered]}` out. The compiled template
+    /// is fetched ONCE and reused for every item — no per-call recompilation.
+    #[napi]
+    pub fn render_batch_packed(&self, data: Uint8Array) -> Result<Buffer> {
+        // get_template is a cheap internal Arc lookup — the expensive part
+        // (compiling the template) happened once in the constructor.
+        let tpl = self
+            .env
+            .get_template("main")
+            .map_err(|e| Error::from_reason(format!("template compile failed: {e}")))?;
+
+        let render_one = |context_json: &[u8]| -> Vec<u8> {
+            let Ok(context) = sonic_rs::from_slice::<sonic_rs::Value>(context_json) else {
+                return Vec::new();
+            };
+            tpl.render(&context)
+                .map(|s| s.into_bytes())
+                .unwrap_or_default()
+        };
+
+        crate::util::run_packed_batch(data.as_ref(), render_one).map(Buffer::from)
+    }
+}
+
+/// C-ABI support: render the compiled template with a pre-serialized JSON
+/// context. `Err(())` on invalid JSON context / render error (napi parity).
+///
+/// # Safety
+/// `p` must be a valid `*const TemplateRenderer` from `inner_ptr`, alive for
+/// the call (the JS wrapper holds the napi instance).
+pub(crate) unsafe fn template_render_core(
+    p: *const TemplateRenderer,
+    context_json: &[u8],
+) -> std::result::Result<Vec<u8>, ()> {
+    let this = &*p;
+    let tpl = this.env.get_template("main").map_err(|_| ())?;
+    let context: sonic_rs::Value = sonic_rs::from_slice(context_json).map_err(|_| ())?;
+    let out = tpl.render(&context).map_err(|_| ())?;
+    Ok(out.into_bytes())
+}
+
+/// Parallel render batch: packed `[u32 count]{[u32 len][context-json]}` in →
+/// packed `[u32 count]{[u32 len][rendered]}` out. A new `TemplateRenderer` is
+/// built once per call from `source`, then all contexts render in parallel.
+#[napi]
+pub fn template_render_batch_packed(data: Uint8Array, source: String) -> Result<Buffer> {
+    let mut env = minijinja::Environment::new();
+    env.add_template_owned("main", source)
+        .map_err(|e| Error::from_reason(format!("template compile failed: {e}")))?;
+
+    let render_one = |context_json: &[u8]| -> Vec<u8> {
+        let Ok(context) = sonic_rs::from_slice::<sonic_rs::Value>(context_json) else {
+            return Vec::new();
+        };
+        let Ok(tpl) = env.get_template("main") else {
+            return Vec::new();
+        };
+        tpl.render(&context)
+            .map(|s| s.into_bytes())
+            .unwrap_or_default()
+    };
+
+    crate::util::run_packed_batch(data.as_ref(), render_one).map(Buffer::from)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::BTreeMap;
+
+    #[test]
+    fn renders_variables() {
+        let mut env = minijinja::Environment::new();
+        env.add_template("t", "Hello {{ name }}!").unwrap();
+        let tpl = env.get_template("t").unwrap();
+        let mut ctx = BTreeMap::new();
+        ctx.insert("name", "World");
+        assert_eq!(tpl.render(ctx).unwrap(), "Hello World!");
+    }
+
+    #[test]
+    fn renders_loops_over_serde_value() {
+        let mut env = minijinja::Environment::new();
+        env.add_template(
+            "t",
+            "{% for u in users %}<li>{{ u.name }} ({{ u.id }})</li>{% endfor %}",
+        )
+        .unwrap();
+        let tpl = env.get_template("t").unwrap();
+
+        let context = serde_json::json!({
+            "users": [
+                { "name": "Alice", "id": 1 },
+                { "name": "Bob", "id": 2 },
+            ]
+        });
+        let out = tpl.render(&context).unwrap();
+        assert_eq!(out, "<li>Alice (1)</li><li>Bob (2)</li>");
+    }
+
+    #[test]
+    fn compile_error_is_reported() {
+        let mut env = minijinja::Environment::new();
+        assert!(env.add_template("t", "{% for x in %}").is_err());
+    }
+
+    #[test]
+    fn missing_variable_renders_empty() {
+        let mut env = minijinja::Environment::new();
+        env.add_template("t", "[{{ missing }}]").unwrap();
+        let tpl = env.get_template("t").unwrap();
+        let ctx = serde_json::json!({});
+        assert_eq!(tpl.render(&ctx).unwrap(), "[]");
+    }
+
+    fn pack_contexts(contexts: &[serde_json::Value]) -> Vec<u8> {
+        let mut out = Vec::new();
+        out.extend_from_slice(&(contexts.len() as u32).to_le_bytes());
+        for c in contexts {
+            let bytes = serde_json::to_vec(c).unwrap();
+            out.extend_from_slice(&(bytes.len() as u32).to_le_bytes());
+            out.extend_from_slice(&bytes);
+        }
+        out
+    }
+
+    #[test]
+    fn renderer_instance_reuses_compiled_template() {
+        let r = TemplateRenderer::new("Hello {{ name }}!".to_string()).unwrap();
+        let ctx = serde_json::json!({ "name": "World" });
+        assert_eq!(&r.render(ctx).unwrap()[..], b"Hello World!");
+
+        // Batch path must reuse the SAME compiled template.
+        let data = pack_contexts(&[
+            serde_json::json!({ "name": "Alice" }),
+            serde_json::json!({ "name": "Bob" }),
+        ]);
+        let batch = r.render_batch_packed(Uint8Array::new(data)).unwrap();
+        assert_eq!(u32::from_le_bytes(batch[..4].try_into().unwrap()), 2);
+
+        let mut pos = 4usize;
+        let mut renders = Vec::new();
+        for _ in 0..2 {
+            let len = u32::from_le_bytes(batch[pos..pos + 4].try_into().unwrap()) as usize;
+            pos += 4;
+            renders.push(String::from_utf8(batch[pos..pos + len].to_vec()).unwrap());
+            pos += len;
+        }
+        assert_eq!(
+            renders,
+            vec!["Hello Alice!".to_string(), "Hello Bob!".to_string()]
+        );
+    }
+
+    #[test]
+    fn render_bytes_matches_render() {
+        let r = TemplateRenderer::new("Hello {{ name }}!".to_string()).unwrap();
+        let via_value = r.render(serde_json::json!({ "name": "World" })).unwrap();
+        let via_bytes = r
+            .render_bytes(Uint8Array::new(br#"{"name":"World"}"#.to_vec()))
+            .unwrap();
+        assert_eq!(via_value.as_ref(), via_bytes.as_ref());
+        assert_eq!(&via_bytes[..], b"Hello World!");
+    }
+
+    #[test]
+    fn render_bytes_rejects_invalid_json_context() {
+        let r = TemplateRenderer::new("x".to_string()).unwrap();
+        assert!(r
+            .render_bytes(Uint8Array::new(b"not json".to_vec()))
+            .is_err());
+    }
+
+    #[test]
+    fn renderer_rejects_bad_compile() {
+        assert!(TemplateRenderer::new("{% for x in %}".to_string()).is_err());
+    }
+}

package/rust/payload/websocket.rs

@@ -0,0 +1,69 @@
+// rust/payload/websocket.rs — RFC 6455 Sec-WebSocket-Accept key derivation.
+
+use aws_lc_rs::digest;
+use base64::engine::general_purpose::STANDARD as BASE64;
+use base64::Engine;
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+const WS_MAGIC: &[u8] = b"258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+
+/// Zero-alloc core: RFC 6455 Sec-WebSocket-Accept (exactly 28 bytes) into a
+/// caller-provided buffer. Shared by the C-ABI (`bun:ffi`) path so it never
+/// allocates the accept string.
+pub fn ws_accept_key_into(key: &[u8], out: &mut [u8]) -> Result<usize> {
+    let mut ctx = digest::Context::new(&digest::SHA1_FOR_LEGACY_USE_ONLY);
+    ctx.update(key);
+    ctx.update(WS_MAGIC);
+
+    let hash = ctx.finish();
+
+    BASE64
+        .encode_slice(hash.as_ref(), out)
+        .map_err(|e| Error::from_reason(e.to_string()))
+}
+
+/// RFC 6455 Sec-WebSocket-Accept core over a raw key slice. Shared by the
+/// scalar napi path and the packed batch path.
+pub fn ws_accept_key_bytes(key: &[u8]) -> Result<Vec<u8>> {
+    let mut out = [0u8; 28];
+    let n = ws_accept_key_into(key, &mut out)?;
+    Ok(out[..n].to_vec())
+}
+
+#[napi]
+pub fn ws_accept_key(key: Uint8Array) -> Result<Buffer> {
+    Ok(Buffer::from(ws_accept_key_bytes(key.as_ref())?))
+}
+
+/// Packed WebSocket accept-key batch: `[u32 count]{[u32 len][key]}` in →
+/// `[u32 count]{[u32 len][accept]}` out.
+#[napi]
+pub fn ws_accept_key_batch_packed(input: Uint8Array) -> Result<Buffer> {
+    crate::util::run_packed_batch(input.as_ref(), |k| {
+        ws_accept_key_bytes(k).unwrap_or_default()
+    })
+    .map(Buffer::from)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn rfc6455_accept_key_vector() {
+        // RFC 6455 §1.3: accept = base64(SHA1(key + magic GUID)) where `key` is
+        // the Sec-WebSocket-Key header value (the base64 string) concatenated
+        // with the magic GUID. Verified against node:crypto.
+        let key = b"dGhlIHNhbXBsZSBub25jZQ==";
+        let out = ws_accept_key(Uint8Array::new(key.to_vec())).unwrap();
+        assert_eq!(out.as_ref(), b"s3pPLMBiTxaQ9kYGzzhZRbK+xOo=");
+    }
+
+    #[test]
+    fn different_keys_differ() {
+        let a = ws_accept_key(Uint8Array::new(b"AAAA".to_vec())).unwrap();
+        let b = ws_accept_key(Uint8Array::new(b"BBBB".to_vec())).unwrap();
+        assert_ne!(a.as_ref(), b.as_ref());
+    }
+}