microsandbox-rb 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: abfe8d0fedb192bc5efa95a741ae971475a2a5cc441879c092108bc8bdf9eed5
-  data.tar.gz: ffeb9bda17817cc1c58bfe5cc9c7d58543cde155eead9d2e5eb3844c8a48b4dd
+  metadata.gz: 158469a5ebe84ee4863c2a141cbeb486407bfc5ee05866be9005f9aee3bd249d
+  data.tar.gz: ef08b6519ac87f66c20f704e4c55590f56b3d6c05fa01ab6f9187db46f8b43af
 SHA512:
-  metadata.gz: 73379d82644123c717cd7db9391cab9bf72c16b5cf398ea104fb51d2b608353ed9cd6783db55e1490d941ae67728f1c69fe0bd2dcec37c7ad541c56996afea9f
-  data.tar.gz: b20914b13315697e89ec8a72e7620592a9c00d1e8fa908117ef24d64aea9755b431a2298b85d58ed00ca664065f0b626510c7f11fbb919860d3f839c93268a28
+  metadata.gz: d63ed9d45bdf68fb2f8352927412b23debd45e5e011f30a835fd2e75bae206e2ce19d1875c6099ce72c808c7d5e05e62a459f81794589e090ab837b9541d5da7
+  data.tar.gz: '09a726c22f8b12ecb0d575f0c4e20ce446aa5761cf5ed8cc15155a6b567e7ee867c4f95545a9595f786b88ec2f6dbd75b1bfe721fb629025ce8bfc19aa63fda0'

data/CHANGELOG.md

@@ -8,6 +8,96 @@ wraps, and the README's Versioning section keeps the full gem→runtime map.
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-06-23
+
+A large parity release closing the binding gaps an audit against the upstream
+Python/Node SDKs (at the wrapped `v0.5.8` runtime) surfaced. The runtime tag is
+unchanged. Two genuine bug fixes; the rest is newly-exposed surface plus a few
+behavior corrections (see **Changed**).
+
+### Fixed
+
+- **Lossy UTF-8 decoding.** `LogEntry#text`, `ExecOutput#stdout`/`#stderr`,
+  `ExecEvent#text`, `SshOutput#stdout`/`#stderr`, and `SftpClient#read_text` now
+  scrub invalid byte sequences (replacing them with U+FFFD) so they always
+  return a *valid* UTF-8 String — matching the Python/Node SDKs. Previously they
+  re-tagged raw bytes as UTF-8 without transcoding, so captured output
+  containing invalid UTF-8 produced strings that raised downstream (regex,
+  concatenation, `JSON.generate`). Raw bytes remain available via `#data` /
+  `#stdout_bytes` / `#stderr_bytes`.
+- **`runtime_path=` spec** no longer pollutes the process-wide set-once
+  `msb`-path `OnceLock` (it now stubs the native setter), removing an
+  order-dependent failure in combined unit+integration runs.
+
+### Added
+
+- **Streaming image-pull progress** — `Sandbox.create_with_progress` returns a
+  `PullSession` (an `Enumerable` of progress-event Hashes) with `#sandbox` for
+  the booted sandbox.
+- **Host-side volume filesystem** — `Volume.fs(name)` / `VolumeInfo#fs` return a
+  `VolumeFs` (read/read_text/write/list/mkdir/remove_file/remove_dir/exists?/
+  copy/rename/stat) that reads and writes a named volume without a running
+  sandbox.
+- **Streaming guest filesystem** — `FS#read_stream` / `FS#write_stream`
+  (`FsReadStream`/`FsWriteSink`) for files too large to buffer in memory.
+- **Full secrets surface** — `secrets:` entries accept `hosts:` / `host_patterns:`
+  (wildcards) allow-lists, `placeholder:`, `require_tls:`, injection toggles
+  (`inject_headers:`/`inject_basic_auth:`/`inject_query:`/`inject_body:`), and
+  per-secret `on_violation:`; plus a sandbox-level `on_secret_violation:`. The
+  block-variant actions accept both the underscore form (`block_and_log`) and the
+  upstream kebab-case wire spelling (`block-and-log`) used by the CLI / Go SDK /
+  config files; the bare `"passthrough"` string (passthrough-all-hosts, as in the
+  Python/Node SDKs) is also accepted, so a policy copied from another SDK ports
+  over unchanged.
+- **Network configuration** — `Sandbox.create` now accepts `dns:` (nameservers/
+  rebind_protection/query_timeout_ms), `tls:` (interception tuning incl. bypass
+  patterns, intercepted ports, block_quic, and CA cert/key paths), `ipv4_pool:`/
+  `ipv6_pool:`, `max_connections:`, and `trust_host_cas:`.
+- **Create options** — `init:`/`init_with` (hand guest PID 1 to an init system),
+  `ephemeral:` (auto-remove state on terminal), and disk-image `fstype:`.
+  `fstype:` is rejected up front unless `image:` is a disk-image path (a local
+  path ending in `.raw`/`.qcow2`/`.vmdk`); pairing it with an OCI reference no
+  longer routes the ref through the disk-image builder and fails at boot.
+- **Full mount options** — `volumes:` now supports `{ tmpfs: }`, `{ disk:,
+  format:, fstype: }`, and per-mount `stat_virtualization:`/`host_permissions:`
+  alongside the existing bind/named + ro/noexec/nosuid/nodev flags. The pre-0.7.0
+  `options: %w[ro noexec]` array form is still honored (translated onto the
+  boolean flags); an unrecognized token now raises rather than being silently
+  dropped, so a requested read-only/noexec mount can't quietly become writable.
+- **Snapshots** — `Snapshot.open`/`list_dir`/`reindex`, `SnapshotInfo#open`/
+  `#remove`, and `SandboxHandle#snapshot`/`#snapshot_to`. `SnapshotInfo` now
+  carries the full manifest (`image_manifest_digest`, `fstype`,
+  `source_sandbox`, `labels`) on the artifact-opening paths.
+- **`SandboxHandle#config` / `#config_json`** — read the stored sandbox config.
+- **Metrics** — `upper_used_bytes`, `upper_free_bytes`,
+  `upper_host_allocated_bytes` (OCI writable-upper-layer accounting).
+- **`ImageDetail#config["labels"]`** — OCI config labels.
+- **`Microsandbox.setup`** — customizable runtime install (`base_dir:`,
+  `version:`, `force:`, `skip_verify:`); `force:` repairs a corrupt install.
+
+### Changed
+
+- **`exec`/`shell` stdin** is now a closed set: `nil`/`:null` = no stdin,
+  `:pipe` = streaming pipe (streaming variants only), a String = bytes. An
+  unrecognized Symbol now raises `ArgumentError` instead of being fed as its
+  characters (so a mistaken `stdin: :null` no longer sends the literal `"null"`).
+- **Write methods reject non-Strings.** `FS#write`, `SftpClient#write`,
+  `ExecStdin#write`, `VolumeFs#write`, and `FsWriteSink#write` now raise
+  `TypeError` for non-String data instead of silently writing its `to_s` form.
+- **Agent connect timeout.** `AgentClient.connect_sandbox`/`connect_path`
+  `timeout:` now treats `0` as an immediate deadline and raises on a
+  negative/non-finite value, instead of silently falling back to the default.
+- **Secrets shorthand** still accepts `{ env:, value:, host: }`; the validation
+  message changed and a host allow-list is now required.
+
+### Docs
+
+- README/DESIGN implemented-surface corrected to match the binding (and to list
+  the few secondary knobs still not exposed); assorted YARD fixes
+  (`runtime_path=` set-once note, `VolumeInfo#kind` `:dir`, `create`'s
+  `volumes:`/`from_snapshot:` params, `log_stream` `'all'` source); CHANGELOG
+  compare links added for 0.5.9–0.5.12.
+
 ## [0.6.0] - 2026-06-23
 
 This release puts the gem on its **own semantic version**, decoupled from the
@@ -291,7 +381,12 @@ microsandbox runtime, aligned with the official Python/Node/Go SDKs.
   core crate has Apple-native deps). Until precompiled gems are published,
   installing from source requires a Rust toolchain (stable >= 1.91).
 
-[Unreleased]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.5.12...v0.6.0
+[0.5.12]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.5.11...v0.5.12
+[0.5.11]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.5.10...v0.5.11
+[0.5.10]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.5.9...v0.5.10
+[0.5.9]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.5.8...v0.5.9
 [0.5.8]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.5.7...v0.5.8
 [0.5.7]: https://github.com/superradcompany/microsandbox/releases/tag/v0.5.7

data/Cargo.lock

@@ -3249,7 +3249,7 @@ dependencies = [
 
 [[package]]
 name = "microsandbox_rb"
-version = "0.6.0"
+version = "0.7.0"
 dependencies = [
  "chrono",
  "futures",

data/DESIGN.md

@@ -183,9 +183,19 @@ The binding is verified at four levels:
    microVM, confirming the gem manifest and source-install path are complete.
 
 **Roadmap:** the v1 roadmap (custom per-rule network policies, file patches,
-interactive `attach`/`attach_shell`, SSH, and the raw agent client) is now
-implemented — see the list above. What remains is upstream-gated rather than a
-binding gap: surfacing newer core features as the pinned core-crate tag advances
-(e.g. additional network knobs like DNS/TLS-proxy tuning and per-mount stat
-virtualization), which slot in module-by-module exactly as the existing bindings
-do.
+interactive `attach`/`attach_shell`, SSH, and the raw agent client) is
+implemented, and so is the bulk of the v0.5.8 configuration surface that a
+later parity pass added: streaming image-pull progress, host-side `VolumeFs`,
+streaming guest fs (`read_stream`/`write_stream`), the full secrets surface,
+network configuration (DNS, TLS-interception tuning, IPv4/IPv6 pools,
+`max_connections`, `trust_host_cas`), `init`/`ephemeral`/disk-image `fstype`
+create options, full mount options (tmpfs/disk + stat-virtualization/
+host-permissions), and snapshot inspection (`open`/`list_dir`/`reindex`).
+
+A few **secondary** upstream knobs remain unexposed (a genuine binding gap, not
+upstream-gated — they exist at the pinned `v0.5.8`): per-published-port host
+**bind address** (ports always bind loopback), network **interface overrides**,
+and inline **named-volume create-mode** (pre-create with `Volume.create`, then
+mount with `{ named: }`). These slot in module-by-module exactly as the existing
+bindings do. Beyond those, surfacing genuinely newer core features is gated on
+advancing the pinned core-crate tag.

data/README.md

@@ -347,7 +347,7 @@ variable → an SDK-set override → the config file → `~/.microsandbox/bin/ms
 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
+Microsandbox.runtime_path = "/opt/microsandbox/bin/msb"  # override (set-once)
 Microsandbox.libkrunfw_path = "/opt/microsandbox/lib/libkrunfw.dylib"  # override (set-once)
 ```
 
@@ -470,25 +470,38 @@ or credential setup is needed.
 > Until promoted, users install the source gem (which compiles via `rb_sys`).
 
 See [DESIGN.md](DESIGN.md) for the architecture and the implemented-surface
-section. The binding now covers the full official-SDK surface: sandbox
+section. The binding covers the official-SDK surface: sandbox
 lifecycle (the live `Sandbox` `stop`/`stop_and_wait`/`kill`/`drain`/`wait`/
 `status`/`detach`/`owns_lifecycle?`, plus the `SandboxHandle` controls
 `stop_with_timeout`/`request_stop`/`request_kill`/`request_drain`/
-`wait_until_stopped` from `Sandbox.get`, and label-filtered `list_with`),
+`wait_until_stopped`/`config`/`config_json`/`snapshot`/`snapshot_to` from
+`Sandbox.get`, and label-filtered `list_with`),
 backend routing (`set_default_backend`/`with_backend`/`default_backend_kind`),
 `exec`/`shell` (collected and streaming), interactive `attach`/
-`attach_shell`, the full guest filesystem, metrics (per-sandbox,
-`Microsandbox.all_sandbox_metrics`, and streaming `metrics_stream`/`log_stream`),
-logs, OCI image-cache management, named volumes, snapshots (create/list/verify/
-export/import + boot-from-snapshot), **rootfs patches** (`Microsandbox::Patch`),
-**custom per-rule network policies** (`Microsandbox::NetworkPolicy`/`Rule`/
-`Destination`, alongside the presets), **SSH** (`Sandbox#ssh` →
-`SshClient`/`SftpClient`/`SshServer`), and the **raw agent client**
-(`Microsandbox::AgentClient`). Create options span resources, network policy,
-`log_level`/`security`/`rlimits`/`pull_policy`/`secrets`/`patches` and more;
-`exec`/`shell` take per-call `rlimits`, and `create` accepts
+`attach_shell`, the full guest filesystem (incl. streaming `read_stream`/
+`write_stream`), metrics (per-sandbox, `Microsandbox.all_sandbox_metrics`, and
+streaming `metrics_stream`/`log_stream`), logs, OCI image-cache management,
+named volumes (incl. host-side `Volume.fs`/`VolumeInfo#fs` read/write),
+snapshots (create/open/list/list_dir/reindex/verify/export/import +
+boot-from-snapshot), streaming image-pull progress
+(`Sandbox.create_with_progress` → `PullSession`), **rootfs patches**
+(`Microsandbox::Patch`), **network configuration** (presets, custom per-rule
+`Microsandbox::NetworkPolicy`/`Rule`/`Destination`, plus DNS, TLS interception,
+IPv4/IPv6 pools, `max_connections`, `trust_host_cas`), **secrets** (multi-host /
+wildcard allow-lists, injection toggles, per-secret + sandbox-level violation
+policy), **SSH** (`Sandbox#ssh` → `SshClient`/`SftpClient`/`SshServer`), and the
+**raw agent client** (`Microsandbox::AgentClient`). Create options span
+resources, `init`/`ephemeral`, disk-image `fstype`, network policy + config,
+`log_level`/`security`/`rlimits`/`pull_policy`/`secrets`/`patches`/`volumes`
+(bind/named/tmpfs/disk with mount policies) and more; `exec`/`shell` take
+per-call `rlimits`, and `create` accepts
 `registry_auth`/`registry_insecure`/`registry_ca_certs` for private and
-authenticated registries.
+authenticated registries, plus customizable provisioning via `Microsandbox.setup`.
+
+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: "…" }`).
 
 ## Contributing
 

data/ext/microsandbox/Cargo.toml

@@ -7,7 +7,7 @@ description = "Ruby SDK native extension for microsandbox — secure, fast micro
 # 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.5.8).
-version = "0.6.0"
+version = "0.7.0"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"

data/ext/microsandbox/src/agent.rs

@@ -40,7 +40,7 @@ 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) {
+        let bridge = match dur(timeout)? {
             Some(t) => block_on(AgentBridge::connect_sandbox_with_timeout(&name, t)),
             None => block_on(AgentBridge::connect_sandbox(&name)),
         }
@@ -50,7 +50,7 @@ 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) {
+        let bridge = match dur(timeout)? {
             Some(t) => block_on(AgentBridge::connect_path_with_timeout(&path, t)),
             None => block_on(AgentBridge::connect_path(&path)),
         }
@@ -125,12 +125,23 @@ impl AgentClient {
     }
 }
 
-/// Convert seconds into a `Duration`, treating a non-positive/absent value as
-/// "use the default handshake timeout".
-fn dur(timeout: Option<f64>) -> Option<Duration> {
+/// Convert an optional `timeout` (seconds) into an optional `Duration`,
+/// mirroring the Python SDK's `timeout_duration`:
+///   - absent (`nil`) → `None` → the core's default handshake timeout
+///   - `0` → an explicit zero deadline (fail fast), *not* "use the default"
+///   - negative or non-finite (NaN/Inf) → a caller error (rather than being
+///     silently swallowed into the default)
+///   - finite but out of `Duration` range (e.g. `Float::MAX`) → a caller error
+///     via `try_from_secs_f64`, rather than the panic `from_secs_f64` would raise
+fn dur(timeout: Option<f64>) -> Result<Option<Duration>, Error> {
     match timeout {
-        Some(t) if t.is_finite() && t > 0.0 => Some(Duration::from_secs_f64(t)),
-        _ => None,
+        None => Ok(None),
+        Some(t) if t.is_finite() && t >= 0.0 => Duration::try_from_secs_f64(t)
+            .map(Some)
+            .map_err(|e| error::base_error(format!("timeout {t} seconds is out of range: {e}"))),
+        Some(t) => Err(error::base_error(format!(
+            "timeout must be a non-negative, finite number of seconds (got {t})"
+        ))),
     }
 }
 

data/ext/microsandbox/src/conv.rs

@@ -5,7 +5,7 @@
 
 use std::collections::HashMap;
 
-use magnus::{value::ReprValue, Error, RArray, RHash, TryConvert, Value};
+use magnus::{value::ReprValue, Error, IntoValue, RArray, RHash, TryConvert, Value};
 
 /// Fetch a non-nil value for `key`, if present.
 fn get(hash: RHash, key: &str) -> Option<Value> {
@@ -90,3 +90,39 @@ pub fn opt_port_map(hash: RHash, key: &str) -> Result<Vec<(u16, u16)>, Error> {
         None => Ok(Vec::new()),
     }
 }
+
+/// Recursively convert a `serde_json::Value` into a Ruby value. Used for
+/// pass-through JSON whose shape is not fixed — e.g. an image config's OCI
+/// `labels` object, which the Ruby layer hands back verbatim (mirroring the
+/// Python SDK's `dict | None`).
+pub fn json_to_ruby(value: &serde_json::Value) -> Value {
+    let ruby = crate::runtime::ruby();
+    match value {
+        serde_json::Value::Null => ruby.qnil().as_value(),
+        serde_json::Value::Bool(b) => b.into_value_with(&ruby),
+        serde_json::Value::Number(n) => {
+            if let Some(i) = n.as_i64() {
+                i.into_value_with(&ruby)
+            } else if let Some(u) = n.as_u64() {
+                u.into_value_with(&ruby)
+            } else {
+                n.as_f64().unwrap_or(0.0).into_value_with(&ruby)
+            }
+        }
+        serde_json::Value::String(s) => s.as_str().into_value_with(&ruby),
+        serde_json::Value::Array(items) => {
+            let arr = ruby.ary_new();
+            for item in items {
+                let _ = arr.push(json_to_ruby(item));
+            }
+            arr.into_value_with(&ruby)
+        }
+        serde_json::Value::Object(map) => {
+            let hash = ruby.hash_new();
+            for (k, v) in map {
+                let _ = hash.aset(k.as_str(), json_to_ruby(v));
+            }
+            hash.into_value_with(&ruby)
+        }
+    }
+}

data/ext/microsandbox/src/fs_stream.rs

@@ -0,0 +1,92 @@
+//! Streaming guest-filesystem I/O: `Microsandbox::Native::FsReadStream` and
+//! `Microsandbox::Native::FsWriteSink`.
+//!
+//! Wraps the core `SandboxFs::read_stream`/`write_stream` handles so large files
+//! can be moved without buffering the whole thing in memory. The core
+//! `FsReadStream::recv` needs `&mut self` and `FsWriteSink::close` consumes
+//! `self`, so each is held behind a `tokio::Mutex` (the sink as an `Option`, so
+//! `close` can take it and be idempotent). Each call drives the future to
+//! completion with the GVL released; the Ruby layer wraps these as an
+//! `Enumerable` reader and a writer with a block form.
+
+use std::sync::Arc;
+
+use magnus::{method, prelude::*, Error, RModule, RString, Ruby};
+use microsandbox::sandbox::{FsReadStream, FsWriteSink};
+use tokio::sync::Mutex;
+
+use crate::error;
+use crate::runtime::{block_on, ruby};
+
+#[magnus::wrap(class = "Microsandbox::Native::FsReadStream", free_immediately, size)]
+pub struct FsReadStreamHandle {
+    inner: Arc<Mutex<FsReadStream>>,
+}
+
+impl FsReadStreamHandle {
+    pub fn new(stream: FsReadStream) -> Self {
+        Self {
+            inner: Arc::new(Mutex::new(stream)),
+        }
+    }
+
+    /// Next chunk of bytes (ASCII-8BIT), or nil at end of stream.
+    fn recv(&self) -> Result<Option<RString>, Error> {
+        let inner = Arc::clone(&self.inner);
+        match block_on(async move { inner.lock().await.recv().await }).map_err(error::to_ruby)? {
+            Some(bytes) => Ok(Some(ruby().str_from_slice(bytes.as_ref()))),
+            None => Ok(None),
+        }
+    }
+}
+
+#[magnus::wrap(class = "Microsandbox::Native::FsWriteSink", free_immediately, size)]
+pub struct FsWriteSinkHandle {
+    inner: Arc<Mutex<Option<FsWriteSink>>>,
+}
+
+impl FsWriteSinkHandle {
+    pub fn new(sink: FsWriteSink) -> Self {
+        Self {
+            inner: Arc::new(Mutex::new(Some(sink))),
+        }
+    }
+
+    /// Write a chunk of bytes. Errors if the sink is already closed.
+    fn write(&self, data: RString) -> Result<(), Error> {
+        // Copy out while the GVL is held (GC.compact could move the buffer).
+        let bytes = unsafe { data.as_slice() }.to_vec();
+        let inner = Arc::clone(&self.inner);
+        let result = block_on(async move {
+            let guard = inner.lock().await;
+            match guard.as_ref() {
+                Some(sink) => Some(sink.write(&bytes).await),
+                None => None,
+            }
+        });
+        match result {
+            Some(r) => r.map_err(error::to_ruby),
+            None => Err(error::base_error("write to a closed FsWriteSink")),
+        }
+    }
+
+    /// 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(()),
+        }
+    }
+}
+
+pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
+    let rs = native.define_class("FsReadStream", ruby.class_object())?;
+    rs.define_method("recv", method!(FsReadStreamHandle::recv, 0))?;
+
+    let ws = native.define_class("FsWriteSink", ruby.class_object())?;
+    ws.define_method("write", method!(FsWriteSinkHandle::write, 1))?;
+    ws.define_method("close", method!(FsWriteSinkHandle::close, 0))?;
+    Ok(())
+}

data/ext/microsandbox/src/image.rs

@@ -9,6 +9,7 @@ use magnus::{function, prelude::*, Error, RArray, RHash, RModule, Ruby};
 use microsandbox::image::{Image, ImageDetail, ImageHandle, ImagePruneReport};
 
 use crate::backend::with_local_backend;
+use crate::conv;
 use crate::runtime::ruby;
 
 fn handle_to_hash(h: &ImageHandle) -> RHash {
@@ -43,6 +44,11 @@ fn detail_to_hash(detail: ImageDetail) -> RHash {
         let _ = c.aset("entrypoint", config.entrypoint);
         let _ = c.aset("working_dir", config.working_dir);
         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.)
+        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);
     } else {

data/ext/microsandbox/src/lib.rs

@@ -13,6 +13,7 @@ mod backend;
 mod conv;
 mod error;
 mod exec;
+mod fs_stream;
 mod image;
 mod runtime;
 mod sandbox;
@@ -47,6 +48,43 @@ fn install() -> Result<(), Error> {
     runtime::block_on(microsandbox::setup::install()).map_err(error::to_ruby)
 }
 
+/// Customizable install via the core `Setup` builder. `opts`: base_dir (install
+/// root), version (pin the runtime version), force (re-download even if present
+/// — repairs a corrupt install), skip_verify. Mirrors the Node `Setup` builder.
+fn setup(opts: RHash) -> Result<(), Error> {
+    use microsandbox::setup::Setup;
+    let base_dir = conv::opt_string(opts, "base_dir")?;
+    let version = conv::opt_string(opts, "version")?;
+    let skip_verify = conv::opt_bool(opts, "skip_verify")?;
+    let force = conv::opt_bool(opts, "force")?;
+    // `Setup` uses a typed-builder whose `strip_option` setters change the type
+    // on each call, so optional fields can't be set conditionally on one binding
+    // — branch on presence instead (matching the Node binding).
+    let setup = match (base_dir, version) {
+        (Some(d), Some(v)) => Setup::builder()
+            .base_dir(d)
+            .version(v)
+            .skip_verify(skip_verify)
+            .force(force)
+            .build(),
+        (Some(d), None) => Setup::builder()
+            .base_dir(d)
+            .skip_verify(skip_verify)
+            .force(force)
+            .build(),
+        (None, Some(v)) => Setup::builder()
+            .version(v)
+            .skip_verify(skip_verify)
+            .force(force)
+            .build(),
+        (None, None) => Setup::builder()
+            .skip_verify(skip_verify)
+            .force(force)
+            .build(),
+    };
+    runtime::block_on(setup.install()).map_err(error::to_ruby)
+}
+
 /// Whether the `msb` runtime + `libkrunfw` are installed and resolvable.
 fn is_installed() -> bool {
     microsandbox::setup::is_installed()
@@ -88,6 +126,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
 
     native.define_singleton_method("version", function!(version, 0))?;
     native.define_singleton_method("install", function!(install, 0))?;
+    native.define_singleton_method("setup", function!(setup, 1))?;
     native.define_singleton_method("installed?", function!(is_installed, 0))?;
     native.define_singleton_method("set_runtime_msb_path", function!(set_runtime_msb_path, 1))?;
     native.define_singleton_method(
@@ -101,6 +140,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     sandbox::define(ruby, &native)?;
     exec::define(ruby, &native)?;
     stream::define(ruby, &native)?;
+    fs_stream::define(ruby, &native)?;
     snapshot::define(ruby, &native)?;
     image::define(ruby, &native)?;
     volume::define(ruby, &native)?;