microsandbox-rb 0.10.0 → 0.12.0

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.6).
-version = "0.10.0"
+# The core-crate dependency below stays pinned at its own tag (v0.6.7).
+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.6", default-features = true, features = ["ssh"] }
-microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.6" }
+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.
@@ -51,6 +51,10 @@ fn class_name(err: &MicrosandboxError) -> &'static str {
         SnapshotSandboxRunning(_) => "SnapshotSandboxRunningError",
         SnapshotImageMissing(_) => "SnapshotImageMissingError",
         SnapshotIntegrity(_) => "SnapshotIntegrityError",
+        // v0.6.7 (#1200): the automatic v0.6.6→v0.6.7 snapshot-descriptor
+        // migration (run at backend connect / artifact open) failed and needs
+        // repair. Mirrors the Python `SnapshotMigrationError`.
+        SnapshotMigration { .. } => "SnapshotMigrationError",
         // Give the already-defined-but-orphaned `NetworkPolicyError` a mapping:
         // a builder parse/validation error from `network(|n| ...)`. The gem
         // unconditionally enables the core's `net` feature (default-features),
@@ -79,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,9 +7,11 @@
 
 use magnus::{function, prelude::*, Error, RArray, RHash, RModule, Ruby};
 use microsandbox::image::{Image, ImageDetail, ImageHandle, ImagePruneReport};
+use microsandbox::{ImageArchiveFormat, Operation};
 
 use crate::backend::with_local_backend;
 use crate::conv;
+use crate::error;
 use crate::runtime::ruby;
 
 fn handle_to_hash(h: &ImageHandle) -> RHash {
@@ -82,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))?;
@@ -96,19 +102,59 @@ 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))
 }
 
+/// Load images into the cache from a local `docker save` tarball or an OCI
+/// Image Layout archive. `tags` optionally retags what was loaded. Returns an
+/// Array of image-handle Hashes. Mirrors the Python `Image.load` / Node
+/// `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(Operation::ImageLoad, async |local| {
+        Image::load_local(local, std::path::Path::new(&input_path), tags).await
+    })?;
+    let arr = ruby().ary_new();
+    for h in handles.iter() {
+        arr.push(handle_to_hash(h))?;
+    }
+    Ok(arr)
+}
+
+/// Save cached image(s) into a local archive. `format` is "docker" (default
+/// shape callers expect from `docker load`) or "oci" (OCI Image Layout).
+/// Mirrors the Python `Image.save` / Node `imageSave` added in v0.6.7.
+fn save(references: Vec<String>, output_path: String, format: String) -> Result<(), Error> {
+    let fmt = match format.as_str() {
+        "docker" => ImageArchiveFormat::Docker,
+        "oci" => ImageArchiveFormat::Oci,
+        other => {
+            return Err(error::base_error(format!(
+                "invalid archive format {other:?}: expected \"docker\" or \"oci\""
+            )))
+        }
+    };
+    with_local_backend(Operation::ImageSave, async |local| {
+        Image::save_local(local, &references, std::path::Path::new(&output_path), fmt).await
+    })
+}
+
 pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     let class = native.define_class("Image", ruby.class_object())?;
     class.define_singleton_method("get", function!(get, 1))?;
@@ -116,5 +162,7 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     class.define_singleton_method("inspect", function!(inspect, 1))?;
     class.define_singleton_method("remove", function!(remove, 2))?;
     class.define_singleton_method("prune", function!(prune, 0))?;
+    class.define_singleton_method("load", function!(load, 2))?;
+    class.define_singleton_method("save", function!(save, 3))?;
     Ok(())
 }

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())
 }