microsandbox-rb 0.15.0 → 0.17.0

data/lib/microsandbox/sandbox.rb

@@ -20,6 +20,14 @@ module Microsandbox
     # @return [String]
     def name = @native.name
 
+    # The opaque, backend-assigned identity of the persisted sandbox this handle
+    # is bound to (runtime v0.6.16). Unlike {#name} — a reusable label — it is
+    # stable for the sandbox's lifetime and changes once the same name is
+    # removed and recreated; the convergent operations below compare against it
+    # before acting.
+    # @return [String]
+    def id = @native.id
+
     # @return [Symbol] :created, :starting, :running, :draining, :paused,
     #   :stopped, or :crashed (a snapshot, captured when this handle was fetched)
     def status = @native.status.to_sym
@@ -95,6 +103,68 @@ module Microsandbox
       nil
     end
 
+    # Converge on a live sandbox for this handle (runtime v0.6.16): connect
+    # when it is already running, wait while it is starting, or start it when it
+    # is created/stopped/crashed. A draining or paused sandbox is rejected
+    # rather than raced.
+    # @param detached [Boolean] applies only when a start is actually required
+    # @raise [SandboxReplacedError] if the name now refers to a different sandbox
+    # @return [Sandbox] the live sandbox
+    def connect_or_start(detached: false)
+      # May boot a microVM (the start arm), so it needs a provisioned runtime
+      # just like {Sandbox.create}/{Sandbox.start}. Memoized after the first
+      # call, so the extra check costs nothing on the connect arm.
+      Microsandbox.ensure_runtime!
+      opts = detached ? {"detached" => true} : {}
+      Sandbox.new(@native.connect_or_start(opts))
+    end
+
+    # Block until *this exact* sandbox reaches +status+ (runtime v0.6.16).
+    #
+    # The wait is uninterruptible from Ruby: the native call blocks with the GVL
+    # released and no unblock function, so Ctrl-C (and any other signal) only
+    # lands once it returns. There is no built-in timeout either — the core
+    # polls every 100ms forever, by design, leaving the deadline to the caller.
+    # So wait only for a state this *backend* can actually reach (`:created` and
+    # `:paused` are cloud-side states, unreachable locally), and if you need a
+    # deadline, run this on a Thread of its own and enforce the timeout there
+    # (`Timeout.timeout` around it would not fire).
+    # @param status [Symbol, String] :created, :starting, :running, :draining,
+    #   :paused, :stopped, or :crashed
+    # @raise [ArgumentError] on an unknown status name
+    # @raise [SandboxReplacedError] if the name now refers to a different sandbox
+    # @return [SandboxHandle] a fresh handle observed in that state
+    def wait_for_status(status)
+      SandboxHandle.new(@native.wait_for_status(Sandbox.send(:coerce_status, status)))
+    end
+
+    # Stop and start *this exact* sandbox, returning the new live sandbox
+    # (runtime v0.6.16). A created/stopped/crashed sandbox is started directly.
+    # @param force [Boolean] SIGKILL instead of requesting a graceful shutdown
+    # @param timeout [Numeric, nil] graceful-shutdown seconds before escalating
+    #   (the core's default is 10)
+    # @param detached [Boolean] start the replacement detached
+    # @raise [SandboxReplacedError] if the name now refers to a different sandbox
+    # @return [Sandbox]
+    def restart(force: false, timeout: nil, detached: false)
+      Microsandbox.ensure_runtime!
+      opts = Sandbox.send(:build_restart_opts, force: force, timeout: timeout, detached: detached)
+      Sandbox.new(@native.restart(opts))
+    end
+
+    # Stop and remove *this exact* sandbox (runtime v0.6.16) — {#stop} plus
+    # {Sandbox.remove} in one convergent step, with an identity check that
+    # refuses to remove a same-name replacement.
+    # @param force [Boolean] SIGKILL instead of requesting a graceful shutdown
+    # @param timeout [Numeric, nil] graceful-shutdown seconds before escalating
+    #   (the core's default is 10)
+    # @raise [SandboxReplacedError] if the name now refers to a different sandbox
+    # @return [nil]
+    def destroy(force: false, timeout: nil)
+      @native.destroy(Sandbox.send(:build_destroy_opts, force: force, timeout: timeout))
+      nil
+    end
+
     # Block until the sandbox is observed in a terminal (non-running) state.
     # @return [SandboxStopResult]
     def wait_until_stopped
@@ -265,6 +335,11 @@ module Microsandbox
     # to gate the `fstype:`-vs-OCI check; keep in sync on a runtime-tag bump.
     DISK_IMAGE_EXTENSIONS = %w[raw qcow2 vmdk].freeze
 
+    # The seven lifecycle states a sandbox can be observed in — the spelling
+    # {Sandbox#status} / {SandboxHandle#status} return, and the accepted
+    # arguments of {Sandbox#wait_for_status} / {SandboxHandle#wait_for_status}.
+    STATUSES = %i[created starting running draining paused stopped crashed].freeze
+
     class << self
       # Create and boot a sandbox.
       #
@@ -309,7 +384,11 @@ module Microsandbox
       #   (4 GiB as of `v0.5.10`); the core rejects it on tmpfs/disk/named (for a
       #   named volume, set its quota via {Volume.create}). Bind/named mounts
       #   also accept `follow_root_symlinks: true` to opt out of the default-on
-      #   mount-root symlink protection (runtime v0.6.7).
+      #   mount-root symlink protection (runtime v0.6.7), and `uid:`/`gid:`
+      #   (runtime v0.6.15) to pin the guest owner presented for host files that
+      #   carry no per-file stat override — both must be given together, each an
+      #   Integer in 0..4294967295, and they conflict with
+      #   `stat_virtualization: :off`.
       # @param network [Array, String, Symbol, NetworkPolicy, Hash, nil] network
       #   policy. Composable profiles (`[:public]` (the default), `[:public,
       #   :private]`, `:host`, …), a terminal preset (:none, :allow_all), a
@@ -329,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
@@ -414,6 +509,62 @@ module Microsandbox
         end
       end
 
+      # Converge on a live sandbox called +name+ (runtime v0.6.16, upstream
+      # #1462): connect to the persisted sandbox with that name — starting it
+      # when it is created/stopped/crashed, waiting when it is already starting
+      # — or create it when none exists. Concurrent callers converge on the
+      # winning identity instead of one of them losing to a name clash.
+      #
+      # The keyword options are exactly {create}'s and are used **only when a
+      # create actually happens**: an existing sandbox keeps its persisted
+      # configuration, so passing `memory:` here will not resize one that is
+      # already there. `replace:`/`replace_with_timeout:` are accepted for
+      # kwargs parity with {create} but are rejected by the core — replacing a
+      # sandbox is the opposite of converging on it — and raise
+      # {InvalidConfigError}.
+      #
+      # The block form yields the sandbox and then stops it **only when this
+      # call owns its lifecycle** ({Sandbox#owns_lifecycle?}). That is a
+      # deliberate divergence from {create}, whose block form always stops:
+      # `connect_or_create` may hand back a sandbox this process did not start,
+      # and tearing down someone else's long-lived service on the way out of a
+      # block is never what the caller meant. Concretely:
+      #
+      # - created here (the common case) — yielded, then stopped, exactly like
+      #   {create};
+      # - *connected* to a sandbox that was already running — left running;
+      # - created here with `detached: true` — left running, which is what
+      #   `detached:` asks for (this is where the divergence from {create} bites:
+      #   `create(..., detached: true) { }` still stops on block exit).
+      #
+      # Either way, stop it yourself with {Sandbox#stop}/{Sandbox#destroy} when
+      # you do want it gone.
+      #
+      # The teardown is safe against name reuse from either side: it skips the
+      # stop entirely for a sandbox this call did not start, and the stop it does
+      # issue is scoped to this sandbox's {Sandbox#id} (runtime v0.6.16), so a
+      # name removed and recreated while the block ran raises inside the ensure
+      # — swallowed as a best-effort teardown failure — rather than taking the
+      # replacement down.
+      # @param name [String]
+      # @yieldparam sandbox [Sandbox]
+      # @return [Sandbox, Object] the live sandbox, or the block's return value
+      def connect_or_create(name, **kwargs, &block)
+        opts = build_create_opts(**kwargs)
+        sandbox = new(Native::Sandbox.connect_or_create(name.to_s, opts))
+        return sandbox unless block_given?
+
+        begin
+          yield sandbox
+        ensure
+          begin
+            sandbox.stop if sandbox.owns_lifecycle?
+          rescue Microsandbox::Error
+            # best-effort cleanup; ignore stop failures during teardown
+          end
+        end
+      end
+
       # Create a sandbox while streaming image-pull progress. Accepts the same
       # options as {create}; returns a {PullSession} — iterate it (an
       # {Enumerable} of progress-event Hashes, each with a "kind"), then call
@@ -441,7 +592,8 @@ module Microsandbox
         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,
@@ -502,7 +654,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
@@ -590,6 +744,40 @@ module Microsandbox
         seconds
       end
 
+      # Validate a `wait_for_status` target and lower it to the wire name.
+      # Accepts a Symbol or String in the {STATUSES} spelling; anything else is
+      # an ArgumentError (an unreachable typo would otherwise block forever —
+      # `wait_for_status` has no built-in timeout).
+      def coerce_status(status)
+        name = status.to_s
+        unless STATUSES.include?(name.to_sym)
+          raise ArgumentError,
+            "unknown sandbox status #{status.inspect} " \
+            "(expected one of: #{STATUSES.join(", ")})"
+        end
+        name
+      end
+
+      # Shared option builder for `restart`, on both {Sandbox} and
+      # {SandboxHandle}. An omitted `timeout:` keeps the core's ten-second
+      # graceful-shutdown default.
+      def build_restart_opts(force:, timeout:, detached:)
+        opts = {}
+        opts["force"] = true if force
+        opts["detached"] = true if detached
+        opts["timeout"] = coerce_duration(timeout, "timeout") if timeout
+        opts
+      end
+
+      # Shared option builder for `destroy`, on both {Sandbox} and
+      # {SandboxHandle}.
+      def build_destroy_opts(force:, timeout:)
+        opts = {}
+        opts["force"] = true if force
+        opts["timeout"] = coerce_duration(timeout, "timeout") if timeout
+        opts
+      end
+
       def stringify(hash)
         hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v.to_s }
       end
@@ -987,7 +1175,8 @@ module Microsandbox
       #   { tmpfs: true, size_mib: 64 }                          # memory-backed
       #   { disk: "/img.raw", format: "raw", fstype: "ext4" }   # disk-image mount
       # Any mount may also carry stat_virtualization: (:strict/:relaxed/:off) and
-      # host_permissions: (:private/:mirror); a bind mount may carry quota_mib:.
+      # host_permissions: (:private/:mirror); a bind/named mount may carry
+      # uid:/gid: (the fallback guest owner); a bind mount may carry quota_mib:.
       # Coerce the `root_disk:` argument — an Integer (managed size in MiB), a
       # {RootDisk} factory Hash, or an equivalent hand-written Hash — into the
       # wire shape, validating kind/field combinations up front (mirrors the
@@ -1115,6 +1304,8 @@ module Microsandbox
       # `follow_root_symlinks:` opts out of the default-on mount-root symlink
       # protection (runtime v0.6.7; bind/named only — the core silently ignores
       # it on tmpfs/disk mounts, so reject those here instead).
+      # `uid:`/`gid:` pin the fallback guest owner (runtime v0.6.15) — see
+      # {apply_mount_owner}.
       def apply_mount_flags(mount, spec)
         mount["readonly"] = true if spec[:ro] || spec["ro"] || spec[:readonly] || spec["readonly"]
         mount["noexec"] = true if spec[:noexec] || spec["noexec"]
@@ -1134,6 +1325,58 @@ module Microsandbox
           end
           mount["follow_root_symlinks"] = !!follow
         end
+        apply_mount_owner(mount, spec)
+      end
+
+      # Apply a volume spec Hash's fallback mount ownership (runtime v0.6.15,
+      # upstream #1451). Host files carrying no per-file stat override surface in
+      # the guest as `uid:`/`gid:` instead of the runtime's fallback owner; the
+      # pair travels on the wire as `override_uid`/`override_gid` (the core's
+      # `MountBuilder#owner`), mirroring the Python SDK's concise `uid:`/`gid:`
+      # public names over the same wire fields.
+      #
+      # Validation mirrors the Python SDK exactly: the two must be given
+      # together, each must be a plain Integer in the u32 range, they need stat
+      # virtualization (so `stat_virtualization: :off` conflicts), and they only
+      # apply to bind/named mounts. The one Python rule with no Ruby counterpart
+      # is "not supported for disk-backed named volumes": Python knows the
+      # volume kind because its `Volume.named` carries it, while a Ruby
+      # `{ named: "vol" }` spec only references an existing volume by name — the
+      # core rejects that combination at create() instead.
+      def apply_mount_owner(mount, spec)
+        uid = spec.fetch(:uid, spec["uid"])
+        gid = spec.fetch(:gid, spec["gid"])
+        return if uid.nil? && gid.nil?
+
+        if uid.nil? || gid.nil?
+          raise ArgumentError, "mount uid: and gid: must be set together"
+        end
+        unless %w[bind named].include?(mount["kind"])
+          raise ArgumentError,
+            "uid:/gid: (mount owner) only applies to bind/named mounts " \
+            "(got a #{mount["kind"]} mount), like stat_virtualization:/host_permissions:"
+        end
+        if mount["stat_virtualization"] == "off"
+          raise ArgumentError,
+            "uid:/gid: (mount owner) cannot be combined with stat_virtualization: :off — " \
+            "`off` exposes literal host metadata, leaving no overlay to rewrite the owner in"
+        end
+        mount["override_uid"] = coerce_mount_owner_id(uid, "uid:")
+        mount["override_gid"] = coerce_mount_owner_id(gid, "gid:")
+      end
+
+      # Range-check one mount owner ID. Deliberately stricter than the repo's
+      # usual `Integer(value)` coercion: `Integer("1000")` and a truncating
+      # `Integer(1000.7)` would both silently accept input that never named a
+      # real owner. `is_a?(Integer)` also rejects `true`/`false`, matching the
+      # Python SDK's `_mount_owner_id` (`type(value) is not int`, which excludes
+      # `bool`).
+      def coerce_mount_owner_id(value, label)
+        unless value.is_a?(Integer) && value >= 0 && value <= 0xFFFF_FFFF
+          raise ArgumentError,
+            "#{label} must be an Integer between 0 and 4294967295 (got #{value.inspect})"
+        end
+        value
       end
 
       # Translate the pre-0.7.0 `options:` array form (e.g. options: %w[ro noexec])
@@ -1201,6 +1444,16 @@ module Microsandbox
       @native.name
     end
 
+    # The opaque, backend-assigned identity of the persisted sandbox (runtime
+    # v0.6.16). Unlike {#name} — a reusable label — this is stable for the
+    # sandbox's lifetime and changes once the same name is removed and
+    # recreated, which is exactly what {#wait_for_status}/{#restart}/{#destroy}
+    # check before acting.
+    # @return [String]
+    def id
+      @native.id
+    end
+
     # Run a command (no shell interpretation) and collect its output.
     #
     # @param command [String] the executable
@@ -1488,6 +1741,13 @@ module Microsandbox
     # Gracefully stop the sandbox (SIGTERM→SIGKILL escalation, 10s default) and
     # wait for it to terminate. For a custom timeout or fire-and-return
     # `request_*` control, fetch a {SandboxHandle} via {Sandbox.get}.
+    #
+    # Scoped to *this exact* sandbox: as of runtime v0.6.16 the stop carries this
+    # object's {#id}, so if the name has since been removed and recreated the
+    # call raises {SandboxReplacedError} (or {SandboxNotFoundError} when nothing
+    # holds the name any more) instead of terminating whatever sandbox now
+    # answers to it. Same for {#kill}, {#drain} and {#stop_and_wait}.
+    # @raise [SandboxReplacedError] if the name now refers to a different sandbox
     # @return [nil]
     def stop
       @native.stop
@@ -1520,6 +1780,59 @@ module Microsandbox
       ExitStatus.new(@native.wait)
     end
 
+    # Block until *this exact* sandbox reaches +status+ (runtime v0.6.16). If
+    # the name has since been recreated as a different sandbox, this raises
+    # {SandboxReplacedError} rather than silently redirecting the wait to the
+    # replacement.
+    #
+    # The wait is uninterruptible from Ruby: the native call blocks with the GVL
+    # released and no unblock function, so Ctrl-C (and any other signal) only
+    # lands once it returns. There is no built-in timeout either — the core
+    # polls every 100ms forever, by design, leaving the deadline to the caller.
+    # So wait only for a state this *backend* can actually reach (`:created` and
+    # `:paused` are cloud-side states, unreachable locally), and if you need a
+    # deadline, run this on a Thread of its own and enforce the timeout there
+    # (`Timeout.timeout` around it would not fire).
+    # @param status [Symbol, String] :created, :starting, :running, :draining,
+    #   :paused, :stopped, or :crashed
+    # @raise [ArgumentError] on an unknown status name
+    # @return [SandboxHandle] a fresh handle observed in that state (mirrors the
+    #   official SDKs, which return a handle from both `Sandbox` and
+    #   `SandboxHandle`)
+    def wait_for_status(status)
+      SandboxHandle.new(@native.wait_for_status(self.class.send(:coerce_status, status)))
+    end
+
+    # Stop and start *this exact* sandbox, returning the new live sandbox
+    # (runtime v0.6.16). A created/stopped/crashed sandbox is started directly.
+    # This handle is spent afterwards — use the returned one.
+    # @param force [Boolean] SIGKILL instead of requesting a graceful shutdown
+    # @param timeout [Numeric, nil] graceful-shutdown seconds before escalating
+    #   (the core's default is 10)
+    # @param detached [Boolean] start the replacement detached
+    # @raise [SandboxReplacedError] if the name now refers to a different sandbox
+    # @return [Sandbox]
+    def restart(force: false, timeout: nil, detached: false)
+      # Boots a microVM again, so it needs a provisioned runtime — the sandbox
+      # this object came from may have been created in a different process.
+      Microsandbox.ensure_runtime!
+      opts = self.class.send(:build_restart_opts, force: force, timeout: timeout, detached: detached)
+      self.class.new(@native.restart(opts))
+    end
+
+    # Stop and remove *this exact* sandbox (runtime v0.6.16) — the convergent
+    # equivalent of {#stop} followed by {Sandbox.remove}, with an identity check
+    # that refuses to remove a same-name replacement.
+    # @param force [Boolean] SIGKILL instead of requesting a graceful shutdown
+    # @param timeout [Numeric, nil] graceful-shutdown seconds before escalating
+    #   (the core's default is 10)
+    # @raise [SandboxReplacedError] if the name now refers to a different sandbox
+    # @return [nil]
+    def destroy(force: false, timeout: nil)
+      @native.destroy(self.class.send(:build_destroy_opts, force: force, timeout: timeout))
+      nil
+    end
+
     # The live status, fetched from the backend (a round-trip per call).
     # @return [Symbol] :created, :starting, :running, :draining, :paused,
     #   :stopped, or :crashed

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.15.0"
+  VERSION = "0.17.0"
 
   # 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.14"
+  RUNTIME_VERSION = "v0.6.18"
 end

data/lib/microsandbox.rb

@@ -30,6 +30,7 @@ require_relative "microsandbox/snapshot"
 require_relative "microsandbox/patch"
 require_relative "microsandbox/root_disk"
 require_relative "microsandbox/network"
+require_relative "microsandbox/outbound_proxy"
 require_relative "microsandbox/agent"
 require_relative "microsandbox/ssh"
 require_relative "microsandbox/modification"

data/sig/microsandbox.rbs

@@ -39,6 +39,7 @@ module Microsandbox
   class SandboxNotRunningError < Error end
   class SandboxAlreadyExistsError < Error end
   class SandboxStillRunningError < Error end
+  class SandboxReplacedError < Error end
   class ExecTimeoutError < Error end
   class ExecFailedError < Error end
   class NoDefaultCommandError < Error end
@@ -163,6 +164,7 @@ module Microsandbox
 
   class SandboxHandle
     def name: () -> String
+    def id: () -> String
     def status: () -> Symbol
     def running?: () -> bool
     def stopped?: () -> bool
@@ -176,6 +178,10 @@ module Microsandbox
     def request_kill: () -> nil
     def request_drain: () -> nil
     def wait_until_stopped: () -> SandboxStopResult
+    def connect_or_start: (?detached: bool) -> Sandbox
+    def wait_for_status: (Symbol | String status) -> SandboxHandle
+    def restart: (?force: bool, ?timeout: Numeric?, ?detached: bool) -> Sandbox
+    def destroy: (?force: bool, ?timeout: Numeric?) -> nil
     def config_json: () -> String
     def config: () -> Hash[String, untyped]
     def snapshot: (String name) -> SnapshotInfo
@@ -243,6 +249,8 @@ module Microsandbox
   end
 
   class Sandbox
+    STATUSES: Array[Symbol]
+
     def self.create: (String name, ?image: String?, ?cpus: Integer?, ?max_cpus: Integer?,
                       ?memory: Integer?, ?max_memory: Integer?,
                       ?env: Hash[untyped, untyped]?, ?workdir: String?, ?shell: String?,
@@ -253,8 +261,9 @@ module Microsandbox
                       ?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?,
+                      ?max_connections: Integer?, ?trust_host_cas: bool?, ?strict: bool?,
                       ?rate_limiter: Hash[untyped, untyped]?,
+                      ?proxy: (OutboundProxy | Hash[untyped, untyped])?,
                       ?vsock: (Hash[untyped, untyped] | Array[Hash[untyped, untyped]])?,
                       ?patches: Array[Hash[untyped, untyped]]?, ?from_snapshot: String?,
                       ?fstype: String?, ?init: (String | Symbol | Hash[untyped, untyped])?, ?ephemeral: bool,
@@ -269,6 +278,10 @@ module Microsandbox
                       ?detached: bool,
                       ?replace: bool, ?replace_with_timeout: Numeric?)
                       ?{ (Sandbox) -> untyped } -> untyped
+    # Accepts the same keyword options as {create} (used only when a create is
+    # actually necessary); `replace:`/`replace_with_timeout:` are rejected by
+    # the core.
+    def self.connect_or_create: (String name, **untyped) ?{ (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
@@ -278,6 +291,7 @@ module Microsandbox
     def self.remove: (String name) -> nil
 
     def name: () -> String
+    def id: () -> String
     def exec: (String command, ?Array[String] args, ?cwd: String?, ?user: String?,
                ?env: Hash[untyped, untyped]?, ?timeout: Numeric?, ?tty: bool, ?stdin: (String | :null)?,
                ?rlimits: Hash[untyped, untyped]?) -> ExecOutput
@@ -322,6 +336,9 @@ module Microsandbox
     def kill: () -> nil
     def drain: () -> nil
     def wait: () -> ExitStatus
+    def wait_for_status: (Symbol | String status) -> SandboxHandle
+    def restart: (?force: bool, ?timeout: Numeric?, ?detached: bool) -> Sandbox
+    def destroy: (?force: bool, ?timeout: Numeric?) -> nil
     def status: () -> Symbol
     def owns_lifecycle?: () -> bool
     def detach: () -> nil
@@ -560,6 +577,44 @@ module Microsandbox
     def cloud?: () -> bool
   end
 
+  # Host-side secret source (runtime v0.6.17): only `env` exists.
+  class SecretSource
+    KINDS: Array[String]
+    attr_reader kind: String
+    attr_reader var: String
+    def self.env: ((String | Symbol) variable) -> SecretSource
+    def self.coerce: (untyped value, ?String context) -> SecretSource
+    def initialize: ((String | Symbol) kind, (String | Symbol) var) -> void
+    def to_h: () -> Hash[String, String]
+    def ==: (untyped other) -> bool
+    def eql?: (untyped other) -> bool
+    def hash: () -> Integer
+  end
+
+  # Outbound SOCKS4/SOCKS5 proxy for the `proxy:` create option (runtime
+  # v0.6.17). Immutable: `credentials` returns a new proxy.
+  class OutboundProxy
+    PROTOCOLS: Array[String]
+    attr_reader protocol: String
+    attr_reader address: String
+    attr_reader user_id: String?
+    attr_reader username: String?
+    attr_reader password: SecretSource?
+    def self.socks4: (String address, ?user_id: String?) -> OutboundProxy
+    def self.socks5: (String address) -> OutboundProxy
+    def self.coerce: (untyped value) -> Hash[String, untyped]
+    def self.from_hash: (Hash[untyped, untyped] hash) -> OutboundProxy
+    def initialize: (protocol: (String | Symbol), address: String, ?user_id: String?,
+                     ?username: String?, ?password: SecretSource?) -> void
+    def credentials: (String username, (SecretSource | Hash[untyped, untyped]) password) -> OutboundProxy
+    def socks4?: () -> bool
+    def socks5?: () -> bool
+    def to_h: () -> Hash[String, untyped]
+    def ==: (untyped other) -> bool
+    def eql?: (untyped other) -> bool
+    def hash: () -> Integer
+  end
+
   class NetworkPolicy
     PROFILES: Array[String]
     PRESET_ALIASES: Hash[String, String]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: microsandbox-rb
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - ya-luotao
@@ -71,6 +71,7 @@ files:
 - lib/microsandbox/metrics.rb
 - lib/microsandbox/modification.rb
 - lib/microsandbox/network.rb
+- lib/microsandbox/outbound_proxy.rb
 - lib/microsandbox/patch.rb
 - lib/microsandbox/root_disk.rb
 - lib/microsandbox/sandbox.rb