kobako 0.9.2 → 0.11.0

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

@@ -1,41 +1,48 @@
-//! Cached wasmtime export handles for the host-driven ABI surface.
+//! Per-invocation wasmtime export handles for the host-driven ABI
+//! surface.
 //!
-//! `Runtime::from_path` resolves the three docs/wire-codec.md ABI exports
-//! the run path drives (`__kobako_eval` / `__kobako_run` /
-//! `__kobako_take_outcome`) once at construction and stores their typed
-//! handles here, so each `#eval` / `#run` calls a cached handle rather than
-//! re-resolving the export by name. Distinct from `super::cache` (the
-//! process-wide Engine / Module cache): this caches *which guest function
-//! to call*, per `Runtime`.
+//! `Runtime::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
+//! carries *which guest function to call*, per invocation.
 //!
-//! `__kobako_alloc` is deliberately absent — only `super::dispatch` calls
-//! it, and it does so through `Caller::get_export` on the wasmtime side.
+//! `super::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.
 
-use wasmtime::{AsContextMut, Instance as WtInstance, TypedFunc};
+use wasmtime::{AsContextMut, Instance as WtInstance, Memory, TypedFunc};
 
-use super::invocation::StoreCell;
-
-/// The cached host-driven export handles. Each is `Option` because test
+/// 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`) when a handle is `None`.
+/// `Kobako::TrapError` (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
+/// no `Instance` field is kept.
 pub(crate) struct Exports {
     pub(crate) eval: Option<TypedFunc<(), ()>>,
     pub(crate) run: Option<TypedFunc<(i32, i32), ()>>,
     pub(crate) take_outcome: Option<TypedFunc<(), u64>>,
+    pub(crate) alloc: Option<TypedFunc<u32, u32>>,
+    pub(crate) memory: Option<Memory>,
 }
 
 impl Exports {
-    /// Best-effort lookup of the three host-driven exports against a
-    /// freshly instantiated module. Missing exports are not an error here
+    /// Best-effort lookup of the host-driven exports against a freshly
+    /// instantiated module. Missing exports are not an error here
     /// (the test fixture is a bare module); the host enforces presence at
     /// invocation time. Only the SPEC ABI shapes are accepted —
     /// `__kobako_eval` is `() -> ()`, `__kobako_run` is
-    /// `(env_ptr, env_len) -> ()`, `__kobako_take_outcome` is `() -> u64`
+    /// `(env_ptr, env_len) -> ()`, `__kobako_take_outcome` is `() -> u64`,
+    /// `__kobako_alloc` is `(len) -> ptr`
     /// (docs/wire-codec.md § ABI Signatures).
-    pub(crate) fn resolve(instance: &WtInstance, store: &StoreCell) -> Self {
-        let mut store_ref = store.borrow_mut();
-        let mut ctx = store_ref.as_context_mut();
+    pub(crate) fn resolve(instance: &WtInstance, mut ctx: impl AsContextMut) -> Self {
         Self {
             eval: instance
                 .get_typed_func::<(), ()>(&mut ctx, "__kobako_eval")
@@ -46,6 +53,10 @@ impl Exports {
             take_outcome: instance
                 .get_typed_func::<(), u64>(&mut ctx, "__kobako_take_outcome")
                 .ok(),
+            alloc: instance
+                .get_typed_func::<u32, u32>(&mut ctx, "__kobako_alloc")
+                .ok(),
+            memory: instance.get_memory(&mut ctx, "memory"),
         }
     }
 }

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

@@ -0,0 +1,97 @@
+//! Per-path cache of pre-instantiated wasmtime artifacts.
+//!
+//! The `Linker` wiring (the WASI preview1 import set plus the
+//! `__kobako_dispatch` host import) and its type-check against the
+//! compiled Module are identical for every `Kobako::Runtime` on the
+//! same Guest Binary — both host closures read all their state from
+//! the `Invocation` inside the calling Store, never from the Runtime.
+//! Caching the resolved `InstancePre` per path leaves only the
+//! `instantiate` call itself on the `Runtime.from_path` hot path.
+//!
+//! Concurrency: see `super::cache` — under Ruby's GVL the Mutex serves
+//! `Sync` bounds rather than real contention.
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::sync::{Mutex, OnceLock};
+
+use magnus::{Error as MagnusError, Ruby};
+use wasmtime::{Caller, InstancePre, Linker};
+use wasmtime_wasi::p1;
+
+use super::cache::{cached_module, shared_engine};
+use super::invocation::Invocation;
+use super::{dispatch, setup_err, trap};
+
+static INSTANCE_PRE_CACHE: OnceLock<Mutex<HashMap<PathBuf, InstancePre<Invocation>>>> =
+    OnceLock::new();
+
+/// Look up `path` in the per-path `InstancePre` cache, wiring the
+/// Linker and resolving the Module's imports on a miss. Compilation
+/// faults surface through `cached_module`; import-resolution faults
+/// raise `Kobako::SetupError`.
+pub(crate) fn cached_instance_pre(path: &Path) -> Result<InstancePre<Invocation>, MagnusError> {
+    let cache = INSTANCE_PRE_CACHE.get_or_init(|| Mutex::new(HashMap::new()));
+
+    if let Some(pre) = cache
+        .lock()
+        .expect("instance_pre cache mutex poisoned")
+        .get(path)
+        .cloned()
+    {
+        return Ok(pre);
+    }
+
+    let module = cached_module(path)?;
+    let linker = build_linker()?;
+    let ruby = Ruby::get().expect("Ruby thread");
+    let pre = linker
+        .instantiate_pre(&module)
+        .map_err(|e| trap::instantiate_err(&ruby, e))?;
+    cache
+        .lock()
+        .expect("instance_pre cache mutex poisoned")
+        .insert(path.to_path_buf(), pre.clone());
+    Ok(pre)
+}
+
+/// Build the host-import `Linker` every Guest Binary instantiates
+/// against.
+fn build_linker() -> Result<Linker<Invocation>, MagnusError> {
+    let ruby = Ruby::get().expect("Ruby thread");
+    let mut linker: Linker<Invocation> = Linker::new(shared_engine()?);
+
+    // Wire the wasmtime-wasi preview1 WASI imports. Routes guest fd 1/2
+    // to the MemoryOutputPipes set up before each run via
+    // `Runtime::eval`. The closure pulls a `&mut WasiP1Ctx` out of
+    // Invocation; the panic semantics live inside `Invocation::wasi_mut`
+    // so the wiring stays honest about its precondition.
+    p1::add_to_linker_sync(&mut linker, |state: &mut Invocation| state.wasi_mut())
+        .map_err(|e| setup_err(&ruby, format!("failed to set up the WASI runtime: {}", e)))?;
+
+    // `__kobako_dispatch` host import. Signature per docs/wire-codec.md
+    // § ABI Signatures:
+    //   (req_ptr: i32, req_len: i32) -> i64
+    // Decodes the Request bytes, dispatches via the Ruby-side
+    // dispatch Proc (bound per-Sandbox through `Runtime#on_dispatch=`),
+    // allocates a guest buffer through `__kobako_alloc`, writes
+    // the Response bytes there, and returns the packed
+    // `(ptr<<32)|len`. The dispatcher returns 0 on any wire-layer
+    // fault (including no Proc bound); see `dispatch::handle`.
+    linker
+        .func_wrap(
+            "env",
+            "__kobako_dispatch",
+            |mut caller: Caller<'_, Invocation>, req_ptr: i32, req_len: i32| -> i64 {
+                dispatch::handle(&mut caller, req_ptr, req_len)
+            },
+        )
+        .map_err(|e| {
+            setup_err(
+                &ruby,
+                format!("failed to set up the host callback bridge: {}", e),
+            )
+        })?;
+
+    Ok(linker)
+}

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

@@ -2,29 +2,27 @@
 //! [SPEC.md Single-Invocation Slot] (one `Invocation` per OS thread
 //! for the lifetime of one `Runtime::eval` / `Runtime::run` call).
 //!
-//! Owned by `StoreCell` (a `RefCell` shim wrapping `wasmtime::Store`)
-//! and threaded through every host import — the `__kobako_dispatch`
-//! dispatcher reads the bound dispatch Proc, while the run-path methods
-//! on `crate::runtime::Runtime` install fresh WASI context + pipes
-//! before every invocation (docs/behavior.md B-03 / B-04).
+//! Owned as the data of each per-invocation `wasmtime::Store`
+//! and threaded through every host import —
+//! the `__kobako_dispatch` dispatcher reads the bound dispatch Proc,
+//! while the run-path methods on `crate::runtime::Runtime` install the
+//! invocation's WASI context + pipes at Store creation.
 //!
 //! The slot also carries the per-invocation wall-clock deadline
-//! (docs/behavior.md B-01, E-19) and the per-invocation linear-memory
-//! delta cap `MemoryLimiter` (docs/behavior.md B-01, E-20). Both are
+//! and the per-invocation linear-memory
+//! delta cap `MemoryLimiter`. Both are
 //! read from the wasmtime `epoch_deadline_callback` / `ResourceLimiter`
-//! callbacks installed in `crate::runtime::Runtime::from_path`. The
+//! callbacks installed in `crate::runtime::Runtime::new_store`. The
 //! memory cap measures only the `memory.grow` delta past the linear-
-//! memory size captured at invocation entry — the mruby image's
-//! initial allocation and prior invocations' watermark are outside the
-//! budget.
+//! memory size captured at invocation entry — the image's initial
+//! allocation is outside the budget.
 //!
 //! [SPEC.md Single-Invocation Slot]: ../../../../SPEC.md
 
-use std::cell::{Ref, RefCell, RefMut};
 use std::time::{Duration, Instant};
 
 use magnus::{value::Opaque, Value};
-use wasmtime::{ResourceLimiter, Store as WtStore};
+use wasmtime::ResourceLimiter;
 use wasmtime_wasi::p1::WasiP1Ctx;
 use wasmtime_wasi::p2::pipe::MemoryOutputPipe;
 
@@ -53,7 +51,7 @@ impl Invocation {
     /// Build a fresh per-Store host state. `memory_limit` carries the
     /// `Sandbox#memory_limit` cap in bytes (or `None` to disable the cap);
     /// it is read from the wasmtime `ResourceLimiter` callback every
-    /// time the guest grows linear memory (docs/behavior.md B-01, E-20).
+    /// time the guest grows linear memory.
     pub(super) fn new(memory_limit: Option<usize>) -> Self {
         Self {
             wasi: None,
@@ -70,7 +68,7 @@ impl Invocation {
     /// Install a freshly-built WASI context plus the matching stdout/stderr
     /// pipe clones. Called from `crate::runtime::Runtime::eval` /
     /// `crate::runtime::Runtime::run` at the top of every guest
-    /// invocation (docs/behavior.md B-03 / B-04).
+    /// invocation.
     pub(super) fn install_wasi(
         &mut self,
         wasi: WasiP1Ctx,
@@ -128,20 +126,20 @@ impl Invocation {
 
     /// Replace the per-run wall-clock deadline. `Some(at)` makes the
     /// epoch-deadline callback trap once `Instant::now() >= at`; `None`
-    /// disables the cap. Called at the top of every `#run` (docs/behavior.md B-01).
+    /// disables the cap. Called at the top of every `#run`.
     pub(super) fn set_deadline(&mut self, deadline: Option<Instant>) {
         self.deadline = deadline;
     }
 
     /// Return the current per-run deadline. Read from the epoch-deadline
-    /// callback installed by `crate::runtime::Runtime::from_path`.
+    /// callback installed by `crate::runtime::Runtime::new_store`.
     pub(super) fn deadline(&self) -> Option<Instant> {
         self.deadline
     }
 
     /// Mutable handle to the embedded `MemoryLimiter`. Required by
     /// the wasmtime `ResourceLimiter` callback wiring in
-    /// `crate::runtime::Runtime::from_path`
+    /// `crate::runtime::Runtime::new_store`
     /// (`store.limiter(|state| state.limiter_mut())`); kept private to
     /// the wasm submodule so the only public surface for arming the
     /// cap goes through `Invocation::arm_memory_cap` /
@@ -150,7 +148,7 @@ impl Invocation {
         &mut self.limiter
     }
 
-    /// Arm the docs/behavior.md E-20 memory cap for one guest run with
+    /// Arm the memory cap for one guest run with
     /// the current linear-memory size as the baseline. The limiter
     /// charges only the `memory.grow` delta past `baseline` against
     /// the cap, so the mruby image's initial allocation and the
@@ -163,23 +161,23 @@ impl Invocation {
         self.limiter.activate(baseline);
     }
 
-    /// Disarm the docs/behavior.md E-20 memory cap. See
+    /// Disarm the memory cap. See
     /// `Invocation::arm_memory_cap`.
     pub(super) fn disarm_memory_cap(&mut self) {
         self.limiter.deactivate();
     }
 
-    /// Stamp the wall-clock entry instant for the docs/behavior.md
-    /// B-35 `wall_time` measurement. Called at the top of every
+    /// Stamp the wall-clock entry instant for the `wall_time`
+    /// measurement. Called at the top of every
     /// invocation immediately before the guest export call so the
-    /// bracket matches the `timeout` deadline accounting (B-01) and
+    /// bracket matches the `timeout` deadline accounting and
     /// excludes post-run host bookkeeping such as `OUTCOME_BUFFER`
     /// decoding.
     pub(super) fn start_wall_clock(&mut self) {
         self.wall_entry = Some(Instant::now());
     }
 
-    /// Close the docs/behavior.md B-35 `wall_time` measurement
+    /// Close the `wall_time` measurement
     /// started by `Invocation::start_wall_clock`. Idempotent — a
     /// stop with no matching start (e.g. if the guest export call
     /// never executed because of a host-side allocation failure)
@@ -191,13 +189,13 @@ impl Invocation {
     }
 
     /// Return the wall-clock duration the most recent invocation
-    /// spent inside the guest export call (docs/behavior.md B-35).
+    /// spent inside the guest export call.
     /// Zero before the first invocation.
     pub(super) fn wall_time(&self) -> Duration {
         self.wall_time
     }
 
-    /// Return the docs/behavior.md B-35 `memory_peak` — the high-
+    /// Return the `memory_peak` — the high-
     /// water mark of the per-invocation `memory.grow` delta past the
     /// linear-memory size captured at invocation entry. Zero before
     /// the first invocation.
@@ -207,7 +205,7 @@ impl Invocation {
 }
 
 /// Resource limiter that enforces the per-invocation `memory_limit`
-/// cap from docs/behavior.md B-01 / E-20.
+/// cap.
 ///
 /// `max_memory` is the byte cap on per-invocation growth (`None` disables
 /// the cap). `baseline` is the linear-memory size captured at invocation
@@ -250,9 +248,9 @@ impl MemoryLimiter {
     /// the cap is dormant by default — the module's declared initial
     /// memory is allocated during `Linker::instantiate` and the
     /// per-invocation budget excludes anything that existed before
-    /// arming (docs/behavior.md B-01 Notes, E-20). Also clears the
+    /// arming. Also clears the
     /// per-invocation `MemoryLimiter::peak` high-water so the
-    /// docs/behavior.md B-35 `memory_peak` accounting restarts from
+    /// `memory_peak` accounting restarts from
     /// zero for the new invocation.
     fn activate(&mut self, baseline: usize) {
         self.baseline = baseline;
@@ -271,9 +269,9 @@ impl MemoryLimiter {
     /// Return the high-water mark of the per-invocation
     /// `memory.grow` delta past `baseline` observed since the last
     /// `MemoryLimiter::activate`. Read after the guest export
-    /// returns to populate `Kobako::Usage#memory_peak`
-    /// (docs/behavior.md B-35). Pinned to the last accepted grow —
-    /// rejected `desired` values that trip the docs/behavior.md E-20
+    /// returns to populate `Kobako::Usage#memory_peak`.
+    /// Pinned to the last accepted grow —
+    /// rejected `desired` values that trip the memory
     /// cap never update the peak, so the reported value never exceeds
     /// `memory_limit`.
     pub(super) fn peak(&self) -> usize {
@@ -313,8 +311,9 @@ impl ResourceLimiter for MemoryLimiter {
     }
 }
 
-/// Marker error returned from `MemoryLimiter::memory_growing` on
-/// docs/behavior.md E-20. Downcast from the wasmtime trap error to surface as
+/// Marker error returned from `MemoryLimiter::memory_growing` when the
+/// per-invocation memory cap is exceeded. Downcast from the wasmtime
+/// trap error to surface as
 /// `Kobako::MemoryLimitError` on the Ruby side. Callers use the
 /// `Display` impl below — no field is read directly — so the inner
 /// state stays private.
@@ -348,9 +347,9 @@ impl std::fmt::Display for MemoryLimitTrap {
 
 impl std::error::Error for MemoryLimitTrap {}
 
-/// Marker error returned from the epoch-deadline callback on
-/// docs/behavior.md E-19. Downcast from the wasmtime trap error to
-/// surface as `Kobako::TimeoutError` on the Ruby side.
+/// Marker error returned from the epoch-deadline callback when the
+/// wall-clock deadline is exceeded. Downcast from the wasmtime trap
+/// error to surface as `Kobako::TimeoutError` on the Ruby side.
 #[derive(Debug)]
 pub(crate) struct TimeoutTrap;
 
@@ -362,62 +361,6 @@ impl std::fmt::Display for TimeoutTrap {
 
 impl std::error::Error for TimeoutTrap {}
 
-/// Interior-mutability wrapper around `wasmtime::Store<Invocation>`.
-///
-/// Magnus requires `Send + Sync` for wrapped types. `wasmtime::Store` is not
-/// `Sync`, so we wrap it in a `RefCell`. `RefCell` alone is sufficient
-/// because magnus enforces single-threaded GVL access from Ruby; `Send` and
-/// `Sync` are asserted via the unsafe impls below.
-pub(super) struct StoreCell {
-    inner: RefCell<WtStore<Invocation>>,
-}
-
-impl StoreCell {
-    /// Wrap a freshly-built `wasmtime::Store<Invocation>` so it can be owned
-    /// by the magnus-wrapped `Runtime`.
-    pub(super) fn new(store: WtStore<Invocation>) -> Self {
-        Self {
-            inner: RefCell::new(store),
-        }
-    }
-
-    /// Immutable borrow of the wrapped Store. Panics if a `borrow_mut()`
-    /// is currently live — matches `RefCell::borrow` semantics.
-    pub(super) fn borrow(&self) -> Ref<'_, WtStore<Invocation>> {
-        self.inner.borrow()
-    }
-
-    /// Mutable borrow of the wrapped Store. Panics if any other borrow is
-    /// currently live — matches `RefCell::borrow_mut` semantics.
-    pub(super) fn borrow_mut(&self) -> RefMut<'_, WtStore<Invocation>> {
-        self.inner.borrow_mut()
-    }
-}
-
-// SAFETY: magnus requires `Send + Sync` on `#[magnus::wrap]` types. Both
-// claims hold under the GVL invariant:
-//
-//   * Send — `wasmtime::Store<Invocation>` is itself `Send` (verified
-//     upstream by wasmtime; see `wasmtime::Store`'s trait impls).
-//     `RefCell<T>: Send` whenever `T: Send`. The remaining stored state
-//     (`Invocation`) holds `Opaque<Value>` for the Ruby Server handle —
-//     `Opaque<Value>` is documented as `Send` by magnus precisely so
-//     wrapped objects can satisfy this bound.
-//
-//   * Sync — `RefCell` is *not* `Sync` in the general Rust sense
-//     (concurrent `borrow_mut` is UB). We assert `Sync` here because the
-//     GVL serialises every call into Ruby C and every entry into magnus-
-//     wrapped methods onto a single OS thread at a time: by the time the
-//     `Sync` bound matters, magnus has already established that only one
-//     thread can be inside the wrapper. Cross-thread mutation cannot
-//     occur. If a future magnus release adopts a thread model that
-//     permits concurrent access to wrapped objects, this assertion would
-//     have to revert and `StoreCell` would need to switch to
-//     `Mutex<wasmtime::Store<…>>` — but as of magnus 0.8 the contract
-//     holds.
-unsafe impl Send for StoreCell {}
-unsafe impl Sync for StoreCell {}
-
 #[cfg(test)]
 mod tests {
     //! Unit tests for `MemoryLimiter` — the per-invocation memory

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

@@ -17,7 +17,7 @@ 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` (docs/behavior.md B-01) and trap with
+/// wall-clock deadline from `Invocation` and trap with
 /// `TimeoutTrap` once the deadline has passed; otherwise extend the
 /// next check by one tick of the process-wide epoch ticker. When the
 /// deadline is `None` the callback should not fire under normal
@@ -41,9 +41,9 @@ pub(super) fn epoch_deadline_callback(
 /// without the magnus surface.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum TrapClass {
-    /// docs/behavior.md E-19 wall-clock cap path.
+    /// Wall-clock cap path.
     Timeout,
-    /// docs/behavior.md E-20 linear-memory cap path.
+    /// Linear-memory cap path.
     MemoryLimit,
     /// Any other wasmtime error — surfaces as the base
     /// `Kobako::TrapError`.
@@ -117,8 +117,8 @@ fn other_trap_message(err: &wasmtime::Error) -> String {
 }
 
 /// Map an instantiation error to `Kobako::SetupError`. Instantiation runs
-/// during `from_path` construction, before any invocation — docs/behavior.md
-/// E-41 classifies every such failure as a construction setup fault, not a
+/// during `from_path` construction, before any invocation — every such
+/// failure is a construction setup fault, not a
 /// per-invocation cap outcome. The memory cap is dormant during
 /// instantiation (see `Invocation::arm_memory_cap` /
 /// `Invocation::disarm_memory_cap`) and the epoch deadline is not yet