process_executer 3.2.4 → 4.0.0

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

data/lib/process_executer/destinations/file_path_mode.rb

@@ -1,17 +1,18 @@
 # frozen_string_literal: true
 
+require_relative 'destination_base'
+
 module ProcessExecuter
   module Destinations
     # Handles file paths with specific open modes
     #
     # @api private
-    class FilePathMode < ProcessExecuter::DestinationBase
+    class FilePathMode < DestinationBase
       # Initializes a new file path with mode destination handler
       #
-      # Opens the file at the given path with the specified mode.
+      # Redirects to the file at destination via `open(destination[0], destination[1], 0644)`
       #
       # @param destination [Array<String, String>] array with file path and mode
-      # @return [FilePathMode] a new file path with mode destination handler
       # @raise [Errno::ENOENT] if the file path is invalid
       # @raise [ArgumentError] if the mode is invalid
       def initialize(destination)
@@ -26,13 +27,16 @@ module ProcessExecuter
 
       # Writes data to the file
       #
+      # @example
+      #   mode_handler = ProcessExecuter::Destinations::FilePathMode.new(["output.log", "a"])
+      #   mode_handler.write("Appended log entry")
+      #
       # @param data [String] the data to write
+      #
       # @return [Integer] the number of bytes written
+      #
       # @raise [IOError] if the file is closed
       #
-      # @example
-      #   mode_handler = ProcessExecuter::Destinations::FilePathMode.new(["output.log", "a"])
-      #   mode_handler.write("Appended log entry")
       def write(data)
         super
         file.write data

data/lib/process_executer/destinations/file_path_mode_perms.rb

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
 
+require_relative 'destination_base'
+
 module ProcessExecuter
   module Destinations
     # Handles file paths with specific open modes and permissions
     #
     # @api private
-    class FilePathModePerms < ProcessExecuter::DestinationBase
+    class FilePathModePerms < DestinationBase
       # Initializes a new file path with mode and permissions destination handler
       #
       # Opens the file at the given path with the specified mode and permissions.
       #
       # @param destination [Array<String, String, Integer>] array with file path, mode, and permissions
-      # @return [FilePathModePerms] a new handler instance
+      #
       # @raise [Errno::ENOENT] if the file path is invalid
+      #
       # @raise [ArgumentError] if the mode is invalid
+      #
       def initialize(destination)
         super
         @file = File.open(destination[0], destination[1], destination[2])
@@ -26,13 +30,16 @@ module ProcessExecuter
 
       # Writes data to the file
       #
+      # @example
+      #   perms_handler = ProcessExecuter::Destinations::FilePathModePerms.new(["output.log", "w", 0644])
+      #   perms_handler.write("Log entry with specific permissions")
+      #
       # @param data [String] the data to write
+      #
       # @return [Integer] the number of bytes written
+      #
       # @raise [IOError] if the file is closed
       #
-      # @example
-      #   perms_handler = ProcessExecuter::Destinations::FilePathModePerms.new(["output.log", "w", 0644])
-      #   perms_handler.write("Log entry with specific permissions")
       def write(data)
         super
         file.write data

data/lib/process_executer/destinations/io.rb

@@ -1,21 +1,26 @@
 # frozen_string_literal: true
 
+require_relative 'destination_base'
+
 module ProcessExecuter
   module Destinations
     # Handles IO objects
     #
     # @api private
-    class IO < ProcessExecuter::DestinationBase
+    class IO < DestinationBase
       # Writes data to the IO object
       #
-      # @param data [String] the data to write
-      # @return [Integer] the number of bytes written
-      # @raise [IOError] if the IO object is closed
-      #
       # @example
       #   io = File.open('file.txt', 'w')
       #   io_handler = ProcessExecuter::Destinations::IO.new(io)
       #   io_handler.write("Hello world")
+      #
+      # @param data [String] the data to write
+      #
+      # @return [Integer] the number of bytes written
+      #
+      # @raise [IOError] if the IO object is closed
+      #
       def write(data)
         super
         destination.write data