microsandbox-rb 0.5.7

data/lib/microsandbox/fs.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # A directory entry returned by {FS#list}.
+  class FsEntry
+    # @return [String] absolute guest path
+    attr_reader :path
+    # @return [Symbol] one of :file, :directory, :symlink, :other
+    attr_reader :type
+    # @return [Integer] size in bytes
+    attr_reader :size
+    # @return [Integer] POSIX mode bits
+    attr_reader :mode
+
+    def initialize(data)
+      @path = data["path"]
+      @type = data["type"].to_sym
+      @size = data["size"]
+      @mode = data["mode"]
+      @modified_ms = data["modified_ms"]
+    end
+
+    # @return [String] the final path component
+    def name
+      File.basename(@path)
+    end
+
+    # @return [Time, nil] last-modified time, if known
+    def modified
+      @modified_ms && Time.at(@modified_ms / 1000.0)
+    end
+
+    def file?       = @type == :file
+    def directory?  = @type == :directory
+    def symlink?    = @type == :symlink
+
+    def inspect
+      "#<Microsandbox::FsEntry path=#{@path.inspect} type=#{@type} size=#{@size}>"
+    end
+  end
+
+  # File/directory metadata returned by {FS#stat}.
+  class FsMetadata
+    # @return [Symbol] one of :file, :directory, :symlink, :other
+    attr_reader :type
+    # @return [Integer] size in bytes
+    attr_reader :size
+    # @return [Integer] POSIX mode bits
+    attr_reader :mode
+
+    def initialize(data)
+      @type = data["type"].to_sym
+      @size = data["size"]
+      @mode = data["mode"]
+      @readonly = data["readonly"]
+      @modified_ms = data["modified_ms"]
+      @created_ms = data["created_ms"]
+    end
+
+    def readonly?   = @readonly
+    def file?       = @type == :file
+    def directory?  = @type == :directory
+    def symlink?    = @type == :symlink
+
+    # @return [Time, nil] last-modified time, if known
+    def modified
+      @modified_ms && Time.at(@modified_ms / 1000.0)
+    end
+
+    # @return [Time, nil] creation time, if known
+    def created
+      @created_ms && Time.at(@created_ms / 1000.0)
+    end
+
+    def inspect
+      "#<Microsandbox::FsMetadata type=#{@type} size=#{@size} mode=#{format("%o", @mode)}>"
+    end
+  end
+
+  # Guest filesystem operations for a running sandbox. Obtain via {Sandbox#fs}.
+  # All paths are paths *inside* the guest VM.
+  class FS
+    def initialize(native)
+      @native = native
+    end
+
+    # Read a file as raw bytes (ASCII-8BIT).
+    # @return [String]
+    def read(path)
+      @native.fs_read(path.to_s)
+    end
+
+    # Read a file as a UTF-8 string.
+    # @return [String]
+    def read_text(path)
+      @native.fs_read_text(path.to_s)
+    end
+
+    # Write data (a String) to a file, creating or truncating it.
+    # @return [nil]
+    def write(path, data)
+      @native.fs_write(path.to_s, data.to_s)
+      nil
+    end
+
+    # List the entries of a directory.
+    # @return [Array<FsEntry>]
+    def list(path)
+      @native.fs_list(path.to_s).map { |entry| FsEntry.new(entry) }
+    end
+
+    # Create a directory (and any missing parents).
+    # @return [nil]
+    def mkdir(path)
+      @native.fs_mkdir(path.to_s)
+      nil
+    end
+
+    # Remove a single file.
+    # @return [nil]
+    def remove(path)
+      @native.fs_remove(path.to_s)
+      nil
+    end
+
+    # Remove a directory recursively.
+    # @return [nil]
+    def remove_dir(path)
+      @native.fs_remove_dir(path.to_s)
+      nil
+    end
+
+    # Copy a file within the guest.
+    # @return [nil]
+    def copy(src, dst)
+      @native.fs_copy(src.to_s, dst.to_s)
+      nil
+    end
+
+    # Rename/move a file or directory within the guest.
+    # @return [nil]
+    def rename(src, dst)
+      @native.fs_rename(src.to_s, dst.to_s)
+      nil
+    end
+
+    # @return [Boolean] whether the path exists in the guest
+    def exists?(path)
+      @native.fs_exists(path.to_s)
+    end
+
+    # Stat a path.
+    # @return [FsMetadata]
+    def stat(path)
+      FsMetadata.new(@native.fs_stat(path.to_s))
+    end
+
+    # Copy a file from the host into the guest.
+    # @return [nil]
+    def copy_from_host(host_path, guest_path)
+      @native.fs_copy_from_host(host_path.to_s, guest_path.to_s)
+      nil
+    end
+
+    # Copy a file from the guest to the host.
+    # @return [nil]
+    def copy_to_host(guest_path, host_path)
+      @native.fs_copy_to_host(guest_path.to_s, host_path.to_s)
+      nil
+    end
+  end
+end

data/lib/microsandbox/image.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # Metadata for a cached OCI image, from {Image.get} / {Image.list}.
+  class ImageInfo
+    attr_reader :reference, :size_bytes, :manifest_digest, :architecture, :os, :layer_count
+
+    def initialize(data)
+      @reference = data["reference"]
+      @size_bytes = data["size_bytes"]
+      @manifest_digest = data["manifest_digest"]
+      @architecture = data["architecture"]
+      @os = data["os"]
+      @layer_count = data["layer_count"]
+      @created_at_ms = data["created_at_ms"]
+      @last_used_at_ms = data["last_used_at_ms"]
+    end
+
+    # @return [Time, nil]
+    def created_at
+      @created_at_ms && Time.at(@created_at_ms / 1000.0)
+    end
+
+    # @return [Time, nil]
+    def last_used_at
+      @last_used_at_ms && Time.at(@last_used_at_ms / 1000.0)
+    end
+
+    def inspect
+      "#<Microsandbox::ImageInfo reference=#{@reference.inspect} layers=#{@layer_count}>"
+    end
+  end
+
+  # Full inspection detail for a cached image, from {Image.inspect}.
+  class ImageDetail
+    # @return [ImageInfo]
+    attr_reader :handle
+    # @return [Hash, nil] OCI config (digest, env, cmd, entrypoint, working_dir, user, stop_signal)
+    attr_reader :config
+    # @return [Array<Hash>] layer descriptors
+    attr_reader :layers
+
+    def initialize(data)
+      @handle = ImageInfo.new(data["handle"])
+      @config = data["config"]
+      @layers = data["layers"] || []
+    end
+
+    def reference = @handle.reference
+
+    def inspect
+      "#<Microsandbox::ImageDetail reference=#{@handle.reference.inspect} layers=#{@layers.size}>"
+    end
+  end
+
+  # The result of {Image.prune}.
+  class ImagePruneReport
+    attr_reader :image_refs_removed, :manifests_removed, :layers_removed,
+                :fsmeta_removed, :vmdk_removed, :bytes_reclaimed
+
+    def initialize(data)
+      @image_refs_removed = data["image_refs_removed"]
+      @manifests_removed = data["manifests_removed"]
+      @layers_removed = data["layers_removed"]
+      @fsmeta_removed = data["fsmeta_removed"]
+      @vmdk_removed = data["vmdk_removed"]
+      @bytes_reclaimed = data["bytes_reclaimed"]
+    end
+  end
+
+  # Management of the local OCI image cache. Images are pulled automatically by
+  # {Sandbox.create}; this namespace lets you inspect and prune the cache.
+  class Image
+    class << self
+      # All cached images.
+      # @return [Array<ImageInfo>]
+      def list
+        Native::Image.list.map { |info| ImageInfo.new(info) }
+      end
+
+      # Metadata for one cached image.
+      # @return [ImageInfo]
+      def get(reference)
+        ImageInfo.new(Native::Image.get(reference.to_s))
+      end
+
+      # Full inspection detail for a cached image. With no argument this is the
+      # normal class `#inspect` (so object display still works).
+      # @return [ImageDetail]
+      def inspect(reference = nil)
+        return super() if reference.nil?
+
+        ImageDetail.new(Native::Image.inspect(reference.to_s))
+      end
+
+      # Remove a cached image.
+      # @param force [Boolean] remove even if referenced
+      # @return [nil]
+      def remove(reference, force: false)
+        Native::Image.remove(reference.to_s, force)
+        nil
+      end
+
+      # Garbage-collect unreferenced images, manifests, and layers.
+      # @return [ImagePruneReport]
+      def prune
+        ImagePruneReport.new(Native::Image.prune)
+      end
+    end
+  end
+end

data/lib/microsandbox/log_entry.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # A single captured log entry, returned by {Sandbox#logs}.
+  class LogEntry
+    # @return [Symbol] one of :stdout, :stderr, :output, :system
+    attr_reader :source
+    # @return [Integer, nil] relay-monotonic session id (nil for system markers)
+    attr_reader :session_id
+    # @return [String] opaque resume cursor token
+    attr_reader :cursor
+    # @return [String] raw captured bytes (ASCII-8BIT)
+    attr_reader :data
+
+    def initialize(entry)
+      @timestamp_ms = entry["timestamp_ms"]
+      @source = entry["source"].to_sym
+      @session_id = entry["session_id"]
+      @cursor = entry["cursor"]
+      @data = entry["data"]
+    end
+
+    # @return [Time] wall-clock capture time
+    def timestamp
+      Time.at(@timestamp_ms / 1000.0)
+    end
+
+    # @return [String] the captured bytes decoded as UTF-8 (lenient)
+    def text
+      @data.dup.force_encoding(Encoding::UTF_8)
+    end
+
+    def inspect
+      "#<Microsandbox::LogEntry source=#{@source} session_id=#{@session_id} " \
+        "len=#{@data.bytesize}>"
+    end
+  end
+end

data/lib/microsandbox/metrics.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # A point-in-time resource-usage snapshot for a sandbox, returned by
+  # {Sandbox#metrics}.
+  class Metrics
+    # @return [Float] CPU usage as a percentage (0.0–100.0 * vCPUs)
+    attr_reader :cpu_percent
+    # @return [Integer] cumulative vCPU time in nanoseconds
+    attr_reader :vcpu_time_ns
+    # @return [Integer] memory currently used, in bytes
+    attr_reader :memory_bytes
+    # @return [Integer, nil] memory available to the guest, in bytes
+    attr_reader :memory_available_bytes
+    # @return [Integer, nil] host-resident memory for the VM, in bytes
+    attr_reader :memory_host_resident_bytes
+    # @return [Integer] memory limit, in bytes
+    attr_reader :memory_limit_bytes
+    # @return [Integer] cumulative bytes read from disk
+    attr_reader :disk_read_bytes
+    # @return [Integer] cumulative bytes written to disk
+    attr_reader :disk_write_bytes
+    # @return [Integer] cumulative bytes received over the network
+    attr_reader :net_rx_bytes
+    # @return [Integer] cumulative bytes transmitted over the network
+    attr_reader :net_tx_bytes
+    # @return [Float] sandbox uptime in seconds
+    attr_reader :uptime_secs
+
+    def initialize(data)
+      @cpu_percent = data["cpu_percent"]
+      @vcpu_time_ns = data["vcpu_time_ns"]
+      @memory_bytes = data["memory_bytes"]
+      @memory_available_bytes = data["memory_available_bytes"]
+      @memory_host_resident_bytes = data["memory_host_resident_bytes"]
+      @memory_limit_bytes = data["memory_limit_bytes"]
+      @disk_read_bytes = data["disk_read_bytes"]
+      @disk_write_bytes = data["disk_write_bytes"]
+      @net_rx_bytes = data["net_rx_bytes"]
+      @net_tx_bytes = data["net_tx_bytes"]
+      @uptime_secs = data["uptime_secs"]
+      @timestamp_ms = data["timestamp_ms"]
+    end
+
+    # @return [Time] when this snapshot was captured
+    def timestamp
+      Time.at(@timestamp_ms / 1000.0)
+    end
+
+    def inspect
+      "#<Microsandbox::Metrics cpu=#{@cpu_percent.round(1)}% " \
+        "mem=#{@memory_bytes}/#{@memory_limit_bytes}B uptime=#{@uptime_secs.round(1)}s>"
+    end
+  end
+end