kobako 0.3.0 → 0.5.0

data/ext/kobako/src/runtime/dispatch.rs

@@ -0,0 +1,211 @@
+//! Host-side dispatch for the `__kobako_dispatch` import.
+//!
+//! When the guest invokes the wasm import declared in
+//! `wasm/kobako-wasm/src/abi.rs`, wasmtime calls back into the host
+//! through the closure built in `super::Runtime::build`.
+//! That closure delegates here. The dispatcher (docs/behavior.md B-12 / B-13):
+//!
+//!   1. Reads the Request bytes from guest linear memory.
+//!   2. Invokes the Ruby-side dispatch Proc bound via
+//!      `Runtime#on_dispatch=` and recovers Response bytes.
+//!   3. Allocates a guest buffer via `__kobako_alloc(len)` invoked
+//!      through `Caller::get_export`.
+//!   4. Writes the Response bytes into the guest buffer.
+//!   5. Returns packed `(ptr<<32)|len` for the guest to decode.
+//!
+//! Returns 0 on any step failure. `Kobako::Sandbox#initialize` always
+//! installs the dispatch Proc before any invocation, so reaching the
+//! dispatcher with no Proc bound is itself a wire-layer fault; the
+//! guest maps a 0 return to a trap. Failures during normal dispatch
+//! surface as Response.err envelopes from
+//! `Kobako::Transport::Dispatcher.dispatch` itself — they never reach
+//! this 0-return path.
+//!
+//! ## Why this module writes to `stderr`
+//!
+//! This file is the one place in `ext/` that deliberately prints
+//! through `eprintln!`. The host normally surfaces faults by
+//! raising a `MagnusError` back into Ruby; the dispatcher contract
+//! is the exception — it must return a packed `i64` to the guest
+//! and cannot raise, so a 0 return is the only signal the wasm side
+//! receives. The guest collapses every 0 into the same trap, so the
+//! Ruby host has no way to attribute the failure to a specific step
+//! (missing `memory` export vs. no dispatch Proc bound vs. the Proc
+//! raised vs. `__kobako_alloc` returned 0 vs. `memory.write`
+//! rejected).
+//!
+//! `handle` writes a single `[kobako-dispatch] <reason>` line to
+//! `stderr` on each failure path so operators have a breadcrumb to
+//! correlate the trap with the actual cause. The line is emitted in
+//! both debug and release builds on purpose: dispatcher failures are
+//! wire-layer faults rather than expected error paths (`Kobako::Sandbox`
+//! always installs the Proc, the Proc is contracted never to raise,
+//! etc.), so the "release-build noise" cost is bounded — under normal
+//! operation the line is never written. Operators that need to silence
+//! the stream can redirect the host process's stderr, but the kobako
+//! convention is "ext never logs" plus this single, named exception.
+
+use core::cell::Cell;
+use core::ptr::NonNull;
+
+use magnus::value::{Opaque, ReprValue};
+use magnus::{Error as MagnusError, RString, Ruby, Value};
+use wasmtime::Caller;
+
+use super::invocation::Invocation;
+
+// ============================================================
+// Active-caller pointer for the per-thread Invocation slot (B-24, B-28,
+// SPEC.md Single-Invocation Slot).
+// ============================================================
+//
+// `Runtime#yield_to_active_invocation` (whose body is the
+// `__kobako_yield_to_block` guest export) runs synchronously inside a
+// Ruby Service callback that itself was invoked from inside this
+// dispatcher — at that moment we are several stack frames deep in
+// `try_handle`, with the original `&mut Caller<'_, Invocation>` parked
+// unused on the Rust stack while Ruby code is running. The yield path
+// needs the same Caller to call the guest export, but the Rust borrow
+// type is non-`'static` so it cannot be stored on the `Invocation`
+// struct directly (the `&mut Caller` outlives no struct field — its
+// lifetime ends when `handle` returns to wasmtime).
+//
+// The pointer is therefore erased to `NonNull<()>` and parked in a
+// per-thread slot — the materialised form of the SPEC.md
+// "Single-Invocation Slot" invariant. The single-threaded wasm
+// execution per Sandbox (B-22) plus the LIFO re-entry shape of nested
+// dispatch frames (B-28) ensures no aliasing across threads or across
+// frames; the recovery invariant lives at `current_caller`. The
+// pointer is set on entry to `handle` and restored to the outer
+// frame's value on every exit through a drop guard.
+
+thread_local! {
+    static ACTIVE_CALLER: Cell<Option<NonNull<()>>> = const { Cell::new(None) };
+}
+
+/// RAII guard that saves the previous `ACTIVE_CALLER` value on
+/// installation and restores it on drop. Nested `__kobako_dispatch`
+/// frames stack within one Invocation (B-28) — the inner frame's `set`
+/// swaps in its own pointer while remembering the outer's; drop
+/// restores the outer so its continuation (e.g. iterating over another
+/// guest block) still finds a live caller.
+pub(crate) struct CallerGuard {
+    previous: Option<NonNull<()>>,
+}
+
+impl CallerGuard {
+    fn set(ptr: NonNull<()>) -> Self {
+        let previous = ACTIVE_CALLER.with(|c| c.replace(Some(ptr)));
+        Self { previous }
+    }
+}
+
+impl Drop for CallerGuard {
+    fn drop(&mut self) {
+        ACTIVE_CALLER.with(|c| c.set(self.previous));
+    }
+}
+
+/// Recover the active `&mut Caller<'_, Invocation>` set by the
+/// enclosing `handle` frame. Returns `None` when no dispatch frame is
+/// active on this thread.
+///
+/// # Safety
+///
+/// The returned reference aliases the original `&mut Caller` borrow
+/// held on the Rust stack inside `handle`'s enclosing frame. The
+/// original borrow is logically inactive while Ruby code is running
+/// (it is parked on the stack between `invoke_on_dispatch` and the
+/// eventual `funcall` return), and the SPEC.md Single-Invocation Slot
+/// invariant (one Invocation per OS thread for the duration of any
+/// invocation) guarantees no other Rust frame can observe it. Callers
+/// must not retain the returned `&mut` past the synchronous Ruby
+/// callback that requested it — i.e. only use it inside one short
+/// magnus method body and let the borrow end before the method returns.
+pub(crate) fn current_caller<'a>() -> Option<&'a mut Caller<'a, Invocation>> {
+    let raw: NonNull<()> = ACTIVE_CALLER.with(|c| c.get())?;
+    // SAFETY: see item doc.
+    Some(unsafe { &mut *raw.as_ptr().cast::<Caller<'a, Invocation>>() })
+}
+
+/// Drive a single `__kobako_dispatch` invocation end-to-end. Entry point
+/// from the wasmtime closure built in `super::Runtime::build`.
+///
+/// Returns the packed `(ptr<<32)|len` u64 on success, 0 on any
+/// wire-layer fault. Failure paths log a `[kobako-dispatch]` line to
+/// `stderr` so operators have a breadcrumb when the guest sees a 0
+/// return and traps. The bound dispatch Proc is contracted never to
+/// raise (it folds Service exceptions into Response.err envelopes),
+/// so reaching the failure path is always a wiring bug or wire-layer
+/// fault rather than an expected path.
+pub(crate) fn handle(caller: &mut Caller<'_, Invocation>, req_ptr: i32, req_len: i32) -> i64 {
+    // SAFETY: lifetime erased to `NonNull<()>` per the module's
+    // Invocation-slot doc. The pointer is restored by `_caller_guard`
+    // before this function returns, and only
+    // `Runtime#yield_to_active_invocation` (running inside a Ruby
+    // callback we are about to invoke) reads it through `current_caller`.
+    let ptr: NonNull<()> = NonNull::from(&mut *caller).cast();
+    let _caller_guard = CallerGuard::set(ptr);
+
+    match try_handle(caller, req_ptr, req_len) {
+        Ok(packed) => packed,
+        Err(reason) => {
+            eprintln!("[kobako-dispatch] {}", reason);
+            0
+        }
+    }
+}
+
+/// Result-returning core of `handle`. Pulled out so each early
+/// failure path carries a diagnostic string instead of an opaque 0.
+fn try_handle(
+    caller: &mut Caller<'_, Invocation>,
+    req_ptr: i32,
+    req_len: i32,
+) -> Result<i64, &'static str> {
+    let req_bytes = super::guest_mem::read(caller, req_ptr, req_len)?;
+
+    // `Kobako::Sandbox` always installs the dispatch Proc before
+    // invoking the runtime, so reaching this branch indicates a misuse
+    // rather than a normal control path.
+    let on_dispatch = caller
+        .data()
+        .on_dispatch()
+        .ok_or("a Sandbox callback fired outside an active Sandbox#run — please report this as a kobako bug")?;
+
+    let resp_bytes = invoke_on_dispatch(on_dispatch, &req_bytes).map_err(|_| {
+        "a Sandbox callback raised an exception instead of returning a fault — please report this as a kobako bug"
+    })?;
+
+    write_response(caller, &resp_bytes)
+}
+
+/// Invoke the Ruby-side dispatch +Proc+ with the request bytes and return
+/// the encoded Response bytes. The Proc is contracted to fold every
+/// dispatch failure into a +Response.err+ envelope (see
+/// `Kobako::Transport::Dispatcher.dispatch`), so reaching the error
+/// branch is itself a wire-layer fault rather than a normal control path.
+fn invoke_on_dispatch(
+    on_dispatch: Opaque<Value>,
+    req_bytes: &[u8],
+) -> Result<Vec<u8>, MagnusError> {
+    // The wasmtime callback runs on the same Ruby thread that called the
+    // active Sandbox invocation (#eval or #run) — the invariant SPEC
+    // Implementation Standards Architecture pins for the host gem — so
+    // `Ruby::get()` is always available here. Panicking with `expect`
+    // localises the violation rather than letting a nonsense error
+    // propagate.
+    let ruby = Ruby::get().expect("Ruby handle unavailable in __kobako_dispatch");
+    let proc_value: Value = ruby.get_inner(on_dispatch);
+    let req_str = ruby.str_from_slice(req_bytes);
+    let resp: RString = proc_value.funcall("call", (req_str,))?;
+    Ok(super::rstring_to_vec(resp))
+}
+
+/// Allocate a guest-side buffer and copy the response bytes into it via
+/// `super::guest_mem::alloc_and_write`, returning the packed
+/// `(ptr<<32)|len` u64 the guest's `__kobako_dispatch` import expects.
+fn write_response(caller: &mut Caller<'_, Invocation>, bytes: &[u8]) -> Result<i64, &'static str> {
+    let ptr = super::guest_mem::alloc_and_write(caller, bytes)?;
+    Ok(((ptr as i64) << 32) | (bytes.len() as i64))
+}

data/ext/kobako/src/runtime/exports.rs

@@ -0,0 +1,51 @@
+//! Cached wasmtime export handles for the host-driven ABI surface.
+//!
+//! `Runtime::from_path` resolves the three docs/wire-codec.md ABI exports
+//! the run path drives (`__kobako_eval` / `__kobako_run` /
+//! `__kobako_take_outcome`) once at construction and stores their typed
+//! handles here, so each `#eval` / `#run` calls a cached handle rather than
+//! re-resolving the export by name. Distinct from `super::cache` (the
+//! process-wide Engine / Module cache): this caches *which guest function
+//! to call*, per `Runtime`.
+//!
+//! `__kobako_alloc` is deliberately absent — only `super::dispatch` calls
+//! it, and it does so through `Caller::get_export` on the wasmtime side.
+
+use wasmtime::{AsContextMut, Instance as WtInstance, TypedFunc};
+
+use super::invocation::StoreCell;
+
+/// The cached host-driven export handles. Each is `Option` because test
+/// fixtures (a minimal "ping" module) need not provide them; real
+/// `kobako.wasm` always does, and the run-path methods raise a Ruby
+/// `Kobako::TrapError` (via `require_export`) when a handle is `None`.
+pub(crate) struct Exports {
+    pub(crate) eval: Option<TypedFunc<(), ()>>,
+    pub(crate) run: Option<TypedFunc<(i32, i32), ()>>,
+    pub(crate) take_outcome: Option<TypedFunc<(), u64>>,
+}
+
+impl Exports {
+    /// Best-effort lookup of the three host-driven exports against a
+    /// freshly instantiated module. Missing exports are not an error here
+    /// (the test fixture is a bare module); the host enforces presence at
+    /// invocation time. Only the SPEC ABI shapes are accepted —
+    /// `__kobako_eval` is `() -> ()`, `__kobako_run` is
+    /// `(env_ptr, env_len) -> ()`, `__kobako_take_outcome` is `() -> u64`
+    /// (docs/wire-codec.md § ABI Signatures).
+    pub(crate) fn resolve(instance: &WtInstance, store: &StoreCell) -> Self {
+        let mut store_ref = store.borrow_mut();
+        let mut ctx = store_ref.as_context_mut();
+        Self {
+            eval: instance
+                .get_typed_func::<(), ()>(&mut ctx, "__kobako_eval")
+                .ok(),
+            run: instance
+                .get_typed_func::<(i32, i32), ()>(&mut ctx, "__kobako_run")
+                .ok(),
+            take_outcome: instance
+                .get_typed_func::<(), u64>(&mut ctx, "__kobako_take_outcome")
+                .ok(),
+        }
+    }
+}

data/ext/kobako/src/runtime/guest_mem.rs

@@ -0,0 +1,228 @@
+//! Caller-based guest linear-memory I/O shared by the host-import paths.
+//!
+//! Both directions of a host↔guest buffer handoff that run *inside* a wasm
+//! callback frame go through here: writing the transport Response back
+//! (`super::dispatch`) and shipping block-yield args into the guest
+//! (`drive_yield`, below) performed the same `__kobako_alloc` +
+//! bounds-check + `memory.write` dance with only the diagnostic strings
+//! differing. The Store-based write path (`Runtime::write_envelope`) is a
+//! separate beast — it holds the cached `Store`, not a `Caller` — and stays
+//! in `runtime.rs`.
+
+use wasmtime::{Caller, Extern, Memory};
+
+use super::invocation::Invocation;
+
+/// User-facing reason when a required guest export (the allocation or
+/// block-yield hook) is absent or has the wrong signature — the loaded
+/// `data/kobako.wasm` does not match the installed gem. Phrased in caller
+/// vocabulary: the underlying hook symbol names are not actionable, and
+/// the actionable fix is to rebuild the runtime.
+const RUNTIME_INCOMPATIBLE: &str =
+    "the Sandbox runtime is incompatible; rebuild data/kobako.wasm against the installed version";
+
+/// Resolve the guest's exported linear `memory`. The lookup shape (and its
+/// diagnostic) is shared by every Caller-based path here — the write side
+/// (`alloc_and_write`), the read side (`read`), and the yield round-trip
+/// (`drive_yield`) — so the "no linear memory" reason lives in one place.
+/// `read` maps the `Err` to its own `None` outcome via `.ok()`.
+fn memory_export(caller: &mut Caller<'_, Invocation>) -> Result<Memory, &'static str> {
+    match caller.get_export("memory") {
+        Some(Extern::Memory(m)) => Ok(m),
+        _ => Err("the loaded Wasm module is not a Kobako-compatible runtime"),
+    }
+}
+
+/// Allocate `bytes.len()` bytes in guest memory via `__kobako_alloc` and
+/// copy `bytes` in. Returns the guest pointer. Every failure path carries a
+/// `&'static str` reason so the caller can surface a diagnostic rather than
+/// a silent fault.
+pub(super) fn alloc_and_write(
+    caller: &mut Caller<'_, Invocation>,
+    bytes: &[u8],
+) -> Result<u32, &'static str> {
+    let alloc = match caller.get_export("__kobako_alloc") {
+        Some(Extern::Func(f)) => f
+            .typed::<i32, i32>(&*caller)
+            .map_err(|_| RUNTIME_INCOMPATIBLE)?,
+        _ => return Err(RUNTIME_INCOMPATIBLE),
+    };
+    let len = checked_payload_len(bytes.len())?;
+    let ptr = alloc
+        .call(&mut *caller, len)
+        .map_err(|_| "the Sandbox trapped while allocating memory for the request")?;
+    if ptr == 0 {
+        return Err("the Sandbox ran out of memory while preparing the request");
+    }
+
+    let mem = memory_export(caller)?;
+    mem.write(&mut *caller, ptr as usize, bytes)
+        .map_err(|_| "could not write the request into the Sandbox's memory")?;
+    Ok(ptr as u32)
+}
+
+/// Copy `[ptr, ptr + len)` out of the guest's linear memory as seen from
+/// `caller`. Each failure carries a `&'static str` reason — matching the
+/// other Caller-based ops here — so the caller surfaces a specific
+/// diagnostic instead of a lumped one; a guest-claimed length past the
+/// 16 MiB cap is a wire violation that names the cap (the caller walks
+/// the trap path on any `Err`).
+pub(super) fn read(
+    caller: &mut Caller<'_, Invocation>,
+    ptr: i32,
+    len: i32,
+) -> Result<Vec<u8>, &'static str> {
+    let len = usize::try_from(len).map_err(|_| "the Sandbox produced a negative request length")?;
+    if len > MAX_DISPATCH_PAYLOAD {
+        return Err("request payload exceeds the 16 MiB limit");
+    }
+    let mem = memory_export(caller)?;
+    let data = mem.data(&caller);
+    let start =
+        usize::try_from(ptr).map_err(|_| "the Sandbox produced a negative request pointer")?;
+    let end = start
+        .checked_add(len)
+        .ok_or("the Sandbox produced an out-of-range request")?;
+    data.get(start..end)
+        .map(|s| s.to_vec())
+        .ok_or("the Sandbox produced an out-of-bounds request")
+}
+
+/// Single-dispatch payload cap: 16 MiB in either direction
+/// (SPEC.md § Wire Codec; docs/wire-codec.md § ABI). A host↔guest
+/// transfer larger than this is a wire violation — the Host Gem walks
+/// the trap path rather than allocate or copy the buffer. Held as a
+/// constant for now; a future SPEC anchor may let the Host App raise it.
+pub(super) const MAX_DISPATCH_PAYLOAD: usize = 16 * 1024 * 1024;
+
+/// Validate a payload length against `MAX_DISPATCH_PAYLOAD` and narrow it
+/// to `i32` — the signed wasm ABI width for the guest buffer parameters.
+/// Every host *write* boundary (`alloc_and_write`, `drive_yield`,
+/// `Runtime::write_envelope`) routes its length through here so the
+/// wire-violation reason is uniform; the *read* boundaries compare
+/// against `MAX_DISPATCH_PAYLOAD` directly.
+pub(super) fn checked_payload_len(len: usize) -> Result<i32, &'static str> {
+    if len > MAX_DISPATCH_PAYLOAD {
+        return Err("payload exceeds the 16 MiB limit");
+    }
+    // The cap above sits below `i32::MAX`, so this conversion cannot wrap.
+    i32::try_from(len).map_err(|_| "payload exceeds the 16 MiB limit")
+}
+
+/// Compute the half-open range `[ptr, ptr + len)` for a guest linear-memory
+/// copy, validating that the arithmetic does not overflow and the range
+/// fits inside `mem_size`. Shared by `Runtime::write_envelope` (write side)
+/// and `Runtime::fetch_outcome_bytes` (read side).
+pub(super) fn guest_buffer_range(
+    ptr: usize,
+    len: usize,
+    mem_size: usize,
+) -> Result<core::ops::Range<usize>, &'static str> {
+    let end = ptr.checked_add(len).ok_or("ptr + len overflow")?;
+    if end > mem_size {
+        return Err("range exceeds Sandbox memory size");
+    }
+    Ok(ptr..end)
+}
+
+/// Unpack the `(ptr, len)` u64 returned by `__kobako_take_outcome`:
+/// high 32 bits = ptr, low 32 bits = len. Mirrors the guest-side
+/// `crate::abi::unpack_u64` in `wasm/kobako-wasm/src/abi.rs`.
+pub(super) fn unpack_outcome_packed(packed: u64) -> (usize, usize) {
+    let ptr = (packed >> 32) as u32 as usize;
+    let len = packed as u32 as usize;
+    (ptr, len)
+}
+
+/// Allocate `args.len()` bytes in guest memory, copy the args payload in,
+/// call `__kobako_yield_to_block(ptr, len)`, then read the response slice
+/// the guest produced and return it. Mirrors `dispatch::write_response`'s
+/// allocator dance but in the opposite direction — the host is the
+/// *initiator* of this round-trip, not the responder.
+pub(super) fn drive_yield(
+    caller: &mut Caller<'_, Invocation>,
+    args: &[u8],
+) -> Result<Vec<u8>, &'static str> {
+    let len_i32 = checked_payload_len(args.len())?;
+    let req_ptr = alloc_and_write(caller, args)? as i32;
+
+    let yield_fn = match caller.get_export("__kobako_yield_to_block") {
+        Some(Extern::Func(f)) => f
+            .typed::<(i32, i32), u64>(&*caller)
+            .map_err(|_| RUNTIME_INCOMPATIBLE)?,
+        _ => return Err(RUNTIME_INCOMPATIBLE),
+    };
+    let packed = yield_fn
+        .call(&mut *caller, (req_ptr, len_i32))
+        .map_err(|_| "the Sandbox trapped while invoking a block")?;
+    let (resp_ptr, resp_len) = unpack_outcome_packed(packed);
+    if resp_len == 0 {
+        return Err("the Sandbox returned an empty block result");
+    }
+    if resp_len > MAX_DISPATCH_PAYLOAD {
+        return Err("block result payload exceeds the 16 MiB limit");
+    }
+
+    let mem = memory_export(caller)?;
+    let data = mem.data(&caller);
+    let range = guest_buffer_range(resp_ptr, resp_len, data.len())
+        .map_err(|_| "the Sandbox returned an out-of-bounds block result")?;
+    Ok(data[range].to_vec())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        checked_payload_len, guest_buffer_range, unpack_outcome_packed, MAX_DISPATCH_PAYLOAD,
+    };
+
+    #[test]
+    fn checked_payload_len_accepts_zero_and_the_cap() {
+        assert_eq!(checked_payload_len(0), Ok(0));
+        assert_eq!(
+            checked_payload_len(MAX_DISPATCH_PAYLOAD),
+            Ok(MAX_DISPATCH_PAYLOAD as i32)
+        );
+    }
+
+    #[test]
+    fn checked_payload_len_rejects_past_the_cap() {
+        assert!(checked_payload_len(MAX_DISPATCH_PAYLOAD + 1).is_err());
+        assert!(checked_payload_len(usize::MAX).is_err());
+    }
+
+    #[test]
+    fn guest_buffer_range_returns_half_open_range() {
+        assert_eq!(guest_buffer_range(10, 5, 100), Ok(10..15));
+    }
+
+    #[test]
+    fn guest_buffer_range_accepts_zero_length_at_any_in_bounds_ptr() {
+        assert_eq!(guest_buffer_range(0, 0, 0), Ok(0..0));
+        assert_eq!(guest_buffer_range(42, 0, 100), Ok(42..42));
+    }
+
+    #[test]
+    fn guest_buffer_range_rejects_ptr_plus_len_overflow() {
+        assert!(guest_buffer_range(usize::MAX, 1, usize::MAX).is_err());
+    }
+
+    #[test]
+    fn guest_buffer_range_rejects_end_past_memory() {
+        assert!(guest_buffer_range(10, 100, 50).is_err());
+        assert_eq!(guest_buffer_range(0, 50, 50), Ok(0..50));
+    }
+
+    #[test]
+    fn unpack_outcome_packed_extracts_high_ptr_low_len() {
+        assert_eq!(
+            unpack_outcome_packed(0xAABB_CCDD_1122_3344),
+            (0xAABB_CCDD, 0x1122_3344)
+        );
+    }
+
+    #[test]
+    fn unpack_outcome_packed_zero_decodes_to_zero_pair() {
+        assert_eq!(unpack_outcome_packed(0), (0, 0));
+    }
+}