microsandbox-rb 0.13.0 → 0.15.0

data/DESIGN.md

@@ -85,28 +85,106 @@ and the Rust→class mapping in `sdk/python/src/error.rs`.
 
 ## Runtime binary (`msb` + `libkrunfw`)
 
-The core crate's `prebuilt` feature (on by default) downloads the `msb` microVM
-runtime and `libkrunfw` firmware into `~/.microsandbox/{bin,lib}` **at build
-time** (`build.rs`). The path resolver checks, in order: `$MSB_PATH` →
-SDK-set path (`Microsandbox.runtime_path=`) → config file → workspace build →
-`~/.microsandbox/bin/msb` → `which msb`. `Microsandbox.install` / `.installed?`
-expose the core `setup::install`/`is_installed` for explicit, idempotent
-provisioning (mirrors the Python `install()`/`is_installed()`).
-
-Build-time provisioning only helps the **source gem**, where `build.rs` runs on
-the user's own machine. A **precompiled gem** is built in CI, so its build-time
-download lands on the CI host, not the user's — the user's `~/.microsandbox` is
-empty. `Microsandbox.ensure_runtime!` closes that gap: `Sandbox.create`/`start`
-call it to fetch the runtime on first use (by the *running* host's arch, which is
-always correct), at most once per process. `MICROSANDBOX_NO_AUTO_INSTALL` opts
-out (air-gapped hosts that provision out of band). libkrunfw is `dlopen`'d by
-`msb` at runtime and is never linked into the extension.
+The gem is **SDK-only**: nothing is provisioned while it is built or installed.
+The core crate's `prebuilt` feature — whose `build.rs` downloads the `msb`
+microVM runtime and `libkrunfw` firmware into `~/.microsandbox/{bin,lib}` at
+build time — is deliberately **off** (`default-features = false`, features
+`keyring`/`net`/`ssh`, the set the official SDKs ship). Build-time provisioning
+only ever helped the source gem: for a precompiled gem the download lands on the
+CI host, and even for a source install it couples "compile a Ruby extension" to
+"fetch 50 MB of host binaries", which is not the compiler's business.
+
+The *guest* agent is a different story and is still embedded at build time: the
+`agentd` binary that runs as PID 1 inside every microVM is `include_bytes!`-d
+into the extension by `microsandbox-filesystem`'s `build.rs`, keyed by *target*
+arch. Without its `prebuilt` feature that build script demands a locally built
+`build/agentd` (workspace-only), so `ext/microsandbox/Cargo.toml` enables exactly
+that one sub-feature through a direct `microsandbox-runtime` dependency
+(`default-features = false, features = ["prebuilt"]`, whose `prebuilt` is just
+`microsandbox-filesystem/prebuilt`) while the SDK-level host download stays off.
+
+### The companion gem
+
+The host runtime ships as its own gem, **`microsandbox-rb-binaries`** (source in
+`binaries/`), one platform gem per `arm64-darwin` / `x86_64-linux-gnu` /
+`aarch64-linux-gnu` (Linux binaries are glibc-linked, hence
+`required_rubygems_version >= 3.3.11`). It carries `vendor/bin/msb`,
+`vendor/lib/libkrunfw.*` and a `vendor/manifest.json` — a layout that mirrors
+both the upstream release bundle and `~/.microsandbox`, so the core finds the
+firmware by `../lib` adjacency to `msb` and only the binary path needs handing
+over (same trick as the Python and Node SDKs). Everything is downloaded from the
+upstream GitHub release named by `Microsandbox::Binaries::RUNTIME_VERSION` and
+sha256-verified fail-closed against that release's `checksums.sha256` — the copy
+committed as `binaries/checksums/<tag>.sha256` when the runtime was adopted
+(a GitHub release is mutable, so the live file must agree with the reviewed
+one, not replace it) — at vendoring time; the gem build re-verifies the staged
+tree against the manifest (regular files only), so nothing unverified is ever
+packaged. Build pipeline:
+`rake -C binaries vendor[<platform>] build[<platform>] verify`.
+
+There is **no dependency edge in either direction**. RubyGems has no optional
+dependencies, and cloud-only users (`MSB_BACKEND=cloud`) must not be forced to
+download ~50 MB of binaries they will never execute — so the SDK discovers the
+companion gem instead of depending on it, and the companion gem stays a pure
+payload. The two are versioned in lockstep (`Binaries::VERSION` ==
+`Microsandbox::VERSION`, `Binaries::RUNTIME_VERSION` == `RUNTIME_VERSION`, both
+asserted by `spec/unit/version_spec.rb`).
+
+### Activation and the resolver ladder
+
+`lib/microsandbox.rb` runs a private `activate_bundled_runtime!` once, at
+`require "microsandbox"` time: `gem "microsandbox-rb-binaries", "= VERSION"`
+(pins the lockstep version when RubyGems, not Bundler, picks the gem; a failure
+here is tolerated) → `require "microsandbox/binaries"` (`LoadError` → the tier is
+simply absent, silently) → `Binaries::VERSION` must equal `VERSION` and
+`Binaries::RUNTIME_VERSION` must equal `RUNTIME_VERSION` (the `gem` pin above
+cannot enforce lockstep: under Bundler it raises whenever the bundle picked any
+other version, and that is swallowed) **and** both `msb_path` and
+`libkrunfw_path` must exist →
+`Native.set_runtime_msb_path(msb)`. The version gate is the load-bearing part: a
+runtime from a different upstream release passes any exists-check and then fails
+every `create` on a wire-protocol mismatch, so a mismatch is reported with a
+warning and skipped rather than handed to the core. The whole path is
+non-raising — a broken companion gem must never take `require "microsandbox"`
+down with it.
+
+Activation is **eager** rather than lazy, mirroring the Node SDK (`napi.ts`
+pushes its platform package's `msb` into the same set-once slot at module load).
+A lazy hook inside `ensure_runtime!` would only cover `Sandbox.create`/`start`
+and silently miss every other entry point that resolves or spawns `msb`.
+
+The resolver order is therefore: `$MSB_PATH` → SDK-set path (claimed by the
+companion gem at load; `Microsandbox.runtime_path=` targets this same set-once
+slot, so with the gem installed the setter is a **no-op** — override via
+`MSB_PATH`) → config file → workspace build → `~/.microsandbox/bin/msb` →
+`which msb`. `Microsandbox.runtime_path` reports the winner.
+`Microsandbox.install` / `.installed?` expose the core `setup::install`/
+`is_installed` for explicit, idempotent provisioning (mirrors the Python
+`install()`/`is_installed()`).
+
+Auto-provisioning stays as the **lowest tier**, deliberately (npx-style
+first-use download; see upstream discussion
+[superradcompany/microsandbox#1305](https://github.com/superradcompany/microsandbox/issues/1305)):
+`Sandbox.create`/`start` call `Microsandbox.ensure_runtime!`, which fetches a
+missing or version-stale runtime into `~/.microsandbox` on first use — by the
+*running* host's arch, which is always correct — at most once per process.
+`MICROSANDBOX_NO_AUTO_INSTALL` opts out (air-gapped hosts that provision out of
+band). When the companion gem won the resolver (`bundled_runtime_active?`),
+`ensure_runtime!` returns immediately: those binaries are already the matching
+version, so nothing is downloaded or touched in `~/.microsandbox`. Note the
+asymmetry in trust: the companion gem's payload is digest-verified when it is
+vendored, while the first-use download is not yet content-verified (pending
+upstream
+[superradcompany/microsandbox#1300](https://github.com/superradcompany/microsandbox/issues/1300)).
+
+libkrunfw is `dlopen`'d by `msb` at runtime and is never linked into the
+extension.
 
 ## Core-crate dependency (self-contained)
 
 `ext/microsandbox/Cargo.toml` depends on the core crate via a **pinned git tag**
 (`microsandbox` / `microsandbox-network`, pinned to the same tag as
-`Microsandbox::RUNTIME_VERSION` — currently `v0.6.2`), so the gem builds anywhere
+`Microsandbox::RUNTIME_VERSION` — currently `v0.6.14`), so the gem builds anywhere
 — CI, `rake-compiler-dock` release containers, and end-user source installs —
 without an adjacent checkout. For fast local development against a sibling
 microsandbox checkout, copy `.cargo/config.toml.example` to `.cargo/config.toml`
@@ -122,7 +200,8 @@ git. The override must never be committed — it would break container builds.
   (`rake-compiler-dock`) per `Gem::Platform`, shipping multi-ABI
   `lib/microsandbox/<ruby_abi>/` native artifacts — the same model Node uses with
   per-platform packages. End users then install with no Rust toolchain, and the
-  runtime is fetched on first use (see above). The guest `agentd` is baked into
+  host runtime comes from the `microsandbox-rb-binaries` gem — or, without it, is
+  fetched on first use (see above). The guest `agentd` is baked into
   the extension by *target* arch (`filesystem/build.rs` uses
   `CARGO_CFG_TARGET_ARCH` + `include_bytes!`), so it cross-compiles correctly;
   the real cross work is linking the *target* native libs — `libcap-ng` on Linux
@@ -133,6 +212,16 @@ git. The override must never be committed — it would break container builds.
   since CI can't boot a microVM to prove a built gem actually works, gems are
   promoted to the publish path manually after per-platform validation. Published
   to RubyGems via Trusted Publishing (OIDC). See [Releasing](README.md#releasing).
+* **Runtime binaries gems** (`microsandbox-rb-binaries`): a distinct artifact
+  from the precompiled *extension* gems above — no Ruby code beyond a small
+  locator module, just the verified upstream `msb` + `libkrunfw` for one
+  platform. CI's `binaries` job vendors and builds all three platforms on every
+  run and smoke-tests the host one; the `package` job installs the source gem
+  together with the host binaries gem and asserts `Microsandbox.runtime_path`
+  resolves into it, and the real-microVM integration job runs twice — once
+  against a `~/.microsandbox` provision (the fallback tier) and once booting from
+  the gem's vendored runtime. Publishing them is a follow-up (it needs a pending
+  trusted publisher on rubygems.org) and lands with the next release.
 
 ## Build requirements
 

data/README.md

@@ -58,6 +58,10 @@ them. Our deepest thanks to the maintainers and community. 🙏
 - A **Rust** toolchain (stable >= 1.91) — needed only when installing the source
   gem (it compiles the native extension on install). Precompiled per-platform
   gems, where available, require no Rust toolchain; see [Releasing](#releasing)
+- The **`msb` runtime + `libkrunfw` firmware** — shipped by the optional
+  companion gem `microsandbox-rb-binaries`, or downloaded into `~/.microsandbox`
+  on first use; see [The runtime binaries](#the-runtime-binaries). Cloud-only
+  users (`MSB_BACKEND=cloud`) need no local runtime at all
 
 ## Installation
 
@@ -80,17 +84,49 @@ takes a few minutes and needs a Rust toolchain (`rustc >= 1.91`) on `PATH`. When
 a **precompiled platform gem** is available for your OS/architecture, RubyGems
 picks it automatically and no Rust toolchain is required.
 
-Either way 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:
+### 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` (first release to ship them: the one after
+> 0.13.0). On an older SDK version, or a platform without a bundle, use the
+> fallback below (or build them yourself from `binaries/` — see that
+> directory's README).
+
+**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).
+(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`.
 
 ## Quick start
 
@@ -428,8 +464,9 @@ end
 ## Runtime configuration
 
 The `msb` runtime path is resolved in this order: the `MSB_PATH` environment
-variable → an SDK-set override → the config file → `~/.microsandbox/bin/msb` →
-`msb` on `PATH`.
+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
@@ -439,6 +476,16 @@ 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`](#the-runtime-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
 
 As of v0.5.8 every operation runs through a backend. The default is the local
@@ -477,10 +524,17 @@ change diverged the two numbers — the gem version is **not** a reliable indica
 of the embedded runtime version. To learn which runtime a build wraps, ask it:
 
 ```ruby
-Microsandbox::VERSION          # => "0.13.0"  (the gem's own version)
-Microsandbox.runtime_version   # => "v0.6.9"  (the embedded upstream runtime tag)
+Microsandbox::VERSION          # => "0.15.0"  (the gem's own version)
+Microsandbox.runtime_version   # => "v0.6.14" (the embedded upstream runtime tag)
 ```
 
+The companion [`microsandbox-rb-binaries`](#the-runtime-binaries) gem is
+versioned in **lockstep** with this gem (same number, released together) and
+pins the same upstream runtime — install both at the same version. The gem's
+`Microsandbox::Binaries::VERSION` and `::RUNTIME_VERSION` are asserted against
+this gem's constants by the test suite, so a companion gem can't silently go
+stale.
+
 | Gem version | Upstream runtime | Notes |
 |-------------|------------------|-------|
 | `0.5.7`  | `v0.5.7` | initial release |
@@ -502,6 +556,8 @@ Microsandbox.runtime_version   # => "v0.6.9"  (the embedded upstream runtime tag
 | `0.11.0` | `v0.6.7` | adopts upstream `v0.6.7` (**breaking**): network profiles replace `public_only`/`non_local`, structured `root_disk:` replaces `oci_upper_size:` (deprecated alias kept), snapshot descriptor contract (`create` re-keyed by name, `save`/`load` rename, `snapshot_to` removed, on-disk auto-migration), `Image.load`/`Image.save`, `follow_root_symlinks:`; runtime carries the GHSA-4vq3-cjpp-v7fg `msb copy` fix |
 | `0.12.0` | `v0.6.8` | adopts upstream `v0.6.8` (**breaking**): `Sandbox.list`/`.list_with` return a cursor-paginated `SandboxPage` (`limit:`/`cursor:` keywords), `UnsupportedError` re-keyed by structured operations with `#operation`/`#hint`; runtime adds a shared log registry for followed streams and cloud exec/ssh reconnects |
 | `0.13.0` | `v0.6.9` | adopts upstream `v0.6.9` (**breaking**): a bare `MSB_API_KEY` no longer selects the cloud backend (explicit `MSB_BACKEND=cloud` or a cloud profile required; invalid cloud config fails closed with `InvalidConfigError`); snapshot payload integrity becomes opt-in (`record_integrity:`, `verify` can report `:not_recorded`). Parity: default-workload execution (`exec_default`/`exec_default_stream`/`attach_default`, `cmd:`), flat root disks (`RootDisk.flat`), `modify(root_disk_size:)`, `rate_limiter:`, `vsock:`, `default_backend_info`, `Volume.get_default` |
+| `0.14.0` | `v0.6.9` | two-gem split: SDK-only gem (no build-time runtime download) + companion `microsandbox-rb-binaries` platform gems |
+| `0.15.0` | `v0.6.14` | adopts upstream `v0.6.10`–`v0.6.14` step by step: bind-mount correctness, guest bootstrap off the kernel command line, DNS pins for deferred domain allows, Linux glibc 2.28 baseline for the prebuilt runtime, legacy ext4 upper-disk resize, `msb_krun` 0.1.32. Parity: `ssh.open_client`/`prepare_server` accept `inactivity_timeout:` (seconds; `0` disables, `nil` inherits the 600s global default) |
 
 **Going forward** — the gem version moves on its own semver track and no longer
 mirrors the upstream tag:
@@ -555,7 +611,11 @@ or credential setup is needed.
    the number to mirror the upstream tag. If the release also adopts a new upstream
    runtime, bump the `tag = "vX.Y.Z"` on **both** the `microsandbox` and
    `microsandbox-network` git deps, update `Microsandbox::RUNTIME_VERSION` to match,
-   and add a row to the Versioning table. Update `CHANGELOG.md`.
+   and add a row to the Versioning table. Also bump
+   `Microsandbox::Binaries::VERSION` (and, on a runtime adoption,
+   `::RUNTIME_VERSION`) in `binaries/lib/microsandbox/binaries.rb` — the
+   companion gem ships in lockstep and the specs assert both. Update
+   `CHANGELOG.md`.
 2. Push a `vX.Y.Z` tag. CI builds the **source gem** and pushes it to RubyGems
    via `rubygems/configure-rubygems-credentials` (OIDC, `id-token: write`) — no
    `RUBYGEMS_API_KEY` secret required.
@@ -568,13 +628,29 @@ or credential setup is needed.
 > prove otherwise — so promotion is manual after validating the artifact on each
 > platform. A precompiled gem ships the compiled extension (with the guest
 > `agentd` baked in by *target* arch); the host-side `msb` + `libkrunfw` runtime
-> is fetched into `~/.microsandbox` on first use by `Microsandbox.ensure_runtime!`
-> (libkrunfw is `dlopen`'d by `msb` at runtime, never linked into the gem). The
+> is **not** in it — that comes from the companion `microsandbox-rb-binaries`
+> gem, or, when that isn't installed, is fetched into `~/.microsandbox` on first
+> use by `Microsandbox.ensure_runtime!` (libkrunfw is `dlopen`'d by `msb` at
+> runtime, never linked into the gem). The
 > real cross-compile work is linking the *target* native libraries — `libcap-ng`
 > on Linux (handled via Debian multiarch in the workflow) and the Hypervisor +
 > Security frameworks on macOS (via osxcross; the one platform left to confirm).
 > Until promoted, users install the source gem (which compiles via `rb_sys`).
 
+> **Runtime binaries gems** (`microsandbox-rb-binaries`, source in `binaries/`)
+> are a *separate* artifact from the precompiled extension gems above: they carry
+> 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 (a companion
+> failure is its own red job and never blocks the SDK release).
+> They use their own RubyGems trusted-publisher entry (same repo + workflow,
+> gem name `microsandbox-rb-binaries`). To build them by hand:
+> `rake -C binaries vendor[<platform>]` then `rake -C binaries build[<platform>]`
+> (→ `binaries/pkg/*.gem`).
+
 See [DESIGN.md](DESIGN.md) for the architecture and the implemented-surface
 section. The binding covers the official-SDK surface: sandbox
 lifecycle (the live `Sandbox` `stop`/`stop_and_wait`/`kill`/`drain`/`wait`/

data/ext/microsandbox/Cargo.toml

@@ -6,8 +6,8 @@ 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.9).
-version = "0.13.0"
+# The core-crate dependency below stays pinned at its own tag (v0.6.14).
+version = "0.15.0"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"
@@ -32,11 +32,27 @@ rb-sys = "0.9"
 # gem is self-contained and buildable anywhere (CI, release containers, end-user
 # source installs) without an adjacent checkout. For local development against a
 # sibling checkout, use the `paths` override in `.cargo/config.toml` (see
-# `.cargo/config.toml.example`). "ssh" matches the feature set the Python/Node
-# SDKs ship with; default features add "prebuilt" (provisions msb + libkrunfw at
-# build time), "net", and "keyring".
-microsandbox = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.9", default-features = true, features = ["ssh"] }
-microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.9" }
+# `.cargo/config.toml.example`).
+#
+# Features are listed explicitly (default-features = false) so the SDK crate's
+# own "prebuilt" feature stays OFF: that feature makes its build.rs download
+# the msb + libkrunfw *host runtime* into ~/.microsandbox at compile time. This
+# gem is SDK-only — the host runtime comes from the companion
+# `microsandbox-rb-binaries` gem (see binaries/) or, as the lowest tier, the
+# first-use download into ~/.microsandbox (`setup::install`, which is not
+# gated on "prebuilt"). "net"/"ssh"/"keyring" are the features the official
+# SDKs ship with.
+microsandbox = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.14", default-features = false, features = ["keyring", "net", "ssh"] }
+microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.14" }
+# The *guest* agent (`agentd`, PID 1 inside every microVM) is embedded into the
+# extension by microsandbox-filesystem's build.rs, which without its "prebuilt"
+# feature demands a locally built `build/agentd` (workspace-only, `just
+# build-deps`). Enable that one sub-feature directly — via microsandbox-runtime,
+# whose "prebuilt" is exactly `microsandbox-filesystem/prebuilt` — so the
+# prebuilt agentd for the target arch is fetched (same behaviour as before)
+# while the SDK-level msb download above stays off. Feature unification means
+# this adds no new crates; keep it on the same tag as the deps above.
+microsandbox-runtime = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.14", default-features = false, features = ["prebuilt"] }
 
 # Async core bridged to Ruby's synchronous API via a blocking tokio runtime.
 tokio = { version = "1", features = ["rt-multi-thread", "sync", "time"] }

data/ext/microsandbox/src/sandbox.rs

@@ -866,11 +866,14 @@ impl Sandbox {
     //----------------------------------------------------------------------
 
     /// Open a native in-process SSH client to this sandbox. `opts`: user, term,
-    /// sftp (bool, default true).
+    /// sftp (bool, default true), inactivity_timeout (seconds, f64; 0 disables).
     fn ssh_open_client(&self, opts: RHash) -> Result<crate::ssh::SshClient, Error> {
         let user = conv::opt_string(opts, "user")?;
         let term = conv::opt_string(opts, "term")?;
         let sftp = conv::opt::<bool>(opts, "sftp")?.unwrap_or(true);
+        let inactivity_timeout = conv::opt_f64(opts, "inactivity_timeout")?
+            .map(secs_to_duration)
+            .transpose()?;
         let ssh = self.inner.ssh();
         let client = block_on(ssh.open_client_with(move |mut b| {
             if let Some(u) = user {
@@ -879,6 +882,9 @@ impl Sandbox {
             if let Some(t) = term {
                 b = b.term(t);
             }
+            if let Some(t) = inactivity_timeout {
+                b = b.inactivity_timeout(t);
+            }
             b.sftp(sftp)
         }))
         .map_err(error::to_ruby)?;
@@ -886,12 +892,16 @@ impl Sandbox {
     }
 
     /// Prepare a reusable SSH server endpoint. `opts`: host_key_path,
-    /// authorized_keys_path, user, sftp (bool, default true).
+    /// authorized_keys_path, user, sftp (bool, default true),
+    /// inactivity_timeout (seconds, f64; 0 disables).
     fn ssh_prepare_server(&self, opts: RHash) -> Result<crate::ssh::SshServer, Error> {
         let host_key_path = conv::opt_string(opts, "host_key_path")?;
         let authorized_keys_path = conv::opt_string(opts, "authorized_keys_path")?;
         let user = conv::opt_string(opts, "user")?;
         let sftp = conv::opt::<bool>(opts, "sftp")?.unwrap_or(true);
+        let inactivity_timeout = conv::opt_f64(opts, "inactivity_timeout")?
+            .map(secs_to_duration)
+            .transpose()?;
         let ssh = self.inner.ssh();
         let server = block_on(ssh.prepare_server_with(move |mut b| {
             if let Some(p) = host_key_path {
@@ -903,6 +913,9 @@ impl Sandbox {
             if let Some(u) = user {
                 b = b.user(u);
             }
+            if let Some(t) = inactivity_timeout {
+                b = b.inactivity_timeout(t);
+            }
             b.sftp(sftp)
         }))
         .map_err(error::to_ruby)?;

data/lib/microsandbox/ssh.rb

@@ -231,11 +231,17 @@ module Microsandbox
     # @param user [String] guest user to authenticate as (default "root")
     # @param term [String, nil] TERM value for the session
     # @param sftp [Boolean] enable the SFTP subsystem (default true)
+    # @param inactivity_timeout [Numeric, nil] per-session inactivity timeout in
+    #   seconds; `nil` inherits the global config (default 600s), `0` disables it
     # @yieldparam client [SshClient]
     # @return [SshClient, Object]
-    def open_client(user: "root", term: nil, sftp: true)
+    def open_client(user: "root", term: nil, sftp: true, inactivity_timeout: nil)
       opts = {"user" => user.to_s, "sftp" => sftp ? true : false}
       opts["term"] = term.to_s if term
+      unless inactivity_timeout.nil?
+        opts["inactivity_timeout"] =
+          Sandbox.send(:coerce_duration, inactivity_timeout, "inactivity_timeout")
+      end
       client = SshClient.new(@native.ssh_open_client(opts))
       return client unless block_given?
 
@@ -251,12 +257,19 @@ module Microsandbox
     # @param authorized_keys_path [String, nil] authorized_keys file path
     # @param user [String, nil] guest user connections run as
     # @param sftp [Boolean] enable the SFTP subsystem (default true)
+    # @param inactivity_timeout [Numeric, nil] per-session inactivity timeout in
+    #   seconds; `nil` inherits the global config (default 600s), `0` disables it
     # @return [SshServer]
-    def prepare_server(host_key_path: nil, authorized_keys_path: nil, user: nil, sftp: true)
+    def prepare_server(host_key_path: nil, authorized_keys_path: nil, user: nil, sftp: true,
+      inactivity_timeout: nil)
       opts = {"sftp" => sftp ? true : false}
       opts["host_key_path"] = host_key_path.to_s if host_key_path
       opts["authorized_keys_path"] = authorized_keys_path.to_s if authorized_keys_path
       opts["user"] = user.to_s if user
+      unless inactivity_timeout.nil?
+        opts["inactivity_timeout"] =
+          Sandbox.send(:coerce_duration, inactivity_timeout, "inactivity_timeout")
+      end
       SshServer.new(@native.ssh_prepare_server(opts))
     end
   end

data/lib/microsandbox/version.rb

@@ -8,12 +8,12 @@ module Microsandbox
   # Versioning section of the README for the full gem-to-runtime map. Must equal
   # the native ext's Cargo crate version (`Native.version`), enforced by
   # spec/unit/version_spec.rb.
-  VERSION = "0.13.0"
+  VERSION = "0.15.0"
 
   # The upstream microsandbox runtime release this gem build embeds — the `tag`
   # pinned on the `microsandbox`/`microsandbox-network` git deps in
   # ext/microsandbox/Cargo.toml. Exposed at runtime as
   # {Microsandbox.runtime_version}. spec/unit/version_spec.rb asserts it stays in
   # sync with the Cargo tag so it can't silently drift out of date.
-  RUNTIME_VERSION = "v0.6.9"
+  RUNTIME_VERSION = "v0.6.14"
 end