microsandbox-rb 0.9.2 → 0.11.0

data/README.md

@@ -39,7 +39,7 @@ them. Our deepest thanks to the maintainers and community. 🙏
 - **Guest filesystem access** — read, write, list, copy, stat files inside a running sandbox
 - **Metrics & logs** — CPU, memory, disk and network I/O; captured stdout/stderr/system logs
 - **Rootfs patches** — inject files, dirs, and symlinks into the image before boot (`Microsandbox::Patch`)
-- **Fine-grained networking** — policy presets *and* custom CIDR/domain/group allow-deny rules (`Microsandbox::NetworkPolicy`)
+- **Fine-grained networking** — composable profiles (`:public`/`:private`/`:host`) *and* custom CIDR/domain/group allow-deny rules (`Microsandbox::NetworkPolicy`)
 - **SSH & SFTP** — native in-process SSH client/server and file transfer (`Sandbox#ssh`)
 - **Raw agent client** — byte-level access to the guest `agentd` protocol (`Microsandbox::AgentClient`)
 - **Idiomatic Ruby** — keyword arguments, block-scoped lifecycle, a typed error hierarchy
@@ -160,7 +160,7 @@ Microsandbox::Sandbox.create(
   workdir:  "/app",
   labels:   { "team" => "research" },
   ports:    { 8080 => 80 },            # host => guest (TCP)
-  network:  "public_only",             # or "none" for airgapped
+  network:  [:public],                 # composable profiles; :none for airgapped
   replace:  true                       # replace an existing sandbox of the same name
 ) do |sb|
   # ...
@@ -229,6 +229,55 @@ Microsandbox::Sandbox.create("obs", image: "public.ecr.aws/docker/library/alpine
 end
 ```
 
+### Live modification & health
+
+Resize, reconfigure, or rotate secrets on a sandbox **without recreating it**,
+and probe the guest agent's liveness. To leave headroom for a live CPU/memory
+resize, reserve a ceiling at create time with `max_cpus:`/`max_memory:`:
+
+```ruby
+Microsandbox::Sandbox.create("live", image: "public.ecr.aws/docker/library/alpine:latest",
+  cpus: 1, max_cpus: 4, memory: 512, max_memory: 2048) do |sb|
+  # Health check — does NOT refresh the idle timer:
+  ping = sb.ping                       # => Microsandbox::PingResult
+  ping.latency_ms                      # round-trip latency
+
+  # Explicitly refresh the idle-activity timer (resets any idle_timeout:):
+  sb.touch.activity_seq                # => Microsandbox::TouchResult
+
+  # Preview a change without applying it:
+  plan = sb.modify(cpus: 2, memory: 1024, dry_run: true)
+  plan.applied?                        # => false
+  plan.changes                         # => [{ kind: "config", field: "cpus", ... }, ...]
+
+  # Live resize — applies to the running VM under the default :no_restart policy:
+  sb.modify(cpus: 2, memory: 1024)
+
+  # 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 —
+  # by saying so explicitly:
+  sb.modify(env: { "TIER" => "prod" }, remove_env: ["DEBUG"],
+    labels: { "role" => "worker" }, policy: :next_start)  # or policy: :restart
+
+  # Rotating/removing an *existing* secret (or updating its allowed hosts) is
+  # live; *adding* a new secret is restart-required, like env. Specs are keyed
+  # by name; env:/store:/value: are mutually exclusive:
+  sb.modify(
+    secrets: { "API_KEY" => { env: "HOST_API_KEY", allowed_hosts: ["api.example.com"] } },
+    remove_secrets: ["OLD_TOKEN"],
+  )
+end
+```
+
+The apply is **all-or-nothing**: under a given `policy:` every planned change
+must be applicable, or the whole `modify` raises — nothing is partially
+applied. Use `dry_run: true` to inspect each change's `disposition` (`"live"`,
+`"next start"`, `"requires restart"`) before committing.
+
+`SandboxHandle` (from `Sandbox.get`/`list`) carries the same `#ping`/`#touch`/
+`#modify`; on a stopped sandbox `#ping`/`#touch` raise `SandboxNotRunningError`.
+
 ### Streaming output
 
 For long-running commands, stream events as they arrive instead of waiting:
@@ -393,8 +442,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.9.2"  (the gem's own version)
-Microsandbox.runtime_version   # => "v0.6.3"  (the embedded upstream runtime tag)
+Microsandbox::VERSION          # => "0.11.0"  (the gem's own version)
+Microsandbox.runtime_version   # => "v0.6.7"  (the embedded upstream runtime tag)
 ```
 
 | Gem version | Upstream runtime | Notes |
@@ -413,6 +462,9 @@ Microsandbox.runtime_version   # => "v0.6.3"  (the embedded upstream runtime tag
 | `0.9.0`  | `v0.6.1` | adopts upstream `v0.6.0`+`v0.6.1` (zombie-runtime wait fix, secret substitution through CONNECT proxies, stale-sandbox cleanup); upstream public API is additive — no Ruby surface change |
 | `0.9.1`  | `v0.6.2` | adopts upstream `v0.6.2` (faster image loads/pulls via early cache gate + zlib-rs); upstream API unchanged — no Ruby surface change |
 | `0.9.2`  | `v0.6.3` | adopts upstream `v0.6.3` (v4-only sandboxes stop advertising AAAA DNS answers — fixes guest gRPC/c-ares preferring unreachable IPv6; scoped upstream TLS verification); glue moves to `*_local` SDK variants — no Ruby surface change |
+| `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 |
 
 **Going forward** — the gem version moves on its own semver track and no longer
 mirrors the upstream tag:
@@ -491,7 +543,7 @@ 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`/`config`/`config_json`/`snapshot`/`snapshot_to` from
+`wait_until_stopped`/`config`/`config_json`/`snapshot` 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`/
@@ -499,10 +551,12 @@ backend routing (`set_default_backend`/`with_backend`/`default_backend_kind`),
 `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
+snapshots (create/open/list/list_dir/reindex/verify/save/load +
+boot-from-snapshot), image archives (`Image.load`/`Image.save`), streaming
+image-pull progress (`Sandbox.create_with_progress` → `PullSession`),
+**rootfs patches** (`Microsandbox::Patch`), the structured **root disk**
+(`root_disk:` managed/tmpfs/disk via `Microsandbox::RootDisk`), **network
+configuration** (composable profiles, 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

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.3).
-version = "0.9.2"
+# The core-crate dependency below stays pinned at its own tag (v0.6.7).
+version = "0.11.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.3", default-features = true, features = ["ssh"] }
-microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.3" }
+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" }
 
 # 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/error.rs

@@ -17,6 +17,12 @@ fn class_name(err: &MicrosandboxError) -> &'static str {
         SandboxNotFound(_) => "SandboxNotFoundError",
         SandboxAlreadyExists(_) => "SandboxAlreadyExistsError",
         SandboxStillRunning(_) => "SandboxStillRunningError",
+        // v0.6.6 (#1099): the sandbox exists but isn't running. Raised by the
+        // handle's exec/attach/ping/touch not-running guards and the fs
+        // agent-endpoint lookup. The `SandboxNotRunningError` class already
+        // existed (mirroring the Python SDK); this wires the new core variant to
+        // it instead of letting it collapse to the base `Error`.
+        SandboxNotRunning(_) => "SandboxNotRunningError",
         ExecTimeout(_) => "ExecTimeoutError",
         ExecFailed(_) => "ExecFailedError",
         SandboxFsOps(_) => "FilesystemError",
@@ -45,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),

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;
 
 use crate::backend::with_local_backend;
 use crate::conv;
+use crate::error;
 use crate::runtime::ruby;
 
 fn handle_to_hash(h: &ImageHandle) -> RHash {
@@ -109,6 +111,40 @@ fn prune() -> Result<RHash, Error> {
     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(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(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 +152,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(())
 }