kobako 0.12.1 → 0.12.2

data/{ext/kobako/src/runtime → crates/kobako-wasmtime/src}/frames.rs

@@ -1,64 +1,60 @@
-//! Per-invocation byte-shuttle between Ruby and guest linear memory: it
-//! resolves the required `memory` / ABI-export handles, writes the `#run`
-//! envelope into a freshly allocated guest buffer, builds the stdin frame
-//! stream plus stdout / stderr capture pipes for the WASI context, and
-//! reads the OUTCOME_BUFFER back out. The ext owns no wire codec — these
-//! helpers move raw bytes; Ruby decodes them.
-
-use magnus::{Error as MagnusError, RString, Ruby};
+//! Per-invocation byte-shuttle between the host and guest linear memory:
+//! it resolves the required `memory` / ABI-export handles, writes the
+//! `#run` envelope into a freshly allocated guest buffer, builds the
+//! stdin frame stream plus stdout / stderr capture pipes for the WASI
+//! context, and reads the OUTCOME_BUFFER back out. The driver owns no
+//! wire codec — these helpers move raw bytes; the frontend decodes them.
+
 use wasmtime::{AsContextMut, Memory, Store as WtStore, TypedFunc};
 use wasmtime_wasi::p2::pipe::{MemoryInputPipe, MemoryOutputPipe};
 use wasmtime_wasi::WasiCtxBuilder;
 
-use super::config::Config;
-use super::exports::Exports;
-use super::invocation::Invocation;
-use super::rstring_to_vec;
-use super::{ambient, capture, errors, guest_mem};
-
-/// Return the resolved `memory` export handle, or raise
-/// `Kobako::TrapError` when the loaded module exports no linear
-/// memory — the "not a Kobako-shaped runtime" failure mode
-/// (`SANDBOX_RUNTIME_NOT_KOBAKO`).
-fn require_memory(ruby: &Ruby, exports: &Exports) -> Result<Memory, MagnusError> {
+use crate::config::Config;
+use crate::exports::Exports;
+use crate::invocation::Invocation;
+use crate::{ambient, capture, guest_mem};
+use kobako_runtime::error::{Error, SetupError, Trap};
+
+/// Return the resolved `memory` export handle, or a `Trap` when the loaded
+/// module exports no linear memory — the "not a Kobako-shaped runtime"
+/// failure mode (`SANDBOX_RUNTIME_NOT_KOBAKO`).
+fn require_memory(exports: &Exports) -> Result<Memory, Trap> {
     exports
         .memory
-        .ok_or_else(|| errors::trap_err(ruby, SANDBOX_RUNTIME_NOT_KOBAKO))
+        .ok_or_else(|| Trap::Other(SANDBOX_RUNTIME_NOT_KOBAKO.to_string()))
 }
 
 /// Allocate a `len`-byte buffer in guest linear memory via
 /// `__kobako_alloc`, copy `envelope` into it, and return `(ptr, len)`
 /// as `i32` values matching the `__kobako_run(env_ptr, env_len)` ABI.
-/// Raises `Kobako::TrapError` when the allocation hook is missing or
-/// itself traps, and `Kobako::SandboxError` when the hook runs but
-/// cannot reserve the buffer (`__kobako_alloc` returns 0) — an
-/// intact runtime, not an engine fault.
+/// Returns a `Trap` when the allocation hook is missing or itself traps
+/// (an engine fault), and a runtime-intact `SetupError` when the hook runs
+/// but cannot reserve the buffer (`__kobako_alloc` returns 0). The ext
+/// boundary maps these to `Kobako::TrapError` / `Kobako::SandboxError`.
 pub(crate) fn write_envelope(
-    ruby: &Ruby,
     store: &mut WtStore<Invocation>,
     exports: &Exports,
-    envelope: RString,
-) -> Result<(i32, i32), MagnusError> {
-    let bytes = rstring_to_vec(envelope);
-    let len_i32 =
-        guest_mem::checked_payload_len(bytes.len()).map_err(|msg| errors::trap_err(ruby, msg))?;
+    envelope: &[u8],
+) -> Result<(i32, i32), Error> {
+    let len_i32 = guest_mem::checked_payload_len(envelope.len())
+        .map_err(|msg| Trap::Other(msg.to_string()))?;
 
-    let alloc = require_export(ruby, exports.alloc.as_ref())?;
-    let memory = require_memory(ruby, exports)?;
+    let alloc = require_export(exports.alloc.as_ref())?;
+    let memory = require_memory(exports)?;
 
     let ptr = alloc
-        .call(store.as_context_mut(), bytes.len() as u32)
-        .map_err(|e| errors::trap_err(ruby, format!("failed to allocate input buffer: {}", e)))?;
+        .call(store.as_context_mut(), envelope.len() as u32)
+        .map_err(|e| Trap::Other(format!("failed to allocate input buffer: {e}")))?;
     if ptr == 0 {
-        return Err(errors::sandbox_err(
-            ruby,
-            "could not allocate input buffer (out of memory)",
-        ));
+        return Err(SetupError::Intact(
+            "could not allocate input buffer (out of memory)".to_string(),
+        )
+        .into());
     }
     let data = memory.data_mut(store.as_context_mut());
-    let range = guest_mem::guest_buffer_range(ptr as usize, bytes.len(), data.len())
-        .map_err(|msg| errors::trap_err(ruby, msg))?;
-    data[range].copy_from_slice(&bytes);
+    let range = guest_mem::guest_buffer_range(ptr as usize, envelope.len(), data.len())
+        .map_err(|msg| Trap::Other(msg.to_string()))?;
+    data[range].copy_from_slice(envelope);
 
     Ok((ptr as i32, len_i32))
 }
@@ -73,24 +69,23 @@ pub(crate) fn write_envelope(
 /// `capture::clip_capture` can distinguish "wrote exactly cap bytes"
 /// from "exceeded cap"; uncapped channels fall back to `usize::MAX` and
 /// rely on `memory_limit` for the real ceiling.
-/// Raises `Kobako::TrapError` when any frame exceeds the 16 MiB cap that
-/// keeps its `u32` length prefix from wrapping.
+/// Returns a `Trap` when any frame exceeds the 16 MiB cap that keeps its
+/// `u32` length prefix from wrapping (boundary → `Kobako::TrapError`).
 pub(crate) fn install_wasi_frames(
     store: &mut WtStore<Invocation>,
     config: &Config,
-    frames: &[Vec<u8>],
-) -> Result<(), MagnusError> {
-    let ruby = Ruby::get().expect("Ruby thread");
+    frames: &[&[u8]],
+) -> Result<(), Trap> {
     // Every frame carries the same 16 MiB cap as the `#run` envelope
     // (`write_envelope`): the length prefix is a `u32`, so a frame past
     // the cap would silently wrap and corrupt the stdin frame stream.
-    for frame in frames {
-        guest_mem::checked_payload_len(frame.len()).map_err(|msg| errors::trap_err(&ruby, msg))?;
+    for &frame in frames {
+        guest_mem::checked_payload_len(frame.len()).map_err(|msg| Trap::Other(msg.to_string()))?;
     }
 
-    let total: usize = frames.iter().map(|f| 4 + f.len()).sum();
+    let total: usize = frames.iter().map(|&f| 4 + f.len()).sum();
     let mut stdin_content: Vec<u8> = Vec::with_capacity(total);
-    for frame in frames {
+    for &frame in frames {
         stdin_content.extend_from_slice(&(frame.len() as u32).to_be_bytes());
         stdin_content.extend_from_slice(frame);
     }
@@ -117,37 +112,31 @@ pub(crate) fn install_wasi_frames(
 }
 
 /// Invoke `__kobako_take_outcome`, decode the packed `(ptr<<32)|len`
-/// u64, and copy the OUTCOME_BUFFER slice out of guest memory. Raises
-/// `Kobako::TrapError` when the export is missing, `len` exceeds the
-/// 16 MiB single-dispatch cap, the `ptr`/`len` arithmetic overflows,
-/// the slice falls outside live memory, or the `memory` export itself
-/// is absent.
+/// u64, and copy the OUTCOME_BUFFER slice out of guest memory. Returns a
+/// `Trap` (boundary → `Kobako::TrapError`) when the export is missing,
+/// `len` exceeds the 16 MiB single-dispatch cap, the `ptr`/`len`
+/// arithmetic overflows, the slice falls outside live memory, or the
+/// `memory` export itself is absent.
 pub(crate) fn fetch_outcome_bytes(
-    ruby: &Ruby,
     store: &mut WtStore<Invocation>,
     exports: &Exports,
-) -> Result<Vec<u8>, MagnusError> {
-    let take = require_export(ruby, exports.take_outcome.as_ref())?;
-    let mem = require_memory(ruby, exports)?;
+) -> Result<Vec<u8>, Trap> {
+    let take = require_export(exports.take_outcome.as_ref())?;
+    let mem = require_memory(exports)?;
 
     let packed = take
         .call(store.as_context_mut(), ())
-        .map_err(|e| errors::trap_err(ruby, format!("failed to read the Sandbox result: {}", e)))?;
+        .map_err(|e| Trap::Other(format!("failed to read the Sandbox result: {e}")))?;
     let (ptr, len) = guest_mem::unpack_outcome_packed(packed);
     if len > guest_mem::MAX_DISPATCH_PAYLOAD {
-        return Err(errors::trap_err(
-            ruby,
-            "result payload exceeds the 16 MiB limit",
+        return Err(Trap::Other(
+            "result payload exceeds the 16 MiB limit".to_string(),
         ));
     }
 
     let data = mem.data(store.as_context_mut());
-    let range = guest_mem::guest_buffer_range(ptr, len, data.len()).map_err(|msg| {
-        errors::trap_err(
-            ruby,
-            format!("the Sandbox result is out of bounds: {}", msg),
-        )
-    })?;
+    let range = guest_mem::guest_buffer_range(ptr, len, data.len())
+        .map_err(|msg| Trap::Other(format!("the Sandbox result is out of bounds: {msg}")))?;
     Ok(data[range].to_vec())
 }
 
@@ -168,21 +157,20 @@ const SANDBOX_RUNTIME_MISSING_HOOKS: &str = "Sandbox runtime is missing required
 const SANDBOX_RUNTIME_NOT_KOBAKO: &str =
     "the loaded Wasm module is not a Kobako-compatible runtime";
 
-/// Return the resolved `TypedFunc` for an ABI export, or raise
-/// `Kobako::TrapError` when the option is `None`. Both run-path
-/// methods (`#eval`, `#run`) plus the `build_snapshot` readout that
-/// drains `OUTCOME_BUFFER` share the same "missing export → Ruby
-/// error" boilerplate; this helper collapses those sites onto one
-/// safe entry. The user-facing message is intentionally export-
-/// agnostic (see `SANDBOX_RUNTIME_MISSING_HOOKS`) — the ABI symbol
-/// name is not actionable to callers, so it is not threaded in.
-pub(crate) fn require_export<'a, Params, Results>(
-    ruby: &Ruby,
-    export: Option<&'a TypedFunc<Params, Results>>,
-) -> Result<&'a TypedFunc<Params, Results>, MagnusError>
+/// Return the resolved `TypedFunc` for an ABI export, or a `Trap`
+/// (boundary → `Kobako::TrapError`) when the option is `None`. Both
+/// run-path methods (`#eval`, `#run`) plus the `build_snapshot` readout
+/// that drains `OUTCOME_BUFFER` share the same "missing export" handling;
+/// this helper collapses those sites onto one safe entry. The user-facing
+/// message is intentionally export-agnostic (see
+/// `SANDBOX_RUNTIME_MISSING_HOOKS`) — the ABI symbol name is not
+/// actionable to callers, so it is not threaded in.
+pub(crate) fn require_export<Params, Results>(
+    export: Option<&TypedFunc<Params, Results>>,
+) -> Result<&TypedFunc<Params, Results>, Trap>
 where
     Params: wasmtime::WasmParams,
     Results: wasmtime::WasmResults,
 {
-    export.ok_or_else(|| errors::trap_err(ruby, SANDBOX_RUNTIME_MISSING_HOOKS))
+    export.ok_or_else(|| Trap::Other(SANDBOX_RUNTIME_MISSING_HOOKS.to_string()))
 }

data/{ext/kobako/src/runtime → crates/kobako-wasmtime/src}/guest_mem.rs

@@ -2,16 +2,39 @@
 //!
 //! 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
+//! (`crate::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`.
+//! differing. The Store-based write path (`frames::write_envelope`) is a
+//! separate beast — it holds the per-invocation `Store`, not a `Caller` —
+//! and stays in `frames`.
 
 use wasmtime::{Caller, Extern, Memory};
 
-use super::invocation::Invocation;
+use crate::invocation::Invocation;
+use kobako_runtime::error::Trap;
+use kobako_runtime::yielder::Yielder;
+
+/// The wasmtime-backed `Yielder` (`kobako_runtime::yielder`): a
+/// frame-scoped wrapper over the dispatch `Caller` that drives a block-yield
+/// round-trip through `drive_yield`. Built per `__kobako_dispatch` frame and
+/// handed to the dispatch handler, so nested dispatch frames each
+/// carry their own and stack on the Rust call stack with no shared slot.
+pub(crate) struct CallerYielder<'a, 'c> {
+    caller: &'a mut Caller<'c, Invocation>,
+}
+
+impl<'a, 'c> CallerYielder<'a, 'c> {
+    pub(crate) fn new(caller: &'a mut Caller<'c, Invocation>) -> Self {
+        Self { caller }
+    }
+}
+
+impl Yielder for CallerYielder<'_, '_> {
+    fn yield_block(&mut self, args: &[u8]) -> Result<Vec<u8>, Trap> {
+        drive_yield(self.caller, args).map_err(|msg| Trap::Other(msg.to_string()))
+    }
+}
 
 /// User-facing reason when a required guest export (the allocation or
 /// block-yield hook) is absent or has the wrong signature — the loaded
@@ -37,7 +60,7 @@ fn memory_export(caller: &mut Caller<'_, Invocation>) -> Result<Memory, &'static
 /// 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(
+pub(crate) fn alloc_and_write(
     caller: &mut Caller<'_, Invocation>,
     bytes: &[u8],
 ) -> Result<u32, &'static str> {
@@ -67,7 +90,7 @@ pub(super) fn alloc_and_write(
 /// 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(
+pub(crate) fn read(
     caller: &mut Caller<'_, Invocation>,
     ptr: i32,
     len: i32,
@@ -93,15 +116,15 @@ pub(super) fn read(
 /// 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;
+pub(crate) 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
+/// `frames::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> {
+pub(crate) fn checked_payload_len(len: usize) -> Result<i32, &'static str> {
     if len > MAX_DISPATCH_PAYLOAD {
         return Err("payload exceeds the 16 MiB limit");
     }
@@ -111,9 +134,9 @@ pub(super) fn checked_payload_len(len: usize) -> Result<i32, &'static str> {
 
 /// 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(
+/// fits inside `mem_size`. Shared by `frames::write_envelope` (write side)
+/// and `frames::fetch_outcome_bytes` (read side).
+pub(crate) fn guest_buffer_range(
     ptr: usize,
     len: usize,
     mem_size: usize,
@@ -128,7 +151,7 @@ pub(super) fn guest_buffer_range(
 /// Unpack the `(ptr, len)` u64 returned by `__kobako_take_outcome`:
 /// high 32 bits = ptr, low 32 bits = len. Mirrors the guest-side
 /// `unpack_u64` in `wasm/kobako-core/src/abi.rs`.
-pub(super) fn unpack_outcome_packed(packed: u64) -> (usize, usize) {
+pub(crate) 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)
@@ -139,7 +162,7 @@ pub(super) fn unpack_outcome_packed(packed: u64) -> (usize, usize) {
 /// 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(
+pub(crate) fn drive_yield(
     caller: &mut Caller<'_, Invocation>,
     args: &[u8],
 ) -> Result<Vec<u8>, &'static str> {

data/{ext/kobako/src/runtime → crates/kobako-wasmtime/src}/instance_pre.rs

@@ -6,23 +6,22 @@
 //! same Guest Binary — both host closures read all their state from
 //! the `Invocation` inside the calling Store, never from the Runtime.
 //! Caching the resolved `InstancePre` per path leaves only the
-//! `instantiate` call itself on the `Runtime.from_path` hot path.
+//! `instantiate` call itself on the `Driver::new` hot path.
 //!
-//! Concurrency: see `super::cache` — under Ruby's GVL the Mutex serves
+//! Concurrency: see `crate::cache` — under Ruby's GVL the Mutex serves
 //! `Sync` bounds rather than real contention.
 
 use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 use std::sync::{Mutex, OnceLock};
 
-use magnus::{Error as MagnusError, Ruby};
 use wasmtime::{Caller, InstancePre, Linker};
 use wasmtime_wasi::p1;
 
-use super::cache::{cached_module, shared_engine};
-use super::errors::setup_err;
-use super::invocation::Invocation;
-use super::{dispatch, trap};
+use crate::cache::{cached_module, shared_engine};
+use crate::invocation::Invocation;
+use crate::{dispatch, trap};
+use kobako_runtime::error::SetupError;
 
 static INSTANCE_PRE_CACHE: OnceLock<Mutex<HashMap<PathBuf, InstancePre<Invocation>>>> =
     OnceLock::new();
@@ -30,8 +29,8 @@ static INSTANCE_PRE_CACHE: OnceLock<Mutex<HashMap<PathBuf, InstancePre<Invocatio
 /// Look up `path` in the per-path `InstancePre` cache, wiring the
 /// Linker and resolving the Module's imports on a miss. Compilation
 /// faults surface through `cached_module`; import-resolution faults
-/// raise `Kobako::SetupError`.
-pub(crate) fn cached_instance_pre(path: &Path) -> Result<InstancePre<Invocation>, MagnusError> {
+/// return a runtime-dead `SetupError` (boundary → `Kobako::SetupError`).
+pub(crate) fn cached_instance_pre(path: &Path) -> Result<InstancePre<Invocation>, SetupError> {
     let cache = INSTANCE_PRE_CACHE.get_or_init(|| Mutex::new(HashMap::new()));
 
     if let Some(pre) = cache
@@ -45,10 +44,9 @@ pub(crate) fn cached_instance_pre(path: &Path) -> Result<InstancePre<Invocation>
 
     let module = cached_module(path)?;
     let linker = build_linker()?;
-    let ruby = Ruby::get().expect("Ruby thread");
     let pre = linker
         .instantiate_pre(&module)
-        .map_err(|e| trap::instantiate_err(&ruby, e))?;
+        .map_err(trap::instantiate_err)?;
     cache
         .lock()
         .expect("instance_pre cache mutex poisoned")
@@ -58,17 +56,16 @@ pub(crate) fn cached_instance_pre(path: &Path) -> Result<InstancePre<Invocation>
 
 /// Build the host-import `Linker` every Guest Binary instantiates
 /// against.
-fn build_linker() -> Result<Linker<Invocation>, MagnusError> {
-    let ruby = Ruby::get().expect("Ruby thread");
+fn build_linker() -> Result<Linker<Invocation>, SetupError> {
     let mut linker: Linker<Invocation> = Linker::new(shared_engine()?);
 
     // Wire the wasmtime-wasi preview1 WASI imports. Routes guest fd 1/2
     // to the MemoryOutputPipes set up before each run via
-    // `Runtime::eval`. The closure pulls a `&mut WasiP1Ctx` out of
+    // `Driver::invoke`. The closure pulls a `&mut WasiP1Ctx` out of
     // Invocation; the panic semantics live inside `Invocation::wasi_mut`
     // so the wiring stays honest about its precondition.
     p1::add_to_linker_sync(&mut linker, |state: &mut Invocation| state.wasi_mut())
-        .map_err(|e| setup_err(&ruby, format!("failed to set up the WASI runtime: {}", e)))?;
+        .map_err(|e| SetupError::Dead(format!("failed to set up the WASI runtime: {e}")))?;
 
     // `__kobako_dispatch` host import. Signature per docs/wire-codec.md
     // § ABI Signatures:
@@ -87,12 +84,7 @@ fn build_linker() -> Result<Linker<Invocation>, MagnusError> {
                 dispatch::handle(&mut caller, req_ptr, req_len)
             },
         )
-        .map_err(|e| {
-            setup_err(
-                &ruby,
-                format!("failed to set up the host callback bridge: {}", e),
-            )
-        })?;
+        .map_err(|e| SetupError::Dead(format!("failed to set up the host callback bridge: {e}")))?;
 
     Ok(linker)
 }