microsandbox-rb 0.5.7

data/ext/microsandbox/src/snapshot.rs

@@ -0,0 +1,158 @@
+//! Snapshot management: `Microsandbox::Native::Snapshot`.
+//!
+//! Snapshots capture a stopped sandbox's upper layer into a portable artifact
+//! that a later `Sandbox.create(from_snapshot:)` can boot from. Exposed as
+//! singleton functions returning plain Hashes/Arrays (shaped into value objects
+//! by the Ruby layer) — there is no long-lived handle to own.
+
+use std::path::PathBuf;
+
+use magnus::{function, prelude::*, Error, RArray, RHash, RModule, Ruby};
+use microsandbox::snapshot::{
+    ExportOpts, Snapshot, SnapshotDestination, SnapshotFormat, SnapshotHandle,
+    SnapshotVerifyReport, UpperVerifyStatus,
+};
+
+use crate::conv;
+use crate::error;
+use crate::runtime::{block_on, ruby};
+
+fn format_str(format: SnapshotFormat) -> &'static str {
+    match format {
+        SnapshotFormat::Raw => "raw",
+        SnapshotFormat::Qcow2 => "qcow2",
+    }
+}
+
+/// Create a snapshot of a stopped sandbox. `opts`: name | path (destination),
+/// labels, force, record_integrity. Returns {digest, path, size_bytes}.
+fn create(source_sandbox: String, opts: RHash) -> Result<RHash, Error> {
+    let mut b = Snapshot::builder(source_sandbox);
+    if let Some(name) = conv::opt_string(opts, "name")? {
+        b = b.destination(SnapshotDestination::Name(name));
+    } else if let Some(path) = conv::opt_string(opts, "path")? {
+        b = b.destination(SnapshotDestination::Path(PathBuf::from(path)));
+    } else {
+        return Err(error::base_error(
+            "snapshot create needs a destination: pass name: or path:",
+        ));
+    }
+    for (k, v) in conv::opt_string_map(opts, "labels")? {
+        b = b.label(k, v);
+    }
+    if conv::opt_bool(opts, "force")? {
+        b = b.force();
+    }
+    if conv::opt_bool(opts, "record_integrity")? {
+        b = b.record_integrity();
+    }
+
+    let snap = block_on(b.create()).map_err(error::to_ruby)?;
+    let hash = ruby().hash_new();
+    hash.aset("digest", snap.digest().to_string())?;
+    hash.aset("path", snap.path().to_string_lossy().into_owned())?;
+    hash.aset("size_bytes", snap.size_bytes())?;
+    Ok(hash)
+}
+
+/// Metadata for one snapshot by name or digest.
+fn get(name_or_digest: String) -> Result<RHash, Error> {
+    let handle = block_on(Snapshot::get(&name_or_digest)).map_err(error::to_ruby)?;
+    Ok(handle_to_hash(&handle))
+}
+
+/// All snapshots as metadata hashes.
+fn list() -> Result<RArray, Error> {
+    let handles = block_on(Snapshot::list()).map_err(error::to_ruby)?;
+    let arr = ruby().ary_new();
+    for h in &handles {
+        arr.push(handle_to_hash(h))?;
+    }
+    Ok(arr)
+}
+
+/// Remove a snapshot artifact by name or path.
+fn remove(name_or_path: String, force: bool) -> Result<(), Error> {
+    block_on(Snapshot::remove(&name_or_path, force)).map_err(error::to_ruby)
+}
+
+/// Verify a snapshot's recorded upper-layer integrity. Returns
+/// {digest, path, upper_status, upper_algorithm?, upper_digest?}.
+fn verify(name_or_path: String) -> Result<RHash, Error> {
+    let snap = block_on(Snapshot::open(&name_or_path)).map_err(error::to_ruby)?;
+    let report = block_on(snap.verify()).map_err(error::to_ruby)?;
+    Ok(verify_report_to_hash(&report))
+}
+
+/// Bundle a snapshot into a `.tar.zst` (or plain `.tar`) archive. `opts`:
+/// with_parents, with_image, plain_tar.
+fn export(name_or_path: String, out_path: String, opts: RHash) -> Result<(), Error> {
+    let export_opts = ExportOpts {
+        with_parents: conv::opt_bool(opts, "with_parents")?,
+        with_image: conv::opt_bool(opts, "with_image")?,
+        plain_tar: conv::opt_bool(opts, "plain_tar")?,
+    };
+    block_on(Snapshot::export(
+        &name_or_path,
+        std::path::Path::new(&out_path),
+        export_opts,
+    ))
+    .map_err(error::to_ruby)
+}
+
+/// Unpack a snapshot archive into the snapshots dir. Returns the imported
+/// snapshot's metadata hash. `dest` is an optional explicit directory.
+fn import(archive_path: String, dest: Option<String>) -> Result<RHash, Error> {
+    let dest_path = dest.map(PathBuf::from);
+    let handle = block_on(Snapshot::import(
+        std::path::Path::new(&archive_path),
+        dest_path.as_deref(),
+    ))
+    .map_err(error::to_ruby)?;
+    Ok(handle_to_hash(&handle))
+}
+
+fn handle_to_hash(handle: &SnapshotHandle) -> RHash {
+    let hash = ruby().hash_new();
+    let _ = hash.aset("digest", handle.digest().to_string());
+    let _ = hash.aset("name", handle.name().map(str::to_string));
+    let _ = hash.aset("parent_digest", handle.parent_digest().map(str::to_string));
+    let _ = hash.aset("image_ref", handle.image_ref().to_string());
+    let _ = hash.aset("format", format_str(handle.format()));
+    let _ = hash.aset("size_bytes", handle.size_bytes());
+    let _ = hash.aset("path", handle.path().to_string_lossy().into_owned());
+    let _ = hash.aset(
+        "created_at_ms",
+        handle.created_at().and_utc().timestamp_millis(),
+    );
+    hash
+}
+
+fn verify_report_to_hash(report: &SnapshotVerifyReport) -> RHash {
+    let hash = ruby().hash_new();
+    let _ = hash.aset("digest", report.digest.clone());
+    let _ = hash.aset("path", report.path.to_string_lossy().into_owned());
+    match &report.upper {
+        UpperVerifyStatus::NotRecorded => {
+            let _ = hash.aset("upper_status", "not_recorded");
+        }
+        UpperVerifyStatus::Verified { algorithm, digest } => {
+            let _ = hash.aset("upper_status", "verified");
+            let _ = hash.aset("upper_algorithm", algorithm.clone());
+            let _ = hash.aset("upper_digest", digest.clone());
+        }
+    }
+    hash
+}
+
+pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
+    let class = native.define_class("Snapshot", ruby.class_object())?;
+    class.define_singleton_method("create", function!(create, 2))?;
+    class.define_singleton_method("get", function!(get, 1))?;
+    class.define_singleton_method("list", function!(list, 0))?;
+    class.define_singleton_method("remove", function!(remove, 2))?;
+    class.define_singleton_method("verify", function!(verify, 1))?;
+    class.define_singleton_method("export", function!(export, 3))?;
+    class.define_singleton_method("import", function!(import, 2))?;
+    Ok(())
+}

data/ext/microsandbox/src/stream.rs

@@ -0,0 +1,86 @@
+//! Streaming logs and metrics: `Microsandbox::Native::LogStream` and
+//! `Microsandbox::Native::MetricsStream`.
+//!
+//! Mirrors the `ExecHandle` streaming pattern in `exec.rs`. The core
+//! `log_stream`/`metrics_stream` return `impl Stream`; we box+pin each into an
+//! `Arc<tokio::Mutex<…>>` and expose a synchronous `recv` that drives the next
+//! item to completion with the GVL released, returning a Ruby Hash (or `nil` at
+//! end of stream). The Ruby layer wraps each as an `Enumerable`.
+
+use std::pin::Pin;
+use std::sync::Arc;
+
+use futures::Stream;
+use magnus::{method, prelude::*, Error, RHash, RModule, Ruby};
+use microsandbox::logs::LogEntry;
+use microsandbox::sandbox::SandboxMetrics;
+use microsandbox::MicrosandboxResult;
+use tokio::sync::Mutex;
+
+use crate::error;
+use crate::runtime::block_on;
+use crate::sandbox::{log_entry_to_hash, metrics_to_hash};
+
+type BoxStream<T> = Pin<Box<dyn Stream<Item = MicrosandboxResult<T>> + Send>>;
+
+#[magnus::wrap(class = "Microsandbox::Native::LogStream", free_immediately, size)]
+pub struct LogStream {
+    inner: Arc<Mutex<BoxStream<LogEntry>>>,
+}
+
+impl LogStream {
+    pub fn from_stream(
+        stream: impl Stream<Item = MicrosandboxResult<LogEntry>> + Send + 'static,
+    ) -> Self {
+        Self {
+            inner: Arc::new(Mutex::new(Box::pin(stream))),
+        }
+    }
+
+    /// Next log entry as a Hash, or nil when the stream ends.
+    fn recv(&self) -> Result<Option<RHash>, Error> {
+        use futures::StreamExt;
+        let inner = Arc::clone(&self.inner);
+        match block_on(async move { inner.lock().await.next().await }) {
+            Some(Ok(entry)) => Ok(Some(log_entry_to_hash(&entry))),
+            Some(Err(e)) => Err(error::to_ruby(e)),
+            None => Ok(None),
+        }
+    }
+}
+
+#[magnus::wrap(class = "Microsandbox::Native::MetricsStream", free_immediately, size)]
+pub struct MetricsStream {
+    inner: Arc<Mutex<BoxStream<SandboxMetrics>>>,
+}
+
+impl MetricsStream {
+    pub fn from_stream(
+        stream: impl Stream<Item = MicrosandboxResult<SandboxMetrics>> + Send + 'static,
+    ) -> Self {
+        Self {
+            inner: Arc::new(Mutex::new(Box::pin(stream))),
+        }
+    }
+
+    /// Next metrics snapshot as a Hash, or nil when the stream ends.
+    fn recv(&self) -> Result<Option<RHash>, Error> {
+        use futures::StreamExt;
+        let inner = Arc::clone(&self.inner);
+        match block_on(async move { inner.lock().await.next().await }) {
+            Some(Ok(metrics)) => Ok(Some(metrics_to_hash(&metrics))),
+            Some(Err(e)) => Err(error::to_ruby(e)),
+            None => Ok(None),
+        }
+    }
+}
+
+pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
+    let logs = native.define_class("LogStream", ruby.class_object())?;
+    logs.define_method("recv", method!(LogStream::recv, 0))?;
+
+    let metrics = native.define_class("MetricsStream", ruby.class_object())?;
+    metrics.define_method("recv", method!(MetricsStream::recv, 0))?;
+
+    Ok(())
+}

data/ext/microsandbox/src/volume.rs

@@ -0,0 +1,97 @@
+//! Named persistent volume management: `Microsandbox::Native::Volume`.
+//!
+//! Mirrors `sdk/python/src/volume.rs`. Static async CRUD over the volume store;
+//! results are returned as plain Ruby Hashes/Arrays.
+
+use magnus::{function, prelude::*, Error, RArray, RHash, RModule, Ruby};
+use microsandbox::volume::VolumeHandle;
+
+use crate::conv;
+use crate::error;
+use crate::runtime::{block_on, ruby};
+
+fn handle_to_hash(h: &VolumeHandle) -> RHash {
+    let hash = ruby().hash_new();
+    let _ = hash.aset("name", h.name().to_string());
+    let _ = hash.aset("kind", h.kind().as_str().to_string());
+    let _ = hash.aset("quota_mib", h.quota_mib());
+    let _ = hash.aset("used_bytes", h.used_bytes());
+    let _ = hash.aset("capacity_bytes", h.capacity_bytes());
+    let _ = hash.aset("disk_format", h.disk_format().map(str::to_string));
+    let _ = hash.aset("disk_fstype", h.disk_fstype().map(str::to_string));
+    let _ = hash.aset(
+        "created_at_ms",
+        h.created_at().map(|dt| dt.timestamp_millis()),
+    );
+    let labels = ruby().hash_new();
+    for (k, v) in h.labels().iter() {
+        let _ = labels.aset(k.clone(), v.clone());
+    }
+    let _ = hash.aset("labels", labels);
+    hash
+}
+
+/// Create a named volume. `opts`: kind ("dir"|"disk"), size_mib, quota_mib, labels.
+fn create(name: String, opts: RHash) -> Result<RHash, Error> {
+    let mut builder = microsandbox::Volume::builder(&name);
+    let kind = conv::opt_string(opts, "kind")?.unwrap_or_else(|| "dir".to_string());
+    let size_mib = conv::opt_u32(opts, "size_mib")?;
+
+    match kind.as_str() {
+        "dir" => {
+            builder = builder.directory();
+            if size_mib.is_some() {
+                return Err(error::base_error(
+                    "size_mib is only supported with kind: \"disk\"",
+                ));
+            }
+        }
+        "disk" => {
+            builder = builder.disk();
+            let size = size_mib
+                .ok_or_else(|| error::base_error("size_mib is required with kind: \"disk\""))?;
+            builder = builder.size(size);
+        }
+        other => return Err(error::base_error(format!("unknown volume kind: {other:?}"))),
+    }
+
+    if let Some(quota) = conv::opt_u32(opts, "quota_mib")? {
+        builder = builder.quota(quota);
+    }
+    for (k, v) in conv::opt_string_map(opts, "labels")? {
+        builder = builder.label(k, v);
+    }
+
+    let vol = block_on(builder.create()).map_err(error::to_ruby)?;
+    let hash = ruby().hash_new();
+    hash.aset("name", vol.name().to_string())?;
+    hash.aset("path", vol.path().display().to_string())?;
+    Ok(hash)
+}
+
+fn get(name: String) -> Result<RHash, Error> {
+    let handle = block_on(microsandbox::Volume::get(&name)).map_err(error::to_ruby)?;
+    Ok(handle_to_hash(&handle))
+}
+
+fn list() -> Result<RArray, Error> {
+    let handles = block_on(microsandbox::Volume::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 remove(name: String) -> Result<(), Error> {
+    block_on(microsandbox::Volume::remove(&name)).map_err(error::to_ruby)
+}
+
+pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
+    let class = native.define_class("Volume", ruby.class_object())?;
+    class.define_singleton_method("create", function!(create, 2))?;
+    class.define_singleton_method("get", function!(get, 1))?;
+    class.define_singleton_method("list", function!(list, 0))?;
+    class.define_singleton_method("remove", function!(remove, 1))?;
+    Ok(())
+}

data/lib/microsandbox/errors.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # Base class for every error raised by the SDK. Mirrors the Python SDK's
+  # flat hierarchy (`sdk/python/microsandbox/errors.py`): each class carries a
+  # stable `#code`. The native layer raises the matching subclass based on the
+  # core `MicrosandboxError` variant; unmapped variants surface as `Error`.
+  class Error < StandardError
+    CODE = "microsandbox-error"
+
+    # The stable, machine-readable error code for this class.
+    def self.code
+      const_get(:CODE)
+    end
+
+    # The stable, machine-readable error code for this instance.
+    def code
+      self.class.code
+    end
+  end
+
+  # Defines `Microsandbox::<name>` as a subclass of `parent` carrying `code`.
+  def self.define_error(name, code, parent = Error)
+    klass = Class.new(parent)
+    klass.const_set(:CODE, code)
+    const_set(name, klass)
+  end
+  private_class_method :define_error
+
+  # Configuration / validation errors --------------------------------------
+  define_error(:InvalidConfigError, "invalid-config")
+
+  # Lifecycle errors --------------------------------------------------------
+  define_error(:SandboxNotFoundError, "sandbox-not-found")
+  define_error(:SandboxNotRunningError, "sandbox-not-running")
+  define_error(:SandboxAlreadyExistsError, "sandbox-already-exists")
+  define_error(:SandboxStillRunningError, "sandbox-still-running")
+
+  # Execution errors --------------------------------------------------------
+  define_error(:ExecTimeoutError, "exec-timeout")
+  define_error(:ExecFailedError, "exec-failed")
+
+  # Filesystem errors -------------------------------------------------------
+  define_error(:FilesystemError, "filesystem-error")
+  define_error(:PathNotFoundError, "path-not-found")
+
+  # Volume / image errors ---------------------------------------------------
+  define_error(:VolumeNotFoundError, "volume-not-found")
+  define_error(:VolumeAlreadyExistsError, "volume-already-exists")
+  define_error(:ImageNotFoundError, "image-not-found")
+  define_error(:ImageInUseError, "image-in-use")
+  define_error(:ImagePullFailedError, "image-pull-failed")
+
+  # Networking / secrets errors ---------------------------------------------
+  define_error(:NetworkPolicyError, "network-policy-error")
+  define_error(:SecretViolationError, "secret-violation")
+  define_error(:TlsError, "tls-error")
+
+  # I/O ---------------------------------------------------------------------
+  define_error(:IoError, "io-error")
+
+  # Metrics errors ----------------------------------------------------------
+  define_error(:MetricsDisabledError, "metrics-disabled")
+  define_error(:MetricsUnavailableError, "metrics-unavailable")
+
+  # Runtime compatibility ---------------------------------------------------
+  define_error(:UnsupportedOperationError, "unsupported-operation")
+end

data/lib/microsandbox/exec_handle.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # A single event from a streaming execution ({Sandbox#exec_stream}).
+  class ExecEvent
+    # @return [Symbol] :started, :stdout, :stderr, :exited, :failed, or :stdin_error
+    attr_reader :type
+    # @return [Integer, nil] pid (for :started)
+    attr_reader :pid
+    # @return [Integer, nil] exit code (:exited) or errno (:failed/:stdin_error)
+    attr_reader :code
+    # @return [String, nil] raw bytes (ASCII-8BIT) for :stdout/:stderr, or the
+    #   message for :failed/:stdin_error
+    attr_reader :data
+
+    def initialize(event)
+      @type = event["type"].to_sym
+      @pid = event["pid"]
+      @code = event["code"]
+      @data = event["data"]
+    end
+
+    # @return [String, nil] {#data} decoded as UTF-8 (lenient)
+    def text
+      @data && @data.dup.force_encoding(Encoding::UTF_8)
+    end
+
+    def started?      = @type == :started
+    def stdout?       = @type == :stdout
+    def stderr?       = @type == :stderr
+    def exited?       = @type == :exited
+    def failed?       = @type == :failed
+    def stdin_error?  = @type == :stdin_error
+
+    def inspect
+      "#<Microsandbox::ExecEvent type=#{@type}#{@pid ? " pid=#{@pid}" : ""}" \
+        "#{@code ? " code=#{@code}" : ""}#{@data ? " data=#{@data.bytesize}B" : ""}>"
+    end
+  end
+
+  # The terminal status of a streamed execution, from {ExecHandle#wait}.
+  class ExitStatus
+    # @return [Integer]
+    attr_reader :exit_code
+
+    def initialize(data)
+      @exit_code = data["exit_code"]
+      @success = data["success"]
+    end
+
+    def success? = @success
+    def failure? = !@success
+  end
+
+  # A writer for a streamed process's stdin, from {ExecHandle#stdin}.
+  class ExecStdin
+    def initialize(native)
+      @native = native
+    end
+
+    # Write data to the process stdin.
+    # @return [self]
+    def write(data)
+      @native.write(data.to_s)
+      self
+    end
+
+    # Send EOF.
+    # @return [nil]
+    def close
+      @native.close
+      nil
+    end
+  end
+
+  # A live, streaming command execution, returned by {Sandbox#exec_stream} and
+  # {Sandbox#shell_stream}.
+  #
+  # Iterate it (it is {Enumerable}) to consume {ExecEvent}s as they arrive, or
+  # call {#collect} to drain it into an {ExecOutput}.
+  #
+  # @example
+  #   handle = sb.exec_stream("python", ["-u", "script.py"])
+  #   handle.each do |event|
+  #     print event.text if event.stdout? || event.stderr?
+  #   end
+  class ExecHandle
+    include Enumerable
+
+    def initialize(native)
+      @native = native
+    end
+
+    # @return [String] the correlation id for this execution
+    def id
+      @native.id
+    end
+
+    # Yield each {ExecEvent} until the stream ends. Returns an Enumerator when
+    # called without a block.
+    # @yieldparam event [ExecEvent]
+    # @return [self, Enumerator]
+    def each
+      return enum_for(:each) unless block_given?
+
+      while (event = @native.recv)
+        yield ExecEvent.new(event)
+      end
+      self
+    end
+
+    # Block until the process exits.
+    # @return [ExitStatus]
+    def wait
+      ExitStatus.new(@native.wait)
+    end
+
+    # Drain the stream and collect all output.
+    # @return [ExecOutput]
+    def collect
+      ExecOutput.new(@native.collect)
+    end
+
+    # Send a signal (integer) to the running process.
+    # @return [nil]
+    def signal(sig)
+      @native.signal(Integer(sig))
+      nil
+    end
+
+    # Kill the running process (SIGKILL).
+    # @return [nil]
+    def kill
+      @native.kill
+      nil
+    end
+
+    # Resize the pseudo-terminal (only meaningful when started with tty: true).
+    # @return [nil]
+    def resize(rows, cols)
+      @native.resize(Integer(rows), Integer(cols))
+      nil
+    end
+
+    # The stdin writer, or nil if stdin was not piped. Returned only once.
+    # @return [ExecStdin, nil]
+    def stdin
+      return @stdin if defined?(@stdin)
+
+      native_sink = @native.take_stdin
+      @stdin = native_sink && ExecStdin.new(native_sink)
+    end
+  end
+end

data/lib/microsandbox/exec_output.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # The result of a completed `exec`/`shell` call.
+  #
+  # `stdout`/`stderr` return the captured bytes decoded as UTF-8 (lenient — the
+  # bytes are preserved even if they are not valid UTF-8); use `stdout_bytes`/
+  # `stderr_bytes` for the raw ASCII-8BIT bytes.
+  class ExecOutput
+    # @return [Integer] the process exit code
+    attr_reader :exit_code
+    # @return [String] raw stdout bytes (ASCII-8BIT)
+    attr_reader :stdout_bytes
+    # @return [String] raw stderr bytes (ASCII-8BIT)
+    attr_reader :stderr_bytes
+
+    # @param data [Hash] the native exec result hash
+    def initialize(data)
+      @exit_code = data["exit_code"]
+      @success = data["success"]
+      @stdout_bytes = data["stdout"]
+      @stderr_bytes = data["stderr"]
+    end
+
+    # @return [Boolean] whether the process exited with status 0
+    def success?
+      @success
+    end
+
+    # @return [Boolean] whether the process exited non-zero
+    def failure?
+      !@success
+    end
+
+    # @return [String] stdout decoded as UTF-8
+    def stdout
+      @stdout ||= @stdout_bytes.dup.force_encoding(Encoding::UTF_8)
+    end
+
+    # @return [String] stderr decoded as UTF-8
+    def stderr
+      @stderr ||= @stderr_bytes.dup.force_encoding(Encoding::UTF_8)
+    end
+
+    # @return [String] stdout decoded as UTF-8 (alias for {#stdout})
+    def to_s
+      stdout
+    end
+
+    def inspect
+      "#<Microsandbox::ExecOutput exit_code=#{@exit_code} success=#{@success} " \
+        "stdout=#{stdout.bytesize}B stderr=#{stderr.bytesize}B>"
+    end
+  end
+end