kobako 0.27.0 → 0.29.0

data/crates/kobako-wasmtime/src/guest_mem.rs

@@ -1,130 +1,154 @@
-//! Caller-based guest linear-memory I/O shared by the host-import paths.
+//! Guest linear-memory I/O for the ABI's buffer handoffs, whether the
+//! invocation body drives one through its `Store` or a dispatch or yield
+//! import drives one through its `Caller`. preview1 reads and writes its
+//! arguments through its own `GuestMemory`.
 //!
-//! Both directions of a host↔guest buffer handoff that run *inside* a wasm
-//! callback frame go through here: writing the transport Reply back
-//! (`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 (`frames::write_envelope`) is a
-//! separate beast — it holds the per-invocation `Store`, not a `Caller` —
-//! and stays in `frames`.
+//! The two shared steps answer an error kind, and each caller words it,
+//! because depth decides what the same problem means: before the export
+//! call it is a `Trap` or an intact runtime, inside a callback it is a
+//! wire failure the guest receives.
 
-use wasmtime::{Caller, Extern, Memory};
+use wasmtime::{AsContext, AsContextMut, Caller, Memory};
 
+use crate::exports::{Exports, RUNTIME_INCOMPATIBLE};
 use crate::invocation::Invocation;
-use kobako_runtime::error::Trap;
-use kobako_runtime::yielder::Yielder;
 use kobako_transport::abi::{unpack_ptr_len, MAX_DISPATCH_PAYLOAD};
+use kobako_transport::envelope::Downcall;
 
-/// 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_to_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
-/// `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";
+// The size-limit messages here and in `io` name the cap as 16 MiB, so
+// moving the cap fails the build until they are reworded with it.
+const _: () = assert!(MAX_DISPATCH_PAYLOAD == 16 << 20);
 
 /// User-facing message for the "the loaded Wasm module is not a
-/// Kobako-shaped runtime at all" failure mode — no linear memory export
-/// here, no `memory` module export on the instantiation path in
-/// `frames`. One constant so the two detection sites cannot drift.
+/// Kobako-shaped runtime at all" failure mode, such as an instance with no
+/// `memory` export.
 pub(crate) const SANDBOX_RUNTIME_NOT_KOBAKO: &str =
     "the loaded Wasm module is not a Kobako-compatible runtime";
 
-/// 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(SANDBOX_RUNTIME_NOT_KOBAKO),
-    }
+/// Why a host write into guest memory failed.
+pub(crate) enum WriteError {
+    TooLarge,
+    /// The allocator or the memory is missing or mistyped; carries the
+    /// message for it.
+    Incompatible(&'static str),
+    Trapped(wasmtime::Error),
+    /// The allocator ran and answered 0.
+    OutOfMemory,
+    OutOfBounds,
 }
 
-/// 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.
+/// Why a host read of a guest-named buffer failed.
+pub(crate) enum ReadError {
+    TooLarge,
+    OutOfBounds,
+}
+
+/// Allocate a guest buffer through `__kobako_alloc` and copy `bytes` into
+/// it, answering the buffer's address.
 pub(crate) fn alloc_and_write(
-    caller: &mut Caller<'_, Invocation>,
+    mut ctx: impl AsContextMut,
+    exports: &Exports,
     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())?;
+) -> Result<u32, WriteError> {
+    let len = checked_payload_len(bytes.len()).map_err(|_| WriteError::TooLarge)?;
+    let alloc = exports
+        .alloc
+        .as_ref()
+        .ok_or(WriteError::Incompatible(RUNTIME_INCOMPATIBLE))?;
+    let memory = exports
+        .memory
+        .ok_or(WriteError::Incompatible(SANDBOX_RUNTIME_NOT_KOBAKO))?;
     let ptr = alloc
-        .call(&mut *caller, len)
-        .map_err(|_| "the Sandbox trapped while allocating memory for the request")?;
+        .call(&mut ctx, len as u32)
+        .map_err(WriteError::Trapped)?;
     if ptr == 0 {
-        return Err("the Sandbox ran out of memory while preparing the request");
+        return Err(WriteError::OutOfMemory);
+    }
+    memory
+        .write(&mut ctx, ptr as usize, bytes)
+        .map_err(|_| WriteError::OutOfBounds)?;
+    Ok(ptr)
+}
+
+/// Copy out the buffer the guest names; a length past the 16 MiB cap is
+/// refused before memory is touched.
+pub(crate) fn read_buffer(
+    ctx: impl AsContext,
+    memory: Memory,
+    ptr: usize,
+    len: usize,
+) -> Result<Vec<u8>, ReadError> {
+    if len > MAX_DISPATCH_PAYLOAD {
+        return Err(ReadError::TooLarge);
     }
+    let data = memory.data(&ctx);
+    let range = guest_buffer_range(ptr, len, data.len()).map_err(|_| ReadError::OutOfBounds)?;
+    Ok(data[range].to_vec())
+}
 
-    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)
+/// The handles of the instance a host import runs inside.
+fn callback_exports(caller: &Caller<'_, Invocation>) -> Result<Exports, &'static str> {
+    caller.data().exports().ok_or(SANDBOX_RUNTIME_NOT_KOBAKO)
 }
 
-/// 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(crate) fn read(
+/// Keep a trap the guest raised during a callback into it for the dispatch
+/// import to end the invocation with, and answer the callback's own reason.
+fn keep_trap(
     caller: &mut Caller<'_, Invocation>,
-    ptr: i32,
-    len: i32,
+    trap: wasmtime::Error,
+    reason: &'static str,
+) -> &'static str {
+    caller.data_mut().record_reentry_trap(trap);
+    reason
+}
+
+/// The request the guest hands the upcall import. Its `(ptr, len)` are
+/// guest addresses, so they are read unsigned.
+pub(crate) fn read_request(
+    caller: &mut Caller<'_, Invocation>,
+    req_ptr: i32,
+    req_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 memory = callback_exports(caller)?
+        .memory
+        .ok_or(SANDBOX_RUNTIME_NOT_KOBAKO)?;
+    read_buffer(
+        &*caller,
+        memory,
+        req_ptr as u32 as usize,
+        req_len as u32 as usize,
+    )
+    .map_err(|err| match err {
+        ReadError::TooLarge => "request payload exceeds the 16 MiB limit",
+        ReadError::OutOfBounds => "the Sandbox produced an out-of-bounds request",
+    })
+}
+
+/// Write `bytes` into the guest from inside a callback. A guest that has
+/// already trapped is not called again.
+pub(crate) fn write_from_callback(
+    caller: &mut Caller<'_, Invocation>,
+    bytes: &[u8],
+) -> Result<u32, &'static str> {
+    if caller.data().reentry_trapped() {
+        return Err("the Sandbox already trapped during this invocation");
     }
-    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")
+    let exports = callback_exports(caller)?;
+    alloc_and_write(&mut *caller, &exports, bytes).map_err(|err| match err {
+        WriteError::TooLarge => "payload exceeds the 16 MiB limit",
+        WriteError::Incompatible(message) => message,
+        WriteError::Trapped(trap) => keep_trap(
+            caller,
+            trap,
+            "the Sandbox trapped while allocating memory for the request",
+        ),
+        WriteError::OutOfMemory => "the Sandbox ran out of memory while preparing the request",
+        WriteError::OutOfBounds => "could not write the request into the Sandbox's memory",
+    })
 }
 
-/// 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`,
-/// `frames::write_envelope`) routes its length through here so the
-/// wire-violation reason is uniform; the *read* boundaries compare
-/// against `MAX_DISPATCH_PAYLOAD` directly.
+/// Every host write boundary routes its length through here, so the
+/// wire-violation reason is uniform.
 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");
@@ -133,10 +157,6 @@ pub(crate) fn checked_payload_len(len: usize) -> Result<i32, &'static str> {
     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 `frames::write_envelope` (write side)
-/// and `frames::fetch_outcome_bytes` (read side).
 pub(crate) fn guest_buffer_range(
     ptr: usize,
     len: usize,
@@ -149,53 +169,46 @@ pub(crate) fn guest_buffer_range(
     Ok(ptr..end)
 }
 
-/// The `(ptr, len)` a buffer-returning ABI export answered with, widened
-/// to the `usize` the linear-memory ranges here are computed in.
-pub(crate) fn unpack_outcome_packed(packed: u64) -> (usize, usize) {
+/// The `(ptr, len)` the guest packs for any answer it hands back, the
+/// outcome and a block's result alike.
+pub(crate) fn unpack_guest_buffer(packed: u64) -> (usize, usize) {
     let (ptr, len) = unpack_ptr_len(packed);
     (ptr as usize, len as usize)
 }
 
-/// 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(crate) fn drive_yield(
     caller: &mut Caller<'_, Invocation>,
+    frame: u32,
     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 request = Downcall::Yield {
+        frame,
+        args: args.to_vec(),
+    }
+    .encode();
+    let len_i32 = checked_payload_len(request.len())?;
+    let req_ptr = write_from_callback(caller, &request)? 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 exports = callback_exports(caller)?;
+    let yield_fn = exports.downcall.ok_or(RUNTIME_INCOMPATIBLE)?;
+    let memory = exports.memory.ok_or(SANDBOX_RUNTIME_NOT_KOBAKO)?;
     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 {
+        .map_err(|trap| keep_trap(caller, trap, "the Sandbox trapped while invoking a block"))?;
+    let (reply_ptr, reply_len) = unpack_guest_buffer(packed);
+    if reply_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())
+    read_buffer(&*caller, memory, reply_ptr, reply_len).map_err(|err| match err {
+        ReadError::TooLarge => "block result payload exceeds the 16 MiB limit",
+        ReadError::OutOfBounds => "the Sandbox returned an out-of-bounds block result",
+    })
 }
 
 #[cfg(test)]
 mod tests {
     use super::{
-        checked_payload_len, guest_buffer_range, unpack_outcome_packed, MAX_DISPATCH_PAYLOAD,
+        checked_payload_len, guest_buffer_range, unpack_guest_buffer, MAX_DISPATCH_PAYLOAD,
     };
 
     // @behavior WE-059
@@ -243,16 +256,16 @@ mod tests {
 
     // @behavior WE-001
     #[test]
-    fn unpack_outcome_packed_extracts_high_ptr_low_len() {
+    fn unpack_guest_buffer_extracts_high_ptr_low_len() {
         assert_eq!(
-            unpack_outcome_packed(0xAABB_CCDD_1122_3344),
+            unpack_guest_buffer(0xAABB_CCDD_1122_3344),
             (0xAABB_CCDD, 0x1122_3344)
         );
     }
 
     // @behavior WE-065
     #[test]
-    fn unpack_outcome_packed_zero_decodes_to_zero_pair() {
-        assert_eq!(unpack_outcome_packed(0), (0, 0));
+    fn unpack_guest_buffer_zero_decodes_to_zero_pair() {
+        assert_eq!(unpack_guest_buffer(0), (0, 0));
     }
 }

data/crates/kobako-wasmtime/src/imports.rs

@@ -0,0 +1,46 @@
+//! The host imports a Guest Binary resolves: the WASI preview1 set and
+//! the wire ABI's `__kobako_upcall`.
+//!
+//! Both closures read all their state from the `Invocation` inside the
+//! calling Store, never from a Runtime, so the wiring is the same for
+//! every Sandbox and `crate::instance_pre` can cache what it resolves.
+
+use wasmtime::{Caller, Linker};
+use wasmtime_wasi::p1;
+
+use crate::cache::shared_engine;
+use crate::invocation::Invocation;
+use crate::{dispatch, preview1};
+use kobako_runtime::error::SetupError;
+
+pub(crate) fn linker() -> Result<Linker<Invocation>, SetupError> {
+    let mut linker: Linker<Invocation> = Linker::new(shared_engine()?);
+
+    // Wire the wasmtime-wasi preview1 WASI imports against each
+    // invocation's own `Wasi` context, then answer every call that reads
+    // a descriptor from kobako's own table, which routes guest fd 1/2 to
+    // its capture pipes.
+    p1::add_to_linker_sync(&mut linker, |state: &mut Invocation| {
+        state.wasi_mut().ctx_mut()
+    })
+    .and_then(|_| preview1::shadow(&mut linker))
+    .map_err(|e| SetupError::Dead(format!("failed to set up the WASI runtime: {e}")))?;
+
+    // `__kobako_upcall`, `(ptr: i32, len: i32) -> i64` per
+    // docs/wire/abi.md § ABI Signatures; `dispatch::handle` owns what it
+    // answers.
+    linker
+        .func_wrap(
+            "env",
+            "__kobako_upcall",
+            |mut caller: Caller<'_, Invocation>,
+             req_ptr: i32,
+             req_len: i32|
+             -> wasmtime::Result<i64> {
+                dispatch::handle(&mut caller, req_ptr, req_len)
+            },
+        )
+        .map_err(|e| SetupError::Dead(format!("failed to set up the host callback bridge: {e}")))?;
+
+    Ok(linker)
+}

data/crates/kobako-wasmtime/src/instance_pre.rs

@@ -1,38 +1,35 @@
 //! Per-path cache of pre-instantiated wasmtime artifacts.
 //!
-//! The `Linker` wiring (the WASI preview1 import set plus the
-//! `__kobako_dispatch` host import) and its type-check against the
-//! compiled Module are identical for every `Kobako::Runtime` on the
-//! 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 — together with the ABI
-//! version check it guards (`crate::abi`) — takes both off the
-//! `Driver::new` hot path.
+//! The host imports (`crate::imports`) and their type-check against the
+//! compiled Module are identical for every `Kobako::Runtime` on the same
+//! Guest Binary. Caching the resolved `InstancePre` per path — together
+//! with the ABI version check it guards (`crate::abi`) — takes both off
+//! the `Driver::new` hot path.
 //!
-//! Concurrency: see `crate::cache` — under Ruby's GVL the Mutex serves
-//! `Sync` bounds rather than real contention.
+//! Concurrency: the same as `crate::cache` — the Mutex covers lookup and
+//! insert only, and a concurrent miss builds an equivalent `InstancePre`.
 
 use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 use std::sync::{Mutex, OnceLock};
+use std::time::Duration;
 
-use wasmtime::{Caller, InstancePre, Linker};
-use wasmtime_wasi::p1;
+use wasmtime::InstancePre;
 
-use crate::cache::{cached_module, shared_engine};
+use crate::cache::cached_module;
 use crate::invocation::Invocation;
-use crate::{abi, dispatch, trap};
+use crate::{abi, imports, trap};
 use kobako_runtime::error::SetupError;
 
 static INSTANCE_PRE_CACHE: OnceLock<Mutex<HashMap<PathBuf, InstancePre<Invocation>>>> =
     OnceLock::new();
 
-/// Look up `path` in the per-path `InstancePre` cache, wiring the
-/// Linker, resolving the Module's imports, and verifying the artifact's
-/// ABI version on a miss. Compilation faults surface through
-/// `cached_module`; import-resolution and ABI faults return a
-/// runtime-dead `SetupError` (boundary → `Kobako::SetupError`).
-pub(crate) fn cached_instance_pre(path: &Path) -> Result<InstancePre<Invocation>, SetupError> {
+/// The probe runs only on the first load of a path, so only that load's
+/// `setup_timeout` bounds it; a path already verified is not set up again.
+pub(crate) fn cached_instance_pre(
+    path: &Path,
+    setup_timeout: Option<Duration>,
+) -> Result<InstancePre<Invocation>, SetupError> {
     let cache = INSTANCE_PRE_CACHE.get_or_init(|| Mutex::new(HashMap::new()));
 
     if let Some(pre) = cache
@@ -45,52 +42,16 @@ pub(crate) fn cached_instance_pre(path: &Path) -> Result<InstancePre<Invocation>
     }
 
     let module = cached_module(path)?;
-    let linker = build_linker()?;
+    let linker = imports::linker()?;
     let pre = linker
         .instantiate_pre(&module)
         .map_err(trap::instantiate_err)?;
     // Verify before the insert, so a rejected artifact is never
     // remembered as a usable template.
-    abi::verify(&pre)?;
+    abi::verify(&pre, setup_timeout)?;
     cache
         .lock()
         .expect("instance_pre cache mutex poisoned")
         .insert(path.to_path_buf(), pre.clone());
     Ok(pre)
 }
-
-/// Build the host-import `Linker` every Guest Binary instantiates
-/// against.
-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
-    // `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| SetupError::Dead(format!("failed to set up the WASI runtime: {e}")))?;
-
-    // `__kobako_dispatch` host import. Signature per docs/wire-codec.md
-    // § ABI Signatures:
-    //   (req_ptr: i32, req_len: i32) -> i64
-    // Reads the Call bytes from guest memory and hands them —
-    // undecoded — to the bound `DispatchHandler` (the frontend's
-    // dispatch bridge, e.g. a Ruby Proc), then allocates a guest
-    // buffer through `__kobako_alloc`, writes the handler's Reply
-    // bytes there, and returns the packed `(ptr<<32)|len`. The
-    // dispatcher returns 0 on any wire-layer fault (including no
-    // handler bound); see `dispatch::handle`.
-    linker
-        .func_wrap(
-            "env",
-            "__kobako_dispatch",
-            |mut caller: Caller<'_, Invocation>, req_ptr: i32, req_len: i32| -> i64 {
-                dispatch::handle(&mut caller, req_ptr, req_len)
-            },
-        )
-        .map_err(|e| SetupError::Dead(format!("failed to set up the host callback bridge: {e}")))?;
-
-    Ok(linker)
-}