microsandbox-rb 0.16.0 → 0.17.1

data/lib/microsandbox/volume.rb

@@ -38,7 +38,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
 
     # A host-side filesystem view over this volume (read/write its contents
@@ -55,8 +55,10 @@ module Microsandbox
 
   # A host-side filesystem view over a named volume, from {Volume.fs} or
   # {VolumeInfo#fs}. Reads and writes the volume's contents directly on the host,
-  # without booting a sandbox. All paths are relative to the volume root. Mirrors
-  # the `VolumeFs` of the official Python/Node SDKs.
+  # without booting a sandbox. All paths are relative to the volume root (a
+  # leading `/` is the volume root) and may not contain a `..` segment — every
+  # operation raises {FilesystemError} for one. Mirrors the `VolumeFs` of the
+  # official Python/Node SDKs.
   class VolumeFs
     def initialize(native)
       @native = native
@@ -65,13 +67,13 @@ module Microsandbox
     # Read a file as raw bytes (ASCII-8BIT).
     # @return [String]
     def read(path)
-      @native.read(path.to_s)
+      @native.read(contained(path))
     end
 
     # Read a file as a UTF-8 string.
     # @return [String]
     def read_text(path)
-      @native.read_text(path.to_s)
+      @native.read_text(contained(path))
     end
 
     # Write data to a file, creating parent directories as needed.
@@ -80,60 +82,75 @@ module Microsandbox
     # @return [nil]
     def write(path, data)
       bytes = Microsandbox.coerce_write_bytes(data)
-      @native.write(path.to_s, bytes)
+      @native.write(contained(path), bytes)
       nil
     end
 
     # List the entries of a directory.
     # @return [Array<FsEntry>]
     def list(path)
-      @native.list(path.to_s).map { |entry| FsEntry.new(entry) }
+      @native.list(contained(path)).map { |entry| FsEntry.new(entry) }
     end
 
     # Create a directory (and any missing parents).
     # @return [nil]
     def mkdir(path)
-      @native.mkdir(path.to_s)
+      @native.mkdir(contained(path))
       nil
     end
 
     # Remove a single file.
     # @return [nil]
     def remove_file(path)
-      @native.remove_file(path.to_s)
+      @native.remove_file(contained(path))
       nil
     end
 
     # Remove a directory recursively.
     # @return [nil]
     def remove_dir(path)
-      @native.remove_dir(path.to_s)
+      @native.remove_dir(contained(path))
       nil
     end
 
     # @return [Boolean] whether the path exists in the volume
     def exists?(path)
-      @native.exists(path.to_s)
+      @native.exists(contained(path))
     end
 
     # Copy a file within the volume.
     # @return [nil]
     def copy(src, dst)
-      @native.copy(src.to_s, dst.to_s)
+      @native.copy(contained(src), contained(dst))
       nil
     end
 
     # Rename/move a file or directory within the volume.
     # @return [nil]
     def rename(src, dst)
-      @native.rename(src.to_s, dst.to_s)
+      @native.rename(contained(src), contained(dst))
       nil
     end
 
     # Stat a path.
     # @return [FsMetadata]
     def stat(path)
-      FsMetadata.new(@native.stat(path.to_s))
+      FsMetadata.new(@native.stat(contained(path)))
+    end
+
+    private
+
+    # Volume paths are relative to the volume root and never need a `..`
+    # segment, so one is refused here with a clear message instead of being
+    # handed to the resolver. The native layer enforces the same rule; this
+    # check only exists so the error names the cause.
+    def contained(path)
+      s = path.to_s
+      if s.split("/").include?("..")
+        raise Microsandbox::FilesystemError,
+          "path traversal outside volume root (`..` segments are not allowed in volume paths)"
+      end
+      s
     end
   end
 

data/lib/microsandbox-rb.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Entry point named after the gem. `require "microsandbox"` resolves to
+# whichever installed gem ships that file first, and the separate
+# `microsandbox` gem on RubyGems ships one too; outside Bundler,
+# `require "microsandbox-rb"` always loads this gem.
+require_relative "microsandbox"

data/lib/microsandbox.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "monitor"
+
 require_relative "microsandbox/version"
 
 # Load the compiled native extension. Precompiled platform gems stage the
@@ -30,6 +32,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"
@@ -46,6 +49,13 @@ require_relative "microsandbox/sandbox"
 #     puts sb.exec("python", ["-c", "print('Hello, World!')"]).stdout
 #   end
 module Microsandbox
+  # Serializes runtime provisioning within this process: {install}, {setup} and
+  # the first-use check in {ensure_runtime!}. The installer replaces files in
+  # place, so two threads racing through a first `Sandbox.create` must not both
+  # run it. A Monitor (re-entrant) because ensure_runtime! calls install.
+  RUNTIME_SETUP_LOCK = Monitor.new
+  private_constant :RUNTIME_SETUP_LOCK
+
   class << self
     # @return [String] the gem version
     def version
@@ -73,7 +83,7 @@ module Microsandbox
     # gem supplies the runtime.
     # @return [nil]
     def install
-      Native.install
+      RUNTIME_SETUP_LOCK.synchronize { Native.install }
       nil
     end
 
@@ -92,7 +102,7 @@ module Microsandbox
       opts["version"] = version.to_s if version
       opts["force"] = true if force
       opts["skip_verify"] = true if skip_verify
-      Native.setup(opts)
+      RUNTIME_SETUP_LOCK.synchronize { Native.setup(opts) }
       nil
     end
 
@@ -129,34 +139,38 @@ 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
-      # The binaries gem won the resolver: its vendored msb (and the libkrunfw
-      # beside it) are exactly the version this gem was built for, so there is
-      # nothing to verify or download. (If `MSB_PATH` overrides it, the user owns
-      # the runtime and we fall through to the existing behaviour.)
-      if bundled_runtime_active?
-        @runtime_ready = true
-        return
-      end
-      # Opted out: the caller manages the runtime out of band, so don't fetch,
-      # verify, or repair it here. Memoize the decision (the env var is stable for
-      # the process); the operation resolves `msb` itself and surfaces any problem.
-      if auto_install_disabled?
-        @runtime_ready = true
-        return
-      end
+      RUNTIME_SETUP_LOCK.synchronize do
+        # Re-check under the lock: another thread may have finished meanwhile.
+        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
+        # The binaries gem won the resolver: its vendored msb (and the libkrunfw
+        # beside it) are exactly the version this gem was built for, so there is
+        # nothing to verify or download. (If `MSB_PATH` overrides it, the user owns
+        # the runtime and we fall through to the existing behaviour.)
+        if bundled_runtime_active?
+          @runtime_ready = true
+          return
+        end
+        # Opted out: the caller manages the runtime out of band, so don't fetch,
+        # verify, or repair it here. Memoize the decision (the env var is stable for
+        # the process); the operation resolves `msb` itself and surfaces any problem.
+        if auto_install_disabled?
+          @runtime_ready = true
+          return
+        end
 
-      unless installed?
-        warn "[microsandbox] runtime (msb + libkrunfw) not found; " \
-             "downloading to ~/.microsandbox (set MICROSANDBOX_NO_AUTO_INSTALL to skip, " \
-             "or install the microsandbox-rb-binaries gem to ship it with your bundle)..."
+        unless installed?
+          warn "[microsandbox] runtime (msb + libkrunfw) not found; " \
+               "downloading to ~/.microsandbox (set MICROSANDBOX_NO_AUTO_INSTALL to skip, " \
+               "or install the microsandbox-rb-binaries gem to ship it with your bundle)..."
+        end
+        install
+        @runtime_ready = true
       end
-      install
-      @runtime_ready = true
       nil
     end
 
@@ -175,7 +189,9 @@ module Microsandbox
     # setter is a no-op — use `MSB_PATH` to override a bundled runtime.
     # @param path [String]
     # @return [void]
+    # @raise [ArgumentError] for nil or an empty path (the slot cannot be cleared)
     def runtime_path=(path)
+      require_runtime_path!(:runtime_path=, path)
       if @bundled_msb_path && path.to_s != @bundled_msb_path
         warn "[microsandbox] runtime_path= ignored: the microsandbox-rb-binaries gem already " \
              "claimed the set-once SDK slot (#{@bundled_msb_path}); set MSB_PATH to override it"
@@ -189,7 +205,9 @@ module Microsandbox
     # Mirrors {runtime_path=} for libkrunfw.
     # @param path [String]
     # @return [void]
+    # @raise [ArgumentError] for nil or an empty path (the slot cannot be cleared)
     def libkrunfw_path=(path)
+      require_runtime_path!(:libkrunfw_path=, path)
       Native.set_runtime_libkrunfw_path(path.to_s)
     end
 
@@ -271,6 +289,36 @@ module Microsandbox
         raise TypeError, "data must be a String (got #{data.class})"
     end
 
+    # A Time for an epoch-milliseconds Integer from the native layer, or nil.
+    # Integer arithmetic on purpose: `Time.at(ms / 1000.0)` goes through a
+    # Float and lands one millisecond low for about half of all timestamps.
+    # @api private
+    # @param ms [Integer, nil]
+    # @return [Time, nil]
+    def time_from_ms(ms)
+      ms && Time.at(ms.div(1000), ms % 1000, :millisecond)
+    end
+
+    # Run the block, then close +resource+ — the shared tail of the block forms
+    # that own a resource whose close can fail (a write sink flushes on close).
+    # If the block raised, its exception is the one the caller needs: a failure
+    # from the close that follows is dropped instead of replacing it. If the
+    # block finished (or left via break/throw), a close failure propagates.
+    # @api private
+    def close_after(resource)
+      raised = false
+      yield
+    rescue Exception # standard:disable Lint/RescueException -- re-raised unchanged
+      raised = true
+      raise
+    ensure
+      begin
+        resource.close
+      rescue
+        raise unless raised
+      end
+    end
+
     private
 
     # Auto-provisioning is on by default; any non-empty, non-"0"/"false" value
@@ -357,12 +405,22 @@ module Microsandbox
     private_constant :TRUSTED_BINARIES_OWNERS
 
     # Name of the loaded gem whose files define Microsandbox::Binaries, or nil
-    # when it came from a bare load path.
+    # when it came from a bare load path. Gem roots can nest — a host project
+    # that is itself a gem, with its bundle installed under the project
+    # directory, is a prefix of every gem in that bundle — so the owner is the
+    # gem with the LONGEST matching root, not whichever one is listed first.
     def bundled_runtime_owner
       source = Binaries.method(:msb_path).source_location&.first
       return nil unless source
-      spec = Gem.loaded_specs.values.find { |s| source.start_with?(File.join(s.full_gem_path, "")) }
-      spec&.name
+      roots = Gem.loaded_specs.values.select { |s| source.start_with?(File.join(s.full_gem_path, "")) }
+      roots.max_by { |s| s.full_gem_path.length }&.name
+    end
+
+    # The runtime path slots are set-once in the core and have no "unset": nil
+    # or "" would be stored as an empty path for the rest of the process.
+    def require_runtime_path!(setter, path)
+      return unless path.nil? || path.to_s.empty?
+      raise ArgumentError, "#{setter} needs a non-empty path (the slot is set-once and cannot be cleared)"
     end
 
     # Whether the binaries gem's msb is what the resolver actually returns — i.e.

data/sig/microsandbox.rbs

@@ -261,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,
@@ -576,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.16.0
+  version: 0.17.1
 platform: ruby
 authors:
 - ya-luotao
@@ -43,6 +43,17 @@ files:
 - DESIGN.md
 - LICENSE
 - README.md
+- SECURITY.md
+- docs/configuration.md
+- docs/errors.md
+- docs/execution.md
+- docs/filesystem.md
+- docs/images.md
+- docs/lifecycle.md
+- docs/observability.md
+- docs/releasing.md
+- docs/runtime.md
+- docs/surface.md
 - ext/microsandbox/Cargo.toml
 - ext/microsandbox/extconf.rb
 - ext/microsandbox/src/agent.rs
@@ -51,6 +62,7 @@ files:
 - ext/microsandbox/src/error.rs
 - ext/microsandbox/src/exec.rs
 - ext/microsandbox/src/fs_stream.rs
+- ext/microsandbox/src/host_path.rs
 - ext/microsandbox/src/image.rs
 - ext/microsandbox/src/lib.rs
 - ext/microsandbox/src/runtime.rs
@@ -59,6 +71,7 @@ files:
 - ext/microsandbox/src/ssh.rs
 - ext/microsandbox/src/stream.rs
 - ext/microsandbox/src/volume.rs
+- lib/microsandbox-rb.rb
 - lib/microsandbox.rb
 - lib/microsandbox/agent.rb
 - lib/microsandbox/backend_info.rb
@@ -71,6 +84,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