microsandbox-rb 0.11.0 → 0.13.0

data/README.md

@@ -20,7 +20,13 @@ them. Our deepest thanks to the maintainers and community. 🙏
   [Rust](https://github.com/superradcompany/microsandbox/tree/main/sdk) ·
   [Python](https://github.com/superradcompany/microsandbox/tree/main/sdk/python) ·
   [TypeScript / Node](https://github.com/superradcompany/microsandbox/tree/main/sdk/node-ts) ·
-  [Go](https://github.com/superradcompany/microsandbox/tree/main/sdk/go)
+  [Go](https://github.com/superradcompany/microsandbox/tree/main/sdk/go) ·
+  [Ruby](https://github.com/superradcompany/microsandbox/tree/main/sdk/ruby)
+  (since upstream `v0.6.9` there is an **official** `microsandbox` gem — a
+  compact veneer over the same Rust SDK. This gem predates it and covers a
+  larger surface (snapshots, SSH, streaming, volumes fs, network policy DSL,
+  RBS types); both define the `Microsandbox` module, so use one or the other,
+  not both, in a single process.)
 - **Agents** — [Agent Skills](https://github.com/superradcompany/skills) · [MCP server](https://github.com/superradcompany/microsandbox-mcp)
 - **Community** — [Discord](https://discord.gg/T95Y3XnEAK)
 
@@ -126,10 +132,13 @@ ensure
   # sb.kill          # force (SIGKILL); sb.drain for a graceful drain
 end
 
-# Inspect / manage existing sandboxes. `get`/`list` return a controllable
+# Inspect / manage existing sandboxes. `get` returns a controllable
 # SandboxHandle (the live `stop`/`kill`/`drain`/`wait` live on the object from
-# `create`/`start`; fine-grained control lives on the handle).
-Microsandbox::Sandbox.list            # => [Microsandbox::SandboxHandle, ...]
+# `create`/`start`; fine-grained control lives on the handle). `list` returns a
+# cursor-paginated, Enumerable SandboxPage of handles (runtime v0.6.8).
+Microsandbox::Sandbox.list            # => Microsandbox::SandboxPage (first page)
+Microsandbox::Sandbox.list.map(&:name)  # enumerate the page's handles
+# next page: Sandbox.list_with(cursor: page.next_cursor, limit: 50)
 h = Microsandbox::Sandbox.get("box")  # => Microsandbox::SandboxHandle
 h.status                              # :running, :stopped, :created, ...
 h.stop_with_timeout(5)                # custom escalation timeout
@@ -190,6 +199,22 @@ end
 A non-zero exit is **not** an error — inspect `exit_code`/`success?`. Spawn-time
 failures (e.g. command not found) and timeouts raise typed errors (see below).
 
+**Default workload** (runtime `v0.6.9`): `create` is strictly boot-only — it
+never runs the image's `ENTRYPOINT`/`CMD`. Execute the image's own command
+explicitly:
+
+```ruby
+Microsandbox::Sandbox.create("worker", image: "example/worker:latest",
+  cmd: ["worker.py", "--once"]) do |sb|   # cmd: overrides the durable image CMD
+  out = sb.exec_default(timeout: 300)     # buffered; exec-style options
+  handle = sb.exec_default_stream         # or streaming (returns an ExecHandle)
+  sb.attach_default                       # or interactive (host TTY)
+end
+```
+
+An image whose entrypoint and CMD resolve to no executable command raises
+`Microsandbox::NoDefaultCommandError`.
+
 ### Guest filesystem
 
 ```ruby
@@ -253,6 +278,10 @@ Microsandbox::Sandbox.create("live", image: "public.ecr.aws/docker/library/alpin
   # 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 —
@@ -427,9 +456,15 @@ Microsandbox.with_backend(:local) { Microsandbox::Sandbox.create("box", image: "
 ```
 
 Resolution order when no backend is set programmatically: `MSB_BACKEND`
-(`local`/`cloud`) → `MSB_API_URL` + `MSB_API_KEY` → `MSB_PROFILE` → the
-`active_profile` in `~/.microsandbox/config.json` (path overridable via
-`MSB_CONFIG_PATH`) → local. The cloud backend currently supports a subset of
+(`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`.
 
@@ -442,8 +477,8 @@ 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.11.0"  (the gem's own version)
-Microsandbox.runtime_version   # => "v0.6.7"  (the embedded upstream runtime tag)
+Microsandbox::VERSION          # => "0.13.0"  (the gem's own version)
+Microsandbox.runtime_version   # => "v0.6.9"  (the embedded upstream runtime tag)
 ```
 
 | Gem version | Upstream runtime | Notes |
@@ -465,6 +500,8 @@ Microsandbox.runtime_version   # => "v0.6.7"  (the embedded upstream runtime tag
 | `0.9.3`  | `v0.6.6` | adopts upstream `v0.6.4`+`v0.6.6` (`v0.6.5` was yanked upstream): snapshot restore by pinned digest — fixes fatal restore-after-tag-republish bug, fragmented-UDP/PMTU relay fixes, exec kills the whole process group, ephemeral stop-wait tolerance, readdir RSS-leak fix; upstream API growth is additive-only — no Ruby surface change |
 | `0.10.0` | `v0.6.6` | `v0.6.6` API parity: live `modify`/resize, `ping`/`touch`, create `max_cpus`/`max_memory` |
 | `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` |
 
 **Going forward** — the gem version moves on its own semver track and no longer
 mirrors the upstream tag:
@@ -544,7 +581,8 @@ 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`/`config`/`config_json`/`snapshot` from
-`Sandbox.get`, and label-filtered `list_with`),
+`Sandbox.get`, and the cursor-paginated `list`/`list_with` with label
+filters),
 backend routing (`set_default_backend`/`with_backend`/`default_backend_kind`),
 `exec`/`shell` (collected and streaming), interactive `attach`/
 `attach_shell`, the full guest filesystem (incl. streaming `read_stream`/

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.7).
-version = "0.11.0"
+# The core-crate dependency below stays pinned at its own tag (v0.6.9).
+version = "0.13.0"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"
@@ -35,8 +35,8 @@ rb-sys = "0.9"
 # `.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.7", default-features = true, features = ["ssh"] }
-microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.7" }
+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" }
 
 # 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/backend.rs

@@ -20,7 +20,7 @@ use std::sync::atomic::{AtomicU32, Ordering};
 use std::sync::{Arc, Mutex, OnceLock};
 
 use magnus::{function, prelude::*, Error, RModule, Ruby};
-use microsandbox::{Backend, MicrosandboxError};
+use microsandbox::{Backend, MicrosandboxError, Operation};
 
 use crate::error;
 use crate::runtime::block_on;
@@ -31,17 +31,14 @@ use crate::runtime::block_on;
 /// borrowing `&LocalBackend` from it (`as_local()` borrows the `Arc`). Pure
 /// Rust — safe to call inside `block_on` (no Ruby C API), and it returns a raw
 /// `MicrosandboxError` so the Ruby-exception mapping happens *after* `block_on`
-/// re-acquires the GVL. Cloud backends yield `Unsupported`, mirroring pyo3's
-/// `resolve_local`.
-pub fn local_backend() -> Result<Arc<dyn Backend>, MicrosandboxError> {
+/// re-acquires the GVL. Cloud backends yield `Unsupported` for the given
+/// operation (v0.6.8 `Operation`-keyed shape), mirroring pyo3's `resolve_local`.
+pub fn local_backend(op: Operation) -> Result<Arc<dyn Backend>, MicrosandboxError> {
     let backend = microsandbox::default_backend();
     if backend.as_local().is_some() {
         Ok(backend)
     } else {
-        Err(MicrosandboxError::Unsupported {
-            feature: "this operation requires a local backend".into(),
-            available_when: "with the local backend (the default)".into(),
-        })
+        Err(MicrosandboxError::local_only(op))
     }
 }
 
@@ -53,10 +50,11 @@ pub fn local_backend() -> Result<Arc<dyn Backend>, MicrosandboxError> {
 /// it and returns the same `Arc` kept alive for the borrow — so it lives here
 /// once rather than at every call site.
 pub fn with_local_backend<T>(
+    operation: Operation,
     op: impl AsyncFnOnce(&microsandbox::LocalBackend) -> Result<T, MicrosandboxError>,
 ) -> Result<T, Error> {
     block_on(async move {
-        let backend = local_backend()?;
+        let backend = local_backend(operation)?;
         let local = backend
             .as_local()
             .expect("local_backend() guarantees a local backend");
@@ -161,10 +159,32 @@ fn default_backend_kind() -> String {
     .to_string()
 }
 
+/// Secret-safe description of the active default backend (v0.6.9):
+/// {kind, api_url, source, profile}. `source` names what selected the backend
+/// (e.g. "MSB_BACKEND", "programmatic", "default"); the API key is never
+/// included. Like `default_backend_kind`, the first call freezes ambient
+/// env/profile resolution for the process.
+fn default_backend_info() -> magnus::RHash {
+    let info = microsandbox::default_backend_info();
+    let hash = crate::runtime::ruby().hash_new();
+    let _ = hash.aset(
+        "kind",
+        match info.kind {
+            microsandbox::BackendKind::Local => "local",
+            microsandbox::BackendKind::Cloud => "cloud",
+        },
+    );
+    let _ = hash.aset("api_url", info.api_url);
+    let _ = hash.aset("source", info.source.as_str());
+    let _ = hash.aset("profile", info.profile);
+    hash
+}
+
 pub fn define(_ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     native.define_singleton_method("set_default_backend", function!(set_default_backend, 4))?;
     native.define_singleton_method("push_default_backend", function!(push_default_backend, 4))?;
     native.define_singleton_method("pop_default_backend", function!(pop_default_backend, 1))?;
     native.define_singleton_method("default_backend_kind", function!(default_backend_kind, 0))?;
+    native.define_singleton_method("default_backend_info", function!(default_backend_info, 0))?;
     Ok(())
 }

data/ext/microsandbox/src/error.rs

@@ -6,7 +6,7 @@
 //! is always the core error's `to_string()`.
 
 use magnus::{value::ReprValue, Error, ExceptionClass, Module, RClass, RModule, Ruby};
-use microsandbox::{AgentClientError, MicrosandboxError};
+use microsandbox::{AgentClientError, MicrosandboxError, Operation, UnsupportedReason};
 
 /// The Ruby class (relative to the `Microsandbox` module) for a core error.
 /// `"Error"` is the base class; anything else is a named subclass.
@@ -60,6 +60,10 @@ fn class_name(err: &MicrosandboxError) -> &'static str {
         // unconditionally enables the core's `net` feature (default-features),
         // so this variant is always present.
         NetworkBuilder(_) => "NetworkPolicyError",
+        // v0.6.9: `exec_default`/`attach_default` on an image whose resolved
+        // ENTRYPOINT+CMD provide no executable command. Mirrors the Python
+        // SDK's `NoDefaultCommandError`.
+        NoDefaultCommand => "NoDefaultCommandError",
         _ => "Error",
     }
 }
@@ -83,12 +87,96 @@ pub fn to_ruby(err: MicrosandboxError) -> Error {
         Err(_) => return Error::new(magnus::exception::runtime_error(), message),
     };
 
+    // `Unsupported` gets a Ruby-idiom message (`sandbox.kill` instead of
+    // `Sandbox::kill`) plus structured `operation` / `hint` attributes on the
+    // exception instance, mirroring the Python SDK's enrichment (v0.6.8).
+    if let MicrosandboxError::Unsupported { op, reason } = &err {
+        return unsupported_error(&ruby, &ruby_api_name(*op), &ruby_hint(reason));
+    }
+
     match exception_class(&ruby, class_name(&err)) {
         Some(class) => Error::new(class, message),
         None => Error::new(ruby.exception_runtime_error(), message),
     }
 }
 
+/// `UnsupportedError` for shim-only entry points that require the local
+/// backend but have no SDK [`Operation`] (Ruby-only diagnostic hooks such as
+/// `Microsandbox.runtime_path`). `name` is the Ruby-facing API name. Mirrors
+/// the Python SDK's name-based `local_only` helper.
+#[allow(deprecated)]
+pub fn local_only(name: &str) -> Error {
+    match Ruby::get() {
+        Ok(ruby) => unsupported_error(&ruby, name, "use a local backend"),
+        Err(_) => Error::new(
+            magnus::exception::runtime_error(),
+            format!("{name} is not supported by this backend: use a local backend"),
+        ),
+    }
+}
+
+/// Build a `Microsandbox::UnsupportedError` carrying the rendered message and
+/// the structured `@operation` / `@hint` attributes.
+fn unsupported_error(ruby: &Ruby, operation: &str, hint: &str) -> Error {
+    let message = format!("{operation} is not supported by this backend: {hint}");
+    let Some(class) = exception_class(ruby, "UnsupportedError") else {
+        return Error::new(ruby.exception_runtime_error(), message);
+    };
+    match class
+        .as_value()
+        .funcall::<_, _, magnus::Exception>("new", (message.as_str(),))
+    {
+        Ok(exc) => {
+            // Best-effort extras; the message already carries both.
+            let _ = exc
+                .funcall::<_, _, magnus::Value>("instance_variable_set", ("@operation", operation));
+            let _ = exc.funcall::<_, _, magnus::Value>("instance_variable_set", ("@hint", hint));
+            exc.into()
+        }
+        Err(_) => Error::new(class, message),
+    }
+}
+
+/// Render an [`Operation`] as the Ruby API it corresponds to: `Sandbox::kill`
+/// becomes `sandbox.kill` and `SandboxFsOps::stat_handle` becomes
+/// `sandbox_fs_ops.stat_handle`; a parenthetical keeps its Ruby keyword shape
+/// (`log_stream(follow=false)` becomes `log_stream(follow: false)`). Plain
+/// phrases without a `Type::method` shape (`config`, `snapshot operations`)
+/// pass through as-is. Mirrors the Python SDK's `py_api_name`.
+fn ruby_api_name(op: Operation) -> String {
+    let path = op.api_path();
+    let Some((ty, method)) = path.split_once("::") else {
+        return path.to_string();
+    };
+    format!("{}.{}", camel_to_snake(ty), method.replace('=', ": "))
+}
+
+/// Render an [`UnsupportedReason`] with `use instead` targets pointing at the
+/// Ruby API name rather than the Rust path.
+fn ruby_hint(reason: &UnsupportedReason) -> String {
+    match reason {
+        UnsupportedReason::UseInstead(op) => format!("use {}", ruby_api_name(*op)),
+        other => other.hint(),
+    }
+}
+
+/// Lower a `CamelCase` type name to `snake_case` (`SandboxFsOps` becomes
+/// `sandbox_fs_ops`).
+fn camel_to_snake(name: &str) -> String {
+    let mut out = String::with_capacity(name.len() + 4);
+    for (i, ch) in name.char_indices() {
+        if ch.is_ascii_uppercase() {
+            if i > 0 {
+                out.push('_');
+            }
+            out.push(ch.to_ascii_lowercase());
+        } else {
+            out.push(ch);
+        }
+    }
+    out
+}
+
 /// A plain `Microsandbox::Error` (base) with a custom message — used for
 /// binding-level validation errors that have no core counterpart.
 #[allow(deprecated)]

data/ext/microsandbox/src/image.rs

@@ -7,7 +7,7 @@
 
 use magnus::{function, prelude::*, Error, RArray, RHash, RModule, Ruby};
 use microsandbox::image::{Image, ImageDetail, ImageHandle, ImagePruneReport};
-use microsandbox::ImageArchiveFormat;
+use microsandbox::{ImageArchiveFormat, Operation};
 
 use crate::backend::with_local_backend;
 use crate::conv;
@@ -84,12 +84,16 @@ fn report_to_hash(report: ImagePruneReport) -> RHash {
 }
 
 fn get(reference: String) -> Result<RHash, Error> {
-    let handle = with_local_backend(async |local| Image::get_local(local, &reference).await)?;
+    let handle = with_local_backend(Operation::ImageGet, async |local| {
+        Image::get_local(local, &reference).await
+    })?;
     Ok(handle_to_hash(&handle))
 }
 
 fn list() -> Result<RArray, Error> {
-    let handles = with_local_backend(async |local| Image::list_local(local).await)?;
+    let handles = with_local_backend(Operation::ImageList, async |local| {
+        Image::list_local(local).await
+    })?;
     let arr = ruby().ary_new();
     for h in handles.iter() {
         arr.push(handle_to_hash(h))?;
@@ -98,16 +102,22 @@ fn list() -> Result<RArray, Error> {
 }
 
 fn inspect(reference: String) -> Result<RHash, Error> {
-    let detail = with_local_backend(async |local| Image::inspect_local(local, &reference).await)?;
+    let detail = with_local_backend(Operation::ImageInspect, async |local| {
+        Image::inspect_local(local, &reference).await
+    })?;
     Ok(detail_to_hash(detail))
 }
 
 fn remove(reference: String, force: bool) -> Result<(), Error> {
-    with_local_backend(async |local| Image::remove_local(local, &reference, force).await)
+    with_local_backend(Operation::ImageRemove, async |local| {
+        Image::remove_local(local, &reference, force).await
+    })
 }
 
 fn prune() -> Result<RHash, Error> {
-    let report = with_local_backend(async |local| Image::prune_local(local).await)?;
+    let report = with_local_backend(Operation::ImagePrune, async |local| {
+        Image::prune_local(local).await
+    })?;
     Ok(report_to_hash(report))
 }
 
@@ -117,7 +127,7 @@ fn prune() -> Result<RHash, Error> {
 /// `imageLoad` added in v0.6.7. (The `"-"` stdin form is spooled to a temp
 /// file by the Ruby layer — the core reads seekable files only.)
 fn load(input_path: String, tags: Vec<String>) -> Result<RArray, Error> {
-    let handles = with_local_backend(async |local| {
+    let handles = with_local_backend(Operation::ImageLoad, async |local| {
         Image::load_local(local, std::path::Path::new(&input_path), tags).await
     })?;
     let arr = ruby().ary_new();
@@ -140,7 +150,7 @@ fn save(references: Vec<String>, output_path: String, format: String) -> Result<
             )))
         }
     };
-    with_local_backend(async |local| {
+    with_local_backend(Operation::ImageSave, async |local| {
         Image::save_local(local, &references, std::path::Path::new(&output_path), fmt).await
     })
 }

data/ext/microsandbox/src/lib.rs

@@ -33,9 +33,10 @@ fn version() -> String {
 /// Ruby Hash. Mirrors the official `all_sandbox_metrics` / `allSandboxMetrics`
 /// helpers (Python/Node/Go).
 fn all_sandbox_metrics() -> Result<RHash, Error> {
-    let map = backend::with_local_backend(async |local| {
-        microsandbox::sandbox::all_sandbox_metrics_local(local).await
-    })?;
+    let map =
+        backend::with_local_backend(microsandbox::Operation::AllSandboxMetrics, async |local| {
+            microsandbox::sandbox::all_sandbox_metrics_local(local).await
+        })?;
     let hash = runtime::ruby().hash_new();
     for (name, metrics) in &map {
         hash.aset(name.as_str(), sandbox::metrics_to_hash(metrics))?;
@@ -107,12 +108,11 @@ fn set_runtime_libkrunfw_path(path: String) {
 /// backend's config.
 fn resolved_msb_path() -> Result<String, Error> {
     let backend = microsandbox::default_backend();
-    let local = backend.as_local().ok_or_else(|| {
-        error::to_ruby(microsandbox::MicrosandboxError::Unsupported {
-            feature: "resolved_msb_path requires a local backend".into(),
-            available_when: "with the local backend".into(),
-        })
-    })?;
+    // Shim-only entry point with no SDK `Operation` — report the Ruby-facing
+    // name (`Microsandbox.runtime_path`), like Python's name-based local_only.
+    let local = backend
+        .as_local()
+        .ok_or_else(|| error::local_only("runtime_path"))?;
     let path = local.config().resolve_msb_path().map_err(error::to_ruby)?;
     Ok(path.to_string_lossy().into_owned())
 }