kobako 0.12.1 → 0.12.2

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

@@ -11,7 +11,7 @@
 /// `cap + 1` (saturated against `usize::MAX`) when a cap is set so the
 /// "wrote exactly cap" and "exceeded cap" cases stay distinguishable;
 /// `usize::MAX` when the channel is uncapped.
-pub(super) fn pipe_capacity(cap: Option<usize>) -> usize {
+pub(crate) fn pipe_capacity(cap: Option<usize>) -> usize {
     match cap {
         Some(c) => c.saturating_add(1),
         None => usize::MAX,
@@ -24,7 +24,7 @@ pub(super) fn pipe_capacity(cap: Option<usize>) -> usize {
 /// `true` only when the snapshot strictly exceeded the cap — this is the
 /// "wrote `cap + 1` bytes into a `cap + 1`-sized pipe" case; "wrote
 /// exactly `cap` bytes" stays `false`.
-pub(super) fn clip_capture(raw: &[u8], cap: Option<usize>) -> (&[u8], bool) {
+pub(crate) fn clip_capture(raw: &[u8], cap: Option<usize>) -> (&[u8], bool) {
     match cap {
         Some(c) if raw.len() > c => (&raw[..c], true),
         _ => (raw, false),

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

@@ -0,0 +1,25 @@
+//! Per-`Driver` execution configuration.
+//!
+//! The wall-clock and per-channel capture caps a frontend forwards into
+//! `Driver::new`. A plain value carrier owned by the `Driver` — distinct
+//! from the process-wide engine/module `crate::cache` (which is shared
+//! across every sandbox) and from the per-invocation
+//! `crate::invocation::Invocation` (which the wasm engine mutates from
+//! inside a run). These caps are read only by `Driver` methods between
+//! runs, so they live here.
+
+use std::time::Duration;
+
+/// Wall-clock and output caps for one `Driver`. `None` on any field
+/// disables that cap.
+pub struct Config {
+    /// Wall-clock cap for one guest `#eval` / `#run`. Stamped into a
+    /// per-run `Instant` deadline by `Driver::prime_caps`.
+    pub timeout: Option<Duration>,
+    /// Byte cap for guest stdout capture.
+    /// Sizes the per-run `MemoryOutputPipe` and computes the truncation
+    /// flag in `Driver::build_snapshot`.
+    pub stdout_limit_bytes: Option<usize>,
+    /// Byte cap for guest stderr capture. Mirror of `stdout_limit_bytes`.
+    pub stderr_limit_bytes: Option<usize>,
+}

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

@@ -0,0 +1,110 @@
+//! Host-side dispatch for the `__kobako_dispatch` import.
+//!
+//! When the guest invokes the wasm import declared in
+//! `wasm/kobako-core/src/abi.rs`, wasmtime calls back into the host
+//! through the closure registered by `instance_pre::build_linker`.
+//! That closure delegates here. The dispatcher:
+//!
+//!   1. Reads the Request bytes from guest linear memory.
+//!   2. Invokes the bound `DispatchHandler` (the frontend's dispatch
+//!      bridge, e.g. a Ruby Proc) 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 handler before any invocation, so reaching the
+//! dispatcher with no handler 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 the driver that deliberately prints
+//! through `eprintln!`. The host normally surfaces faults through the
+//! contract's error channels; the dispatcher contract is the exception
+//! — it must return a packed `i64` to the guest and cannot fail, 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 handler bound vs. the
+//! handler 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 handler, the handler 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 wasmtime::Caller;
+
+use crate::invocation::Invocation;
+
+/// Drive a single `__kobako_dispatch` invocation end-to-end. Entry point
+/// from the wasmtime closure registered by `instance_pre::build_linker`.
+///
+/// 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 handler 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 {
+    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 = crate::guest_mem::read(caller, req_ptr, req_len)?;
+
+    // `Kobako::Sandbox` always installs the dispatch handler before
+    // invoking the runtime, so reaching this branch indicates a misuse
+    // rather than a normal control path.
+    let handler = caller
+        .data()
+        .on_dispatch()
+        .ok_or("a Sandbox callback fired outside an active Sandbox#run — please report this as a kobako bug")?;
+
+    // Build a frame-scoped yielder over this Caller and hand it to the
+    // handler. The borrow ends with the block, freeing the Caller for
+    // `write_response`; nested dispatch frames each build their own, so
+    // the LIFO re-entry lives on the Rust stack — no shared slot.
+    let resp_bytes = {
+        let mut yielder = crate::guest_mem::CallerYielder::new(caller);
+        handler.dispatch(&req_bytes, &mut yielder)
+    }
+    .ok_or(
+        "a Sandbox callback raised an exception instead of returning a fault — please report this as a kobako bug",
+    )?;
+
+    write_response(caller, &resp_bytes)
+}
+
+/// Allocate a guest-side buffer and copy the response bytes into it via
+/// `crate::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 = crate::guest_mem::alloc_and_write(caller, bytes)?;
+    Ok(((ptr as i64) << 32) | (bytes.len() as i64))
+}

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

@@ -0,0 +1,285 @@
+//! The wasmtime driver: everything needed to run one guest invocation,
+//! expressed purely in contract and wasmtime types.
+//!
+//! A `Driver` is the engine half of a kobako host — the pre-linked
+//! `InstancePre` plus the per-Driver caps — and implements the contract
+//! `Runtime` trait over it. It is free of any frontend type; a frontend
+//! shell (the Ruby ext's `Kobako::Runtime`) only shuttles its
+//! host-language values across the contract boundary.
+
+use std::path::Path;
+use std::sync::Arc;
+use std::time::Instant;
+
+use wasmtime::{
+    AsContextMut, InstancePre as WtInstancePre, ResourceLimiter, Store as WtStore, TypedFunc,
+};
+
+use crate::cache::shared_engine;
+use crate::config::Config;
+use crate::exports::Exports;
+use crate::invocation::Invocation;
+use crate::{capture, frames, instance_pre, trap};
+use kobako_runtime::dispatch::DispatchHandler;
+use kobako_runtime::error::{Error, SetupError, Trap};
+use kobako_runtime::runtime::{Entry, Frames, Runtime as ContractRuntime};
+use kobako_runtime::snapshot::{Capture, Completion, Snapshot, Usage};
+
+/// The wire ABI version this host implements (docs/wire-codec.md § ABI
+/// Version). A Guest Binary is accepted only when its
+/// `__kobako_abi_version` export reports the same value; a mismatch
+/// is a deterministic artifact fault. The guest-side mirror is
+/// `kobako_core::abi::ABI_VERSION`. Version 2
+/// carries the per-invocation instance discipline: the host
+/// drives every invocation on a fresh instance, so the guest may leave
+/// its VM state dirty at exit.
+const ABI_VERSION: u32 = 2;
+
+/// The wasmtime execution unit behind one sandbox runtime.
+pub struct Driver {
+    // Pre-linked instantiation template (import wiring + type checks
+    // done once in `instance_pre::cached_instance_pre`). Every
+    // invocation instantiates a fresh instance from it and discards the
+    // whole Store afterwards — the per-invocation instance discipline.
+    instance_pre: WtInstancePre<Invocation>,
+    // Per-invocation linear-memory cap,
+    // threaded into each fresh `Invocation`; lives apart from `Config`
+    // because the wasmtime `ResourceLimiter` callback consumes it from
+    // inside the wasm engine.
+    memory_limit: Option<usize>,
+    // Wall-clock + per-channel capture caps forwarded from the Sandbox;
+    // see `Config`.
+    config: Config,
+}
+
+impl Driver {
+    /// Construct a Driver from a wasm file path, using the process-wide
+    /// shared Engine and per-path Module / InstancePre caches, and verify
+    /// the artifact's ABI version. Every failure is a `SetupError` for
+    /// the frontend to attribute — Engine and Module never leave the
+    /// driver.
+    pub fn new(
+        path: &Path,
+        memory_limit: Option<usize>,
+        config: Config,
+    ) -> Result<Self, SetupError> {
+        let instance_pre = instance_pre::cached_instance_pre(path)?;
+        let driver = Self {
+            instance_pre,
+            memory_limit,
+            config,
+        };
+        driver.probe_abi_version()?;
+        Ok(driver)
+    }
+
+    /// Instantiate a throwaway probe instance at construction and require
+    /// the guest's `__kobako_abi_version` export to equal `ABI_VERSION`.
+    /// An absent export or a non-equal value is a deterministic artifact
+    /// fault. The probe Store drops here; invocation instances are
+    /// created per invoke. The frameless WASI context keeps a third-party
+    /// guest whose start section touches WASI on the `SetupError` path
+    /// instead of panicking in `Invocation::wasi_mut`.
+    fn probe_abi_version(&self) -> Result<(), SetupError> {
+        let mut store = self.new_store()?;
+        frames::install_wasi_frames(&mut store, &self.config, &[])
+            .map_err(|t| SetupError::Dead(t.to_string()))?;
+        let instance = self
+            .instance_pre
+            .instantiate(store.as_context_mut())
+            .map_err(trap::instantiate_err)?;
+        let probe = instance
+            .get_typed_func::<(), u32>(store.as_context_mut(), "__kobako_abi_version")
+            .map_err(|_| {
+                SetupError::Dead(format!(
+                    "the Guest Binary does not export __kobako_abi_version; \
+                     rebuild it against ABI version {ABI_VERSION}"
+                ))
+            })?;
+        let reported = probe.call(store.as_context_mut(), ()).map_err(|e| {
+            SetupError::Dead(format!(
+                "failed to read the Guest Binary's ABI version: {e}"
+            ))
+        })?;
+        if reported != ABI_VERSION {
+            return Err(SetupError::Dead(format!(
+                "the Guest Binary reports ABI version {reported}, but this host \
+                 implements ABI version {ABI_VERSION}; rebuild the Guest Binary \
+                 against the host's version"
+            )));
+        }
+        Ok(())
+    }
+
+    /// Build the per-invocation Store: a fresh `Invocation` wired with
+    /// the memory limiter and the epoch-deadline callback.
+    fn new_store(&self) -> Result<WtStore<Invocation>, SetupError> {
+        let mut store = WtStore::new(shared_engine()?, Invocation::new(self.memory_limit));
+        store.limiter(|state: &mut Invocation| -> &mut dyn ResourceLimiter { state.limiter_mut() });
+        store.epoch_deadline_callback(trap::epoch_deadline_callback);
+        Ok(store)
+    }
+
+    /// Instantiate the per-invocation instance from the pre-linked
+    /// template and resolve its host-driven export handles. An
+    /// instantiation failure at invocation time is an engine fault —
+    /// a `Trap` — unlike the construction-time probe, whose failure is
+    /// `SetupError`.
+    fn instantiate(&self, store: &mut WtStore<Invocation>) -> Result<Exports, Trap> {
+        let instance = self
+            .instance_pre
+            .instantiate(store.as_context_mut())
+            .map_err(|e| Trap::Other(format!("failed to instantiate the Sandbox runtime: {e}")))?;
+        Ok(Exports::resolve(&instance, store.as_context_mut()))
+    }
+
+    /// Run one guest export call inside the per-invocation cap window:
+    /// `Driver::prime_caps` before, `disarm_caps` after — the shared
+    /// bracket for both run-path exports (`__kobako_eval` /
+    /// `__kobako_run`). Disarm runs whether the call returns or traps, so
+    /// the `wall_time` bracket and the memory
+    /// cap always close — that close-on-trap guarantee is the reason this
+    /// bracket lives in one place rather than inline at each call site.
+    /// The wasmtime trap is returned unmapped; the caller classifies it
+    /// through `trap::trap_from`.
+    fn call_with_caps<Params, Results>(
+        &self,
+        store: &mut WtStore<Invocation>,
+        exports: &Exports,
+        export: &TypedFunc<Params, Results>,
+        params: Params,
+    ) -> Result<Results, wasmtime::Error>
+    where
+        Params: wasmtime::WasmParams,
+        Results: wasmtime::WasmResults,
+    {
+        self.prime_caps(store, exports);
+        let result = export.call(store.as_context_mut(), params);
+        disarm_caps(store);
+        result
+    }
+
+    /// Stamp the per-invocation wall-clock deadline into `Invocation`
+    /// and prime the wasmtime epoch deadline so the next ticker tick
+    /// wakes the epoch-deadline callback. When `timeout` is disabled,
+    /// the deadline is set far enough in the future that the callback
+    /// effectively never fires.
+    ///
+    /// Also captures the current linear-memory size as the baseline
+    /// for the per-invocation memory delta cap —
+    /// the pre-initialized image's allocation is folded into the
+    /// baseline rather than the budget — and stamps the wall-clock
+    /// entry instant for the `wall_time`
+    /// measurement. The bracket closes in `disarm_caps` so it matches
+    /// the `timeout` deadline window and excludes `OUTCOME_BUFFER`
+    /// decoding and stdout / stderr capture readout.
+    fn prime_caps(&self, store: &mut WtStore<Invocation>, exports: &Exports) {
+        match self.config.timeout {
+            Some(timeout) => {
+                let deadline = Instant::now() + timeout;
+                store.data_mut().set_deadline(Some(deadline));
+                store.set_epoch_deadline(1);
+            }
+            None => {
+                store.data_mut().set_deadline(None);
+                store.set_epoch_deadline(u64::MAX);
+            }
+        }
+        let baseline = match exports.memory {
+            Some(m) => m.data_size(store.as_context_mut()),
+            None => 0,
+        };
+        store.data_mut().arm_memory_cap(baseline);
+        store.data_mut().start_wall_clock();
+    }
+
+    /// Bundle one invocation's observables into a fresh `Snapshot`,
+    /// uniformly for every `completion` — the clipped captures and the
+    /// cap-bracket usage must survive a trap just as they do an outcome.
+    fn build_snapshot(&self, store: &WtStore<Invocation>, completion: Completion) -> Snapshot {
+        let data = store.data();
+        let usage = Usage {
+            wall_time: data.wall_time().as_secs_f64(),
+            memory_peak: data.memory_peak(),
+        };
+        let (stdout_raw, stderr_raw) = (data.stdout_bytes(), data.stderr_bytes());
+        let (stdout_visible, stdout_truncated) =
+            capture::clip_capture(&stdout_raw, self.config.stdout_limit_bytes);
+        let (stderr_visible, stderr_truncated) =
+            capture::clip_capture(&stderr_raw, self.config.stderr_limit_bytes);
+        Snapshot {
+            completion,
+            stdout: Capture {
+                bytes: stdout_visible.to_vec(),
+                truncated: stdout_truncated,
+            },
+            stderr: Capture {
+                bytes: stderr_visible.to_vec(),
+                truncated: stderr_truncated,
+            },
+            usage,
+        }
+    }
+}
+
+impl ContractRuntime for Driver {
+    /// Drive one guest invocation on a fresh instance and return its
+    /// `Snapshot`, `Ok` iff the guest export ran. Builds a fresh Store,
+    /// binds the borrowed dispatch handler, installs the stdin frames
+    /// (three for `Eval` — preamble / source / snippets; two for `Run` —
+    /// preamble / snippets, with the envelope copied into guest memory),
+    /// and primes the per-invocation caps around the export call. A fault
+    /// before the export call is the `Err` channel; once the call starts,
+    /// every fault folds into the Snapshot's `Completion` — the
+    /// configured-cap paths as `Trap::Timeout` / `Trap::MemoryLimit`,
+    /// everything else as `Trap::Other` — so captures and usage survive
+    /// it. The body touches no frontend value — the handler is only
+    /// borrowed (see the trait's safety contract).
+    fn invoke(
+        &self,
+        entry: Entry<'_>,
+        frames: Frames<'_>,
+        handler: Option<Arc<dyn DispatchHandler>>,
+    ) -> Result<Snapshot, Error> {
+        let mut store = self.new_store()?;
+        if let Some(handler) = handler {
+            store.data_mut().bind_on_dispatch(handler);
+        }
+        let frame_list: Vec<&[u8]> = match &entry {
+            Entry::Eval { source } => vec![frames.preamble, source, frames.snippets],
+            Entry::Run { .. } => vec![frames.preamble, frames.snippets],
+        };
+        frames::install_wasi_frames(&mut store, &self.config, &frame_list)?;
+        let exports = self.instantiate(&mut store)?;
+        let called = match entry {
+            Entry::Eval { .. } => {
+                let eval = frames::require_export(exports.eval.as_ref())?;
+                self.call_with_caps(&mut store, &exports, eval, ())
+            }
+            Entry::Run { envelope } => {
+                let run = frames::require_export(exports.run.as_ref())?;
+                let (env_ptr, env_len) = frames::write_envelope(&mut store, &exports, envelope)?;
+                self.call_with_caps(&mut store, &exports, run, (env_ptr, env_len))
+            }
+        };
+        let completion = match called {
+            Ok(()) => match frames::fetch_outcome_bytes(&mut store, &exports) {
+                Ok(bytes) => Completion::Outcome(bytes),
+                Err(t) => Completion::Trap(t),
+            },
+            Err(e) => Completion::Trap(trap::trap_from(e)),
+        };
+        Ok(self.build_snapshot(&store, completion))
+    }
+}
+
+/// Drop the memory cap as soon as the guest call returns so that
+/// any post-run host bookkeeping (e.g. fetching the OUTCOME_BUFFER,
+/// which can grow guest memory transiently) is not attributed to
+/// the user script. Also closes the
+/// `wall_time` bracket opened by `Driver::prime_caps`. Paired
+/// with `Driver::prime_caps`.
+fn disarm_caps(store: &mut WtStore<Invocation>) {
+    store.data_mut().stop_wall_clock();
+    store.data_mut().disarm_memory_cap();
+}

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

@@ -1,16 +1,16 @@
 //! Per-invocation wasmtime export handles for the host-driven ABI
 //! surface.
 //!
-//! `Runtime::instantiate` resolves the ABI exports the run path drives
+//! `Driver::instantiate` resolves the ABI exports the run path drives
 //! (`__kobako_eval` / `__kobako_run` / `__kobako_take_outcome` /
 //! `__kobako_alloc`) plus the `memory` export against each fresh
 //! per-invocation instance and bundles their
 //! typed handles here, so the invocation body passes one struct around
 //! rather than re-resolving exports by name at every step. Distinct
-//! from `super::cache` (the process-wide Engine / Module cache): this
+//! from `crate::cache` (the process-wide Engine / Module cache): this
 //! carries *which guest function to call*, per invocation.
 //!
-//! `super::dispatch` does not reach this struct — a host import runs
+//! `crate::dispatch` does not reach this struct — a host import runs
 //! against a `Caller`, so the dispatch path resolves `__kobako_alloc`
 //! and `memory` through `Caller::get_export` instead.
 
@@ -18,9 +18,8 @@ use wasmtime::{AsContextMut, Instance as WtInstance, Memory, TypedFunc};
 
 /// The resolved 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` / `require_memory`) when a
-/// handle is `None`.
+/// `kobako.wasm` always does, and the run-path methods surface a `Trap`
+/// (via `require_export` / `require_memory`) when a handle is `None`.
 ///
 /// The handles are indices into the owning Store, not borrows of the
 /// `Instance` — they stay valid for the Store's lifetime, which is why