microsandbox-rb 0.17.2 → 0.17.3

data/ext/microsandbox/src/backend.rs

@@ -17,13 +17,13 @@
 
 use std::collections::HashMap;
 use std::sync::atomic::{AtomicU32, Ordering};
-use std::sync::{Arc, Mutex, OnceLock};
+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;
+use crate::runtime::{block_on, current_pid};
 
 /// Resolve the ambient default backend, requiring it to be local.
 ///
@@ -31,7 +31,8 @@ use crate::runtime::block_on;
 /// borrowing `&LocalBackend` from it (`as_local()` borrows the `Arc`). Pure
 /// Rust — safe to call inside `block_on` (no Ruby C API), and it returns a raw
 /// `MicrosandboxError` so the Ruby-exception mapping happens *after* `block_on`
-/// re-acquires the GVL. Cloud backends yield `Unsupported` for the given
+/// re-acquires the GVL. It does not run [`ensure_this_process_backend`] (that
+/// needs the GVL): the `block_on` it executes under already did. Cloud backends yield `Unsupported` for the given
 /// operation (v0.6.8 `Operation`-keyed shape), mirroring pyo3's `resolve_local`.
 pub fn local_backend(op: Operation) -> Result<Arc<dyn Backend>, MicrosandboxError> {
     let backend = microsandbox::default_backend();
@@ -65,14 +66,16 @@ pub fn with_local_backend<T>(
 
 /// Build an `Arc<dyn Backend>` from the SDK facade. Ported from pyo3
 /// `build_backend` (`sdk/python/src/lib.rs`) / node `build_backend`. Synchronous
-/// (no network I/O): cloud construction only builds the HTTP client. Runs on the
-/// Ruby thread with the GVL held, so it may map errors to Ruby directly.
+/// (no network I/O): cloud construction only builds the HTTP client. Pure Rust
+/// — it is also called with one of the mutexes below held, where calling into
+/// Ruby (to build an exception) is not allowed; callers map the error
+/// afterwards.
 fn build_backend(
-    kind: String,
+    kind: &str,
     url: Option<String>,
     api_key: Option<String>,
     profile: Option<String>,
-) -> Result<Arc<dyn Backend>, Error> {
+) -> Result<Arc<dyn Backend>, MicrosandboxError> {
     match kind.trim().to_ascii_lowercase().as_str() {
         "local" => Ok(Arc::new(microsandbox::LocalBackend::lazy())),
         "cloud" => {
@@ -81,21 +84,166 @@ fn build_backend(
                 None => match (url, api_key) {
                     (Some(url), Some(api_key)) => microsandbox::CloudBackend::new(url, api_key),
                     _ => {
-                        return Err(error::to_ruby(MicrosandboxError::InvalidConfig(
+                        return Err(MicrosandboxError::InvalidConfig(
                             "cloud backend requires url + api_key or profile".into(),
-                        )))
+                        ))
                     }
                 },
-            }
-            .map_err(error::to_ruby)?;
+            }?;
             Ok(Arc::new(cloud))
         }
-        other => Err(error::to_ruby(MicrosandboxError::InvalidConfig(format!(
+        other => Err(MicrosandboxError::InvalidConfig(format!(
             "backend kind must be 'local' or 'cloud', got {other:?}"
-        )))),
+        ))),
+    }
+}
+
+//--------------------------------------------------------------------------------------------------
+// Fork safety: the backend generation
+//--------------------------------------------------------------------------------------------------
+//
+// `fork(2)` copies only the calling thread. A child of a process that used the
+// SDK inherits the core's process-wide default backend — a `LocalBackend`
+// whose SQLite connections are each served by a worker thread that does not
+// exist in the child, or a `CloudBackend` whose pooled connections belong to
+// the parent's dead tokio runtime. Using it hangs (Linux: the pool's 30 s
+// acquire timeout) or kills the process (macOS: waking the missing worker
+// thread traps in libdispatch), and so does DROPPING it, because the
+// destructor wakes the same threads.
+//
+// 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.
+//
+// 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
+// releases the GVL (which is why the code under them is pure Rust and Ruby
+// exceptions are built after they are released). Ruby-level `fork` needs the
+// GVL too, so no fork can happen while one of them is held: a child never
+// inherits them locked.
+
+/// How the current default backend was chosen, so a forked child can choose
+/// it again. Deliberately not `Debug`: `Explicit` carries the cloud API key
+/// (which the backend `Arc` in this process holds anyway — recording it here
+/// adds no new exposure, as long as it is never printed).
+#[derive(Clone)]
+enum Selection {
+    /// The core's own resolution ladder (`MSB_BACKEND`, `MSB_PROFILE`, the
+    /// config file, else local): what `default_backend()` does on first use.
+    Ladder,
+    /// A `set_default_backend` / `with_backend` selection.
+    Explicit {
+        kind: String,
+        url: Option<String>,
+        api_key: Option<String>,
+        profile: Option<String>,
+    },
+}
+
+impl Selection {
+    /// A fresh backend for this selection, owned by the calling process.
+    fn build(&self) -> Result<Arc<dyn Backend>, MicrosandboxError> {
+        match self {
+            Selection::Ladder => microsandbox::resolve_default_backend(),
+            Selection::Explicit {
+                kind,
+                url,
+                api_key,
+                profile,
+            } => build_backend(kind, url.clone(), api_key.clone(), profile.clone()),
+        }
     }
 }
 
+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);
+
+static REBUILD_LOCK: Mutex<()> = Mutex::new(());
+
+/// Lock one of this module's mutexes. A poisoned one is recovered: the data
+/// behind them stays consistent across a panic (plain assignments), and
+/// refusing to go on would only turn one failure into a permanent one.
+fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
+    mutex.lock().unwrap_or_else(PoisonError::into_inner)
+}
+
+/// Make sure the core's default backend belongs to THIS process, rebuilding it
+/// after a fork. Every Ruby-facing entry that can reach the default backend
+/// runs this first: [`crate::runtime::block_on`] for the async operations, and
+/// each synchronous entry that reads the backend itself. (The three that are
+/// about to replace the default anyway — `set_default_backend`,
+/// `push_default_backend` and `pop_default_backend` — adopt with the
+/// selection they install instead.)
+///
+/// Runs only with the GVL held — never inside a future (see the locking note
+/// 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)
+        .map(|_| ())
+        .map_err(error::to_ruby)
+}
+
+/// Take the backend state over for process `cur` if it still belongs to a
+/// parent process: install a backend built in this process and leak every
+/// inherited one.
+///
+/// What gets installed is `replacement` when the caller itself determines the
+/// backend (a selection, or the restore of a scope), and otherwise a rebuild
+/// of the inherited selection. The difference
+/// matters when the inherited selection no longer resolves in the child (say
+/// the ladder now reads `MSB_BACKEND=cloud` without credentials): the rebuild
+/// fails, and keeps failing on every call, but an explicit selection must
+/// still get the child out of that state — so it never depends on the
+/// inherited one.
+///
+/// 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.
+fn adopt_backend(
+    cur: u32,
+    replacement: Option<&Selection>,
+) -> Result<Option<Selection>, MicrosandboxError> {
+    if BACKEND_PID.load(Ordering::Acquire) == cur {
+        return Ok(None);
+    }
+    let _rebuild = lock(&REBUILD_LOCK);
+    let seen = BACKEND_PID.load(Ordering::Acquire);
+    if seen == cur {
+        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);
+        return Ok(None);
+    }
+
+    // A process that used the backend forked us. Build ours first, so that a
+    // failure leaves everything as it was.
+    let fresh = match replacement {
+        Some(selection) => selection.build()?,
+        None => lock(&SELECTION).build()?,
+    };
+    // 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
+    // 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);
+    Ok(inherited)
+}
+
 /// Install a process-wide default backend. Synchronous (an `RwLock` write) — no
 /// `block_on`. Mirrors Python `set_default_backend` / Node `setDefaultBackend`.
 fn set_default_backend(
@@ -104,7 +252,23 @@ fn set_default_backend(
     api_key: Option<String>,
     profile: Option<String>,
 ) -> Result<(), Error> {
-    microsandbox::set_default_backend(build_backend(kind, url, api_key, profile)?);
+    let selection = Selection::Explicit {
+        kind,
+        url,
+        api_key,
+        profile,
+    };
+    // 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))
+        .map_err(error::to_ruby)?
+        .is_some()
+    {
+        return Ok(());
+    }
+    microsandbox::set_default_backend(selection.build().map_err(error::to_ruby)?);
+    *lock(&SELECTION) = selection;
     Ok(())
 }
 
@@ -114,9 +278,24 @@ fn set_default_backend(
 // swaps the default and stores the previous backend under a fresh token; pop
 // restores it. The Ruby wrapper drives this through an `ensure` block.
 static NEXT_BACKEND_SCOPE: AtomicU32 = AtomicU32::new(1);
-static BACKEND_SCOPES: OnceLock<Mutex<HashMap<u32, Arc<dyn Backend>>>> = OnceLock::new();
+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,
+    /// 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
+    /// was the child's first use of the backend and replaced an inherited
+    /// default ([`adopt_backend`]). The pop then rebuilds from `selection`.
+    previous: Option<Arc<dyn Backend>>,
+    /// How that previous backend had been chosen: what a rebuild starts from,
+    /// and what `SELECTION` goes back to when the scope closes.
+    selection: Selection,
+}
 
-fn backend_scopes() -> &'static Mutex<HashMap<u32, Arc<dyn Backend>>> {
+fn backend_scopes() -> &'static Mutex<HashMap<u32, Scope>> {
     BACKEND_SCOPES.get_or_init(|| Mutex::new(HashMap::new()))
 }
 
@@ -129,34 +308,111 @@ fn push_default_backend(
     api_key: Option<String>,
     profile: Option<String>,
 ) -> Result<u32, Error> {
-    let previous = microsandbox::swap_default_backend(build_backend(kind, url, api_key, profile)?);
+    let cur = current_pid();
+    let selection = Selection::Explicit {
+        kind,
+        url,
+        api_key,
+        profile,
+    };
+    let (previous, before) = match adopt_backend(cur, Some(&selection)).map_err(error::to_ruby)? {
+        // A forked child's first use of the backend: the scoped backend
+        // replaced the inherited default (now forgotten), so there is nothing
+        // of this process to put back. The pop rebuilds from how the inherited
+        // default had been chosen.
+        Some(inherited) => (None, inherited),
+        None => {
+            let previous =
+                microsandbox::swap_default_backend(selection.build().map_err(error::to_ruby)?);
+            let before = std::mem::replace(&mut *lock(&SELECTION), selection);
+            (Some(previous), before)
+        }
+    };
     let token = NEXT_BACKEND_SCOPE.fetch_add(1, Ordering::Relaxed);
-    backend_scopes()
-        .lock()
-        .map_err(|_| error::base_error("backend scope registry poisoned"))?
-        .insert(token, previous);
+    lock(backend_scopes()).insert(
+        token,
+        Scope {
+            pid: cur,
+            previous,
+            selection: before,
+        },
+    );
     Ok(token)
 }
 
-/// Restore the backend saved by [`push_default_backend`].
+/// Close the scope opened by [`push_default_backend`]: restore the backend it
+/// saved.
+///
+/// A pop consumes its token whether or not it succeeds. It can fail only when
+/// the backend to restore has to be rebuilt from how it had been chosen (the
+/// saved one was the parent's) and that selection does not resolve in this
+/// process. The scope is closed anyway and its temporary selection stays in
+/// effect: the temporary backend remains installed, or — in a child that has
+/// not yet built a backend of its own — is what the next call rebuilds. That
+/// 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 previous = backend_scopes()
-        .lock()
-        .map_err(|_| error::base_error("backend scope registry poisoned"))?
-        .remove(&token)
-        .ok_or_else(|| error::base_error("unknown backend scope token"))?;
-    microsandbox::set_default_backend(previous);
+    let cur = current_pid();
+    // (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"));
+    };
+
+    // A forked child whose first use of the backend is this pop (the parent
+    // forked inside a `with_backend` block and the child now leaves it) takes
+    // over with what the scope restores — directly, never by way of the
+    // scope's temporary backend, which the child may be unable to rebuild (a
+    // cloud profile that is gone there) and has no use for.
+    match adopt_backend(cur, Some(&scope.selection)) {
+        // Done: the restored selection is installed and recorded. The backend
+        // this scope had saved is the parent's; it left the registry above, so
+        // it is leaked here rather than by the adoption.
+        Ok(Some(_temporary)) => {
+            std::mem::forget(scope.previous);
+            return Ok(());
+        }
+        // This process already owns its backend: restore below.
+        Ok(None) => {}
+        // Nothing was changed (see `adopt_backend`), so everything in sight is
+        // still the parent's: leak what the scope saved, and report. The next
+        // call tries to take over with the temporary selection.
+        Err(e) => {
+            std::mem::forget(scope.previous);
+            return Err(error::to_ruby(e));
+        }
+    }
+
+    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),
+        // 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
+        // default being replaced was built in this process and could be
+        // dropped safely; it is forgotten all the same, so that no path of a
+        // 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.
+            std::mem::forget(previous);
+            let fresh = scope.selection.build().map_err(error::to_ruby)?;
+            std::mem::forget(microsandbox::swap_default_backend(fresh));
+        }
+    }
+    *lock(&SELECTION) = scope.selection;
     Ok(())
 }
 
 /// The active default backend kind: `"local"` or `"cloud"`. First call lazily
 /// resolves the env/profile/config ladder. Synchronous (an `RwLock` read).
-fn default_backend_kind() -> String {
-    match microsandbox::default_backend().kind() {
+fn default_backend_kind() -> Result<String, Error> {
+    ensure_this_process_backend()?;
+    Ok(match microsandbox::default_backend().kind() {
         microsandbox::BackendKind::Local => "local",
         microsandbox::BackendKind::Cloud => "cloud",
     }
-    .to_string()
+    .to_string())
 }
 
 /// Secret-safe description of the active default backend (v0.6.9):
@@ -164,7 +420,8 @@ fn default_backend_kind() -> String {
 /// (e.g. "MSB_BACKEND", "programmatic", "default"); the API key is never
 /// included. Like `default_backend_kind`, the first call freezes ambient
 /// env/profile resolution for the process.
-fn default_backend_info() -> magnus::RHash {
+fn default_backend_info() -> Result<magnus::RHash, Error> {
+    ensure_this_process_backend()?;
     let info = microsandbox::default_backend_info();
     let hash = crate::runtime::ruby().hash_new();
     let _ = hash.aset(
@@ -177,7 +434,7 @@ fn default_backend_info() -> magnus::RHash {
     let _ = hash.aset("api_url", info.api_url);
     let _ = hash.aset("source", info.source.as_str());
     let _ = hash.aset("profile", info.profile);
-    hash
+    Ok(hash)
 }
 
 pub fn define(_ruby: &Ruby, native: &RModule) -> Result<(), Error> {

data/ext/microsandbox/src/error.rs

@@ -202,3 +202,21 @@ pub fn base_error(message: impl Into<String>) -> Error {
         Err(_) => Error::new(magnus::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)]
+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),
+    }
+}

data/ext/microsandbox/src/exec.rs

@@ -12,14 +12,20 @@ use magnus::{method, prelude::*, Error, RHash, RModule, RString, Ruby};
 use tokio::sync::Mutex;
 
 use crate::error;
-use crate::runtime::{block_on, ruby};
+use crate::runtime::{block_on, ruby, ForkGuarded};
 
 #[magnus::wrap(class = "Microsandbox::Native::ExecHandle", free_immediately, size)]
 pub struct ExecHandle {
-    inner: Arc<Mutex<microsandbox::ExecHandle>>,
+    inner: ForkGuarded<ExecParts>,
+    /// Plain data, readable in any process.
+    id: String,
+}
+
+/// Everything of an exec session that is bound to the creating process.
+struct ExecParts {
+    handle: Arc<Mutex<microsandbox::ExecHandle>>,
     control: microsandbox::ExecControl,
     stdin: std::sync::Mutex<Option<Arc<microsandbox::sandbox::exec::ExecSink>>>,
-    id: String,
 }
 
 impl ExecHandle {
@@ -29,9 +35,14 @@ impl ExecHandle {
         let control = handle.control();
         let stdin = handle.take_stdin().map(Arc::new);
         Self {
-            inner: Arc::new(Mutex::new(handle)),
-            control,
-            stdin: std::sync::Mutex::new(stdin),
+            inner: ForkGuarded::new(
+                "Microsandbox::ExecHandle",
+                ExecParts {
+                    handle: Arc::new(Mutex::new(handle)),
+                    control,
+                    stdin: std::sync::Mutex::new(stdin),
+                },
+            ),
             id,
         }
     }
@@ -42,14 +53,14 @@ impl ExecHandle {
 
     /// Next event as a Hash, or nil when the stream ends.
     fn recv(&self) -> Result<Option<RHash>, Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(&self.inner.get()?.handle);
         let event = block_on(async move { inner.lock().await.recv().await })?;
         Ok(event.map(exec_event_to_hash))
     }
 
     /// Block until exit; returns {exit_code, success}.
     fn wait(&self) -> Result<RHash, Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(&self.inner.get()?.handle);
         let status =
             block_on(async move { inner.lock().await.wait().await })?.map_err(error::to_ruby)?;
         let hash = ruby().hash_new();
@@ -60,46 +71,49 @@ impl ExecHandle {
 
     /// Drain the stream and return a collected exec-output Hash.
     fn collect(&self) -> Result<RHash, Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(&self.inner.get()?.handle);
         let output =
             block_on(async move { inner.lock().await.collect().await })?.map_err(error::to_ruby)?;
         crate::sandbox::exec_output_to_hash(output)
     }
 
     fn signal(&self, sig: i32) -> Result<(), Error> {
-        block_on(self.control.signal(sig))?.map_err(error::to_ruby)
+        block_on(self.inner.get()?.control.signal(sig))?.map_err(error::to_ruby)
     }
 
     fn kill(&self) -> Result<(), Error> {
-        block_on(self.control.kill())?.map_err(error::to_ruby)
+        block_on(self.inner.get()?.control.kill())?.map_err(error::to_ruby)
     }
 
     fn resize(&self, rows: u16, cols: u16) -> Result<(), Error> {
-        block_on(self.control.resize(rows, cols))?.map_err(error::to_ruby)
+        block_on(self.inner.get()?.control.resize(rows, cols))?.map_err(error::to_ruby)
     }
 
     /// The stdin sink (only the first call returns it; nil afterwards or if
     /// stdin was not piped).
-    fn take_stdin(&self) -> Option<ExecSink> {
-        let mut guard = self.stdin.lock().expect("exec stdin mutex poisoned");
-        guard.take().map(|sink| ExecSink { inner: sink })
+    fn take_stdin(&self) -> Result<Option<ExecSink>, Error> {
+        let parts = self.inner.get()?;
+        let mut guard = parts.stdin.lock().expect("exec stdin mutex poisoned");
+        Ok(guard.take().map(|sink| ExecSink {
+            inner: ForkGuarded::new("Microsandbox::ExecStdin", sink),
+        }))
     }
 }
 
 #[magnus::wrap(class = "Microsandbox::Native::ExecSink", free_immediately, size)]
 pub struct ExecSink {
-    inner: Arc<microsandbox::sandbox::exec::ExecSink>,
+    inner: ForkGuarded<Arc<microsandbox::sandbox::exec::ExecSink>>,
 }
 
 impl ExecSink {
     fn write(&self, data: RString) -> Result<(), Error> {
         // Copy out while holding the GVL (see sandbox::fs_write for the rationale).
         let bytes = unsafe { data.as_slice() }.to_vec();
-        block_on(self.inner.write(&bytes))?.map_err(error::to_ruby)
+        block_on(self.inner.get()?.write(&bytes))?.map_err(error::to_ruby)
     }
 
     fn close(&self) -> Result<(), Error> {
-        block_on(self.inner.close())?.map_err(error::to_ruby)
+        block_on(self.inner.get()?.close())?.map_err(error::to_ruby)
     }
 }
 

data/ext/microsandbox/src/fs_stream.rs

@@ -16,23 +16,23 @@ use microsandbox::sandbox::{FsReadStream, FsWriteSink};
 use tokio::sync::Mutex;
 
 use crate::error;
-use crate::runtime::{block_on, ruby};
+use crate::runtime::{block_on, ruby, ForkGuarded};
 
 #[magnus::wrap(class = "Microsandbox::Native::FsReadStream", free_immediately, size)]
 pub struct FsReadStreamHandle {
-    inner: Arc<Mutex<FsReadStream>>,
+    inner: ForkGuarded<Arc<Mutex<FsReadStream>>>,
 }
 
 impl FsReadStreamHandle {
     pub fn new(stream: FsReadStream) -> Self {
         Self {
-            inner: Arc::new(Mutex::new(stream)),
+            inner: ForkGuarded::new("Microsandbox::FsReadStream", Arc::new(Mutex::new(stream))),
         }
     }
 
     /// 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);
+        let inner = Arc::clone(self.inner.get()?);
         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),
@@ -42,13 +42,16 @@ impl FsReadStreamHandle {
 
 #[magnus::wrap(class = "Microsandbox::Native::FsWriteSink", free_immediately, size)]
 pub struct FsWriteSinkHandle {
-    inner: Arc<Mutex<Option<FsWriteSink>>>,
+    inner: ForkGuarded<Arc<Mutex<Option<FsWriteSink>>>>,
 }
 
 impl FsWriteSinkHandle {
     pub fn new(sink: FsWriteSink) -> Self {
         Self {
-            inner: Arc::new(Mutex::new(Some(sink))),
+            inner: ForkGuarded::new(
+                "Microsandbox::FsWriteSink",
+                Arc::new(Mutex::new(Some(sink))),
+            ),
         }
     }
 
@@ -56,7 +59,7 @@ impl FsWriteSinkHandle {
     fn write(&self, data: RString) -> Result<(), Error> {
         // Copy out while the GVL is held (GC.compact could move the buffer).
         let bytes = unsafe { data.as_slice() }.to_vec();
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         let result = block_on(async move {
             let guard = inner.lock().await;
             match guard.as_ref() {
@@ -72,7 +75,7 @@ impl FsWriteSinkHandle {
 
     /// Flush and close the sink. Idempotent.
     fn close(&self) -> Result<(), Error> {
-        let inner = Arc::clone(&self.inner);
+        let inner = Arc::clone(self.inner.get()?);
         // 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

data/ext/microsandbox/src/host_path.rs

@@ -47,10 +47,11 @@ pub struct HostPaths {
 
 impl HostPaths {
     /// Capture which backend the create call is about to dispatch to.
-    pub fn for_default_backend() -> Self {
-        Self {
+    pub fn for_default_backend() -> Result<Self, Error> {
+        crate::backend::ensure_this_process_backend()?;
+        Ok(Self {
             local: matches!(microsandbox::default_backend().kind(), BackendKind::Local),
-        }
+        })
     }
 
     /// Anchor a relative host path to the current directory. Absolute paths

data/ext/microsandbox/src/lib.rs

@@ -108,6 +108,7 @@ fn set_runtime_libkrunfw_path(path: String) {
 /// no async) — runs on the Ruby thread; resolves the path from the local
 /// backend's config.
 fn resolved_msb_path() -> Result<String, Error> {
+    backend::ensure_this_process_backend()?;
     let backend = microsandbox::default_backend();
     // Shim-only entry point with no SDK `Operation` — report the Ruby-facing
     // name (`Microsandbox.runtime_path`), like Python's name-based local_only.