process_executer 1.3.0 → 2.0.0

data/lib/process_executer/command/result.rb

@@ -1,77 +0,0 @@
-# frozen_string_literal: true
-
-require 'delegate'
-
-module ProcessExecuter
-  module Command
-    # A wrapper around {ProcessExecuter::Status} which adds captured command output
-    #
-    # This class is used to represent the result of a subprocess execution, combining
-    # the process status with the captured output for easier access and manipulation.
-    #
-    # Features:
-    # * Provides access to the process's status, stdout, and stderr.
-    # * Allows conversion of stdout and stderr buffers to strings.
-    #
-    # @example Create a Result object
-    #   status = ProcessExecuter.spawn(*command, timeout:, out:, err:)
-    #   result = ProcessExecuter::Command::Result.new(command, status, out_buffer.string, err_buffer.string)
-    #
-    # @api public
-    #
-    class Result < SimpleDelegator
-      # Create a new Result object
-      # @example
-      #   status = ProcessExecuter.spawn(*command, timeout:, out:, err:)
-      #   Result.new(command, status, out_buffer.string, err_buffer.string)
-      # @param command [Array<String>] The command that was executed
-      # @param status [ProcessExecuter::Status] The status of the process
-      # @param stdout [String] The stdout output from the process
-      # @param stderr [String] The stderr output from the process
-      def initialize(command, status, stdout, stderr)
-        super(status)
-        @command = command
-        @stdout = stdout
-        @stderr = stderr
-      end
-
-      # The command that was run
-      # @example
-      #   result.command #=> %w[git status]
-      # @return [Array<String>]
-      attr_reader :command
-
-      # The captured stdout output from the process
-      # @example
-      #   result.stdout #=> "On branch master\nnothing to commit, working tree clean\n"
-      # @return [String]
-      attr_reader :stdout
-
-      # The captured stderr output from the process
-      # @example
-      #   result.stderr #=> "ERROR: file not found"
-      # @return [String]
-      attr_reader :stderr
-
-      # Return the stdout output as a string
-      # @example When stdout is a StringIO containing "Hello World"
-      #   result.stdout_to_s #=> "Hello World"
-      # @example When stdout is a File object
-      #   result.stdout_to_s #=> #<File:/tmp/output.txt>
-      # @return [String, Object] Returns a String if stdout is a StringIO; otherwise, returns the stdout object
-      def stdout_to_s
-        stdout.respond_to?(:string) ? stdout.string : stdout
-      end
-
-      # Return the stderr output as a string
-      # @example When stderr is a StringIO containing "Hello World"
-      #   result.stderr_to_s #=> "Hello World"
-      # @example When stderr is a File object
-      #   result.stderr_to_s #=> #<File:/tmp/output.txt>
-      # @return [String, Object] Returns a String if stderr is a StringIO; otherwise, returns the stderr object
-      def stderr_to_s
-        stderr.respond_to?(:string) ? stderr.string : stderr
-      end
-    end
-  end
-end

data/lib/process_executer/command/runner.rb

@@ -1,167 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'errors'
-require_relative 'result'
-
-module ProcessExecuter
-  module Command
-    # 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
-      # Create a new RunCommand instance
-      #
-      # @example
-      #   runner = Runner.new()
-      #   status = runner.call('echo', 'hello')
-      #
-      # @param logger [Logger] The logger to use. Defaults to a no-op logger if nil.
-      #
-      def initialize(logger)
-        @logger = logger || Logger.new(nil)
-      end
-
-      # The logger to use
-      # @example
-      #   runner.logger #=> #<Logger:0x00007f9b1b8b3d20>
-      # @return [Logger]
-      attr_reader :logger
-
-      # rubocop:disable Metrics/ParameterLists
-
-      # Run a command and return the status including stdout and stderr output
-      #
-      # @example
-      #   command = %w[git status]
-      #   status = run(command)
-      #   status.success? # => true
-      #   status.exitstatus # => 0
-      #   status.out # => "On branch master\nnothing to commit, working tree clean\n"
-      #   status.err # => ""
-      #
-      # @param command [Array<String>] The command to run
-      # @param out [#write] The object to which stdout is written
-      # @param err [#write] The object to which stderr is written
-      # @param merge [Boolean] Write both stdout and stderr into the buffer for stdout
-      # @param raise_errors [Boolean] Raise an exception if the command fails
-      # @param options_hash [Hash] Additional options to pass to Process.spawn
-      #
-      #   See {ProcessExecuter.run} for a full list of options.
-      #
-      # @return [ProcessExecuter::Command::Result] The status of the subprocess and captured stdout and stderr output
-      #
-      def call(*command, out: nil, err: nil, merge: false, raise_errors: true, **options_hash)
-        out ||= StringIO.new
-        err ||= (merge ? out : StringIO.new)
-
-        status = spawn(command, out:, err:, **options_hash)
-
-        process_result(command, status, out, err, options_hash[:timeout], raise_errors)
-      end
-
-      # rubocop:enable Metrics/ParameterLists
-
-      private
-
-      # Wrap the output buffers in pipes and then execute the command
-      #
-      # @param command [Array<String>] The command to execute
-      # @param out [#write] The object to which stdout is written
-      # @param err [#write] The object to which stderr is written
-      # @param options_hash [Hash] Additional options to pass to Process.spawn
-      #
-      #   See {ProcessExecuter.run} for a full list of options.
-      #
-      # @raise [ProcessExecuter::Command::ProcessIOError] If an exception was raised while collecting subprocess output
-      # @raise [ProcessExecuter::Command::TimeoutError] If the command times out
-      #
-      # @return [ProcessExecuter::Status] The status of the completed subprocess
-      #
-      # @api private
-      #
-      def spawn(command, out:, err:, **options_hash)
-        out = [out] unless out.is_a?(Array)
-        err = [err] unless err.is_a?(Array)
-        out_pipe = ProcessExecuter::MonitoredPipe.new(*out)
-        err_pipe = ProcessExecuter::MonitoredPipe.new(*err)
-        ProcessExecuter.spawn(*command, out: out_pipe, err: err_pipe, **options_hash)
-      ensure
-        out_pipe.close
-        err_pipe.close
-        raise_pipe_error(command, :stdout, out_pipe) if out_pipe.exception
-        raise_pipe_error(command, :stderr, err_pipe) if err_pipe.exception
-      end
-
-      # rubocop:disable Metrics/ParameterLists
-
-      # Process the result of the command and return a ProcessExecuter::Command::Result
-      #
-      # Log the command and result, and raise an error if the command failed.
-      #
-      # @param command [Array<String>] The git command that was executed
-      # @param status [Process::Status] The status of the completed subprocess
-      # @param out [#write] The object that stdout was written to
-      # @param err [#write] The object that stderr was written to
-      # @param timeout [Numeric, nil] The maximum seconds to wait for the command to complete
-      # @param raise_errors [Boolean] Raise an exception if the command fails
-      #
-      # @return [ProcessExecuter::Command::Result] The status of the subprocess and captured stdout and stderr output
-      #
-      # @raise [ProcessExecuter::Command::FailedError] If the command failed
-      # @raise [ProcessExecuter::Command::SignaledError] If the command was signaled
-      # @raise [ProcessExecuter::Command::TimeoutError] If the command times out
-      # @raise [ProcessExecuter::Command::ProcessIOError] If an exception was raised while collecting subprocess output
-      #
-      # @api private
-      #
-      def process_result(command, status, out, err, timeout, raise_errors)
-        Result.new(command, status, out, err).tap do |result|
-          log_result(result)
-
-          if raise_errors
-            raise TimeoutError.new(result, timeout) if status.timeout?
-            raise SignaledError, result if status.signaled?
-            raise FailedError, result unless status.success?
-          end
-        end
-      end
-
-      # rubocop:enable Metrics/ParameterLists
-
-      # Log the command and result of the subprocess
-      # @param result [ProcessExecuter::Command::Result] the result of the command including
-      #   the command, status, stdout, and stderr
-      # @return [void]
-      # @api private
-      def log_result(result)
-        logger.info { "#{result.command} exited with status #{result}" }
-        logger.debug { "stdout:\n#{result.stdout_to_s.inspect}\nstderr:\n#{result.stderr_to_s.inspect}" }
-      end
-
-      # Raise an error when there was exception while collecting the subprocess output
-      #
-      # @param command [Array<String>] The command that was executed
-      # @param pipe_name [Symbol] The name of the pipe that raised the exception
-      # @param pipe [ProcessExecuter::MonitoredPipe] The pipe that raised the exception
-      #
-      # @raise [ProcessExecuter::Command::ProcessIOError]
-      #
-      # @return [void] This method always raises an error
-      #
-      # @api private
-      #
-      def raise_pipe_error(command, pipe_name, pipe)
-        error = ProcessExecuter::Command::ProcessIOError.new("Pipe Exception for #{command}: #{pipe_name}")
-        raise(error, cause: pipe.exception)
-      end
-    end
-  end
-end

data/lib/process_executer/command.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module ProcessExecuter
-  # This module contains classes for implementing ProcessExecuter.run_command
-  module Command; end
-end
-
-require_relative 'command/errors'
-require_relative 'command/result'
-require_relative 'command/runner'
-
-# Runs a command and returns the result

data/lib/process_executer/status.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-require 'delegate'
-require 'forwardable'
-
-module ProcessExecuter
-  # A simple delegator for Process::Status that adds a `timeout?` attribute
-  #
-  # @api public
-  #
-  class Status < SimpleDelegator
-    extend Forwardable
-
-    # Create a new Status object from a Process::Status and timeout flag
-    #
-    # @param status [Process::Status] the status to delegate to
-    # @param timeout [Boolean] true if the process timed out
-    # @param timeout_duration [Numeric, nil] The secs the command ran before being killed OR o or nil for no timeout
-    #
-    # @example
-    #   status = Process.wait2(pid).last
-    #   timeout = false
-    #   ProcessExecuter::Status.new(status, timeout)
-    #
-    # @api public
-    #
-    def initialize(status, timeout, timeout_duration)
-      super(status)
-      @timeout = timeout
-      @timeout_duration = timeout_duration
-    end
-
-    # The secs the command ran before being killed OR o or nil for no timeout
-    # @example
-    #   status.timeout_duration #=> 10
-    # @return [Numeric, nil]
-    attr_reader :timeout_duration
-
-    # @!attribute [r] timeout?
-    # True if the process timed out and was sent the SIGKILL signal
-    # @example
-    #   status = ProcessExecuter.spawn('sleep 10', timeout: 0.01)
-    #   status.timeout? # => true
-    # @return [Boolean]
-    #
-    def timeout? = @timeout
-
-    # 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
-    #   status = ProcessExecuter.spawn('sleep 10', timeout: 0.01)
-    #   status.success? # => nil
-    # @return [Boolean, nil]
-    #
-    def success?
-      return nil if timeout? # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
-
-      super
-    end
-
-    # Return a string representation of the status
-    # @example
-    #   status.to_s #=> "pid 70144 SIGKILL (signal 9) timed out after 10s"
-    # @return [String]
-    def to_s
-      "#{super}#{timeout? ? " timed out after #{timeout_duration}s" : ''}"
-    end
-  end
-end