kobako 0.12.1 → 0.13.0

data/ext/kobako/src/runtime/frames.rs

@@ -1,188 +0,0 @@
-//! Per-invocation byte-shuttle between Ruby 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 ext owns no wire codec — these
-//! helpers move raw bytes; Ruby decodes them.
-
-use magnus::{Error as MagnusError, RString, Ruby};
-use wasmtime::{AsContextMut, Memory, Store as WtStore, TypedFunc};
-use wasmtime_wasi::p2::pipe::{MemoryInputPipe, MemoryOutputPipe};
-use wasmtime_wasi::WasiCtxBuilder;
-
-use super::config::Config;
-use super::exports::Exports;
-use super::invocation::Invocation;
-use super::rstring_to_vec;
-use super::{ambient, capture, errors, guest_mem};
-
-/// Return the resolved `memory` export handle, or raise
-/// `Kobako::TrapError` when the loaded module exports no linear
-/// memory — the "not a Kobako-shaped runtime" failure mode
-/// (`SANDBOX_RUNTIME_NOT_KOBAKO`).
-fn require_memory(ruby: &Ruby, exports: &Exports) -> Result<Memory, MagnusError> {
-    exports
-        .memory
-        .ok_or_else(|| errors::trap_err(ruby, SANDBOX_RUNTIME_NOT_KOBAKO))
-}
-
-/// 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.
-/// Raises `Kobako::TrapError` when the allocation hook is missing or
-/// itself traps, and `Kobako::SandboxError` when the hook runs but
-/// cannot reserve the buffer (`__kobako_alloc` returns 0) — an
-/// intact runtime, not an engine fault.
-pub(crate) fn write_envelope(
-    ruby: &Ruby,
-    store: &mut WtStore<Invocation>,
-    exports: &Exports,
-    envelope: RString,
-) -> Result<(i32, i32), MagnusError> {
-    let bytes = rstring_to_vec(envelope);
-    let len_i32 =
-        guest_mem::checked_payload_len(bytes.len()).map_err(|msg| errors::trap_err(ruby, msg))?;
-
-    let alloc = require_export(ruby, exports.alloc.as_ref())?;
-    let memory = require_memory(ruby, exports)?;
-
-    let ptr = alloc
-        .call(store.as_context_mut(), bytes.len() as u32)
-        .map_err(|e| errors::trap_err(ruby, format!("failed to allocate input buffer: {}", e)))?;
-    if ptr == 0 {
-        return Err(errors::sandbox_err(
-            ruby,
-            "could not allocate input buffer (out of memory)",
-        ));
-    }
-    let data = memory.data_mut(store.as_context_mut());
-    let range = guest_mem::guest_buffer_range(ptr as usize, bytes.len(), data.len())
-        .map_err(|msg| errors::trap_err(ruby, msg))?;
-    data[range].copy_from_slice(&bytes);
-
-    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.
-/// Raises `Kobako::TrapError` when any frame exceeds the 16 MiB cap that
-/// keeps its `u32` length prefix from wrapping.
-pub(crate) fn install_wasi_frames(
-    store: &mut WtStore<Invocation>,
-    config: &Config,
-    frames: &[Vec<u8>],
-) -> Result<(), MagnusError> {
-    let ruby = Ruby::get().expect("Ruby thread");
-    // 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| errors::trap_err(&ruby, msg))?;
-    }
-
-    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());
-    // Deny the preview1 ambient-authority imports the guest never legitimately
-    // reaches but the WASI layer would otherwise grant (see `ambient`).
-    builder.wall_clock(ambient::FrozenWallClock);
-    builder.monotonic_clock(ambient::FrozenMonotonicClock);
-    builder.secure_random(ambient::deterministic_rng());
-    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. Raises
-/// `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(
-    ruby: &Ruby,
-    store: &mut WtStore<Invocation>,
-    exports: &Exports,
-) -> Result<Vec<u8>, MagnusError> {
-    let take = require_export(ruby, exports.take_outcome.as_ref())?;
-    let mem = require_memory(ruby, exports)?;
-
-    let packed = take
-        .call(store.as_context_mut(), ())
-        .map_err(|e| errors::trap_err(ruby, 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(errors::trap_err(
-            ruby,
-            "result payload exceeds the 16 MiB limit",
-        ));
-    }
-
-    let data = mem.data(store.as_context_mut());
-    let range = guest_mem::guest_buffer_range(ptr, len, data.len()).map_err(|msg| {
-        errors::trap_err(
-            ruby,
-            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 raise
-/// `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 → Ruby
-/// error" boilerplate; 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<'a, Params, Results>(
-    ruby: &Ruby,
-    export: Option<&'a TypedFunc<Params, Results>>,
-) -> Result<&'a TypedFunc<Params, Results>, MagnusError>
-where
-    Params: wasmtime::WasmParams,
-    Results: wasmtime::WasmResults,
-{
-    export.ok_or_else(|| errors::trap_err(ruby, SANDBOX_RUNTIME_MISSING_HOOKS))
-}

data/ext/kobako/src/snapshot.rs

@@ -1,110 +0,0 @@
-//! `Kobako::Snapshot` — per-invocation observable bundle.
-//!
-//! Every successful `Kobako::Runtime#eval` / `#run` returns one of these.
-//! It carries every observable the host needs to surface after a guest
-//! invocation: the OUTCOME_BUFFER bytes (`return_bytes`), the captured
-//! stdout / stderr byte slices with their truncation flags, and
-//! the wall-clock + memory-peak figures from `Kobako::Usage`.
-//!
-//! Ruby callers see the seven raw readers registered below; the helper
-//! methods that pack them into `Kobako::Capture` / `Kobako::Usage`
-//! (`Kobako::Snapshot#stdout` / `#stderr` / `#usage`) live in
-//! `lib/kobako/snapshot.rb`. The split keeps the ext side a pure value
-//! carrier and lets Ruby own the convenience surface.
-
-use std::cell::Cell;
-use std::time::Duration;
-
-use magnus::{method, prelude::*, Error as MagnusError, RModule, RString, Ruby};
-
-/// Per-invocation snapshot value. Magnus wraps it so a single ext call
-/// from `Runtime::eval` / `Runtime::run` returns the whole bundle —
-/// the Sandbox layer can decompose it without round-tripping into ext
-/// again. All fields are private; the seven public methods registered
-/// in `init` read them out one by one. The wall-clock duration is
-/// held as a `Cell<Duration>` only because magnus' `#[magnus::wrap]`
-/// macro requires interior mutability — every field is set once at
-/// construction time and never mutated again.
-#[magnus::wrap(class = "Kobako::Snapshot", free_immediately, size)]
-pub(crate) struct Snapshot {
-    return_bytes: Vec<u8>,
-    stdout_bytes: Vec<u8>,
-    stdout_truncated: bool,
-    stderr_bytes: Vec<u8>,
-    stderr_truncated: bool,
-    wall_time: Cell<Duration>,
-    memory_peak: usize,
-}
-
-impl Snapshot {
-    /// Construct a fresh Snapshot from the per-invocation data the
-    /// Runtime has just collected. Called from
-    /// `crate::runtime::Runtime::build_snapshot` once the
-    /// guest export has returned, the OUTCOME_BUFFER has been drained,
-    /// and the capture pipes have been clipped to their caps.
-    pub(crate) fn new(
-        return_bytes: Vec<u8>,
-        stdout_bytes: Vec<u8>,
-        stdout_truncated: bool,
-        stderr_bytes: Vec<u8>,
-        stderr_truncated: bool,
-        wall_time: Duration,
-        memory_peak: usize,
-    ) -> Self {
-        Self {
-            return_bytes,
-            stdout_bytes,
-            stdout_truncated,
-            stderr_bytes,
-            stderr_truncated,
-            wall_time: Cell::new(wall_time),
-            memory_peak,
-        }
-    }
-
-    fn return_bytes(&self) -> RString {
-        let ruby = Ruby::get().expect("Ruby thread");
-        ruby.str_from_slice(&self.return_bytes)
-    }
-
-    fn stdout_bytes(&self) -> RString {
-        let ruby = Ruby::get().expect("Ruby thread");
-        ruby.str_from_slice(&self.stdout_bytes)
-    }
-
-    fn stdout_truncated(&self) -> bool {
-        self.stdout_truncated
-    }
-
-    fn stderr_bytes(&self) -> RString {
-        let ruby = Ruby::get().expect("Ruby thread");
-        ruby.str_from_slice(&self.stderr_bytes)
-    }
-
-    fn stderr_truncated(&self) -> bool {
-        self.stderr_truncated
-    }
-
-    fn wall_time(&self) -> f64 {
-        self.wall_time.get().as_secs_f64()
-    }
-
-    fn memory_peak(&self) -> usize {
-        self.memory_peak
-    }
-}
-
-/// Register `Kobako::Snapshot` plus its seven raw readers under the
-/// `Kobako` module. Called from `crate::init` after `Kobako::Runtime`
-/// is registered so the magnus wrap macro can resolve the class name.
-pub(crate) fn init(ruby: &Ruby, kobako: RModule) -> Result<(), MagnusError> {
-    let snapshot = kobako.define_class("Snapshot", ruby.class_object())?;
-    snapshot.define_method("return_bytes", method!(Snapshot::return_bytes, 0))?;
-    snapshot.define_method("stdout_bytes", method!(Snapshot::stdout_bytes, 0))?;
-    snapshot.define_method("stdout_truncated", method!(Snapshot::stdout_truncated, 0))?;
-    snapshot.define_method("stderr_bytes", method!(Snapshot::stderr_bytes, 0))?;
-    snapshot.define_method("stderr_truncated", method!(Snapshot::stderr_truncated, 0))?;
-    snapshot.define_method("wall_time", method!(Snapshot::wall_time, 0))?;
-    snapshot.define_method("memory_peak", method!(Snapshot::memory_peak, 0))?;
-    Ok(())
-}

data/lib/kobako/snapshot.rb

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "capture"
-require_relative "usage"
-
-module Kobako
-  # Kobako::Snapshot — per-invocation observable bundle returned from
-  # +Kobako::Runtime#eval+ and +#run+.
-  #
-  # The magnus class (see ext/kobako/src/snapshot.rs) carries seven raw
-  # readers: +return_bytes+, +stdout_bytes+, +stdout_truncated+,
-  # +stderr_bytes+, +stderr_truncated+, +wall_time+, +memory_peak+. This
-  # file reopens the class to add the Ruby-side helpers that pack those
-  # raw fields into the user-facing value objects +Kobako::Capture+ and
-  # +Kobako::Usage+ — the same shape +Kobako::Sandbox+ exposes to the
-  # Host App.
-  class Snapshot
-    # Wrap the stdout capture pair (+stdout_bytes+, +stdout_truncated+)
-    # as a +Kobako::Capture+ value object. The byte content never carries
-    # a truncation sentinel; +#truncated?+ is the only way to observe
-    # that the cap was hit.
-    def stdout
-      Capture.new(bytes: stdout_bytes, truncated: stdout_truncated)
-    end
-
-    # Wrap the stderr capture pair as a +Kobako::Capture+ value object.
-    # Mirror of +#stdout+.
-    def stderr
-      Capture.new(bytes: stderr_bytes, truncated: stderr_truncated)
-    end
-
-    # Wrap the per-last-invocation usage pair (+wall_time+,
-    # +memory_peak+) as a +Kobako::Usage+ value object.
-    def usage
-      Usage.new(wall_time: wall_time, memory_peak: memory_peak)
-    end
-  end
-end

data/sig/kobako/snapshot.rbs

@@ -1,15 +0,0 @@
-module Kobako
-  class Snapshot
-    def return_bytes: () -> String
-    def stdout_bytes: () -> String
-    def stdout_truncated: () -> bool
-    def stderr_bytes: () -> String
-    def stderr_truncated: () -> bool
-    def wall_time: () -> Float
-    def memory_peak: () -> Integer
-
-    def stdout: () -> Kobako::Capture
-    def stderr: () -> Kobako::Capture
-    def usage: () -> Kobako::Usage
-  end
-end