microsandbox-rb 0.17.3 → 0.17.4

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.4"
 
   # 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.4
 platform: ruby
 authors:
 - ya-luotao