kobako 0.28.0 → 0.30.0

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

@@ -5,113 +5,162 @@
 //! dispatch seam touches `magnus`. The wasm-side dispatch path
 //! (`kobako_wasmtime`'s dispatch module) sees only the contract traits.
 
-use core::cell::Cell;
+use core::cell::{Cell, RefCell};
 use core::ptr::NonNull;
+use std::sync::Arc;
 
+use magnus::rb_sys::AsRawValue;
 use magnus::value::{Opaque, ReprValue};
-use magnus::{method, prelude::*, Error as MagnusError, RClass, RString, Ruby, Symbol, Value};
+use magnus::{
+    method, prelude::*, Error as MagnusError, RModule, RString, Ruby, Symbol, TypedData, Value,
+};
 
 use kobako_runtime::dispatch::DispatchHandler;
 use kobako_runtime::yielder::Yielder;
 use kobako_transport::envelope::{Call, Fault, FaultKind, Reply, Target, YieldReply};
 
-/// The names the host `Transport::Yielder` branches on — one per Yield
-/// Reply arm. Neutral Symbols rather than the envelope's tag bytes, the
-/// same way `Snapshot#outcome` names its arms: the core envelope is this
-/// side's to read, so no byte value of it reaches Ruby.
+/// The names each side of this seam branches on — one per Reply and
+/// Yield Reply arm. Neutral Symbols rather than the envelope's tag bytes,
+/// the same way `Snapshot#outcome` names its arms: the Envelope is
+/// this side's to read, so no byte value of it reaches Ruby.
 const ARM_OK: &str = "ok";
+const ARM_FAULT: &str = "fault";
 const ARM_BREAK: &str = "break";
 const ARM_ERROR: &str = "error";
 const ARM_UNSUPPORTED: &str = "unsupported";
 
-/// Runs after `Kobako::Runtime` is defined, so the `#[magnus::wrap]` class
-/// name resolves before any object is wrapped.
-pub(super) fn register(runtime_class: RClass) -> Result<(), MagnusError> {
+/// Defines the class the `#[magnus::wrap]` name resolves to, and looks it
+/// up once, before any object is wrapped.
+pub(super) fn register(kobako: RModule) -> Result<(), MagnusError> {
     let ruby = Ruby::get().expect("Ruby thread");
-    let class = runtime_class.define_class("GuestYielder", ruby.class_object())?;
+    let class = kobako.define_class("GuestYielder", ruby.class_object())?;
     class.define_method("call", method!(GuestYielder::call, 1))?;
+    GuestYielder::class(&ruby);
     Ok(())
 }
 
-/// Frame-scoped Ruby handle that lets the dispatch `Proc` re-enter the
-/// guest to run a yielded block. It wraps the active `&mut dyn Yielder`
-/// for exactly one `__kobako_upcall` frame: the bridge builds one, hands
-/// it to the `Proc` as the second argument, and `invalidate`s it the
+/// The Yielders one invocation's open Calls lent, innermost last. A yield
+/// re-enters the guest only through the innermost, whatever Call's block
+/// it runs, so no Yielder is reached while a later Call holds the guest.
+///
+/// This is the one place the host↔guest re-entry still costs raw
+/// pointers: `magnus`' `funcall` sits between two Rust frames, so the
+/// typed `&mut dyn Yielder` cannot cross it and is erased here. Each
+/// pointer is pushed before its frame's `funcall` and popped after it, so
+/// every pointer on the stack belongs to a frame still on the Rust stack.
+#[derive(Default)]
+struct OpenFrames(RefCell<Vec<NonNull<dyn Yielder>>>);
+
+// SAFETY: the stack is pushed and popped by the dispatch frames on the
+// fiber driving the invocation, and read only by a `GuestYielder` that
+// refuses every other fiber, so it is never reached from another thread.
+unsafe impl Send for OpenFrames {}
+unsafe impl Sync for OpenFrames {}
+
+impl OpenFrames {
+    /// Lend `yielder` for the frame `run` answers, popping it however
+    /// `run` returns.
+    fn lend<T>(&self, yielder: &mut dyn Yielder, run: impl FnOnce() -> T) -> T {
+        struct Pop<'a>(&'a OpenFrames);
+        impl Drop for Pop<'_> {
+            fn drop(&mut self) {
+                self.0 .0.borrow_mut().pop();
+            }
+        }
+        // SAFETY: the lifetime is erased only for as long as `Pop` keeps
+        // the pointer on the stack, which ends before `yielder` does.
+        let ptr: NonNull<dyn Yielder> = unsafe {
+            std::mem::transmute::<NonNull<dyn Yielder + '_>, NonNull<dyn Yielder + 'static>>(
+                NonNull::from(yielder),
+            )
+        };
+        self.0.borrow_mut().push(ptr);
+        let _pop = Pop(self);
+        run()
+    }
+
+    fn innermost(&self) -> Option<NonNull<dyn Yielder>> {
+        self.0.borrow().last().copied()
+    }
+}
+
+/// Frame-scoped Ruby handle that lets the dispatch `Proc` run the block
+/// one Call carried. The bridge builds one per `__kobako_upcall` frame,
+/// hands it to the `Proc` as the last argument, and `invalidate`s it the
 /// instant the `Proc` returns. A guest block stashed and called after that
 /// frame normally raises `LocalJumpError` at the Ruby
 /// `Transport::Yielder` net — invalidated in the dispatcher's `ensure`,
 /// which fires before this handle is reached. This inner invalidation is
-/// the backstop behind that outer net: it keeps `call`'s `unsafe`
-/// `NonNull` deref from touching freed stack should the outer net ever be
-/// bypassed, so neither net is redundant.
+/// the backstop behind that outer net, so neither net is redundant.
+///
+/// The guest's Store is entered from the fiber that drives the
+/// invocation, and only from it: another fiber runs on its own native
+/// stack, which wasmtime's stack limit and the value budget never saw. A
+/// block run from any other fiber, including one on another thread, is
+/// refused before it reaches the guest.
 ///
-/// This is the single, explicit, frame-scoped FFI pointer the host↔guest
-/// re-entry still costs: `magnus`' `funcall` sits between two Rust frames,
-/// so the typed `&mut dyn Yielder` cannot cross it and is erased to a raw
-/// pointer here. Unlike the dispatch `Proc`, this handle holds **no Ruby
-/// `Value`**, so GC has nothing to trace through it — it needs no `mark`.
-#[magnus::wrap(class = "Kobako::Runtime::GuestYielder", free_immediately, size)]
+/// It holds **no Ruby `Value`**, so GC has nothing to trace through it —
+/// it needs no `mark`. The driving fiber is kept as its raw identity,
+/// compared only while the frame is live and so while that fiber is.
+#[magnus::wrap(class = "Kobako::GuestYielder", free_immediately, size)]
 struct GuestYielder {
-    yielder: Cell<Option<NonNull<dyn Yielder>>>,
+    frame: u32,
+    open: Arc<OpenFrames>,
+    live: Cell<bool>,
+    fiber: rb_sys::VALUE,
 }
 
-// SAFETY: magnus requires `Send + Sync` on wrapped types. The raw pointer
-// is created, used, and invalidated within a single `__kobako_upcall`
-// frame on the one Ruby thread that owns the active Invocation; it is
-// never read from another thread.
+// SAFETY: magnus requires `Send + Sync` on wrapped types. `call` refuses
+// every fiber but the one driving the invocation, so the frames it reaches
+// are only ever read on that fiber's thread.
 unsafe impl Send for GuestYielder {}
 unsafe impl Sync for GuestYielder {}
 
 impl GuestYielder {
-    /// Erase the frame-scoped `&mut dyn Yielder` into a Ruby-owned handle.
-    /// Safety contract for the caller: `invalidate` MUST run before the
-    /// borrow this pointer came from ends (i.e. before the dispatch frame
-    /// returns).
-    fn new(yielder: &mut dyn Yielder) -> Self {
-        let ptr = NonNull::from(yielder);
-        // Erase the borrow's lifetime to `'static`; the pointer is only
-        // ever dereferenced while it is still `Some` (i.e. `invalidate`
-        // has not run), so the referent is guaranteed live.
-        let ptr: NonNull<dyn Yielder> = unsafe {
-            std::mem::transmute::<NonNull<dyn Yielder + '_>, NonNull<dyn Yielder + 'static>>(ptr)
-        };
+    fn new(ruby: &Ruby, frame: u32, open: Arc<OpenFrames>) -> Self {
         Self {
-            yielder: Cell::new(Some(ptr)),
+            frame,
+            open,
+            live: Cell::new(true),
+            fiber: ruby.fiber_current().as_raw(),
         }
     }
 
     /// Runs the instant the dispatch frame's `funcall` returns, so a guest
-    /// block stashed beyond its frame raises instead of dereferencing freed
-    /// stack.
+    /// block stashed beyond its frame raises instead of re-entering.
     fn invalidate(&self) {
-        self.yielder.set(None);
+        self.live.set(false);
     }
 
     /// The arm is named here off the decoded Yield Reply, so the host
     /// `Transport::Yielder` decodes only a payload.
     fn call(&self, args: RString) -> Result<(Symbol, RString, Option<String>), MagnusError> {
         let ruby = Ruby::get().expect("Ruby handle unavailable in the block bridge");
-        let Some(mut ptr) = self.yielder.get() else {
+        let innermost = self.open.innermost().filter(|_| self.live.get());
+        let Some(mut ptr) = innermost else {
             return Err(super::errors::trap_err(
                 &ruby,
                 "guest block invoked after the host dispatch frame returned",
             ));
         };
+        if ruby.fiber_current().as_raw() != self.fiber {
+            return Err(MagnusError::new(
+                ruby.exception_thread_error(),
+                "guest block called from a thread or fiber other than its invocation's",
+            ));
+        }
         let bytes = super::rstring_to_vec(args);
-        // SAFETY: `yielder` is `Some`, so `invalidate` has not run — the
-        // dispatch frame that lent the `&mut dyn Yielder` is still on the
-        // Rust stack, and each dispatch frame lends its own Yielder on the
-        // one thread driving the invocation, so no other frame aliases it.
-        // The borrow ends with this method.
+        // SAFETY: this frame is live, so the innermost frame — this one or
+        // a later Call — is still on the Rust stack with its Yielder lent.
+        // Only the innermost frame's Ruby code runs, so no other borrow of
+        // that Yielder is live; the borrow ends with this method.
         let yielder: &mut dyn Yielder = unsafe { ptr.as_mut() };
         let reply = yielder
-            .yield_to_block(&bytes)
+            .yield_to_block(self.frame, &bytes)
             .map_err(|t| super::errors::trap_to_magnus(&ruby, t))?;
         Ok(match reply {
             YieldReply::Ok(body) => (ruby.to_symbol(ARM_OK), ruby.str_from_slice(&body), None),
-            YieldReply::Break(body) => {
-                (ruby.to_symbol(ARM_BREAK), ruby.str_from_slice(&body), None)
-            }
+            YieldReply::Break => (ruby.to_symbol(ARM_BREAK), ruby.str_from_slice(&[]), None),
             YieldReply::Error(record) => (
                 ruby.to_symbol(ARM_ERROR),
                 ruby.str_new(&record.message),
@@ -136,19 +185,24 @@ impl GuestYielder {
 /// `Opaque` copy of the same handle.
 pub(super) struct RubyDispatchHandler {
     on_dispatch: Opaque<Value>,
+    open: Arc<OpenFrames>,
 }
 
 impl RubyDispatchHandler {
     pub(super) fn new(on_dispatch: Opaque<Value>) -> Self {
-        Self { on_dispatch }
+        Self {
+            on_dispatch,
+            open: Arc::default(),
+        }
     }
 }
 
 impl DispatchHandler for RubyDispatchHandler {
     /// Ruby decodes only the payload, through the codec it already owns,
     /// which keeps a large payload's strings shared with the buffer rather
-    /// than copied. The Proc folds every dispatch failure into the Reply's
-    /// fault arm, so a raise is a contract violation surfaced as `None`.
+    /// than copied. The Proc folds every `StandardError` into the Reply's
+    /// fault arm, so one escaping is a contract violation surfaced as
+    /// `None`.
     fn dispatch(&self, call: Call<'_>, yielder: &mut dyn Yielder) -> Option<Reply> {
         // The guest may be running GVL-free (`gvl: :release`); re-acquire the
         // GVL for the whole callback before touching any Ruby VALUE. In hold
@@ -171,34 +225,53 @@ impl DispatchHandler for RubyDispatchHandler {
             };
             // Hand the Proc a frame-scoped yielder object as its last arg and
             // invalidate it the instant the Proc returns, so a guest block that
-            // escapes the dispatch frame can never deref the freed stack
-            // pointer. `guest_yielder` holds no Ruby Value, so it needs no GC
-            // mark — the GC has nothing to trace through it.
-            let guest_yielder = ruby.obj_wrap(GuestYielder::new(yielder));
-            let answer: Result<(bool, RString, Option<RString>), magnus::Error> = proc_value
-                .funcall(
-                    "call",
-                    (
-                        target,
-                        ruby.str_new(call.method),
-                        call.block_given,
-                        ruby.str_from_slice(call.payload),
-                        guest_yielder,
-                    ),
-                );
+            // escapes the dispatch frame never re-enters the guest.
+            let guest_yielder =
+                ruby.obj_wrap(GuestYielder::new(&ruby, yielder.frame(), self.open.clone()));
+            let answer: Result<(Symbol, RString, Option<RString>), magnus::Error> =
+                self.open.lend(yielder, || {
+                    proc_value.funcall(
+                        "call",
+                        (
+                            target,
+                            ruby.str_new(call.method),
+                            call.block_given,
+                            ruby.str_from_slice(call.payload),
+                            guest_yielder,
+                        ),
+                    )
+                });
             guest_yielder.invalidate();
+            // The Proc rescues only StandardError, so what else escapes it
+            // is the host's own and is held for the host; a StandardError
+            // escaping breaks the Proc's contract.
+            let (arm, body, kind) = match answer {
+                Ok(answer) => answer,
+                Err(error) => {
+                    let _ = super::escape::hold(&ruby, error);
+                    return None;
+                }
+            };
             // The ok arm carries payload bytes the codec owns; the fault
             // arm carries the Fault's own two fields, which the envelope
             // types — so Ruby names a category rather than encoding one.
-            // A category outside the closed set cannot come from the
-            // public API, so it fails the dispatch rather than degrading.
-            answer.ok().and_then(|(ok, body, kind)| match ok {
-                true => Some(Reply::Ok(super::rstring_to_vec(body))),
-                false => {
-                    let kind = FaultKind::from_name(&kind?.to_string().ok()?)?;
-                    Some(Reply::Fault(Fault::new(kind, body.to_string().ok()?)))
-                }
-            })
+            // A block exit carries nothing, since nothing of it crosses.
+            // An arm or category outside the closed set cannot come from
+            // the public API, so it fails the dispatch rather than
+            // degrading.
+            match arm.name().ok()?.as_ref() {
+                ARM_OK => Some(Reply::Ok(super::rstring_to_vec(body))),
+                ARM_BREAK => Some(Reply::Break),
+                ARM_FAULT => Some(Reply::Fault(Fault::new(
+                    FaultKind::from_name(&kind?.to_string().ok()?)?,
+                    body.to_string().ok()?,
+                ))),
+                _ => None,
+            }
         })
     }
+
+    fn abandoned(&self) -> bool {
+        super::escape::pending()
+    }
 }

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

@@ -58,7 +58,7 @@ pub(super) fn trap_class(ruby: &Ruby, trap: &Trap) -> ExceptionClass {
     }
 }
 
-/// The verb prefix is left to `Kobako::Context#invoke!`.
+/// The verb prefix is left to `Kobako::Context#invoke`.
 pub(super) fn trap_to_magnus(ruby: &Ruby, trap: Trap) -> MagnusError {
     MagnusError::new(trap_class(ruby, &trap), trap.to_string())
 }

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

@@ -0,0 +1,67 @@
+//! What a Host App's callback raises that is not a `StandardError`:
+//! `Interrupt`, `exit`, `throw`, `Timeout`, and any interrupt delivered to the
+//! Thread while a run gives up the GVL. These belong to the host, so one is held
+//! here instead of answering the guest with it, the invocation ends at its next
+//! host call, and the run raises it again once control is back in Ruby.
+//!
+//! The slot is per thread, as each invocation runs on its caller's
+//! thread. A nested invocation takes what its own run held before the
+//! outer callback sees it, so the outer one holds it next.
+
+use std::cell::RefCell;
+
+use magnus::value::BoxValue;
+use magnus::{Error as MagnusError, Ruby, Value};
+
+thread_local! {
+    static ESCAPE: RefCell<Option<Escape>> = const { RefCell::new(None) };
+}
+
+/// The error and, when it carries one, its exception kept rooted while
+/// the guest finishes unwinding.
+struct Escape {
+    error: MagnusError,
+    _rooted: Option<BoxValue<Value>>,
+}
+
+/// Hold `error` unless it is a `StandardError`, which comes back for the
+/// callback to answer the guest with.
+pub(super) fn hold(ruby: &Ruby, error: MagnusError) -> Result<(), MagnusError> {
+    if error.is_kind_of(ruby.exception_standard_error()) {
+        return Err(error);
+    }
+    keep(error);
+    Ok(())
+}
+
+/// Run what is pending on this Thread, holding what it raises, whatever its
+/// class: no callback asked for it, so no guest is answered with it.
+pub(super) fn hold_interrupts() {
+    let ruby = Ruby::get().expect("a Thread that was not given up holds the GVL");
+    if let Err(error) = ruby.thread_check_ints() {
+        keep(error);
+    }
+}
+
+/// Keep `error` for the host; the first one kept wins.
+fn keep(error: MagnusError) {
+    ESCAPE.with(|held| {
+        held.borrow_mut().get_or_insert_with(|| Escape {
+            _rooted: error.value().map(BoxValue::new),
+            error,
+        });
+    });
+}
+
+/// Whether this thread holds an error for the host.
+pub(super) fn pending() -> bool {
+    ESCAPE.with(|held| held.borrow().is_some())
+}
+
+/// Raise what was held, once the run is back in Ruby.
+pub(super) fn resume() -> Result<(), MagnusError> {
+    match ESCAPE.with(|held| held.borrow_mut().take()) {
+        Some(held) => Err(held.error),
+        None => Ok(()),
+    }
+}

data/ext/kobako/src/runtime/filesystem/grants.rs

@@ -0,0 +1,107 @@
+//! A Sandbox's Mounts as contract Grants: refused at `mount` time and
+//! built afresh for every invocation by the same rules, each mount's
+//! block standing in for its access.
+
+use std::sync::Arc;
+
+use magnus::value::{Opaque, ReprValue};
+use magnus::{prelude::*, Error as MagnusError, RArray, RString, Ruby, Symbol, Value};
+
+use kobako_runtime::grant::Grant;
+use kobako_runtime::mount::{Access, Mount, Policy};
+
+use super::to_filesystem;
+use crate::runtime::pinned_value::PinnedValue;
+use crate::runtime::{escape, gvl};
+
+/// Refuse a Mount at `mount` time by the same rules an invocation builds
+/// it with, so a mistake raises where it was made.
+pub(in crate::runtime) fn validate_mount(
+    at: Value,
+    access: Value,
+    filesystem: Value,
+) -> Result<(), MagnusError> {
+    to_mount(at, access, filesystem).map(drop)
+}
+
+/// The Mount a Sandbox's `[at, access, filesystem]` stands for: one owner
+/// of the path, access, and Filesystem rules.
+fn to_mount(at: Value, access: Value, filesystem: Value) -> Result<Mount, MagnusError> {
+    let ruby = Ruby::get().expect("Ruby thread");
+    let at = RString::try_convert(at)?.to_string()?;
+    let access = to_access(access)?;
+    Mount::new(at, to_filesystem(filesystem)?, access)
+        .map_err(|err| MagnusError::new(ruby.exception_arg_error(), err.to_string()))
+}
+
+fn to_access(access: Value) -> Result<Access, MagnusError> {
+    let name = Symbol::from_value(access)
+        .map(|symbol| symbol.name())
+        .transpose()?;
+    match name.as_deref() {
+        Some("read") => Ok(Access::Read),
+        Some("read_write") => Ok(Access::ReadWrite),
+        _ => Err(MagnusError::new(
+            Ruby::get().expect("Ruby thread").exception_arg_error(),
+            format!(
+                "access must be :read or :read_write, got {}",
+                access.inspect()
+            ),
+        )),
+    }
+}
+
+/// A mount's block, asked what its access allows. A block raising a
+/// StandardError refuses, so the guest's open fails and its script goes
+/// on; anything else it raises is held for the host.
+struct RubyPolicy {
+    block: Opaque<Value>,
+}
+
+impl Policy for RubyPolicy {
+    fn allows(&self, path: &str, access: Access) -> bool {
+        gvl::reenter(|| {
+            let ruby = Ruby::get().expect("Ruby handle unavailable in a mount's block");
+            let block: Value = ruby.get_inner(self.block);
+            let access = ruby.to_symbol(match access {
+                Access::Read => "read",
+                Access::ReadWrite => "read_write",
+            });
+            block
+                .funcall::<_, _, Value>("call", (ruby.str_new(path), access))
+                .map(|answer| answer.to_bool())
+                .unwrap_or_else(|error| {
+                    let _ = escape::hold(&ruby, error);
+                    false
+                })
+        })
+    }
+}
+
+/// The Grants one invocation carries, from the Sandbox's Mounts as
+/// `[at, access, filesystem, block]` entries, beside the pins keeping
+/// each Mount's filesystem and block in place while the guest may reach
+/// them; the caller holds both until the invocation returns.
+pub(in crate::runtime) fn to_grants(
+    ruby: &Ruby,
+    mounts: RArray,
+) -> Result<(Vec<Grant>, Vec<PinnedValue>), MagnusError> {
+    let mut grants = Vec::with_capacity(mounts.len());
+    let mut pins = Vec::with_capacity(mounts.len() * 2);
+    for index in 0..mounts.len() as isize {
+        let entry: RArray = mounts.entry(index)?;
+        let filesystem: Value = entry.entry(2)?;
+        pins.push(PinnedValue::new(ruby, filesystem));
+        let mount = to_mount(entry.entry(0)?, entry.entry(1)?, filesystem)?;
+        let block: Value = entry.entry(3)?;
+        grants.push(Grant::Mount(if block.is_nil() {
+            mount
+        } else {
+            pins.push(PinnedValue::new(ruby, block));
+            mount.with_policy(Arc::new(RubyPolicy {
+                block: Opaque::from(block),
+            }))
+        }));
+    }
+    Ok((grants, pins))
+}