microsandbox-rb 0.16.0 → 0.17.1

data/lib/microsandbox/outbound_proxy.rb

@@ -0,0 +1,340 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # Host-side source for secret material (runtime v0.6.17). The only kind is
+  # `env`: the secret is read from an environment variable of the **host**
+  # process (the one running this gem) when the sandbox is created — the
+  # variable's *name* travels to the runtime, never its value.
+  #
+  # Used for the password of an authenticated SOCKS5 {OutboundProxy}. Mirrors
+  # the Python SDK's frozen `SecretSource` dataclass.
+  #
+  # @example
+  #   Microsandbox::SecretSource.env("PROXY_PASSWORD")
+  class SecretSource
+    KINDS = %w[env].freeze
+
+    # @return [String] the source kind (always `"env"`)
+    attr_reader :kind
+    # @return [String] the host environment variable name
+    attr_reader :var
+
+    # Resolve the secret from a host environment variable.
+    # @param variable [String, Symbol] the variable name (non-empty)
+    # @return [SecretSource]
+    def self.env(variable)
+      new("env", variable)
+    end
+
+    # Coerce a user-facing value into a {SecretSource}: an instance passes
+    # through, a Hash must be `{ env: "VAR" }` or the wire form
+    # `{ kind: "env", var: "VAR" }`.
+    #
+    # A rejected value is NEVER rendered into the error: a caller who reaches
+    # for `{ value: "hunter2" }` or `{ store: ... }` by analogy with other
+    # secret APIs has just handed us a real password, and the exception
+    # message is the one place it must not resurface (logs, bug reports).
+    # Errors describe the expected shape and, at most, the offending class.
+    # @api private
+    def self.coerce(value, context = "password")
+      case value
+      when SecretSource then value
+      when Hash
+        env = fetch_key(value, :env)
+        return new("env", env) unless env.nil?
+
+        kind = fetch_key(value, :kind)
+        var = fetch_key(value, :var)
+        if kind.nil? && var.nil?
+          raise ArgumentError,
+            "#{context}: expects { env: \"VAR\" } naming a host environment variable " \
+            "(got a Hash without env:; plaintext password values are not accepted)"
+        end
+        new(kind, var)
+      else
+        raise ArgumentError,
+          "#{context}: expects a Microsandbox::SecretSource (SecretSource.env(\"VAR\")) " \
+          "or a Hash { env: \"VAR\" } (got #{value.class}; plaintext password values " \
+          "are not accepted)"
+      end
+    end
+
+    # @api private
+    def self.fetch_key(hash, key)
+      hash.key?(key) ? hash[key] : hash[key.to_s]
+    end
+    private_class_method :fetch_key
+
+    # @api private — use {.env}.
+    #
+    # Retained Strings are private frozen copies: the caller's originals are
+    # neither frozen nor aliased, so mutating them later (or a String obtained
+    # from {#var}/{#to_h}) cannot change this object's state. Only a
+    # String/Symbol kind or var is described in an error, and only by the
+    # allowed-shape wording — a nested Hash/other object is named by class so
+    # a misplaced secret is never rendered.
+    def initialize(kind, var)
+      unless kind.is_a?(String) || kind.is_a?(Symbol)
+        raise ArgumentError,
+          "secret source kind must be \"env\" (got #{kind.class})"
+      end
+      # An unsupported kind is reported by class only, never by value: a
+      # caller who mis-keys a password into `kind:` must not see it echoed.
+      unless KINDS.include?(kind.to_s)
+        raise ArgumentError,
+          "secret source kind must be \"env\" (only environment-backed secret sources " \
+          "are supported; got an unsupported #{kind.class})"
+      end
+      kind = kind.to_s
+      unless var.is_a?(String) || var.is_a?(Symbol)
+        raise ArgumentError,
+          "secret source environment variable must be a String name (got #{var.class})"
+      end
+      var = var.to_s
+      raise ArgumentError, "secret source environment variable must not be empty" if var.empty?
+      @kind = kind.dup.freeze
+      @var = var.dup.freeze
+      freeze
+    end
+
+    # Wire form for the native layer (Python's `_to_dict`).
+    # @return [Hash{String => String}]
+    def to_h
+      {"kind" => @kind, "var" => @var}
+    end
+
+    def ==(other)
+      other.is_a?(SecretSource) && other.kind == kind && other.var == var
+    end
+    alias_method :eql?, :==
+
+    def hash
+      [SecretSource, @kind, @var].hash
+    end
+
+    def inspect
+      "#<Microsandbox::SecretSource env=#{@var}>"
+    end
+  end
+
+  # An outbound proxy for a sandbox's egress traffic (runtime v0.6.17, upstream
+  # #1234 / #1507), passed to {Sandbox.create} via `proxy:`. The runtime's
+  # host-side network stack dials the proxy — so the address is resolved from
+  # the **host**, and `127.0.0.1` names the host's loopback, not the guest's.
+  #
+  # - {socks4} — SOCKS4 for TCP, with an optional `user_id:` sent in the
+  #   handshake.
+  # - {socks5} — SOCKS5 for TCP and non-DNS UDP; chain {#credentials} for
+  #   username/password authentication, the password coming from a host
+  #   {SecretSource} (only its variable name reaches the runtime).
+  #
+  # The proxy applies uniformly to TLS-intercepted and bypassed/plain TCP; the
+  # egress policy (`network:`) still decides which destinations may be reached.
+  # Not accepted by the cloud backend (`UnsupportedError`).
+  #
+  # Instances are immutable: {#credentials} returns a new proxy. `proxy:` also
+  # accepts the equivalent plain Hash (see {.coerce}).
+  #
+  # @example
+  #   Sandbox.create("worker", image: "python",
+  #     proxy: Microsandbox::OutboundProxy.socks5("127.0.0.1:1080"))
+  #   Sandbox.create("worker", image: "python",
+  #     proxy: Microsandbox::OutboundProxy.socks5("10.0.0.5:1080")
+  #       .credentials("sandbox", Microsandbox::SecretSource.env("PROXY_PASSWORD")))
+  #   Sandbox.create("worker", image: "python",
+  #     proxy: { protocol: :socks4, address: "127.0.0.1:1080", user_id: "ci" })
+  #
+  # Mirrors the Python SDK's frozen `OutboundProxy` dataclass (`socks4` /
+  # `socks5` / `credentials`).
+  class OutboundProxy
+    PROTOCOLS = %w[socks4 socks5].freeze
+
+    # @return [String] `"socks4"` or `"socks5"`
+    attr_reader :protocol
+    # @return [String] the proxy's `IP:port` address, as seen from the host
+    attr_reader :address
+    # @return [String, nil] SOCKS4 user ID
+    attr_reader :user_id
+    # @return [String, nil] SOCKS5 username
+    attr_reader :username
+    # @return [SecretSource, nil] SOCKS5 password source
+    attr_reader :password
+
+    # A SOCKS4 outbound proxy.
+    # @param address [String] `IP:port` of the proxy, resolved from the host
+    # @param user_id [String, nil] optional user ID sent in the SOCKS4 handshake
+    # @return [OutboundProxy]
+    def self.socks4(address, user_id: nil)
+      new(protocol: "socks4", address: address, user_id: user_id)
+    end
+
+    # A SOCKS5 outbound proxy (unauthenticated; chain {#credentials}).
+    # @param address [String] `IP:port` of the proxy, resolved from the host
+    # @return [OutboundProxy]
+    def self.socks5(address)
+      new(protocol: "socks5", address: address)
+    end
+
+    # Coerce a user-facing `proxy:` value into the normalized wire Hash:
+    # an {OutboundProxy}, or a Hash `{ protocol: :socks4|:socks5, address:,
+    # user_id:, credentials: { username:, password: SecretSource | { env: } } }`.
+    # @api private
+    # @return [Hash{String => untyped}]
+    def self.coerce(value)
+      case value
+      # No re-validation for an existing instance, and none is needed: the
+      # constructor is the only writer, the object is frozen (no ivar can be
+      # reassigned), and every retained String is a private frozen copy, so
+      # {#to_h} is a pure function of already-validated state. Re-running the
+      # checks would only re-examine data the constructor itself produced.
+      when OutboundProxy then value.to_h
+      when Hash then from_hash(value).to_h
+      else
+        raise ArgumentError,
+          "proxy: expects a Microsandbox::OutboundProxy (OutboundProxy.socks4/socks5) " \
+          "or a Hash { protocol:, address:, ... } (got #{value.class})"
+      end
+    end
+
+    # @api private
+    def self.from_hash(hash)
+      protocol = fetch_key(hash, :protocol)
+      raise ArgumentError, "proxy: requires protocol: (:socks4 or :socks5)" if protocol.nil?
+      address = fetch_key(hash, :address)
+      raise ArgumentError, "proxy: requires address:" if address.nil?
+      user_id = fetch_key(hash, :user_id)
+      credentials = fetch_key(hash, :credentials)
+      username = nil
+      password = nil
+      unless credentials.nil?
+        unless credentials.is_a?(Hash)
+          raise ArgumentError,
+            "proxy credentials: must be a Hash { username:, password: } (got #{credentials.class})"
+        end
+        username = fetch_key(credentials, :username)
+        password = fetch_key(credentials, :password)
+        if username.nil? || password.nil?
+          raise ArgumentError, "proxy credentials: requires both username: and password:"
+        end
+        password = SecretSource.coerce(password, "proxy credentials password")
+      end
+      new(protocol: protocol, address: address, user_id: user_id,
+        username: username, password: password)
+    end
+
+    # @api private
+    def self.fetch_key(hash, key)
+      hash.key?(key) ? hash[key] : hash[key.to_s]
+    end
+    private_class_method :fetch_key
+
+    # @api private — use {.socks4} / {.socks5}.
+    def initialize(protocol:, address:, user_id: nil, username: nil, password: nil)
+      unless protocol.is_a?(String) || protocol.is_a?(Symbol)
+        raise ArgumentError,
+          "unsupported outbound proxy protocol (got #{protocol.class}; expected :socks4 or :socks5)"
+      end
+      protocol = protocol.to_s.downcase
+      unless PROTOCOLS.include?(protocol)
+        raise ArgumentError,
+          "unsupported outbound proxy protocol (expected :socks4 or :socks5)"
+      end
+      unless address.is_a?(String)
+        raise ArgumentError,
+          "proxy address must be a non-empty \"IP:port\" String (got #{address.class})"
+      end
+      if address.empty?
+        raise ArgumentError, "proxy address must be a non-empty \"IP:port\" String (got \"\")"
+      end
+      # A URL-style address (`socks5://user:pass@host:1080`) is never valid, and
+      # the core would quote it back in its error. Refuse it by shape, without
+      # echoing it, so the embedded credentials stay out of logs.
+      if address.match?(%r{@|://|\s})
+        raise ArgumentError,
+          "proxy address must be \"IP:port\" with no scheme, credentials or whitespace " \
+          "(pass SOCKS5 credentials as username:/password:)"
+      end
+      # Same rules as the Python SDK's OutboundProxy.__post_init__; the address
+      # itself is parsed by the core (which reports e.g. "invalid SOCKS5 proxy
+      # address" as an InvalidConfigError at create time).
+      # Identifiers are documented as Strings (RBS: String?). A misplaced
+      # container (a credentials Hash, an Array) must not be stringified into
+      # the wire hash / #inspect; reject it by class, never rendering it.
+      unless user_id.nil? || user_id.is_a?(String) || user_id.is_a?(Symbol)
+        raise ArgumentError, "SOCKS4 user_id must be a String (got #{user_id.class})"
+      end
+      unless username.nil? || username.is_a?(String) || username.is_a?(Symbol)
+        raise ArgumentError, "SOCKS5 username must be a String (got #{username.class})"
+      end
+      if protocol != "socks4" && !user_id.nil?
+        raise ArgumentError, "user_id is only supported for SOCKS4 proxies"
+      end
+      if protocol != "socks5" && !(username.nil? && password.nil?)
+        raise ArgumentError, "credentials are only supported for SOCKS5 proxies"
+      end
+      if username.nil? != password.nil?
+        raise ArgumentError, "SOCKS5 username and password must be provided together"
+      end
+      unless password.nil? || password.is_a?(SecretSource)
+        raise ArgumentError,
+          "SOCKS5 password must be a Microsandbox::SecretSource (SecretSource.env(\"VAR\")), " \
+          "got #{password.class}"
+      end
+      # Private frozen copies (see SecretSource#initialize): the caller keeps
+      # its own, unfrozen Strings; readers and {#to_h} hand out these frozen
+      # ones, so neither side can mutate stored state after construction.
+      @protocol = protocol.dup.freeze
+      @address = address.dup.freeze
+      @user_id = user_id&.to_s&.dup&.freeze
+      @username = username&.to_s&.dup&.freeze
+      @password = password
+      freeze
+    end
+
+    # Username/password authentication for a SOCKS5 proxy. Returns a **new**
+    # proxy; the receiver is unchanged.
+    # @param username [String]
+    # @param password [SecretSource] host-side password source
+    #   ({SecretSource.env}); its variable *name* is what reaches the runtime
+    # @return [OutboundProxy]
+    # @raise [ArgumentError] on a SOCKS4 proxy
+    def credentials(username, password)
+      raise ArgumentError, "credentials are only supported for SOCKS5 proxies" unless socks5?
+      self.class.new(protocol: @protocol, address: @address,
+        username: username, password: SecretSource.coerce(password, "proxy credentials password"))
+    end
+
+    def socks4? = @protocol == "socks4"
+
+    def socks5? = @protocol == "socks5"
+
+    # Wire form for the native layer (Python's `_to_dict`): `user_id` only when
+    # set, `credentials` only when both halves are set.
+    # @return [Hash{String => untyped}]
+    def to_h
+      h = {"protocol" => @protocol, "address" => @address}
+      h["user_id"] = @user_id unless @user_id.nil?
+      if @username && @password
+        h["credentials"] = {"username" => @username, "password" => @password.to_h}
+      end
+      h
+    end
+
+    def ==(other)
+      other.is_a?(OutboundProxy) && other.to_h == to_h
+    end
+    alias_method :eql?, :==
+
+    def hash
+      [OutboundProxy, to_h].hash
+    end
+
+    # Never renders a password value — there is none; only the env var name.
+    def inspect
+      parts = ["#{@protocol} #{@address}"]
+      parts << "user_id=#{@user_id}" if @user_id
+      parts << "username=#{@username} password=env:#{@password.var}" if @username
+      "#<Microsandbox::OutboundProxy #{parts.join(" ")}>"
+    end
+  end
+end

data/lib/microsandbox/sandbox.rb

@@ -42,13 +42,13 @@ module Microsandbox
     # @return [Time, nil]
     def created_at
       ms = @native.created_at_ms
-      ms && Time.at(ms / 1000.0)
+      Microsandbox.time_from_ms(ms)
     end
 
     # @return [Time, nil]
     def updated_at
       ms = @native.updated_at_ms
-      ms && Time.at(ms / 1000.0)
+      Microsandbox.time_from_ms(ms)
     end
 
     # Gracefully stop the sandbox (SIGTERM→SIGKILL escalation, 10s default).
@@ -263,7 +263,7 @@ module Microsandbox
 
     # @return [Time] when the stopped state was observed
     def observed_at
-      Time.at(@observed_at_ms / 1000.0)
+      Microsandbox.time_from_ms(@observed_at_ms)
     end
 
     def inspect
@@ -408,12 +408,28 @@ module Microsandbox
       # @param ipv6_pool [String, nil] guest IPv6 address pool CIDR
       # @param max_connections [Integer, nil] cap on concurrent proxied connections
       # @param trust_host_cas [Boolean, nil] trust the host's CA bundle for upstream TLS
+      # @param strict [Boolean, nil] strict hostname-policy mode (runtime
+      #   v0.6.18, default false): a hostname-rule allow must be backed by an
+      #   inspectable request authority — plain-HTTP `Host`, or SNI/authority
+      #   under TLS interception. Without that visibility (e.g. bypassed or
+      #   non-intercepted HTTPS) a flow allowed only by a hostname rule is
+      #   denied before the upstream dial. Create-only; `modify` cannot change it.
       # @param rate_limiter [Hash, nil] per-sandbox egress/ingress token-bucket
       #   limits (runtime v0.6.9, local backend):
       #   `{ egress: { bandwidth: { size: 1_048_576, refill_time_ms: 1000,
       #   one_time_burst: 0 }, ops: { size: 1000, refill_time_ms: 1000 } },
       #   ingress: { ... } }`. `bandwidth` buckets meter bytes, `ops` buckets
       #   meter network frames; an omitted bucket or direction is unlimited.
+      # @param proxy [OutboundProxy, Hash, nil] outbound SOCKS proxy for the
+      #   sandbox's egress traffic (runtime v0.6.17, local backend):
+      #   {OutboundProxy.socks4}(address, user_id:) or {OutboundProxy.socks5}
+      #   (address), optionally `.credentials(username, SecretSource.env("VAR"))`
+      #   — or the equivalent Hash `{ protocol: :socks5, address: "IP:port",
+      #   credentials: { username:, password: { env: "VAR" } } }`. The address is
+      #   dialed from the host; only the password's env var *name* is sent. The
+      #   cloud backend rejects it with {UnsupportedError}. An unparseable
+      #   address is rejected by the core at create time with
+      #   {InvalidConfigError}, before any boot.
       # @param vsock [Hash, Array, nil] host sockets exposed on guest-to-host
       #   vsock ports (runtime v0.6.9): `{ "/host/api.sock" => 5000 }` (stream
       #   sockets), or an Array of
@@ -479,6 +495,7 @@ module Microsandbox
       # @return [Sandbox, Object] the sandbox, or the block's return value
       def create(name, **kwargs, &block)
         opts = build_create_opts(**kwargs)
+        Microsandbox.ensure_runtime!
         sandbox = new(Native::Sandbox.create(name.to_s, opts))
         return sandbox unless block_given?
 
@@ -535,6 +552,7 @@ module Microsandbox
       # @return [Sandbox, Object] the live sandbox, or the block's return value
       def connect_or_create(name, **kwargs, &block)
         opts = build_create_opts(**kwargs)
+        Microsandbox.ensure_runtime!
         sandbox = new(Native::Sandbox.connect_or_create(name.to_s, opts))
         return sandbox unless block_given?
 
@@ -566,17 +584,22 @@ module Microsandbox
             "for progress, then call #sandbox and stop it when done"
         end
         opts = build_create_opts(**kwargs)
+        Microsandbox.ensure_runtime!
         PullSession.new(Native::Sandbox.create_with_progress(name.to_s, opts))
       end
 
       # @api private
-      # Shared keyword-option builder for {create}/{create_with_progress}.
+      # Shared keyword-option builder for {create}/{connect_or_create}/
+      # {create_with_progress}. Pure validation and normalization: the callers
+      # provision the runtime ({Microsandbox.ensure_runtime!}) only after this
+      # returns, so a rejected option never triggers a runtime download.
       def build_create_opts(image: nil, cpus: nil, max_cpus: nil, memory: nil, max_memory: nil,
         env: nil, workdir: nil,
         shell: nil, user: nil, hostname: nil, labels: nil, scripts: nil,
         entrypoint: nil, cmd: nil, ports: nil, ports_udp: nil, volumes: nil, network: nil,
         dns: nil, tls: nil, ipv4_pool: nil, ipv6_pool: nil,
-        max_connections: nil, trust_host_cas: nil, rate_limiter: nil, vsock: nil,
+        max_connections: nil, trust_host_cas: nil, strict: nil, rate_limiter: nil, proxy: nil,
+        vsock: nil,
         patches: nil,
         from_snapshot: nil, fstype: nil, init: nil, ephemeral: false,
         log_level: nil, quiet_logs: false, security: nil,
@@ -593,7 +616,14 @@ module Microsandbox
         if root_disk && oci_upper_size
           raise ArgumentError, "pass either root_disk: or oci_upper_size:, not both"
         end
-        Microsandbox.ensure_runtime!
+        # The core refuses patches on a snapshot-booted sandbox, but only after
+        # it has claimed the sandbox name on disk. Refuse the pair before any
+        # side effect.
+        if from_snapshot && patches && !Array(patches).empty?
+          raise ArgumentError,
+            "patches: cannot be combined with from_snapshot: (a snapshot restores its own " \
+            "root disk; apply changes after boot with sandbox.fs instead)"
+        end
         # `fstype:` names the inner filesystem of a disk-image rootfs, so it only
         # applies when `image:` is a disk-image path (a local path ending in
         # .raw/.qcow2/.vmdk). Routing an OCI ref (e.g. "python") through the
@@ -637,7 +667,9 @@ module Microsandbox
         opts["ipv6_pool"] = ipv6_pool.to_s if ipv6_pool
         opts["max_connections"] = Integer(max_connections) if max_connections
         set_bool(opts, "trust_host_cas", trust_host_cas)
+        set_bool(opts, "strict", strict)
         opts["rate_limiter"] = normalize_rate_limiter(rate_limiter) if rate_limiter
+        opts["proxy"] = OutboundProxy.coerce(proxy) unless proxy.nil?
         opts["vsock"] = normalize_vsock(vsock) if vsock
         opts["log_level"] = log_level.to_s if log_level
         opts["quiet_logs"] = true if quiet_logs
@@ -760,7 +792,16 @@ module Microsandbox
       end
 
       def stringify(hash)
-        hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v.to_s }
+        # Anything that converts to pairs is fine (a Hash, ENV, an Array of
+        # pairs). For the rest, name the type, not the value: env values are
+        # often credentials.
+        pairs = begin
+          hash.to_h if hash.respond_to?(:to_h)
+        rescue TypeError
+          nil
+        end
+        raise ArgumentError, "expected a Hash of names to values (got #{hash.class})" unless pairs
+        pairs.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v.to_s }
       end
 
       # Wrap a native page Hash ({"sandboxes" => [...], "next_cursor" => ...})
@@ -825,7 +866,21 @@ module Microsandbox
       # :inject_basic_auth / :inject_query / :inject_body, and :on_violation (see
       # {#normalize_violation}).
       def normalize_secrets(secrets)
-        Array(secrets).map { |spec| normalize_secret(spec) }
+        if secrets.is_a?(Hash)
+          # One spec given bare is fine. A Hash keyed by variable name is the
+          # shape {Sandbox#modify} takes, where `env:` also means something
+          # else (the HOST variable to read); it is not a create-time spec.
+          unless secrets.key?(:env) || secrets.key?("env")
+            raise ArgumentError,
+              "secrets: takes an Array of Hashes like { env:, value:, host: } at create time; " \
+              "the { \"NAME\" => { ... } } form belongs to #modify"
+          end
+          secrets = [secrets]
+        end
+        Array(secrets).map do |spec|
+          raise ArgumentError, "secret spec must be a Hash (got #{spec.class})" unless spec.is_a?(Hash)
+          normalize_secret(spec)
+        end
       end
 
       # @api private
@@ -1390,9 +1445,11 @@ module Microsandbox
       # plain Hash) into string-keyed Hashes for the native layer. Values are
       # passed through unchanged (mode stays Integer, content stays String).
       def normalize_patches(patches)
+        patches = [patches] if patches.is_a?(Hash) # a single patch, not a list of pairs
         Array(patches).map do |p|
           unless p.is_a?(Hash)
-            raise ArgumentError, "patch must be a Hash (use Microsandbox::Patch.*): #{p.inspect}"
+            # Name the type, not the value: a patch can carry file content.
+            raise ArgumentError, "patch must be a Hash (use Microsandbox::Patch.*), got #{p.class}"
           end
           p.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
         end
@@ -1938,10 +1995,16 @@ module Microsandbox
 
     # The booted sandbox. Joins the create task (draining any remaining pull
     # progress first), so call it after iterating progress. The returned
-    # {Sandbox} is live — stop it when done. Memoized; callable once.
+    # {Sandbox} is live — stop it when done. Memoized: the native result can be
+    # taken only once, so a later call returns the same {Sandbox}, or re-raises
+    # the same error if the create failed.
     # @return [Sandbox]
     def sandbox
+      raise @failure if @failure
       @sandbox ||= Sandbox.new(@native.result)
+    rescue Microsandbox::Error => e
+      @failure ||= e
+      raise
     end
   end
 end

data/lib/microsandbox/snapshot.rb

@@ -92,7 +92,7 @@ module Microsandbox
 
     # @return [Time, nil]
     def created_at
-      @created_at_ms && Time.at(@created_at_ms / 1000.0)
+      Microsandbox.time_from_ms(@created_at_ms)
     end
 
     # Re-open this snapshot's artifact (cheap metadata validation), returning a

data/lib/microsandbox/ssh.rb

@@ -173,11 +173,7 @@ module Microsandbox
       session = SftpClient.new(@native.sftp)
       return session unless block_given?
 
-      begin
-        yield session
-      ensure
-        session.close
-      end
+      Microsandbox.close_after(session) { yield session }
     end
 
     # Close the SSH client session. Idempotent. Sends the graceful protocol
@@ -245,11 +241,7 @@ module Microsandbox
       client = SshClient.new(@native.ssh_open_client(opts))
       return client unless block_given?
 
-      begin
-        yield client
-      ensure
-        client.close
-      end
+      Microsandbox.close_after(client) { yield client }
     end
 
     # Prepare a reusable SSH server endpoint for the sandbox.

data/lib/microsandbox/streams.rb

@@ -2,17 +2,20 @@
 
 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.
+  # iterate to consume entries as they are appended. Without `follow:` the
+  # iteration ends once the historical log is drained. With `follow: true` it
+  # keeps waiting for new entries and does NOT end when the sandbox stops: the
+  # runtime follows the log file, not the sandbox, and there is no way to
+  # cancel the wait.
   #
   # @note **Single-pass, forward-only, single-consumer.** `each` drains a
   #   one-shot native channel, so it is *not* rewindable: a second `each` — or
   #   any `Enumerable` combinator after a partial drain (`to_a` twice, `count`
   #   then `each`, `first(n)` then `each`) — silently yields nothing. Iterate
   #   exactly once, from one thread. With `follow: true`, `each` blocks the
-  #   calling thread uninterruptibly until the sandbox stops (see DESIGN.md on
-  #   GVL release).
+  #   calling thread uninterruptibly and indefinitely (see DESIGN.md on GVL
+  #   release); a thread blocked there also keeps the process from exiting
+  #   normally, so follow from a process you are prepared to kill.
   #
   # @example
   #   sb.log_stream(follow: true).each { |entry| print entry.text }

data/lib/microsandbox/version.rb

@@ -8,12 +8,12 @@ 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.16.0"
+  VERSION = "0.17.1"
 
   # The upstream microsandbox runtime release this gem build embeds — the `tag`
   # pinned on the `microsandbox`/`microsandbox-network` git deps in
   # ext/microsandbox/Cargo.toml. Exposed at runtime as
   # {Microsandbox.runtime_version}. spec/unit/version_spec.rb asserts it stays in
   # sync with the Cargo tag so it can't silently drift out of date.
-  RUNTIME_VERSION = "v0.6.16"
+  RUNTIME_VERSION = "v0.6.18"
 end