castrum 0.9.2 → 0.9.4

package/rust/ffi/payload.rs

@@ -0,0 +1,275 @@
+// rust/ffi/payload.rs — payload C-ABI exports.
+//
+// WebSocket accept-key + frame encode/decode, gzip/brotli compress-decompress
+// (via the shared `compress_to_out!` macro — see the needed-size convention),
+// and SSE event encoding.
+
+use std::slice;
+
+use super::util::{cstring_return, panic_guard};
+
+/// RFC 6455 Sec-WebSocket-Accept (28 bytes) returned as a null-terminated C
+/// string into the per-thread reused buffer (`cstring` return).
+///
+/// `key` is a `bun:ffi` `cstring` ARG — the engine transcodes the JS base64 key
+/// in-engine (JS does zero encode; the callee borrows via `CStr::from_ptr`).
+/// The pooled `castrum_ws_accept_key_into` keeps the `(ptr,len)` byte form.
+///
+/// # Safety
+/// `key` must be a valid NUL-terminated C string.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_ws_accept_key(
+    key: *const std::os::raw::c_char,
+) -> *const std::os::raw::c_char {
+    if key.is_null() {
+        return std::ptr::null();
+    }
+    cstring_return(28, |out| {
+        crate::payload::websocket::ws_accept_key_into(std::ffi::CStr::from_ptr(key).to_bytes(), out)
+            .ok()
+    })
+}
+
+/// RFC 6455 Sec-WebSocket-Accept written directly into a caller buffer — the
+/// pooled sibling of `castrum_ws_accept_key` (no cstring round-trip). Writes 28
+/// bytes; returns bytes written, the exact required size when `out_cap` is too
+/// small, or 0 on a malformed key.
+///
+/// # Safety
+/// `key` must be valid for reads of `klen` bytes; `out` for writes up to `out_cap`.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_ws_accept_key_into(
+    key: *const u8,
+    klen: usize,
+    out: *mut u8,
+    out_cap: usize,
+) -> usize {
+    if key.is_null() || out.is_null() {
+        return 0;
+    }
+    if out_cap < 28 {
+        return 28;
+    }
+    match crate::payload::websocket::ws_accept_key_into(
+        slice::from_raw_parts(key, klen),
+        slice::from_raw_parts_mut(out, 28),
+    ) {
+        Ok(28) => 28,
+        _ => 0,
+    }
+}
+
+/// WebSocket frame encode into `out` (opcode 1/2/8/9/10, `mask`/`fin` flags).
+///
+/// # Safety
+/// `payload` must be valid for reads of `plen` bytes; `out` for `out_cap`.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_ws_frame_encode(
+    opcode: u8,
+    payload: *const u8,
+    plen: usize,
+    mask: u8,
+    fin: u8,
+    out: *mut u8,
+    out_cap: usize,
+) -> usize {
+    if payload.is_null() || out.is_null() {
+        return 0;
+    }
+    crate::payload::ws_frames::encode_frame_into(
+        opcode,
+        slice::from_raw_parts(payload, plen),
+        mask != 0,
+        fin != 0,
+        slice::from_raw_parts_mut(out, out_cap),
+    )
+    .unwrap_or(0)
+}
+
+/// Decode a WebSocket frame into a packed `[u8 flags][u8 opcode][u32 payload_len]
+/// [payload]` layout (flags bit0 = FIN). Returns bytes written, 0 on malformed
+/// input. JS decodes the small header into the `WsFrame` shape.
+///
+/// # Safety
+/// `data` must be valid for reads of `len` bytes; `out` for writes up to `out_cap`.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_ws_frame_decode_packed(
+    data: *const u8,
+    len: usize,
+    out: *mut u8,
+    out_cap: usize,
+) -> usize {
+    if data.is_null() || out.is_null() {
+        return 0;
+    }
+    let Some(frame) = crate::payload::ws_frames::decode_frame(slice::from_raw_parts(data, len))
+    else {
+        return 0;
+    };
+    let Some(need) = 6usize.checked_add(frame.payload.len()) else {
+        return 0;
+    };
+    if need > out_cap {
+        return 0;
+    }
+    let o = slice::from_raw_parts_mut(out, need);
+    o[0] = u8::from(frame.fin);
+    o[1] = frame.opcode;
+    o[2..6].copy_from_slice(&(frame.payload.len() as u32).to_le_bytes());
+    o[6..].copy_from_slice(&frame.payload);
+    need
+}
+
+// ── Compression (gzip / brotli) ──────────────────────────────────
+
+macro_rules! compress_to_out {
+    ($name:ident, $core:path, $extra:ty) => {
+        #[doc = concat!("Run `", stringify!($core), "` and write the result into `out`.")]
+        ///
+        /// # Convention
+        /// Returns the exact total bytes the result requires (the written count
+        /// on success, or the needed size when `out_cap` is too small). The JS
+        /// wrapper compares against `out_cap` to distinguish success from
+        /// too-small, so a miss allocates EXACTLY once and retries — it never
+        /// re-runs the whole (de)compression in a grow loop. `0` is reserved
+        /// for a REAL error (invalid stream / decompression-cap exceeded).
+        ///
+        /// # Safety
+        /// `data` must be valid for reads of `len` bytes; `out` for writes up to `out_cap`.
+        #[no_mangle]
+        pub unsafe extern "C" fn $name(
+            data: *const u8,
+            len: usize,
+            extra: $extra,
+            out: *mut u8,
+            out_cap: usize,
+        ) -> usize {
+            if data.is_null() || out.is_null() {
+                return 0;
+            }
+            let input = slice::from_raw_parts(data, len);
+            let output = slice::from_raw_parts_mut(out, out_cap);
+            panic_guard(
+                || match $core(input, extra, output) {
+                    Ok(w) => w,
+                    // Needed-size convention: report the EXACT required size so the
+                    // JS wrapper allocates once and retries (never a re-run loop).
+                    Err(crate::payload::compress::StreamError::TooSmall { needed }) => needed,
+                    // Real error (invalid stream / decompression cap exceeded) → 0.
+                    Err(_) => 0,
+                },
+                0,
+            )
+        }
+    };
+}
+
+compress_to_out!(
+    castrum_gzip_compress,
+    crate::payload::compress::gzip_compress_into,
+    u32
+);
+compress_to_out!(
+    castrum_gzip_decompress,
+    crate::payload::compress::gzip_decompress_into,
+    usize
+);
+compress_to_out!(
+    castrum_brotli_compress,
+    crate::payload::compress::brotli_compress_into,
+    u32
+);
+compress_to_out!(
+    castrum_brotli_decompress,
+    crate::payload::compress::brotli_decompress_into,
+    usize
+);
+
+/// Read the original (uncompressed) size from a gzip stream's ISIZE trailer
+/// (last 4 bytes, little-endian, original size mod 2^32). Returns the EXACT
+/// output size for a single-member standard gzip stream, or 0 when the input
+/// isn't a usable standard gzip stream (too short / not gzip magic). Lets the
+/// JS wrapper pre-size the decompress buffer exactly so the happy path is a
+/// single pass (no grow-retry re-run).
+///
+/// # Safety
+/// `data` must be valid for reads of `len` bytes.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_gzip_isize(data: *const u8, len: usize) -> u32 {
+    if data.is_null() || len < 18 {
+        return 0;
+    }
+    let s = slice::from_raw_parts(data, len);
+    if s[0] != 0x1f || s[1] != 0x8b {
+        return 0;
+    }
+    u32::from_le_bytes([s[len - 4], s[len - 3], s[len - 2], s[len - 1]])
+}
+
+/// Encode one SSE event into `out`. Optional fields use `flags` bits
+/// (1 = event present, 2 = id present, 4 = retry present) so a present-but-empty
+/// string is distinct from an absent one, matching the napi `Option<String>`.
+/// Returns bytes written, or 0 on a too-small buffer / invalid UTF-8 in
+/// event/id (JS sizes `data_len + 64` to guarantee success). FFI sibling of the
+/// napi `sse_encode_event` — the wrapper decodes nothing (output is raw SSE
+/// bytes), so this just removes the napi crossing.
+///
+/// # Safety
+/// `event`/`id` must be valid for reads of `event_len`/`id_len` bytes when their
+/// flag is set; `data` valid for `data_len` reads; `out` for `out_cap` writes.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_sse_encode_into(
+    event: *const u8,
+    event_len: usize,
+    data: *const u8,
+    data_len: usize,
+    id: *const u8,
+    id_len: usize,
+    flags: u8,
+    retry: u32,
+    out: *mut u8,
+    out_cap: usize,
+) -> usize {
+    if data.is_null() || out.is_null() {
+        return 0;
+    }
+    // A PRESENT but empty event/id is valid (emits the line) — only a null
+    // pointer with its flag set is malformed (would be UB to slice).
+    if (flags & 1 != 0 && event.is_null()) || (flags & 2 != 0 && id.is_null()) {
+        return 0;
+    }
+    panic_guard(
+        || -> Option<usize> {
+            let data_bytes = slice::from_raw_parts(data, data_len);
+            let output = slice::from_raw_parts_mut(out, out_cap);
+            let event_opt = if flags & 1 != 0 {
+                Some(std::str::from_utf8(slice::from_raw_parts(event, event_len)).ok()?)
+            } else {
+                None
+            };
+            let id_opt = if flags & 2 != 0 {
+                Some(std::str::from_utf8(slice::from_raw_parts(id, id_len)).ok()?)
+            } else {
+                None
+            };
+            let retry_opt = if flags & 4 != 0 {
+                Some(u64::from(retry))
+            } else {
+                None
+            };
+            match crate::payload::sse::encode_event_into_slice(
+                event_opt, data_bytes, id_opt, retry_opt, output,
+            ) {
+                Ok(w) => Some(w),
+                // Too-small buffer: return the exact required size so the JS
+                // wrapper allocates ONCE and retries (needed-size convention);
+                // 0 stays a real error (invalid UTF-8 in event/id above).
+                Err(_) => Some(crate::payload::sse::encode_event_size(
+                    event_opt, data_bytes, id_opt, retry_opt,
+                )),
+            }
+        },
+        None,
+    )
+    .unwrap_or(0)
+}

package/rust/ffi/probe.rs

@@ -0,0 +1,60 @@
+// rust/ffi/probe.rs — diagnostic C-ABI probes (bench-only, NOT in the ffi.ts surface).
+//
+// Used ONLY by bench/ffi-margin.ts to isolate the fixed per-call FFI cost into
+// its components: the bare trampoline (noop), scalar-arg/return conversion
+// (echo_usize, which can be bound with either `usize` or `u64_fast` to measure
+// BigInt boxing in isolation), TypedArray-view→pointer resolution
+// (echo_view), and `cstring`-ARG transcoding (echo_cstr — the engine encodes
+// the JS string to a call-scoped NUL-terminated buffer; the callee borrows it
+// via `CStr::from_ptr`, never dereferencing beyond NUL). They are trivial,
+// non-fallible, allocate nothing, and are NOT part of the shipped
+// `src/native/ffi.ts` dlopen map, so the bind-time self-test does not cover
+// them. The `ffi_probe_*` prefix (NOT `castrum_*`) keeps them out of the
+// shipped-symbol namespace so the source-level symbol-parity guard
+// (test/unit/features/ffi-symbol-parity.test.ts) stays meaningful.
+
+use std::slice;
+
+/// Bare C-ABI trampoline floor: does nothing, returns nothing.
+#[no_mangle]
+pub extern "C" fn ffi_probe_noop() {}
+
+/// Scalar pass-through: returns `v` unchanged. Measures scalar-arg + return
+/// conversion only (bind with `usize` vs `u64_fast` to isolate BigInt boxing).
+#[no_mangle]
+pub extern "C" fn ffi_probe_echo_usize(v: usize) -> usize {
+    v
+}
+
+/// View pass-through: returns the byte length of the `(ptr, len)` pair.
+/// Measures TypedArray-view→pointer resolution + (ptr,len) arg conversion.
+///
+/// # Safety
+/// `data` must be valid for reads of `len` bytes (the pointer is only used to
+/// form a slice whose length we return — never dereferenced).
+#[no_mangle]
+pub unsafe extern "C" fn ffi_probe_echo_view(data: *const u8, len: usize) -> usize {
+    if data.is_null() && len != 0 {
+        return 0;
+    }
+    let _ = slice::from_raw_parts(data, len);
+    len
+}
+
+/// `cstring`-ARG pass-through: returns the byte length of the NUL-terminated
+/// C string the engine produced by transcoding a JS string arg. Measures the
+/// engine-side JS-string→UTF-8 transcode + call-scoped buffer + callee
+/// `CStr::from_ptr` borrow — the cost a `'cstring'` input arg adds compared
+/// with a JS-side `encoder.encode` + `(ptr,len)` pair. The pointer is only
+/// used to form a slice whose length we return — never dereferenced beyond
+/// NUL.
+///
+/// # Safety
+/// `data` must be a valid NUL-terminated C string for reads up to its terminator.
+#[no_mangle]
+pub unsafe extern "C" fn ffi_probe_echo_cstr(data: *const std::os::raw::c_char) -> usize {
+    if data.is_null() {
+        return 0;
+    }
+    std::ffi::CStr::from_ptr(data).to_bytes().len()
+}

package/rust/ffi/rate_limit.rs

@@ -0,0 +1,77 @@
+// rust/ffi/rate_limit.rs — rate-limiter C-ABI exports.
+//
+// Both entries check a limit via the opaque `RateLimiter` handle; one hashes a
+// `cstring` key in-engine, the other takes a pre-hashed i64 key. The packed
+// verdict is written by the shared `write_rate_check` helper in `util.rs`.
+
+use super::util::{panic_guard, write_rate_check};
+
+/// RateLimiter: check a rate limit for a STRING key (hashed internally) at
+/// `now_ms` via its opaque inner handle. Writes packed `[u8 allowed][u32
+/// remaining LE][i64 reset_ms LE]` (13 bytes); needed-size convention; 0 =
+/// null handle (real error).
+///
+/// `key` is a `bun:ffi` `cstring` ARG — the engine transcodes the JS rate-limit
+/// key in-engine (JS does zero encode; the callee borrows via `CStr::from_ptr`).
+/// Intended keys are IPs / route identifiers (text, no NUL); a key containing a
+/// NUL would be truncated before hashing.
+///
+/// # Safety
+/// `inner` must be a valid `RateLimiter` pointer from `inner_ptr()`, alive for
+/// the call; `key` must be a valid NUL-terminated C string; `out` for writes up
+/// to `out_cap`.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_rate_limiter_check(
+    inner: usize,
+    key: *const std::os::raw::c_char,
+    now_ms: i64,
+    out: *mut u8,
+    out_cap: usize,
+) -> usize {
+    if inner == 0 || key.is_null() || out.is_null() {
+        return 0;
+    }
+    let k = std::ffi::CStr::from_ptr(key).to_bytes();
+    let hashed = crate::crypto::hashing::fast_hash_bytes(k);
+    let (allowed, remaining, reset_ms) = panic_guard(
+        || unsafe {
+            crate::ingress::rate_limit::rate_limiter_check_core(
+                inner as *const crate::ingress::rate_limit::RateLimiter,
+                hashed,
+                now_ms as u64,
+            )
+        },
+        (false, 0, 0),
+    );
+    write_rate_check(allowed, remaining, reset_ms, out, out_cap)
+}
+
+/// RateLimiter: check a rate limit for a PRE-HASHED i64 key at `now_ms` via its
+/// opaque inner handle (packed `[u8 allowed][u32 remaining LE][i64 reset_ms LE]`).
+///
+/// # Safety
+/// `inner` must be a valid `RateLimiter` pointer from `inner_ptr()`, alive for
+/// the call; `out` for writes up to `out_cap`.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_rate_limiter_check_key(
+    inner: usize,
+    key: i64,
+    now_ms: i64,
+    out: *mut u8,
+    out_cap: usize,
+) -> usize {
+    if inner == 0 || out.is_null() {
+        return 0;
+    }
+    let (allowed, remaining, reset_ms) = panic_guard(
+        || unsafe {
+            crate::ingress::rate_limit::rate_limiter_check_core(
+                inner as *const crate::ingress::rate_limit::RateLimiter,
+                key as u64,
+                now_ms as u64,
+            )
+        },
+        (false, 0, 0),
+    );
+    write_rate_check(allowed, remaining, reset_ms, out, out_cap)
+}

package/rust/ffi/route.rs

@@ -0,0 +1,85 @@
+// rust/ffi/route.rs — per-route native stack C-ABI exports (`castrum_route_*`).
+//
+// The live external wire consumed by `@ignex/native` (`createNativeRoute` →
+// `route-wire.ts` v3): a route descriptor compiles ONCE into a pre-baked
+// `NativeRoute` (rust/ingress/native_route.rs), then each request packs a tiny
+// frame and gets a packed verdict in one call. The handle is an owned
+// `Box<NativeRoute>` (opaque u64); `route_run` follows the needed-size
+// convention (`0` = real error, `> out_cap` = exact required size) so the JS
+// wrapper allocates once and retries at most once. All three are `panic_guard`ed
+// — a panic must never unwind through the C ABI.
+
+use std::slice;
+
+use super::util::panic_guard;
+
+/// Compile a route descriptor into an opaque handle (`0` = failure / null
+/// input / panic). The handle is an owned `Box<NativeRoute>`; release it with
+/// {@link castrum_route_destroy}.
+///
+/// # Safety
+/// `desc` must be valid for reads of `desc_len` bytes.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_route_compile(desc: *const u8, desc_len: usize) -> u64 {
+    if desc.is_null() {
+        return 0;
+    }
+    let bytes = slice::from_raw_parts(desc, desc_len);
+    panic_guard(
+        || match crate::ingress::NativeRoute::compile(bytes) {
+            Ok(route) => Box::into_raw(Box::new(route)) as u64,
+            Err(_) => 0,
+        },
+        0,
+    )
+}
+
+/// Run a compiled route on one request frame, writing the packed verdict into
+/// `out`. Returns bytes written (`0` = real error / malformed frame / panic;
+/// `> out_cap` = the EXACT required size — allocate once and retry).
+///
+/// # Safety
+/// `handle` must be a live handle from {@link castrum_route_compile} (not yet
+/// destroyed); `frame` valid for `frame_len` reads; `out` valid for `out_cap`
+/// writes. The route is immutable (`&self`, no interior mutability), so
+/// concurrent calls from multiple worker threads are safe.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_route_run(
+    handle: u64,
+    frame: *const u8,
+    frame_len: usize,
+    out: *mut u8,
+    out_cap: usize,
+) -> usize {
+    if handle == 0 || frame.is_null() || out.is_null() {
+        return 0;
+    }
+    let route: &crate::ingress::NativeRoute = &*(handle as *const crate::ingress::NativeRoute);
+    let frame_slice = slice::from_raw_parts(frame, frame_len);
+    let out_slice = slice::from_raw_parts_mut(out, out_cap);
+    // Aliasing insurance (mirrors castrum_ingress_handle_packed): a pooled
+    // frame that overlaps `out` must be copied before the shared &/&mut borrow
+    // pair (aliased &/&mut is instant UB). The JS wrapper uses distinct pooled
+    // buffers, so this is a rare defensive copy.
+    let owned_frame;
+    let frame_ref: &[u8] = if crate::util::slices_overlap(frame_slice, out_slice) {
+        owned_frame = frame_slice.to_vec();
+        &owned_frame
+    } else {
+        frame_slice
+    };
+    panic_guard(|| route.run(frame_ref, out_slice).unwrap_or(0), 0)
+}
+
+/// Destroy a compiled route handle (frees the `Box<NativeRoute>`). A null
+/// handle is a no-op; double-destroy is UB and must not be called.
+///
+/// # Safety
+/// `handle` must come from {@link castrum_route_compile} and be destroyed at
+/// most once.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_route_destroy(handle: u64) {
+    if handle != 0 {
+        drop(Box::from_raw(handle as *mut crate::ingress::NativeRoute));
+    }
+}