microsandbox-rb 0.17.0 → 0.17.2

data/docs/observability.md

@@ -0,0 +1,99 @@
+# Metrics, logs, and live modification
+
+## Metrics & logs
+
+```ruby
+Microsandbox::Sandbox.create("obs", image: "public.ecr.aws/docker/library/alpine:latest") do |sb|
+  # On v0.6.x runtimes the metrics slot goes live a beat after create returns,
+  # so `metrics` can briefly raise "no live metrics slot" right after boot —
+  # retry for a few hundred ms rather than treating the first failure as fatal.
+  m = sb.metrics                       # => Microsandbox::Metrics
+  m.cpu_percent
+  m.memory_bytes
+  m.uptime_secs
+
+  sb.logs(tail: 100, sources: ["stdout", "stderr"]).each do |entry|
+    puts "[#{entry.source}] #{entry.text}"
+  end
+end
+```
+
+Streaming counterparts: `sb.metrics_stream` (`MetricsStream` over `Metrics`)
+and `sb.log_stream` (`LogStream` over `LogEntry`) — both single-pass, see
+[execution.md](execution.md#streams-are-single-pass).
+`Microsandbox.all_sandbox_metrics` reports every running sandbox at once.
+
+`MetricsDisabledError` means metrics are turned off for the sandbox. The
+metrics slot goes live a moment *after* `create` returns; a call inside that
+window raises the base `Microsandbox::Error` with a message containing
+`no live metrics slot` (not `MetricsUnavailableError`, which the pinned runtime
+never raises). Retry on that message:
+
+```ruby
+metrics = begin
+  sb.metrics
+rescue Microsandbox::Error => e
+  raise unless e.message.include?("no live metrics slot")
+  sleep 0.1
+  retry
+end
+```
+
+`sb.log_stream(follow: true)` keeps waiting for new entries and **does not end
+when the sandbox stops** — the runtime follows the log file, not the sandbox —
+and the wait cannot be interrupted. A thread blocked in it also keeps the
+process from exiting normally. Read what exists with `sb.logs` or
+`sb.log_stream` (no `follow:`), or follow from a separate process you can kill.
+
+## Live modification and health
+
+Resize, reconfigure, or rotate secrets on a sandbox **without recreating it**,
+and probe the guest agent's liveness. To leave headroom for a live CPU/memory
+resize, reserve a ceiling at create time with `max_cpus:`/`max_memory:`:
+
+```ruby
+Microsandbox::Sandbox.create("live", image: "public.ecr.aws/docker/library/alpine:latest",
+  cpus: 1, max_cpus: 4, memory: 512, max_memory: 2048) do |sb|
+  # Health check — does NOT refresh the idle timer:
+  ping = sb.ping                       # => Microsandbox::PingResult
+  ping.latency_ms                      # round-trip latency
+
+  # Explicitly refresh the idle-activity timer (resets any idle_timeout:):
+  sb.touch.activity_seq                # => Microsandbox::TouchResult
+
+  # Preview a change without applying it:
+  plan = sb.modify(cpus: 2, memory: 1024, dry_run: true)
+  plan.applied?                        # => false
+  plan.changes                         # => [{ kind: "config", field: "cpus", ... }, ...]
+
+  # Live resize — applies to the running VM under the default :no_restart policy:
+  sb.modify(cpus: 2, memory: 1024)
+
+  # Grow the root disk (managed upper or flat, MiB — runtime v0.6.9). Applied
+  # while stopped; growth-only:
+  sb.modify(root_disk_size: 8192, policy: :next_start)
+
+  # env/labels/workdir changes on a *running* sandbox require a restart, so the
+  # default :no_restart policy rejects the whole apply (it raises rather than
+  # partially applying). Persist them for the next start — or restart now —
+  # by saying so explicitly:
+  sb.modify(env: { "TIER" => "prod" }, remove_env: ["DEBUG"],
+    labels: { "role" => "worker" }, policy: :next_start)  # or policy: :restart
+
+  # Rotating/removing an *existing* secret (or updating its allowed hosts) is
+  # live; *adding* a new secret is restart-required, like env. Specs are keyed
+  # by name; env:/store:/value: are mutually exclusive:
+  sb.modify(
+    secrets: { "API_KEY" => { env: "HOST_API_KEY", allowed_hosts: ["api.example.com"] } },
+    remove_secrets: ["OLD_TOKEN"],
+  )
+end
+```
+
+The apply is **all-or-nothing**: under a given `policy:` every planned change
+must be applicable, or the whole `modify` raises — nothing is partially
+applied. Use `dry_run: true` to inspect each change's `disposition` (`"live"`,
+`"next start"`, `"requires restart"`) before committing.
+
+`SandboxHandle` (from `Sandbox.get`/`list`) carries the same `#ping`/`#touch`/
+`#modify`; on a stopped sandbox `#ping`/`#touch` raise `SandboxNotRunningError`.

data/docs/releasing.md

@@ -0,0 +1,117 @@
+# Releasing
+
+Releases are automated by `.github/workflows/release.yml` via RubyGems
+**Trusted Publishing** (OIDC) — there is no API key to store as a secret. The
+trusted publisher is already configured for this gem, so no per-release secret
+or credential setup is needed.
+
+## Each release
+
+1. Bump the gem's **own** version on its independent semver track (see the
+   [Versioning](../README.md#versioning) section of the README); **don't** pick
+   the number to mirror the upstream tag. The version is written in three
+   files that must stay equal (`spec/unit/version_spec.rb` asserts it), and
+   recorded in the lockfile:
+   - `lib/microsandbox/version.rb` — `Microsandbox::VERSION`;
+   - `ext/microsandbox/Cargo.toml` — the `[package] version`;
+   - `binaries/lib/microsandbox/binaries.rb` — `Microsandbox::Binaries::VERSION`
+     (the companion gem ships in lockstep);
+   - `Cargo.lock` — committed and packed into the gem, and it records the
+     extension crate's version, so a version bump must commit the regenerated
+     lock (`bundle exec rake compile` rewrites it).
+
+   If the release also adopts a new upstream runtime, move the runtime tag
+   everywhere it is named:
+   - `ext/microsandbox/Cargo.toml` — the `tag = "vX.Y.Z"` on **all three**
+     upstream git deps (`microsandbox`, `microsandbox-network`,
+     `microsandbox-runtime`);
+   - `lib/microsandbox/version.rb` — `Microsandbox::RUNTIME_VERSION`;
+   - `binaries/lib/microsandbox/binaries.rb` —
+     `Microsandbox::Binaries::RUNTIME_VERSION`;
+   - `binaries/checksums/<tag>.sha256` — the release's `checksums.sha256`,
+     committed (vendoring fails closed without it);
+   - `Cargo.lock` — regenerated again, since it pins the git deps to the new
+     tag's commit.
+
+   Then add a row to the Versioning table in the README and update
+   `CHANGELOG.md`.
+2. Push a `vX.Y.Z` tag. Once the [release preflight](#release-preflight)
+   passes, CI pushes the **source gem** to RubyGems via
+   `rubygems/configure-rubygems-credentials` (OIDC, `id-token: write`) — no
+   `RUBYGEMS_API_KEY` secret required — then creates the GitHub Release.
+
+## Release preflight
+
+`release.yml`'s `preflight` job runs `.github/scripts/release_preflight.sh
+<tag>` and the `publish` job needs it, so nothing reaches RubyGems unless:
+
+- the tag is `vX.Y.Z` and the three version constants **in the tagged commit**
+  — `Microsandbox::VERSION`, `[package] version` in
+  `ext/microsandbox/Cargo.toml`, `Microsandbox::Binaries::VERSION` — all equal
+  `X.Y.Z`;
+- the tagged commit is on `main`;
+- the `CI` workflow's push run for that exact commit concluded `success`.
+
+Pushing `main` and the tag together is fine: the preflight **waits** for that
+CI run to appear and finish (polling every 30 s, up to 45 min —
+`PREFLIGHT_CI_WAIT_SECONDS` / `PREFLIGHT_CI_POLL_SECONDS`), so a release
+publishes only after CI, including the real-microVM integration lanes, is
+green. A failed or timed-out preflight leaves the tag unpublished. How to
+recover depends on whether the tag has to move:
+
+- **The tagged commit is right** (CI flaked, or was still red): re-run the
+  `CI` run for that commit until it is green, then re-run the failed `Release`
+  run.
+- **The tag must point at a different commit** (wrong version constants, not
+  on `main`): delete the tag, fix the commit, and push the tag again — that
+  starts a new `Release` run. Never re-run the old run after retagging: a
+  re-run keeps the commit it was started for, so it checks the old commit
+  again and fails the same way.
+
+Dry-run it against an existing tag — nothing is published on a manual
+dispatch — or run the script locally from a full clone:
+
+```bash
+gh workflow run release.yml --ref main -f preflight_ref=vX.Y.Z
+GH_TOKEN=$(gh auth token) .github/scripts/release_preflight.sh vX.Y.Z
+```
+
+It is a workflow-level gate; branch protection and a protected environment for
+the trusted publisher are separate repository settings.
+
+CI's `lint` job also runs `cargo deny check advisories` against `Cargo.lock`;
+the exceptions (advisories with no fixed release at the pinned runtime) are in
+`deny.toml` at the repository root — re-check them on every runtime adoption.
+
+## Precompiled per-platform gems
+
+Precompiled *extension* gems are not built or published. Users install the
+source gem, which compiles the extension via `rb_sys` at install time (so a
+stable Rust toolchain is required on the installing host). The companion
+`microsandbox-rb-binaries` gems below are unaffected: they carry the host
+runtime, not the extension.
+
+## Runtime binaries gems
+
+`microsandbox-rb-binaries` (source in `binaries/`) is a *separate* artifact from
+the SDK gem: it carries no Ruby extension, only the
+upstream `msb` + `libkrunfw` for one platform, verified against the release's
+published `checksums.sha256` when vendored. CI's `binaries` job vendors and
+builds all three (`arm64-darwin`, `x86_64-linux-gnu`, `aarch64-linux-gnu`) on
+every run and smoke-tests the host one; `release.yml`'s `binaries-gems` job
+does the same on a tag and a separate `publish-binaries` job pushes them after
+the SDK gem is live. The SDK `publish` job needs `binaries-gems`, so a
+companion **build** failure blocks the SDK publish as well. A companion
+**push** failure is its own red job once the SDK gem is live: the release is
+then incomplete until `publish-binaries` is re-run. They use their own RubyGems
+trusted-publisher entry (same repo + workflow, gem name
+`microsandbox-rb-binaries`). To build them by hand:
+
+```bash
+rake -C binaries vendor[arm64-darwin]   # download + sha256-verify into binaries/vendor
+rake -C binaries build[arm64-darwin]    # package into binaries/pkg/*.gem
+rake -C binaries verify                 # host-only: run the vendored `msb --version`
+```
+
+`binaries/vendor` and `binaries/pkg` are gitignored — binaries are never
+committed; CI rebuilds them from the upstream release.

data/docs/runtime.md

@@ -0,0 +1,154 @@
+# Runtime binaries, resolution, and backends
+
+## The runtime binaries
+
+`microsandbox-rb` is **SDK-only** — it wraps the microVM runtime, it doesn't
+carry it. The host-side `msb` runtime and the `libkrunfw` firmware come from an
+optional companion gem, **`microsandbox-rb-binaries`**, published as one gem per
+platform (`arm64-darwin`, `x86_64-linux-gnu`, `aarch64-linux-gnu`) and
+versioned in lockstep with this gem:
+
+```ruby
+# Gemfile — install both gems at the same version
+gem "microsandbox-rb", require: "microsandbox"
+gem "microsandbox-rb-binaries"
+```
+
+That's all the wiring there is: `require "microsandbox"` finds the companion
+gem, checks it is the same version and built for the same upstream runtime, and
+points the resolver at its vendored `msb` — so your bundle carries the runtime
+and nothing is downloaded at install time or on first call. **Recommended
+whenever you boot local microVMs.** Cloud-only users (`MSB_BACKEND=cloud`)
+should skip it: it is a separate, optional gem precisely so nobody has to fetch
+~50 MB of binaries they won't run. Neither gem depends on the other.
+
+> **Availability.** The binaries gems are published on every release tag
+> alongside `microsandbox-rb` since `0.14.0`. On an older SDK version, or a
+> platform without a bundle, use the fallback below (or build them yourself
+> from `binaries/` — see [binaries/README.md](https://github.com/ya-luotao/microsandbox-rb/blob/main/binaries/README.md)).
+
+### Fallback — first-use download
+
+Without the companion gem, the `msb` runtime and `libkrunfw` firmware are
+provisioned into `~/.microsandbox` automatically on first use (the first
+`Sandbox.create`/`start` downloads them if missing). To provision ahead of time
+— e.g. while baking a container image, or to avoid the first-call latency —
+call `install` explicitly:
+
+```ruby
+Microsandbox.install unless Microsandbox.installed?
+```
+
+Set `MICROSANDBOX_NO_AUTO_INSTALL` to disable the automatic first-use download
+(e.g. on air-gapped hosts that provision the runtime out of band). None of this
+applies when the companion gem supplies the runtime: its binaries are already
+the matching version, so `ensure_runtime!` skips the installer entirely and
+nothing is written to `~/.microsandbox`. `Microsandbox.setup` customizes the
+provisioning step itself.
+
+## Runtime path resolution
+
+The `msb` runtime path is resolved in this order: the `MSB_PATH` environment
+variable → the `microsandbox-rb-binaries` gem (or another SDK-set override) →
+the config file → `~/.microsandbox/bin/msb` → `msb` on `PATH`.
+`Microsandbox.runtime_path` reports the winner.
+
+```ruby
+Microsandbox.installed?            # => true/false
+Microsandbox.install               # download + install the runtime (idempotent)
+Microsandbox.runtime_path          # => "/Users/you/.microsandbox/bin/msb"
+Microsandbox.runtime_path = "/opt/microsandbox/bin/msb"  # override (set-once)
+Microsandbox.libkrunfw_path = "/opt/microsandbox/lib/libkrunfw.dylib"  # override (set-once)
+```
+
+When `microsandbox-rb-binaries` is installed, `require "microsandbox"` claims
+that SDK-set slot with the gem's vendored `msb` (the firmware is found alongside
+it), and `runtime_path` points into the gem. The two gems are versioned in
+lockstep and the companion gem must be the same version **and** built for the
+same upstream runtime — a mismatch of either is reported with a warning and
+skipped, and the SDK falls back to `~/.microsandbox` rather than driving a
+runtime it doesn't match. Because the slot is **set-once**,
+`Microsandbox.runtime_path=` is then a no-op: use the `MSB_PATH` environment
+variable, which outranks it, to point at a different runtime.
+
+## Backend routing
+
+Every operation runs through a backend. The default is the local libkrun
+backend; without any configuration nothing changes. A backend can be selected
+programmatically or via the environment:
+
+```ruby
+Microsandbox.default_backend_kind          # => :local (or :cloud)
+Microsandbox.default_backend_info          # => Microsandbox::BackendInfo
+Microsandbox.set_default_backend(:cloud, url: "https://api.example.com", api_key: ENV["MSB_API_KEY"])
+# or a named profile from ~/.microsandbox/config.json:
+Microsandbox.set_default_backend(:cloud, profile: "prod")
+
+# Scoped override (restored afterward, even on error):
+Microsandbox.with_backend(:local) do
+  Microsandbox::Sandbox.create("box", image: "alpine") { |sb| puts sb.shell("uname -a").stdout }
+end
+```
+
+Resolution order when no backend is set programmatically: `MSB_BACKEND`
+(`local`/`cloud`) → `MSB_PROFILE` → the `active_profile` in
+`~/.microsandbox/config.json` (path overridable via `MSB_CONFIG_PATH`) →
+local. **Cloud intent must be explicit** (since runtime `v0.6.9`): a bare
+`MSB_API_KEY` is treated as credential material, not backend intent, and no
+longer selects the cloud on its own — pair it with `MSB_BACKEND=cloud` (which
+reads `MSB_API_URL`/`MSB_API_KEY`), or select a cloud profile. Invalid cloud
+configuration (e.g. `MSB_BACKEND=cloud` without a usable API key or cloud
+profile) fails closed with `Microsandbox::InvalidConfigError` instead of
+silently running locally. The cloud backend currently supports a subset of
+operations (create/start/stop/remove/get/list, one-shot exec, follow log
+streaming); unsupported operations raise `Microsandbox::UnsupportedError`
+(with `#operation` and `#hint`).
+
+## One runtime line per home
+
+The runtime home (`MSB_HOME`, default `~/.microsandbox`) belongs to one
+runtime line at a time. This gem embeds runtime `v0.6.18` and, on first use,
+installs that version of `msb` into the home — replacing a different version
+that is already there, including a newer `msb` installed by the official CLI.
+In the other direction, a `0.7.x` `msb` migrates the catalog to a newer schema
+the first time it opens it, after which every local call from this gem fails
+with `database schema is newer than this msb binary`. The migration is one-way.
+
+If the official CLI (or another SDK) on a different runtime line shares the
+machine, give this gem its own home:
+
+```sh
+export MSB_HOME="$HOME/.microsandbox-rb"
+```
+
+## Known issues at the pinned runtime
+
+These are fixed upstream in runtime releases this gem has not adopted yet. See
+[SECURITY.md](../SECURITY.md) for the security advisories.
+
+- **macOS hosts: guest `fallocate` can truncate a file on a bind mount or a
+  directory-backed named volume.** Preallocating a range that ends inside an
+  existing file shrinks the file to the end of that range, and the call
+  reports success. Fixed upstream in `v0.7.0`. Until then, keep data that
+  guest programs preallocate (databases, download tools) on the guest's OCI
+  root disk or a `disk:` volume, not on a host directory.
+- **`modify(secrets:)` adding the first secret** to a sandbox created without
+  any does not turn on TLS interception, so the value is not substituted.
+  Create the sandbox with at least one secret.
+- **`patches:`** resets the owner and mode of parent directories that already
+  exist in the image to `root:root 0755`. Write after boot with `sb.fs`, or
+  restore ownership yourself.
+
+## Environment variables
+
+| Variable | Effect |
+|----------|--------|
+| `MSB_PATH` | Path to the `msb` runtime binary; outranks every other source, including the binaries gem |
+| `MSB_LIBKRUNFW_PATH` | Path to the `libkrunfw` shared library; outranks `Microsandbox.libkrunfw_path=` |
+| `MSB_HOME` | Runtime home: the catalog, image cache, sandboxes, volumes, snapshots, and the first-use runtime install. Default `~/.microsandbox` |
+| `MSB_BACKEND` | `local` or `cloud`; cloud additionally reads `MSB_API_URL` / `MSB_API_KEY` |
+| `MSB_PROFILE` | Select a named profile from the config file |
+| `MSB_CONFIG_PATH` | Override the `~/.microsandbox/config.json` location |
+| `MICROSANDBOX_NO_AUTO_INSTALL` | Disable the first-use runtime download |
+| `MICROSANDBOX_INTEGRATION` | Set to `1` to run the integration specs (development only) |
+| `MICROSANDBOX_TEST_IMAGE` | Override the integration-spec image (development only) |

data/docs/surface.md

@@ -0,0 +1,75 @@
+# Supported surface
+
+The binding covers the official-SDK surface of the upstream Rust core. This
+page is the authoritative scope statement; `sig/microsandbox.rbs` is the typed
+counterpart, and [DESIGN.md](../DESIGN.md) explains how the layers fit.
+
+## Implemented
+
+- **Sandbox lifecycle** — the live `Sandbox` (`stop`/`stop_and_wait`/`kill`/
+  `drain`/`wait`/`status`/`detach`/`owns_lifecycle?`), the `SandboxHandle`
+  controls from `Sandbox.get` (`stop_with_timeout`/`request_stop`/
+  `request_kill`/`request_drain`/`wait_until_stopped`/`config`/`config_json`/
+  `snapshot`), the cursor-paginated `list`/`list_with` with label filters, and
+  the convergent lifecycle (`connect_or_create`, `#id`, `wait_for_status`,
+  `restart`, `destroy`, `SandboxHandle#connect_or_start`,
+  `SandboxReplacedError`).
+- **Backend routing** — `set_default_backend`/`with_backend`/
+  `default_backend_kind`/`default_backend_info`.
+- **Execution** — `exec`/`shell` (collected and streaming), the default
+  workload (`exec_default`/`exec_default_stream`/`attach_default`, `cmd:`),
+  interactive `attach`/`attach_shell`, per-call `rlimits`.
+- **Guest filesystem** — the full API including streaming `read_stream`/
+  `write_stream`.
+- **Observability** — per-sandbox `metrics`, `Microsandbox.all_sandbox_metrics`,
+  streaming `metrics_stream`/`log_stream`, `logs`, `ping`/`touch`.
+- **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`).
+- **Named volumes** — `Volume.create`/`get`/`list`/`remove`/`get_default`, plus
+  host-side `Volume.fs`/`VolumeInfo#fs` read/write.
+- **Snapshots** — create/open/list/list_dir/reindex/verify/save/load, boot from
+  snapshot, opt-in `record_integrity:`.
+- **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:`; `oci_upper_size:` is the
+  deprecated alias for a managed `root_disk:` size.
+- **Network configuration** — composable profiles, custom per-rule
+  `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 `on_violation:` and sandbox-level `on_secret_violation:` policy.
+- **SSH** — `Sandbox#ssh` → `SshClient`/`SftpClient`/`SshServer`, with
+  `inactivity_timeout:`.
+- **Raw agent client** — `Microsandbox::AgentClient` → `AgentStream`/
+  `AgentFrame`.
+- **Runtime provisioning** — `install`/`installed?`/`ensure_runtime!`/
+  `runtime_path`/`libkrunfw_path`, customizable via `Microsandbox.setup`; the
+  companion `microsandbox-rb-binaries` gem.
+- **Registries** — `registry_auth`/`registry_insecure`/`registry_ca_certs` on
+  `create`.
+- **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`, named `scripts`, the image
+`entrypoint`/`cmd` overrides, `init`/`ephemeral`,
+disk-image `fstype`, `ports`/`ports_udp`, network policy + config,
+`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`.
+
+## Not yet exposed
+
+A few secondary upstream knobs are not yet exposed: per-published-port host
+bind address (ports always bind loopback), network interface overrides, and
+inline named-volume create-mode (pre-create the volume with `Volume.create`,
+then mount it with `{ named: "…" }`).

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.0"
+# 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))?;