microsandbox-rb 0.5.8 → 0.5.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56e1f366f8e18a95965bc917c65b739426499a147f1da4a2defb090dba4c375d
-  data.tar.gz: 689f3c5518ddc52e6fd851d290e2629d3a3a9a043ba09653a6ce1041039a9a37
+  metadata.gz: 045a5bf021edaf5afcfcf487cf0d980c38018560cc842c44018863570236f4ed
+  data.tar.gz: 25791e8bab4051711794cb8c1e08bbabc2b4dbc79bf080b02908b620ee0bd06e
 SHA512:
-  metadata.gz: 503d0a3460f47855742e5179ccafab4e7b65132e71af5d3c39ed77b14542ac231e6bdbb9ebe2021e06ff2da912f702c8ad44f5a0dd882343879954d529581729
-  data.tar.gz: '08880c49fc0803d36ba7d1ee3b457c130528155a0ede5d3360c34fc805bc94feb4f6b88f7ae16287b97bdfefc32bbb8c1fdb7a7c89cfee3d46606c6a071efd6d'
+  metadata.gz: 1b89148498194edb82241979432ee2e47599f2b657805b05718bfd18a8e1104318833ef84eb5f5e47a66f3cec8dc369f742897bbfe60cdb07fb613b597ef6ac5
+  data.tar.gz: c25b033291b4fb5195349030dcf2296006fa8b3563c7e1f6804441ed5e554e496583b22ddbca32828dff1b36127082b4cb1e995ab654573afc46b09e012031fd

data/CHANGELOG.md

@@ -6,6 +6,54 @@ upstream microsandbox runtime.
 
 ## [Unreleased]
 
+## [0.5.9] - 2026-06-18
+
+Closes the remaining roadmap items, bringing the binding surface to parity with
+the official Python/Node/Go SDKs (still wrapping the same upstream core,
+`v0.5.7`).
+
+### Added
+
+- **Rootfs patches** — `Sandbox.create(patches: [...])` applies modifications to
+  the root filesystem before boot, built with the new `Microsandbox::Patch`
+  factory: `Patch.text`/`file`/`append`/`copy_file`/`copy_dir`/`symlink`/`mkdir`/
+  `remove`. Mirrors the `Patch` factory in the official SDKs. (OverlayFS/bind
+  roots only — not disk images.)
+- **Custom per-rule network policies** — `Sandbox.create(network:)` now accepts,
+  besides the existing preset names, a `Microsandbox::NetworkPolicy` or a Hash
+  describing an ordered allow/deny rule list with per-direction defaults and bulk
+  domain denials. New `Microsandbox::NetworkPolicy` (`public_only`/`none`/
+  `allow_all`/`non_local`/`custom`), `Microsandbox::Rule` (`allow`/`deny`), and
+  `Microsandbox::Destination` (`any`/`ip`/`cidr`/`domain`/`domain_suffix`/
+  `group`, plus shorthand-string classification) factories. Destination
+  classification and rule composition mirror the official binding exactly.
+- **Raw agent client** — `Microsandbox::AgentClient.connect_sandbox`/
+  `connect_path`/`socket_path` open the byte-level transport to a sandbox's
+  `agentd` relay socket: `request`, `stream` (→ `Microsandbox::AgentStream`,
+  `Enumerable` over `Microsandbox::AgentFrame`), `send_frame`, `ready_bytes`,
+  `close`, with the `FLAG_TERMINAL`/`FLAG_SESSION_START`/`FLAG_SHUTDOWN` frame
+  flags. Mirrors the official `AgentClient`.
+- **SSH** — `Sandbox#ssh` returns a `Microsandbox::SshOps` to `open_client`
+  (→ `Microsandbox::SshClient`: `exec` → `Microsandbox::SshOutput`, `attach`,
+  `sftp` → `Microsandbox::SftpClient` with `read`/`write`/`mkdir`/`remove_file`/
+  `remove_dir`/`rename`/`symlink`/`real_path`/`read_link`, `close`) or
+  `prepare_server` (→ `Microsandbox::SshServer`: `serve_connection`, `close`).
+- **Interactive attach** — `Sandbox#attach(command, args, …)` and
+  `Sandbox#attach_shell` couple the host terminal (raw mode, SIGWINCH) to a
+  command (or the default shell) in the sandbox and return its exit code. For
+  CLI use — requires a real TTY.
+- RBS signatures for all of the above.
+
+### Notes
+
+- Network policy: a `preset` and custom `rules:`/`default_egress:`/`default_ingress:`
+  are mutually exclusive (a preset already defines its rules and defaults); a
+  preset may still be layered with `deny_domains:`/`deny_domain_suffixes:`. A
+  hand-written rule Hash accepts the singular `protocol:`/`port:` keys (the
+  spelling the Go/Python `PolicyRule` use) as well as the plural forms. The
+  deny-list-only shorthand (`network: { deny_domains: [...] }`) keeps the rest of
+  the network reachable (permissive defaults), matching the official SDKs.
+
 ## [0.5.8] - 2026-06-17
 
 Closes the `Sandbox`-class lifecycle gap with the official Python/Node/Go SDKs

data/Cargo.lock

@@ -3232,7 +3232,7 @@ dependencies = [
 
 [[package]]
 name = "microsandbox_rb"
-version = "0.5.8"
+version = "0.5.9"
 dependencies = [
  "chrono",
  "futures",

data/DESIGN.md

@@ -137,24 +137,32 @@ API (`fs.read`/`write`/`list`/`mkdir`/`remove`/`stat`/…), `metrics`,
 **OCI image-cache management** (`Image.get`/`list`/`inspect`/`remove`/`prune`),
 **named volumes** (`Volume.create`/`get`/`list`/`remove` + `volumes:` mounts),
 **snapshots** (`Snapshot.create`/`get`/`list`/`remove`/`verify`/`export`/`import`
-+ `from_snapshot:` boot), `version`/`install`/`installed?`/`ensure_runtime!`,
-**registry auth** (`registry_auth`/`registry_insecure`/`registry_ca_certs` on
-`create`, for private/authenticated registries), and the typed error hierarchy.
++ `from_snapshot:` boot), **rootfs patches** (`Patch.text`/`file`/`append`/
+`copy_file`/`copy_dir`/`symlink`/`mkdir`/`remove` via `create(patches:)`),
+**custom per-rule network policies** (`NetworkPolicy`/`Rule`/`Destination` —
+CIDR/IP/domain/suffix/group allow-deny rules with per-direction defaults and
+bulk domain denials, alongside the presets), interactive **`attach`/
+`attach_shell`** (host-TTY coupled — raw mode + SIGWINCH), **SSH**
+(`Sandbox#ssh` → `SshClient`/`SftpClient`/`SshServer`), the **raw agent client**
+(`AgentClient` → `AgentStream`/`AgentFrame`),
+`version`/`install`/`installed?`/`ensure_runtime!`, **registry auth**
+(`registry_auth`/`registry_insecure`/`registry_ca_certs` on `create`, for
+private/authenticated registries), and the typed error hierarchy.
 
 Create options now cover `image`, `cpus`, `memory`, `oci_upper_size`, `env`,
 `workdir`, `shell`, `user`, `hostname`, `labels`, `scripts`, `entrypoint`,
-`ports`/`ports_udp`, `volumes`, `network` policy presets
-(`public_only`/`none`/`allow_all`/`non_local`), `log_level`, `quiet_logs`,
-`security`, `max_duration`, `idle_timeout`, `rlimits`, `pull_policy`,
-`registry_auth`/`registry_insecure`/`registry_ca_certs`, `secrets`,
-`from_snapshot`, `detached`, and `replace`/`replace_with_timeout`. `exec`/`shell`
-add per-call `rlimits`.
+`ports`/`ports_udp`, `volumes`, `patches`, `network` (policy presets
+`public_only`/`none`/`allow_all`/`non_local`, or a custom `NetworkPolicy`/Hash),
+`log_level`, `quiet_logs`, `security`, `max_duration`, `idle_timeout`, `rlimits`,
+`pull_policy`, `registry_auth`/`registry_insecure`/`registry_ca_certs`,
+`secrets`, `from_snapshot`, `detached`, and `replace`/`replace_with_timeout`.
+`exec`/`shell` add per-call `rlimits`.
 
 ## Verification
 
 The binding is verified at four levels:
 
-1. **Unit** (140 examples) — the Ruby layer's option normalization and value
+1. **Unit** (192 examples) — the Ruby layer's option normalization and value
    objects, with the native layer stubbed.
 2. **Real-microVM integration** (`spec/integration`, opt-in via
    `MICROSANDBOX_INTEGRATION=1`) — boots actual sandboxes and round-trips
@@ -170,9 +178,10 @@ The binding is verified at four levels:
    shipped Rust source via `extconf.rb` and the installed gem boots a real
    microVM, confirming the gem manifest and source-install path are complete.
 
-**Roadmap:** custom per-rule network policies (CIDR/domain/group allow-deny
-rules — the presets and secret-host allowances are covered), file patches,
-interactive `attach`/`attach_shell` (host-TTY coupled — raw mode,
-SIGWINCH), SSH (`SshClient`/`SftpClient`/`SshServer`), and the raw agent client.
-The native layer is structured so these slot in module-by-module, exactly as in
-the Python binding.
+**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.

data/README.md

@@ -14,6 +14,10 @@ This is an **unofficial, community-maintained** Ruby implementation — not part
 - **Command execution** — run commands or shell scripts and collect output
 - **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`)
+- **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
 - **Thread-friendly** — the GVL is released during sandbox calls, so other Ruby threads keep running
 
@@ -372,19 +376,22 @@ one bound to the gem.
 > 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 for what's covered today vs. on the roadmap. Covered: full sandbox
+section. The binding now covers the full official-SDK surface: sandbox
 lifecycle (including the async `request_stop`/`request_kill`/`request_drain`/
 `wait_until_stopped`/`detach`/`owns_lifecycle?` controls and label-filtered
-`list_with`), `exec`/`shell` (collected and streaming), the full guest
-filesystem, metrics (per-sandbox, `Microsandbox.all_sandbox_metrics`, and
-streaming `metrics_stream`/`log_stream`), logs, OCI image-cache management,
-named volumes, and snapshots (create/list/verify/export/import +
-boot-from-snapshot). Create options span resources, network policy presets,
-`log_level`/`security`/`rlimits`/`pull_policy`/`secrets` and more; `exec`/`shell`
-take per-call `rlimits`, and `create` accepts `registry_auth`/`registry_insecure`/
-`registry_ca_certs` for private and authenticated registries. Still on the
-roadmap: custom per-rule network policies, file patches, interactive `attach`,
-SSH, and the raw agent client.
+`list_with`), `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
+`registry_auth`/`registry_insecure`/`registry_ca_certs` for private and
+authenticated registries.
 
 ## License
 

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.7).
-version = "0.5.8"
+version = "0.5.9"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"

data/ext/microsandbox/src/agent.rs

@@ -0,0 +1,166 @@
+//! Raw agent client: `Microsandbox::Native::AgentClient`.
+//!
+//! Mirrors `sdk/python/src/agent.rs`. Wraps the core `AgentBridge` — the
+//! FFI-shaped, bytes-in/bytes-out façade over a sandbox's agentd relay socket.
+//! Frames are moved as raw CBOR bodies; (de)serialization stays in Ruby. Streams
+//! are referenced by opaque `u64` handles so the Ruby layer never owns a tokio
+//! receiver. Every call runs on the shared tokio runtime with the GVL released.
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use magnus::{function, method, prelude::*, Error, RHash, RModule, RString, Ruby};
+use microsandbox::agent::AgentClient as CoreAgentClient;
+use microsandbox::{AgentBridge, BridgeFrame, MicrosandboxError};
+
+use crate::error;
+use crate::runtime::{block_on, ruby};
+
+/// Map an agent-client error onto the Ruby exception hierarchy (via the core
+/// `MicrosandboxError::AgentClient` wrapper, exactly like the Python binding).
+fn to_ruby_agent(err: microsandbox::AgentClientError) -> Error {
+    error::to_ruby(MicrosandboxError::AgentClient(err))
+}
+
+#[magnus::wrap(class = "Microsandbox::Native::AgentClient", free_immediately, size)]
+pub struct AgentClient {
+    inner: Arc<AgentBridge>,
+}
+
+impl AgentClient {
+    fn from_bridge(bridge: AgentBridge) -> Self {
+        Self {
+            inner: Arc::new(bridge),
+        }
+    }
+
+    //----------------------------------------------------------------------
+    // Connection (singleton methods)
+    //----------------------------------------------------------------------
+
+    /// 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) {
+            Some(t) => block_on(AgentBridge::connect_sandbox_with_timeout(&name, t)),
+            None => block_on(AgentBridge::connect_sandbox(&name)),
+        }
+        .map_err(to_ruby_agent)?;
+        Ok(AgentClient::from_bridge(bridge))
+    }
+
+    /// 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) {
+            Some(t) => block_on(AgentBridge::connect_path_with_timeout(&path, t)),
+            None => block_on(AgentBridge::connect_path(&path)),
+        }
+        .map_err(to_ruby_agent)?;
+        Ok(AgentClient::from_bridge(bridge))
+    }
+
+    /// Resolve a sandbox's agent relay socket path without connecting.
+    fn socket_path(name: String) -> Result<String, Error> {
+        let path = CoreAgentClient::socket_path(&name).map_err(error::to_ruby)?;
+        Ok(path.to_string_lossy().into_owned())
+    }
+
+    //----------------------------------------------------------------------
+    // Instance methods
+    //----------------------------------------------------------------------
+
+    /// Send one frame and await a single response frame ({id, flags, body}).
+    fn request(&self, flags: u8, body: RString) -> Result<RHash, Error> {
+        let body = unsafe { body.as_slice() }.to_vec();
+        let inner = Arc::clone(&self.inner);
+        let frame =
+            block_on(async move { inner.request(flags, body).await }).map_err(to_ruby_agent)?;
+        Ok(frame_to_hash(frame))
+    }
+
+    /// Open a streaming session; returns {id, handle}.
+    fn stream_open(&self, flags: u8, body: RString) -> Result<RHash, Error> {
+        let body = unsafe { body.as_slice() }.to_vec();
+        let inner = Arc::clone(&self.inner);
+        let (id, handle) =
+            block_on(async move { inner.stream_open(flags, body).await }).map_err(to_ruby_agent)?;
+        let hash = ruby().hash_new();
+        hash.aset("id", id)?;
+        hash.aset("handle", handle)?;
+        Ok(hash)
+    }
+
+    /// Pull the next frame from a stream; nil at end-of-stream.
+    fn stream_next(&self, handle: u64) -> Result<Option<RHash>, Error> {
+        let inner = Arc::clone(&self.inner);
+        let frame =
+            block_on(async move { inner.stream_next(handle).await }).map_err(to_ruby_agent)?;
+        Ok(frame.map(frame_to_hash))
+    }
+
+    /// Close a stream handle. Idempotent.
+    fn stream_close(&self, handle: u64) -> Result<(), Error> {
+        let inner = Arc::clone(&self.inner);
+        block_on(async move { inner.stream_close(handle).await });
+        Ok(())
+    }
+
+    /// Send a follow-up frame on an existing correlation id.
+    fn send(&self, id: u32, flags: u8, body: RString) -> Result<(), Error> {
+        let body = unsafe { body.as_slice() }.to_vec();
+        let inner = Arc::clone(&self.inner);
+        block_on(async move { inner.send(id, flags, body).await }).map_err(to_ruby_agent)
+    }
+
+    /// Cached handshake `core.ready` frame body bytes (CBOR).
+    fn ready_bytes(&self) -> Result<RString, Error> {
+        let bytes = self.inner.ready_bytes().map_err(to_ruby_agent)?;
+        Ok(ruby().str_from_slice(&bytes))
+    }
+
+    /// Close the connection. Idempotent.
+    fn close(&self) -> Result<(), Error> {
+        let inner = Arc::clone(&self.inner);
+        block_on(async move { inner.close().await });
+        Ok(())
+    }
+}
+
+/// Convert seconds into a `Duration`, treating a non-positive/absent value as
+/// "use the default handshake timeout".
+fn dur(timeout: Option<f64>) -> Option<Duration> {
+    match timeout {
+        Some(t) if t.is_finite() && t > 0.0 => Some(Duration::from_secs_f64(t)),
+        _ => None,
+    }
+}
+
+/// Shape a `BridgeFrame` into a Ruby Hash. `body` is binary (ASCII-8BIT).
+fn frame_to_hash(frame: BridgeFrame) -> RHash {
+    let r = ruby();
+    let hash = r.hash_new();
+    let _ = hash.aset("id", frame.id);
+    let _ = hash.aset("flags", frame.flags);
+    let _ = hash.aset("body", r.str_from_slice(&frame.body));
+    hash
+}
+
+pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
+    let class = native.define_class("AgentClient", ruby.class_object())?;
+
+    class.define_singleton_method(
+        "connect_sandbox",
+        function!(AgentClient::connect_sandbox, 2),
+    )?;
+    class.define_singleton_method("connect_path", function!(AgentClient::connect_path, 2))?;
+    class.define_singleton_method("socket_path", function!(AgentClient::socket_path, 1))?;
+
+    class.define_method("request", method!(AgentClient::request, 2))?;
+    class.define_method("stream_open", method!(AgentClient::stream_open, 2))?;
+    class.define_method("stream_next", method!(AgentClient::stream_next, 1))?;
+    class.define_method("stream_close", method!(AgentClient::stream_close, 1))?;
+    class.define_method("send", method!(AgentClient::send, 3))?;
+    class.define_method("ready_bytes", method!(AgentClient::ready_bytes, 0))?;
+    class.define_method("close", method!(AgentClient::close, 0))?;
+
+    Ok(())
+}

data/ext/microsandbox/src/conv.rs

@@ -5,7 +5,7 @@
 
 use std::collections::HashMap;
 
-use magnus::{value::ReprValue, Error, RHash, TryConvert, Value};
+use magnus::{value::ReprValue, Error, RArray, RHash, TryConvert, Value};
 
 /// Fetch a non-nil value for `key`, if present.
 fn get(hash: RHash, key: &str) -> Option<Value> {
@@ -62,6 +62,24 @@ pub fn opt_string_vec(hash: RHash, key: &str) -> Result<Vec<String>, Error> {
     }
 }
 
+/// Array of `Hash`es (e.g. `patches`, custom-policy `rules`). Empty if absent.
+///
+/// `RHash` is a GC-managed handle and so cannot be collected via the blanket
+/// `Vec<T: TryConvert>` path; we walk the `Array` and convert each element.
+pub fn opt_hash_vec(hash: RHash, key: &str) -> Result<Vec<RHash>, Error> {
+    match get(hash, key) {
+        Some(v) => {
+            let arr = RArray::try_convert(v)?;
+            let mut out = Vec::with_capacity(arr.len());
+            for i in 0..arr.len() {
+                out.push(arr.entry::<RHash>(i as isize)?);
+            }
+            Ok(out)
+        }
+        None => Ok(Vec::new()),
+    }
+}
+
 /// `u16`→`u16` port map (host→guest TCP). Empty if absent.
 pub fn opt_port_map(hash: RHash, key: &str) -> Result<Vec<(u16, u16)>, Error> {
     match get(hash, key) {

data/ext/microsandbox/src/lib.rs

@@ -8,6 +8,7 @@
 //! Everything here lives under `Microsandbox::Native`; the ergonomic, idiomatic
 //! surface is the pure-Ruby layer in `lib/microsandbox/`.
 
+mod agent;
 mod conv;
 mod error;
 mod exec;
@@ -15,6 +16,7 @@ mod image;
 mod runtime;
 mod sandbox;
 mod snapshot;
+mod ssh;
 mod stream;
 mod volume;
 
@@ -79,6 +81,8 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     snapshot::define(ruby, &native)?;
     image::define(ruby, &native)?;
     volume::define(ruby, &native)?;
+    agent::define(ruby, &native)?;
+    ssh::define(ruby, &native)?;
 
     Ok(())
 }