microsandbox-rb 0.17.3 → 0.17.4

data/ext/microsandbox/Cargo.toml

@@ -8,7 +8,7 @@ description = "Ruby SDK native extension for microsandbox — secure, fast micro
 # returns this via env!("CARGO_PKG_VERSION") and version_spec.rb asserts equality.
 # The core-crate dependencies below stay on their own tag, which is
 # Microsandbox::RUNTIME_VERSION and moves independently of this version.
-version = "0.17.3"
+version = "0.17.4"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"
@@ -25,12 +25,19 @@ crate-type = ["cdylib"]
 [dependencies]
 # "rb-sys" exposes `magnus::rb_sys::protect` (rb_protect), which the GVL bridge
 # uses to check interrupts without letting Ruby longjmp over Rust frames.
-magnus = { version = "0.8", features = ["rb-sys"] }
+# Default features are off: `old-api` (the free functions that conjure a `Ruby`
+# handle unchecked in release builds) must not creep back, and `io` only gates
+# `magnus::io`, which the extension does not use.
+magnus = { version = "0.9", default-features = false, features = ["rb-sys"] }
 # Low-level Ruby C API — used directly for rb_thread_call_without_gvl2 (GVL
 # release during blocking sandbox calls) and rb_thread_check_ints. Kept in
 # lock-step with magnus's own rb-sys.
 rb-sys = "0.9"
 
+# `pthread_atfork`, for the fork generation (runtime::ProcessIdentity). Already
+# in the dependency graph; listed so the binding can call it directly.
+libc = "0.2"
+
 # The microsandbox core runtime, wrapped via FFI exactly like the official
 # Python (pyo3) and Node (napi) SDKs. Pinned to the matching upstream tag so the
 # gem is self-contained and buildable anywhere (CI, release containers, end-user

data/ext/microsandbox/src/backend.rs

@@ -16,14 +16,14 @@
 //! matching Python and Node.
 
 use std::collections::HashMap;
-use std::sync::atomic::{AtomicU32, Ordering};
+use std::sync::atomic::{AtomicU32, AtomicU64, Ordering};
 use std::sync::{Arc, Mutex, MutexGuard, OnceLock, PoisonError};
 
 use magnus::{function, prelude::*, Error, RModule, Ruby};
 use microsandbox::{Backend, MicrosandboxError, Operation};
 
 use crate::error;
-use crate::runtime::{block_on, current_pid};
+use crate::runtime::{block_on, ProcessIdentity};
 
 /// Resolve the ambient default backend, requiring it to be local.
 ///
@@ -99,7 +99,7 @@ fn build_backend(
 }
 
 //--------------------------------------------------------------------------------------------------
-// Fork safety: the backend generation
+// Fork safety: the backend record
 //--------------------------------------------------------------------------------------------------
 //
 // `fork(2)` copies only the calling thread. A child of a process that used the
@@ -114,7 +114,7 @@ fn build_backend(
 // So the child never touches what it inherited: the first native call after a
 // fork builds a fresh backend the same way the inherited one was chosen and
 // swaps it in, and every inherited `Arc` is `mem::forget`-ed — leaked once per
-// fork generation — instead of dropped.
+// forked process — instead of dropped.
 //
 // Locking. The three mutexes below are only ever taken on a Ruby thread that
 // holds the GVL, and nothing that runs while one is held calls into Ruby or
@@ -158,9 +158,11 @@ impl Selection {
 
 static SELECTION: Mutex<Selection> = Mutex::new(Selection::Ladder);
 
-/// The pid of the process whose default backend the core currently holds.
-/// 0 = no native operation has touched the backend in this process lineage.
-static BACKEND_PID: AtomicU32 = AtomicU32::new(0);
+/// The identity of the process whose default backend the core currently holds
+/// ([`ProcessIdentity::to_bits`]: pid and fork generation in one word, so it
+/// is read and written whole). 0 = no native operation has touched the
+/// backend in this process lineage.
+static BACKEND_OWNER: AtomicU64 = AtomicU64::new(0);
 
 static REBUILD_LOCK: Mutex<()> = Mutex::new(());
 
@@ -183,7 +185,7 @@ fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
 /// above).
 pub fn ensure_this_process_backend() -> Result<(), Error> {
     // The Ruby exception is built here, after the locks are released.
-    adopt_backend(current_pid(), None)
+    adopt_backend(ProcessIdentity::current(), None)
         .map(|_| ())
         .map_err(error::to_ruby)
 }
@@ -204,23 +206,24 @@ pub fn ensure_this_process_backend() -> Result<(), Error> {
 /// Returns `Some(inherited selection)` when `replacement` was installed here
 /// (the caller has nothing left to install), `None` when the caller proceeds
 /// as in any process that already owns its backend. On an error nothing has
-/// changed, `BACKEND_PID` included, so the next call tries again.
+/// changed, `BACKEND_OWNER` included, so the next call tries again.
 fn adopt_backend(
-    cur: u32,
+    cur: ProcessIdentity,
     replacement: Option<&Selection>,
 ) -> Result<Option<Selection>, MicrosandboxError> {
-    if BACKEND_PID.load(Ordering::Acquire) == cur {
+    let cur_bits = cur.to_bits();
+    if BACKEND_OWNER.load(Ordering::Acquire) == cur_bits {
         return Ok(None);
     }
     let _rebuild = lock(&REBUILD_LOCK);
-    let seen = BACKEND_PID.load(Ordering::Acquire);
-    if seen == cur {
+    let seen = BACKEND_OWNER.load(Ordering::Acquire);
+    if seen == cur_bits {
         return Ok(None);
     }
     if seen == 0 {
         // Nothing was inherited; the core resolves its default lazily, in this
         // process, on first use.
-        BACKEND_PID.store(cur, Ordering::Release);
+        BACKEND_OWNER.store(cur_bits, Ordering::Release);
         return Ok(None);
     }
 
@@ -233,14 +236,14 @@ fn adopt_backend(
     // The inherited default must never be dropped (see above).
     std::mem::forget(microsandbox::swap_default_backend(fresh));
     // Neither may the backends that open `with_backend` scopes saved for their
-    // restore. The entries themselves stay — pid and selection — so a scope
+    // restore. The entries themselves stay — owner and selection — so a scope
     // the parent opened can still be closed here (see `pop_default_backend`).
     for scope in lock(backend_scopes()).values_mut() {
         std::mem::forget(scope.previous.take());
     }
     let inherited =
         replacement.map(|selection| std::mem::replace(&mut *lock(&SELECTION), selection.clone()));
-    BACKEND_PID.store(cur, Ordering::Release);
+    BACKEND_OWNER.store(cur_bits, Ordering::Release);
     Ok(inherited)
 }
 
@@ -261,7 +264,7 @@ fn set_default_backend(
     // A forked child that starts by selecting a backend: the inherited default
     // is forgotten and this selection installed in its place, without ever
     // rebuilding the inherited one.
-    if adopt_backend(current_pid(), Some(&selection))
+    if adopt_backend(ProcessIdentity::current(), Some(&selection))
         .map_err(error::to_ruby)?
         .is_some()
     {
@@ -283,7 +286,7 @@ static BACKEND_SCOPES: OnceLock<Mutex<HashMap<u32, Scope>>> = OnceLock::new();
 /// What an open `with_backend` scope restores when it closes.
 struct Scope {
     /// The process that opened the scope.
-    pid: u32,
+    owner: ProcessIdentity,
     /// The backend that was the default before the push, kept to be put back
     /// by a pop in the same process. `None` when there is no such backend of
     /// this process's own: a forked child took it out to leak it, or the push
@@ -308,7 +311,7 @@ fn push_default_backend(
     api_key: Option<String>,
     profile: Option<String>,
 ) -> Result<u32, Error> {
-    let cur = current_pid();
+    let cur = ProcessIdentity::current();
     let selection = Selection::Explicit {
         kind,
         url,
@@ -332,7 +335,7 @@ fn push_default_backend(
     lock(backend_scopes()).insert(
         token,
         Scope {
-            pid: cur,
+            owner: cur,
             previous,
             selection: before,
         },
@@ -352,7 +355,7 @@ fn push_default_backend(
 /// is a state the caller can describe and leave with `set_default_backend`;
 /// a token nobody can retry (`with_backend` never hands it out) would not be.
 fn pop_default_backend(token: u32) -> Result<(), Error> {
-    let cur = current_pid();
+    let cur = ProcessIdentity::current();
     // (The registry lock is not held while an exception is built.)
     let Some(scope) = lock(backend_scopes()).remove(&token) else {
         return Err(error::base_error("unknown backend scope token"));
@@ -384,7 +387,7 @@ fn pop_default_backend(token: u32) -> Result<(), Error> {
 
     match scope.previous {
         // Opened and closed in the same process: put the saved backend back.
-        Some(previous) if scope.pid == cur => microsandbox::set_default_backend(previous),
+        Some(previous) if scope.owner == cur => microsandbox::set_default_backend(previous),
         // No backend of this process's own was saved (see `Scope::previous`):
         // restore one built here from how the saved one had been chosen. On
         // failure the temporary backend stays installed (see above). The
@@ -393,8 +396,9 @@ fn pop_default_backend(token: u32) -> Result<(), Error> {
         // forked child ever drops a backend it might have inherited. That
         // leaks at most one backend per scope closed this way.
         previous => {
-            // `None` unless the pid of the process that opened the scope was
-            // reused; an inherited `Arc` is leaked either way.
+            // Always `None` here: a process that is not the scope's opener
+            // took the saved backend out when it adopted (`adopt_backend`).
+            // An inherited `Arc` would be leaked either way.
             std::mem::forget(previous);
             let fresh = scope.selection.build().map_err(error::to_ruby)?;
             std::mem::forget(microsandbox::swap_default_backend(fresh));

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)?;