kobako 0.12.1 → 0.13.0

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

@@ -0,0 +1,276 @@
+//! 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 crate::config::Config;
+use crate::exports::Exports;
+use crate::invocation::Invocation;
+use crate::{ambient, capture, guest_mem};
+use kobako_runtime::error::{Error, SetupError, Trap};
+use kobako_runtime::profile::Profile;
+
+/// 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(|| 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.
+/// 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(
+    store: &mut WtStore<Invocation>,
+    exports: &Exports,
+    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(exports.alloc.as_ref())?;
+    let memory = require_memory(exports)?;
+
+    let ptr = alloc
+        .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(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, envelope.len(), data.len())
+        .map_err(|msg| Trap::Other(msg.to_string()))?;
+    data[range].copy_from_slice(envelope);
+
+    Ok((ptr as i32, len_i32))
+}
+
+/// Build the per-invocation WASI context with stdin carrying every frame
+/// in `frames` (each prefixed by its 4-byte big-endian u32 length —
+/// docs/wire-codec.md § Invocation channels) plus fresh stdout / stderr
+/// pipes, and install it on the invocation's Store. `#eval` passes three
+/// frames (preamble, source, snippets), `#run` passes two (preamble,
+/// snippets — the invocation envelope arrives via linear memory
+/// instead). Each output pipe is sized at `cap + 1` so
+/// `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.
+/// 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: &[&[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| Trap::Other(msg.to_string()))?;
+    }
+
+    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 {
+        stdin_content.extend_from_slice(&(frame.len() as u32).to_be_bytes());
+        stdin_content.extend_from_slice(frame);
+    }
+
+    let stdin_pipe = MemoryInputPipe::new(stdin_content);
+    let stdout_pipe = MemoryOutputPipe::new(capture::pipe_capacity(config.stdout_limit_bytes));
+    let stderr_pipe = MemoryOutputPipe::new(capture::pipe_capacity(config.stderr_limit_bytes));
+
+    let mut builder = WasiCtxBuilder::new();
+    builder.stdin(stdin_pipe);
+    builder.stdout(stdout_pipe.clone());
+    builder.stderr(stderr_pipe.clone());
+    // The requested profile decides the ambient-authority grant: the
+    // hermetic rung denies the preview1 time and entropy imports (see
+    // `ambient`), the permissive rung leaves the live WASI sources.
+    // Filesystem, environment, and network stay absent on both rungs —
+    // the builder grants none unless asked. The exhaustive match makes
+    // a future ladder rung a compile error here, not a silent grant.
+    match config.profile {
+        Profile::Hermetic => {
+            builder.wall_clock(ambient::FrozenWallClock);
+            builder.monotonic_clock(ambient::FrozenMonotonicClock);
+            builder.secure_random(ambient::deterministic_rng());
+        }
+        Profile::Permissive => {}
+    }
+    let wasi = builder.build_p1();
+
+    store
+        .data_mut()
+        .install_wasi(wasi, stdout_pipe, stderr_pipe);
+    Ok(())
+}
+
+/// Invoke `__kobako_take_outcome`, decode the packed `(ptr<<32)|len`
+/// 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(
+    store: &mut WtStore<Invocation>,
+    exports: &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| 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(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| Trap::Other(format!("the Sandbox result is out of bounds: {msg}")))?;
+    Ok(data[range].to_vec())
+}
+
+/// User-facing message for the "Sandbox runtime is missing one of the
+/// internal Kobako hooks" failure mode. Phrased in caller vocabulary —
+/// the underlying ABI symbol names (`__kobako_alloc`, `__kobako_eval`,
+/// `__kobako_take_outcome`) are not actionable to callers, and the
+/// gem itself raises this error so a self-reference like "matches the
+/// kobako gem version" reads as third-person. The actionable
+/// diagnosis is "your data/kobako.wasm is out of sync; rebuild it".
+const SANDBOX_RUNTIME_MISSING_HOOKS: &str = "Sandbox runtime is missing required hooks; \
+     rebuild data/kobako.wasm against the installed version";
+
+/// User-facing message for the "the loaded Wasm module is not a
+/// Kobako-shaped runtime at all" failure mode (no linear memory
+/// export). Same phrasing philosophy as
+/// `SANDBOX_RUNTIME_MISSING_HOOKS`.
+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 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(|| Trap::Other(SANDBOX_RUNTIME_MISSING_HOOKS.to_string()))
+}
+
+#[cfg(test)]
+mod tests {
+    //! Witness the B-54 rung split at the WASI boundary: one probe
+    //! module reads `wasi:clocks` / `wasi:random` through the context
+    //! `install_wasi_frames` builds — frozen under `Hermetic`, live
+    //! under `Permissive`.
+    use wasmtime::{Linker, Module};
+    use wasmtime_wasi::p1;
+
+    use super::*;
+    use crate::cache::shared_engine;
+
+    /// Preview1 probe with one export per ambient source: `clock_ns`
+    /// reads the realtime clock, `random_word` reads eight entropy bytes.
+    const AMBIENT_PROBE_WAT: &str = r#"
+        (module
+          (import "wasi_snapshot_preview1" "clock_time_get"
+            (func $clock (param i32 i64 i32) (result i32)))
+          (import "wasi_snapshot_preview1" "random_get"
+            (func $random (param i32 i32) (result i32)))
+          (memory (export "memory") 1)
+          (func (export "clock_ns") (result i64)
+            (drop (call $clock (i32.const 0) (i64.const 1) (i32.const 0)))
+            (i64.load (i32.const 0)))
+          (func (export "random_word") (result i64)
+            (drop (call $random (i32.const 8) (i32.const 8)))
+            (i64.load (i32.const 8))))
+    "#;
+
+    /// Instantiate the probe over a WASI context built at `profile` and
+    /// return the `(clock, random)` readings it observes.
+    fn probe_ambient(profile: Profile) -> (i64, i64) {
+        let engine = shared_engine().expect("shared engine must be constructible");
+        let config = Config {
+            timeout: None,
+            stdout_limit_bytes: None,
+            stderr_limit_bytes: None,
+            profile,
+        };
+        let mut store = WtStore::new(engine, Invocation::new(None));
+        store.set_epoch_deadline(u64::MAX);
+        install_wasi_frames(&mut store, &config, &[]).expect("WASI context must install");
+
+        let mut linker: Linker<Invocation> = Linker::new(engine);
+        p1::add_to_linker_sync(&mut linker, |state: &mut Invocation| state.wasi_mut())
+            .expect("WASI imports must link");
+        let module = Module::new(engine, AMBIENT_PROBE_WAT).expect("probe module must compile");
+        let instance = linker
+            .instantiate(&mut store, &module)
+            .expect("probe module must instantiate");
+
+        let read = |store: &mut WtStore<Invocation>, name: &str| -> i64 {
+            instance
+                .get_typed_func::<(), i64>(store.as_context_mut(), name)
+                .expect("probe export must resolve")
+                .call(store.as_context_mut(), ())
+                .expect("probe export must run")
+        };
+        let clock = read(&mut store, "clock_ns");
+        let random = read(&mut store, "random_word");
+        (clock, random)
+    }
+
+    #[test]
+    fn hermetic_denies_ambient_time_and_entropy() {
+        let (clock, random) = probe_ambient(Profile::Hermetic);
+        assert_eq!(
+            clock, 0,
+            "a hermetic guest's wasi:clocks must read the Unix epoch, not host time"
+        );
+        assert_eq!(
+            random, 0,
+            "a hermetic guest's wasi:random must yield the constant stream, not host entropy"
+        );
+    }
+
+    #[test]
+    fn permissive_grants_live_ambient_time_and_entropy() {
+        let (clock, random) = probe_ambient(Profile::Permissive);
+        assert!(
+            clock > 0,
+            "a permissive guest's wasi:clocks must read live host time"
+        );
+        assert_ne!(
+            random, 0,
+            "a permissive guest's wasi:random must yield host entropy"
+        );
+    }
+}

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)
 }