kobako 0.27.0 → 0.28.0

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

@@ -0,0 +1,286 @@
+//! Per-invocation I/O between the host and the guest: it writes the
+//! entry's downcall into a freshly allocated guest buffer, puts the
+//! Preamble on stdin beside stdout / stderr capture pipes for the WASI
+//! context, and reads the Outcome the downcall answered with.
+
+use wasmtime::Store as WtStore;
+use wasmtime_wasi::p2::pipe::{MemoryInputPipe, MemoryOutputPipe};
+use wasmtime_wasi::WasiCtxBuilder;
+
+use crate::config::Config;
+use crate::exports::Exports;
+use crate::guest_mem::{self, ReadError, WriteError};
+use crate::invocation::Invocation;
+use crate::{ambient, capture};
+use kobako_runtime::error::{InvokeError, SetupError, Trap};
+use kobako_runtime::profile::Profile;
+use kobako_transport::abi::FRAME_LEN_SIZE;
+use kobako_transport::envelope::{CompileReply, Outcome};
+
+/// A missing or trapping allocator is an engine fault, a `Trap`; one that
+/// runs but returns 0 leaves the runtime intact, so it is a `SetupError`.
+pub(crate) fn write_request(
+    store: &mut WtStore<Invocation>,
+    exports: &Exports,
+    envelope: &[u8],
+) -> Result<(i32, i32), InvokeError> {
+    let trap = |message: String| -> InvokeError { Trap::Other(message).into() };
+    let ptr =
+        guest_mem::alloc_and_write(&mut *store, exports, envelope).map_err(|err| match err {
+            WriteError::OutOfMemory => {
+                SetupError::Intact("could not allocate input buffer (out of memory)".to_string())
+                    .into()
+            }
+            WriteError::TooLarge => trap("payload exceeds the 16 MiB limit".to_string()),
+            WriteError::Incompatible(message) => trap(message.to_string()),
+            WriteError::Trapped(e) => trap(format!("failed to allocate input buffer: {e}")),
+            WriteError::OutOfBounds => {
+                trap("the input buffer lies outside the Sandbox's memory".to_string())
+            }
+        })?;
+    // The write has already held the length to the payload cap.
+    Ok((ptr as i32, envelope.len() as i32))
+}
+
+/// An uncapped output channel relies on `memory_limit` for its real
+/// ceiling. The 16 MiB cap keeps the Preamble's `u32` length prefix from
+/// wrapping.
+pub(crate) fn install_wasi(
+    store: &mut WtStore<Invocation>,
+    config: &Config,
+    preamble: &[u8],
+) -> Result<(), Trap> {
+    // The Preamble carries the same 16 MiB cap as a downcall request
+    // (`write_request`): past it, the length prefix would silently wrap.
+    guest_mem::checked_payload_len(preamble.len()).map_err(|msg| Trap::Other(msg.to_string()))?;
+
+    let mut stdin_content: Vec<u8> = Vec::with_capacity(FRAME_LEN_SIZE + preamble.len());
+    stdin_content.extend_from_slice(&(preamble.len() as u32).to_be_bytes());
+    stdin_content.extend_from_slice(preamble);
+
+    let stdin_pipe = MemoryInputPipe::new(stdin_content);
+    let stdout_pipe = MemoryOutputPipe::new(capture::pipe_capacity(config.stdout_limit));
+    let stderr_pipe = MemoryOutputPipe::new(capture::pipe_capacity(config.stderr_limit));
+
+    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(())
+}
+
+/// A guest that answered without an Outcome the envelope can frame — an
+/// empty answer included — has nothing left to attribute, so it is a
+/// `Trap` like every other way of failing to read the result.
+pub(crate) fn read_outcome(
+    store: &WtStore<Invocation>,
+    exports: &Exports,
+    packed: u64,
+) -> Result<Outcome, Trap> {
+    let bytes = read_answer(store, exports, packed)?;
+    Outcome::decode(&bytes).map_err(|_| {
+        Trap::Other(
+            if bytes.is_empty() {
+                "Sandbox exited without producing a result"
+            } else {
+                "Sandbox produced an unrecognised result"
+            }
+            .to_string(),
+        )
+    })
+}
+
+/// Held to the same 16 MiB bound as an Outcome; an answer that does not
+/// frame is a `Trap` the caller treats like any other failed compile.
+pub(crate) fn read_compile_reply(
+    store: &WtStore<Invocation>,
+    exports: &Exports,
+    packed: u64,
+) -> Result<CompileReply, Trap> {
+    let bytes = read_answer(store, exports, packed)?;
+    CompileReply::decode(&bytes)
+        .map_err(|_| Trap::Other("Sandbox produced an unrecognised compile answer".to_string()))
+}
+
+fn read_answer(
+    store: &WtStore<Invocation>,
+    exports: &Exports,
+    packed: u64,
+) -> Result<Vec<u8>, Trap> {
+    let mem = exports.require_memory()?;
+    let (ptr, len) = guest_mem::unpack_guest_buffer(packed);
+    guest_mem::read_buffer(store, mem, ptr, len).map_err(|err| {
+        Trap::Other(
+            match err {
+                ReadError::TooLarge => "result payload exceeds the 16 MiB limit",
+                ReadError::OutOfBounds => "the Sandbox result is out of bounds",
+            }
+            .to_string(),
+        )
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    //! Witness what the context `install_wasi` builds grants at
+    //! each profile rung: `wasi:clocks` / `wasi:random` frozen under
+    //! `Hermetic` and live under `Permissive`, and no filesystem,
+    //! environment, or socket under either.
+    use wasmtime::{AsContextMut, Linker, Module};
+    use wasmtime_wasi::p1;
+
+    use super::*;
+    use crate::cache::shared_engine;
+
+    /// Preview1 `errno` for a descriptor the context does not hold.
+    const ERRNO_BADF: i64 = 8;
+
+    /// Preview1 probe with one export per ambient source: `clock_ns`
+    /// reads the realtime clock, `random_word` reads eight entropy bytes,
+    /// `environ_count` counts environment variables, and `prestat_errno`
+    /// / `accept_errno` ask descriptor 3 for a directory and a
+    /// connection. Preview1 numbers preopens from 3, so nothing there
+    /// means no directory and no socket was granted.
+    const 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)))
+          (import "wasi_snapshot_preview1" "environ_sizes_get"
+            (func $environ (param i32 i32) (result i32)))
+          (import "wasi_snapshot_preview1" "fd_prestat_get"
+            (func $prestat (param i32 i32) (result i32)))
+          (import "wasi_snapshot_preview1" "sock_accept"
+            (func $accept (param i32 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)))
+          (func (export "environ_count") (result i64)
+            (drop (call $environ (i32.const 16) (i32.const 20)))
+            (i64.extend_i32_u (i32.load (i32.const 16))))
+          (func (export "prestat_errno") (result i64)
+            (i64.extend_i32_u (call $prestat (i32.const 3) (i32.const 24))))
+          (func (export "accept_errno") (result i64)
+            (i64.extend_i32_u (call $accept (i32.const 3) (i32.const 0) (i32.const 24)))))
+    "#;
+
+    /// Instantiate the probe over a WASI context built at `profile` and
+    /// return a reader for its exports.
+    fn probe(profile: Profile) -> impl FnMut(&str) -> i64 {
+        let engine = shared_engine().expect("shared engine must be constructible");
+        let config = Config {
+            timeout: None,
+            memory_limit: None,
+            stdout_limit: None,
+            stderr_limit: None,
+            profile,
+        };
+        let mut store = WtStore::new(engine, Invocation::new(None));
+        store.set_epoch_deadline(crate::trap::NO_TIMEOUT_EPOCH_DELTA);
+        install_wasi(&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, PROBE_WAT).expect("probe module must compile");
+        let instance = linker
+            .instantiate(&mut store, &module)
+            .expect("probe module must instantiate");
+
+        move |name| {
+            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")
+        }
+    }
+
+    /// Assert that the context built at `profile` grants no directory,
+    /// environment variable, or socket.
+    fn assert_grants_no_resource(profile: Profile) {
+        let mut read = probe(profile);
+        assert_eq!(
+            read("prestat_errno"),
+            ERRNO_BADF,
+            "a {profile:?} guest's WASI context must preopen no directory"
+        );
+        assert_eq!(
+            read("environ_count"),
+            0,
+            "a {profile:?} guest's WASI context must carry no environment variable"
+        );
+        assert_eq!(
+            read("accept_errno"),
+            ERRNO_BADF,
+            "a {profile:?} guest's WASI context must hold no socket"
+        );
+    }
+
+    // @behavior RT-047 RT-048
+    #[test]
+    fn hermetic_denies_ambient_time_and_entropy() {
+        let mut read = probe(Profile::Hermetic);
+        assert_eq!(
+            read("clock_ns"),
+            0,
+            "a hermetic guest's wasi:clocks must read the Unix epoch, not host time"
+        );
+        assert_eq!(
+            read("random_word"),
+            0,
+            "a hermetic guest's wasi:random must yield the constant stream, not host entropy"
+        );
+    }
+
+    // @behavior RT-049 RT-050
+    #[test]
+    fn permissive_grants_live_ambient_time_and_entropy() {
+        let mut read = probe(Profile::Permissive);
+        assert!(
+            read("clock_ns") > 0,
+            "a permissive guest's wasi:clocks must read live host time"
+        );
+        assert_ne!(
+            read("random_word"),
+            0,
+            "a permissive guest's wasi:random must yield host entropy"
+        );
+    }
+
+    // @behavior RT-067
+    #[test]
+    fn hermetic_grants_no_filesystem_environment_or_socket() {
+        assert_grants_no_resource(Profile::Hermetic);
+    }
+
+    // @behavior RT-067
+    #[test]
+    fn permissive_grants_no_filesystem_environment_or_socket() {
+        assert_grants_no_resource(Profile::Permissive);
+    }
+}

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

@@ -8,29 +8,7 @@
 //! lives behind the contract surface, so a frontend shell (the Ruby
 //! ext's `Kobako::Runtime`) sees no wasmtime type.
 //!
-//! Module layout (one responsibility per file):
-//!
-//! * `driver` — `Driver` + `impl kobako_runtime::runtime::Runtime`
-//!   (the run mechanics).
-//! * `cache` — process-wide Engine + per-path Module cache and the
-//!   process-singleton epoch ticker thread.
-//! * `config` — per-Driver caps (timeout / stdout / stderr limits).
-//! * `exports` — per-invocation `__kobako_eval` / `_run` /
-//!   `_take_outcome` / `_alloc` / `memory` handles.
-//! * `instance_pre` — host-import Linker wiring + per-path
-//!   `InstancePre` cache.
-//! * `abi` — the Guest Binary's declared ABI version check, verified
-//!   with the cached `InstancePre` it guards.
-//! * `invocation` — Invocation (per-Store context), the
-//!   `MemoryLimiter` memory cap, and the trap marker types
-//!   (`TimeoutTrap` / `MemoryLimitTrap`).
-//! * `dispatch` — `__kobako_dispatch` host-import dispatch helpers.
-//! * `frames` — stdin frame stream + WASI context assembly, `#run`
-//!   envelope write, OUTCOME_BUFFER readout.
-//! * `guest_mem` — Caller-based guest linear-memory alloc / write / read.
-//! * `capture` — stdout / stderr pipe sizing + clip helpers.
-//! * `ambient` — frozen WASI clocks + constant RNG (ambient denial).
-//! * `trap` — wasmtime-error → neutral `Trap` classification.
+//! Each module holds one responsibility and opens with its own doc.
 
 mod abi;
 mod ambient;
@@ -40,10 +18,11 @@ mod config;
 mod dispatch;
 mod driver;
 mod exports;
-mod frames;
 mod guest_mem;
 mod instance_pre;
 mod invocation;
+mod io;
+mod limiter;
 mod trap;
 
 pub use config::Config;

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

@@ -0,0 +1,253 @@
+//! The per-invocation memory cap: only the `memory.grow` delta past the
+//! linear-memory size captured at invocation entry is charged, so the
+//! image's initial allocation is outside the budget.
+
+use wasmtime::ResourceLimiter;
+
+/// Resource limiter that enforces the per-invocation `memory_limit`
+/// cap.
+///
+/// `max_memory` is the byte cap on per-invocation growth (`None` disables
+/// the cap). `baseline` is the linear-memory size captured at invocation
+/// entry by `MemoryLimiter::activate`; the limiter charges only the
+/// `memory.grow` delta past `baseline` against `max_memory`, so the
+/// mruby image's initial allocation and any high-water mark left by
+/// prior invocations on the same Sandbox do not consume the budget.
+/// `cap_active` gates whether the cap is enforced — wasmtime's
+/// `ResourceLimiter` also fires for the module's declared initial
+/// allocation at instantiation time, but the cap stays dormant until
+/// `MemoryLimiter::activate` flips the flag for one `Driver` invoke
+/// call. When `cap_active` is `false`, the limiter always allows
+/// growth.
+///
+/// When `memory.grow` would push the per-invocation delta past
+/// `max_memory`, the limiter returns `MemoryLimitTrap` from
+/// `memory_growing`; wasmtime turns that into the trap surfaced to the
+/// host as a guest invocation failure.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct MemoryLimiter {
+    max_memory: Option<usize>,
+    baseline: usize,
+    cap_active: bool,
+    peak: usize,
+}
+
+impl MemoryLimiter {
+    pub(crate) fn new(max_memory: Option<usize>) -> Self {
+        Self {
+            max_memory,
+            baseline: 0,
+            cap_active: false,
+            peak: 0,
+        }
+    }
+
+    /// The cap stays dormant until armed, because the module's declared
+    /// initial memory is allocated during instantiation and must pass.
+    pub(crate) fn activate(&mut self, baseline: usize) {
+        self.baseline = baseline;
+        self.cap_active = true;
+        self.peak = 0;
+    }
+
+    pub(crate) fn deactivate(&mut self) {
+        self.cap_active = false;
+    }
+
+    /// A grow the cap rejects never updates the peak, so the reported value
+    /// never exceeds `memory_limit`.
+    pub(crate) fn peak(&self) -> usize {
+        self.peak
+    }
+}
+
+impl ResourceLimiter for MemoryLimiter {
+    fn memory_growing(
+        &mut self,
+        _current: usize,
+        desired: usize,
+        _maximum: Option<usize>,
+    ) -> wasmtime::Result<bool> {
+        if !self.cap_active {
+            return Ok(true);
+        }
+        let delta = desired.saturating_sub(self.baseline);
+        if let Some(limit) = self.max_memory {
+            if delta > limit {
+                return Err(wasmtime::Error::new(MemoryLimitTrap { desired, limit }));
+            }
+        }
+        if delta > self.peak {
+            self.peak = delta;
+        }
+        Ok(true)
+    }
+
+    fn table_growing(
+        &mut self,
+        _current: usize,
+        _desired: usize,
+        _maximum: Option<usize>,
+    ) -> wasmtime::Result<bool> {
+        Ok(true)
+    }
+}
+
+/// Marker error returned from `MemoryLimiter::memory_growing` when the
+/// per-invocation memory cap is exceeded. Downcast from the wasmtime
+/// trap error to classify the failure as a memory-limit `Trap`. Callers
+/// use the `Display` impl below — no field is read directly — so the
+/// inner state stays private.
+#[derive(Debug)]
+pub(crate) struct MemoryLimitTrap {
+    desired: usize,
+    limit: usize,
+}
+
+impl MemoryLimitTrap {
+    #[cfg(test)]
+    pub(crate) fn new(desired: usize, limit: usize) -> Self {
+        Self { desired, limit }
+    }
+}
+
+impl std::fmt::Display for MemoryLimitTrap {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "memory usage exceeded memory_limit: \
+             requested={} bytes, limit={} bytes",
+            self.desired, self.limit
+        )
+    }
+}
+
+impl std::error::Error for MemoryLimitTrap {}
+
+#[cfg(test)]
+mod tests {
+    //! Unit tests for `MemoryLimiter` — the per-invocation memory
+    //! delta cap. The Ruby-facing E2E suite exercises the full path
+    //! through wasmtime; these tests pin the pure delta arithmetic so
+    //! a regression that breaks the baseline accounting (e.g. dropping
+    //! the `baseline` subtraction, or letting `activate` carry stale
+    //! state across invocations) is caught without spinning up a
+    //! Store.
+    use super::{MemoryLimitTrap, MemoryLimiter};
+    use wasmtime::ResourceLimiter;
+
+    fn assert_growing(limiter: &mut MemoryLimiter, desired: usize) {
+        assert!(
+            limiter.memory_growing(0, desired, None).unwrap(),
+            "expected memory_growing({desired}) to allow growth"
+        );
+    }
+
+    fn assert_trapping(limiter: &mut MemoryLimiter, desired: usize) {
+        let err = limiter
+            .memory_growing(0, desired, None)
+            .expect_err("expected memory_growing to trap");
+        assert!(
+            err.downcast_ref::<MemoryLimitTrap>().is_some(),
+            "expected MemoryLimitTrap, got {err:?}"
+        );
+    }
+
+    // @behavior S-113
+    #[test]
+    fn dormant_limiter_allows_any_growth() {
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
+        // Without `activate`, the cap is dormant — the module's
+        // declared initial allocation must pass through unconditionally.
+        assert_growing(&mut limiter, 100 << 20);
+    }
+
+    // @behavior S-114
+    #[test]
+    fn delta_below_cap_passes_after_activate() {
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
+        limiter.activate(2 << 20);
+        // baseline=2 MiB, desired=2.5 MiB → delta=0.5 MiB ≤ 1 MiB cap.
+        assert_growing(&mut limiter, (2 << 20) + (1 << 19));
+    }
+
+    // @behavior S-121
+    #[test]
+    fn delta_past_cap_traps_with_memory_limit_trap() {
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
+        limiter.activate(2 << 20);
+        // baseline=2 MiB, desired=4 MiB → delta=2 MiB > 1 MiB cap.
+        assert_trapping(&mut limiter, 4 << 20);
+    }
+
+    // @behavior S-008
+    #[test]
+    fn activate_resets_baseline_on_each_invocation() {
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
+        limiter.activate(2 << 20);
+        assert_growing(&mut limiter, (2 << 20) + (1 << 20));
+        // Second invocation: linear memory has grown to 3 MiB. Re-arming
+        // must re-anchor the baseline so the next 1 MiB of growth fits
+        // the per-invocation budget rather than being charged against
+        // the prior invocation's residue.
+        limiter.activate(3 << 20);
+        assert_growing(&mut limiter, (3 << 20) + (1 << 20));
+    }
+
+    // @behavior S-009
+    #[test]
+    fn disabled_cap_ignores_delta_size() {
+        let mut limiter = MemoryLimiter::new(None);
+        limiter.activate(0);
+        assert_growing(&mut limiter, 100 << 20);
+    }
+
+    // @behavior S-116
+    #[test]
+    fn peak_starts_at_zero_before_any_grow() {
+        let limiter = MemoryLimiter::new(Some(1 << 20));
+        assert_eq!(limiter.peak(), 0);
+    }
+
+    // @behavior S-115
+    #[test]
+    fn peak_tracks_high_water_of_delta_past_baseline() {
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
+        limiter.activate(2 << 20);
+        assert_growing(&mut limiter, (2 << 20) + (1 << 18)); // delta=256 KiB
+        assert_growing(&mut limiter, (2 << 20) + (1 << 19)); // delta=512 KiB (new peak)
+        assert_growing(&mut limiter, (2 << 20) + (1 << 17)); // delta=128 KiB (below peak)
+        assert_eq!(limiter.peak(), 1 << 19);
+    }
+
+    // @behavior S-062
+    #[test]
+    fn trap_does_not_update_peak() {
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
+        limiter.activate(2 << 20);
+        assert_growing(&mut limiter, (2 << 20) + (1 << 19)); // delta=512 KiB
+        assert_trapping(&mut limiter, (2 << 20) + (2 << 20)); // would be 2 MiB > 1 MiB cap
+                                                              // Peak reflects the last accepted grow, not the rejected desired.
+        assert_eq!(limiter.peak(), 1 << 19);
+    }
+
+    // @behavior S-117
+    #[test]
+    fn activate_resets_peak_for_new_invocation() {
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
+        limiter.activate(2 << 20);
+        assert_growing(&mut limiter, (2 << 20) + (1 << 19));
+        assert_eq!(limiter.peak(), 1 << 19);
+        limiter.activate(3 << 20);
+        assert_eq!(limiter.peak(), 0);
+    }
+
+    // @behavior S-118
+    #[test]
+    fn disabled_cap_still_tracks_peak() {
+        let mut limiter = MemoryLimiter::new(None);
+        limiter.activate(1 << 20);
+        assert_growing(&mut limiter, (1 << 20) + (4 << 20));
+        assert_eq!(limiter.peak(), 4 << 20);
+    }
+}