process_executer 1.3.0 → 3.0.0

data/lib/process_executer/result.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module ProcessExecuter
+  # A decorator for Process::Status that adds the following attributes:
+  #
+  # * `command`: the command that was used to spawn the process
+  # * `options`: the options that were used to spawn the process
+  # * `elapsed_time`: the secs the command ran
+  # * `stdout`: the captured stdout output
+  # * `stderr`: the captured stderr output
+  # * `timed_out?`: true if the process timed out
+  #
+  # @api public
+  #
+  class Result < SimpleDelegator
+    # Create a new Result object
+    #
+    # @param status [Process::Status] the status to delegate to
+    # @param command [Array] the command that was used to spawn the process
+    # @param options [ProcessExecuter::Options] the options that were used to spawn the process
+    # @param timed_out [Boolean] true if the process timed out
+    # @param elapsed_time [Numeric] the secs the command ran
+    #
+    # @example
+    #   command = ['sleep 1']
+    #   options = ProcessExecuter::Options.new(timeout_after: 0.5)
+    #   start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    #   timed_out = false
+    #   status = nil
+    #   pid = Process.spawn(*command, **options.spawn_options)
+    #   Timeout.timeout(options.timeout_after) do
+    #     _pid, status = Process.wait2(pid)
+    #   rescue Timeout::Error
+    #     Process.kill('KILL', pid)
+    #     timed_out = true
+    #     _pid, status = Process.wait2(pid)
+    #   end
+    #   elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+    #
+    #   ProcessExecuter::Result.new(status, command:, options:, timed_out:, elapsed_time:)
+    #
+    # @api public
+    #
+    def initialize(status, command:, options:, timed_out:, elapsed_time:)
+      super(status)
+      @command = command
+      @options = options
+      @timed_out = timed_out
+      @elapsed_time = elapsed_time
+    end
+
+    # The command that was used to spawn the process
+    # @see Process.spawn
+    # @example
+    #   result.command #=> [{ 'GIT_DIR' => '/path/to/repo' }, 'git', 'status']
+    # @return [Array]
+    attr_reader :command
+
+    # The options that were used to spawn the process
+    # @see Process.spawn
+    # @example
+    #   result.options #=> { chdir: '/path/to/repo', timeout_after: 0.5 }
+    # @return [Hash]
+    # @api public
+    attr_reader :options
+
+    # The secs the command ran
+    # @example
+    #   result.elapsed_time #=> 10
+    # @return [Numeric, nil]
+    # @api public
+    attr_reader :elapsed_time
+
+    # @!attribute [r] timed_out?
+    # True if the process timed out and was sent the SIGKILL signal
+    # @example
+    #   result = ProcessExecuter.spawn('sleep 10', timeout_after: 0.01)
+    #   result.timed_out? # => true
+    # @return [Boolean]
+    #
+    def timed_out?
+      @timed_out
+    end
+
+    # Overrides the default success? method to return nil if the process timed out
+    #
+    # This is because when a timeout occurs, Windows will still return true.
+    #
+    # @example
+    #   result = ProcessExecuter.spawn('sleep 10', timeout_after: 0.01)
+    #   result.success? # => nil
+    # @return [true, nil]
+    #
+    def success?
+      return nil if timed_out? # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
+
+      super
+    end
+
+    # Return a string representation of the result
+    # @example
+    #   result.to_s #=> "pid 70144 SIGKILL (signal 9) timed out after 10s"
+    # @return [String]
+    def to_s
+      "#{super}#{timed_out? ? " timed out after #{options.timeout_after}s" : ''}"
+    end
+
+    # Return the captured stdout output
+    #
+    # This output is only returned if the `:out` option value is a
+    # `ProcessExecuter::MonitoredPipe`.
+    #
+    # @example
+    #   # Note that `ProcessExecuter.run` will wrap the given out: object in a
+    #   # ProcessExecuter::MonitoredPipe
+    #   result = ProcessExecuter.run('echo hello': out: StringIO.new)
+    #   result.stdout #=> "hello\n"
+    #
+    # @return [String, nil]
+    #
+    def stdout
+      pipe = options.stdout_redirection_value
+      return nil unless pipe.is_a?(ProcessExecuter::MonitoredPipe)
+
+      pipe.destination.string
+    end
+
+    # Return the captured stderr output
+    #
+    # This output is only returned if the `:err` option value is a
+    # `ProcessExecuter::MonitoredPipe`.
+    #
+    # @example
+    #   # Note that `ProcessExecuter.run` will wrap the given err: object in a
+    #   # ProcessExecuter::MonitoredPipe
+    #   result = ProcessExecuter.run('echo ERROR 1>&2', err: StringIO.new)
+    #   resuilt.stderr #=> "ERROR\n"
+    #
+    # @return [String, nil]
+    #
+    def stderr
+      pipe = options.stderr_redirection_value
+      return nil unless pipe.is_a?(ProcessExecuter::MonitoredPipe)
+
+      pipe.destination.string
+    end
+  end
+end

data/lib/process_executer/runner.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module ProcessExecuter
+  # The `Runner` class executes subprocess commands and captures their status and output.
+  #
+  # It does the following:
+  # - Run commands (`call`) with options for capturing output, handling timeouts, and merging stdout/stderr.
+  # - Process command results, including logging and error handling.
+  # - Raise detailed exceptions for common command failures, such as timeouts or subprocess errors.
+  #
+  # This class is used internally by {ProcessExecuter.run}.
+  #
+  # @api public
+  #
+  class Runner
+    # Run a command and return the status including stdout and stderr output
+    #
+    # @example
+    #   runner = ProcessExecuter::Runner.new()
+    #   result = runner.call('echo hello')
+    #   result = ProcessExecuter.run('echo hello')
+    #   result.success? # => true
+    #   result.exitstatus # => 0
+    #   result.stdout # => "hello\n"
+    #   result.stderr # => ""
+    #
+    # @param command [Array<String>] The command to run
+    # @param options [ProcessExecuter::Options::RunOptions] Options for running the command
+    #
+    # @return [ProcessExecuter::Result] The result of the completed subprocess
+    #
+    def call(command, options)
+      spawn(command, options).tap { |result| process_result(result) }
+    end
+
+    private
+
+    # Wrap the output buffers in pipes and then execute the command
+    #
+    # @param command [Array<String>] The command to execute
+    # @param options [ProcessExecuter::Options::RunOptions] Options for running the command
+    #
+    # @raise [ProcessExecuter::ProcessIOError] If an exception was raised while collecting subprocess output
+    # @raise [ProcessExecuter::TimeoutError] If the command times out
+    #
+    # @return [ProcessExecuter::Result] The result of the completed subprocess
+    #
+    # @api private
+    #
+    def spawn(command, options)
+      opened_pipes = wrap_stdout_stderr(options)
+      ProcessExecuter.spawn_and_wait_with_options(command, options)
+    ensure
+      opened_pipes.each { |key, value| close_pipe(command, key, value) }
+    end
+
+    # Wrap the stdout and stderr redirection options with a MonitoredPipe
+    # @param options [ProcessExecuter::Options::RunOptions] Options for running the command
+    # @return [Hash<Object, ProcessExecuter::MonitoredPipe>] The opened pipes (the Object is the option key)
+    # @api private
+    def wrap_stdout_stderr(options)
+      options.each_with_object({}) do |key_value, opened_pipes|
+        key, value = key_value
+
+        next unless should_wrap?(options, key, value)
+
+        wrapped_destination = ProcessExecuter::MonitoredPipe.new(value)
+        opened_pipes[key] = wrapped_destination
+        options.merge!(key => wrapped_destination)
+      end
+    end
+
+    # Should the redirection option be wrapped by a MonitoredPipe
+    # @param key [Object] The option key
+    # @param value [Object] The option value
+    # @return [Boolean] Whether the option should be wrapped
+    # @api private
+    def should_wrap?(options, key, value)
+      (options.stdout_redirection?(key) || options.stderr_redirection?(key)) &&
+        ProcessExecuter::Destinations.compatible_with_monitored_pipe?(value)
+    end
+
+    # Close the pipe and raise an error if the pipe raised an exception
+    # @return [void]
+    # @raise [ProcessExecuter::ProcessIOError] If an exception was raised while
+    #   collecting subprocess output
+    # @api private
+    def close_pipe(command, option_key, pipe)
+      pipe.close
+      raise_pipe_error(command, option_key, pipe) if pipe.exception
+    end
+
+    # Process the result of the command and return a ProcessExecuter::Result
+    #
+    # Log the command and result, and raise an error if the command failed.
+    #
+    # @param result [ProcessExecuter::Result] The result of the command
+    #
+    # @return [Void]
+    #
+    # @raise [ProcessExecuter::FailedError] If the command failed
+    # @raise [ProcessExecuter::SignaledError] If the command was signaled
+    # @raise [ProcessExecuter::TimeoutError] If the command times out
+    # @raise [ProcessExecuter::ProcessIOError] If an exception was raised while collecting subprocess output
+    #
+    # @api private
+    #
+    def process_result(result)
+      log_result(result)
+
+      raise_errors(result) if result.options.raise_errors
+    end
+
+    # Raise an error if the command failed
+    # @return [void]
+    # @raise [ProcessExecuter::FailedError] If the command failed
+    # @raise [ProcessExecuter::SignaledError] If the command was signaled
+    # @raise [ProcessExecuter::TimeoutError] If the command times out
+    # @api private
+    def raise_errors(result)
+      raise TimeoutError, result if result.timed_out?
+      raise SignaledError, result if result.signaled?
+      raise FailedError, result unless result.success?
+    end
+
+    # Log the result of running the command
+    # @param result [ProcessExecuter::Result] the result of the command including
+    #   the command, status, stdout, and stderr
+    # @return [void]
+    # @api private
+    def log_result(result)
+      result.options.logger.info { "#{result.command} exited with status #{result}" }
+      result.options.logger.debug { "stdout:\n#{result.stdout.inspect}\nstderr:\n#{result.stderr.inspect}" }
+    end
+
+    # Raise an error when there was exception while collecting the subprocess output
+    #
+    # @param command [Array<String>] The command that was executed
+    # @param option_key [Symbol] The name of the pipe that raised the exception
+    # @param pipe [ProcessExecuter::MonitoredPipe] The pipe that raised the exception
+    #
+    # @raise [ProcessExecuter::ProcessIOError]
+    #
+    # @return [void] This method always raises an error
+    #
+    # @api private
+    #
+    def raise_pipe_error(command, option_key, pipe)
+      error = ProcessExecuter::ProcessIOError.new("Pipe Exception for #{command}: #{option_key.inspect}")
+      raise(error, cause: pipe.exception)
+    end
+  end
+end

data/lib/process_executer/version.rb

@@ -2,5 +2,5 @@
 
 module ProcessExecuter
   # The current Gem version
-  VERSION = '1.3.0'
+  VERSION = '3.0.0'
 end