process_executer 1.3.0 → 3.0.0

data/lib/process_executer/command/errors.rb

@@ -1,170 +0,0 @@
-# frozen_string_literal: true
-
-# rubocop:disable Layout/LineLength
-
-module ProcessExecuter
-  module Command
-    # Base class for all ProcessExecuter::Command errors
-    #
-    # It is recommended to rescue `ProcessExecuter::Command::Error` to catch any
-    # runtime error raised by this gem unless you need more specific error handling.
-    #
-    # Custom errors are arranged in the following class hierarchy:
-    #
-    # ```text
-    # ::StandardError
-    #   └─> Error
-    #       ├─> CommandError
-    #       │   ├─> FailedError
-    #       │   └─> SignaledError
-    #       │       └─> TimeoutError
-    #       └─> ProcessIOError
-    # ```
-    #
-    # | Error Class | Description |
-    # | --- | --- |
-    # | `Error` | This catch-all error serves as the base class for other custom errors. |
-    # | `CommandError` | A subclass of this error is raised when there is a problem executing a command. |
-    # | `FailedError` | Raised when the command exits with a non-zero status code. |
-    # | `SignaledError` | Raised when the command is terminated as a result of receiving a signal. This could happen if the process is forcibly terminated or if there is a serious system error. |
-    # | `TimeoutError` | This is a specific type of `SignaledError` that is raised when the command times out and is killed via the SIGKILL signal. Raised when the operation takes longer than the specified timeout duration (if provided). |
-    # | `ProcessIOError` | Raised when an error was encountered reading or writing to the command's subprocess. |
-    #
-    # @example Rescuing any error
-    #   begin
-    #     ProcessExecuter.run_command('git', 'status')
-    #   rescue ProcessExecuter::Command::Error => e
-    #     puts "An error occurred: #{e.message}"
-    #   end
-    #
-    # @example Rescuing a timeout error
-    #   begin
-    #     timeout_duration = 0.1 # seconds
-    #     ProcessExecuter.run_command('sleep', '1', timeout: timeout_duration)
-    #   rescue ProcessExecuter::TimeoutError => e # Catch the more specific error first!
-    #     puts "Command took too long and timed out: #{e}"
-    #   rescue ProcessExecuter::Error => e
-    #     puts "Some other error occured: #{e}"
-    #   end
-    #
-    # @api public
-    #
-    class Error < ::StandardError; end
-
-    # Raised when a command fails or exits because of an uncaught signal
-    #
-    # The command executed, status, stdout, and stderr are available from this
-    # object.
-    #
-    # The Gem will raise a more specific error for each type of failure:
-    #
-    # * {FailedError}: when the command exits with a non-zero status
-    # * {SignaledError}: when the command exits because of an uncaught signal
-    # * {TimeoutError}: when the command times out
-    #
-    # @api public
-    #
-    class CommandError < ProcessExecuter::Command::Error
-      # Create a CommandError object
-      #
-      # @example
-      #   `exit 1` # set $? appropriately for this example
-      #   result = ProcessExecuter::Command::Result.new(%w[git status], $?, 'stdout', 'stderr')
-      #   error = ProcessExecuter::Command::CommandError.new(result)
-      #   error.to_s #=> '["git", "status"], status: pid 89784 exit 1, stderr: "stderr"'
-      #
-      # @param result [Result] The result of the command including the command,
-      #   status, stdout, and stderr
-      #
-      def initialize(result)
-        @result = result
-        super(error_message)
-      end
-
-      # The human readable representation of this error
-      #
-      # @example
-      #   error.error_message #=> '["git", "status"], status: pid 89784 exit 1, stderr: "stderr"'
-      #
-      # @return [String]
-      #
-      def error_message
-        "#{result.command}, status: #{result}, stderr: #{result.stderr_to_s.inspect}"
-      end
-
-      # @attribute [r] result
-      #
-      # The result of the command including the command, its status and its output
-      #
-      # @example
-      #   error.result #=> #<ProcessExecuter::Command::Result:0x00007f9b1b8b3d20>
-      #
-      # @return [Result]
-      #
-      attr_reader :result
-    end
-
-    # Raised when the command returns a non-zero exitstatus
-    #
-    # @api public
-    #
-    class FailedError < ProcessExecuter::Command::CommandError; end
-
-    # Raised when the command exits because of an uncaught signal
-    #
-    # @api public
-    #
-    class SignaledError < ProcessExecuter::Command::CommandError; end
-
-    # Raised when the command takes longer than the configured timeout
-    #
-    # @example
-    #   result.status.timeout? #=> true
-    #
-    # @api public
-    #
-    class TimeoutError < ProcessExecuter::Command::SignaledError
-      # Create a TimeoutError object
-      #
-      # @example
-      #   command = %w[sleep 10]
-      #   timeout_duration = 1
-      #   status = ProcessExecuter.spawn(*command, timeout: timeout_duration)
-      #   result = Result.new(command, status, 'stdout', 'err output')
-      #   error = TimeoutError.new(result, timeout_duration)
-      #   error.error_message
-      #     #=> '["sleep", "10"], status: pid 70144 SIGKILL (signal 9), stderr: "err output", timed out after 1s'
-      #
-      # @param result [Result] The result of the command including the git command,
-      #   status, stdout, and stderr
-      #
-      # @param timeout_duration [Numeric] The duration the subprocess was allowed
-      #   to run before being terminated
-      #
-      def initialize(result, timeout_duration)
-        @timeout_duration = timeout_duration
-        super(result)
-      end
-
-      # The amount of time the subprocess was allowed to run before being killed
-      #
-      # @example
-      #   `kill -9 $$` # set $? appropriately for this example
-      #   result = Result.new(%w[git status], $?, '', "killed")
-      #   error = TimeoutError.new(result, 10)
-      #   error.timeout_duration #=> 10
-      #
-      # @return [Numeric]
-      #
-      attr_reader :timeout_duration
-    end
-
-    # Raised when the output of a command can not be read
-    #
-    # @api public
-    #
-    class ProcessIOError < ProcessExecuter::Command::Error; end
-  end
-end
-
-# rubocop:enable Layout/LineLength

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