microsandbox-rb 0.17.0 → 0.17.2

data/ext/microsandbox/src/fs_stream.rs

@@ -33,7 +33,7 @@ impl FsReadStreamHandle {
     /// Next chunk of bytes (ASCII-8BIT), or nil at end of stream.
     fn recv(&self) -> Result<Option<RString>, Error> {
         let inner = Arc::clone(&self.inner);
-        match block_on(async move { inner.lock().await.recv().await }).map_err(error::to_ruby)? {
+        match block_on(async move { inner.lock().await.recv().await })?.map_err(error::to_ruby)? {
             Some(bytes) => Ok(Some(ruby().str_from_slice(bytes.as_ref()))),
             None => Ok(None),
         }
@@ -63,7 +63,7 @@ impl FsWriteSinkHandle {
                 Some(sink) => Some(sink.write(&bytes).await),
                 None => None,
             }
-        });
+        })?;
         match result {
             Some(r) => r.map_err(error::to_ruby),
             None => Err(error::base_error("write to a closed FsWriteSink")),
@@ -73,19 +73,31 @@ impl FsWriteSinkHandle {
     /// Flush and close the sink. Idempotent.
     fn close(&self) -> Result<(), Error> {
         let inner = Arc::clone(&self.inner);
-        let taken = block_on(async move { inner.lock().await.take() });
-        match taken {
-            Some(sink) => block_on(sink.close()).map_err(error::to_ruby),
-            None => Ok(()),
-        }
+        // Take AND close in ONE `block_on`. `block_on` returns `Err` when an
+        // interrupt is delivered before it starts; as two calls, an interrupt
+        // between them would drop the sink the first one took without ever
+        // sending its EOF (the guest file is left unfinished, and the handle
+        // can no longer close it).
+        block_on(async move {
+            let taken = inner.lock().await.take();
+            match taken {
+                Some(sink) => sink.close().await,
+                None => Ok(()),
+            }
+        })?
+        .map_err(error::to_ruby)
     }
 }
 
 pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     let rs = native.define_class("FsReadStream", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<FsReadStreamHandle>(ruby);
     rs.define_method("recv", method!(FsReadStreamHandle::recv, 0))?;
 
     let ws = native.define_class("FsWriteSink", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<FsWriteSinkHandle>(ruby);
     ws.define_method("write", method!(FsWriteSinkHandle::write, 1))?;
     ws.define_method("close", method!(FsWriteSinkHandle::close, 0))?;
     Ok(())

data/ext/microsandbox/src/host_path.rs

@@ -0,0 +1,108 @@
+//! Pin caller-supplied host paths when a sandbox is created (GHSA-mcw9-9rf6-p4rm).
+//!
+//! The pinned core stores a relative host path exactly as written and resolves
+//! it against the working directory of whichever process later starts the
+//! sandbox, so restarting from another directory mounts a different host
+//! directory than the one the caller meant. Upstream fixed that in v0.7.6 by
+//! resolving host paths once, at the local-backend boundary, before the
+//! configuration is persisted. This module applies the same resolution in the
+//! binding so it also holds on the runtime this gem pins.
+//!
+//! Rules, matching upstream's `resolve_host_paths`:
+//!
+//! - Local backend only: on a cloud backend the paths belong to the remote
+//!   host and are forwarded untouched.
+//! - `std::path::absolute`, never `canonicalize`: anchoring must not follow
+//!   symlinks (that would defeat the default refusal to follow a symlinked
+//!   bind-mount root) and must not require the target to exist.
+//! - Only create-time input is resolved. A sandbox that was already persisted
+//!   with a relative path keeps it; nothing here rewrites saved state.
+//!
+//! A vsock `host_socket` is deliberately not routed through here: the core
+//! refuses a relative one outright ("vsock host path must be absolute") before
+//! anything is persisted, so there is no stored relative path to pin.
+
+use std::path::PathBuf;
+
+use magnus::Error;
+use microsandbox::sandbox::{IntoImage, RootfsSource};
+use microsandbox::{BackendKind, MicrosandboxError};
+
+use crate::error;
+
+/// How the `image:` text should be handed to the builder.
+pub enum Image {
+    /// An OCI reference, an already-absolute path, or text the core rejects —
+    /// passed through unchanged so the core classifies (or reports) it.
+    Text(String),
+    /// A relative local rootfs path, anchored to the current directory.
+    Path(PathBuf),
+}
+
+/// Resolves host paths for one create call.
+#[derive(Clone, Copy)]
+pub struct HostPaths {
+    local: bool,
+}
+
+impl HostPaths {
+    /// Capture which backend the create call is about to dispatch to.
+    pub fn for_default_backend() -> Self {
+        Self {
+            local: matches!(microsandbox::default_backend().kind(), BackendKind::Local),
+        }
+    }
+
+    /// Anchor a relative host path to the current directory. Absolute paths
+    /// and the empty string (left for the core to reject) pass through.
+    pub fn pin(self, raw: String, label: &str) -> Result<PathBuf, Error> {
+        let path = PathBuf::from(raw);
+        if !self.local || path.as_os_str().is_empty() || path.is_absolute() {
+            return Ok(path);
+        }
+        std::path::absolute(&path).map_err(|e| {
+            error::to_ruby(MicrosandboxError::InvalidConfig(format!(
+                "cannot resolve {label} {}: {e}",
+                path.display()
+            )))
+        })
+    }
+
+    /// Classify `image:` text the way the core does and pin it when it names a
+    /// relative local path (a directory rootfs or a disk image).
+    pub fn pin_image(self, text: String) -> Result<Image, Error> {
+        if !self.local {
+            return Ok(Image::Text(text));
+        }
+        let relative_local = matches!(
+            text.as_str().into_rootfs_source(),
+            Ok(RootfsSource::Bind { ref path, .. } | RootfsSource::DiskImage { ref path, .. })
+                if path.is_relative()
+        );
+        if relative_local {
+            self.pin(text, "rootfs path").map(Image::Path)
+        } else {
+            Ok(Image::Text(text))
+        }
+    }
+
+    /// Pin a `from_snapshot:` value when it is a path rather than a snapshot
+    /// name or digest. Uses the core's own name-vs-path split: a value that
+    /// contains `/` or starts with `.` or `~` is a path. (The core does not
+    /// expand `~`; like any other relative path it is anchored as written.)
+    pub fn pin_snapshot(self, raw: String) -> Result<String, Error> {
+        let path_like = raw.contains('/') || raw.starts_with('.') || raw.starts_with('~');
+        if !self.local || !path_like {
+            return Ok(raw);
+        }
+        self.pin(raw, "snapshot path")?
+            .into_os_string()
+            .into_string()
+            .map_err(|path| {
+                error::to_ruby(MicrosandboxError::InvalidConfig(format!(
+                    "cannot resolve snapshot path {}: the current directory is not valid UTF-8",
+                    PathBuf::from(path).display()
+                )))
+            })
+    }
+}

data/ext/microsandbox/src/image.rs

@@ -48,8 +48,8 @@ fn detail_to_hash(detail: ImageDetail) -> RHash {
         let _ = c.aset("user", config.user);
         // OCI config labels: a free-form JSON object (or nil). Converted to a
         // Ruby Hash so `ImageDetail#config["labels"]` matches the Python/Node
-        // `config.labels` dict. (The pinned v0.5.8 runtime persists this as
-        // null today; the key exists for forward-compatibility/parity.)
+        // `config.labels` dict. (The runtime persisted this as null when the
+        // key was added, at v0.5.8; it exists for forward-compatibility/parity.)
         let _ = c.aset("labels", config.labels.as_ref().map(conv::json_to_ruby));
         let _ = c.aset("stop_signal", config.stop_signal);
         let _ = hash.aset("config", c);

data/ext/microsandbox/src/lib.rs

@@ -14,6 +14,7 @@ mod conv;
 mod error;
 mod exec;
 mod fs_stream;
+mod host_path;
 mod image;
 mod runtime;
 mod sandbox;
@@ -46,7 +47,7 @@ fn all_sandbox_metrics() -> Result<RHash, Error> {
 
 /// Download and install the `msb` runtime + `libkrunfw` into `~/.microsandbox`.
 fn install() -> Result<(), Error> {
-    runtime::block_on(microsandbox::setup::install()).map_err(error::to_ruby)
+    runtime::block_on(microsandbox::setup::install())?.map_err(error::to_ruby)
 }
 
 /// Customizable install via the core `Setup` builder. `opts`: base_dir (install
@@ -83,7 +84,7 @@ fn setup(opts: RHash) -> Result<(), Error> {
             .force(force)
             .build(),
     };
-    runtime::block_on(setup.install()).map_err(error::to_ruby)
+    runtime::block_on(setup.install())?.map_err(error::to_ruby)
 }
 
 /// Whether the `msb` runtime + `libkrunfw` are installed and resolvable.

data/ext/microsandbox/src/runtime.rs

@@ -5,6 +5,39 @@
 //! tokio runtime. Crucially, the blocking call happens inside [`nogvl`], which
 //! releases Ruby's Global VM Lock for the duration so other Ruby threads keep
 //! running while a (potentially long) sandbox operation is in flight.
+//!
+//! # Interrupts must not lose a result
+//!
+//! A native call cannot be interrupted while it runs (see `DESIGN.md`), so a
+//! `Thread#raise` (what `Timeout.timeout` uses), a `Thread#kill` or the main
+//! thread's SIGINT that arrives meanwhile is delivered *after* it. Ruby delivers
+//! those by `longjmp`, which skips Rust frames without running destructors: if
+//! that happened while the value the call just produced still lived only in a
+//! Rust frame, the value — a booted sandbox, a guest exec session, megabytes of
+//! output — would be neither returned to Ruby nor dropped. Two rules keep that
+//! from happening; every bound method relies on both:
+//!
+//! 1. **[`nogvl`] never lets Ruby jump out of it.** It checks interrupts only
+//!    *before* the work starts, under `rb_protect`, and reports one as an
+//!    ordinary `Err` that unwinds the Rust frames normally. After the work it
+//!    does not check at all (see the function for the CRuby details).
+//! 2. **Between [`block_on`] returning and the bound method returning, the code
+//!    must not run Ruby code or check interrupts**: no `funcall` (CRuby's
+//!    `vm_call0_body` runs `RUBY_VM_CHECK_INTS` after *every* call it makes, C
+//!    functions included), no `rb_thread_check_ints`, nothing that can enter a
+//!    Ruby method body. Only C-level construction is allowed there — `rb_hash_*`,
+//!    `rb_ary_*`, `rb_str_*`, number boxing, and `TypedData` wrapping. The one
+//!    `funcall` magnus would otherwise make at that point — `#[magnus::wrap]`
+//!    resolves its class with `const_get` the first time a value is wrapped — is
+//!    moved to extension load by [`preload_class`]. Error construction
+//!    (`error::to_ruby`) may call Ruby: on that path there is no value to lose.
+//!
+//! Together: after `block_on` returns `Ok`, the next interrupt checkpoint is
+//! the Ruby VM's own, reached only once the bound method has handed its value
+//! to Ruby (the first one is `vm_pop_frame` popping the native method's frame,
+//! in `vm_call_cfunc_with_frame_`). From then on the value is an ordinary Ruby
+//! object — returned to the caller, or garbage whose `free` drops the Rust
+//! value. It is never abandoned.
 
 use std::ffi::c_void;
 use std::future::Future;
@@ -12,9 +45,11 @@ use std::panic::{catch_unwind, AssertUnwindSafe};
 use std::sync::atomic::{AtomicPtr, AtomicU32, Ordering};
 use std::sync::Mutex;
 
-use magnus::Ruby;
+use magnus::{Error, Ruby, TypedData};
 use tokio::runtime::Runtime;
 
+use crate::error;
+
 /// The current Ruby handle. Safe to call from any bound method or value
 /// conversion: we always hold the GVL there (conversions run after `block_on`
 /// returns and re-acquires it).
@@ -78,6 +113,52 @@ pub fn runtime() -> &'static Runtime {
     rt
 }
 
+/// Resolve the Ruby class of a `#[magnus::wrap]` type now, at extension load.
+///
+/// The `wrap` macro looks its class up lazily, the first time a value of the
+/// type is handed to Ruby, with `funcall("const_get", ...)` — and a `funcall`
+/// is an interrupt checkpoint (rule 2 in the module docs). Left lazy, the first
+/// `Sandbox.create` of a process that an interrupt raced would hit that
+/// checkpoint while the freshly booted sandbox was still a plain Rust value.
+/// Every module's `define` calls this for each type it wraps, right after
+/// defining the class, so wrapping a value afterwards is `TypedData::class`
+/// reading a resolved static plus `rb_data_typed_object_wrap`.
+pub fn preload_class<T: TypedData>(ruby: &Ruby) {
+    let _ = T::class(ruby);
+}
+
+/// How often [`nogvl`] lets Ruby process interrupts before the work starts
+/// until it gives up. See the comment in the loop: this is a defensive bound,
+/// not a path a healthy process takes.
+const MAX_ENTRY_ATTEMPTS: u32 = 64;
+
+/// Let Ruby deliver whatever interrupts are pending for this thread, turning a
+/// raised exception or any other non-local exit (e.g. the `TAG_FATAL` jump of a
+/// `Thread#kill`) into an `Err` instead of letting it `longjmp` through us.
+///
+/// `rb_thread_check_ints` is `rb_ec_check_ints` → `RUBY_VM_CHECK_INTS_BLOCKING`
+/// → `vm_check_ints_blocking` → `rb_threadptr_execute_interrupts(th, 1)`
+/// (thread.c): it runs trap handlers, may switch threads on a timer tick, and
+/// raises queued `Thread#raise` exceptions — with *blocking* timing, so it also
+/// raises the ones a caller deferred with
+/// `Thread.handle_interrupt(X => :on_blocking)`.
+///
+/// (All CRuby references in this file were read from the Ruby 3.4.5 sources;
+/// the functions named behave the same in 3.1–3.3, the other versions this gem
+/// supports.)
+/// `magnus::rb_sys::protect` is `rb_protect`; magnus re-raises (or re-jumps)
+/// the returned `Error` once it reaches the method boundary, after every Rust
+/// frame in between has unwound normally.
+fn check_interrupts() -> Result<(), Error> {
+    magnus::rb_sys::protect(|| {
+        // SAFETY: called on a Ruby thread holding the GVL (every caller of
+        // `nogvl` is a bound method), inside `rb_protect`.
+        unsafe { rb_sys::rb_thread_check_ints() };
+        rb_sys::Qnil as rb_sys::VALUE
+    })
+    .map(|_| ())
+}
+
 /// Run `f` with the Ruby GVL released.
 ///
 /// `f` runs on the *same* OS thread (the C call blocks until it returns), so no
@@ -85,7 +166,12 @@ pub fn runtime() -> &'static Runtime {
 /// the GVL is released. Panics are caught and re-raised after the GVL is
 /// re-acquired, because unwinding across the C frame would be undefined
 /// behaviour.
-pub fn nogvl<F, R>(f: F) -> R
+///
+/// Returns `Err` only when `f` did NOT run: an interrupt was delivered before
+/// the work started (a pending `Thread#raise`/`Thread#kill`/SIGINT), so there
+/// is nothing to lose and the caller just propagates it with `?`. Once `f` has
+/// run, this returns `Ok` with its value and Ruby is not consulted again.
+pub fn nogvl<F, R>(f: F) -> Result<R, Error>
 where
     F: FnOnce() -> R,
 {
@@ -99,7 +185,7 @@ where
         F: FnOnce() -> R,
     {
         // SAFETY: `arg` points to the `State` on the caller's stack, which
-        // outlives this call (rb_thread_call_without_gvl blocks until return).
+        // outlives this call (rb_thread_call_without_gvl2 blocks until return).
         let state = unsafe { &mut *(arg as *mut State<F, R>) };
         let f = state.f.take().expect("nogvl callback invoked twice");
         state.out = Some(catch_unwind(AssertUnwindSafe(f)));
@@ -111,24 +197,114 @@ where
         out: None,
     };
 
-    unsafe {
-        rb_sys::rb_thread_call_without_gvl(
-            Some(call::<F, R>),
-            &mut state as *mut _ as *mut c_void,
-            None,
-            std::ptr::null_mut(),
-        );
+    // Why not the plain `rb_thread_call_without_gvl`: `rb_nogvl` (thread.c)
+    // ends it with `RUBY_VM_CHECK_INTS_BLOCKING(ec)` — step (5) "Check
+    // interrupts" of the contract in its doc comment — AFTER the callback has
+    // returned. An exception raised there leaves by `longjmp` past this frame,
+    // `block_on`'s and the bound method's, with the callback's result sitting
+    // in `state.out`: never returned, never dropped. That exit check is the bug
+    // this function exists to avoid, so the plain call must not come back here
+    // in any form, not even as a fallback.
+    //
+    // `rb_thread_call_without_gvl2` is `rb_nogvl(..., RB_NOGVL_INTR_FAIL)`:
+    //   * at entry `unblock_function_set(.., fail_if_interrupted = 1)` returns
+    //     FALSE when `RUBY_VM_INTERRUPTED_ANY(ec)` — any unmasked bit of
+    //     `ec->interrupt_flag` — is set, and `BLOCKING_REGION` then skips the
+    //     callback altogether;
+    //   * at exit the `RUBY_VM_CHECK_INTS_BLOCKING` is skipped
+    //     (`if ((flags & RB_NOGVL_INTR_FAIL) == 0)`).
+    // So it never jumps, but it can decline to run. We do the checking
+    // ourselves, only at points where nothing has happened yet.
+
+    // (i) One protected check before we start. The plain call also checked at
+    //     entry (`unblock_function_set` → `RUBY_VM_CHECK_INTS`), so an interrupt
+    //     that is already pending keeps being delivered before any work is
+    //     done. One difference, on purpose: the plain call's entry check used
+    //     non-blocking timing and its EXIT check was the one that delivered
+    //     exceptions deferred with `Thread.handle_interrupt(X => :on_blocking)`
+    //     — i.e. at exactly the point that lost the result. This check uses
+    //     blocking timing (see `check_interrupts`), so such an exception is now
+    //     raised here, before the call, if it is already queued; one that
+    //     arrives during the call waits for the thread's next blocking point.
+    //     Nothing has happened yet, so an `Err` unwinds our frames normally and
+    //     drops `f` (and the future it owns).
+    check_interrupts()?;
+
+    let mut attempts = 0;
+    loop {
+        // SAFETY: `call` matches the expected signature, `state` outlives the
+        // call, and a null unblock function is allowed (the call is simply not
+        // cancellable, as before).
+        unsafe {
+            rb_sys::rb_thread_call_without_gvl2(
+                Some(call::<F, R>),
+                &mut state as *mut _ as *mut c_void,
+                None,
+                std::ptr::null_mut(),
+            );
+        }
+        if state.out.is_some() {
+            // The callback ran. Do NOT check interrupts: see the invariant below.
+            break;
+        }
+
+        // (ii) An interrupt bit was set at entry, so the callback did NOT run
+        //      and nothing has happened. This is routine, not exotic:
+        //      `RUBY_VM_INTERRUPTED_ANY` also covers the timer tick, postponed
+        //      jobs and the VM barrier, and a `Thread#raise` can land in the few
+        //      instructions since the check above. Let Ruby process it under
+        //      protection, then retry.
+        //
+        //      The retry cannot spin: `rb_threadptr_execute_interrupts` loops on
+        //      `threadptr_get_interrupts`, which clears every unmasked bit of
+        //      `ec->interrupt_flag` (the `ATOMIC_CAS` to `interrupt &
+        //      ec->interrupt_mask`) before dispatching, until none is left. That
+        //      holds even when the queued exception stays masked
+        //      (`handle_interrupt(X => :never)`):
+        //      `rb_threadptr_pending_interrupt_deque` then returns `Qundef` and
+        //      sets `pending_interrupt_queue_checked`, and although
+        //      `vm_check_ints_blocking` re-sets the pending bit on each call, the
+        //      same call consumes it again. We hold the GVL from the return of
+        //      the check to the entry test of the next attempt, so only a
+        //      non-Ruby source (timer thread, signal) can set a bit in between.
+        check_interrupts()?;
+
+        // The one case in which the bits are NOT consumed is `ec->raised_flag`:
+        // `rb_threadptr_execute_interrupts` returns at once while CRuby is in
+        // the middle of raising (`setup_exception` in eval.c — an overridden
+        // `Exception#backtrace`, a `TracePoint` `:raise` hook). A native call
+        // made from there with an interrupt pending can never start under
+        // `_gvl2`. Fail it with a normal error rather than loop forever (or
+        // reach for the plain call); nothing has run, so nothing is lost.
+        attempts += 1;
+        if attempts >= MAX_ENTRY_ATTEMPTS {
+            return Err(error::base_error(
+                "native call could not start: interrupt check did not settle",
+            ));
+        }
     }
 
+    // INVARIANT: from here until the bound method returns its value to Ruby,
+    // nothing checks interrupts (rule 2 in the module docs). The next
+    // checkpoint is the Ruby VM's own, AFTER the value has become a Ruby
+    // object, so the value is either returned or dropped by Rust — never
+    // abandoned in this frame by a `longjmp`.
     match state.out.take() {
-        Some(Ok(value)) => value,
+        Some(Ok(value)) => Ok(value),
         Some(Err(panic)) => std::panic::resume_unwind(panic),
-        None => unreachable!("nogvl callback did not run"),
+        // Not reachable: the loop above only breaks once `state.out` is `Some`.
+        // Kept as an error instead of a panic so a future edit to the loop
+        // cannot turn into an abort across the FFI boundary.
+        None => Err(error::base_error("native call did not run")),
     }
 }
 
 /// Drive a future to completion on the shared runtime with the GVL released.
-pub fn block_on<F>(fut: F) -> F::Output
+///
+/// `Err` means the future was never polled (see [`nogvl`]); propagate it with
+/// `?` before looking at the future's own output:
+/// `block_on(fut)?.map_err(error::to_ruby)?`.
+pub fn block_on<F>(fut: F) -> Result<F::Output, Error>
 where
     F: Future,
 {