microsandbox-rb 0.5.7

data/lib/microsandbox/volume.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # A named persistent volume, from {Volume.create} / {Volume.get} / {Volume.list}.
+  #
+  # `path` is populated when returned from {Volume.create}; the storage stats
+  # (`kind`, `used_bytes`, …) are populated when returned from {Volume.get}/{Volume.list}.
+  class VolumeInfo
+    attr_reader :name, :path, :quota_mib, :used_bytes, :capacity_bytes,
+                :disk_format, :disk_fstype, :labels
+
+    def initialize(data)
+      @name = data["name"]
+      @path = data["path"]
+      @kind = data["kind"]
+      @quota_mib = data["quota_mib"]
+      @used_bytes = data["used_bytes"]
+      @capacity_bytes = data["capacity_bytes"]
+      @disk_format = data["disk_format"]
+      @disk_fstype = data["disk_fstype"]
+      @labels = data["labels"] || {}
+      @created_at_ms = data["created_at_ms"]
+    end
+
+    # @return [Symbol, nil] :directory or :disk
+    def kind
+      @kind&.to_sym
+    end
+
+    # @return [Time, nil]
+    def created_at
+      @created_at_ms && Time.at(@created_at_ms / 1000.0)
+    end
+
+    def inspect
+      "#<Microsandbox::VolumeInfo name=#{@name.inspect}#{@kind ? " kind=#{@kind}" : ""}>"
+    end
+  end
+
+  # Management of named persistent volumes. Mount them into a sandbox via
+  # `Sandbox.create(..., volumes: { "/data" => { named: "my-vol" } })`.
+  class Volume
+    class << self
+      # Create a named volume.
+      # @param name [String]
+      # @param kind ["dir", "disk"] storage kind (default "dir")
+      # @param size_mib [Integer, nil] required for kind "disk"
+      # @param quota_mib [Integer, nil] optional quota
+      # @param labels [Hash, nil]
+      # @return [VolumeInfo]
+      def create(name, kind: "dir", size_mib: nil, quota_mib: nil, labels: nil)
+        opts = { "kind" => kind.to_s }
+        opts["size_mib"] = Integer(size_mib) if size_mib
+        opts["quota_mib"] = Integer(quota_mib) if quota_mib
+        opts["labels"] = labels.each_with_object({}) { |(k, v), a| a[k.to_s] = v.to_s } if labels
+        VolumeInfo.new(Native::Volume.create(name.to_s, opts))
+      end
+
+      # Metadata for a volume.
+      # @return [VolumeInfo]
+      def get(name)
+        VolumeInfo.new(Native::Volume.get(name.to_s))
+      end
+
+      # All volumes.
+      # @return [Array<VolumeInfo>]
+      def list
+        Native::Volume.list.map { |info| VolumeInfo.new(info) }
+      end
+
+      # Remove a volume.
+      # @return [nil]
+      def remove(name)
+        Native::Volume.remove(name.to_s)
+        nil
+      end
+    end
+  end
+end

data/lib/microsandbox.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "microsandbox/version"
+
+# Load the compiled native extension. Precompiled platform gems ship a
+# version-specific subdirectory (e.g. lib/microsandbox/3.4/microsandbox_rb.bundle);
+# fall back to the flat path used by source builds.
+begin
+  ruby_version = RbConfig::CONFIG["ruby_version"].to_s
+  require_relative "microsandbox/#{ruby_version}/microsandbox_rb"
+rescue LoadError
+  require_relative "microsandbox/microsandbox_rb"
+end
+
+require_relative "microsandbox/errors"
+require_relative "microsandbox/exec_output"
+require_relative "microsandbox/exec_handle"
+require_relative "microsandbox/fs"
+require_relative "microsandbox/metrics"
+require_relative "microsandbox/log_entry"
+require_relative "microsandbox/streams"
+require_relative "microsandbox/image"
+require_relative "microsandbox/volume"
+require_relative "microsandbox/snapshot"
+require_relative "microsandbox/sandbox"
+
+# Microsandbox — lightweight microVM sandboxes for Ruby.
+#
+# The runtime is embedded directly in the process via a Rust native extension;
+# there is no daemon to install and no server to connect to. Creating a sandbox
+# spawns a real microVM as a child process.
+#
+# @example
+#   Microsandbox::Sandbox.create("hello", image: "python") do |sb|
+#     puts sb.exec("python", ["-c", "print('Hello, World!')"]).stdout
+#   end
+module Microsandbox
+  class << self
+    # @return [String] the gem version
+    def version
+      VERSION
+    end
+
+    # Download and install the `msb` runtime + `libkrunfw` into
+    # `~/.microsandbox` (idempotent). Usually unnecessary: the native
+    # extension provisions the runtime at build time.
+    # @return [nil]
+    def install
+      Native.install
+      nil
+    end
+
+    # @return [Boolean] whether the runtime is installed and resolvable
+    def installed?
+      Native.installed?
+    end
+
+    # @return [String] the resolved path to the `msb` runtime binary
+    def runtime_path
+      Native.resolved_msb_path
+    end
+
+    # Override the `msb` runtime path (highest-priority SDK tier of the
+    # resolver, below only the `MSB_PATH` environment variable).
+    # @param path [String]
+    # @return [void]
+    def runtime_path=(path)
+      Native.set_runtime_msb_path(path.to_s)
+    end
+
+    # Latest resource-usage snapshot for every running sandbox, keyed by name.
+    # Mirrors the official `all_sandbox_metrics`/`allSandboxMetrics` helpers.
+    # @return [Hash{String => Metrics}]
+    def all_sandbox_metrics
+      Native.all_sandbox_metrics.transform_values { |m| Metrics.new(m) }
+    end
+  end
+end

data/rust-toolchain.toml

@@ -0,0 +1,5 @@
+# The microsandbox core crate uses Rust edition 2024 and pulls in dependencies
+# (e.g. smoltcp) that require a recent compiler. Stable >= 1.91 is the minimum
+# supported Rust version (MSRV) for building this gem from source.
+[toolchain]
+channel = "stable"

data/sig/microsandbox.rbs

@@ -0,0 +1,321 @@
+# Type signatures for the public microsandbox Ruby API.
+
+module Microsandbox
+  VERSION: String
+
+  def self.version: () -> String
+  def self.install: () -> nil
+  def self.installed?: () -> bool
+  def self.runtime_path: () -> String
+  def self.runtime_path=: (String path) -> void
+  def self.all_sandbox_metrics: () -> Hash[String, Metrics]
+
+  class Error < StandardError
+    def self.code: () -> String
+    def code: () -> String
+  end
+
+  class InvalidConfigError < Error end
+  class SandboxNotFoundError < Error end
+  class SandboxNotRunningError < Error end
+  class SandboxAlreadyExistsError < Error end
+  class SandboxStillRunningError < Error end
+  class ExecTimeoutError < Error end
+  class ExecFailedError < Error end
+  class FilesystemError < Error end
+  class PathNotFoundError < Error end
+  class VolumeNotFoundError < Error end
+  class VolumeAlreadyExistsError < Error end
+  class ImageNotFoundError < Error end
+  class ImageInUseError < Error end
+  class ImagePullFailedError < Error end
+  class NetworkPolicyError < Error end
+  class SecretViolationError < Error end
+  class TlsError < Error end
+  class IoError < Error end
+  class MetricsDisabledError < Error end
+  class MetricsUnavailableError < Error end
+  class UnsupportedOperationError < Error end
+
+  class ExecOutput
+    def initialize: (Hash[String, untyped] data) -> void
+    def exit_code: () -> Integer
+    def success?: () -> bool
+    def failure?: () -> bool
+    def stdout: () -> String
+    def stderr: () -> String
+    def stdout_bytes: () -> String
+    def stderr_bytes: () -> String
+    def to_s: () -> String
+  end
+
+  class FsEntry
+    def path: () -> String
+    def name: () -> String
+    def type: () -> Symbol
+    def size: () -> Integer
+    def mode: () -> Integer
+    def modified: () -> Time?
+    def file?: () -> bool
+    def directory?: () -> bool
+    def symlink?: () -> bool
+  end
+
+  class FsMetadata
+    def type: () -> Symbol
+    def size: () -> Integer
+    def mode: () -> Integer
+    def readonly?: () -> bool
+    def file?: () -> bool
+    def directory?: () -> bool
+    def symlink?: () -> bool
+    def modified: () -> Time?
+    def created: () -> Time?
+  end
+
+  class FS
+    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: (String path) -> nil
+    def remove_dir: (String path) -> nil
+    def copy: (String src, String dst) -> nil
+    def rename: (String src, String dst) -> nil
+    def exists?: (String path) -> bool
+    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
+  end
+
+  class Metrics
+    def cpu_percent: () -> Float
+    def vcpu_time_ns: () -> Integer
+    def memory_bytes: () -> Integer
+    def memory_available_bytes: () -> Integer?
+    def memory_host_resident_bytes: () -> Integer?
+    def memory_limit_bytes: () -> Integer
+    def disk_read_bytes: () -> Integer
+    def disk_write_bytes: () -> Integer
+    def net_rx_bytes: () -> Integer
+    def net_tx_bytes: () -> Integer
+    def uptime_secs: () -> Float
+    def timestamp: () -> Time
+  end
+
+  class LogEntry
+    def source: () -> Symbol
+    def session_id: () -> Integer?
+    def cursor: () -> String
+    def data: () -> String
+    def text: () -> String
+    def timestamp: () -> Time
+  end
+
+  class SandboxInfo
+    def name: () -> String
+    def status: () -> Symbol
+    def running?: () -> bool
+    def stopped?: () -> bool
+    def created_at: () -> Time?
+    def updated_at: () -> Time?
+  end
+
+  class SandboxStopResult
+    def name: () -> String
+    def status: () -> Symbol
+    def exit_code: () -> Integer?
+    def signal: () -> Integer?
+    def source: () -> String?
+    def stopped?: () -> bool
+    def crashed?: () -> bool
+    def observed_at: () -> Time
+  end
+
+  class Sandbox
+    def self.create: (String name, ?image: String?, ?cpus: Integer?, ?memory: Integer?,
+                      ?env: Hash[untyped, untyped]?, ?workdir: String?, ?shell: String?,
+                      ?user: String?, ?hostname: String?, ?labels: Hash[untyped, untyped]?,
+                      ?scripts: Hash[untyped, untyped]?, ?entrypoint: Array[String]?,
+                      ?ports: Hash[untyped, untyped]?, ?ports_udp: Hash[untyped, untyped]?,
+                      ?volumes: Hash[untyped, untyped]?, ?network: untyped?, ?from_snapshot: String?,
+                      ?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)?,
+                      ?secrets: Array[Hash[untyped, untyped]]?, ?detached: bool,
+                      ?replace: bool, ?replace_with_timeout: Numeric?)
+                      ?{ (Sandbox) -> untyped } -> untyped
+    def self.start: (String name, ?detached: bool) -> Sandbox
+    def self.get: (String name) -> SandboxInfo
+    def self.list: () -> Array[SandboxInfo]
+    def self.list_with: (?labels: Hash[untyped, untyped]) -> Array[SandboxInfo]
+    def self.remove: (String name) -> nil
+
+    def name: () -> String
+    def exec: (String command, ?Array[String] args, ?cwd: String?, ?user: String?,
+               ?env: Hash[untyped, untyped]?, ?timeout: Numeric?, ?tty: bool, ?stdin: String?,
+               ?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
+    def exec_stream: (String command, ?Array[String] args, ?cwd: String?, ?user: String?,
+                      ?env: Hash[untyped, untyped]?, ?timeout: Numeric?, ?tty: bool, ?stdin: String?,
+                      ?rlimits: Hash[untyped, untyped]?) -> ExecHandle
+    def shell_stream: (String script, ?cwd: String?, ?user: String?, ?env: Hash[untyped, untyped]?,
+                       ?timeout: Numeric?, ?tty: bool, ?stdin: String?, ?rlimits: Hash[untyped, untyped]?) -> ExecHandle
+    def fs: () -> FS
+    def metrics: () -> Metrics
+    def logs: (?tail: Integer?, ?since_ms: Numeric?, ?until_ms: Numeric?,
+               ?sources: Array[String | Symbol]?) -> Array[LogEntry]
+    def metrics_stream: (?interval: Numeric) -> MetricsStream
+    def log_stream: (?sources: Array[String | Symbol]?, ?since_ms: Numeric?,
+                     ?from_cursor: String?, ?until_ms: Numeric?, ?follow: bool) -> LogStream
+    def stop: (?timeout: Numeric?) -> nil
+    def kill: (?timeout: Numeric?) -> nil
+    def request_stop: () -> nil
+    def request_kill: () -> nil
+    def request_drain: () -> nil
+    def wait_until_stopped: () -> SandboxStopResult
+    def owns_lifecycle?: () -> bool
+    def detach: () -> nil
+  end
+
+  class LogStream
+    include Enumerable[LogEntry]
+    def each: () { (LogEntry) -> void } -> self
+            | () -> Enumerator[LogEntry, self]
+  end
+
+  class MetricsStream
+    include Enumerable[Metrics]
+    def each: () { (Metrics) -> void } -> self
+            | () -> Enumerator[Metrics, self]
+  end
+
+  class ExecEvent
+    def type: () -> Symbol
+    def pid: () -> Integer?
+    def code: () -> Integer?
+    def data: () -> String?
+    def text: () -> String?
+    def started?: () -> bool
+    def stdout?: () -> bool
+    def stderr?: () -> bool
+    def exited?: () -> bool
+    def failed?: () -> bool
+    def stdin_error?: () -> bool
+  end
+
+  class ExitStatus
+    def exit_code: () -> Integer
+    def success?: () -> bool
+    def failure?: () -> bool
+  end
+
+  class ExecStdin
+    def write: (untyped data) -> self
+    def close: () -> nil
+  end
+
+  class ExecHandle
+    include Enumerable[ExecEvent]
+    def id: () -> String
+    def each: () { (ExecEvent) -> void } -> self
+            | () -> Enumerator[ExecEvent, self]
+    def wait: () -> ExitStatus
+    def collect: () -> ExecOutput
+    def signal: (Integer sig) -> nil
+    def kill: () -> nil
+    def resize: (Integer rows, Integer cols) -> nil
+    def stdin: () -> ExecStdin?
+  end
+
+  class ImageInfo
+    def reference: () -> String
+    def size_bytes: () -> Integer?
+    def manifest_digest: () -> String?
+    def architecture: () -> String?
+    def os: () -> String?
+    def layer_count: () -> Integer
+    def created_at: () -> Time?
+    def last_used_at: () -> Time?
+  end
+
+  class ImageDetail
+    def handle: () -> ImageInfo
+    def config: () -> Hash[String, untyped]?
+    def layers: () -> Array[Hash[String, untyped]]
+    def reference: () -> String
+  end
+
+  class ImagePruneReport
+    def image_refs_removed: () -> Integer
+    def manifests_removed: () -> Integer
+    def layers_removed: () -> Integer
+    def fsmeta_removed: () -> Integer
+    def vmdk_removed: () -> Integer
+    def bytes_reclaimed: () -> Integer?
+  end
+
+  class Image
+    def self.list: () -> Array[ImageInfo]
+    def self.get: (String reference) -> ImageInfo
+    def self.inspect: (?String? reference) -> (ImageDetail | String)
+    def self.remove: (String reference, ?force: bool) -> nil
+    def self.prune: () -> ImagePruneReport
+  end
+
+  class VolumeInfo
+    def name: () -> String
+    def path: () -> String?
+    def kind: () -> Symbol?
+    def quota_mib: () -> Integer?
+    def used_bytes: () -> Integer?
+    def capacity_bytes: () -> Integer?
+    def disk_format: () -> String?
+    def disk_fstype: () -> String?
+    def labels: () -> Hash[String, String]
+    def created_at: () -> Time?
+  end
+
+  class Volume
+    def self.create: (String name, ?kind: String, ?size_mib: Integer?, ?quota_mib: Integer?,
+                      ?labels: Hash[untyped, untyped]?) -> VolumeInfo
+    def self.get: (String name) -> VolumeInfo
+    def self.list: () -> Array[VolumeInfo]
+    def self.remove: (String name) -> nil
+  end
+
+  class SnapshotInfo
+    def digest: () -> String
+    def path: () -> String
+    def name: () -> String?
+    def parent_digest: () -> String?
+    def image_ref: () -> String?
+    def size_bytes: () -> Integer?
+    def format: () -> Symbol?
+    def created_at: () -> Time?
+  end
+
+  class SnapshotVerifyReport
+    def digest: () -> String
+    def path: () -> String
+    def status: () -> Symbol
+    def algorithm: () -> String?
+    def content_digest: () -> String?
+    def verified?: () -> bool
+    def not_recorded?: () -> bool
+  end
+
+  class Snapshot
+    def self.create: (String source_sandbox, ?name: String?, ?path: String?,
+                      ?labels: Hash[untyped, untyped]?, ?force: bool, ?record_integrity: bool) -> SnapshotInfo
+    def self.get: (String name_or_digest) -> SnapshotInfo
+    def self.list: () -> Array[SnapshotInfo]
+    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,
+                      ?with_image: bool, ?plain_tar: bool) -> nil
+    def self.import: (String archive_path, ?dest: String?) -> SnapshotInfo
+  end
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: microsandbox-rb
+version: !ruby/object:Gem::Version
+  version: 0.5.7
+platform: ruby
+authors:
+- ya-luotao
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.91
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.91
+description: |
+  The microsandbox-rb gem provides native bindings to the microsandbox runtime via
+  a Rust extension (magnus). It spins up real microVMs (not containers) in under
+  100ms, runs standard OCI (Docker) images, and gives you full control over
+  command execution, the guest filesystem, networking, volumes, snapshots, SSH,
+  and secrets — all from an idiomatic, synchronous Ruby API. No daemon, no server
+  to connect to: the runtime is embedded directly in your process.
+email:
+- luotao@hey.com
+executables: []
+extensions:
+- ext/microsandbox/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Cargo.lock
+- Cargo.toml
+- DESIGN.md
+- LICENSE
+- README.md
+- ext/microsandbox/Cargo.toml
+- ext/microsandbox/extconf.rb
+- ext/microsandbox/src/conv.rs
+- ext/microsandbox/src/error.rs
+- ext/microsandbox/src/exec.rs
+- ext/microsandbox/src/image.rs
+- ext/microsandbox/src/lib.rs
+- ext/microsandbox/src/runtime.rs
+- ext/microsandbox/src/sandbox.rs
+- ext/microsandbox/src/snapshot.rs
+- ext/microsandbox/src/stream.rs
+- ext/microsandbox/src/volume.rs
+- lib/microsandbox.rb
+- lib/microsandbox/errors.rb
+- lib/microsandbox/exec_handle.rb
+- lib/microsandbox/exec_output.rb
+- lib/microsandbox/fs.rb
+- lib/microsandbox/image.rb
+- lib/microsandbox/log_entry.rb
+- lib/microsandbox/metrics.rb
+- lib/microsandbox/sandbox.rb
+- lib/microsandbox/snapshot.rb
+- lib/microsandbox/streams.rb
+- lib/microsandbox/version.rb
+- lib/microsandbox/volume.rb
+- rust-toolchain.toml
+- sig/microsandbox.rbs
+homepage: https://github.com/ya-luotao/microsandbox-rb
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/ya-luotao/microsandbox-rb
+  source_code_uri: https://github.com/ya-luotao/microsandbox-rb
+  documentation_uri: https://github.com/ya-luotao/microsandbox-rb#readme
+  changelog_uri: https://github.com/ya-luotao/microsandbox-rb/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: microsandbox_rb
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.11
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Lightweight microVM sandboxes for Ruby — run AI agents and untrusted code
+  with hardware-level isolation.
+test_files: []