mxc 0.1.0-x86_64-linux → 0.2.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 937f45a4c10fe7ba6663b0385284ea1299601e105ff9629c0734dafce0db89b5
-  data.tar.gz: 6f4f495281d51b6f85f4928e7115c6587d21600e688553e766cb93dcbf9b573a
+  metadata.gz: 86bb54e129b48e32e469fa771293b5d887064fad5a98c1ed7d47e98c823288e2
+  data.tar.gz: 22054e5c8fe708cf11fcacfba0e1612a296716f7f7f7f8428d2786ba93ca9e18
 SHA512:
-  metadata.gz: 3b6af2d6bd101e36254b046de3f6236d2a8711faf1c93e38da019cc7ae7950b1450738d3977c2e03f1361878b968ea902f5bc0e6e304442104a6ff9260b97a95
-  data.tar.gz: eedb50f24207a0b79b9f0c67cc15ca6b90e51bf96587f7b9d6efbbce81843909c4ae677c8be013a636eb617815ee3ab943031ebf2c044a86888825fe26191d73
+  metadata.gz: 4db21a001399af4632811e84238a37b32d9d21b10fead1d87e62599385a5aa2fa661690fd182a35d9a0c6453981e4ad39970ca0262dccb2144a3b435b1f73e34
+  data.tar.gz: eef8f390ec961e9940660c10f2020820a7e341c8e53e584385b80571f8876d8291f6c94796ccb5da110705d1d33af045ac73f6e70b649a3e2119af48539fa61f

data/NOTICE

@@ -5,7 +5,8 @@ This gem is an unofficial Ruby binding to MXC. It is not affiliated with or
 endorsed by Microsoft.
 
 The native extension compiles and links the mxc-sdk crate
-(https://github.com/microsoft/mxc, https://crates.io/crates/mxc-sdk),
+(https://github.com/microsoft/mxc, https://crates.io/crates/mxc-sdk), from
+a fork at https://github.com/crmne/microsoft-mxc that adds resource limits,
 which is distributed under the MIT License:
 
 MIT License

data/README.md

@@ -14,7 +14,7 @@
 
 ---
 
-Your app runs code it did not write: scripts a model generated, skills users uploaded, build steps from someone else. MXC for Ruby runs them in a sandbox that decides what they can read, write, and reach, and how long they get.
+Your app runs code it did not write: scripts a model generated, skills users uploaded, build steps from someone else. MXC for Ruby runs them in a sandbox that decides what they can read, write, and reach, how long they get, and how much CPU and memory they can use.
 
 ```ruby
 result = MXC.run("python3 build.py", readable: "app/skills", writable: "tmp/out", timeout: 30)
@@ -22,7 +22,7 @@ result.stdout
 result.success?
 ```
 
-It is an unofficial Ruby binding to [Microsoft's MXC](https://github.com/microsoft/mxc), the MIT-licensed sandbox library. Not affiliated with or endorsed by Microsoft.
+It is an unofficial Ruby binding to [Microsoft's MXC](https://github.com/microsoft/mxc), the MIT-licensed sandbox library. Not affiliated with or endorsed by Microsoft. Resource limits come from [a fork of MXC](https://github.com/crmne/microsoft-mxc) until they are [part of MXC itself](https://github.com/microsoft/mxc/issues/1498).
 
 ## Installation
 
@@ -68,6 +68,14 @@ result = sandbox.run("pip download --no-deps -d /tmp/wheels requests")
 result.blocked # => hosts the allow-list refused
 ```
 
+Limit what a command can use, and lower its priority so your app stays responsive:
+
+```ruby
+result = sandbox.with_limits(cpu_time: 2.minutes, memory: 2.gigabytes).with_priority(:low).run("python3 build.py")
+result.cpu_time       # => 3.42
+result.limit_exceeded # => nil, or :cpu_time when it ran out
+```
+
 Stream output as it arrives:
 
 ```ruby
@@ -92,6 +100,7 @@ class SkillSandbox < MXC::Sandbox
   writable "tmp/skills"
   network false
   timeout 30
+  limits cpu_time: 60, memory: 1.gigabyte
 end
 
 SkillSandbox.new.run("python3 app/skills/build.py")
@@ -108,10 +117,10 @@ MXC.backends                   # => [#<MXC::Backend name=:bubblewrap ...>]
 
 ## Platforms
 
-| Platform | Backend | 0.1.0 |
+| Platform | Backend | 0.2.0 |
 | --- | --- | --- |
-| Linux | Bubblewrap | Supported and tested |
-| macOS | Seatbelt | Supported and tested |
+| Linux | Bubblewrap | Supported and tested, without process limits |
+| macOS | Seatbelt | Supported and tested, without memory or process limits |
 | Windows 11 24H2 and later | ProcessContainer | Supported and tested, without host allow-lists |
 
 On Windows, a single String runs through `cmd.exe` instead of `sh`. See [Running Commands](https://crmne.github.io/mxc/running-commands/#windows) and [Policies](https://crmne.github.io/mxc/policies/#windows) for what else differs.

data/lib/mxc/preflight.rb

@@ -12,15 +12,35 @@ module MXC
                          'a sandbox to a proxy only by also accepting inbound connections to it'
     WINDOWS_DENIED = 'Leave the paths out of readable and writable instead, or run on a Windows build where ' \
                      'MXC.supports?(:filesystem_denied_paths) is true'
+    MACOS_MEMORY = 'Leave memory out of the limits on macOS, which rejects memory rlimits. ' \
+                   'Linux and Windows support it'
+    PROCESS_LIMIT = 'Leave processes out of the limits. Only Windows can count the processes of one sandbox; ' \
+                    'in a container, limit them with docker run --pids-limit'
 
     module_function
 
-    def check!(network:, denied: [])
-      error = problem(network:, denied:)
+    def check!(network:, denied: [], resources: nil)
+      error = problem(network:, denied:, resources:)
       raise error if error
     end
 
-    def problem(network:, denied: [], path: ENV.fetch('PATH', ''), tun: TUN)
+    def problem(network:, denied: [], resources: nil, path: ENV.fetch('PATH', ''), tun: TUN)
+      resource_problem(resources) || host_problem(network, denied, path, tun)
+    end
+
+    def resource_problem(resources)
+      return if resources.nil? || windows?
+
+      if resources[:max_processes]
+        UnsupportedError.new("Process limits are not supported on #{linux? ? 'Linux' : 'macOS'}",
+                             code: :backend_unavailable, remediation: PROCESS_LIMIT)
+      elsif resources[:memory_mb] && !linux?
+        UnsupportedError.new('Memory limits are not supported on macOS',
+                             code: :backend_unavailable, remediation: MACOS_MEMORY)
+      end
+    end
+
+    def host_problem(network, denied, path, tun)
       return windows_problem(network, denied) if windows?
       return unless network && linux?
 

data/lib/mxc/result.rb

@@ -25,7 +25,18 @@ module MXC
     # Returns the backend that ran the command, such as <tt>:bubblewrap</tt>.
     attr_reader :backend
 
-    def initialize(stdout:, stderr:, exit_code:, timed_out:, warnings:, blocked:, backend:) # :nodoc:
+    # Returns the CPU time the command used, user and system, in seconds as a Float. It
+    # includes every process the command started and waited for. Returns nil unless the
+    # sandbox has limits or a priority.
+    attr_reader :cpu_time
+
+    # Returns the limit the command ran into: <tt>:cpu_time</tt>, <tt>:memory</tt>,
+    # <tt>:processes</tt>, or nil. Linux and macOS report <tt>:cpu_time</tt> only, because a
+    # program that cannot allocate memory decides itself how to fail.
+    attr_reader :limit_exceeded
+
+    def initialize(stdout:, stderr:, exit_code:, timed_out:, warnings:, blocked:, backend:, # :nodoc:
+                   cpu_time: nil, limit_exceeded: nil)
       @stdout = text(stdout)
       @stderr = text(stderr)
       @exit_code = exit_code
@@ -33,6 +44,8 @@ module MXC
       @warnings = warnings.freeze
       @blocked = blocked.freeze
       @backend = backend
+      @cpu_time = cpu_time
+      @limit_exceeded = limit_exceeded
     end
 
     # Returns true when the command exited with status 0 before its timeout.
@@ -47,11 +60,13 @@ module MXC
 
     # Returns the result as a Hash.
     def to_h
-      { stdout:, stderr:, exit_code:, timed_out: timed_out?, warnings:, blocked:, backend: }
+      { stdout:, stderr:, exit_code:, timed_out: timed_out?, warnings:, blocked:, backend:, cpu_time:,
+        limit_exceeded: }
     end
 
     def inspect # :nodoc:
-      "#<MXC::Result exit_code=#{exit_code.inspect} timed_out=#{timed_out?} backend=#{backend.inspect}>"
+      usage = " cpu_time=#{cpu_time.round(3)} limit_exceeded=#{limit_exceeded.inspect}" if cpu_time
+      "#<MXC::Result exit_code=#{exit_code.inspect} timed_out=#{timed_out?}#{usage} backend=#{backend.inspect}>"
     end
 
     private

data/lib/mxc/sandbox.rb

@@ -22,19 +22,25 @@ module MXC
   #     writable "tmp/skills"
   #     network false
   #     timeout 30
+  #     limits cpu_time: 60, memory: 2 * 1024**3
+  #     priority :low
   #   end
   #
   #   SkillSandbox.new.run("python3 app/skills/build.py")
   class Sandbox
     BACKENDS = %i[auto bubblewrap seatbelt process_container].freeze # :nodoc:
-    OPTIONS = %i[readable writable denied network env directory timeout backend].freeze # :nodoc:
+    OPTIONS = %i[readable writable denied network env directory timeout backend limits priority].freeze # :nodoc:
     HOST_RESOLVER_SOCKETS = %w[/run/systemd/resolve].freeze # :nodoc:
     WINDOWS_ENV = %w[SYSTEMROOT WINDIR SYSTEMDRIVE COMSPEC PATHEXT PATH LOCALAPPDATA TEMP TMP
                      PROCESSOR_ARCHITECTURE NUMBER_OF_PROCESSORS OS].freeze # :nodoc:
     BATCH_FILE = /\.(bat|cmd)\z/i # :nodoc:
     MAX_TIMEOUT_MS = (2**32) - 1 # :nodoc:
+    LIMITS = %i[cpu_time memory processes].freeze # :nodoc:
+    PRIORITIES = { normal: nil, low: 'low', lowest: 'idle' }.freeze # :nodoc:
+    MEGABYTE = 1024 * 1024 # :nodoc:
     DEFAULTS = {
-      readable: [], writable: [], denied: [], env: {}, network: false, directory: nil, timeout: nil, backend: nil
+      readable: [], writable: [], denied: [], env: {}, network: false, directory: nil, timeout: nil, backend: nil,
+      limits: {}, priority: nil
     }.freeze # :nodoc:
 
     class << self
@@ -62,6 +68,12 @@ module MXC
       # Sets every instance's backend.
       def backend(name) = configure { |sandbox| sandbox.with_backend(name) }
 
+      # Sets every instance's resource limits. Takes the same arguments as #with_limits.
+      def limits(...) = configure { |sandbox| sandbox.with_limits(...) }
+
+      # Sets every instance's scheduling priority: <tt>:normal</tt>, <tt>:low</tt>, or <tt>:lowest</tt>.
+      def priority(level) = configure { |sandbox| sandbox.with_priority(level) }
+
       def defaults # :nodoc:
         @defaults ||= allocate.tap { |sandbox| sandbox.send(:inherit, self == Sandbox ? nil : superclass.defaults) }
       end
@@ -95,9 +107,11 @@ module MXC
 
     # Returns a new sandbox with the class's defaults, then applies +options+ through
     # the matching setters: <tt>readable:</tt>, <tt>writable:</tt>, <tt>denied:</tt>,
-    # <tt>network:</tt>, <tt>env:</tt>, <tt>directory:</tt>, <tt>timeout:</tt> and <tt>backend:</tt>.
+    # <tt>network:</tt>, <tt>env:</tt>, <tt>directory:</tt>, <tt>timeout:</tt>, <tt>backend:</tt>,
+    # <tt>limits:</tt> and <tt>priority:</tt>.
     #
     #   MXC::Sandbox.new(readable: "app/skills", network: { allow: ["pypi.org"] }, timeout: 30)
+    #   MXC::Sandbox.new(limits: { cpu_time: 60, memory: 2 * 1024**3 }, priority: :low)
     def initialize(**options)
       unknown = options.keys - OPTIONS
       raise ArgumentError, "unknown option#{'s' if unknown.size > 1}: #{unknown.join(', ')}" if unknown.any?
@@ -135,6 +149,13 @@ module MXC
     # Returns the backend, falling back to MXC.config.backend.
     def backend = @settings[:backend] || MXC.config.backend
 
+    # Returns the resource limits, such as <tt>{ cpu_time: 60, memory: 2147483648 }</tt>.
+    # A limit that is not set is absent.
+    def limits = @settings[:limits].dup.freeze
+
+    # Returns the scheduling priority: <tt>:normal</tt>, <tt>:low</tt>, or <tt>:lowest</tt>.
+    def priority = @settings[:priority] || :normal
+
     # Adds paths the command can read. Accepts Strings and Pathnames; relative paths
     # are expanded from the current directory when the command runs.
     def with_readable(*paths)
@@ -204,6 +225,42 @@ module MXC
       self
     end
 
+    # Sets resource limits. Each process the command starts gets its own CPU time and memory.
+    #
+    # <tt>cpu_time:</tt> is the CPU time each process may use, in seconds. It accepts
+    # anything that responds to +to_f+, such as <tt>90</tt> or <tt>2.minutes</tt>, and is
+    # rounded up to whole seconds on Linux and macOS. A process that uses it up is stopped.
+    #
+    # <tt>memory:</tt> is the memory each process may allocate, in bytes. It accepts
+    # anything that responds to +to_i+, such as <tt>2 * 1024**3</tt> or
+    # <tt>2.gigabytes</tt>, and is rounded up to whole megabytes. Allocations beyond it
+    # fail. Not available on macOS.
+    #
+    # <tt>processes:</tt> is how many processes the command may run at the same time.
+    # Windows only.
+    #
+    # A limit given as +nil+ is removed, and <tt>with_limits(nil)</tt> removes them all.
+    # Raises ArgumentError for an unknown limit or a value that is not positive.
+    #
+    #   sandbox.with_limits(cpu_time: 2.minutes, memory: 2.gigabytes)
+    def with_limits(reset = (keep = true), **limits)
+      unless keep
+        raise ArgumentError, "pass limits as keywords, or nil to remove them, got #{reset.inspect}" unless reset.nil?
+
+        @settings[:limits].clear
+      end
+      limits.each { |name, value| set_limit(name, value) }
+      self
+    end
+
+    # Sets the scheduling priority of every process the command starts: <tt>:normal</tt>
+    # (the default), <tt>:low</tt> (nice 10 on Linux and macOS, below normal on
+    # Windows), or <tt>:lowest</tt> (nice 19, or idle on Windows).
+    def with_priority(level)
+      @settings[:priority] = level && priority_name(level)
+      self
+    end
+
     # Runs +command+ and returns its Result once it finishes. Like Kernel#system, one
     # String runs through the platform shell: <tt>sh -c</tt>, or <tt>cmd.exe /d /s /c</tt>
     # on Windows. Two or more Strings are a program and its arguments, and each argument
@@ -241,15 +298,16 @@ module MXC
     # Returns the Availability of this sandbox on this host, with the reason and
     # remediation when it cannot run.
     def availability
-      problem = Preflight.problem(network:, denied:)
+      problem = Preflight.problem(network:, denied:, resources:)
       return MXC.availability(backend:) unless problem
 
       Availability.new(backend:, supported: false, reason: problem.message, remediation: problem.remediation)
     end
 
     def inspect # :nodoc:
+      resources = " limits=#{limits.inspect} priority=#{priority.inspect}" if self.resources
       "#<#{self.class.name || 'MXC::Sandbox'} backend=#{backend.inspect} network=#{network.inspect} " \
-        "readable=#{readable.inspect} writable=#{writable.inspect} timeout=#{timeout.inspect}>"
+        "readable=#{readable.inspect} writable=#{writable.inspect} timeout=#{timeout.inspect}#{resources}>"
     end
 
     protected
@@ -266,10 +324,42 @@ module MXC
       case name
       when :readable, :writable, :denied then public_send(:"with_#{name}", *Array(value))
       when :network then value.is_a?(Hash) ? with_network(**value) : with_network(value)
+      when :limits then value.nil? ? with_limits(nil) : with_limits(**value)
       else public_send(:"with_#{name}", value)
       end
     end
 
+    def set_limit(name, value)
+      unless LIMITS.include?(name)
+        raise ArgumentError, "unknown limit #{name.inspect}, expected one of #{LIMITS.map(&:inspect).join(', ')}"
+      end
+      return @settings[:limits].delete(name) if value.nil?
+
+      @settings[:limits][name] = positive_limit(name, value)
+    end
+
+    def positive_limit(name, value)
+      amount = limit_amount(name, value)
+      raise ArgumentError, "#{name} must be a positive number, got #{value.inspect}" unless amount&.positive?
+
+      value
+    end
+
+    def limit_amount(name, value)
+      return (value if value.is_a?(Integer)) if name == :processes
+
+      conversion = name == :cpu_time ? :to_f : :to_i
+      value.public_send(conversion) if value.respond_to?(conversion)
+    end
+
+    def priority_name(level)
+      level = level.to_sym
+      return level if PRIORITIES.key?(level)
+
+      raise ArgumentError,
+            "unknown priority #{level.inspect}, expected one of #{PRIORITIES.keys.map(&:inspect).join(', ')}"
+    end
+
     def add_paths(name, paths)
       list = @settings[name]
       paths == [nil] ? list.clear : list.concat(paths.flatten.map { |path| File.path(path) })
@@ -322,7 +412,7 @@ module MXC
     end
 
     def request
-      Preflight.check!(network:, denied:)
+      Preflight.check!(network:, denied:, resources:)
       {
         readonly: expand(readable),
         readwrite: expand(writable),
@@ -332,10 +422,28 @@ module MXC
         timeout_ms: timeout && [(timeout.to_f * 1000).ceil, MAX_TIMEOUT_MS].min,
         backend:,
         network: network == true,
-        allow: network.is_a?(Hash) ? network[:allow] : nil
+        allow: network.is_a?(Hash) ? network[:allow] : nil,
+        resources:
       }
     end
 
+    protected
+
+    # The resource limits as MXC takes them, or nil when there are none.
+    def resources
+      limits = @settings[:limits]
+      return if limits.empty? && priority == :normal
+
+      {
+        cpu_time_ms: limits[:cpu_time] && (limits[:cpu_time].to_f * 1000).ceil,
+        memory_mb: limits[:memory] && -(-limits[:memory].to_i / MEGABYTE),
+        max_processes: limits[:processes],
+        priority: PRIORITIES.fetch(priority)
+      }.compact
+    end
+
+    private
+
     def expand(paths)
       paths.map { |path| native_path(File.expand_path(path)) }
     end

data/lib/mxc/version.rb

@@ -2,5 +2,5 @@
 
 module MXC
   # The gem version.
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/mxc.rb

@@ -19,6 +19,11 @@ require 'mxc/sandbox'
 #   result = MXC.run("python3 build.py", readable: "app/skills", writable: "tmp/out", timeout: 30)
 #   result.stdout
 module MXC
+  RESOURCE_CAPABILITIES = {
+    cpu_time_limit: { cpu_time_ms: 1 }, memory_limit: { memory_mb: 1 },
+    process_limit: { max_processes: 1 }, priority: { priority: 'low' }
+  }.freeze # :nodoc:
+
   @availability = {}
   @availability_lock = Mutex.new
 
@@ -85,13 +90,19 @@ module MXC
     # Returns true when this host supports +capability+ with the configured backend.
     #
     # +capability+ is <tt>:network</tt> for unrestricted network access,
-    # <tt>:network_policy</tt> for host allow-lists, or any capability a Backend reports.
+    # <tt>:network_policy</tt> for host allow-lists, <tt>:cpu_time_limit</tt>,
+    # <tt>:memory_limit</tt>, <tt>:process_limit</tt> and <tt>:priority</tt> for the
+    # matching Sandbox#with_limits and Sandbox#with_priority settings, or any capability a
+    # Backend reports.
+    #
+    #   MXC.supports?(:memory_limit) # => false on macOS
     def supports?(capability)
       return false unless supported?
 
       case capability
       when :network then Preflight.problem(network: true).nil?
       when :network_policy then Preflight.problem(network: { allow: [] }).nil? && proxy_enforcement?
+      when *RESOURCE_CAPABILITIES.keys then Preflight.resource_problem(RESOURCE_CAPABILITIES[capability]).nil?
       else configured_backends.any? { |backend| backend.supports?(capability) }
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mxc
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: x86_64-linux
 authors:
 - Carmine Paolino