microsandbox-rb 0.5.9 → 0.5.11

data/lib/microsandbox.rb

@@ -78,6 +78,11 @@ module Microsandbox
     # @return [nil]
     def ensure_runtime!
       return if @runtime_ready
+      # A cloud backend has no local msb/libkrunfw runtime to provision: skip the
+      # presence check and the first-use download entirely. Resolving the kind
+      # uses the same lazy env/profile/config ladder every operation already
+      # consults, so this adds no work for local hosts (the common case).
+      return if default_backend_kind == :cloud
       if installed?
         @runtime_ready = true
         return
@@ -104,6 +109,62 @@ module Microsandbox
       Native.set_runtime_msb_path(path.to_s)
     end
 
+    # Override the `libkrunfw` shared-library path (SDK tier of the resolver,
+    # below the `MSB_LIBKRUNFW_PATH` environment variable). Process-level and
+    # set-once: a second call is silently ignored, and the env var still wins.
+    # Mirrors {runtime_path=} for libkrunfw.
+    # @param path [String]
+    # @return [void]
+    def libkrunfw_path=(path)
+      Native.set_runtime_libkrunfw_path(path.to_s)
+    end
+
+    # Install a process-wide default backend (v0.5.8 backend routing). Without a
+    # call to this, operations use a local libkrun backend; the env/profile
+    # ladder (`MSB_BACKEND`, `MSB_API_URL`+`MSB_API_KEY`, `MSB_PROFILE`,
+    # `~/.microsandbox/config.json`) is resolved lazily on first use. Call once
+    # at startup, before any sandbox operations.
+    #
+    # @param kind ["local","cloud", Symbol] backend kind
+    # @param url [String, nil] cloud control-plane URL (cloud, unless `profile:`)
+    # @param api_key [String, nil] cloud API key (cloud, unless `profile:`)
+    # @param profile [String, nil] named profile from `~/.microsandbox/config.json`
+    # @return [void]
+    def set_default_backend(kind, url: nil, api_key: nil, profile: nil)
+      Native.set_default_backend(kind.to_s, url&.to_s, api_key&.to_s, profile&.to_s)
+    end
+
+    # Run the given block with a temporary default backend, restoring the
+    # previous one afterward (even on error). NOTE: the swap is process-wide
+    # while the block runs, not fiber/thread-local — concurrent threads observe
+    # the temporary backend. It is also NOT safe to call from multiple threads
+    # at once: two interleaved `with_backend` calls can restore each other's
+    # saved backend out of order and leave a temporary backend installed
+    # permanently. Use it only when no other thread is changing the backend, and
+    # avoid calling {set_default_backend} inside the block (the restore on exit
+    # would overwrite that change). Mirrors the official SDKs' scoped-backend helper.
+    #
+    # @param kind ["local","cloud", Symbol]
+    # @param url [String, nil]
+    # @param api_key [String, nil]
+    # @param profile [String, nil]
+    # @yield with the temporary backend installed
+    # @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)
+      begin
+        yield
+      ensure
+        Native.pop_default_backend(token)
+      end
+    end
+
+    # @return [Symbol] the active default backend kind, :local or :cloud.
+    #   The first call resolves the env/profile/config ladder.
+    def default_backend_kind
+      Native.default_backend_kind.to_sym
+    end
+
     # Latest resource-usage snapshot for every running sandbox, keyed by name.
     # Mirrors the official `all_sandbox_metrics`/`allSandboxMetrics` helpers.
     # @return [Hash{String => Metrics}]

data/sig/microsandbox.rbs

@@ -9,8 +9,13 @@ module Microsandbox
   def self.ensure_runtime!: () -> nil
   def self.runtime_path: () -> String
   def self.runtime_path=: (String path) -> void
+  def self.libkrunfw_path=: (String path) -> void
   def self.all_sandbox_metrics: () -> Hash[String, Metrics]
 
+  def self.set_default_backend: (String | Symbol kind, ?url: String?, ?api_key: String?, ?profile: String?) -> void
+  def self.with_backend: [T] (String | Symbol kind, ?url: String?, ?api_key: String?, ?profile: String?) { () -> T } -> T
+  def self.default_backend_kind: () -> Symbol
+
   class Error < StandardError
     def self.code: () -> String
     def code: () -> String
@@ -37,6 +42,8 @@ module Microsandbox
   class MetricsDisabledError < Error end
   class MetricsUnavailableError < Error end
   class UnsupportedOperationError < Error end
+  class CloudHttpError < Error end
+  class UnsupportedError < Error end
 
   class ExecOutput
     def initialize: (Hash[String, untyped] data) -> void
@@ -114,15 +121,26 @@ module Microsandbox
     def timestamp: () -> Time
   end
 
-  class SandboxInfo
+  class SandboxHandle
     def name: () -> String
     def status: () -> Symbol
     def running?: () -> bool
     def stopped?: () -> bool
     def created_at: () -> Time?
     def updated_at: () -> Time?
+    def stop: () -> nil
+    def stop_with_timeout: (Numeric timeout) -> nil
+    def kill: () -> nil
+    def kill_with_timeout: (Numeric timeout) -> nil
+    def request_stop: () -> nil
+    def request_kill: () -> nil
+    def request_drain: () -> nil
+    def wait_until_stopped: () -> SandboxStopResult
   end
 
+  # Deprecated alias for SandboxHandle (was a read-only metadata type pre-v0.5.8).
+  SandboxInfo: singleton(SandboxHandle)
+
   class SandboxStopResult
     def name: () -> String
     def status: () -> Symbol
@@ -151,9 +169,9 @@ module Microsandbox
                       ?replace: bool, ?replace_with_timeout: Numeric?)
                       ?{ (Sandbox) -> untyped } -> untyped
     def self.start: (String name, ?detached: bool) -> Sandbox
-    def self.get: (String name) -> SandboxInfo
-    def self.list: () -> Array[SandboxInfo]
-    def self.list_with: (?labels: Hash[untyped, untyped]) -> Array[SandboxInfo]
+    def self.get: (String name) -> SandboxHandle
+    def self.list: () -> Array[SandboxHandle]
+    def self.list_with: (?labels: Hash[untyped, untyped]) -> Array[SandboxHandle]
     def self.remove: (String name) -> nil
 
     def name: () -> String
@@ -163,10 +181,10 @@ module Microsandbox
     def shell: (String script, ?cwd: String?, ?user: String?, ?env: Hash[untyped, untyped]?,
                 ?timeout: Numeric?, ?tty: bool, ?stdin: String?, ?rlimits: Hash[untyped, untyped]?) -> ExecOutput
     def exec_stream: (String command, ?Array[String] args, ?cwd: String?, ?user: String?,
-                      ?env: Hash[untyped, untyped]?, ?timeout: Numeric?, ?tty: bool, ?stdin: String?,
+                      ?env: Hash[untyped, untyped]?, ?timeout: Numeric?, ?tty: bool, ?stdin: (String | :pipe)?,
                       ?rlimits: Hash[untyped, untyped]?) -> ExecHandle
     def shell_stream: (String script, ?cwd: String?, ?user: String?, ?env: Hash[untyped, untyped]?,
-                       ?timeout: Numeric?, ?tty: bool, ?stdin: String?, ?rlimits: Hash[untyped, untyped]?) -> ExecHandle
+                       ?timeout: Numeric?, ?tty: bool, ?stdin: (String | :pipe)?, ?rlimits: Hash[untyped, untyped]?) -> ExecHandle
     def attach: (String command, ?Array[String] args, ?cwd: String?, ?user: String?,
                  ?env: Hash[untyped, untyped]?, ?detach_keys: String?,
                  ?rlimits: Hash[untyped, untyped]?) -> Integer
@@ -179,12 +197,12 @@ module Microsandbox
     def metrics_stream: (?interval: Numeric) -> MetricsStream
     def log_stream: (?sources: Array[String | Symbol]?, ?since_ms: Numeric?,
                      ?from_cursor: String?, ?until_ms: Numeric?, ?follow: bool) -> LogStream
-    def stop: (?timeout: Numeric?) -> nil
-    def kill: (?timeout: Numeric?) -> nil
-    def request_stop: () -> nil
-    def request_kill: () -> nil
-    def request_drain: () -> nil
-    def wait_until_stopped: () -> SandboxStopResult
+    def stop: () -> nil
+    def stop_and_wait: () -> ExitStatus
+    def kill: () -> nil
+    def drain: () -> nil
+    def wait: () -> ExitStatus
+    def status: () -> Symbol
     def owns_lifecycle?: () -> bool
     def detach: () -> nil
   end
@@ -216,7 +234,7 @@ module Microsandbox
   end
 
   class ExitStatus
-    def exit_code: () -> Integer
+    def exit_code: () -> Integer?
     def success?: () -> bool
     def failure?: () -> bool
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: microsandbox-rb
 version: !ruby/object:Gem::Version
-  version: 0.5.9
+  version: 0.5.11
 platform: ruby
 authors:
 - ya-luotao
@@ -46,6 +46,7 @@ files:
 - ext/microsandbox/Cargo.toml
 - ext/microsandbox/extconf.rb
 - ext/microsandbox/src/agent.rs
+- ext/microsandbox/src/backend.rs
 - ext/microsandbox/src/conv.rs
 - ext/microsandbox/src/error.rs
 - ext/microsandbox/src/exec.rs