process_executer 3.2.3 → 4.0.0

data/lib/process_executer/commands/run.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative 'spawn_with_timeout'
+
+module ProcessExecuter
+  module Commands
+    # Run a command and return the {ProcessExecuter::Result}
+    #
+    # Extends {ProcessExecuter::Commands::SpawnWithTimeout} to provide the core functionality for
+    # {ProcessExecuter.run}.
+    #
+    # It accepts all [Process.spawn execution
+    # options](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Execution+Options)
+    # plus the additional options `timeout_after`, `raise_errors` and `logger`.
+    #
+    # This class wraps any stdout or stderr redirection destinations in a {MonitoredPipe}.
+    # This allows any class that implements `#write` to be used as an output redirection
+    # destination. This means that you can redirect to a StringIO which is not possible
+    # with `Process.spawn`.
+    #
+    # @api private
+    #
+    class Run < SpawnWithTimeout
+      # Run a command and return the result
+      #
+      # Wrap the stdout and stderr redirection destinations in pipes and then execute
+      # the command.
+      #
+      # @example
+      #   options = ProcessExecuter::Options::RunOptions.new(raise_errors: true)
+      #   result = ProcessExecuter::Commands::Run.new('echo hello', options).call
+      #   result.success? # => true
+      #   result.exitstatus # => 0
+      #
+      # @raise [ProcessExecuter::SpawnError] `Process.spawn` raised an error before the
+      #   command was run
+      #
+      # @raise [ProcessExecuter::FailedError] If the command ran and failed
+      #
+      # @raise [ProcessExecuter::SignaledError] If the command ran and terminated due to
+      #   an unhandled signal
+      #
+      # @raise [ProcessExecuter::TimeoutError] If the command timed out
+      #
+      # @raise [ProcessExecuter::ProcessIOError] If there was an exception while
+      #   collecting subprocess output
+      #
+      # @return [ProcessExecuter::Result] The result of the completed subprocess
+      #
+      def call
+        opened_pipes = wrap_stdout_stderr
+        super.tap do
+          log_result
+          raise_errors if options.raise_errors
+        end
+      ensure
+        opened_pipes.each_value(&:close)
+        opened_pipes.each { |option_key, pipe| raise_pipe_error(option_key, pipe) }
+      end
+
+      private
+
+      # Wrap the stdout and stderr redirection options with a MonitoredPipe
+      # @return [Hash<Object, ProcessExecuter::MonitoredPipe>] The opened pipes (the Object is the option key)
+      def wrap_stdout_stderr
+        options.each_with_object({}) do |key_value, opened_pipes|
+          key, value = key_value
+
+          next unless should_wrap?(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
+      def should_wrap?(key, value)
+        (options.stdout_redirection?(key) || options.stderr_redirection?(key)) &&
+          ProcessExecuter::Destinations.compatible_with_monitored_pipe?(value)
+      end
+
+      # Raise an error if the command failed
+      # @return [void]
+      # @raise [ProcessExecuter::FailedError] If the command ran and failed
+      # @raise [ProcessExecuter::SignaledError] If the command ran and terminated due to an unhandled signal
+      # @raise [ProcessExecuter::TimeoutError] If the command timed out
+      def raise_errors
+        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
+      # @return [void]
+      def log_result
+        options.logger.info { "PID #{pid}: #{command} exited with status #{result}" }
+      end
+
+      # Raises a ProcessIOError if the given pipe has a recorded exception
+      #
+      # @param option_key [Object] The redirection option key
+      #
+      #   For example, `:out`, or an Array like `[:out, :err]` for merged streams.
+      #
+      # @param pipe [ProcessExecuter::MonitoredPipe] The pipe that raised the exception
+      #
+      # @raise [ProcessExecuter::ProcessIOError] If there was an exception while collecting subprocess output
+      #
+      # @return [void]
+      #
+      def raise_pipe_error(option_key, pipe)
+        return unless pipe.exception
+
+        error = ProcessExecuter::ProcessIOError.new("Pipe Exception for #{command}: #{option_key.inspect}")
+        raise(error, cause: pipe.exception)
+      end
+    end
+  end
+end

data/lib/process_executer/commands/run_with_capture.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module ProcessExecuter
+  module Commands
+    # Runs a subprocess, blocks until it completes, and returns the result
+    #
+    # Extends {ProcessExecuter::Commands::Run} to provide the core functionality for
+    # {ProcessExecuter.run_with_capture}.
+    #
+    # It accepts all [Process.spawn execution
+    # options](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Execution+Options)
+    # plus the additional options `timeout_after`, `raise_errors`, `logger`, and
+    # `merge_output`.
+    #
+    # Like {Run}, any stdout or stderr redirection destinations are wrapped in a
+    # {MonitoredPipe}.
+    #
+    # @api private
+    #
+    class RunWithCapture < Run
+      # Run a command and return the result which includes the captured output
+      #
+      # @example
+      #   options = ProcessExecuter::Options::RunWithCaptureOptions.new(merge_output: false)
+      #   result = ProcessExecuter::Commands::RunWithCapture.new('echo hello', options).call
+      #   result.success? # => true
+      #   result.exitstatus # => 0
+      #   result.stdout # => "hello\n"
+      #
+      # @raise [ProcessExecuter::SpawnError] `Process.spawn` raised an error before the
+      #   command was run
+      #
+      # @raise [ProcessExecuter::FailedError] If the command ran and failed
+      #
+      # @raise [ProcessExecuter::SignaledError] If the command ran and terminated due to
+      #   an unhandled signal
+      #
+      # @raise [ProcessExecuter::TimeoutError] If the command timed out
+      #
+      # @raise [ProcessExecuter::ProcessIOError] If there was an exception while
+      #   collecting subprocess output
+      #
+      # @return [ProcessExecuter::ResultWithCapture] The result of the completed subprocess
+      #
+      def call
+        @stdout_buffer = StringIO.new
+        stdout_buffer.set_encoding(options.effective_stdout_encoding)
+        @stderr_buffer = StringIO.new
+        stderr_buffer.set_encoding(options.effective_stderr_encoding)
+
+        update_capture_options
+
+        begin
+          super
+        ensure
+          log_command_output
+        end
+      end
+
+      # The buffer used to capture stdout
+      #
+      # @example
+      #   run.stdout_buffer #=> StringIO
+      #
+      # @return [StringIO]
+      #
+      attr_reader :stdout_buffer
+
+      # The buffer used to capture stderr
+      #
+      # @example
+      #   run.stderr_buffer #=> StringIO
+      #
+      # @return [StringIO]
+      #
+      attr_reader :stderr_buffer
+
+      private
+
+      # Create a result object that includes the captured stdout and stderr
+      #
+      # @return [ProcessExecuter::ResultWithCapture] The result of the command with captured output
+      #
+      def create_result
+        ProcessExecuter::ResultWithCapture.new(
+          super, stdout_buffer:, stderr_buffer:
+        )
+      end
+
+      # Updates {options} to include the stdout and stderr capture options
+      #
+      # @return [Void]
+      #
+      def update_capture_options
+        out = stdout_buffer
+        err = options.merge_output ? [:child, 1] : stderr_buffer
+
+        options.merge!(
+          capture_option(:out, stdout_redirection_source, stdout_redirection_destination, out),
+          capture_option(:err, stderr_redirection_source, stderr_redirection_destination, err)
+        )
+      end
+
+      # The source for stdout redirection
+      # @return [Object]
+      def stdout_redirection_source = options.stdout_redirection_source
+
+      # The source for stderr redirection
+      # @return [Object]
+      def stderr_redirection_source = options.stderr_redirection_source
+
+      # The destination for stdout redirection
+      # @return [Object]
+      def stdout_redirection_destination = options.stdout_redirection_destination
+
+      # The destination for stderr redirection
+      # @return [Object]
+      def stderr_redirection_destination = options.stderr_redirection_destination
+
+      # Add the capture redirection to existing options (if any)
+      # @param redirection_source [Symbol, Integer] The source of the redirection (e.g., :out, :err)
+      # @param given_source [Symbol, Integer, nil] The source provided by the user (if any)
+      # @param given_destination [Object, nil] The destination provided by the user (if any)
+      # @param capture_destination [Object] The additional destination to capture output to
+      # @return [Hash] The option (including the capture_destination) to merge into options
+      def capture_option(redirection_source, given_source, given_destination, capture_destination)
+        if given_source
+          if Destinations::Tee.handles?(given_destination)
+            { given_source => given_destination + [capture_destination] }
+          else
+            { given_source => [:tee, given_destination, capture_destination] }
+          end
+        else
+          { redirection_source => capture_destination }
+        end
+      end
+
+      # Log the captured command output to the given logger at debug level
+      # @return [Void]
+      def log_command_output
+        options.logger&.debug { "PID #{pid}: stdout: #{stdout_buffer.string.inspect}" }
+        options.logger&.debug { "PID #{pid}: stderr: #{stderr_buffer.string.inspect}" }
+      end
+    end
+  end
+end

data/lib/process_executer/commands/spawn_with_timeout.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module ProcessExecuter
+  module Commands
+    # Spawns a subprocess, waits until it completes, and returns the result
+    #
+    # Wraps `Process.spawn` to provide the core functionality for
+    # {ProcessExecuter.spawn_with_timeout}.
+    #
+    # It accepts all [Process.spawn execution
+    # options](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Execution+Options)
+    # plus the additional option `timeout_after`.
+    #
+    # @api private
+    #
+    class SpawnWithTimeout
+      # Create a new SpawnWithTimeout instance
+      #
+      # @example
+      #   options = ProcessExecuter::Options::SpawnWithTimeoutOptions.new(timeout_after: 5)
+      #   result = ProcessExecuter::Commands::SpawnWithTimeout.new('echo hello', options).call
+      #   result.success? # => true
+      #   result.exitstatus # => 0
+      #
+      # @param command [Array<String>] The command to run in the subprocess
+      # @param options [ProcessExecuter::Options::SpawnWithTimeoutOptions] The options to use when spawning the process
+      #
+      def initialize(command, options)
+        @command = command
+        @options = options
+      end
+
+      # Run a command and return the result
+      #
+      # @example
+      #   options = ProcessExecuter::Options::SpawnWithTimeoutOptions.new(timeout_after: 5)
+      #   result = ProcessExecuter::Commands::SpawnWithTimeout.new('echo hello', options).call
+      #   result.success? # => true
+      #   result.exitstatus # => 0
+      #   result.timed_out? # => false
+      #
+      # @raise [ProcessExecuter::SpawnError] `Process.spawn` raised an error before the
+      #   command was run
+      #
+      # @return [ProcessExecuter::Result] The result of the completed subprocess
+      #
+      def call
+        begin
+          @pid = Process.spawn(*command, **options.spawn_options)
+        rescue StandardError => e
+          raise ProcessExecuter::SpawnError, "Failed to spawn process: #{e.message}"
+        end
+
+        wait_for_process
+      end
+
+      # The command to be run in the subprocess
+      # @see Process.spawn
+      # @example
+      #   spawn.command #=> ['echo', 'hello']
+      # @return [Array<String>]
+      attr_reader :command
+
+      # The options that were used to spawn the process
+      # @example
+      #   spawn.options #=> ProcessExecuter::Options::SpawnWithTimeoutOptions
+      # @return [ProcessExecuter::Options::SpawnWithTimeoutOptions]
+      attr_reader :options
+
+      # The process ID of the spawned subprocess
+      #
+      # @example
+      #   spawn.pid #=> 12345
+      #
+      # @return [Integer]
+      #
+      attr_reader :pid
+
+      # The status returned by Process.wait2
+      #
+      # @example
+      #   spawn.status #=> #<Process::Status: pid 12345 exit 0>
+      #
+      # @return [Process::Status]
+      #
+      attr_reader :status
+
+      # Whether the process timed out
+      #
+      # @example
+      #   spawn.timed_out? #=> true
+      #
+      # @return [Boolean]
+      #
+      attr_reader :timed_out
+
+      alias timed_out? timed_out
+
+      # The elapsed time in seconds that the command ran
+      #
+      # @example
+      #   spawn.elapsed_time #=> 1.234
+      #
+      # @return [Numeric]
+      #
+      attr_reader :elapsed_time
+
+      # The result of the completed subprocess
+      #
+      # @example
+      #   spawn.result #=> ProcessExecuter::Result
+      #
+      # @return [ProcessExecuter::Result]
+      #
+      attr_reader :result
+
+      private
+
+      # Wait for process to terminate
+      #
+      # If a `:timeout_after` is specified in options, terminate the process after the
+      # specified number of seconds.
+      #
+      # @return [ProcessExecuter::Result] The result of the completed subprocess
+      #
+      def wait_for_process
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @status, @timed_out = wait_for_process_raw
+        @elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        @result = create_result
+      end
+
+      # Create a result object that includes the status, command, and other details
+      #
+      # @return [ProcessExecuter::Result] The result of the command
+      #
+      def create_result
+        ProcessExecuter::Result.new(status, command:, options:, timed_out:, elapsed_time:)
+      end
+
+      # Wait for a process to terminate returning the status and timed out flag
+      #
+      # @return [Array<Process::Status, Boolean>] an array containing the process status and a boolean
+      #   indicating whether the process timed out
+      def wait_for_process_raw
+        timed_out = false
+
+        process_status =
+          begin
+            Timeout.timeout(options.timeout_after) { Process.wait2(pid).last }
+          rescue Timeout::Error
+            Process.kill('KILL', pid)
+            timed_out = true
+            Process.wait2(pid).last
+          end
+
+        [process_status, timed_out]
+      end
+    end
+  end
+end

data/lib/process_executer/commands.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'commands/spawn_with_timeout'
+require_relative 'commands/run'
+require_relative 'commands/run_with_capture'
+
+module ProcessExecuter
+  # Classes that implement commands for process execution
+  # @api private
+  module Commands; end
+end

data/lib/process_executer/destinations/child_redirection.rb

@@ -1,22 +1,23 @@
 # frozen_string_literal: true
 
+require_relative 'destination_base'
+
 module ProcessExecuter
   module Destinations
-    # Handles generic objects that respond to write
+    # Handles [:child, fd] redirection options as supported by `Process.spawn`
     #
     # @api private
-    class ChildRedirection < ProcessExecuter::DestinationBase
+    class ChildRedirection < DestinationBase
       # Determines if this class can handle the given destination
       #
       # @param destination [Object] the destination to check
-      # @return [Boolean] true if destination responds to write but is not an IO with fileno
+      # @return [Boolean] true if the destination is an array in the format [:child, file_descriptor]
       def self.handles?(destination)
         destination.is_a?(Array) && destination.size == 2 && destination[0] == :child
       end
 
       # This class should not be wrapped in a monitored pipe
       # @return [Boolean]
-      # @api private
       def self.compatible_with_monitored_pipe? = false
     end
   end

data/lib/process_executer/destinations/close.rb

@@ -1,22 +1,23 @@
 # frozen_string_literal: true
 
+require_relative 'destination_base'
+
 module ProcessExecuter
   module Destinations
-    # Handles generic objects that respond to write
+    # Handles the :close redirection option as supported by `Process.spawn`
     #
     # @api private
-    class Close < ProcessExecuter::DestinationBase
+    class Close < DestinationBase
       # Determines if this class can handle the given destination
       #
       # @param destination [Object] the destination to check
-      # @return [Boolean] true if destination responds to write but is not an IO with fileno
+      # @return [Boolean] true if the destination is the symbol `:close`
       def self.handles?(destination)
         destination == :close
       end
 
       # This class should not be wrapped in a monitored pipe
       # @return [Boolean]
-      # @api private
       def self.compatible_with_monitored_pipe? = false
     end
   end

data/lib/process_executer/destinations/destination_base.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ProcessExecuter
+  module Destinations
+    # Base class for all destination handlers
+    #
+    # Provides the common interface and functionality for all destination
+    # classes that handle different types of output redirection.
+    #
+    # @api private
+    class DestinationBase
+      # Initializes a new destination handler
+      #
+      # @param destination [Object] the destination to write to
+      #
+      def initialize(destination)
+        @destination = destination
+      end
+
+      # The destination object this handler manages
+      #
+      # @return [Object] the destination object
+      attr_reader :destination
+
+      # Writes data to the destination
+      #
+      # Subclasses should override this method to provide specific write behavior.
+      # The base implementation is a no-op.
+      #
+      # @param _data [String] the data to write
+      #
+      # @return [Integer] the number of bytes written
+      #
+      def write(_data)
+        0
+      end
+
+      # Closes the destination if necessary
+      #
+      # By default, this method does nothing. Subclasses should override
+      # this method if they need to perform cleanup.
+      #
+      # @return [void]
+      def close; end
+
+      # Determines if this class can handle the given destination
+      #
+      # This is an abstract class method that must be implemented by subclasses.
+      #
+      # @param destination [Object] the destination to check
+      # @return [Boolean] true if this class can handle the destination
+      # @raise [NotImplementedError] if the subclass doesn't implement this method
+      def self.handles?(destination)
+        raise NotImplementedError
+      end
+
+      # Determines if this destination class can be wrapped by MonitoredPipe
+      #
+      # All destination types can be wrapped by MonitoredPipe unless they explicitly
+      # opt out.
+      #
+      # @return [Boolean]
+      def self.compatible_with_monitored_pipe? = true
+
+      # Determines if this destination instance can be wrapped by MonitoredPipe
+      #
+      # @return [Boolean]
+      def compatible_with_monitored_pipe?
+        self.class.compatible_with_monitored_pipe?
+      end
+    end
+  end
+end

data/lib/process_executer/destinations/file_descriptor.rb

@@ -1,35 +1,39 @@
 # frozen_string_literal: true
 
-require 'process_executer/destination_base'
+require_relative 'destination_base'
 
 module ProcessExecuter
   module Destinations
     # Handles numeric file descriptors
     #
     # @api private
-    class FileDescriptor < ProcessExecuter::DestinationBase
+    class FileDescriptor < DestinationBase
       # Writes data to the file descriptor
       #
       # @param data [String] the data to write
+      #
       # @return [Integer] the number of bytes written
+      #
       # @raise [SystemCallError] if the file descriptor is invalid
       #
       # @example
       #   fd_handler = ProcessExecuter::Destinations::FileDescriptor.new(3)
       #   fd_handler.write("Hello world")
+      #
       def write(data)
         super
         io = ::IO.open(destination, mode: 'a', autoclose: false)
-        io.write(data)
-        io.close
+        io.write(data).tap { io.close }
       end
 
       # Determines if this class can handle the given destination
       #
       # @param destination [Object] the destination to check
-      # @return [Boolean] true if destination is an Integer that's not stdout/stderr
+      #
+      # @return [Boolean] true if destination is a file descriptor that's not stdout or stderr
+      #
       def self.handles?(destination)
-        destination.is_a?(Integer) && ![:out, 1, :err, 2].include?(destination)
+        destination.is_a?(Integer) && ![1, 2].include?(destination)
       end
     end
   end

data/lib/process_executer/destinations/file_path.rb

@@ -1,18 +1,21 @@
 # frozen_string_literal: true
 
+require_relative 'destination_base'
+
 module ProcessExecuter
   module Destinations
     # Handles file path destinations
     #
     # @api private
-    class FilePath < ProcessExecuter::DestinationBase
+    class FilePath < DestinationBase
       # Initializes a new file path destination handler
       #
-      # Opens the file at the given path for writing.
+      # Redirects to the file at destination via `open(destination, 'w', 0644)`
       #
       # @param destination [String] the file path to write to
-      # @return [FilePath] a new file path destination handler
+      #
       # @raise [Errno::ENOENT] if the file path is invalid
+      #
       def initialize(destination)
         super
         @file = File.open(destination, 'w', 0o644)
@@ -25,13 +28,16 @@ module ProcessExecuter
 
       # Writes data to the file
       #
+      # @example
+      #   file_handler = ProcessExecuter::Destinations::FilePath.new("output.log")
+      #   file_handler.write("Log entry")
+      #
       # @param data [String] the data to write
+      #
       # @return [Integer] the number of bytes written
+      #
       # @raise [IOError] if the file is closed
       #
-      # @example
-      #   file_handler = ProcessExecuter::Destinations::FilePath.new("output.log")
-      #   file_handler.write("Log entry")
       def write(data)
         super
         file.write data