microsandbox-rb 0.17.1 → 0.17.3

data/ext/microsandbox/src/fs_stream.rs

@@ -16,24 +16,24 @@ 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);
-        match block_on(async move { inner.lock().await.recv().await }).map_err(error::to_ruby)? {
+        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,14 +59,14 @@ 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() {
                 Some(sink) => Some(sink.write(&bytes).await),
                 None => None,
             }
-        });
+        })?;
         match result {
             Some(r) => r.map_err(error::to_ruby),
             None => Err(error::base_error("write to a closed FsWriteSink")),
@@ -72,20 +75,32 @@ impl FsWriteSinkHandle {
 
     /// Flush and close the sink. Idempotent.
     fn close(&self) -> Result<(), Error> {
-        let inner = Arc::clone(&self.inner);
-        let taken = block_on(async move { inner.lock().await.take() });
-        match taken {
-            Some(sink) => block_on(sink.close()).map_err(error::to_ruby),
-            None => Ok(()),
-        }
+        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
+        // sending its EOF (the guest file is left unfinished, and the handle
+        // can no longer close it).
+        block_on(async move {
+            let taken = inner.lock().await.take();
+            match taken {
+                Some(sink) => sink.close().await,
+                None => Ok(()),
+            }
+        })?
+        .map_err(error::to_ruby)
     }
 }
 
 pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     let rs = native.define_class("FsReadStream", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<FsReadStreamHandle>(ruby);
     rs.define_method("recv", method!(FsReadStreamHandle::recv, 0))?;
 
     let ws = native.define_class("FsWriteSink", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<FsWriteSinkHandle>(ruby);
     ws.define_method("write", method!(FsWriteSinkHandle::write, 1))?;
     ws.define_method("close", method!(FsWriteSinkHandle::close, 0))?;
     Ok(())

data/ext/microsandbox/src/host_path.rs

@@ -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/image.rs

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

data/ext/microsandbox/src/lib.rs

@@ -47,7 +47,7 @@ fn all_sandbox_metrics() -> Result<RHash, Error> {
 
 /// Download and install the `msb` runtime + `libkrunfw` into `~/.microsandbox`.
 fn install() -> Result<(), Error> {
-    runtime::block_on(microsandbox::setup::install()).map_err(error::to_ruby)
+    runtime::block_on(microsandbox::setup::install())?.map_err(error::to_ruby)
 }
 
 /// Customizable install via the core `Setup` builder. `opts`: base_dir (install
@@ -84,7 +84,7 @@ fn setup(opts: RHash) -> Result<(), Error> {
             .force(force)
             .build(),
     };
-    runtime::block_on(setup.install()).map_err(error::to_ruby)
+    runtime::block_on(setup.install())?.map_err(error::to_ruby)
 }
 
 /// Whether the `msb` runtime + `libkrunfw` are installed and resolvable.
@@ -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.

data/ext/microsandbox/src/runtime.rs

@@ -5,16 +5,51 @@
 //! tokio runtime. Crucially, the blocking call happens inside [`nogvl`], which
 //! releases Ruby's Global VM Lock for the duration so other Ruby threads keep
 //! running while a (potentially long) sandbox operation is in flight.
+//!
+//! # Interrupts must not lose a result
+//!
+//! A native call cannot be interrupted while it runs (see `DESIGN.md`), so a
+//! `Thread#raise` (what `Timeout.timeout` uses), a `Thread#kill` or the main
+//! thread's SIGINT that arrives meanwhile is delivered *after* it. Ruby delivers
+//! those by `longjmp`, which skips Rust frames without running destructors: if
+//! that happened while the value the call just produced still lived only in a
+//! Rust frame, the value — a booted sandbox, a guest exec session, megabytes of
+//! output — would be neither returned to Ruby nor dropped. Two rules keep that
+//! from happening; every bound method relies on both:
+//!
+//! 1. **[`nogvl`] never lets Ruby jump out of it.** It checks interrupts only
+//!    *before* the work starts, under `rb_protect`, and reports one as an
+//!    ordinary `Err` that unwinds the Rust frames normally. After the work it
+//!    does not check at all (see the function for the CRuby details).
+//! 2. **Between [`block_on`] returning and the bound method returning, the code
+//!    must not run Ruby code or check interrupts**: no `funcall` (CRuby's
+//!    `vm_call0_body` runs `RUBY_VM_CHECK_INTS` after *every* call it makes, C
+//!    functions included), no `rb_thread_check_ints`, nothing that can enter a
+//!    Ruby method body. Only C-level construction is allowed there — `rb_hash_*`,
+//!    `rb_ary_*`, `rb_str_*`, number boxing, and `TypedData` wrapping. The one
+//!    `funcall` magnus would otherwise make at that point — `#[magnus::wrap]`
+//!    resolves its class with `const_get` the first time a value is wrapped — is
+//!    moved to extension load by [`preload_class`]. Error construction
+//!    (`error::to_ruby`) may call Ruby: on that path there is no value to lose.
+//!
+//! Together: after `block_on` returns `Ok`, the next interrupt checkpoint is
+//! the Ruby VM's own, reached only once the bound method has handed its value
+//! to Ruby (the first one is `vm_pop_frame` popping the native method's frame,
+//! in `vm_call_cfunc_with_frame_`). From then on the value is an ordinary Ruby
+//! object — returned to the caller, or garbage whose `free` drops the Rust
+//! value. It is never abandoned.
 
 use std::ffi::c_void;
 use std::future::Future;
+use std::mem::ManuallyDrop;
 use std::panic::{catch_unwind, AssertUnwindSafe};
-use std::sync::atomic::{AtomicPtr, AtomicU32, Ordering};
-use std::sync::Mutex;
+use std::sync::atomic::{AtomicPtr, Ordering};
 
-use magnus::Ruby;
+use magnus::{Error, Ruby, TypedData};
 use tokio::runtime::Runtime;
 
+use crate::error;
+
 /// The current Ruby handle. Safe to call from any bound method or value
 /// conversion: we always hold the GVL there (conversions run after `block_on`
 /// returns and re-acquires it).
@@ -22,7 +57,14 @@ pub fn ruby() -> Ruby {
     Ruby::get().expect("microsandbox: not on a Ruby thread")
 }
 
-// The process-wide tokio runtime, guarded by the pid it was built under. A
+/// 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()
+}
+
+// The process-wide tokio runtime, tagged with the pid it was built under. 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
@@ -30,16 +72,16 @@ pub fn ruby() -> Ruby {
 // connections stall/drop mid-use. This is hit in practice by forking job servers
 // (Solid Queue, Resque) and clustered web servers (Puma workers).
 //
-// Fix: store the runtime behind a leaked raw pointer tagged with the building
-// pid. If `runtime()` is called in a process whose pid differs (we forked), build
-// a FRESH runtime for this process and swap the pointer. The stale runtime is
-// LEAKED, never dropped — dropping a tokio runtime whose worker threads vanished
-// across fork can hang on the shutdown thread-join. One runtime is leaked per
-// process that uses the SDK (bounded; equivalent to the old set-once behavior in
-// the common no-fork case).
-static RUNTIME_PTR: AtomicPtr<Runtime> = AtomicPtr::new(std::ptr::null_mut());
-static RUNTIME_PID: AtomicU32 = AtomicU32::new(0);
-static RUNTIME_LOCK: Mutex<()> = Mutex::new(());
+// 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.
+struct RuntimeCell {
+    pid: u32,
+    rt: Runtime,
+}
+
+static RUNTIME: AtomicPtr<RuntimeCell> = AtomicPtr::new(std::ptr::null_mut());
 
 fn build_runtime() -> Runtime {
     tokio::runtime::Builder::new_multi_thread()
@@ -50,32 +92,157 @@ fn build_runtime() -> Runtime {
 }
 
 /// The multi-threaded tokio runtime for THIS process, built on first use and
-/// rebuilt after a `fork(2)` (fork-safe — see the note above).
+/// rebuilt after a `fork(2)` (see the note above).
 pub fn runtime() -> &'static Runtime {
-    let cur = std::process::id();
-    let ptr = RUNTIME_PTR.load(Ordering::Acquire);
-    if !ptr.is_null() && RUNTIME_PID.load(Ordering::Acquire) == cur {
-        // SAFETY: ptr was produced by Box::leak (valid for 'static) and matches
-        // this process's pid, so its runtime threads are live in this process.
-        return unsafe { &*ptr };
+    let cur = current_pid();
+    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 {
+            // Built in this process: its threads are alive here.
+            return &cell.rt;
+        }
+    }
+
+    // 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,
+        rt: build_runtime(),
+    }));
+    loop {
+        match RUNTIME.compare_exchange(observed, fresh, Ordering::AcqRel, Ordering::Acquire) {
+            // 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
+            // SDK.
+            Ok(_) => return unsafe { &(*fresh).rt },
+            Err(winner) => {
+                if let Some(cell) = unsafe { winner.as_ref() } {
+                    if cell.pid == 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).
+                        drop(unsafe { Box::from_raw(fresh) });
+                        return &cell.rt;
+                    }
+                }
+                observed = winner;
+            }
+        }
+    }
+}
+
+/// The Rust payload of a wrapped Ruby object, bound to the process that
+/// created it.
+///
+/// A handle that crosses a `fork(2)` is useless in the child and dangerous to
+/// destroy there: it owns tasks, channels and connections of the parent's
+/// runtime, clones of the parent's backend, the parent-watchdog pipe of a
+/// sandbox. So every `#[magnus::wrap]` type keeps its payload in one of these:
+///
+/// * [`get`](Self::get) — the only way to the payload for anything that acts
+///   on it — fails with `Microsandbox::ForkedHandleError` in any process other
+///   than the one that built the value. `Deref` is deliberately not
+///   implemented: an access that skips the check should not compile.
+/// * `Drop` runs the payload's destructor only in that same process. A forked
+///   child that garbage-collects an inherited handle — at the latest when it
+///   exits: Ruby frees every `T_DATA` object in `rb_objspace_call_finalizer` —
+///   leaks it instead.
+pub struct ForkGuarded<T> {
+    pid: u32,
+    /// The Ruby class users know the handle by, for the error message.
+    class: &'static str,
+    inner: ManuallyDrop<T>,
+}
+
+impl<T> ForkGuarded<T> {
+    pub fn new(class: &'static str, inner: T) -> Self {
+        Self {
+            pid: current_pid(),
+            class,
+            inner: ManuallyDrop::new(inner),
+        }
     }
 
-    let _guard = RUNTIME_LOCK
-        .lock()
-        .expect("microsandbox: runtime lock poisoned");
-    // Re-check under the lock (another thread may have just built it).
-    let ptr = RUNTIME_PTR.load(Ordering::Acquire);
-    if !ptr.is_null() && RUNTIME_PID.load(Ordering::Acquire) == cur {
-        return unsafe { &*ptr };
+    /// 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 {
+            Ok(&self.inner)
+        } else {
+            Err(error::forked_handle(self.class, self.pid, cur))
+        }
     }
 
-    // Build a fresh runtime for this process and publish it. The previous pointer
-    // (if any) belonged to a parent process and is intentionally leaked, not
-    // dropped (its threads are gone post-fork; Drop would block on join).
-    let rt: &'static Runtime = Box::leak(Box::new(build_runtime()));
-    RUNTIME_PTR.store(rt as *const Runtime as *mut Runtime, Ordering::Release);
-    RUNTIME_PID.store(cur, Ordering::Release);
-    rt
+    /// The payload without the process check — ONLY for accessors that copy
+    /// plain data out of the value's own memory (a name, an id, a cached
+    /// status). Those stay readable in a forked child, which needs e.g. the
+    /// name to open its own handle. Never use this for anything that takes a
+    /// lock, touches a file descriptor, or reaches the runtime or the backend.
+    pub fn peek(&self) -> &T {
+        &self.inner
+    }
+}
+
+impl<T> Drop for ForkGuarded<T> {
+    fn drop(&mut self) {
+        if self.pid == current_pid() {
+            // SAFETY: dropped exactly once, here; `inner` is not used again.
+            unsafe { ManuallyDrop::drop(&mut self.inner) };
+        }
+        // Otherwise: inherited across a fork. Leak it (see the type docs).
+    }
+}
+
+/// Resolve the Ruby class of a `#[magnus::wrap]` type now, at extension load.
+///
+/// The `wrap` macro looks its class up lazily, the first time a value of the
+/// type is handed to Ruby, with `funcall("const_get", ...)` — and a `funcall`
+/// is an interrupt checkpoint (rule 2 in the module docs). Left lazy, the first
+/// `Sandbox.create` of a process that an interrupt raced would hit that
+/// checkpoint while the freshly booted sandbox was still a plain Rust value.
+/// Every module's `define` calls this for each type it wraps, right after
+/// defining the class, so wrapping a value afterwards is `TypedData::class`
+/// reading a resolved static plus `rb_data_typed_object_wrap`.
+pub fn preload_class<T: TypedData>(ruby: &Ruby) {
+    let _ = T::class(ruby);
+}
+
+/// How often [`nogvl`] lets Ruby process interrupts before the work starts
+/// until it gives up. See the comment in the loop: this is a defensive bound,
+/// not a path a healthy process takes.
+const MAX_ENTRY_ATTEMPTS: u32 = 64;
+
+/// Let Ruby deliver whatever interrupts are pending for this thread, turning a
+/// raised exception or any other non-local exit (e.g. the `TAG_FATAL` jump of a
+/// `Thread#kill`) into an `Err` instead of letting it `longjmp` through us.
+///
+/// `rb_thread_check_ints` is `rb_ec_check_ints` → `RUBY_VM_CHECK_INTS_BLOCKING`
+/// → `vm_check_ints_blocking` → `rb_threadptr_execute_interrupts(th, 1)`
+/// (thread.c): it runs trap handlers, may switch threads on a timer tick, and
+/// raises queued `Thread#raise` exceptions — with *blocking* timing, so it also
+/// raises the ones a caller deferred with
+/// `Thread.handle_interrupt(X => :on_blocking)`.
+///
+/// (All CRuby references in this file were read from the Ruby 3.4.5 sources;
+/// the functions named behave the same in 3.1–3.3, the other versions this gem
+/// supports.)
+/// `magnus::rb_sys::protect` is `rb_protect`; magnus re-raises (or re-jumps)
+/// the returned `Error` once it reaches the method boundary, after every Rust
+/// frame in between has unwound normally.
+fn check_interrupts() -> Result<(), Error> {
+    magnus::rb_sys::protect(|| {
+        // SAFETY: called on a Ruby thread holding the GVL (every caller of
+        // `nogvl` is a bound method), inside `rb_protect`.
+        unsafe { rb_sys::rb_thread_check_ints() };
+        rb_sys::Qnil as rb_sys::VALUE
+    })
+    .map(|_| ())
 }
 
 /// Run `f` with the Ruby GVL released.
@@ -85,7 +252,12 @@ pub fn runtime() -> &'static Runtime {
 /// the GVL is released. Panics are caught and re-raised after the GVL is
 /// re-acquired, because unwinding across the C frame would be undefined
 /// behaviour.
-pub fn nogvl<F, R>(f: F) -> R
+///
+/// Returns `Err` only when `f` did NOT run: an interrupt was delivered before
+/// the work started (a pending `Thread#raise`/`Thread#kill`/SIGINT), so there
+/// is nothing to lose and the caller just propagates it with `?`. Once `f` has
+/// run, this returns `Ok` with its value and Ruby is not consulted again.
+pub fn nogvl<F, R>(f: F) -> Result<R, Error>
 where
     F: FnOnce() -> R,
 {
@@ -99,7 +271,7 @@ where
         F: FnOnce() -> R,
     {
         // SAFETY: `arg` points to the `State` on the caller's stack, which
-        // outlives this call (rb_thread_call_without_gvl blocks until return).
+        // outlives this call (rb_thread_call_without_gvl2 blocks until return).
         let state = unsafe { &mut *(arg as *mut State<F, R>) };
         let f = state.f.take().expect("nogvl callback invoked twice");
         state.out = Some(catch_unwind(AssertUnwindSafe(f)));
@@ -111,26 +283,121 @@ where
         out: None,
     };
 
-    unsafe {
-        rb_sys::rb_thread_call_without_gvl(
-            Some(call::<F, R>),
-            &mut state as *mut _ as *mut c_void,
-            None,
-            std::ptr::null_mut(),
-        );
+    // Why not the plain `rb_thread_call_without_gvl`: `rb_nogvl` (thread.c)
+    // ends it with `RUBY_VM_CHECK_INTS_BLOCKING(ec)` — step (5) "Check
+    // interrupts" of the contract in its doc comment — AFTER the callback has
+    // returned. An exception raised there leaves by `longjmp` past this frame,
+    // `block_on`'s and the bound method's, with the callback's result sitting
+    // in `state.out`: never returned, never dropped. That exit check is the bug
+    // this function exists to avoid, so the plain call must not come back here
+    // in any form, not even as a fallback.
+    //
+    // `rb_thread_call_without_gvl2` is `rb_nogvl(..., RB_NOGVL_INTR_FAIL)`:
+    //   * at entry `unblock_function_set(.., fail_if_interrupted = 1)` returns
+    //     FALSE when `RUBY_VM_INTERRUPTED_ANY(ec)` — any unmasked bit of
+    //     `ec->interrupt_flag` — is set, and `BLOCKING_REGION` then skips the
+    //     callback altogether;
+    //   * at exit the `RUBY_VM_CHECK_INTS_BLOCKING` is skipped
+    //     (`if ((flags & RB_NOGVL_INTR_FAIL) == 0)`).
+    // So it never jumps, but it can decline to run. We do the checking
+    // ourselves, only at points where nothing has happened yet.
+
+    // (i) One protected check before we start. The plain call also checked at
+    //     entry (`unblock_function_set` → `RUBY_VM_CHECK_INTS`), so an interrupt
+    //     that is already pending keeps being delivered before any work is
+    //     done. One difference, on purpose: the plain call's entry check used
+    //     non-blocking timing and its EXIT check was the one that delivered
+    //     exceptions deferred with `Thread.handle_interrupt(X => :on_blocking)`
+    //     — i.e. at exactly the point that lost the result. This check uses
+    //     blocking timing (see `check_interrupts`), so such an exception is now
+    //     raised here, before the call, if it is already queued; one that
+    //     arrives during the call waits for the thread's next blocking point.
+    //     Nothing has happened yet, so an `Err` unwinds our frames normally and
+    //     drops `f` (and the future it owns).
+    check_interrupts()?;
+
+    let mut attempts = 0;
+    loop {
+        // SAFETY: `call` matches the expected signature, `state` outlives the
+        // call, and a null unblock function is allowed (the call is simply not
+        // cancellable, as before).
+        unsafe {
+            rb_sys::rb_thread_call_without_gvl2(
+                Some(call::<F, R>),
+                &mut state as *mut _ as *mut c_void,
+                None,
+                std::ptr::null_mut(),
+            );
+        }
+        if state.out.is_some() {
+            // The callback ran. Do NOT check interrupts: see the invariant below.
+            break;
+        }
+
+        // (ii) An interrupt bit was set at entry, so the callback did NOT run
+        //      and nothing has happened. This is routine, not exotic:
+        //      `RUBY_VM_INTERRUPTED_ANY` also covers the timer tick, postponed
+        //      jobs and the VM barrier, and a `Thread#raise` can land in the few
+        //      instructions since the check above. Let Ruby process it under
+        //      protection, then retry.
+        //
+        //      The retry cannot spin: `rb_threadptr_execute_interrupts` loops on
+        //      `threadptr_get_interrupts`, which clears every unmasked bit of
+        //      `ec->interrupt_flag` (the `ATOMIC_CAS` to `interrupt &
+        //      ec->interrupt_mask`) before dispatching, until none is left. That
+        //      holds even when the queued exception stays masked
+        //      (`handle_interrupt(X => :never)`):
+        //      `rb_threadptr_pending_interrupt_deque` then returns `Qundef` and
+        //      sets `pending_interrupt_queue_checked`, and although
+        //      `vm_check_ints_blocking` re-sets the pending bit on each call, the
+        //      same call consumes it again. We hold the GVL from the return of
+        //      the check to the entry test of the next attempt, so only a
+        //      non-Ruby source (timer thread, signal) can set a bit in between.
+        check_interrupts()?;
+
+        // The one case in which the bits are NOT consumed is `ec->raised_flag`:
+        // `rb_threadptr_execute_interrupts` returns at once while CRuby is in
+        // the middle of raising (`setup_exception` in eval.c — an overridden
+        // `Exception#backtrace`, a `TracePoint` `:raise` hook). A native call
+        // made from there with an interrupt pending can never start under
+        // `_gvl2`. Fail it with a normal error rather than loop forever (or
+        // reach for the plain call); nothing has run, so nothing is lost.
+        attempts += 1;
+        if attempts >= MAX_ENTRY_ATTEMPTS {
+            return Err(error::base_error(
+                "native call could not start: interrupt check did not settle",
+            ));
+        }
     }
 
+    // INVARIANT: from here until the bound method returns its value to Ruby,
+    // nothing checks interrupts (rule 2 in the module docs). The next
+    // checkpoint is the Ruby VM's own, AFTER the value has become a Ruby
+    // object, so the value is either returned or dropped by Rust — never
+    // abandoned in this frame by a `longjmp`.
     match state.out.take() {
-        Some(Ok(value)) => value,
+        Some(Ok(value)) => Ok(value),
         Some(Err(panic)) => std::panic::resume_unwind(panic),
-        None => unreachable!("nogvl callback did not run"),
+        // Not reachable: the loop above only breaks once `state.out` is `Some`.
+        // Kept as an error instead of a panic so a future edit to the loop
+        // cannot turn into an abort across the FFI boundary.
+        None => Err(error::base_error("native call did not run")),
     }
 }
 
 /// Drive a future to completion on the shared runtime with the GVL released.
-pub fn block_on<F>(fut: F) -> F::Output
+///
+/// `Err` means the future was never polled (see [`nogvl`], and the fork check
+/// below); propagate it with `?` before looking at the future's own output:
+/// `block_on(fut)?.map_err(error::to_ruby)?`.
+pub fn block_on<F>(fut: F) -> Result<F::Output, Error>
 where
     F: Future,
 {
+    // Many core operations resolve the process-wide default backend while they
+    // run. After a fork that backend is the parent's; replace it now, while we
+    // still hold the GVL (the check takes a mutex and may build a Ruby
+    // exception — neither is allowed once the GVL is released).
+    crate::backend::ensure_this_process_backend()?;
     nogvl(|| runtime().block_on(fut))
 }