microsandbox-rb 0.17.1 → 0.17.3

data/lib/microsandbox/errors.rb

@@ -102,6 +102,14 @@ module Microsandbox
   define_error(:CloudHttpError, "cloud-http")
   define_error(:UnsupportedError, "unsupported")
 
+  # Process model ------------------------------------------------------------
+  # A handle (a Sandbox, a SandboxHandle, an ExecHandle, a stream, an SSH or
+  # agent client, a VolumeFs, ...) was used in a process forked from the one
+  # that created it. Handles are bound to their creating process; a forked
+  # child opens its own (`Sandbox.get(name).connect`, `Volume.fs(name)`, ...).
+  # The message names both pids. Ruby-only: no other SDK has a counterpart.
+  define_error(:ForkedHandleError, "forked-handle")
+
   # As of runtime v0.6.8 the core keys Unsupported errors by a structured
   # (operation, reason) pair. The native layer renders both into the message
   # ("sandbox.kill is not supported by this backend: ...") and also attaches

data/lib/microsandbox/sandbox.rb

@@ -496,7 +496,10 @@ module Microsandbox
       def create(name, **kwargs, &block)
         opts = build_create_opts(**kwargs)
         Microsandbox.ensure_runtime!
-        sandbox = new(Native::Sandbox.create(name.to_s, opts))
+        # Everything Ruby-level happens BEFORE `acquire`: its interrupt mask must
+        # cover only the native call plus the wrap, never caller-supplied code.
+        sandbox_name = name.to_s
+        sandbox = acquire { Native::Sandbox.create(sandbox_name, opts) }
         return sandbox unless block_given?
 
         begin
@@ -553,7 +556,8 @@ module Microsandbox
       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))
+        sandbox_name = name.to_s # outside the interrupt mask, like in {create}
+        sandbox = acquire { Native::Sandbox.connect_or_create(sandbox_name, opts) }
         return sandbox unless block_given?
 
         begin
@@ -588,6 +592,65 @@ module Microsandbox
         PullSession.new(Native::Sandbox.create_with_progress(name.to_s, opts))
       end
 
+      # @api private
+      # Wrap the native sandbox the block acquires, and stop it again if an
+      # interrupt cuts in before the caller has it.
+      #
+      # A native call cannot be interrupted while it runs, so a `Thread#raise`
+      # (what `Timeout.timeout` uses) or a `Thread#kill` that arrives during the
+      # block is delivered after it — at the next interrupt checkpoint, which is
+      # still in here, before the caller ever sees the object. Left alone the
+      # sandbox would be garbage and only GC would stop it, "eventually"; for
+      # `Timeout.timeout { Sandbox.create(...) }` that is not good enough. So:
+      #
+      # - the acquisition runs under `Thread.handle_interrupt(Object => :never)`,
+      #   which holds a queued exception (or kill) back until the wrapper is
+      #   assigned. The mask covers only the uninterruptible native call plus
+      #   the wrap, so it changes no observable timing; runtime provisioning
+      #   ({Microsandbox.ensure_runtime!}) and the block forms' `yield` stay
+      #   outside it, with normal interrupt handling. For the same reason the
+      #   block passed here must contain NOTHING but the native call: argument
+      #   conversion (`name.to_s`, option Hashes) is the caller's own code and
+      #   has to run before `acquire`, where it stays interruptible;
+      # - the `ensure` plus the `acquired` flag — not `rescue Exception; raise` —
+      #   is what also covers `Thread#kill`, which no `rescue` can catch.
+      #
+      # A SIGINT (Ctrl-C on the main thread) is the exception: it is not queued
+      # like those two and cannot be masked. One that lands during the native
+      # call is raised the moment the call returns — the VM checks interrupts
+      # as it pops the native method's frame, before any Ruby code here can
+      # hold the result — so no assignment order would catch it; the sandbox
+      # is then torn down when the unreferenced object is garbage-collected.
+      #
+      # Ownership: {connect_or_create} can hand back a sandbox that was already
+      # running for someone else, and {start} restarts a persisted one. The
+      # cleanup therefore applies EXACTLY the predicate the block form of
+      # {connect_or_create} uses — {Sandbox#owns_lifecycle?} — in all three
+      # callers, {create} included: a sandbox this call does not own is never
+      # stopped here. Its reference is just let go (GC closes the handle, the
+      # sandbox keeps running).
+      # @yieldreturn [Native::Sandbox]
+      # @return [Sandbox]
+      def acquire
+        sandbox = nil
+        acquired = false
+        begin
+          Thread.handle_interrupt(Object => :never) do
+            sandbox = new(yield)
+          end
+          acquired = true
+        ensure
+          if sandbox && !acquired && sandbox.owns_lifecycle?
+            begin
+              sandbox.stop
+            rescue Microsandbox::Error
+              # best-effort cleanup; the interrupt is what the caller must see
+            end
+          end
+        end
+        sandbox
+      end
+
       # @api private
       # Shared keyword-option builder for {create}/{connect_or_create}/
       # {create_with_progress}. Pure validation and normalization: the callers
@@ -705,7 +768,9 @@ module Microsandbox
       # @return [Sandbox]
       def start(name, detached: false)
         Microsandbox.ensure_runtime!
-        new(Native::Sandbox.start(name.to_s, {"detached" => detached}))
+        sandbox_name = name.to_s # outside the interrupt mask, like in {create}
+        opts = {"detached" => detached}
+        acquire { Native::Sandbox.start(sandbox_name, opts) }
       end
 
       # Fetch a controllable handle for a sandbox by name (running or not).
@@ -1998,10 +2063,16 @@ module Microsandbox
     # {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.
+    #
+    # Interrupt-safe like {Sandbox.create}: if a `Timeout.timeout` (or another
+    # `Thread#raise`/`Thread#kill`) arrives while this is waiting, the sandbox
+    # the session produced is stopped before the exception propagates rather
+    # than left running with nothing referring to it. The result is consumed
+    # by then, so a later call raises instead of returning a sandbox.
     # @return [Sandbox]
     def sandbox
       raise @failure if @failure
-      @sandbox ||= Sandbox.new(@native.result)
+      @sandbox ||= Sandbox.acquire { @native.result }
     rescue Microsandbox::Error => e
       @failure ||= e
       raise

data/lib/microsandbox/version.rb

@@ -8,7 +8,7 @@ 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.17.1"
+  VERSION = "0.17.3"
 
   # The upstream microsandbox runtime release this gem build embeds — the `tag`
   # pinned on the `microsandbox`/`microsandbox-network` git deps in

data/lib/microsandbox.rb

@@ -240,6 +240,15 @@ module Microsandbox
     # avoid calling {set_default_backend} inside the block (the restore on exit
     # would overwrite that change). Mirrors the official SDKs' scoped-backend helper.
     #
+    # The restore can fail in one situation: the previous backend belonged to a
+    # parent process (the block is left in a child forked while it was running,
+    # or it is a forked child's first use of the SDK) and cannot be chosen
+    # again there — it came from the environment or config file, which no
+    # longer resolve. The block's temporary selection then stays in effect. If
+    # the block itself raised, its exception is the one that propagates and the
+    # restore failure is only warned about; otherwise the restore failure is
+    # raised.
+    #
     # @param kind ["local","cloud", Symbol]
     # @param url [String, nil]
     # @param api_key [String, nil]
@@ -248,10 +257,20 @@ module Microsandbox
     # @return [Object] the block's return value
     def with_backend(kind, url: nil, api_key: nil, profile: nil)
       token = Native.push_default_backend(kind.to_s, url&.to_s, api_key&.to_s, profile&.to_s)
+      raised = false
       begin
         yield
+      rescue Exception # standard:disable Lint/RescueException -- only noted, re-raised at once
+        raised = true
+        raise
       ensure
-        Native.pop_default_backend(token)
+        begin
+          Native.pop_default_backend(token)
+        rescue Microsandbox::Error => e
+          # Never let the restore failure replace what the block raised.
+          raise unless raised
+          warn "microsandbox: with_backend could not restore the previous backend: #{e.message}"
+        end
       end
     end
 

data/sig/microsandbox.rbs

@@ -64,6 +64,7 @@ module Microsandbox
   class MetricsUnavailableError < Error end
   class UnsupportedOperationError < Error end
   class CloudHttpError < Error end
+  class ForkedHandleError < Error end
   class UnsupportedError < Error
     def operation: () -> String?
     def hint: () -> String?
@@ -82,6 +83,7 @@ module Microsandbox
   end
 
   class FsEntry
+    def initialize: (Hash[String, untyped] data) -> void
     def path: () -> String
     def name: () -> String
     def type: () -> Symbol
@@ -94,6 +96,7 @@ module Microsandbox
   end
 
   class FsMetadata
+    def initialize: (Hash[String, untyped] data) -> void
     def type: () -> Symbol
     def size: () -> Integer
     def mode: () -> Integer
@@ -106,6 +109,7 @@ module Microsandbox
   end
 
   class FS
+    def initialize: (untyped native) -> void
     def read: (String path) -> String
     def read_text: (String path) -> String
     def write: (String path, String data) -> nil
@@ -125,17 +129,20 @@ module Microsandbox
 
   class FsReadStream
     include Enumerable[String]
+    def initialize: (untyped native) -> void
     def each: () { (String) -> void } -> self
             | () -> Enumerator[String, self]
     def read: () -> String
   end
 
   class FsWriteSink
+    def initialize: (untyped native) -> void
     def write: (String data) -> self
     def close: () -> nil
   end
 
   class Metrics
+    def initialize: (Hash[String, untyped] data) -> void
     def cpu_percent: () -> Float
     def vcpu_time_ns: () -> Integer
     def memory_bytes: () -> Integer
@@ -154,6 +161,7 @@ module Microsandbox
   end
 
   class LogEntry
+    def initialize: (Hash[String, untyped] entry) -> void
     def source: () -> Symbol
     def session_id: () -> Integer?
     def cursor: () -> String
@@ -163,6 +171,7 @@ module Microsandbox
   end
 
   class SandboxHandle
+    def initialize: (untyped native) -> void
     def name: () -> String
     def id: () -> String
     def status: () -> Symbol
@@ -200,6 +209,7 @@ module Microsandbox
   SandboxInfo: singleton(SandboxHandle)
 
   class SandboxStopResult
+    def initialize: (Hash[String, untyped] data) -> void
     def name: () -> String
     def status: () -> Symbol
     def exit_code: () -> Integer?
@@ -290,6 +300,7 @@ module Microsandbox
     def self.list_with: (?labels: Hash[untyped, untyped], ?limit: Integer?, ?cursor: String?) -> SandboxPage
     def self.remove: (String name) -> nil
 
+    def initialize: (untyped native) -> void
     def name: () -> String
     def id: () -> String
     def exec: (String command, ?Array[String] args, ?cwd: String?, ?user: String?,
@@ -354,17 +365,20 @@ module Microsandbox
 
   class LogStream
     include Enumerable[LogEntry]
+    def initialize: (untyped native) -> void
     def each: () { (LogEntry) -> void } -> self
             | () -> Enumerator[LogEntry, self]
   end
 
   class MetricsStream
     include Enumerable[Metrics]
+    def initialize: (untyped native) -> void
     def each: () { (Metrics) -> void } -> self
             | () -> Enumerator[Metrics, self]
   end
 
   class ExecEvent
+    def initialize: (Hash[String, untyped] event) -> void
     def type: () -> Symbol
     def pid: () -> Integer?
     def code: () -> Integer?
@@ -379,18 +393,21 @@ module Microsandbox
   end
 
   class ExitStatus
+    def initialize: (Hash[String, untyped] data) -> void
     def exit_code: () -> Integer?
     def success?: () -> bool
     def failure?: () -> bool
   end
 
   class ExecStdin
+    def initialize: (untyped native) -> void
     def write: (String data) -> self
     def close: () -> nil
   end
 
   class ExecHandle
     include Enumerable[ExecEvent]
+    def initialize: (untyped native) -> void
     def id: () -> String
     def each: () { (ExecEvent) -> void } -> self
             | () -> Enumerator[ExecEvent, self]
@@ -403,6 +420,7 @@ module Microsandbox
   end
 
   class ImageInfo
+    def initialize: (Hash[String, untyped] data) -> void
     def reference: () -> String
     def size_bytes: () -> Integer?
     def manifest_digest: () -> String?
@@ -414,6 +432,7 @@ module Microsandbox
   end
 
   class ImageDetail
+    def initialize: (Hash[String, untyped] data) -> void
     def handle: () -> ImageInfo
     def config: () -> Hash[String, untyped]?
     def layers: () -> Array[Hash[String, untyped]]
@@ -421,6 +440,7 @@ module Microsandbox
   end
 
   class ImagePruneReport
+    def initialize: (Hash[String, untyped] data) -> void
     def image_refs_removed: () -> Integer
     def manifests_removed: () -> Integer
     def layers_removed: () -> Integer
@@ -441,6 +461,7 @@ module Microsandbox
   end
 
   class VolumeInfo
+    def initialize: (Hash[String, untyped] data) -> void
     def name: () -> String
     def path: () -> String?
     def kind: () -> Symbol?
@@ -481,6 +502,7 @@ module Microsandbox
   end
 
   class SnapshotInfo
+    def initialize: (Hash[String, untyped] data) -> void
     def digest: () -> String
     def path: () -> String
     def name: () -> String?
@@ -506,6 +528,7 @@ module Microsandbox
   end
 
   class SnapshotVerifyReport
+    def initialize: (Hash[String, untyped] data) -> void
     def digest: () -> String
     def path: () -> String
     def status: () -> Symbol
@@ -569,6 +592,7 @@ module Microsandbox
   end
 
   class BackendInfo
+    def initialize: (Hash[String, untyped] data) -> void
     def kind: () -> Symbol
     def api_url: () -> String?
     def source: () -> Symbol
@@ -643,6 +667,7 @@ module Microsandbox
 
   class AgentStream
     include Enumerable[AgentFrame]
+    def initialize: (untyped native, Integer id, Integer handle) -> void
     def id: () -> Integer
     def recv: () -> AgentFrame?
     def each: () { (AgentFrame) -> void } -> self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: microsandbox-rb
 version: !ruby/object:Gem::Version
-  version: 0.17.1
+  version: 0.17.3
 platform: ruby
 authors:
 - ya-luotao