kobako 0.28.0 → 0.29.0

data/crates/kobako-wasmtime/tests/preamble_flags.rs

@@ -1,5 +1,5 @@
-//! The bundled guest recognises no flag, so every flag a host sets meets
-//! the unrecognised path: a critical one must refuse the invocation under
+//! A flag the bundled guest does not recognise meets the unrecognised
+//! path: a critical one must refuse the invocation under
 //! its own class, and an advisory one must leave the run untouched.
 
 mod support;
@@ -26,6 +26,7 @@ fn eval_with_flag(critical: bool) -> Option<(Outcome, Vec<u8>)> {
             },
             &preamble,
             None,
+            &[],
         )
         .expect("the invocation must start");
     let Completion::Outcome(outcome) = snapshot.completion else {

data/crates/kobako-wasmtime/tests/snippet_compile.rs

@@ -11,14 +11,14 @@ use kobako_transport::envelope::{Flag, Outcome, Preamble, Snippet, Snippets};
 
 use support::bundled_driver as driver;
 
-fn preamble_of(entries: Vec<Snippet>) -> Preamble {
+fn preamble_with(entries: Vec<Snippet>) -> Preamble {
     let mut preamble = Preamble::default();
     preamble.snippets = Snippets { entries };
     preamble
 }
 
 fn greeter() -> Preamble {
-    preamble_of(vec![Snippet::Source {
+    preamble_with(vec![Snippet::Source {
         name: "Greeter".into(),
         body: "module Greeter; def self.hi = 'hi'; end".into(),
     }])
@@ -33,7 +33,7 @@ fn compiled_snippets_replay_in_a_later_invocation() {
     let bytecodes = driver
         .compile(&greeter())
         .expect("a source snippet that parses must compile");
-    let replay = preamble_of(
+    let replay = preamble_with(
         bytecodes
             .into_iter()
             .map(|body| Snippet::Bytecode { body })
@@ -47,6 +47,7 @@ fn compiled_snippets_replay_in_a_later_invocation() {
             },
             &replay,
             None,
+            &[],
         )
         .expect("the invocation must start");
 

data/crates/kobako-wasmtime/tests/support/mod.rs

@@ -18,17 +18,13 @@ pub fn bundled_driver() -> Option<Driver> {
         );
         return None;
     }
-    Some(
-        Driver::new(
-            Path::new(WASM),
-            Config {
-                timeout: Some(Duration::from_secs(10)),
-                memory_limit: None,
-                stdout_limit: None,
-                stderr_limit: None,
-                profile: Profile::Hermetic,
-            },
-        )
-        .expect("the Guest Binary must load"),
-    )
+    let mut config = Config::default();
+    config.timeout = Some(Duration::from_secs(10));
+    config.setup_timeout = Some(Duration::from_secs(10));
+    config.memory_limit = None;
+    config.stdout_limit = None;
+    config.stderr_limit = None;
+    config.open_file_limit = None;
+    config.profile = Profile::Hermetic;
+    Some(Driver::new(Path::new(WASM), config).expect("the Guest Binary must load"))
 }

data/crates/kobako-wasmtime/tests/unanswered_call.rs

@@ -0,0 +1,86 @@
+//! A Call the host could not answer as the Service meant still reaches the
+//! guest as an answer it can rescue, and the answer says why. The default
+//! frontends never hand the driver either failure, so only a handler
+//! written here reaches them.
+
+mod support;
+
+use std::sync::Arc;
+
+use kobako_runtime::{Completion, DispatchHandler, Entry, Runtime, Yielder};
+use kobako_transport::envelope::{Bindings, Call, Outcome, Preamble, Reply};
+
+/// Answers every Call with one byte more than a message carries.
+struct AnswersTooMuch;
+
+impl DispatchHandler for AnswersTooMuch {
+    fn dispatch(&self, _call: Call<'_>, _yielder: &mut dyn Yielder) -> Option<Reply> {
+        Some(Reply::Ok(vec![0xc0; (16 << 20) + 1]))
+    }
+}
+
+/// Breaks the handler contract by answering nothing.
+struct AnswersNothing;
+
+impl DispatchHandler for AnswersNothing {
+    fn dispatch(&self, _call: Call<'_>, _yielder: &mut dyn Yielder) -> Option<Reply> {
+        None
+    }
+}
+
+fn eval_against(handler: Arc<dyn DispatchHandler>, source: &[u8]) -> Option<Outcome> {
+    let driver = support::bundled_driver()?;
+    let mut preamble = Preamble::default();
+    preamble.bindings = Bindings {
+        paths: vec!["Svc".into()],
+    };
+    let snapshot = driver
+        .invoke(Entry::Eval { source }, &preamble, Some(handler), &[])
+        .expect("the invocation must start");
+    let Completion::Outcome(outcome) = snapshot.completion else {
+        panic!("the invocation must answer rather than trap");
+    };
+    Some(outcome)
+}
+
+// @behavior T-286
+#[test]
+fn an_answer_larger_than_a_message_raises_a_service_failure_naming_the_limit() {
+    let source = b"begin; Svc.go; rescue Kobako::ServiceError => e; e.message; end";
+    let Some(outcome) = eval_against(Arc::new(AnswersTooMuch), source) else {
+        return;
+    };
+
+    let mut expected = vec![0xd9, 0x4e];
+    expected.extend_from_slice(
+        b"Sandbox could not write the Service's answer: payload exceeds the 16 MiB limit",
+    );
+    assert_eq!(
+        outcome,
+        Outcome::Ok(expected),
+        "a Service answer past the message cap through Driver#invoke must raise a Service \
+         failure in the guest naming the limit"
+    );
+}
+
+// @behavior T-287
+#[test]
+fn a_call_the_host_could_not_answer_raises_a_transport_error_naming_why() {
+    let source = b"begin; Svc.go; rescue Kobako::Transport::Error => e; e.message; end";
+    let Some(outcome) = eval_against(Arc::new(AnswersNothing), source) else {
+        return;
+    };
+
+    let mut expected = vec![0xd9, 0x6a];
+    expected.extend_from_slice(
+        "a Sandbox callback raised an exception instead of returning a fault — please report \
+         this as a kobako bug"
+            .as_bytes(),
+    );
+    assert_eq!(
+        outcome,
+        Outcome::Ok(expected),
+        "a Call a handler answered with nothing through Driver#invoke must raise \
+         Kobako::Transport::Error in the guest naming why"
+    );
+}

data/crates/kobako-wasmtime/tests/unsupported_call.rs

@@ -35,6 +35,7 @@ fn a_call_the_host_does_not_serve_raises_unsupported_error_in_the_guest() {
             Entry::Eval { source },
             &preamble,
             Some(Arc::new(ServesNoCall)),
+            &[],
         )
         .expect("the invocation must start");
 

data/ext/kobako/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kobako"
-version = "0.28.0"
+version = "0.29.0"
 edition = "2021"
 authors = ["Aotokitsuruya <contact@aotoki.me>"]
 license = "Apache-2.0"
@@ -10,7 +10,9 @@ publish = false
 crate-type = ["cdylib"]
 
 [dependencies]
-magnus = { version = "0.9.2", features = ["rb-sys"] }
+# 0.9.3 keeps `$!` when Rust catches an exception, which a Filesystem or
+# Service callback running while Ruby handles one would otherwise clear.
+magnus = { version = "0.9.3", features = ["rb-sys"] }
 # Raw Ruby FFI for the GVL release/re-acquire calls magnus does not wrap
 # (`rb_thread_call_without_gvl` / `rb_thread_call_with_gvl`). Pinned to the
 # rb-sys magnus resolves so both share one binding instance.

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 core 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/escape.rs

@@ -0,0 +1,53 @@
+//! What a Host App's callback raises that is not a `StandardError`:
+//! `Interrupt`, `exit`, `throw`, `Timeout`. These belong to the host, so
+//! the callback holds one 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 HELD: RefCell<Option<Held>> = const { RefCell::new(None) };
+}
+
+/// The error and, when it carries one, its exception kept rooted while
+/// the guest finishes unwinding.
+struct Held {
+    error: MagnusError,
+    _rooted: Option<BoxValue<Value>>,
+}
+
+/// Hold `error` unless it is a `StandardError`, which comes back for the
+/// callback to answer the guest with; the first one held wins.
+pub(super) fn hold(ruby: &Ruby, error: MagnusError) -> Result<(), MagnusError> {
+    if error.is_kind_of(ruby.exception_standard_error()) {
+        return Err(error);
+    }
+    HELD.with(|held| {
+        held.borrow_mut().get_or_insert_with(|| Held {
+            _rooted: error.value().map(BoxValue::new),
+            error,
+        });
+    });
+    Ok(())
+}
+
+/// Whether a callback on this thread holds an error for the host.
+pub(super) fn pending() -> bool {
+    HELD.with(|held| held.borrow().is_some())
+}
+
+/// Raise what a callback held, once the run is back in Ruby.
+pub(super) fn resume() -> Result<(), MagnusError> {
+    match HELD.with(|held| held.borrow_mut().take()) {
+        Some(held) => Err(held.error),
+        None => Ok(()),
+    }
+}