mxc 0.1.0

data/lib/mxc/preflight.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module MXC
+  module Preflight # :nodoc:
+    NETWORK_TOOLS = %w[slirp4netns iptables ip6tables iptables-restore ip6tables-restore nsenter unshare].freeze
+    TUN = '/dev/net/tun'
+    INSTALL = 'Install slirp4netns, iptables and util-linux ' \
+              '(Debian/Ubuntu: apt-get install slirp4netns iptables util-linux; ' \
+              'Fedora: dnf install slirp4netns iptables-nft util-linux; ' \
+              'Arch: pacman -S slirp4netns iptables util-linux)'
+    WINDOWS_ALLOW_LIST = 'Use network: false, or network: true for unrestricted access. On Windows, MXC confines ' \
+                         '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'
+
+    module_function
+
+    def check!(network:, denied: [])
+      error = problem(network:, denied:)
+      raise error if error
+    end
+
+    def problem(network:, denied: [], path: ENV.fetch('PATH', ''), tun: TUN)
+      return windows_problem(network, denied) if windows?
+      return unless network && linux?
+
+      missing = NETWORK_TOOLS.reject { |tool| executable?(tool, path) }
+      if missing.any?
+        return UnsupportedError.new("Network access from a sandbox needs #{missing.join(', ')} on PATH",
+                                    code: :backend_unavailable, remediation: INSTALL)
+      end
+      return if tun_usable?(tun)
+
+      UnsupportedError.new("Network access from a sandbox needs a usable #{tun}",
+                           code: :backend_unavailable, remediation: tun_remediation)
+    end
+
+    def linux?
+      RUBY_PLATFORM.include?('linux')
+    end
+
+    def windows?
+      Gem.win_platform?
+    end
+
+    def windows_problem(network, denied)
+      if network.is_a?(Hash)
+        UnsupportedError.new('Host allow-lists are not supported on Windows',
+                             code: :backend_unavailable, remediation: WINDOWS_ALLOW_LIST)
+      elsif denied.any? && !denied_paths_enforced?
+        UnsupportedError.new("MXC's AppContainer sandbox on this Windows build does not enforce denied paths",
+                             code: :backend_unavailable, remediation: WINDOWS_DENIED)
+      end
+    end
+
+    def denied_paths_enforced?
+      MXC.backends.any? { |backend| backend.supports?(:filesystem_denied_paths) }
+    end
+
+    def executable?(tool, path)
+      path.split(File::PATH_SEPARATOR).any? do |dir|
+        file = File.join(dir, tool)
+        File.file?(file) && File.executable?(file)
+      end
+    end
+
+    def tun_usable?(tun)
+      File.open(tun, File::RDWR) { true }
+    rescue SystemCallError
+      false
+    end
+
+    def tun_remediation
+      if File.exist?('/.dockerenv') || File.exist?('/run/.containerenv')
+        'Pass the TUN device to the container: docker run --device /dev/net/tun ' \
+          '(Kamal: options: { device: /dev/net/tun } on the role)'
+      else
+        'Load the tun kernel module: sudo modprobe tun'
+      end
+    end
+  end
+end

data/lib/mxc/process.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module MXC
+  # A command running in a sandbox, as returned by Sandbox#spawn.
+  #
+  #   process = MXC.sandbox.spawn("python3 -i")
+  #   process.write("print(6 * 7)\n")
+  #   process.close_write
+  #   process.each { |chunk| print chunk.content }
+  #   process.wait # => #<MXC::Result exit_code=0 ...>
+  #
+  # Output is read in the background from the start, so the command never blocks on a full pipe,
+  # and the timeout applies whether or not anything waits.
+  class Process
+    READ_SIZE = 16 * 1024 # :nodoc:
+    STREAMS = %i[stdout stderr].freeze # :nodoc:
+
+    def initialize(native, backend:) # :nodoc:
+      @native = native
+      @backend = backend
+      @chunks = Thread::Queue.new
+      @output = STREAMS.to_h { |stream| [stream, String.new(encoding: Encoding::BINARY)] }
+      @lock = Mutex.new
+      @streams_lock = Mutex.new
+      @open_streams = STREAMS.size
+      @readers = STREAMS.map { |stream| background { read(stream) } }
+      @waiter = background { @native.wait }
+    end
+
+    # Returns the operating system process id of the sandbox.
+    def pid
+      @native.pid
+    end
+
+    # Writes +data+ to the command's standard input and returns the number of bytes written.
+    def write(data)
+      @native.write(data.to_s)
+    end
+
+    # Closes the command's standard input, so it reads end of file.
+    def close_write
+      @native.close_stdin
+      nil
+    end
+
+    # Yields each Chunk of output as it arrives, until the command closes both output streams.
+    # Returns an Enumerator without a block.
+    def each
+      return enum_for(:each) unless block_given?
+
+      while (chunk = @chunks.pop)
+        yield chunk
+      end
+      self
+    end
+
+    # Stops the command and everything it started.
+    def kill
+      @native.kill
+      nil
+    end
+
+    # Closes standard input, waits for the command to finish, and returns its Result.
+    #
+    # Raises Error, or UnsupportedError for a host problem, when the sandbox itself could not start.
+    def wait
+      @lock.synchronize { @result || (@result = finish) }
+    end
+
+    def inspect # :nodoc:
+      "#<MXC::Process pid=#{pid} backend=#{@backend.inspect}>"
+    end
+
+    private
+
+    def background(&)
+      Thread.new(&).tap { |thread| thread.report_on_exception = false }
+    end
+
+    def read(stream)
+      reader = :"read_#{stream}"
+      while (data = @native.public_send(reader, READ_SIZE))
+        @output[stream] << data
+        @chunks << Chunk.new(stream:, content: data.dup.force_encoding(Encoding.default_external).freeze)
+      end
+    rescue IOError
+      nil
+    ensure
+      @streams_lock.synchronize { @chunks.close if (@open_streams -= 1).zero? }
+    end
+
+    def finish
+      close_write
+      outcome = @waiter.value
+      @readers.each(&:join)
+      outcome = outcome.merge(stdout: @output[:stdout], stderr: @output[:stderr])
+      Result.new(**StartupFailure.check!(outcome), backend: @backend)
+    end
+  end
+end

data/lib/mxc/result.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module MXC
+  # The outcome of a command that ran in a sandbox.
+  #
+  #   result = MXC.run("python3 build.py")
+  #   result.success? # => true
+  #   result.stdout   # => "built 3 files\n"
+  class Result
+    # Returns everything the command wrote to standard output.
+    attr_reader :stdout
+
+    # Returns everything the command wrote to standard error.
+    attr_reader :stderr
+
+    # Returns the exit code, or nil when the command timed out.
+    attr_reader :exit_code
+
+    # Returns MXC's warnings about the sandbox, as Strings.
+    attr_reader :warnings
+
+    # Returns the <tt>host:port</tt> destinations the network allow-list refused.
+    attr_reader :blocked
+
+    # 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:
+      @stdout = text(stdout)
+      @stderr = text(stderr)
+      @exit_code = exit_code
+      @timed_out = timed_out
+      @warnings = warnings.freeze
+      @blocked = blocked.freeze
+      @backend = backend
+    end
+
+    # Returns true when the command exited with status 0 before its timeout.
+    def success?
+      !timed_out? && exit_code.zero?
+    end
+
+    # Returns true when the command ran out of time and was stopped.
+    def timed_out?
+      @timed_out
+    end
+
+    # Returns the result as a Hash.
+    def to_h
+      { stdout:, stderr:, exit_code:, timed_out: timed_out?, warnings:, blocked:, backend: }
+    end
+
+    def inspect # :nodoc:
+      "#<MXC::Result exit_code=#{exit_code.inspect} timed_out=#{timed_out?} backend=#{backend.inspect}>"
+    end
+
+    private
+
+    def text(bytes)
+      bytes.dup.force_encoding(Encoding.default_external).freeze
+    end
+  end
+end

data/lib/mxc/sandbox.rb

@@ -0,0 +1,366 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module MXC
+  # A sandbox policy: what a command may read, write and reach, and how long it may run.
+  #
+  # Setters return the sandbox, so they chain, and +nil+ resets a setting to its default:
+  #
+  #   sandbox = MXC.sandbox
+  #     .with_readable("app/skills")
+  #     .with_writable(Rails.root.join("tmp"))
+  #     .with_network(allow: ["pypi.org", "*.pythonhosted.org"])
+  #     .with_timeout(30)
+  #   sandbox.run("python3 app/skills/build.py")
+  #   sandbox.run("python3", "app/skills/convert.py", params[:filename])
+  #
+  # Subclasses declare the same settings with class macros:
+  #
+  #   class SkillSandbox < MXC::Sandbox
+  #     readable "app/skills"
+  #     writable "tmp/skills"
+  #     network false
+  #     timeout 30
+  #   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:
+    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:
+    DEFAULTS = {
+      readable: [], writable: [], denied: [], env: {}, network: false, directory: nil, timeout: nil, backend: nil
+    }.freeze # :nodoc:
+
+    class << self
+      # Adds paths every instance can read.
+      def readable(*paths) = configure { |sandbox| sandbox.with_readable(*paths) }
+
+      # Adds paths every instance can read and write.
+      def writable(*paths) = configure { |sandbox| sandbox.with_writable(*paths) }
+
+      # Adds paths every instance hides, even inside readable or writable paths.
+      def denied(*paths) = configure { |sandbox| sandbox.with_denied(*paths) }
+
+      # Sets every instance's network access. Takes the same arguments as #with_network.
+      def network(...) = configure { |sandbox| sandbox.with_network(...) }
+
+      # Adds environment variables for every instance.
+      def env(variables) = configure { |sandbox| sandbox.with_env(variables) }
+
+      # Sets every instance's working directory.
+      def directory(path) = configure { |sandbox| sandbox.with_directory(path) }
+
+      # Sets every instance's timeout in seconds.
+      def timeout(seconds) = configure { |sandbox| sandbox.with_timeout(seconds) }
+
+      # Sets every instance's backend.
+      def backend(name) = configure { |sandbox| sandbox.with_backend(name) }
+
+      def defaults # :nodoc:
+        @defaults ||= allocate.tap { |sandbox| sandbox.send(:inherit, self == Sandbox ? nil : superclass.defaults) }
+      end
+
+      def backend_name(name) # :nodoc:
+        name = name.to_sym
+        return name if BACKENDS.include?(name)
+
+        raise ArgumentError, "unknown backend #{name.inspect}, expected one of #{BACKENDS.map(&:inspect).join(', ')}"
+      end
+
+      def duration(seconds) # :nodoc:
+        return if seconds.nil?
+
+        value = seconds.to_f
+        unless value.positive?
+          raise ArgumentError,
+                "timeout must be a positive number of seconds, got #{seconds.inspect}"
+        end
+
+        seconds
+      end
+
+      private
+
+      def configure
+        yield defaults
+        nil
+      end
+    end
+
+    # 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>.
+    #
+    #   MXC::Sandbox.new(readable: "app/skills", network: { allow: ["pypi.org"] }, timeout: 30)
+    def initialize(**options)
+      unknown = options.keys - OPTIONS
+      raise ArgumentError, "unknown option#{'s' if unknown.size > 1}: #{unknown.join(', ')}" if unknown.any?
+
+      inherit(self.class.defaults)
+      options.each { |name, value| apply(name, value) }
+    end
+
+    def initialize_copy(source) # :nodoc:
+      super
+      @settings = @settings.transform_values(&:dup)
+    end
+
+    # Returns the paths the command can read, as given.
+    def readable = @settings[:readable].dup.freeze
+
+    # Returns the paths the command can read and write, as given.
+    def writable = @settings[:writable].dup.freeze
+
+    # Returns the paths hidden from the command, as given.
+    def denied = @settings[:denied].dup.freeze
+
+    # Returns the environment variables set for the command.
+    def env = @settings[:env].dup.freeze
+
+    # Returns the network access: +false+, +true+, or <tt>{ allow: [...] }</tt> for an allow-list.
+    def network = @settings[:network]
+
+    # Returns the working directory, or nil for the default.
+    def directory = @settings[:directory]
+
+    # Returns the timeout in seconds, falling back to MXC.config.timeout.
+    def timeout = @settings[:timeout] || MXC.config.timeout
+
+    # Returns the backend, falling back to MXC.config.backend.
+    def backend = @settings[:backend] || MXC.config.backend
+
+    # 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)
+      add_paths(:readable, paths)
+    end
+
+    # Adds paths the command can read and write.
+    def with_writable(*paths)
+      add_paths(:writable, paths)
+    end
+
+    # Adds paths hidden from the command, even inside readable or writable paths.
+    def with_denied(*paths)
+      add_paths(:denied, paths)
+    end
+
+    # Sets network access. The default, +false+, gives the command no network at all.
+    # +true+ allows any destination. <tt>allow:</tt> takes a list of hosts the command
+    # may reach over HTTP and HTTPS: <tt>"pypi.org"</tt>, <tt>"*.pythonhosted.org"</tt>
+    # (subdomains only), or <tt>"example.com:8443"</tt> for another port.
+    #
+    #   sandbox.with_network(allow: ["pypi.org", "*.pythonhosted.org"])
+    def with_network(enabled = true, allow: nil)
+      if allow
+        raise ArgumentError, 'pass allow: or true/false, not both' unless enabled == true
+
+        @settings[:network] = { allow: Array(allow).map(&:to_s).freeze }.freeze
+      else
+        raise ArgumentError, "network must be true, false or nil, got #{enabled.inspect}" unless [true, false,
+                                                                                                  nil].include?(enabled)
+
+        @settings[:network] = enabled || false
+      end
+      self
+    end
+
+    # Adds environment variables for the command. The sandbox starts from a minimal
+    # environment, not the parent's. On Windows, that environment keeps the system
+    # variables programs need to start, such as +SYSTEMROOT+ and +PATH+.
+    #
+    #   sandbox.with_env("LANG" => "C.UTF-8")
+    def with_env(variables)
+      env = @settings[:env]
+      variables.nil? ? env.clear : variables.each { |name, value| env[name.to_s] = value.to_s }
+      self
+    end
+
+    # Sets the directory the command starts in. The sandbox must be able to read it.
+    # Without one, the command starts in <tt>/</tt>, or <tt>%SystemRoot%</tt> on Windows.
+    def with_directory(path)
+      @settings[:directory] = path && File.path(path)
+      self
+    end
+
+    # Sets the timeout in seconds. Accepts anything that responds to +to_f+, such as
+    # <tt>30</tt>, <tt>2.5</tt> or <tt>1.minute</tt>.
+    def with_timeout(seconds)
+      @settings[:timeout] = self.class.duration(seconds)
+      self
+    end
+
+    # Sets the backend: <tt>:auto</tt> (Bubblewrap on Linux, Seatbelt on macOS,
+    # ProcessContainer on Windows), <tt>:bubblewrap</tt>, <tt>:seatbelt</tt>, or
+    # <tt>:process_container</tt>.
+    def with_backend(name)
+      @settings[:backend] = name && self.class.backend_name(name)
+      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
+    # reaches the program unchanged, without a shell.
+    #
+    # With a block, yields each Chunk of output as it arrives.
+    #
+    #   sandbox.run("python3 build.py && ls dist")
+    #   sandbox.run("python3", "convert.py", params[:filename])
+    #   sandbox.run("python3", "build.py") { |chunk| print chunk.content }
+    #
+    # Raises ArgumentError without a command or when given an Array. On Windows, it also
+    # raises ArgumentError for a program and arguments that start a +.bat+ or +.cmd+ file,
+    # because Windows runs those through +cmd.exe+, which splits the arguments again.
+    def run(*command, &)
+      return stream(*command, &) if block_given?
+
+      outcome = StartupFailure.check!(Native.run(command_line(command), request))
+      Result.new(**outcome, backend: resolved_backend)
+    end
+
+    # Starts +command+ and returns its Process without waiting for it. Takes the command
+    # the same way as #run.
+    #
+    #   sandbox.spawn("python3", "-i", "-q")
+    def spawn(*command)
+      Process.new(Native.spawn(command_line(command), request), backend: resolved_backend)
+    end
+
+    # Returns true when this host can run this sandbox, including its network policy.
+    def supported?
+      availability.supported?
+    end
+
+    # 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:)
+      return MXC.availability(backend:) unless problem
+
+      Availability.new(backend:, supported: false, reason: problem.message, remediation: problem.remediation)
+    end
+
+    def inspect # :nodoc:
+      "#<#{self.class.name || 'MXC::Sandbox'} backend=#{backend.inspect} network=#{network.inspect} " \
+        "readable=#{readable.inspect} writable=#{writable.inspect} timeout=#{timeout.inspect}>"
+    end
+
+    protected
+
+    attr_reader :settings # :nodoc:
+
+    private
+
+    def inherit(source)
+      @settings = source ? source.settings.transform_values(&:dup) : DEFAULTS.transform_values(&:dup)
+    end
+
+    def apply(name, value)
+      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)
+      else public_send(:"with_#{name}", value)
+      end
+    end
+
+    def add_paths(name, paths)
+      list = @settings[name]
+      paths == [nil] ? list.clear : list.concat(paths.flatten.map { |path| File.path(path) })
+      self
+    end
+
+    def stream(*command, &)
+      process = spawn(*command)
+      finished = false
+      process.each(&)
+      finished = true
+      process.wait
+    ensure
+      process&.kill unless finished
+    end
+
+    def command_line(command)
+      arguments = command_arguments(command)
+      return command_line_for_windows(arguments) if Preflight.windows?
+
+      arguments.one? ? arguments.first : Shellwords.join(arguments)
+    end
+
+    def command_arguments(command)
+      raise ArgumentError, 'no command given' if command.empty?
+      if command.any?(Array)
+        raise ArgumentError, 'pass the program and its arguments as separate Strings, ' \
+                             'as in run("python3", "build.py"), not as an Array'
+      end
+
+      command.map { |argument| String.try_convert(argument) || File.path(argument) }
+    end
+
+    def command_line_for_windows(arguments)
+      return %(cmd.exe /d /s /c "#{arguments.first}") if arguments.one?
+
+      if arguments.first.match?(BATCH_FILE)
+        raise ArgumentError, 'Windows runs batch files through cmd.exe, which does not keep arguments apart. ' \
+                             'Run them with one String and quote untrusted input yourself'
+      end
+
+      arguments.map { |argument| WindowsArguments.quote(argument) }.join(' ')
+    end
+
+    def resolved_backend
+      return backend unless backend == :auto
+      return :process_container if Preflight.windows?
+
+      Preflight.linux? ? :bubblewrap : :seatbelt
+    end
+
+    def request
+      Preflight.check!(network:, denied:)
+      {
+        readonly: expand(readable),
+        readwrite: expand(writable),
+        denied: expand(denied) | hidden_resolver_sockets,
+        environment:,
+        working_directory:,
+        timeout_ms: timeout && [(timeout.to_f * 1000).ceil, MAX_TIMEOUT_MS].min,
+        backend:,
+        network: network == true,
+        allow: network.is_a?(Hash) ? network[:allow] : nil
+      }
+    end
+
+    def expand(paths)
+      paths.map { |path| native_path(File.expand_path(path)) }
+    end
+
+    def native_path(path)
+      Preflight.windows? ? path.tr('/', '\\') : path
+    end
+
+    def working_directory
+      return native_path(File.expand_path(directory)) if directory
+
+      ENV.fetch('SystemRoot', nil) if Preflight.windows?
+    end
+
+    def environment
+      return env unless Preflight.windows?
+
+      system = ENV.to_h.select { |name, _| WINDOWS_ENV.include?(name.upcase) }
+      system.reject { |name, _| env.keys.any? { |own| own.casecmp?(name) } }.merge(env)
+    end
+
+    def hidden_resolver_sockets
+      return [] if network == true
+
+      HOST_RESOLVER_SOCKETS.select { |path| File.exist?(path) }
+    end
+  end
+end

data/lib/mxc/startup_failure.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module MXC
+  module StartupFailure # :nodoc:
+    DOCKER_GUIDE = 'https://crmne.github.io/mxc/running-in-docker/'
+    NAMESPACES = Regexp.union(/No permissions to create a?\s*new namespace/i, /Creating new namespace failed/i,
+                              /setting up uid map/i, /unshare.*Operation not permitted/i)
+    PROC = /Can't mount proc|mount proc on/i
+    HOST_PROBLEMS = {
+      NAMESPACES => 'Unprivileged user namespaces are blocked. On a host, enable kernel.unprivileged_userns_clone=1 ' \
+                    'and, on Ubuntu 23.10 and later, allow bwrap in AppArmor ' \
+                    '(kernel.apparmor_restrict_unprivileged_userns). ' \
+                    "In Docker, run with a seccomp profile that allows namespaces: #{DOCKER_GUIDE}",
+      PROC => 'bwrap cannot mount a fresh /proc because the container masks /proc paths. ' \
+              "In Docker, see #{DOCKER_GUIDE}"
+    }.freeze
+    CHDIR = /Can't chdir/i
+
+    module_function
+
+    def detect(outcome)
+      return unless outcome[:exit_code] == 1 && outcome[:stdout].to_s.empty?
+
+      stderr = outcome[:stderr].to_s
+      return unless stderr.match?(/\Abwrap: [^\n]*\n?\z/)
+
+      message = "Bubblewrap could not start the sandbox: #{stderr.strip}"
+      _, hint = HOST_PROBLEMS.find { |pattern, _| stderr.match?(pattern) }
+      return UnsupportedError.new(message, code: :backend_unavailable, remediation: hint, operation: 'bwrap') if hint
+
+      remediation = 'Make the directory readable or writable in the sandbox' if stderr.match?(CHDIR)
+      Error.new(message, code: :backend_error, remediation:, operation: 'bwrap')
+    end
+
+    def check!(outcome)
+      error = detect(outcome)
+      raise error if error
+
+      outcome
+    end
+  end
+end

data/lib/mxc/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module MXC
+  # The gem version.
+  VERSION = '0.1.0'
+end

data/lib/mxc/windows_arguments.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module MXC
+  module WindowsArguments # :nodoc:
+    SPECIAL = /[\s"]/
+
+    module_function
+
+    # Quotes +argument+ so CommandLineToArgvW and the C runtime read it back unchanged.
+    def quote(argument)
+      return '""' if argument.empty?
+      return argument unless argument.match?(SPECIAL)
+
+      quoted = argument.gsub(/(\\*)"/) { "#{Regexp.last_match(1) * 2}\\\"" }
+      "\"#{quoted.sub(/(\\+)\z/) { Regexp.last_match(1) * 2 }}\""
+    end
+  end
+end