kobako 0.11.0 → 0.11.2

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

@@ -0,0 +1,90 @@
+//! Ruby error classes (lazy-resolved once the top-level Kobako error
+//! hierarchy is loaded by `lib/kobako/errors.rb`) and the `*_err`
+//! constructors every run-mechanics submodule shares. The ext raises
+//! directly into the invocation-outcome taxonomy (`TrapError` and its
+//! subclasses) for run-path failures and into the construction-layer
+//! `SetupError` (and its `ModuleNotBuiltError` subclass) for `from_path`
+//! setup failures — no engine-specific intermediate layer; the Sandbox
+//! layer adds the verb prefix and lets the subclass identity flow through
+//! unchanged.
+
+use magnus::value::Lazy;
+use magnus::{prelude::*, Error as MagnusError, ExceptionClass, RModule, Ruby};
+
+/// Resolve `Kobako::<name>` as an `ExceptionClass` — the shared body of
+/// every error-class `Lazy` below, which differ only in the constant
+/// name. The constants are guaranteed present by the time any of these
+/// lazies first resolve (`lib/kobako/errors.rb` loads the hierarchy before
+/// the ext raises into it), so a missing constant is a build / wiring bug
+/// and the `unwrap` is the correct fail-fast.
+fn kobako_error_class(ruby: &Ruby, name: &str) -> ExceptionClass {
+    let kobako: RModule = ruby.class_object().const_get("Kobako").unwrap();
+    kobako.const_get(name).unwrap()
+}
+
+pub(crate) static SETUP_ERROR: Lazy<ExceptionClass> =
+    Lazy::new(|ruby| kobako_error_class(ruby, "SetupError"));
+
+pub(crate) static MODULE_NOT_BUILT_ERROR: Lazy<ExceptionClass> =
+    Lazy::new(|ruby| kobako_error_class(ruby, "ModuleNotBuiltError"));
+
+pub(crate) static TRAP_ERROR: Lazy<ExceptionClass> =
+    Lazy::new(|ruby| kobako_error_class(ruby, "TrapError"));
+
+pub(crate) static TIMEOUT_ERROR: Lazy<ExceptionClass> =
+    Lazy::new(|ruby| kobako_error_class(ruby, "TimeoutError"));
+
+pub(crate) static MEMORY_LIMIT_ERROR: Lazy<ExceptionClass> =
+    Lazy::new(|ruby| kobako_error_class(ruby, "MemoryLimitError"));
+
+pub(crate) static SANDBOX_ERROR: Lazy<ExceptionClass> =
+    Lazy::new(|ruby| kobako_error_class(ruby, "SandboxError"));
+
+/// Build a `MagnusError` in `class` carrying `msg` — the shared body of
+/// the named `*_err` constructors below, which differ only in which
+/// error-class `Lazy` they target.
+fn error_in(ruby: &Ruby, class: &Lazy<ExceptionClass>, msg: impl Into<String>) -> MagnusError {
+    MagnusError::new(ruby.get_inner(class), msg.into())
+}
+
+/// Construct a `Kobako::TrapError` magnus error. Used for every
+/// invocation-time wasmtime engine failure that is not a configured-cap
+/// trap — missing exports, allocation faults, memory write/read failures.
+/// Construction-time setup failures use `setup_err`, not this.
+pub(crate) fn trap_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
+    error_in(ruby, &TRAP_ERROR, msg)
+}
+
+/// Construct a `Kobako::SetupError` magnus error. Used for every
+/// construction-time failure on the `Runtime.from_path` path before any
+/// invocation runs — unreadable artifact, bytes that are not a valid Wasm
+/// module, or engine / linker / instantiation setup failure. The
+/// `ModuleNotBuiltError` subclass (artifact absent) is
+/// raised through `MODULE_NOT_BUILT_ERROR` directly.
+pub(crate) fn setup_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
+    error_in(ruby, &SETUP_ERROR, msg)
+}
+
+/// Construct a `Kobako::TimeoutError` magnus error. Surfaces the
+/// wall-clock cap path with the verb prefix added
+/// by `Kobako::Sandbox#invoke!`.
+pub(crate) fn timeout_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
+    error_in(ruby, &TIMEOUT_ERROR, msg)
+}
+
+/// Construct a `Kobako::MemoryLimitError` magnus error. Surfaces the
+/// linear-memory cap path with the verb prefix
+/// added by `Kobako::Sandbox#invoke!`.
+pub(crate) fn memory_limit_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
+    error_in(ruby, &MEMORY_LIMIT_ERROR, msg)
+}
+
+/// Construct a `Kobako::SandboxError` magnus error. Used for the
+/// host-side pre-call faults the SPEC attributes to the sandbox / wire
+/// layer rather than the Wasm engine — currently the `#run` invocation
+/// envelope reservation failure (`__kobako_alloc` returns 0).
+/// The runtime is intact, so this must not be a
+/// `TrapError`: no discard-and-recreate recovery is owed to the caller.
+pub(crate) fn sandbox_err(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
+    error_in(ruby, &SANDBOX_ERROR, msg)
+}

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

@@ -0,0 +1,188 @@
+//! 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/runtime/instance_pre.rs

@@ -20,8 +20,9 @@ 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, setup_err, trap};
+use super::{dispatch, trap};
 
 static INSTANCE_PRE_CACHE: OnceLock<Mutex<HashMap<PathBuf, InstancePre<Invocation>>>> =
     OnceLock::new();

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

@@ -13,8 +13,8 @@ use std::time::Instant;
 use magnus::{Error as MagnusError, Ruby};
 use wasmtime::{StoreContextMut, UpdateDeadline};
 
+use super::errors::{memory_limit_err, setup_err, timeout_err, trap_err};
 use super::invocation::{Invocation, MemoryLimitTrap, TimeoutTrap};
-use super::{memory_limit_err, setup_err, timeout_err, trap_err};
 
 /// Epoch-deadline callback installed on every Store. Read the per-run
 /// wall-clock deadline from `Invocation` and trap with