microsandbox-rb 0.6.0 → 0.7.0

data/lib/microsandbox/snapshot.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
 module Microsandbox
-  # Metadata for a snapshot artifact, returned by {Snapshot.create}/{Snapshot.get}/
-  # {Snapshot.list}/{Snapshot.import}.
+  # Metadata for a snapshot artifact, returned by {Snapshot.create}/{Snapshot.open}/
+  # {Snapshot.get}/{Snapshot.list}/{Snapshot.list_dir}/{Snapshot.import}.
   #
-  # `digest` and `path` are always present. `create` additionally populates
-  # `size_bytes`; `get`/`list`/`import` additionally populate `name`,
-  # `parent_digest`, `image_ref`, `format`, and `created_at`.
+  # `digest` and `path` are always present. The artifact-opening paths
+  # (`create`/`open`/`list_dir`, and {SandboxHandle#snapshot}) carry the full
+  # manifest — `size_bytes`, `image_ref`, `image_manifest_digest`, `format`,
+  # `fstype`, `parent_digest`, `created_at`, `source_sandbox`, and `labels`. The
+  # index paths (`get`/`list`/`import`) populate `name`, `parent_digest`,
+  # `image_ref`, `format`, `size_bytes`, and `created_at` (manifest-only fields
+  # such as `fstype`/`source_sandbox`/`labels` are nil/empty there).
   class SnapshotInfo
     # @return [String] manifest digest ("sha256:…") — the canonical identity
     attr_reader :digest
@@ -18,6 +22,14 @@ module Microsandbox
     attr_reader :parent_digest
     # @return [String, nil] source OCI image reference
     attr_reader :image_ref
+    # @return [String, nil] OCI manifest digest of the pinned image (manifest paths)
+    attr_reader :image_manifest_digest
+    # @return [String, nil] upper-layer filesystem type, e.g. "ext4" (manifest paths)
+    attr_reader :fstype
+    # @return [String, nil] best-effort source-sandbox name, if recorded
+    attr_reader :source_sandbox
+    # @return [Hash{String=>String}] user labels ({} for index-only entries)
+    attr_reader :labels
     # @return [Integer, nil] artifact size in bytes
     attr_reader :size_bytes
 
@@ -27,6 +39,10 @@ module Microsandbox
       @name = data["name"]
       @parent_digest = data["parent_digest"]
       @image_ref = data["image_ref"]
+      @image_manifest_digest = data["image_manifest_digest"]
+      @fstype = data["fstype"]
+      @source_sandbox = data["source_sandbox"]
+      @labels = data["labels"] || {}
       @format = data["format"]
       @size_bytes = data["size_bytes"]
       @created_at_ms = data["created_at_ms"]
@@ -42,6 +58,21 @@ module Microsandbox
       @created_at_ms && Time.at(@created_at_ms / 1000.0)
     end
 
+    # Re-open this snapshot's artifact (cheap metadata validation), returning a
+    # fully-populated {SnapshotInfo}. Addresses by path, so it works even for
+    # artifacts that were never added to the local index.
+    # @return [SnapshotInfo]
+    def open
+      Snapshot.open(@path || @digest)
+    end
+
+    # Remove this snapshot's artifact and its index row.
+    # @param force [Boolean] remove even if it has indexed children
+    # @return [nil]
+    def remove(force: false)
+      Snapshot.remove(@path || @digest, force: force)
+    end
+
     def inspect
       "#<Microsandbox::SnapshotInfo digest=#{@digest.inspect}#{" name=#{@name.inspect}" if @name}>"
     end
@@ -98,18 +129,44 @@ module Microsandbox
         SnapshotInfo.new(Native::Snapshot.create(source_sandbox.to_s, opts))
       end
 
+      # Open a snapshot artifact by bare name or path (cheap metadata
+      # validation; does not read the upper layer). Unlike {get}, this also
+      # works for artifacts addressed by path that were never indexed, and it
+      # returns the full manifest.
+      # @return [SnapshotInfo]
+      def open(name_or_path)
+        SnapshotInfo.new(Native::Snapshot.open(name_or_path.to_s))
+      end
+
       # Metadata for a snapshot by name or digest.
       # @return [SnapshotInfo]
       def get(name_or_digest)
         SnapshotInfo.new(Native::Snapshot.get(name_or_digest.to_s))
       end
 
-      # All snapshots.
+      # All snapshots indexed in the local cache.
       # @return [Array<SnapshotInfo>]
       def list
         Native::Snapshot.list.map { |info| SnapshotInfo.new(info) }
       end
 
+      # Enumerate snapshot artifacts under a directory by parsing each
+      # subdirectory's `manifest.json`, without touching the local index — for
+      # inspecting external/un-imported collections (e.g. a mounted volume).
+      # @return [Array<SnapshotInfo>]
+      def list_dir(dir)
+        Native::Snapshot.list_dir(dir.to_s).map { |info| SnapshotInfo.new(info) }
+      end
+
+      # Rebuild the local snapshot index from a directory (defaults to the
+      # configured snapshots dir). The repair for index drift or out-of-band
+      # imports that {list}/{get} can't otherwise see.
+      # @param dir [String, nil]
+      # @return [Integer] number of indexed snapshots
+      def reindex(dir = nil)
+        Native::Snapshot.reindex(dir&.to_s)
+      end
+
       # Remove a snapshot artifact by name or path.
       # @param force [Boolean] remove even if referenced
       # @return [nil]

data/lib/microsandbox/ssh.rb

@@ -2,8 +2,9 @@
 
 module Microsandbox
   # The result of an {SshClient#exec} call. Like {ExecOutput}, `stdout`/`stderr`
-  # are the captured bytes decoded as UTF-8 (lenient); use `stdout_bytes`/
-  # `stderr_bytes` for the raw ASCII-8BIT bytes.
+  # are the captured bytes decoded as UTF-8 (lossy — invalid byte sequences are
+  # replaced with U+FFFD); use `stdout_bytes`/`stderr_bytes` for the raw
+  # ASCII-8BIT bytes.
   class SshOutput
     # @return [Integer] the remote command's exit status
     attr_reader :status
@@ -25,14 +26,14 @@ module Microsandbox
     # @return [Boolean] whether the command exited non-zero
     def failure? = !@success
 
-    # @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
 
     def to_s = stdout
@@ -56,16 +57,20 @@ module Microsandbox
       @native.read(path.to_s)
     end
 
-    # Read a file and decode it as UTF-8 (lenient).
+    # Read a file and decode it as UTF-8 (lossy — invalid byte sequences are
+    # replaced with U+FFFD).
     # @return [String]
     def read_text(path)
-      read(path).force_encoding(Encoding::UTF_8)
+      read(path).force_encoding(Encoding::UTF_8).scrub
     end
 
     # Write a file, creating or truncating it.
+    # @param data [String] raw bytes to write (binary-safe)
+    # @raise [TypeError] if +data+ is not a String
     # @return [nil]
     def write(path, data)
-      @native.write(path.to_s, data.to_s)
+      bytes = Microsandbox.coerce_write_bytes(data)
+      @native.write(path.to_s, bytes)
       nil
     end
 

data/lib/microsandbox/version.rb

@@ -8,7 +8,7 @@ module Microsandbox
   # Versioning section of the README for the full gem-to-runtime map. Must equal
   # the native ext's Cargo crate version (`Native.version`), enforced by
   # spec/unit/version_spec.rb.
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 
   # The upstream microsandbox runtime release this gem build embeds — the `tag`
   # pinned on the `microsandbox`/`microsandbox-network` git deps in

data/lib/microsandbox/volume.rb

@@ -22,7 +22,8 @@ module Microsandbox
       @created_at_ms = data["created_at_ms"]
     end
 
-    # @return [Symbol, nil] :directory or :disk
+    # @return [Symbol, nil] :dir or :disk (matches the {Volume.create} `kind:`
+    #   input and the core's canonical names)
     def kind
       @kind&.to_sym
     end
@@ -32,11 +33,102 @@ module Microsandbox
       @created_at_ms && Time.at(@created_at_ms / 1000.0)
     end
 
+    # A host-side filesystem view over this volume (read/write its contents
+    # without a running sandbox).
+    # @return [VolumeFs]
+    def fs
+      @fs ||= VolumeFs.new(Native::Volume.fs(@name.to_s))
+    end
+
     def inspect
       "#<Microsandbox::VolumeInfo name=#{@name.inspect}#{" kind=#{@kind}" if @kind}>"
     end
   end
 
+  # A host-side filesystem view over a named volume, from {Volume.fs} or
+  # {VolumeInfo#fs}. Reads and writes the volume's contents directly on the host,
+  # without booting a sandbox. All paths are relative to the volume root. Mirrors
+  # the `VolumeFs` of the official Python/Node SDKs.
+  class VolumeFs
+    def initialize(native)
+      @native = native
+    end
+
+    # Read a file as raw bytes (ASCII-8BIT).
+    # @return [String]
+    def read(path)
+      @native.read(path.to_s)
+    end
+
+    # Read a file as a UTF-8 string.
+    # @return [String]
+    def read_text(path)
+      @native.read_text(path.to_s)
+    end
+
+    # Write data to a file, creating parent directories as needed.
+    # @param data [String] raw bytes (binary-safe)
+    # @raise [TypeError] if +data+ is not a String
+    # @return [nil]
+    def write(path, data)
+      bytes = Microsandbox.coerce_write_bytes(data)
+      @native.write(path.to_s, bytes)
+      nil
+    end
+
+    # List the entries of a directory.
+    # @return [Array<FsEntry>]
+    def list(path)
+      @native.list(path.to_s).map { |entry| FsEntry.new(entry) }
+    end
+
+    # Create a directory (and any missing parents).
+    # @return [nil]
+    def mkdir(path)
+      @native.mkdir(path.to_s)
+      nil
+    end
+
+    # Remove a single file.
+    # @return [nil]
+    def remove_file(path)
+      @native.remove_file(path.to_s)
+      nil
+    end
+
+    # Remove a directory recursively.
+    # @return [nil]
+    def remove_dir(path)
+      @native.remove_dir(path.to_s)
+      nil
+    end
+
+    # @return [Boolean] whether the path exists in the volume
+    def exists?(path)
+      @native.exists(path.to_s)
+    end
+
+    # Copy a file within the volume.
+    # @return [nil]
+    def copy(src, dst)
+      @native.copy(src.to_s, dst.to_s)
+      nil
+    end
+
+    # Rename/move a file or directory within the volume.
+    # @return [nil]
+    def rename(src, dst)
+      @native.rename(src.to_s, dst.to_s)
+      nil
+    end
+
+    # Stat a path.
+    # @return [FsMetadata]
+    def stat(path)
+      FsMetadata.new(@native.stat(path.to_s))
+    end
+  end
+
   # Management of named persistent volumes. Mount them into a sandbox via
   # `Sandbox.create(..., volumes: { "/data" => { named: "my-vol" } })`.
   class Volume
@@ -74,6 +166,13 @@ module Microsandbox
         Native::Volume.remove(name.to_s)
         nil
       end
+
+      # A host-side filesystem view over a named volume (read/write its contents
+      # without a running sandbox). The volume need not be mounted.
+      # @return [VolumeFs]
+      def fs(name)
+        VolumeFs.new(Native::Volume.fs(name.to_s))
+      end
     end
   end
 end

data/lib/microsandbox.rb

@@ -69,6 +69,25 @@ module Microsandbox
       nil
     end
 
+    # Customizable install via the core `Setup` builder. Like {install} but with
+    # control over where and what to install — mirrors the Node `Setup` builder.
+    #
+    # @param base_dir [String, nil] install root (default `~/.microsandbox`)
+    # @param version [String, nil] pin the runtime version to download
+    # @param force [Boolean] re-download even if binaries already exist — the way
+    #   to repair a corrupt/incomplete `~/.microsandbox`
+    # @param skip_verify [Boolean] skip the post-install verification step
+    # @return [nil]
+    def setup(base_dir: nil, version: nil, force: false, skip_verify: false)
+      opts = {}
+      opts["base_dir"] = base_dir.to_s if base_dir
+      opts["version"] = version.to_s if version
+      opts["force"] = true if force
+      opts["skip_verify"] = true if skip_verify
+      Native.setup(opts)
+      nil
+    end
+
     # @return [Boolean] whether the runtime is installed and resolvable
     def installed?
       Native.installed?
@@ -111,7 +130,9 @@ module Microsandbox
     end
 
     # Override the `msb` runtime path (highest-priority SDK tier of the
-    # resolver, below only the `MSB_PATH` environment variable).
+    # resolver, below only the `MSB_PATH` environment variable). Process-level
+    # and set-once: a second call is silently ignored, and the `MSB_PATH`
+    # environment variable still wins. Mirrors {libkrunfw_path=}.
     # @param path [String]
     # @return [void]
     def runtime_path=(path)
@@ -181,6 +202,19 @@ module Microsandbox
       Native.all_sandbox_metrics.transform_values { |m| Metrics.new(m) }
     end
 
+    # Coerce write data to a binary-safe String, or raise. Centralizes the
+    # contract every `#write` shares (FS/SftpClient/VolumeFs/ExecStdin/
+    # FsWriteSink): accept a String and reject anything else loudly, instead of
+    # silently writing its `to_s` form (e.g. a StringIO's inspect or "42").
+    # @api private
+    # @param data [Object]
+    # @return [String]
+    # @raise [TypeError] unless +data+ is a String
+    def coerce_write_bytes(data)
+      String.try_convert(data) or
+        raise TypeError, "data must be a String (got #{data.class})"
+    end
+
     private
 
     # Auto-provisioning is on by default; any non-empty, non-"0"/"false" value

data/sig/microsandbox.rbs

@@ -7,6 +7,7 @@ module Microsandbox
   def self.version: () -> String
   def self.runtime_version: () -> String
   def self.install: () -> nil
+  def self.setup: (?base_dir: String?, ?version: String?, ?force: bool, ?skip_verify: bool) -> nil
   def self.installed?: () -> bool
   def self.ensure_runtime!: () -> nil
   def self.runtime_path: () -> String
@@ -97,6 +98,20 @@ module Microsandbox
     def stat: (String path) -> FsMetadata
     def copy_from_host: (String host_path, String guest_path) -> nil
     def copy_to_host: (String guest_path, String host_path) -> nil
+    def read_stream: (String path) -> FsReadStream
+    def write_stream: (String path) ?{ (FsWriteSink) -> untyped } -> untyped
+  end
+
+  class FsReadStream
+    include Enumerable[String]
+    def each: () { (String) -> void } -> self
+            | () -> Enumerator[String, self]
+    def read: () -> String
+  end
+
+  class FsWriteSink
+    def write: (String data) -> self
+    def close: () -> nil
   end
 
   class Metrics
@@ -110,6 +125,9 @@ module Microsandbox
     def disk_write_bytes: () -> Integer
     def net_rx_bytes: () -> Integer
     def net_tx_bytes: () -> Integer
+    def upper_used_bytes: () -> Integer?
+    def upper_free_bytes: () -> Integer?
+    def upper_host_allocated_bytes: () -> Integer?
     def uptime_secs: () -> Float
     def timestamp: () -> Time
   end
@@ -138,6 +156,10 @@ module Microsandbox
     def request_kill: () -> nil
     def request_drain: () -> nil
     def wait_until_stopped: () -> SandboxStopResult
+    def config_json: () -> String
+    def config: () -> Hash[String, untyped]
+    def snapshot: (String name) -> SnapshotInfo
+    def snapshot_to: (String path) -> SnapshotInfo
   end
 
   # Deprecated alias for SandboxHandle (was a read-only metadata type pre-v0.5.8).
@@ -161,15 +183,23 @@ module Microsandbox
                       ?scripts: Hash[untyped, untyped]?, ?entrypoint: Array[String]?,
                       ?ports: Hash[untyped, untyped]?, ?ports_udp: Hash[untyped, untyped]?,
                       ?volumes: Hash[untyped, untyped]?, ?network: untyped?,
+                      ?dns: Hash[untyped, untyped]?, ?tls: Hash[untyped, untyped]?,
+                      ?ipv4_pool: String?, ?ipv6_pool: String?,
+                      ?max_connections: Integer?, ?trust_host_cas: bool?,
                       ?patches: Array[Hash[untyped, untyped]]?, ?from_snapshot: String?,
+                      ?fstype: String?, ?init: (String | Symbol | Hash[untyped, untyped])?, ?ephemeral: bool,
                       ?log_level: (String | Symbol)?, ?quiet_logs: bool, ?security: (String | Symbol)?,
                       ?oci_upper_size: Integer?, ?max_duration: Integer?, ?idle_timeout: Integer?,
                       ?rlimits: Hash[untyped, untyped]?, ?pull_policy: (String | Symbol)?,
                       ?registry_auth: Hash[untyped, untyped]?, ?registry_insecure: bool,
                       ?registry_ca_certs: (String | Array[String])?,
-                      ?secrets: Array[Hash[untyped, untyped]]?, ?detached: bool,
+                      ?secrets: Array[Hash[untyped, untyped]]?,
+                      ?on_secret_violation: (String | Symbol | Hash[untyped, untyped])?,
+                      ?detached: bool,
                       ?replace: bool, ?replace_with_timeout: Numeric?)
                       ?{ (Sandbox) -> untyped } -> untyped
+    # Accepts the same keyword options as {create}.
+    def self.create_with_progress: (String name, **untyped) -> PullSession
     def self.start: (String name, ?detached: bool) -> Sandbox
     def self.get: (String name) -> SandboxHandle
     def self.list: () -> Array[SandboxHandle]
@@ -178,15 +208,15 @@ module Microsandbox
 
     def name: () -> String
     def exec: (String command, ?Array[String] args, ?cwd: String?, ?user: String?,
-               ?env: Hash[untyped, untyped]?, ?timeout: Numeric?, ?tty: bool, ?stdin: String?,
+               ?env: Hash[untyped, untyped]?, ?timeout: Numeric?, ?tty: bool, ?stdin: (String | :null)?,
                ?rlimits: Hash[untyped, untyped]?) -> ExecOutput
     def shell: (String script, ?cwd: String?, ?user: String?, ?env: Hash[untyped, untyped]?,
-                ?timeout: Numeric?, ?tty: bool, ?stdin: String?, ?rlimits: Hash[untyped, untyped]?) -> ExecOutput
+                ?timeout: Numeric?, ?tty: bool, ?stdin: (String | :null)?, ?rlimits: Hash[untyped, untyped]?) -> ExecOutput
     def exec_stream: (String command, ?Array[String] args, ?cwd: String?, ?user: String?,
-                      ?env: Hash[untyped, untyped]?, ?timeout: Numeric?, ?tty: bool, ?stdin: (String | :pipe)?,
+                      ?env: Hash[untyped, untyped]?, ?timeout: Numeric?, ?tty: bool, ?stdin: (String | :pipe | :null)?,
                       ?rlimits: Hash[untyped, untyped]?) -> ExecHandle
     def shell_stream: (String script, ?cwd: String?, ?user: String?, ?env: Hash[untyped, untyped]?,
-                       ?timeout: Numeric?, ?tty: bool, ?stdin: (String | :pipe)?, ?rlimits: Hash[untyped, untyped]?) -> ExecHandle
+                       ?timeout: Numeric?, ?tty: bool, ?stdin: (String | :pipe | :null)?, ?rlimits: Hash[untyped, untyped]?) -> ExecHandle
     def attach: (String command, ?Array[String] args, ?cwd: String?, ?user: String?,
                  ?env: Hash[untyped, untyped]?, ?detach_keys: String?,
                  ?rlimits: Hash[untyped, untyped]?) -> Integer
@@ -209,6 +239,14 @@ module Microsandbox
     def detach: () -> nil
   end
 
+  class PullSession
+    include Enumerable[Hash[String, untyped]]
+    def initialize: (untyped native) -> void
+    def each: () { (Hash[String, untyped]) -> void } -> self
+            | () -> Enumerator[Hash[String, untyped], self]
+    def sandbox: () -> Sandbox
+  end
+
   class LogStream
     include Enumerable[LogEntry]
     def each: () { (LogEntry) -> void } -> self
@@ -242,7 +280,7 @@ module Microsandbox
   end
 
   class ExecStdin
-    def write: (untyped data) -> self
+    def write: (String data) -> self
     def close: () -> nil
   end
 
@@ -305,6 +343,22 @@ module Microsandbox
     def disk_fstype: () -> String?
     def labels: () -> Hash[String, String]
     def created_at: () -> Time?
+    def fs: () -> VolumeFs
+  end
+
+  class VolumeFs
+    def initialize: (untyped native) -> void
+    def read: (String path) -> String
+    def read_text: (String path) -> String
+    def write: (String path, String data) -> nil
+    def list: (String path) -> Array[FsEntry]
+    def mkdir: (String path) -> nil
+    def remove_file: (String path) -> nil
+    def remove_dir: (String path) -> nil
+    def exists?: (String path) -> bool
+    def copy: (String src, String dst) -> nil
+    def rename: (String src, String dst) -> nil
+    def stat: (String path) -> FsMetadata
   end
 
   class Volume
@@ -313,6 +367,7 @@ module Microsandbox
     def self.get: (String name) -> VolumeInfo
     def self.list: () -> Array[VolumeInfo]
     def self.remove: (String name) -> nil
+    def self.fs: (String name) -> VolumeFs
   end
 
   class SnapshotInfo
@@ -321,9 +376,15 @@ module Microsandbox
     def name: () -> String?
     def parent_digest: () -> String?
     def image_ref: () -> String?
+    def image_manifest_digest: () -> String?
+    def fstype: () -> String?
+    def source_sandbox: () -> String?
+    def labels: () -> Hash[String, String]
     def size_bytes: () -> Integer?
     def format: () -> Symbol?
     def created_at: () -> Time?
+    def open: () -> SnapshotInfo
+    def remove: (?force: bool) -> nil
   end
 
   class SnapshotVerifyReport
@@ -339,8 +400,11 @@ module Microsandbox
   class Snapshot
     def self.create: (String source_sandbox, ?name: String?, ?path: String?,
                       ?labels: Hash[untyped, untyped]?, ?force: bool, ?record_integrity: bool) -> SnapshotInfo
+    def self.open: (String name_or_path) -> SnapshotInfo
     def self.get: (String name_or_digest) -> SnapshotInfo
     def self.list: () -> Array[SnapshotInfo]
+    def self.list_dir: (String dir) -> Array[SnapshotInfo]
+    def self.reindex: (?String? dir) -> Integer
     def self.remove: (String name_or_path, ?force: bool) -> nil
     def self.verify: (String name_or_path) -> SnapshotVerifyReport
     def self.export: (String name_or_path, String out_path, ?with_parents: bool,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: microsandbox-rb
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - ya-luotao
@@ -50,6 +50,7 @@ files:
 - ext/microsandbox/src/conv.rs
 - ext/microsandbox/src/error.rs
 - ext/microsandbox/src/exec.rs
+- ext/microsandbox/src/fs_stream.rs
 - ext/microsandbox/src/image.rs
 - ext/microsandbox/src/lib.rs
 - ext/microsandbox/src/runtime.rs