microsandbox-rb 0.5.7

data/lib/microsandbox/sandbox.rb

@@ -0,0 +1,461 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # Lightweight metadata about a sandbox, returned by {Sandbox.get} and
+  # {Sandbox.list}. This is a snapshot, not a live handle.
+  class SandboxInfo
+    # @return [String]
+    attr_reader :name
+    # @return [Symbol] :running, :draining, :paused, :stopped, or :crashed
+    attr_reader :status
+
+    def initialize(data)
+      @name = data["name"]
+      @status = data["status"].to_sym
+      @created_at_ms = data["created_at_ms"]
+      @updated_at_ms = data["updated_at_ms"]
+    end
+
+    def running? = @status == :running
+    def stopped? = @status == :stopped
+
+    # @return [Time, nil]
+    def created_at
+      @created_at_ms && Time.at(@created_at_ms / 1000.0)
+    end
+
+    # @return [Time, nil]
+    def updated_at
+      @updated_at_ms && Time.at(@updated_at_ms / 1000.0)
+    end
+
+    def inspect
+      "#<Microsandbox::SandboxInfo name=#{@name.inspect} status=#{@status}>"
+    end
+  end
+
+  # The terminal observation of a stopped sandbox, returned by
+  # {Sandbox#wait_until_stopped}. Mirrors the official SDKs' `SandboxStopResult`.
+  class SandboxStopResult
+    # @return [String]
+    attr_reader :name
+    # @return [Symbol] :running, :draining, :paused, :stopped, or :crashed
+    attr_reader :status
+    # @return [Integer, nil] process exit code, when observed from an owned child
+    attr_reader :exit_code
+    # @return [Integer, nil] terminating signal, when observed from an owned child
+    attr_reader :signal
+    # @return [String, nil] human description of the observation source
+    attr_reader :source
+
+    def initialize(data)
+      @name = data["name"]
+      @status = data["status"].to_sym
+      @exit_code = data["exit_code"]
+      @signal = data["signal"]
+      @source = data["source"]
+      @observed_at_ms = data["observed_at_ms"]
+    end
+
+    def stopped? = @status == :stopped
+    def crashed? = @status == :crashed
+
+    # @return [Time] when the stopped state was observed
+    def observed_at
+      Time.at(@observed_at_ms / 1000.0)
+    end
+
+    def inspect
+      "#<Microsandbox::SandboxStopResult name=#{@name.inspect} status=#{@status}" \
+        "#{@exit_code ? " exit_code=#{@exit_code}" : ""}#{@signal ? " signal=#{@signal}" : ""}>"
+    end
+  end
+
+  # A running sandbox (microVM) — the primary entry point of the SDK.
+  #
+  # @example Block form (auto-stops on exit)
+  #   Microsandbox::Sandbox.create("hello", image: "python") do |sb|
+  #     out = sb.exec("python", ["-c", "print('hi')"])
+  #     puts out.stdout
+  #   end
+  #
+  # @example Manual lifecycle
+  #   sb = Microsandbox::Sandbox.create("hello", image: "python")
+  #   begin
+  #     sb.shell("echo hi")
+  #   ensure
+  #     sb.stop
+  #   end
+  class Sandbox
+    class << self
+      # Create and boot a sandbox.
+      #
+      # When a block is given the sandbox is yielded and stopped automatically
+      # when the block returns (the block's value is returned); otherwise the
+      # live {Sandbox} is returned and you are responsible for calling {#stop}.
+      #
+      # @param name [String] sandbox name (max 128 UTF-8 bytes)
+      # @param image [String, nil] OCI image reference (e.g. "python")
+      # @param cpus [Integer, nil] number of vCPUs
+      # @param memory [Integer, nil] memory in MiB
+      # @param env [Hash, nil] environment variables
+      # @param workdir [String, nil] working directory inside the guest
+      # @param shell [String, nil] default shell (for {#shell})
+      # @param user [String, nil] default user
+      # @param hostname [String, nil] guest hostname
+      # @param labels [Hash, nil] metadata labels
+      # @param scripts [Hash, nil] named scripts to install
+      # @param entrypoint [Array<String>, nil] image entrypoint override
+      # @param ports [Hash, nil] host_port => guest_port TCP publications
+      # @param ports_udp [Hash, nil] host_port => guest_port UDP publications
+      # @param network ["public_only", "none", "allow_all", "non_local", nil] network
+      #   policy preset (default public_only)
+      # @param log_level ["error","warn","info","debug","trace", nil] guest log verbosity
+      # @param quiet_logs [Boolean] suppress sandbox process logs
+      # @param security ["default", "restricted", nil] exec security profile
+      # @param oci_upper_size [Integer, nil] writable upper-layer size cap, in MiB
+      # @param max_duration [Integer, nil] hard wall-clock lifetime, in seconds
+      # @param idle_timeout [Integer, nil] stop after this many idle seconds
+      # @param rlimits [Hash, nil] resource limits: { resource => limit } or
+      #   { resource => [soft, hard] } (e.g. { nofile: 65_535 })
+      # @param pull_policy ["always","if-missing","never", nil] image pull behavior
+      # @param secrets [Array<Hash>, nil] placeholder-protected secrets, each
+      #   { env:, value:, host: } — the value is substituted by the TLS proxy only
+      #   for the allowed host (auto-enables TLS interception)
+      # @param detached [Boolean] keep running after this process exits
+      # @param replace [Boolean] replace an existing sandbox with the same name
+      # @param replace_with_timeout [Numeric, nil] replace, waiting up to N seconds
+      # @yieldparam sandbox [Sandbox]
+      # @return [Sandbox, Object] the sandbox, or the block's return value
+      def create(name,
+                 image: nil, cpus: nil, memory: nil, env: nil, workdir: nil,
+                 shell: nil, user: nil, hostname: nil, labels: nil, scripts: nil,
+                 entrypoint: nil, ports: nil, ports_udp: nil, volumes: nil, network: nil,
+                 from_snapshot: nil, log_level: nil, quiet_logs: false, security: nil,
+                 oci_upper_size: nil, max_duration: nil, idle_timeout: nil, rlimits: nil,
+                 pull_policy: nil, secrets: nil,
+                 detached: false, replace: false, replace_with_timeout: nil)
+        opts = {}
+        opts["image"] = image.to_s if image
+        opts["from_snapshot"] = from_snapshot.to_s if from_snapshot
+        opts["cpus"] = Integer(cpus) if cpus
+        opts["memory"] = Integer(memory) if memory
+        opts["workdir"] = workdir.to_s if workdir
+        opts["shell"] = shell.to_s if shell
+        opts["user"] = user.to_s if user
+        opts["hostname"] = hostname.to_s if hostname
+        opts["env"] = stringify(env) if env
+        opts["labels"] = stringify(labels) if labels
+        opts["scripts"] = stringify(scripts) if scripts
+        opts["entrypoint"] = Array(entrypoint).map(&:to_s) if entrypoint
+        opts["ports"] = intify_ports(ports) if ports
+        opts["ports_udp"] = intify_ports(ports_udp) if ports_udp
+        opts["volumes"] = normalize_volumes(volumes) if volumes
+        opts["network"] = network.to_s if network
+        opts["log_level"] = log_level.to_s if log_level
+        opts["quiet_logs"] = true if quiet_logs
+        opts["security"] = security.to_s if security
+        opts["oci_upper_size"] = Integer(oci_upper_size) if oci_upper_size
+        opts["max_duration"] = Integer(max_duration) if max_duration
+        opts["idle_timeout"] = Integer(idle_timeout) if idle_timeout
+        opts["rlimits"] = normalize_rlimits(rlimits) if rlimits
+        opts["pull_policy"] = pull_policy.to_s if pull_policy
+        opts["secrets"] = normalize_secrets(secrets) if secrets
+        opts["detached"] = true if detached
+        if replace_with_timeout
+          opts["replace_with_timeout"] = Float(replace_with_timeout)
+        elsif replace
+          opts["replace"] = true
+        end
+
+        sandbox = new(Native::Sandbox.create(name.to_s, opts))
+        return sandbox unless block_given?
+
+        begin
+          yield sandbox
+        ensure
+          begin
+            sandbox.stop
+          rescue Microsandbox::Error
+            # best-effort cleanup; ignore stop failures during teardown
+          end
+        end
+      end
+
+      # Restart a previously-defined sandbox by name.
+      # @return [Sandbox]
+      def start(name, detached: false)
+        new(Native::Sandbox.start(name.to_s, { "detached" => detached }))
+      end
+
+      # Fetch metadata for a sandbox by name.
+      # @return [SandboxInfo]
+      def get(name)
+        SandboxInfo.new(Native::Sandbox.get(name.to_s))
+      end
+
+      # List all sandboxes.
+      # @return [Array<SandboxInfo>]
+      def list
+        Native::Sandbox.list.map { |info| SandboxInfo.new(info) }
+      end
+
+      # List sandboxes carrying all of the given labels (AND-matched).
+      # @param labels [Hash] required key => value labels
+      # @return [Array<SandboxInfo>]
+      def list_with(labels: {})
+        opts = { "labels" => stringify(labels) }
+        Native::Sandbox.list_with(opts).map { |info| SandboxInfo.new(info) }
+      end
+
+      # Remove a (stopped) sandbox by name.
+      # @return [nil]
+      def remove(name)
+        Native::Sandbox.remove(name.to_s)
+        nil
+      end
+
+      private
+
+      def stringify(hash)
+        hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v.to_s }
+      end
+
+      def intify_ports(ports)
+        ports.each_with_object({}) { |(k, v), acc| acc[Integer(k)] = Integer(v) }
+      end
+
+      # Normalize secrets into [env, value, host] triples for the native layer.
+      # Each entry is a Hash { env:, value:, host: } (string or symbol keys).
+      def normalize_secrets(secrets)
+        Array(secrets).map do |spec|
+          env = spec[:env] || spec["env"]
+          value = spec[:value] || spec["value"]
+          host = spec[:host] || spec["host"]
+          unless env && value && host
+            raise ArgumentError, "secret spec needs :env, :value, and :host (got #{spec.inspect})"
+          end
+          [env.to_s, value.to_s, host.to_s]
+        end
+      end
+
+      # Normalize an rlimits Hash into [resource, soft, hard] triples for the
+      # native layer. Each value is either a single limit (soft == hard) or a
+      # [soft, hard] pair. Shared by {Sandbox.create} and {Sandbox#exec}.
+      def normalize_rlimits(rlimits)
+        rlimits.map do |resource, limit|
+          soft, hard = limit.is_a?(Array) ? [limit[0], limit[1]] : [limit, limit]
+          [resource.to_s, Integer(soft), Integer(hard)]
+        end
+      end
+
+      # Normalize volumes (Hash of guest_path => spec) into [guest, kind, source]
+      # triples for the native layer. A spec is a host path String (bind mount),
+      # or a Hash { bind: "/host" } / { named: "volume-name" }.
+      def normalize_volumes(volumes)
+        volumes.map do |guest, spec|
+          guest = guest.to_s
+          case spec
+          when String
+            [guest, "bind", spec]
+          when Hash
+            if (named = spec[:named] || spec["named"])
+              [guest, "named", named.to_s]
+            elsif (bind = spec[:bind] || spec["bind"])
+              [guest, "bind", bind.to_s]
+            else
+              raise ArgumentError, "volume spec for #{guest.inspect} needs :bind or :named"
+            end
+          else
+            raise ArgumentError, "invalid volume spec for #{guest.inspect}: #{spec.inspect}"
+          end
+        end
+      end
+    end
+
+    def initialize(native)
+      @native = native
+    end
+
+    # @return [String] the sandbox name
+    def name
+      @native.name
+    end
+
+    # Run a command (no shell interpretation) and collect its output.
+    #
+    # @param command [String] the executable
+    # @param args [Array<String>] arguments
+    # @param cwd [String, nil] working directory
+    # @param user [String, nil] user to run as
+    # @param env [Hash, nil] extra environment variables
+    # @param timeout [Numeric, nil] kill after N seconds
+    # @param tty [Boolean] allocate a pseudo-terminal
+    # @param stdin [String, nil] data to feed to stdin
+    # @return [ExecOutput]
+    def exec(command, args = [], cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil)
+      ExecOutput.new(@native.exec(command.to_s, Array(args).map(&:to_s),
+                                  exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)))
+    end
+
+    # Run a shell script (pipes, redirects, etc. allowed) and collect output.
+    # @return [ExecOutput]
+    def shell(script, cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil)
+      ExecOutput.new(@native.shell(script.to_s,
+                                   exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)))
+    end
+
+    # Run a command and stream its output as it arrives.
+    # @return [ExecHandle]
+    # @see ExecHandle
+    def exec_stream(command, args = [], cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil)
+      ExecHandle.new(@native.exec_stream(command.to_s, Array(args).map(&:to_s),
+                                         exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)))
+    end
+
+    # Run a shell script and stream its output as it arrives.
+    # @return [ExecHandle]
+    def shell_stream(script, cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil)
+      ExecHandle.new(@native.shell_stream(script.to_s,
+                                          exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)))
+    end
+
+    # Guest filesystem operations.
+    # @return [FS]
+    def fs
+      @fs ||= FS.new(@native)
+    end
+
+    # Latest resource-usage snapshot.
+    # @return [Metrics]
+    def metrics
+      Metrics.new(@native.metrics)
+    end
+
+    # Read captured logs.
+    #
+    # @param tail [Integer, nil] only the last N entries
+    # @param since_ms [Numeric, nil] only entries at/after this Unix ms
+    # @param until_ms [Numeric, nil] only entries before this Unix ms
+    # @param sources [Array<String,Symbol>, nil] filter by source
+    #   ("stdout"/"stderr"/"output"/"system"/"all")
+    # @return [Array<LogEntry>]
+    def logs(tail: nil, since_ms: nil, until_ms: nil, sources: nil)
+      opts = {}
+      opts["tail"] = Integer(tail) if tail
+      opts["since_ms"] = Float(since_ms) if since_ms
+      opts["until_ms"] = Float(until_ms) if until_ms
+      opts["sources"] = Array(sources).map(&:to_s) if sources
+      @native.logs(opts).map { |entry| LogEntry.new(entry) }
+    end
+
+    # Stream resource-usage snapshots, one per interval tick, until the sandbox
+    # stops. Requires metrics to be enabled for the sandbox.
+    # @param interval [Numeric] seconds between snapshots
+    # @return [MetricsStream] an {Enumerable} of {Metrics}
+    def metrics_stream(interval: 1.0)
+      MetricsStream.new(@native.metrics_stream(Float(interval)))
+    end
+
+    # Stream captured logs as they appear.
+    #
+    # @param sources [Array<String,Symbol>, nil] filter by source
+    #   ("stdout"/"stderr"/"output"/"system")
+    # @param since_ms [Numeric, nil] start at the first entry at/after this Unix ms
+    # @param from_cursor [String, nil] resume exactly after a prior {LogEntry#cursor}
+    #   (mutually exclusive with since_ms; takes precedence if both given)
+    # @param until_ms [Numeric, nil] stop before any entry at/after this Unix ms
+    # @param follow [Boolean] keep the stream open for new entries past current EOF
+    # @return [LogStream] an {Enumerable} of {LogEntry}
+    def log_stream(sources: nil, since_ms: nil, from_cursor: nil, until_ms: nil, follow: false)
+      opts = {}
+      opts["sources"] = Array(sources).map(&:to_s) if sources
+      opts["since_ms"] = Float(since_ms) if since_ms
+      opts["from_cursor"] = from_cursor.to_s if from_cursor
+      opts["until_ms"] = Float(until_ms) if until_ms
+      opts["follow"] = true if follow
+      LogStream.new(@native.log_stream(opts))
+    end
+
+    # Gracefully stop the sandbox (and wait for it to terminate).
+    # @param timeout [Numeric, nil] seconds to wait before SIGKILL
+    # @return [nil]
+    def stop(timeout: nil)
+      @native.stop(timeout && Float(timeout))
+      nil
+    end
+
+    # Force-kill the sandbox (SIGKILL).
+    # @param timeout [Numeric, nil] seconds to wait
+    # @return [nil]
+    def kill(timeout: nil)
+      @native.kill(timeout && Float(timeout))
+      nil
+    end
+
+    # Send the graceful-shutdown request and return immediately, without waiting
+    # for the sandbox to terminate. Pair with {#wait_until_stopped}.
+    # @return [nil]
+    def request_stop
+      @native.request_stop
+      nil
+    end
+
+    # Send the force-kill request and return immediately, without waiting.
+    # @return [nil]
+    def request_kill
+      @native.request_kill
+      nil
+    end
+
+    # Request a graceful drain and return immediately, without waiting.
+    # @return [nil]
+    def request_drain
+      @native.request_drain
+      nil
+    end
+
+    # Block until the sandbox is observed in a terminal (non-running) state.
+    # @return [SandboxStopResult]
+    def wait_until_stopped
+      SandboxStopResult.new(@native.wait_until_stopped)
+    end
+
+    # @return [Boolean] whether this handle owns the sandbox process lifecycle
+    #   (i.e. stopping it or dropping the handle terminates the sandbox)
+    def owns_lifecycle?
+      @native.owns_lifecycle
+    end
+
+    # Detach this handle: disarm the stop-on-drop safety net so the sandbox
+    # keeps running after this handle is gone (and after this process exits).
+    # @return [nil]
+    def detach
+      @native.detach
+      nil
+    end
+
+    def inspect
+      "#<Microsandbox::Sandbox name=#{name.inspect}>"
+    end
+
+    private
+
+    def exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)
+      opts = {}
+      opts["cwd"] = cwd.to_s if cwd
+      opts["user"] = user.to_s if user
+      opts["env"] = env.each_with_object({}) { |(k, v), a| a[k.to_s] = v.to_s } if env
+      opts["timeout"] = Float(timeout) if timeout
+      opts["tty"] = true if tty
+      opts["stdin"] = stdin.to_s if stdin
+      if rlimits
+        opts["rlimits"] = rlimits.map do |resource, limit|
+          soft, hard = limit.is_a?(Array) ? [limit[0], limit[1]] : [limit, limit]
+          [resource.to_s, Integer(soft), Integer(hard)]
+        end
+      end
+      opts
+    end
+  end
+end

data/lib/microsandbox/snapshot.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # Metadata for a snapshot artifact, returned by {Snapshot.create}/{Snapshot.get}/
+  # {Snapshot.list}/{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`.
+  class SnapshotInfo
+    # @return [String] manifest digest ("sha256:…") — the canonical identity
+    attr_reader :digest
+    # @return [String] artifact directory path
+    attr_reader :path
+    # @return [String, nil] name alias (nil for digest-only entries)
+    attr_reader :name
+    # @return [String, nil] parent snapshot digest
+    attr_reader :parent_digest
+    # @return [String, nil] source OCI image reference
+    attr_reader :image_ref
+    # @return [Integer, nil] artifact size in bytes
+    attr_reader :size_bytes
+
+    def initialize(data)
+      @digest = data["digest"]
+      @path = data["path"]
+      @name = data["name"]
+      @parent_digest = data["parent_digest"]
+      @image_ref = data["image_ref"]
+      @format = data["format"]
+      @size_bytes = data["size_bytes"]
+      @created_at_ms = data["created_at_ms"]
+    end
+
+    # @return [Symbol, nil] disk format (:raw or :qcow2)
+    def format
+      @format&.to_sym
+    end
+
+    # @return [Time, nil]
+    def created_at
+      @created_at_ms && Time.at(@created_at_ms / 1000.0)
+    end
+
+    def inspect
+      "#<Microsandbox::SnapshotInfo digest=#{@digest.inspect}#{@name ? " name=#{@name.inspect}" : ""}>"
+    end
+  end
+
+  # The result of {Snapshot.verify}.
+  class SnapshotVerifyReport
+    # @return [String] manifest digest
+    attr_reader :digest
+    # @return [String] artifact directory path
+    attr_reader :path
+    # @return [Symbol] :not_recorded or :verified
+    attr_reader :status
+    # @return [String, nil] digest algorithm (when :verified)
+    attr_reader :algorithm
+    # @return [String, nil] matched content digest (when :verified)
+    attr_reader :content_digest
+
+    def initialize(data)
+      @digest = data["digest"]
+      @path = data["path"]
+      @status = data["upper_status"].to_sym
+      @algorithm = data["upper_algorithm"]
+      @content_digest = data["upper_digest"]
+    end
+
+    # @return [Boolean] whether content integrity was recorded and matched
+    def verified? = @status == :verified
+    # @return [Boolean] whether no integrity descriptor was recorded
+    def not_recorded? = @status == :not_recorded
+  end
+
+  # Creation and management of sandbox snapshots. A snapshot captures a stopped
+  # sandbox's upper layer into a portable artifact; boot from it with
+  # `Sandbox.create(from_snapshot: "name-or-digest")`.
+  class Snapshot
+    class << self
+      # Create a snapshot of a stopped sandbox.
+      #
+      # @param source_sandbox [String] name of the (stopped) source sandbox
+      # @param name [String, nil] destination name under the snapshots dir
+      # @param path [String, nil] explicit destination directory (alternative to name)
+      # @param labels [Hash, nil] user labels
+      # @param force [Boolean] overwrite an existing artifact at the destination
+      # @param record_integrity [Boolean] compute + record upper-layer integrity
+      # @return [SnapshotInfo]
+      def create(source_sandbox, name: nil, path: nil, labels: nil, force: false, record_integrity: false)
+        opts = {}
+        opts["name"] = name.to_s if name
+        opts["path"] = path.to_s if path
+        opts["labels"] = stringify(labels) if labels
+        opts["force"] = true if force
+        opts["record_integrity"] = true if record_integrity
+        SnapshotInfo.new(Native::Snapshot.create(source_sandbox.to_s, opts))
+      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.
+      # @return [Array<SnapshotInfo>]
+      def list
+        Native::Snapshot.list.map { |info| SnapshotInfo.new(info) }
+      end
+
+      # Remove a snapshot artifact by name or path.
+      # @param force [Boolean] remove even if referenced
+      # @return [nil]
+      def remove(name_or_path, force: false)
+        Native::Snapshot.remove(name_or_path.to_s, force)
+        nil
+      end
+
+      # Verify a snapshot's recorded upper-layer integrity.
+      # @return [SnapshotVerifyReport]
+      def verify(name_or_path)
+        SnapshotVerifyReport.new(Native::Snapshot.verify(name_or_path.to_s))
+      end
+
+      # Bundle a snapshot into a `.tar.zst` (or plain `.tar`) archive.
+      # @param with_parents [Boolean] include ancestor snapshots
+      # @param with_image [Boolean] include OCI image artifacts (boots offline)
+      # @param plain_tar [Boolean] write an uncompressed `.tar`
+      # @return [nil]
+      def export(name_or_path, out_path, with_parents: false, with_image: false, plain_tar: false)
+        opts = {}
+        opts["with_parents"] = true if with_parents
+        opts["with_image"] = true if with_image
+        opts["plain_tar"] = true if plain_tar
+        Native::Snapshot.export(name_or_path.to_s, out_path.to_s, opts)
+        nil
+      end
+
+      # Unpack a snapshot archive into the snapshots dir.
+      # @param dest [String, nil] explicit destination directory
+      # @return [SnapshotInfo]
+      def import(archive_path, dest: nil)
+        SnapshotInfo.new(Native::Snapshot.import(archive_path.to_s, dest && dest.to_s))
+      end
+
+      private
+
+      def stringify(hash)
+        hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v.to_s }
+      end
+    end
+  end
+end

data/lib/microsandbox/streams.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # A live stream of {LogEntry}s, returned by {Sandbox#log_stream}. Enumerable:
+  # iterate to consume entries as they are appended. With `follow: true` the
+  # iteration blocks for new entries until the sandbox stops; otherwise it ends
+  # once the historical log is drained.
+  #
+  # @example
+  #   sb.log_stream(follow: true).each { |entry| print entry.text }
+  class LogStream
+    include Enumerable
+
+    def initialize(native)
+      @native = native
+    end
+
+    # @yieldparam entry [LogEntry]
+    # @return [self, Enumerator]
+    def each
+      return enum_for(:each) unless block_given?
+
+      while (entry = @native.recv)
+        yield LogEntry.new(entry)
+      end
+      self
+    end
+  end
+
+  # A live stream of {Metrics} snapshots, returned by {Sandbox#metrics_stream}.
+  # Enumerable: iteration yields one snapshot per interval tick until the
+  # sandbox stops.
+  #
+  # @example
+  #   sb.metrics_stream(interval: 0.5).each { |m| puts m.cpu_percent }
+  class MetricsStream
+    include Enumerable
+
+    def initialize(native)
+      @native = native
+    end
+
+    # @yieldparam metrics [Metrics]
+    # @return [self, Enumerator]
+    def each
+      return enum_for(:each) unless block_given?
+
+      while (snapshot = @native.recv)
+        yield Metrics.new(snapshot)
+      end
+      self
+    end
+  end
+end

data/lib/microsandbox/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # Gem version. Kept in lock-step with the upstream microsandbox runtime and
+  # the official Python/Node/Go SDKs (workspace version in the microsandbox repo).
+  VERSION = "0.5.7"
+end