microsandbox-rb 0.5.7

data/ext/microsandbox/src/exec.rs

@@ -0,0 +1,158 @@
+//! Streaming command execution: `Microsandbox::Native::ExecHandle` and
+//! `Microsandbox::Native::ExecSink`.
+//!
+//! Mirrors `sdk/python/src/exec.rs`. The core `ExecHandle` is `&mut`-driven and
+//! lives behind an `Arc<tokio::Mutex<…>>`; each call locks it inside `block_on`.
+//! Signal/kill go through a cloned `ExecControl` so they never contend with an
+//! in-flight `recv`. Stdin (when piped) is exposed as a separate `ExecSink`.
+
+use std::sync::Arc;
+
+use magnus::{method, prelude::*, Error, RHash, RModule, RString, Ruby};
+use tokio::sync::Mutex;
+
+use crate::error;
+use crate::runtime::{block_on, ruby};
+
+#[magnus::wrap(class = "Microsandbox::Native::ExecHandle", free_immediately, size)]
+pub struct ExecHandle {
+    inner: Arc<Mutex<microsandbox::ExecHandle>>,
+    control: microsandbox::ExecControl,
+    stdin: std::sync::Mutex<Option<Arc<microsandbox::sandbox::exec::ExecSink>>>,
+    id: String,
+}
+
+impl ExecHandle {
+    /// Wrap a freshly-opened core handle, lifting out its id and stdin sink.
+    pub fn from_core(mut handle: microsandbox::ExecHandle) -> Self {
+        let id = handle.id();
+        let control = handle.control();
+        let stdin = handle.take_stdin().map(Arc::new);
+        Self {
+            inner: Arc::new(Mutex::new(handle)),
+            control,
+            stdin: std::sync::Mutex::new(stdin),
+            id,
+        }
+    }
+
+    fn id(&self) -> String {
+        self.id.clone()
+    }
+
+    /// Next event as a Hash, or nil when the stream ends.
+    fn recv(&self) -> Result<Option<RHash>, Error> {
+        let inner = Arc::clone(&self.inner);
+        let event = block_on(async move { inner.lock().await.recv().await });
+        Ok(event.map(exec_event_to_hash))
+    }
+
+    /// Block until exit; returns {exit_code, success}.
+    fn wait(&self) -> Result<RHash, Error> {
+        let inner = Arc::clone(&self.inner);
+        let status =
+            block_on(async move { inner.lock().await.wait().await }).map_err(error::to_ruby)?;
+        let hash = ruby().hash_new();
+        hash.aset("exit_code", status.code)?;
+        hash.aset("success", status.success)?;
+        Ok(hash)
+    }
+
+    /// Drain the stream and return a collected exec-output Hash.
+    fn collect(&self) -> Result<RHash, Error> {
+        let inner = Arc::clone(&self.inner);
+        let output =
+            block_on(async move { inner.lock().await.collect().await }).map_err(error::to_ruby)?;
+        crate::sandbox::exec_output_to_hash(output)
+    }
+
+    fn signal(&self, sig: i32) -> Result<(), Error> {
+        block_on(self.control.signal(sig)).map_err(error::to_ruby)
+    }
+
+    fn kill(&self) -> Result<(), Error> {
+        block_on(self.control.kill()).map_err(error::to_ruby)
+    }
+
+    fn resize(&self, rows: u16, cols: u16) -> Result<(), Error> {
+        block_on(self.control.resize(rows, cols)).map_err(error::to_ruby)
+    }
+
+    /// The stdin sink (only the first call returns it; nil afterwards or if
+    /// stdin was not piped).
+    fn take_stdin(&self) -> Option<ExecSink> {
+        let mut guard = self.stdin.lock().expect("exec stdin mutex poisoned");
+        guard.take().map(|sink| ExecSink { inner: sink })
+    }
+}
+
+#[magnus::wrap(class = "Microsandbox::Native::ExecSink", free_immediately, size)]
+pub struct ExecSink {
+    inner: Arc<microsandbox::sandbox::exec::ExecSink>,
+}
+
+impl ExecSink {
+    fn write(&self, data: RString) -> Result<(), Error> {
+        // Copy out while holding the GVL (see sandbox::fs_write for the rationale).
+        let bytes = unsafe { data.as_slice() }.to_vec();
+        block_on(self.inner.write(&bytes)).map_err(error::to_ruby)
+    }
+
+    fn close(&self) -> Result<(), Error> {
+        block_on(self.inner.close()).map_err(error::to_ruby)
+    }
+}
+
+/// Convert a core `ExecEvent` into a Ruby Hash. `data` is binary (ASCII-8BIT).
+fn exec_event_to_hash(event: microsandbox::ExecEvent) -> RHash {
+    use microsandbox::ExecEvent::*;
+    let r = ruby();
+    let hash = r.hash_new();
+    match event {
+        Started { pid } => {
+            let _ = hash.aset("type", "started");
+            let _ = hash.aset("pid", pid);
+        }
+        Stdout(data) => {
+            let _ = hash.aset("type", "stdout");
+            let _ = hash.aset("data", r.str_from_slice(data.as_ref()));
+        }
+        Stderr(data) => {
+            let _ = hash.aset("type", "stderr");
+            let _ = hash.aset("data", r.str_from_slice(data.as_ref()));
+        }
+        Exited { code } => {
+            let _ = hash.aset("type", "exited");
+            let _ = hash.aset("code", code);
+        }
+        Failed(payload) => {
+            let _ = hash.aset("type", "failed");
+            let _ = hash.aset("data", r.str_from_slice(payload.message.as_bytes()));
+            let _ = hash.aset("code", payload.errno);
+        }
+        StdinError(payload) => {
+            let _ = hash.aset("type", "stdin_error");
+            let _ = hash.aset("data", r.str_from_slice(payload.message.as_bytes()));
+            let _ = hash.aset("code", payload.errno);
+        }
+    }
+    hash
+}
+
+pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
+    let handle = native.define_class("ExecHandle", ruby.class_object())?;
+    handle.define_method("id", method!(ExecHandle::id, 0))?;
+    handle.define_method("recv", method!(ExecHandle::recv, 0))?;
+    handle.define_method("wait", method!(ExecHandle::wait, 0))?;
+    handle.define_method("collect", method!(ExecHandle::collect, 0))?;
+    handle.define_method("signal", method!(ExecHandle::signal, 1))?;
+    handle.define_method("kill", method!(ExecHandle::kill, 0))?;
+    handle.define_method("resize", method!(ExecHandle::resize, 2))?;
+    handle.define_method("take_stdin", method!(ExecHandle::take_stdin, 0))?;
+
+    let sink = native.define_class("ExecSink", ruby.class_object())?;
+    sink.define_method("write", method!(ExecSink::write, 1))?;
+    sink.define_method("close", method!(ExecSink::close, 0))?;
+
+    Ok(())
+}

data/ext/microsandbox/src/image.rs

@@ -0,0 +1,114 @@
+//! OCI image-cache management: `Microsandbox::Native::Image`.
+//!
+//! Mirrors `sdk/python/src/image.rs`. Static async operations over the cached
+//! image store; results are returned as plain Ruby Hashes/Arrays. Note the core
+//! `ImageHandle` exposes accessor *methods* while `ImageDetail`/`ImageConfigDetail`/
+//! `ImageLayerDetail`/`ImagePruneReport` expose public *fields*.
+
+use magnus::{function, prelude::*, Error, RArray, RHash, RModule, Ruby};
+use microsandbox::image::{Image, ImageDetail, ImageHandle, ImagePruneReport};
+
+use crate::error;
+use crate::runtime::{block_on, ruby};
+
+fn handle_to_hash(h: &ImageHandle) -> RHash {
+    let hash = ruby().hash_new();
+    let _ = hash.aset("reference", h.reference().to_string());
+    let _ = hash.aset("size_bytes", h.size_bytes());
+    let _ = hash.aset("manifest_digest", h.manifest_digest().map(str::to_string));
+    let _ = hash.aset("architecture", h.architecture().map(str::to_string));
+    let _ = hash.aset("os", h.os().map(str::to_string));
+    let _ = hash.aset("layer_count", h.layer_count());
+    let _ = hash.aset(
+        "created_at_ms",
+        h.created_at().map(|dt| dt.timestamp_millis()),
+    );
+    let _ = hash.aset(
+        "last_used_at_ms",
+        h.last_used_at().map(|dt| dt.timestamp_millis()),
+    );
+    hash
+}
+
+fn detail_to_hash(detail: ImageDetail) -> RHash {
+    let r = ruby();
+    let hash = r.hash_new();
+    let _ = hash.aset("handle", handle_to_hash(&detail.handle));
+
+    if let Some(config) = detail.config {
+        let c = r.hash_new();
+        let _ = c.aset("digest", config.digest);
+        let _ = c.aset("env", config.env);
+        let _ = c.aset("cmd", config.cmd);
+        let _ = c.aset("entrypoint", config.entrypoint);
+        let _ = c.aset("working_dir", config.working_dir);
+        let _ = c.aset("user", config.user);
+        let _ = c.aset("stop_signal", config.stop_signal);
+        let _ = hash.aset("config", c);
+    } else {
+        let _ = hash.aset("config", r.qnil());
+    }
+
+    let layers = r.ary_new();
+    for layer in detail.layers {
+        let l = r.hash_new();
+        let _ = l.aset("diff_id", layer.diff_id);
+        let _ = l.aset("blob_digest", layer.blob_digest);
+        let _ = l.aset("media_type", layer.media_type);
+        let _ = l.aset("compressed_size_bytes", layer.compressed_size_bytes);
+        let _ = l.aset("erofs_size_bytes", layer.erofs_size_bytes);
+        let _ = l.aset("position", layer.position);
+        let _ = layers.push(l);
+    }
+    let _ = hash.aset("layers", layers);
+    hash
+}
+
+fn report_to_hash(report: ImagePruneReport) -> RHash {
+    let hash = ruby().hash_new();
+    let _ = hash.aset("image_refs_removed", report.image_refs_removed);
+    let _ = hash.aset("manifests_removed", report.manifests_removed);
+    let _ = hash.aset("layers_removed", report.layers_removed);
+    let _ = hash.aset("fsmeta_removed", report.fsmeta_removed);
+    let _ = hash.aset("vmdk_removed", report.vmdk_removed);
+    let _ = hash.aset("bytes_reclaimed", report.bytes_reclaimed);
+    hash
+}
+
+fn get(reference: String) -> Result<RHash, Error> {
+    let handle = block_on(Image::get(&reference)).map_err(error::to_ruby)?;
+    Ok(handle_to_hash(&handle))
+}
+
+fn list() -> Result<RArray, Error> {
+    let handles = block_on(Image::list()).map_err(error::to_ruby)?;
+    let arr = ruby().ary_new();
+    for h in handles.iter() {
+        arr.push(handle_to_hash(h))?;
+    }
+    Ok(arr)
+}
+
+fn inspect(reference: String) -> Result<RHash, Error> {
+    let detail = block_on(Image::inspect(&reference)).map_err(error::to_ruby)?;
+    Ok(detail_to_hash(detail))
+}
+
+fn remove(reference: String, force: bool) -> Result<(), Error> {
+    block_on(Image::remove(&reference, force)).map_err(error::to_ruby)
+}
+
+fn prune() -> Result<RHash, Error> {
+    let report = block_on(Image::prune()).map_err(error::to_ruby)?;
+    Ok(report_to_hash(report))
+}
+
+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))?;
+    class.define_singleton_method("list", function!(list, 0))?;
+    class.define_singleton_method("inspect", function!(inspect, 1))?;
+    class.define_singleton_method("remove", function!(remove, 2))?;
+    class.define_singleton_method("prune", function!(prune, 0))?;
+    Ok(())
+}

data/ext/microsandbox/src/lib.rs

@@ -0,0 +1,84 @@
+//! Ruby SDK native extension for microsandbox.
+//!
+//! The Ruby analogue of the official Python (pyo3) and Node (napi) bindings: it
+//! exposes the embedded `microsandbox` runtime to Ruby via magnus. The core is
+//! async (tokio); the Ruby API is synchronous, so every binding blocks on a
+//! shared multi-threaded tokio runtime with the GVL released (see `runtime`).
+//!
+//! Everything here lives under `Microsandbox::Native`; the ergonomic, idiomatic
+//! surface is the pure-Ruby layer in `lib/microsandbox/`.
+
+mod conv;
+mod error;
+mod exec;
+mod image;
+mod runtime;
+mod sandbox;
+mod snapshot;
+mod stream;
+mod volume;
+
+use magnus::{function, prelude::*, Error, RHash, Ruby};
+
+/// Gem/runtime version string.
+fn version() -> String {
+    env!("CARGO_PKG_VERSION").to_string()
+}
+
+/// Latest metrics for every running sandbox, as a `{ name => metrics_hash }`
+/// Ruby Hash. Mirrors the official `all_sandbox_metrics` / `allSandboxMetrics`
+/// helpers (Python/Node/Go).
+fn all_sandbox_metrics() -> Result<RHash, Error> {
+    let map =
+        runtime::block_on(microsandbox::sandbox::all_sandbox_metrics()).map_err(error::to_ruby)?;
+    let hash = runtime::ruby().hash_new();
+    for (name, metrics) in &map {
+        hash.aset(name.as_str(), sandbox::metrics_to_hash(metrics))?;
+    }
+    Ok(hash)
+}
+
+/// Download and install the `msb` runtime + `libkrunfw` into `~/.microsandbox`.
+fn install() -> Result<(), Error> {
+    runtime::block_on(microsandbox::setup::install()).map_err(error::to_ruby)
+}
+
+/// Whether the `msb` runtime + `libkrunfw` are installed and resolvable.
+fn is_installed() -> bool {
+    microsandbox::setup::is_installed()
+}
+
+/// Override the resolved `msb` runtime path (SDK tier of the resolver).
+fn set_runtime_msb_path(path: String) {
+    microsandbox::config::set_sdk_msb_path(path);
+}
+
+/// The currently-resolved `msb` runtime path.
+fn resolved_msb_path() -> Result<String, Error> {
+    let path = microsandbox::config::resolve_msb_path().map_err(error::to_ruby)?;
+    Ok(path.to_string_lossy().into_owned())
+}
+
+/// magnus entry point. RubyGems loads this via `require "microsandbox/microsandbox_rb"`,
+/// which calls `Init_microsandbox_rb` (matching the cdylib `[lib] name`).
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("Microsandbox")?;
+    let native = module.define_module("Native")?;
+
+    native.define_singleton_method("version", function!(version, 0))?;
+    native.define_singleton_method("install", function!(install, 0))?;
+    native.define_singleton_method("installed?", function!(is_installed, 0))?;
+    native.define_singleton_method("set_runtime_msb_path", function!(set_runtime_msb_path, 1))?;
+    native.define_singleton_method("resolved_msb_path", function!(resolved_msb_path, 0))?;
+    native.define_singleton_method("all_sandbox_metrics", function!(all_sandbox_metrics, 0))?;
+
+    sandbox::define(ruby, &native)?;
+    exec::define(ruby, &native)?;
+    stream::define(ruby, &native)?;
+    snapshot::define(ruby, &native)?;
+    image::define(ruby, &native)?;
+    volume::define(ruby, &native)?;
+
+    Ok(())
+}

data/ext/microsandbox/src/runtime.rs

@@ -0,0 +1,92 @@
+//! Shared tokio runtime and the GVL-release bridge.
+//!
+//! The microsandbox core is async; the Ruby API is synchronous. Every native
+//! method runs its future to completion on a single, process-wide multi-threaded
+//! tokio runtime. Crucially, the blocking call happens inside [`nogvl`], which
+//! releases Ruby's Global VM Lock for the duration so other Ruby threads keep
+//! running while a (potentially long) sandbox operation is in flight.
+
+use std::ffi::c_void;
+use std::future::Future;
+use std::panic::{catch_unwind, AssertUnwindSafe};
+use std::sync::OnceLock;
+
+use magnus::Ruby;
+use tokio::runtime::Runtime;
+
+/// The current Ruby handle. Safe to call from any bound method or value
+/// conversion: we always hold the GVL there (conversions run after `block_on`
+/// returns and re-acquires it).
+pub fn ruby() -> Ruby {
+    Ruby::get().expect("microsandbox: not on a Ruby thread")
+}
+
+static RUNTIME: OnceLock<Runtime> = OnceLock::new();
+
+/// The process-wide multi-threaded tokio runtime, built on first use.
+pub fn runtime() -> &'static Runtime {
+    RUNTIME.get_or_init(|| {
+        tokio::runtime::Builder::new_multi_thread()
+            .enable_all()
+            .thread_name("microsandbox-rb")
+            .build()
+            .expect("microsandbox: failed to build tokio runtime")
+    })
+}
+
+/// Run `f` with the Ruby GVL released.
+///
+/// `f` runs on the *same* OS thread (the C call blocks until it returns), so no
+/// `Send`/`'static` bound is required. `f` MUST NOT touch the Ruby C API while
+/// the GVL is released. Panics are caught and re-raised after the GVL is
+/// re-acquired, because unwinding across the C frame would be undefined
+/// behaviour.
+pub fn nogvl<F, R>(f: F) -> R
+where
+    F: FnOnce() -> R,
+{
+    struct State<F, R> {
+        f: Option<F>,
+        out: Option<std::thread::Result<R>>,
+    }
+
+    unsafe extern "C" fn call<F, R>(arg: *mut c_void) -> *mut c_void
+    where
+        F: FnOnce() -> R,
+    {
+        // SAFETY: `arg` points to the `State` on the caller's stack, which
+        // outlives this call (rb_thread_call_without_gvl blocks until return).
+        let state = unsafe { &mut *(arg as *mut State<F, R>) };
+        let f = state.f.take().expect("nogvl callback invoked twice");
+        state.out = Some(catch_unwind(AssertUnwindSafe(f)));
+        std::ptr::null_mut()
+    }
+
+    let mut state: State<F, R> = State {
+        f: Some(f),
+        out: None,
+    };
+
+    unsafe {
+        rb_sys::rb_thread_call_without_gvl(
+            Some(call::<F, R>),
+            &mut state as *mut _ as *mut c_void,
+            None,
+            std::ptr::null_mut(),
+        );
+    }
+
+    match state.out.take() {
+        Some(Ok(value)) => value,
+        Some(Err(panic)) => std::panic::resume_unwind(panic),
+        None => unreachable!("nogvl callback did not run"),
+    }
+}
+
+/// Drive a future to completion on the shared runtime with the GVL released.
+pub fn block_on<F>(fut: F) -> F::Output
+where
+    F: Future,
+{
+    nogvl(|| runtime().block_on(fut))
+}