microsandbox-rb 0.17.1 → 0.17.2

data/docs/surface.md

@@ -23,8 +23,10 @@ counterpart, and [DESIGN.md](../DESIGN.md) explains how the layers fit.
   `write_stream`.
 - **Observability** — per-sandbox `metrics`, `Microsandbox.all_sandbox_metrics`,
   streaming `metrics_stream`/`log_stream`, `logs`, `ping`/`touch`.
-- **Live modification** — `modify` with `dry_run:`, `policy:`, CPU/memory
-  resize, root-disk growth, env/labels/workdir, secret rotation.
+- **Live modification** — `modify` with `dry_run:` and `policy:`: CPU/memory
+  resize (`cpus`/`max_cpus`/`memory`/`max_memory`), root-disk growth
+  (`root_disk_size`, MiB), `env`/`remove_env`, `labels`/`remove_labels`,
+  `workdir`, and secret rotation (`secrets`/`remove_secrets`).
 - **OCI image cache** — `Image.get`/`list`/`inspect`/`remove`/`prune`, image
   archives (`Image.load`/`Image.save`), streaming pull progress
   (`Sandbox.create_with_progress` → `PullSession`).
@@ -35,14 +37,16 @@ counterpart, and [DESIGN.md](../DESIGN.md) explains how the layers fit.
 - **Rootfs patches** — `Microsandbox::Patch` (text/file/append/copy_file/
   copy_dir/symlink/mkdir/remove) via `create(patches:)`.
 - **Root disk** — structured `root_disk:` (managed / tmpfs / disk / flat via
-  `Microsandbox::RootDisk`), `follow_root_symlinks:`.
+  `Microsandbox::RootDisk`), `follow_root_symlinks:`; `oci_upper_size:` is the
+  deprecated alias for a managed `root_disk:` size.
 - **Network configuration** — composable profiles, custom per-rule
-  `Microsandbox::NetworkPolicy`/`Rule`/`Destination`, DNS, TLS interception,
-  IPv4/IPv6 pools, `max_connections`, `trust_host_cas`, `strict` hostname mode,
+  `Microsandbox::NetworkPolicy`/`Rule`/`Destination`, custom DNS (`dns:`),
+  TLS-interception tuning (`tls:`), guest address pools (`ipv4_pool:`/
+  `ipv6_pool:`), `max_connections`, `trust_host_cas`, `strict` hostname mode,
   outbound SOCKS4/SOCKS5 `proxy:` (`OutboundProxy`/`SecretSource`),
   `rate_limiter:`, `vsock:`.
 - **Secrets** — multi-host / wildcard allow-lists, injection toggles,
-  per-secret and sandbox-level violation policy.
+  per-secret `on_violation:` and sandbox-level `on_secret_violation:` policy.
 - **SSH** — `Sandbox#ssh` → `SshClient`/`SftpClient`/`SshServer`, with
   `inactivity_timeout:`.
 - **Raw agent client** — `Microsandbox::AgentClient` → `AgentStream`/
@@ -55,9 +59,10 @@ counterpart, and [DESIGN.md](../DESIGN.md) explains how the layers fit.
 - **Errors** — the typed hierarchy in [errors.md](errors.md).
 
 Create options span resources (`cpus`/`memory`/`max_cpus`/`max_memory`),
-`env`/`workdir`/`labels`/`user`/`hostname`/`shell`, `init`/`ephemeral`,
+`env`/`workdir`/`labels`/`user`/`hostname`/`shell`, named `scripts`, the image
+`entrypoint`/`cmd` overrides, `init`/`ephemeral`,
 disk-image `fstype`, `ports`/`ports_udp`, network policy + config,
-`log_level`/`security`/`rlimits`/`pull_policy`/`secrets`/`patches`/`volumes`
+`log_level`/`quiet_logs`/`security`/`rlimits`/`pull_policy`/`secrets`/`patches`/`volumes`
 (bind/named/tmpfs/disk with mount policies, `uid`/`gid`, `quota_mib`),
 `idle_timeout`/`max_duration`, `from_snapshot`, `detached`, and
 `replace`/`replace_with_timeout`.

data/ext/microsandbox/Cargo.toml

@@ -6,8 +6,9 @@ name = "microsandbox_rb"
 description = "Ruby SDK native extension for microsandbox — secure, fast microVM-based sandboxing."
 # Must equal Microsandbox::VERSION (lib/microsandbox/version.rb) — Native.version
 # returns this via env!("CARGO_PKG_VERSION") and version_spec.rb asserts equality.
-# The core-crate dependency below stays pinned at its own tag (v0.6.16).
-version = "0.17.1"
+# The core-crate dependencies below stay on their own tag, which is
+# Microsandbox::RUNTIME_VERSION and moves independently of this version.
+version = "0.17.2"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"
@@ -22,9 +23,12 @@ name = "microsandbox_rb"
 crate-type = ["cdylib"]
 
 [dependencies]
-magnus = "0.8"
-# Low-level Ruby C API — used directly for rb_thread_call_without_gvl (GVL release
-# during blocking sandbox calls). Kept in lock-step with magnus's own rb-sys.
+# "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"] }
+# 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"
 
 # The microsandbox core runtime, wrapped via FFI exactly like the official

data/ext/microsandbox/src/agent.rs

@@ -41,8 +41,8 @@ impl AgentClient {
     /// Connect to a running sandbox by name. `timeout` is optional seconds.
     fn connect_sandbox(name: String, timeout: Option<f64>) -> Result<AgentClient, Error> {
         let bridge = match dur(timeout)? {
-            Some(t) => block_on(AgentBridge::connect_sandbox_with_timeout(&name, t)),
-            None => block_on(AgentBridge::connect_sandbox(&name)),
+            Some(t) => block_on(AgentBridge::connect_sandbox_with_timeout(&name, t))?,
+            None => block_on(AgentBridge::connect_sandbox(&name))?,
         }
         .map_err(to_ruby_agent)?;
         Ok(AgentClient::from_bridge(bridge))
@@ -51,8 +51,8 @@ impl AgentClient {
     /// Connect to an agentd relay socket by path. `timeout` is optional seconds.
     fn connect_path(path: String, timeout: Option<f64>) -> Result<AgentClient, Error> {
         let bridge = match dur(timeout)? {
-            Some(t) => block_on(AgentBridge::connect_path_with_timeout(&path, t)),
-            None => block_on(AgentBridge::connect_path(&path)),
+            Some(t) => block_on(AgentBridge::connect_path_with_timeout(&path, t))?,
+            None => block_on(AgentBridge::connect_path(&path))?,
         }
         .map_err(to_ruby_agent)?;
         Ok(AgentClient::from_bridge(bridge))
@@ -73,7 +73,7 @@ impl AgentClient {
         let body = unsafe { body.as_slice() }.to_vec();
         let inner = Arc::clone(&self.inner);
         let frame =
-            block_on(async move { inner.request(flags, body).await }).map_err(to_ruby_agent)?;
+            block_on(async move { inner.request(flags, body).await })?.map_err(to_ruby_agent)?;
         Ok(frame_to_hash(frame))
     }
 
@@ -81,8 +81,8 @@ impl AgentClient {
     fn stream_open(&self, flags: u8, body: RString) -> Result<RHash, Error> {
         let body = unsafe { body.as_slice() }.to_vec();
         let inner = Arc::clone(&self.inner);
-        let (id, handle) =
-            block_on(async move { inner.stream_open(flags, body).await }).map_err(to_ruby_agent)?;
+        let (id, handle) = block_on(async move { inner.stream_open(flags, body).await })?
+            .map_err(to_ruby_agent)?;
         let hash = ruby().hash_new();
         hash.aset("id", id)?;
         hash.aset("handle", handle)?;
@@ -93,14 +93,14 @@ impl AgentClient {
     fn stream_next(&self, handle: u64) -> Result<Option<RHash>, Error> {
         let inner = Arc::clone(&self.inner);
         let frame =
-            block_on(async move { inner.stream_next(handle).await }).map_err(to_ruby_agent)?;
+            block_on(async move { inner.stream_next(handle).await })?.map_err(to_ruby_agent)?;
         Ok(frame.map(frame_to_hash))
     }
 
     /// Close a stream handle. Idempotent.
     fn stream_close(&self, handle: u64) -> Result<(), Error> {
         let inner = Arc::clone(&self.inner);
-        block_on(async move { inner.stream_close(handle).await });
+        block_on(async move { inner.stream_close(handle).await })?;
         Ok(())
     }
 
@@ -108,7 +108,7 @@ impl AgentClient {
     fn send(&self, id: u32, flags: u8, body: RString) -> Result<(), Error> {
         let body = unsafe { body.as_slice() }.to_vec();
         let inner = Arc::clone(&self.inner);
-        block_on(async move { inner.send(id, flags, body).await }).map_err(to_ruby_agent)
+        block_on(async move { inner.send(id, flags, body).await })?.map_err(to_ruby_agent)
     }
 
     /// Cached handshake `core.ready` frame body bytes (CBOR).
@@ -120,7 +120,7 @@ impl AgentClient {
     /// Close the connection. Idempotent.
     fn close(&self) -> Result<(), Error> {
         let inner = Arc::clone(&self.inner);
-        block_on(async move { inner.close().await });
+        block_on(async move { inner.close().await })?;
         Ok(())
     }
 }
@@ -157,6 +157,8 @@ fn frame_to_hash(frame: BridgeFrame) -> RHash {
 
 pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     let class = native.define_class("AgentClient", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<AgentClient>(ruby);
 
     class.define_singleton_method(
         "connect_sandbox",

data/ext/microsandbox/src/backend.rs

@@ -59,7 +59,7 @@ pub fn with_local_backend<T>(
             .as_local()
             .expect("local_backend() guarantees a local backend");
         op(local).await
-    })
+    })?
     .map_err(error::to_ruby)
 }
 

data/ext/microsandbox/src/exec.rs

@@ -43,7 +43,7 @@ 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 event = block_on(async move { inner.lock().await.recv().await });
+        let event = block_on(async move { inner.lock().await.recv().await })?;
         Ok(event.map(exec_event_to_hash))
     }
 
@@ -51,7 +51,7 @@ impl ExecHandle {
     fn wait(&self) -> Result<RHash, Error> {
         let inner = Arc::clone(&self.inner);
         let status =
-            block_on(async move { inner.lock().await.wait().await }).map_err(error::to_ruby)?;
+            block_on(async move { inner.lock().await.wait().await })?.map_err(error::to_ruby)?;
         let hash = ruby().hash_new();
         hash.aset("exit_code", status.code)?;
         hash.aset("success", status.success)?;
@@ -62,20 +62,20 @@ impl ExecHandle {
     fn collect(&self) -> Result<RHash, Error> {
         let inner = Arc::clone(&self.inner);
         let output =
-            block_on(async move { inner.lock().await.collect().await }).map_err(error::to_ruby)?;
+            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.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.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.control.resize(rows, cols))?.map_err(error::to_ruby)
     }
 
     /// The stdin sink (only the first call returns it; nil afterwards or if
@@ -95,11 +95,11 @@ 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.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.close())?.map_err(error::to_ruby)
     }
 }
 
@@ -141,6 +141,8 @@ fn exec_event_to_hash(event: microsandbox::ExecEvent) -> RHash {
 
 pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     let handle = native.define_class("ExecHandle", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<ExecHandle>(ruby);
     handle.define_method("id", method!(ExecHandle::id, 0))?;
     handle.define_method("recv", method!(ExecHandle::recv, 0))?;
     handle.define_method("wait", method!(ExecHandle::wait, 0))?;
@@ -151,6 +153,8 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     handle.define_method("take_stdin", method!(ExecHandle::take_stdin, 0))?;
 
     let sink = native.define_class("ExecSink", ruby.class_object())?;
+    // Resolve the wrapper class now, not on first use (see `preload_class`).
+    crate::runtime::preload_class::<ExecSink>(ruby);
     sink.define_method("write", method!(ExecSink::write, 1))?;
     sink.define_method("close", method!(ExecSink::close, 0))?;
 

data/ext/microsandbox/src/fs_stream.rs

@@ -33,7 +33,7 @@ impl FsReadStreamHandle {
     /// 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)? {
+        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),
         }
@@ -63,7 +63,7 @@ impl FsWriteSinkHandle {
                 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")),
@@ -73,19 +73,31 @@ 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(()),
-        }
+        // 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/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.

data/ext/microsandbox/src/runtime.rs

@@ -5,6 +5,39 @@
 //! 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;
@@ -12,9 +45,11 @@ use std::panic::{catch_unwind, AssertUnwindSafe};
 use std::sync::atomic::{AtomicPtr, AtomicU32, Ordering};
 use std::sync::Mutex;
 
-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).
@@ -78,6 +113,52 @@ pub fn runtime() -> &'static Runtime {
     rt
 }
 
+/// 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.
 ///
 /// `f` runs on the *same* OS thread (the C call blocks until it returns), so no
@@ -85,7 +166,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 +185,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,24 +197,114 @@ 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`]); 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,
 {