microsandbox-rb 0.6.0 → 0.7.0

data/ext/microsandbox/src/snapshot.rs

@@ -5,7 +5,7 @@
 //! 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 std::path::{Path, PathBuf};
 
 use magnus::{function, prelude::*, Error, RArray, RHash, RModule, Ruby};
 use microsandbox::snapshot::{
@@ -24,6 +24,38 @@ fn format_str(format: SnapshotFormat) -> &'static str {
     }
 }
 
+/// Parse a manifest's RFC 3339 `created_at` into epoch-ms (nil if unparseable).
+fn created_at_ms(rfc3339: &str) -> Option<i64> {
+    chrono::DateTime::parse_from_rfc3339(rfc3339)
+        .ok()
+        .map(|dt| dt.timestamp_millis())
+}
+
+/// Convert a fully-opened `Snapshot` into the `SnapshotInfo` Hash. Unlike a
+/// `SnapshotHandle` (a lightweight index row), an opened snapshot carries the
+/// full manifest, so this is the richest shape — `create`/`open`/`list_dir`
+/// and the `SandboxHandle#snapshot`/`#snapshot_to` shortcuts all funnel here.
+pub(crate) fn snapshot_to_hash(snap: &Snapshot) -> RHash {
+    let m = snap.manifest();
+    let hash = ruby().hash_new();
+    let _ = hash.aset("digest", snap.digest().to_string());
+    let _ = hash.aset("path", snap.path().to_string_lossy().into_owned());
+    let _ = hash.aset("size_bytes", snap.size_bytes());
+    let _ = hash.aset("image_ref", m.image.reference.clone());
+    let _ = hash.aset("image_manifest_digest", m.image.manifest_digest.clone());
+    let _ = hash.aset("format", format_str(m.format));
+    let _ = hash.aset("fstype", m.fstype.clone());
+    let _ = hash.aset("parent_digest", m.parent.clone());
+    let _ = hash.aset("created_at_ms", created_at_ms(&m.created_at));
+    let _ = hash.aset("source_sandbox", m.source_sandbox.clone());
+    let labels = ruby().hash_new();
+    for (k, v) in &m.labels {
+        let _ = labels.aset(k.as_str(), v.as_str());
+    }
+    let _ = hash.aset("labels", labels);
+    hash
+}
+
 /// 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> {
@@ -48,11 +80,42 @@ fn create(source_sandbox: String, opts: RHash) -> Result<RHash, Error> {
     }
 
     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)
+    Ok(snapshot_to_hash(&snap))
+}
+
+/// Open an existing snapshot artifact by bare name or path. Cheap metadata
+/// validation only (does not read the upper file). Returns a full SnapshotInfo
+/// Hash — the only way to inspect an artifact addressed by path (`get`/`list`
+/// read the local index, which path-addressed artifacts are absent from).
+fn open(path_or_name: String) -> Result<RHash, Error> {
+    let snap = block_on(Snapshot::open(&path_or_name)).map_err(error::to_ruby)?;
+    Ok(snapshot_to_hash(&snap))
+}
+
+/// Walk `dir` and parse each subdirectory's `manifest.json` without touching the
+/// local index — for enumerating external/un-imported snapshot collections.
+fn list_dir(dir: String) -> Result<RArray, Error> {
+    let snaps = block_on(Snapshot::list_dir(Path::new(&dir))).map_err(error::to_ruby)?;
+    let arr = ruby().ary_new();
+    for snap in &snaps {
+        arr.push(snapshot_to_hash(snap))?;
+    }
+    Ok(arr)
+}
+
+/// Rebuild the local snapshot index from `dir` (defaults to the configured
+/// snapshots directory). Returns the number of indexed snapshots — the repair
+/// for index drift or out-of-band imports that `get`/`list` can't see.
+fn reindex(dir: Option<String>) -> Result<u64, Error> {
+    let dir: PathBuf = match dir {
+        Some(d) => PathBuf::from(d),
+        None => microsandbox::default_backend()
+            .as_local()
+            .map(|l| l.snapshots_dir())
+            .unwrap_or_else(|| PathBuf::from(".")),
+    };
+    let n = block_on(Snapshot::reindex(&dir)).map_err(error::to_ruby)?;
+    Ok(n as u64)
 }
 
 /// Metadata for one snapshot by name or digest.
@@ -148,8 +211,11 @@ fn verify_report_to_hash(report: &SnapshotVerifyReport) -> RHash {
 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("open", function!(open, 1))?;
     class.define_singleton_method("get", function!(get, 1))?;
     class.define_singleton_method("list", function!(list, 0))?;
+    class.define_singleton_method("list_dir", function!(list_dir, 1))?;
+    class.define_singleton_method("reindex", function!(reindex, 1))?;
     class.define_singleton_method("remove", function!(remove, 2))?;
     class.define_singleton_method("verify", function!(verify, 1))?;
     class.define_singleton_method("export", function!(export, 3))?;

data/ext/microsandbox/src/volume.rs

@@ -3,12 +3,17 @@
 //! 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 std::sync::Arc;
+
+use magnus::{function, method, prelude::*, Error, RArray, RHash, RModule, RString, Ruby};
 use microsandbox::volume::VolumeHandle;
+use microsandbox::Backend;
 
+use crate::backend::local_backend;
 use crate::conv;
 use crate::error;
 use crate::runtime::{block_on, ruby};
+use crate::sandbox::{fs_entry_to_hash, fs_metadata_to_hash};
 
 fn handle_to_hash(h: &VolumeHandle) -> RHash {
     let hash = ruby().hash_new();
@@ -92,11 +97,118 @@ fn remove(name: String) -> Result<(), Error> {
     block_on(microsandbox::Volume::remove(&name)).map_err(error::to_ruby)
 }
 
+/// A host-side filesystem view over a named volume — read/write its contents
+/// without a running sandbox. Mirrors the Python `VolumeFs` / Node `VolumeFs`.
+/// The core `VolumeFs<'a>` borrows the volume name, so (like the Python binding)
+/// each operation rebuilds it from the stored backend + name.
+#[magnus::wrap(class = "Microsandbox::Native::VolumeFs", free_immediately, size)]
+pub struct VolumeFs {
+    backend: Arc<dyn Backend>,
+    name: String,
+}
+
+impl VolumeFs {
+    /// Resolve the (local) backend once and bind it to `name`.
+    fn for_volume(name: String) -> Result<VolumeFs, Error> {
+        Ok(VolumeFs {
+            backend: local_backend().map_err(error::to_ruby)?,
+            name,
+        })
+    }
+
+    fn fs(&self) -> microsandbox::volume::VolumeFs<'_> {
+        microsandbox::volume::VolumeFs::with_backend(self.backend.clone(), &self.name)
+    }
+
+    fn read(&self, path: String) -> Result<RString, Error> {
+        let fs = self.fs();
+        let bytes = block_on(fs.read(&path)).map_err(error::to_ruby)?;
+        Ok(ruby().str_from_slice(bytes.as_ref()))
+    }
+
+    fn read_text(&self, path: String) -> Result<String, Error> {
+        let fs = self.fs();
+        block_on(fs.read_to_string(&path)).map_err(error::to_ruby)
+    }
+
+    fn write(&self, path: String, data: RString) -> Result<(), Error> {
+        // Copy the bytes out while the GVL is held (GC.compact could move them).
+        let bytes = unsafe { data.as_slice() }.to_vec();
+        let fs = self.fs();
+        block_on(fs.write(&path, &bytes)).map_err(error::to_ruby)
+    }
+
+    fn list(&self, path: String) -> Result<RArray, Error> {
+        let fs = self.fs();
+        let entries = block_on(fs.list(&path)).map_err(error::to_ruby)?;
+        let arr = ruby().ary_new();
+        for entry in &entries {
+            arr.push(fs_entry_to_hash(entry))?;
+        }
+        Ok(arr)
+    }
+
+    fn mkdir(&self, path: String) -> Result<(), Error> {
+        let fs = self.fs();
+        block_on(fs.mkdir(&path)).map_err(error::to_ruby)
+    }
+
+    fn remove_file(&self, path: String) -> Result<(), Error> {
+        let fs = self.fs();
+        block_on(fs.remove(&path)).map_err(error::to_ruby)
+    }
+
+    fn remove_dir(&self, path: String) -> Result<(), Error> {
+        let fs = self.fs();
+        block_on(fs.remove_dir(&path)).map_err(error::to_ruby)
+    }
+
+    fn exists(&self, path: String) -> Result<bool, Error> {
+        let fs = self.fs();
+        block_on(fs.exists(&path)).map_err(error::to_ruby)
+    }
+
+    fn copy(&self, from: String, to: String) -> Result<(), Error> {
+        let fs = self.fs();
+        block_on(fs.copy(&from, &to)).map_err(error::to_ruby)
+    }
+
+    fn rename(&self, from: String, to: String) -> Result<(), Error> {
+        let fs = self.fs();
+        block_on(fs.rename(&from, &to)).map_err(error::to_ruby)
+    }
+
+    fn stat(&self, path: String) -> Result<RHash, Error> {
+        let fs = self.fs();
+        let meta = block_on(fs.stat(&path)).map_err(error::to_ruby)?;
+        Ok(fs_metadata_to_hash(&meta))
+    }
+}
+
+/// Open a host-side filesystem view over a named volume.
+fn fs(name: String) -> Result<VolumeFs, Error> {
+    VolumeFs::for_volume(name)
+}
+
 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))?;
+    class.define_singleton_method("fs", function!(fs, 1))?;
+
+    let vfs = native.define_class("VolumeFs", ruby.class_object())?;
+    vfs.define_method("read", method!(VolumeFs::read, 1))?;
+    vfs.define_method("read_text", method!(VolumeFs::read_text, 1))?;
+    vfs.define_method("write", method!(VolumeFs::write, 2))?;
+    vfs.define_method("list", method!(VolumeFs::list, 1))?;
+    vfs.define_method("mkdir", method!(VolumeFs::mkdir, 1))?;
+    vfs.define_method("remove_file", method!(VolumeFs::remove_file, 1))?;
+    vfs.define_method("remove_dir", method!(VolumeFs::remove_dir, 1))?;
+    vfs.define_method("exists", method!(VolumeFs::exists, 1))?;
+    vfs.define_method("copy", method!(VolumeFs::copy, 2))?;
+    vfs.define_method("rename", method!(VolumeFs::rename, 2))?;
+    vfs.define_method("stat", method!(VolumeFs::stat, 1))?;
     Ok(())
 }

data/lib/microsandbox/agent.rb

@@ -100,7 +100,9 @@ module Microsandbox
       # Connect to a running sandbox by name (max 128 UTF-8 bytes). With a block,
       # the client is yielded and closed when the block returns.
       # @param name [String]
-      # @param timeout [Numeric, nil] handshake timeout in seconds (default ~10s)
+      # @param timeout [Numeric, nil] handshake timeout in seconds. nil (the
+      #   default) uses the core default (~10s); 0 fails fast (an immediate
+      #   deadline); a negative or non-finite value raises {Error}.
       # @yieldparam client [AgentClient]
       # @return [AgentClient, Object]
       def connect_sandbox(name, timeout: nil, &block)

data/lib/microsandbox/exec_handle.rb

@@ -20,9 +20,10 @@ module Microsandbox
       @data = event["data"]
     end
 
-    # @return [String, nil] {#data} decoded as UTF-8 (lenient)
+    # @return [String, nil] {#data} decoded as UTF-8 (lossy — invalid byte
+    #   sequences are replaced with U+FFFD, so the result is always valid UTF-8)
     def text
-      @data&.dup&.force_encoding(Encoding::UTF_8)
+      @data&.dup&.force_encoding(Encoding::UTF_8)&.scrub
     end
 
     def started? = @type == :started
@@ -62,9 +63,12 @@ module Microsandbox
     end
 
     # Write data to the process stdin.
+    # @param data [String] raw bytes to write (binary-safe)
+    # @raise [TypeError] if +data+ is not a String
     # @return [self]
     def write(data)
-      @native.write(data.to_s)
+      bytes = Microsandbox.coerce_write_bytes(data)
+      @native.write(bytes)
       self
     end
 

data/lib/microsandbox/exec_output.rb

@@ -3,9 +3,9 @@
 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.
+  # `stdout`/`stderr` return the captured bytes decoded as UTF-8 (lossy —
+  # invalid byte sequences are replaced with U+FFFD, so the result is always
+  # 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
@@ -32,14 +32,14 @@ module Microsandbox
       !@success
     end
 
-    # @return [String] stdout decoded as UTF-8
+    # @return [String] stdout decoded as UTF-8 (lossy)
     def stdout
-      @stdout ||= @stdout_bytes.dup.force_encoding(Encoding::UTF_8)
+      @stdout ||= @stdout_bytes.dup.force_encoding(Encoding::UTF_8).scrub
     end
 
-    # @return [String] stderr decoded as UTF-8
+    # @return [String] stderr decoded as UTF-8 (lossy)
     def stderr
-      @stderr ||= @stderr_bytes.dup.force_encoding(Encoding::UTF_8)
+      @stderr ||= @stderr_bytes.dup.force_encoding(Encoding::UTF_8).scrub
     end
 
     # @return [String] stdout decoded as UTF-8 (alias for {#stdout})

data/lib/microsandbox/fs.rb

@@ -96,10 +96,14 @@ module Microsandbox
       @native.fs_read_text(path.to_s)
     end
 
-    # Write data (a String) to a file, creating or truncating it.
+    # Write data to a file, creating or truncating it.
+    # @param data [String] raw bytes to write (binary-safe; ASCII-8BIT is fine)
+    # @raise [TypeError] if +data+ is not a String (rather than silently writing
+    #   its +to_s+ form, e.g. the inspect string of a StringIO or "42")
     # @return [nil]
     def write(path, data)
-      @native.fs_write(path.to_s, data.to_s)
+      bytes = Microsandbox.coerce_write_bytes(data)
+      @native.fs_write(path.to_s, bytes)
       nil
     end
 
@@ -168,5 +172,83 @@ module Microsandbox
       @native.fs_copy_to_host(guest_path.to_s, host_path.to_s)
       nil
     end
+
+    # Open a streaming reader over a guest file — for files too large to read
+    # into memory at once (unlike {#read}, which buffers the whole file).
+    # @return [FsReadStream] an {Enumerable} of byte chunks (ASCII-8BIT)
+    def read_stream(path)
+      FsReadStream.new(@native.fs_read_stream(path.to_s))
+    end
+
+    # Open a streaming writer to a guest file. With a block, the sink is yielded
+    # and closed (flushed) when the block returns.
+    # @yieldparam sink [FsWriteSink]
+    # @return [FsWriteSink, Object]
+    def write_stream(path)
+      sink = FsWriteSink.new(@native.fs_write_stream(path.to_s))
+      return sink unless block_given?
+
+      begin
+        yield sink
+      ensure
+        sink.close
+      end
+    end
+  end
+
+  # A streaming reader over a guest file, from {FS#read_stream}. Iterate it (it
+  # is {Enumerable}) to consume byte chunks (ASCII-8BIT) as they arrive, or call
+  # {#read} to drain it into one String.
+  class FsReadStream
+    include Enumerable
+
+    def initialize(native)
+      @native = native
+    end
+
+    # Yield each chunk of bytes until the stream ends. Returns an Enumerator when
+    # called without a block.
+    # @yieldparam chunk [String] raw bytes (ASCII-8BIT)
+    # @return [self, Enumerator]
+    def each
+      return enum_for(:each) unless block_given?
+
+      while (chunk = @native.recv)
+        yield chunk
+      end
+      self
+    end
+
+    # Drain the stream into a single byte String.
+    # @return [String] raw bytes (ASCII-8BIT)
+    def read
+      buffer = +"".b
+      each { |chunk| buffer << chunk }
+      buffer
+    end
+  end
+
+  # A streaming writer to a guest file, from {FS#write_stream}.
+  class FsWriteSink
+    def initialize(native)
+      @native = native
+    end
+
+    # Write a chunk of bytes.
+    # @param data [String] raw bytes (binary-safe)
+    # @raise [TypeError] if +data+ is not a String
+    # @return [self]
+    def write(data)
+      bytes = Microsandbox.coerce_write_bytes(data)
+      @native.write(bytes)
+      self
+    end
+
+    # Flush and close the sink. Idempotent.
+    # @return [nil]
+    def close
+      @native.close
+      nil
+    end
   end
 end

data/lib/microsandbox/image.rb

@@ -35,7 +35,8 @@ module Microsandbox
   class ImageDetail
     # @return [ImageInfo]
     attr_reader :handle
-    # @return [Hash, nil] OCI config (digest, env, cmd, entrypoint, working_dir, user, stop_signal)
+    # @return [Hash, nil] OCI config (digest, env, cmd, entrypoint, working_dir,
+    #   user, labels, stop_signal). `labels` is a Hash (or nil) of OCI config labels.
     attr_reader :config
     # @return [Array<Hash>] layer descriptors
     attr_reader :layers

data/lib/microsandbox/log_entry.rb

@@ -25,9 +25,11 @@ module Microsandbox
       Time.at(@timestamp_ms / 1000.0)
     end
 
-    # @return [String] the captured bytes decoded as UTF-8 (lenient)
+    # @return [String] the captured bytes decoded as UTF-8 (lossy — invalid byte
+    #   sequences are replaced with U+FFFD, so the result is always valid UTF-8;
+    #   use {#data} for the raw ASCII-8BIT bytes)
     def text
-      @data.dup.force_encoding(Encoding::UTF_8)
+      @data.dup.force_encoding(Encoding::UTF_8).scrub
     end
 
     def inspect

data/lib/microsandbox/metrics.rb

@@ -24,6 +24,12 @@ module Microsandbox
     attr_reader :net_rx_bytes
     # @return [Integer] cumulative bytes transmitted over the network
     attr_reader :net_tx_bytes
+    # @return [Integer, nil] bytes used in the writable OCI upper layer
+    attr_reader :upper_used_bytes
+    # @return [Integer, nil] bytes free in the writable OCI upper layer
+    attr_reader :upper_free_bytes
+    # @return [Integer, nil] host bytes allocated to back the upper layer
+    attr_reader :upper_host_allocated_bytes
     # @return [Float] sandbox uptime in seconds
     attr_reader :uptime_secs
 
@@ -38,6 +44,9 @@ module Microsandbox
       @disk_write_bytes = data["disk_write_bytes"]
       @net_rx_bytes = data["net_rx_bytes"]
       @net_tx_bytes = data["net_tx_bytes"]
+      @upper_used_bytes = data["upper_used_bytes"]
+      @upper_free_bytes = data["upper_free_bytes"]
+      @upper_host_allocated_bytes = data["upper_host_allocated_bytes"]
       @uptime_secs = data["uptime_secs"]
       @timestamp_ms = data["timestamp_ms"]
     end