microsandbox-rb 0.17.3 → 0.17.5

data/ext/microsandbox/src/error.rs

@@ -9,6 +9,8 @@ use magnus::{value::ReprValue, Error, ExceptionClass, Module, RClass, RModule, R
 use microsandbox::{AgentClientError, MicrosandboxError, Operation, UnsupportedReason};
 use microsandbox_network::policy::BuildError;
 
+use crate::runtime::ruby;
+
 /// The Ruby class (relative to the `Microsandbox` module) for a core error.
 /// `"Error"` is the base class; anything else is a named subclass.
 fn class_name(err: &MicrosandboxError) -> &'static str {
@@ -88,16 +90,16 @@ fn exception_class(ruby: &Ruby, name: &str) -> Option<ExceptionClass> {
 }
 
 /// Convert a core error into a Ruby exception, preserving the typed class.
-// The `exception::runtime_error()` fallbacks fire only off a Ruby thread (which
-// never happens from a bound method); there is no handle-based alternative there.
-#[allow(deprecated)]
+///
+/// Every constructor in this module builds a Ruby exception class, so it must
+/// run on a Ruby thread holding the GVL: in a bound method, never inside a
+/// `block_on` future or a `nogvl` callback (those return the core error and
+/// get mapped after `block_on` returns). There is no exception class to build
+/// without the GVL, so [`ruby`] panics instead of handing out a handle that
+/// isn't backed by one.
 pub fn to_ruby(err: MicrosandboxError) -> Error {
     let message = err.to_string();
-    let ruby = match Ruby::get() {
-        Ok(ruby) => ruby,
-        // Not on a Ruby thread (should never happen from a bound method).
-        Err(_) => return Error::new(magnus::exception::runtime_error(), message),
-    };
+    let ruby = ruby();
 
     // `Unsupported` gets a Ruby-idiom message (`sandbox.kill` instead of
     // `Sandbox::kill`) plus structured `operation` / `hint` attributes on the
@@ -116,15 +118,8 @@ pub fn to_ruby(err: MicrosandboxError) -> Error {
 /// backend but have no SDK [`Operation`] (Ruby-only diagnostic hooks such as
 /// `Microsandbox.runtime_path`). `name` is the Ruby-facing API name. Mirrors
 /// the Python SDK's name-based `local_only` helper.
-#[allow(deprecated)]
 pub fn local_only(name: &str) -> Error {
-    match Ruby::get() {
-        Ok(ruby) => unsupported_error(&ruby, name, "use a local backend"),
-        Err(_) => Error::new(
-            magnus::exception::runtime_error(),
-            format!("{name} is not supported by this backend: use a local backend"),
-        ),
-    }
+    unsupported_error(&ruby(), name, "use a local backend")
 }
 
 /// Build a `Microsandbox::UnsupportedError` carrying the rendered message and
@@ -191,32 +186,37 @@ fn camel_to_snake(name: &str) -> String {
 
 /// A plain `Microsandbox::Error` (base) with a custom message — used for
 /// binding-level validation errors that have no core counterpart.
-#[allow(deprecated)]
 pub fn base_error(message: impl Into<String>) -> Error {
     let message = message.into();
-    match Ruby::get() {
-        Ok(ruby) => match exception_class(&ruby, "Error") {
-            Some(class) => Error::new(class, message),
-            None => Error::new(ruby.exception_runtime_error(), message),
-        },
-        Err(_) => Error::new(magnus::exception::runtime_error(), message),
+    let ruby = ruby();
+    match exception_class(&ruby, "Error") {
+        Some(class) => Error::new(class, message),
+        None => Error::new(ruby.exception_runtime_error(), message),
     }
 }
 
-/// `Microsandbox::ForkedHandleError`: a handle created in process `born` was
-/// used in process `cur`, a fork descendant (see `runtime::ForkGuarded`).
-/// `class` is the Ruby class users know the handle by.
-#[allow(deprecated)]
+/// `Microsandbox::ForkedHandleError`: a handle created in the process with pid
+/// `born` was used in a fork descendant with pid `cur` (see
+/// `runtime::ForkGuarded`). `class` is the Ruby class users know the handle
+/// by. The two pids are equal when the descendant was given its ancestor's
+/// pid again (they differ in fork generation, which is not shown): that
+/// ancestor has exited, so the message must not claim two processes or point
+/// at the original.
 pub fn forked_handle(class: &str, born: u32, cur: u32) -> Error {
-    let message = format!(
-        "{class} was created in process {born} and cannot be used in forked process {cur}; \
-         create a new handle after fork (the original keeps working in process {born})"
-    );
-    match Ruby::get() {
-        Ok(ruby) => match exception_class(&ruby, "ForkedHandleError") {
-            Some(class) => Error::new(class, message),
-            None => Error::new(ruby.exception_runtime_error(), message),
-        },
-        Err(_) => Error::new(magnus::exception::runtime_error(), message),
+    let message = if born == cur {
+        format!(
+            "{class} was created in an earlier process that also had pid {born} and cannot be \
+             used in this forked process; create a new handle after fork"
+        )
+    } else {
+        format!(
+            "{class} was created in process {born} and cannot be used in forked process {cur}; \
+             create a new handle after fork (the original keeps working in process {born})"
+        )
+    };
+    let ruby = ruby();
+    match exception_class(&ruby, "ForkedHandleError") {
+        Some(class) => Error::new(class, message),
+        None => Error::new(ruby.exception_runtime_error(), message),
     }
 }

data/ext/microsandbox/src/lib.rs

@@ -46,8 +46,10 @@ fn all_sandbox_metrics() -> Result<RHash, Error> {
 }
 
 /// Download and install the `msb` runtime + `libkrunfw` into `~/.microsandbox`.
+/// Never touches the backend, so a forked child does not take the inherited
+/// one over here (see `runtime::block_on_runtime_install`).
 fn install() -> Result<(), Error> {
-    runtime::block_on(microsandbox::setup::install())?.map_err(error::to_ruby)
+    runtime::block_on_runtime_install(microsandbox::setup::install())?.map_err(error::to_ruby)
 }
 
 /// Customizable install via the core `Setup` builder. `opts`: base_dir (install
@@ -84,7 +86,8 @@ fn setup(opts: RHash) -> Result<(), Error> {
             .force(force)
             .build(),
     };
-    runtime::block_on(setup.install())?.map_err(error::to_ruby)
+    // Backend-free, like `install`.
+    runtime::block_on_runtime_install(setup.install())?.map_err(error::to_ruby)
 }
 
 /// Whether the `msb` runtime + `libkrunfw` are installed and resolvable.
@@ -119,10 +122,52 @@ fn resolved_msb_path() -> Result<String, Error> {
     Ok(path.to_string_lossy().into_owned())
 }
 
+/// This process's fork generation (see `runtime::ProcessIdentity`): how many
+/// `fork`s led from the process that loaded the extension to this one. A
+/// diagnostic for the fork specs, not part of the Ruby API (nothing in
+/// `lib/` calls it, and `Native` is the extension's internal namespace).
+fn fork_generation() -> u32 {
+    runtime::ProcessIdentity::current().generation()
+}
+
+/// Whether two given identities are the same process, by the two comparisons
+/// every ownership decision uses: `PartialEq` (the runtime cell, handles,
+/// `with_backend` scopes) and the packed word (the backend record). Returns
+/// `[equal, same_bits]`. A spec-only diagnostic, like `fork_generation`:
+/// pid reuse cannot be staged on demand, so this is where the specs pin that
+/// both the pid and the generation take part. Pure: no state is read or
+/// changed.
+fn fork_identity_equal(pid_a: u32, gen_a: u32, pid_b: u32, gen_b: u32) -> (bool, bool) {
+    let a = runtime::ProcessIdentity::from_parts(pid_a, gen_a);
+    let b = runtime::ProcessIdentity::from_parts(pid_b, gen_b);
+    (a == b, a.to_bits() == b.to_bits())
+}
+
+/// Run a handle's real ownership check (`ForkGuarded::get_in`) for a handle
+/// created by the process (`born_pid`, `born_gen`) and used in (`cur_pid`,
+/// `cur_gen`): `nil` when it is allowed, the `ForkedHandleError` that `get`
+/// would raise otherwise — including the equal-pid wording. Spec-only and
+/// pure, like `fork_identity_equal`; the guard holds no payload.
+fn fork_identity_guard(
+    born_pid: u32,
+    born_gen: u32,
+    cur_pid: u32,
+    cur_gen: u32,
+) -> Result<(), Error> {
+    let born = runtime::ProcessIdentity::from_parts(born_pid, born_gen);
+    let cur = runtime::ProcessIdentity::from_parts(cur_pid, cur_gen);
+    let guard = runtime::ForkGuarded::owned_by(born, "Microsandbox::VolumeFs", ());
+    guard.get_in(cur).map(|_| ())
+}
+
 /// magnus entry point. RubyGems loads this via `require "microsandbox/microsandbox_rb"`,
 /// which calls `Init_microsandbox_rb` (matching the cdylib `[lib] name`).
 #[magnus::init]
 fn init(ruby: &Ruby) -> Result<(), Error> {
+    // Before anything can fork: from here on every fork's child gets a fork
+    // generation one higher than its parent's (see `runtime::ProcessIdentity`).
+    runtime::register_fork_handler();
+
     let module = ruby.define_module("Microsandbox")?;
     let native = module.define_module("Native")?;
 
@@ -137,6 +182,9 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     )?;
     native.define_singleton_method("resolved_msb_path", function!(resolved_msb_path, 0))?;
     native.define_singleton_method("all_sandbox_metrics", function!(all_sandbox_metrics, 0))?;
+    native.define_singleton_method("fork_generation", function!(fork_generation, 0))?;
+    native.define_singleton_method("fork_identity_equal", function!(fork_identity_equal, 4))?;
+    native.define_singleton_method("fork_identity_guard", function!(fork_identity_guard, 4))?;
 
     backend::define(ruby, &native)?;
     sandbox::define(ruby, &native)?;

data/ext/microsandbox/src/runtime.rs

@@ -43,28 +43,123 @@ use std::ffi::c_void;
 use std::future::Future;
 use std::mem::ManuallyDrop;
 use std::panic::{catch_unwind, AssertUnwindSafe};
-use std::sync::atomic::{AtomicPtr, Ordering};
+use std::sync::atomic::{AtomicPtr, AtomicU32, Ordering};
 
 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).
+/// The current Ruby handle. Safe to call from any bound method, value
+/// conversion or error construction (`error::*`): we always hold the GVL there
+/// (both run after `block_on` returns and re-acquires it).
+///
+/// Panics when the calling thread does not hold the GVL (a `nogvl` callback, a
+/// tokio worker): `Ruby::get` checks that in release builds too, so a misplaced
+/// call fails loudly instead of touching Ruby without the lock.
 pub fn ruby() -> Ruby {
-    Ruby::get().expect("microsandbox: not on a Ruby thread")
+    Ruby::get().expect("microsandbox: not on a Ruby thread holding the GVL")
 }
 
-/// This process's id. The single `std::process::id()` call site: everything
-/// fork-aware in the extension (the runtime cell below, the backend generation
-/// in `backend.rs`, [`ForkGuarded`]) compares against this.
-pub fn current_pid() -> u32 {
-    std::process::id()
+//--------------------------------------------------------------------------------------------------
+// Process identity
+//--------------------------------------------------------------------------------------------------
+
+/// Which process this is, for fork safety: the pid plus a fork generation.
+///
+/// Everything fork-aware in the extension — the runtime cell below, the
+/// backend record in `backend.rs`, [`ForkGuarded`] — tags what it builds with
+/// the identity of the process that built it and compares that against
+/// [`ProcessIdentity::current`] before use. Both halves are compared:
+///
+/// * The pid alone is not enough. A descendant can end up with the pid of an
+///   ancestor whose state it inherited, if the pid counter wraps onto exactly
+///   that value and no SDK call happened in between; it would then pass for
+///   that ancestor.
+/// * The generation alone is not enough either. It counts the `fork`s that
+///   ran this library's atfork child handler, and a process can be created
+///   without running it — `vfork`, a raw `clone` — in which case only the pid
+///   tells the child apart.
+///
+/// Every `fork(2)` that runs atfork handlers (which `Kernel#fork` /
+/// `Process.fork` always do: Ruby calls libc's `fork`) gives the child a
+/// generation one higher than its parent's, so parent and child differ even
+/// when their pids are equal.
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub struct ProcessIdentity {
+    pub pid: u32,
+    generation: u32,
+}
+
+/// How many `fork`s, counted from the process that loaded the extension, led
+/// to this process. Incremented only by [`on_fork_child`], in a child, and
+/// inherited (as plain memory) by every child. 32 bits: it would take four
+/// billion nested forks in one lineage to wrap, and a wrap matters only if
+/// the pid matches as well.
+static FORK_GENERATION: AtomicU32 = AtomicU32::new(0);
+
+/// The `pthread_atfork` child handler. It runs in the new child before `fork`
+/// returns there, while the child is single-threaded, and must be
+/// async-signal-safe: one lock-free atomic add, nothing else (no allocation,
+/// no lock, no Ruby). `Relaxed` is enough: the only thread that exists to read
+/// the counter is this one, and threads started later see it through the
+/// spawn's own synchronization. The parent never changes its counter.
+extern "C" fn on_fork_child() {
+    FORK_GENERATION.fetch_add(1, Ordering::Relaxed);
+}
+
+/// Register [`on_fork_child`]. Called once, from the extension's init.
+///
+/// Ruby never unloads (`dlclose`s) an extension, so the handler's code stays
+/// mapped for the life of the process, as `pthread_atfork` requires — handlers
+/// cannot be unregistered. If registration fails (`ENOMEM`), the generation
+/// stays 0 and identity degrades to the pid alone, which is how the extension
+/// behaved before the generation existed; that is not worth refusing to load
+/// over. Platforms without `pthread_atfork` (the gem ships for macOS and
+/// Linux only) get the same pid-only identity.
+pub fn register_fork_handler() {
+    static ONCE: std::sync::Once = std::sync::Once::new();
+    ONCE.call_once(|| {
+        #[cfg(unix)]
+        // SAFETY: `on_fork_child` is an `extern "C" fn()` that stays valid for
+        // the life of the process (see above) and is async-signal-safe.
+        unsafe {
+            let _ = libc::pthread_atfork(None, None, Some(on_fork_child));
+        }
+    });
+}
+
+impl ProcessIdentity {
+    /// This process's identity. The single `std::process::id()` call site.
+    pub fn current() -> Self {
+        Self {
+            pid: std::process::id(),
+            generation: FORK_GENERATION.load(Ordering::Relaxed),
+        }
+    }
+
+    /// An identity from its two halves — ONLY for the fork-identity
+    /// diagnostics in `lib.rs`, which let the specs compare identities that no
+    /// real fork can produce on demand (an equal pid with another generation).
+    pub fn from_parts(pid: u32, generation: u32) -> Self {
+        Self { pid, generation }
+    }
+
+    /// The fork generation, for `Native.fork_generation` (a diagnostic the
+    /// fork specs read; not part of the Ruby API).
+    pub fn generation(self) -> u32 {
+        self.generation
+    }
+
+    /// Both halves in one word, for a lock-free atomic record. `0` is never a
+    /// real identity (no user process has pid 0), so it can mean "none".
+    pub fn to_bits(self) -> u64 {
+        (u64::from(self.pid) << 32) | u64::from(self.generation)
+    }
 }
 
-// The process-wide tokio runtime, tagged with the pid it was built under. A
+// The process-wide tokio runtime, tagged with the identity of the process it
+// was built under (see `ProcessIdentity`). A
 // multi-threaded runtime owns worker + I/O-driver threads, and `fork(2)` copies
 // ONLY the calling thread — so a child that inherits this runtime has a runtime
 // whose threads are gone: `block_on` can still drive the current thread, but the
@@ -72,12 +167,12 @@ pub fn current_pid() -> u32 {
 // connections stall/drop mid-use. This is hit in practice by forking job servers
 // (Solid Queue, Resque) and clustered web servers (Puma workers).
 //
-// The runtime and its pid live in ONE heap cell behind ONE atomic pointer, so a
-// reader sees either a whole cell or none: there is no window in which the
-// pointer is new and the pid old (or the reverse), and no mutex that a fork
-// could capture locked or that a panic could poison.
+// The runtime and its process identity live in ONE heap cell behind ONE atomic
+// pointer, so a reader sees either a whole cell or none: there is no window in
+// which the pointer is new and the identity old (or the reverse), and no mutex
+// that a fork could capture locked or that a panic could poison.
 struct RuntimeCell {
-    pid: u32,
+    owner: ProcessIdentity,
     rt: Runtime,
 }
 
@@ -94,13 +189,13 @@ fn build_runtime() -> Runtime {
 /// The multi-threaded tokio runtime for THIS process, built on first use and
 /// rebuilt after a `fork(2)` (see the note above).
 pub fn runtime() -> &'static Runtime {
-    let cur = current_pid();
+    let cur = ProcessIdentity::current();
     let mut observed = RUNTIME.load(Ordering::Acquire);
     // SAFETY (every dereference below): a non-null pointer in `RUNTIME` came
     // from `Box::into_raw` and is never freed once published, so it is valid
     // for `'static`.
     if let Some(cell) = unsafe { observed.as_ref() } {
-        if cell.pid == cur {
+        if cell.owner == cur {
             // Built in this process: its threads are alive here.
             return &cell.rt;
         }
@@ -109,7 +204,7 @@ pub fn runtime() -> &'static Runtime {
     // Slow path: no runtime yet, or the one we see was built by a parent
     // process. Build ours and publish it with a compare-exchange.
     let fresh = Box::into_raw(Box::new(RuntimeCell {
-        pid: cur,
+        owner: cur,
         rt: build_runtime(),
     }));
     loop {
@@ -117,12 +212,12 @@ pub fn runtime() -> &'static Runtime {
             // Published. The cell we replaced (if any) belonged to a parent
             // process and is LEAKED on purpose, never dropped: its worker
             // threads did not survive the fork, and `Runtime`'s `Drop` joins
-            // them. One runtime is leaked per fork generation that uses the
+            // them. One runtime is leaked per forked process that uses the
             // SDK.
             Ok(_) => return unsafe { &(*fresh).rt },
             Err(winner) => {
                 if let Some(cell) = unsafe { winner.as_ref() } {
-                    if cell.pid == cur {
+                    if cell.owner == cur {
                         // Another thread of THIS process won the race. Our
                         // cell was never published and its threads are alive
                         // here, so dropping it is safe (and joins them).
@@ -153,7 +248,7 @@ pub fn runtime() -> &'static Runtime {
 ///   exits: Ruby frees every `T_DATA` object in `rb_objspace_call_finalizer` —
 ///   leaks it instead.
 pub struct ForkGuarded<T> {
-    pid: u32,
+    owner: ProcessIdentity,
     /// The Ruby class users know the handle by, for the error message.
     class: &'static str,
     inner: ManuallyDrop<T>,
@@ -162,7 +257,18 @@ pub struct ForkGuarded<T> {
 impl<T> ForkGuarded<T> {
     pub fn new(class: &'static str, inner: T) -> Self {
         Self {
-            pid: current_pid(),
+            owner: ProcessIdentity::current(),
+            class,
+            inner: ManuallyDrop::new(inner),
+        }
+    }
+
+    /// A guard owned by `owner` instead of this process — ONLY for the
+    /// fork-identity diagnostic in `lib.rs`, which runs the real ownership
+    /// decision ([`get_in`](Self::get_in)) on identities given by a spec.
+    pub fn owned_by(owner: ProcessIdentity, class: &'static str, inner: T) -> Self {
+        Self {
+            owner,
             class,
             inner: ManuallyDrop::new(inner),
         }
@@ -171,11 +277,15 @@ impl<T> ForkGuarded<T> {
     /// The payload, or `ForkedHandleError` when this is not the process that
     /// created it.
     pub fn get(&self) -> Result<&T, Error> {
-        let cur = current_pid();
-        if self.pid == cur {
+        self.get_in(ProcessIdentity::current())
+    }
+
+    /// [`get`](Self::get) as decided in the process identified by `cur`.
+    pub fn get_in(&self, cur: ProcessIdentity) -> Result<&T, Error> {
+        if self.owner == cur {
             Ok(&self.inner)
         } else {
-            Err(error::forked_handle(self.class, self.pid, cur))
+            Err(error::forked_handle(self.class, self.owner.pid, cur.pid))
         }
     }
 
@@ -191,7 +301,7 @@ impl<T> ForkGuarded<T> {
 
 impl<T> Drop for ForkGuarded<T> {
     fn drop(&mut self) {
-        if self.pid == current_pid() {
+        if self.owner == ProcessIdentity::current() {
             // SAFETY: dropped exactly once, here; `inner` is not used again.
             unsafe { ManuallyDrop::drop(&mut self.inner) };
         }
@@ -209,6 +319,13 @@ impl<T> Drop for ForkGuarded<T> {
 /// 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`.
+///
+/// Doing it at load also keeps that first resolution away from concurrent
+/// callers, which matters since magnus 0.9: the static is a magnus `Lazy`, an
+/// `OnceLock` whose initializer (the `const_get`) runs while holding the lock.
+/// That `funcall` can switch Ruby threads, and a second thread reaching the
+/// same lock would block on it while holding the GVL the first one needs to
+/// finish.
 pub fn preload_class<T: TypedData>(ruby: &Ruby) {
     let _ = T::class(ruby);
 }
@@ -390,6 +507,9 @@ where
 /// `Err` means the future was never polled (see [`nogvl`], and the fork check
 /// below); propagate it with `?` before looking at the future's own output:
 /// `block_on(fut)?.map_err(error::to_ruby)?`.
+///
+/// Every native call goes through this, with one deliberate exception: the
+/// runtime installer, see [`block_on_runtime_install`].
 pub fn block_on<F>(fut: F) -> Result<F::Output, Error>
 where
     F: Future,
@@ -401,3 +521,29 @@ where
     crate::backend::ensure_this_process_backend()?;
     nogvl(|| runtime().block_on(fut))
 }
+
+/// [`block_on`] without its backend check, for the runtime installer ONLY:
+/// `Native.install` and `Native.setup` (`microsandbox::setup`).
+///
+/// The check at the top of [`block_on`] is deliberate and stays there: it is
+/// what makes every other native call safe after a fork. This entry is not a
+/// cheaper alternative to it. It exists because the installer never touches
+/// the default backend or the catalog — `Setup::install` creates the
+/// `bin`/`lib` directories, runs the installed `msb --version`, copies a CI
+/// build or downloads and unpacks the release bundle, and checks that the two
+/// files exist, all under the base directory it resolves from `MSB_HOME` —
+/// so in a forked child the check would only rebuild (and leak) a backend
+/// nothing uses, or fail the install when the inherited backend selection no
+/// longer resolves there. Skipping it leaves the backend record as it was:
+/// the child's next call that does reach the backend is the one that takes
+/// it over.
+///
+/// Before adding a caller, trace its core path and confirm it never reaches
+/// `microsandbox::default_backend()` (directly or through a `Sandbox`,
+/// `Volume`, `Image`, `Snapshot` or agent function that resolves it).
+pub fn block_on_runtime_install<F>(fut: F) -> Result<F::Output, Error>
+where
+    F: Future,
+{
+    nogvl(|| runtime().block_on(fut))
+}

data/lib/microsandbox/sandbox.rb

@@ -497,7 +497,7 @@ module Microsandbox
         opts = build_create_opts(**kwargs)
         Microsandbox.ensure_runtime!
         # Everything Ruby-level happens BEFORE `acquire`: its interrupt mask must
-        # cover only the native call plus the wrap, never caller-supplied code.
+        # cover only the native call, never caller-supplied code.
         sandbox_name = name.to_s
         sandbox = acquire { Native::Sandbox.create(sandbox_name, opts) }
         return sandbox unless block_given?
@@ -603,17 +603,34 @@ module Microsandbox
       # sandbox would be garbage and only GC would stop it, "eventually"; for
       # `Timeout.timeout { Sandbox.create(...) }` that is not good enough. So:
       #
-      # - the acquisition runs under `Thread.handle_interrupt(Object => :never)`,
-      #   which holds a queued exception (or kill) back until the wrapper is
-      #   assigned. The mask covers only the uninterruptible native call plus
-      #   the wrap, so it changes no observable timing; runtime provisioning
-      #   ({Microsandbox.ensure_runtime!}) and the block forms' `yield` stay
-      #   outside it, with normal interrupt handling. For the same reason the
-      #   block passed here must contain NOTHING but the native call: argument
-      #   conversion (`name.to_s`, option Hashes) is the caller's own code and
-      #   has to run before `acquire`, where it stays interruptible;
-      # - the `ensure` plus the `acquired` flag — not `rescue Exception; raise` —
-      #   is what also covers `Thread#kill`, which no `rescue` can catch.
+      # - the native call runs under `Thread.handle_interrupt(Object => :never)`,
+      #   which holds a queued exception (or kill) back until the bare
+      #   {Native::Sandbox} is assigned to a local. The mask covers only that
+      #   uninterruptible call, so it changes no observable timing; runtime
+      #   provisioning ({Microsandbox.ensure_runtime!}), the wrapper's
+      #   construction and the block forms' `yield` stay outside it, with
+      #   normal interrupt handling. For the same reason the block passed here
+      #   must contain NOTHING but the native call: argument conversion
+      #   (`name.to_s`, option Hashes) is the caller's own code and has to run
+      #   before `acquire`, where it stays interruptible;
+      # - the wrapper is built after the mask (`new` may run a subclass's
+      #   `initialize`, which must not hold a `Timeout`/`Thread#kill` back), so
+      #   a held-back interrupt is delivered as the mask ends, before `new`.
+      #   Until `new` has returned, the cleanup therefore works on the bare
+      #   native handle, never on the wrapper: an interrupt at that point, one
+      #   that lands inside a subclass's `initialize`, and an exception that
+      #   `initialize` raises itself all leave the caller without a reference,
+      #   so all three stop the sandbox (when owned, see below);
+      # - the `ensure` plus the `handed_off` flag — not `rescue Exception;
+      #   raise` — is what also covers `Thread#kill`, which no `rescue` can
+      #   catch.
+      #
+      # The protected window is the native handle's assignment through the
+      # wrapper's construction, and the cleanup in it is best-effort: a
+      # *further* interrupt that lands during the cleanup, before the native
+      # `stop` has started, or one delivered at this method's return boundary
+      # (after `handed_off` is set, before the caller has assigned the result),
+      # leaves the teardown to GC.
       #
       # A SIGINT (Ctrl-C on the main thread) is the exception: it is not queued
       # like those two and cannot be masked. One that lands during the native
@@ -625,30 +642,32 @@ module Microsandbox
       # Ownership: {connect_or_create} can hand back a sandbox that was already
       # running for someone else, and {start} restarts a persisted one. The
       # cleanup therefore applies EXACTLY the predicate the block form of
-      # {connect_or_create} uses — {Sandbox#owns_lifecycle?} — in all three
+      # {connect_or_create} uses — the lifecycle ownership behind
+      # {Sandbox#owns_lifecycle?}, read from the native handle — in all three
       # callers, {create} included: a sandbox this call does not own is never
       # stopped here. Its reference is just let go (GC closes the handle, the
       # sandbox keeps running).
       # @yieldreturn [Native::Sandbox]
       # @return [Sandbox]
       def acquire
-        sandbox = nil
-        acquired = false
+        native = nil
+        handed_off = false
         begin
           Thread.handle_interrupt(Object => :never) do
-            sandbox = new(yield)
+            native = yield
           end
-          acquired = true
+          sandbox = new(native)
+          handed_off = true
+          sandbox
         ensure
-          if sandbox && !acquired && sandbox.owns_lifecycle?
+          if native && !handed_off
             begin
-              sandbox.stop
+              native.stop if native.owns_lifecycle
             rescue Microsandbox::Error
               # best-effort cleanup; the interrupt is what the caller must see
             end
           end
         end
-        sandbox
       end
 
       # @api private

data/lib/microsandbox/version.rb

@@ -8,7 +8,7 @@ module Microsandbox
   # Versioning section of the README for the full gem-to-runtime map. Must equal
   # the native ext's Cargo crate version (`Native.version`), enforced by
   # spec/unit/version_spec.rb.
-  VERSION = "0.17.3"
+  VERSION = "0.17.5"
 
   # The upstream microsandbox runtime release this gem build embeds — the `tag`
   # pinned on the `microsandbox`/`microsandbox-network` git deps in

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: microsandbox-rb
 version: !ruby/object:Gem::Version
-  version: 0.17.3
+  version: 0.17.5
 platform: ruby
 authors:
 - ya-luotao