microsandbox-rb 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05d5b2e1200b6aff7dc7801259558a202064a01cac529ea55f2390790b7f84bb
-  data.tar.gz: d4d357393a51e2b642dd9d6fc6e899a6a92a3895bf98495a01714fbdbb76c0ed
+  metadata.gz: 72468dc2fa865510c82ecc783988925460acbd7f7d92025f367964277b98e756
+  data.tar.gz: f4bca46d64a694a76a59b712b8d827e6ddff12ba4cb9708a33951f4969c8fce2
 SHA512:
-  metadata.gz: 994d487f8a606de2664566519ba28964fcc1053e9277b768945472dfac105d34a48479b1677d8598fde596b4d5c9f37a31970d2cf3e3a2065f98a12fdfe85322
-  data.tar.gz: c0d57191ef9fc97845c773216dd19194dbad4dd0c58f3525989d16df0c37088749fe880ccd89b53d71f9f9454c149429886de208b36cda2de4210f23b4bc05f8
+  metadata.gz: 31cace38acfb4b535aaeb5f9026acb4c63d5f1376637628c2947e1d5ff9c1492d388cde85f3ba38bd8d462bb0598d12f046467331a6507d6af2cd2720bb57137
+  data.tar.gz: 97e665bd96d8d7ae0719c34d5a7d7f7823966a70f793d251d034a519ad04da70a8925c0e17c01c854ab074de904aa9a1baa88b148f099afba33c751836f97a60

data/CHANGELOG.md

@@ -6,6 +6,50 @@ All notable changes to this gem are documented here. The format is based on
 microsandbox runtime it embeds; each release notes the upstream runtime tag it
 wraps, and the README's Versioning section keeps the full gem→runtime map.
 
+## [0.12.0] - 2026-07-30
+
+Adopts upstream runtime **`v0.6.7` → `v0.6.8`** and mirrors its breaking SDK
+surface (upstream #1232 "unify cloud backend and paginated listings"), keeping
+parity with the Python/Node SDKs.
+
+### Breaking
+
+- **Sandbox listing is cursor-paginated** (upstream #1232). `Sandbox.list` and
+  `Sandbox.list_with` now return a {Microsandbox::SandboxPage} — an Enumerable
+  page of `SandboxHandle`s carrying `#next_cursor` — instead of a plain Array.
+  `Sandbox.list` fetches the first page (upstream default size 20);
+  `Sandbox.list_with` gains `limit:` (1..100) and `cursor:` keywords alongside
+  the existing `labels:` filter. Code that only enumerates
+  (`list.each`/`map`/`to_a`) keeps working; code relying on the return value
+  *being* an Array (e.g. `list + other`, `Array ===`) must adapt, and listings
+  of more than one page must follow `page.next_cursor` via
+  `list_with(cursor:)`.
+- **`UnsupportedError` messages are re-keyed by structured operations**
+  (upstream #1232): the core now reports the rejected API and a remedial hint
+  (e.g. `image.list is not supported by this backend: use a local backend`)
+  instead of the old free-text `feature`/`available_when` pair. The exception
+  additionally exposes the new structured attributes below.
+
+### Added
+
+- {Microsandbox::SandboxPage} — Enumerable over its `#sandboxes`, plus
+  `#next_cursor`, `#size`/`#length`, `#empty?` and `#last_page?`.
+- `Sandbox.list_with(labels:, limit:, cursor:)` pagination keywords.
+- `UnsupportedError#operation` / `#hint` — the rejected API in Ruby rendering
+  (`"sandbox.kill"`) and the remedial hint (`"use a local backend"`),
+  mirroring the Python SDK's enriched `UnsupportedError`.
+
+### Changed
+
+- Direct `VolumeFs` operations now route through the backend's volume trait
+  (upstream #1232) instead of a construction-time local-backend guard, so an
+  unsupported backend rejects each operation with a precise per-operation
+  error.
+- The embedded runtime is `v0.6.8`; see the upstream release notes for
+  runtime-side changes (shared log registry for followed streams, cloud
+  sandbox reconnect fixes for `exec`/`ssh`, kernel sourced from
+  cdn.kernel.org).
+
 ## [0.11.0] - 2026-07-27
 
 Adopts upstream runtime **`v0.6.6` → `v0.6.7`** and mirrors its breaking SDK

data/Cargo.lock

@@ -2954,8 +2954,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox"
-version = "0.6.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.7#0c54fd12acf7740f68d5bcd38e58a9fe82d51a45"
+version = "0.6.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.8#7958cddeff2fce10dbcfd0c0d6a32dec93a9d5ea"
 dependencies = [
  "anyhow",
  "astral-tokio-tar",
@@ -2990,6 +2990,7 @@ dependencies = [
  "reqwest",
  "russh",
  "russh-sftp",
+ "rustls",
  "scopeguard",
  "sea-orm",
  "serde",
@@ -3003,6 +3004,7 @@ dependencies = [
  "tracing",
  "typed-builder",
  "typed-path",
+ "webpki-roots 1.0.7",
  "which",
  "windows-sys 0.61.2",
  "zeroize",
@@ -3010,8 +3012,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-agent-client"
-version = "0.6.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.7#0c54fd12acf7740f68d5bcd38e58a9fe82d51a45"
+version = "0.6.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.8#7958cddeff2fce10dbcfd0c0d6a32dec93a9d5ea"
 dependencies = [
  "ciborium",
  "microsandbox-protocol",
@@ -3023,8 +3025,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-db"
-version = "0.6.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.7#0c54fd12acf7740f68d5bcd38e58a9fe82d51a45"
+version = "0.6.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.8#7958cddeff2fce10dbcfd0c0d6a32dec93a9d5ea"
 dependencies = [
  "async-trait",
  "sea-orm",
@@ -3035,8 +3037,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-filesystem"
-version = "0.6.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.7#0c54fd12acf7740f68d5bcd38e58a9fe82d51a45"
+version = "0.6.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.8#7958cddeff2fce10dbcfd0c0d6a32dec93a9d5ea"
 dependencies = [
  "libc",
  "microsandbox-utils",
@@ -3048,8 +3050,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-image"
-version = "0.6.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.7#0c54fd12acf7740f68d5bcd38e58a9fe82d51a45"
+version = "0.6.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.8#7958cddeff2fce10dbcfd0c0d6a32dec93a9d5ea"
 dependencies = [
  "astral-tokio-tar",
  "async-compression",
@@ -3075,8 +3077,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-metrics"
-version = "0.6.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.7#0c54fd12acf7740f68d5bcd38e58a9fe82d51a45"
+version = "0.6.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.8#7958cddeff2fce10dbcfd0c0d6a32dec93a9d5ea"
 dependencies = [
  "chrono",
  "libc",
@@ -3087,8 +3089,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-migration"
-version = "0.6.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.7#0c54fd12acf7740f68d5bcd38e58a9fe82d51a45"
+version = "0.6.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.8#7958cddeff2fce10dbcfd0c0d6a32dec93a9d5ea"
 dependencies = [
  "sea-orm-migration",
  "serde_json",
@@ -3096,8 +3098,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-network"
-version = "0.6.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.7#0c54fd12acf7740f68d5bcd38e58a9fe82d51a45"
+version = "0.6.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.8#7958cddeff2fce10dbcfd0c0d6a32dec93a9d5ea"
 dependencies = [
  "base64",
  "bytes",
@@ -3140,8 +3142,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-protocol"
-version = "0.6.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.7#0c54fd12acf7740f68d5bcd38e58a9fe82d51a45"
+version = "0.6.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.8#7958cddeff2fce10dbcfd0c0d6a32dec93a9d5ea"
 dependencies = [
  "chrono",
  "ciborium",
@@ -3155,8 +3157,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-runtime"
-version = "0.6.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.7#0c54fd12acf7740f68d5bcd38e58a9fe82d51a45"
+version = "0.6.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.8#7958cddeff2fce10dbcfd0c0d6a32dec93a9d5ea"
 dependencies = [
  "bytes",
  "chrono",
@@ -3187,8 +3189,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-types"
-version = "0.6.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.7#0c54fd12acf7740f68d5bcd38e58a9fe82d51a45"
+version = "0.6.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.8#7958cddeff2fce10dbcfd0c0d6a32dec93a9d5ea"
 dependencies = [
  "chrono",
  "ipnetwork",
@@ -3201,8 +3203,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-utils"
-version = "0.6.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.7#0c54fd12acf7740f68d5bcd38e58a9fe82d51a45"
+version = "0.6.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.6.8#7958cddeff2fce10dbcfd0c0d6a32dec93a9d5ea"
 dependencies = [
  "dirs",
  "libc",
@@ -3214,7 +3216,7 @@ dependencies = [
 
 [[package]]
 name = "microsandbox_rb"
-version = "0.11.0"
+version = "0.12.0"
 dependencies = [
  "chrono",
  "futures",
@@ -6012,8 +6014,12 @@ checksum = "8f72a05e828585856dacd553fba484c242c46e391fb0e58917c942ee9202915c"
 dependencies = [
  "futures-util",
  "log",
+ "rustls",
+ "rustls-pki-types",
  "tokio",
+ "tokio-rustls",
  "tungstenite",
+ "webpki-roots 0.26.11",
 ]
 
 [[package]]
@@ -6170,6 +6176,8 @@ dependencies = [
  "httparse",
  "log",
  "rand 0.9.4",
+ "rustls",
+ "rustls-pki-types",
  "sha1 0.10.6",
  "thiserror 2.0.18",
 ]

data/README.md

@@ -126,10 +126,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
@@ -442,8 +445,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.12.0"  (the gem's own version)
+Microsandbox.runtime_version   # => "v0.6.8"  (the embedded upstream runtime tag)
 ```
 
 | Gem version | Upstream runtime | Notes |
@@ -465,6 +468,7 @@ 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 |
 
 **Going forward** — the gem version moves on its own semver track and no longer
 mirrors the upstream tag:
@@ -544,7 +548,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

@@ -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.6.7).
-version = "0.11.0"
+version = "0.12.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.8", default-features = true, features = ["ssh"] }
+microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.8" }
 
 # 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");

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.
@@ -83,12 +83,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())
 }

data/ext/microsandbox/src/sandbox.rs

@@ -20,9 +20,9 @@ use microsandbox::logs::{
 use microsandbox::sandbox::{
     AttachOptionsBuilder, DiskImageFormat, EnvVar, FsEntry, FsEntryKind, FsMetadata,
     HostPermissions, Patch, PullPolicy, PullProgress, PullProgressHandle, RlimitResource,
-    RootDiskBuilder, SandboxBuilder, SandboxFilter, SandboxHandle, SandboxMetrics,
-    SandboxModificationBuilder, SandboxModificationPatch, SandboxStatus, SandboxStopResult,
-    SecretBuilder, SecretModificationPatch, SecretSource, SecurityProfile, StatVirtualization,
+    RootDiskBuilder, SandboxBuilder, SandboxHandle, SandboxMetrics, SandboxModificationBuilder,
+    SandboxModificationPatch, SandboxStatus, SandboxStopResult, SecretBuilder,
+    SecretModificationPatch, SecretSource, SecurityProfile, StatVirtualization,
 };
 use microsandbox::LogLevel;
 use microsandbox::MicrosandboxResult;
@@ -477,29 +477,44 @@ impl Sandbox {
         Ok(SbHandle::from_inner(handle))
     }
 
-    /// All sandboxes as controllable handles.
-    fn list() -> Result<RArray, Error> {
-        let handles = block_on(microsandbox::Sandbox::list()).map_err(error::to_ruby)?;
+    /// Convert one `SandboxPage` into a `{ "sandboxes" => [SbHandle], "next_cursor" => String|nil }`
+    /// Ruby Hash (v0.6.8 paginated listing contract).
+    fn page_to_hash(page: microsandbox::sandbox::SandboxPage) -> Result<RHash, Error> {
         let arr = ruby().ary_new();
-        for h in handles {
+        for h in page.sandboxes {
             arr.push(SbHandle::from_inner(h))?;
         }
-        Ok(arr)
-    }
-
-    /// Sandboxes filtered by required `key=value` labels (AND-matched), as
-    /// controllable handles. `opts` carries a string→string `labels` map.
-    fn list_with(opts: RHash) -> Result<RArray, Error> {
-        let mut filter = SandboxFilter::new();
-        for (k, v) in conv::opt_string_map(opts, "labels")? {
-            filter = filter.label(k, v);
-        }
-        let handles = block_on(microsandbox::Sandbox::list_with(filter)).map_err(error::to_ruby)?;
-        let arr = ruby().ary_new();
-        for h in handles {
-            arr.push(SbHandle::from_inner(h))?;
-        }
-        Ok(arr)
+        let hash = ruby().hash_new();
+        hash.aset("sandboxes", arr)?;
+        hash.aset("next_cursor", page.next_cursor)?;
+        Ok(hash)
+    }
+
+    /// First page of sandboxes (default page size), as a page Hash of
+    /// controllable handles.
+    fn list() -> Result<RHash, Error> {
+        let page = block_on(microsandbox::Sandbox::list()).map_err(error::to_ruby)?;
+        Self::page_to_hash(page)
+    }
+
+    /// One configured page of sandboxes as a page Hash. `opts` carries an
+    /// optional string→string `labels` map (AND-matched), an optional `limit`
+    /// (1..=100) and an optional opaque `cursor` from a previous page.
+    fn list_with(opts: RHash) -> Result<RHash, Error> {
+        let labels = conv::opt_string_map(opts, "labels")?;
+        let limit = conv::opt_u32(opts, "limit")?;
+        let cursor = conv::opt_string(opts, "cursor")?;
+        let page = block_on(microsandbox::Sandbox::list_with(move |mut b| {
+            if let Some(limit) = limit {
+                b = b.limit(limit);
+            }
+            if let Some(cursor) = cursor {
+                b = b.cursor(cursor);
+            }
+            b.labels(labels)
+        }))
+        .map_err(error::to_ruby)?;
+        Self::page_to_hash(page)
     }
 
     /// Remove a (stopped) sandbox by name.

data/ext/microsandbox/src/volume.rs

@@ -9,7 +9,6 @@ use magnus::{function, method, prelude::*, Error, RArray, RHash, RModule, RStrin
 use microsandbox::volume::VolumeHandle;
 use microsandbox::Backend;
 
-use crate::backend::local_backend;
 use crate::conv;
 use crate::error;
 use crate::runtime::{block_on, ruby};
@@ -108,10 +107,13 @@ pub struct VolumeFs {
 }
 
 impl VolumeFs {
-    /// Resolve the (local) backend once and bind it to `name`.
+    /// Resolve the ambient backend once and bind it to `name`. As of v0.6.8
+    /// every `VolumeFs` op dispatches through the backend's `VolumeBackend`
+    /// trait, which yields precise per-operation `Unsupported` errors on
+    /// backends that can't serve it — no local-only downcast needed here.
     fn for_volume(name: String) -> Result<VolumeFs, Error> {
         Ok(VolumeFs {
-            backend: local_backend().map_err(error::to_ruby)?,
+            backend: microsandbox::default_backend(),
             name,
         })
     }

data/lib/microsandbox/errors.rb

@@ -90,4 +90,16 @@ module Microsandbox
   # cloud backend) is distinct from `UnsupportedOperationError` above.
   define_error(:CloudHttpError, "cloud-http")
   define_error(:UnsupportedError, "unsupported")
+
+  # As of runtime v0.6.8 the core keys Unsupported errors by a structured
+  # (operation, reason) pair. The native layer renders both into the message
+  # ("sandbox.kill is not supported by this backend: ...") and also attaches
+  # them here as structured attributes, mirroring the Python SDK's
+  # `UnsupportedError.operation` / `.hint`.
+  class UnsupportedError
+    # @return [String, nil] the rejected API in Ruby rendering, e.g. "sandbox.kill"
+    attr_reader :operation
+    # @return [String, nil] why it was rejected / what to use instead
+    attr_reader :hint
+  end
 end

data/lib/microsandbox/sandbox.rb

@@ -202,6 +202,48 @@ module Microsandbox
     end
   end
 
+  # One page of sandbox handles, returned by {Sandbox.list} and
+  # {Sandbox.list_with} — sandbox listing is cursor-paginated as of runtime
+  # v0.6.8. Enumerable over its {SandboxHandle}s; fetch the following page by
+  # passing {#next_cursor} to {Sandbox.list_with}.
+  #
+  # @example Walk every page
+  #   page = Microsandbox::Sandbox.list
+  #   loop do
+  #     page.each { |h| puts h.name }
+  #     break if page.last_page?
+  #     page = Microsandbox::Sandbox.list_with(cursor: page.next_cursor)
+  #   end
+  class SandboxPage
+    include Enumerable
+
+    # @return [Array<SandboxHandle>] the sandboxes in this page
+    attr_reader :sandboxes
+    # @return [String, nil] opaque cursor for the next page; nil on the final page
+    attr_reader :next_cursor
+
+    # @api private — construct via {Sandbox.list}/{Sandbox.list_with}.
+    def initialize(sandboxes, next_cursor)
+      @sandboxes = sandboxes
+      @next_cursor = next_cursor
+    end
+
+    def each(&) = @sandboxes.each(&)
+
+    # @return [Integer]
+    def size = @sandboxes.size
+    alias_method :length, :size
+
+    def empty? = @sandboxes.empty?
+
+    # Whether this is the final page (no cursor to continue from).
+    def last_page? = @next_cursor.nil?
+
+    def inspect
+      "#<Microsandbox::SandboxPage size=#{size} next_cursor=#{@next_cursor.inspect}>"
+    end
+  end
+
   # A running sandbox (microVM) — the primary entry point of the SDK.
   #
   # @example Block form (auto-stops on exit)
@@ -478,18 +520,25 @@ module Microsandbox
         SandboxHandle.new(Native::Sandbox.get(name.to_s))
       end
 
-      # List all sandboxes as controllable handles.
-      # @return [Array<SandboxHandle>]
+      # List the first page of sandboxes (default page size 20) as controllable
+      # handles. Cursor-paginated as of runtime v0.6.8 — follow
+      # {SandboxPage#next_cursor} via {.list_with} for subsequent pages.
+      # @return [SandboxPage]
       def list
-        Native::Sandbox.list.map { |h| SandboxHandle.new(h) }
+        build_page(Native::Sandbox.list)
       end
 
-      # List sandboxes carrying all of the given labels (AND-matched).
-      # @param labels [Hash] required key => value labels
-      # @return [Array<SandboxHandle>]
-      def list_with(labels: {})
+      # List one configured page of sandboxes.
+      # @param labels [Hash] required key => value labels (AND-matched)
+      # @param limit [Integer, nil] page size, 1..100 (upstream default 20)
+      # @param cursor [String, nil] opaque cursor from a previous page's
+      #   {SandboxPage#next_cursor}
+      # @return [SandboxPage]
+      def list_with(labels: {}, limit: nil, cursor: nil)
         opts = {"labels" => stringify(labels)}
-        Native::Sandbox.list_with(opts).map { |h| SandboxHandle.new(h) }
+        opts["limit"] = Integer(limit) if limit
+        opts["cursor"] = cursor.to_s if cursor
+        build_page(Native::Sandbox.list_with(opts))
       end
 
       # Remove a (stopped) sandbox by name.
@@ -518,6 +567,15 @@ module Microsandbox
         hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v.to_s }
       end
 
+      # Wrap a native page Hash ({"sandboxes" => [...], "next_cursor" => ...})
+      # into a {SandboxPage} of {SandboxHandle}s.
+      def build_page(data)
+        SandboxPage.new(
+          data["sandboxes"].map { |h| SandboxHandle.new(h) },
+          data["next_cursor"]
+        )
+      end
+
       def intify_ports(ports)
         ports.each_with_object({}) { |(k, v), acc| acc[Integer(k)] = Integer(v) }
       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.11.0"
+  VERSION = "0.12.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.7"
+  RUNTIME_VERSION = "v0.6.8"
 end

data/sig/microsandbox.rbs

@@ -61,7 +61,10 @@ module Microsandbox
   class MetricsUnavailableError < Error end
   class UnsupportedOperationError < Error end
   class CloudHttpError < Error end
-  class UnsupportedError < Error end
+  class UnsupportedError < Error
+    def operation: () -> String?
+    def hint: () -> String?
+  end
 
   class ExecOutput
     def initialize: (Hash[String, untyped] data) -> void
@@ -198,6 +201,19 @@ module Microsandbox
     def observed_at: () -> Time
   end
 
+  class SandboxPage
+    include Enumerable[SandboxHandle]
+    def initialize: (Array[SandboxHandle] sandboxes, String? next_cursor) -> void
+    def sandboxes: () -> Array[SandboxHandle]
+    def next_cursor: () -> String?
+    def each: () { (SandboxHandle) -> void } -> Array[SandboxHandle]
+            | () -> Enumerator[SandboxHandle, Array[SandboxHandle]]
+    def size: () -> Integer
+    def length: () -> Integer
+    def empty?: () -> bool
+    def last_page?: () -> bool
+  end
+
   class PingResult
     def initialize: (Hash[String, untyped] data) -> void
     def name: () -> String
@@ -251,8 +267,8 @@ module Microsandbox
     def self.create_with_progress: (String name, **untyped) -> PullSession
     def self.start: (String name, ?detached: bool) -> Sandbox
     def self.get: (String name) -> SandboxHandle
-    def self.list: () -> Array[SandboxHandle]
-    def self.list_with: (?labels: Hash[untyped, untyped]) -> Array[SandboxHandle]
+    def self.list: () -> SandboxPage
+    def self.list_with: (?labels: Hash[untyped, untyped], ?limit: Integer?, ?cursor: String?) -> SandboxPage
     def self.remove: (String name) -> nil
 
     def name: () -> String

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: microsandbox-rb
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - ya-luotao