kobako 0.28.0 → 0.30.0

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

@@ -1,265 +0,0 @@
-//! Guest linear-memory I/O for every host↔guest buffer handoff, whether
-//! the invocation body drives it through its `Store` or a host import
-//! drives it through its `Caller`.
-//!
-//! 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::{AsContext, AsContextMut, Caller, Memory};
-
-use crate::exports::{Exports, RUNTIME_INCOMPATIBLE};
-use crate::invocation::Invocation;
-use kobako_transport::abi::{unpack_ptr_len, MAX_DISPATCH_PAYLOAD};
-use kobako_transport::envelope::Downcall;
-
-// 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, 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";
-
-/// 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,
-}
-
-/// 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(
-    mut ctx: impl AsContextMut,
-    exports: &Exports,
-    bytes: &[u8],
-) -> 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 ctx, len as u32)
-        .map_err(WriteError::Trapped)?;
-    if ptr == 0 {
-        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())
-}
-
-/// 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)
-}
-
-/// 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 trapped(
-    caller: &mut Caller<'_, Invocation>,
-    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 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 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) => trapped(
-            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",
-    })
-}
-
-/// 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");
-    }
-    // The cap above sits below `i32::MAX`, so this conversion cannot wrap.
-    i32::try_from(len).map_err(|_| "payload exceeds the 16 MiB limit")
-}
-
-pub(crate) fn guest_buffer_range(
-    ptr: usize,
-    len: usize,
-    mem_size: usize,
-) -> Result<core::ops::Range<usize>, &'static str> {
-    let end = ptr.checked_add(len).ok_or("ptr + len overflow")?;
-    if end > mem_size {
-        return Err("range exceeds Sandbox memory size");
-    }
-    Ok(ptr..end)
-}
-
-/// 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)
-}
-
-pub(crate) fn drive_yield(
-    caller: &mut Caller<'_, Invocation>,
-    args: &[u8],
-) -> Result<Vec<u8>, &'static str> {
-    let request = Downcall::Yield(args.to_vec()).encode();
-    let len_i32 = checked_payload_len(request.len())?;
-    let req_ptr = write_from_callback(caller, &request)? as i32;
-
-    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(|trap| trapped(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");
-    }
-    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_guest_buffer, MAX_DISPATCH_PAYLOAD,
-    };
-
-    // @behavior WE-059
-    #[test]
-    fn checked_payload_len_accepts_zero_and_the_cap() {
-        assert_eq!(checked_payload_len(0), Ok(0));
-        assert_eq!(
-            checked_payload_len(MAX_DISPATCH_PAYLOAD),
-            Ok(MAX_DISPATCH_PAYLOAD as i32)
-        );
-    }
-
-    // @behavior WE-060
-    #[test]
-    fn checked_payload_len_rejects_past_the_cap() {
-        assert!(checked_payload_len(MAX_DISPATCH_PAYLOAD + 1).is_err());
-        assert!(checked_payload_len(usize::MAX).is_err());
-    }
-
-    // @behavior WE-061
-    #[test]
-    fn guest_buffer_range_returns_half_open_range() {
-        assert_eq!(guest_buffer_range(10, 5, 100), Ok(10..15));
-    }
-
-    // @behavior WE-062
-    #[test]
-    fn guest_buffer_range_accepts_zero_length_at_any_in_bounds_ptr() {
-        assert_eq!(guest_buffer_range(0, 0, 0), Ok(0..0));
-        assert_eq!(guest_buffer_range(42, 0, 100), Ok(42..42));
-    }
-
-    // @behavior WE-063
-    #[test]
-    fn guest_buffer_range_rejects_ptr_plus_len_overflow() {
-        assert!(guest_buffer_range(usize::MAX, 1, usize::MAX).is_err());
-    }
-
-    // @behavior WE-064
-    #[test]
-    fn guest_buffer_range_rejects_end_past_memory() {
-        assert!(guest_buffer_range(10, 100, 50).is_err());
-        assert_eq!(guest_buffer_range(0, 50, 50), Ok(0..50));
-    }
-
-    // @behavior WE-001
-    #[test]
-    fn unpack_guest_buffer_extracts_high_ptr_low_len() {
-        assert_eq!(
-            unpack_guest_buffer(0xAABB_CCDD_1122_3344),
-            (0xAABB_CCDD, 0x1122_3344)
-        );
-    }
-
-    // @behavior WE-065
-    #[test]
-    fn unpack_guest_buffer_zero_decodes_to_zero_pair() {
-        assert_eq!(unpack_guest_buffer(0), (0, 0));
-    }
-}

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

@@ -1,286 +0,0 @@
-//! 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/sig/kobako/snippet/binary.rbs

@@ -1,12 +0,0 @@
-module Kobako
-  module Snippet
-    class Binary < Data
-      KIND: Symbol
-
-      attr_reader body: String
-
-      def self.new: (body: String) -> Binary
-                  | (String body) -> Binary
-    end
-  end
-end