process_executer 2.0.0 → 3.0.0

data/lib/process_executer/destinations/io.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ProcessExecuter
+  module Destinations
+    # Handles IO objects
+    #
+    # @api private
+    class IO < ProcessExecuter::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")
+      def write(data)
+        super
+        destination.write data
+      end
+
+      # Determines if this class can handle the given destination
+      #
+      # @param destination [Object] the destination to check
+      # @return [Boolean] true if destination is an IO with a valid file descriptor
+      def self.handles?(destination)
+        destination.is_a?(::IO) && destination.respond_to?(:fileno) && destination.fileno
+      end
+    end
+  end
+end

data/lib/process_executer/destinations/monitored_pipe.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ProcessExecuter
+  module Destinations
+    # Handles monitored pipes
+    #
+    # @api private
+    class MonitoredPipe < ProcessExecuter::DestinationBase
+      # Writes data to the monitored pipe
+      #
+      # @param data [String] the data to write
+      # @return [Object] the return value of the pipe's write method
+      #
+      # @example
+      #   pipe = ProcessExecuter::MonitoredPipe.new
+      #   pipe_handler = ProcessExecuter::Destinations::MonitoredPipe.new(pipe)
+      #   pipe_handler.write("Data to pipe")
+      def write(data)
+        super
+        destination.write data
+      end
+
+      # Closes the pipe if it's open
+      #
+      # @return [void]
+      def close
+        destination.close if destination.state == :open
+      end
+
+      # Determines if this class can handle the given destination
+      #
+      # @param destination [Object] the destination to check
+      # @return [Boolean] true if destination is a ProcessExecuter::MonitoredPipe
+      def self.handles?(destination)
+        destination.is_a? ProcessExecuter::MonitoredPipe
+      end
+    end
+  end
+end

data/lib/process_executer/destinations/stderr.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ProcessExecuter
+  module Destinations
+    # Handles standard error redirection
+    #
+    # @api private
+    class Stderr < ProcessExecuter::DestinationBase
+      # Writes data to standard error
+      #
+      # @param data [String] the data to write
+      # @return [Integer] the number of bytes written
+      #
+      # @example
+      #   stderr_handler = ProcessExecuter::Destinations::Stderr.new(:err)
+      #   stderr_handler.write("Error message")
+      def write(data)
+        super
+        $stderr.write data
+      end
+
+      # Determines if this class can handle the given destination
+      #
+      # @param destination [Object] the destination to check
+      # @return [Boolean] true if destination is :err or 2
+      def self.handles?(destination)
+        [:err, 2].include?(destination)
+      end
+    end
+  end
+end

data/lib/process_executer/destinations/stdout.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ProcessExecuter
+  module Destinations
+    # Handles standard output redirection
+    #
+    # @api private
+    class Stdout < ProcessExecuter::DestinationBase
+      # Writes data to standard output
+      #
+      # @param data [String] the data to write
+      # @return [Integer] the number of bytes written
+      #
+      # @example
+      #   stdout_handler = ProcessExecuter::Destinations::Stdout.new(:out)
+      #   stdout_handler.write("Hello world")
+      def write(data)
+        super
+        $stdout.write data
+      end
+
+      # Determines if this class can handle the given destination
+      #
+      # @param destination [Object] the destination to check
+      # @return [Boolean] true if destination is :out or 1
+      def self.handles?(destination)
+        [:out, 1].include?(destination)
+      end
+    end
+  end
+end

data/lib/process_executer/destinations/tee.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module ProcessExecuter
+  module Destinations
+    # Handles destination for writing to multiple destinations
+    #
+    # The destination is an array with the first element being :tee and the rest
+    # being the destinations.
+    #
+    # @api private
+    class Tee < ProcessExecuter::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
+        @child_destinations = destination[1..].map { |dest| ProcessExecuter::Destinations.factory(dest) }
+      end
+
+      # The opened file object
+      #
+      # @return [File] the opened file
+      attr_reader :child_destinations
+
+      # Writes data to the file
+      #
+      # @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
+        child_destinations.each { |dest| dest.write(data) }
+      end
+
+      # Closes the file if it's open
+      #
+      # @return [void]
+      def close
+        child_destinations.each(&: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 Array with path, mode, and permissions
+      def self.handles?(destination)
+        destination.is_a?(Array) && destination.size > 1 && destination[0] == :tee
+      end
+    end
+  end
+end

data/lib/process_executer/destinations/writer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ProcessExecuter
+  module Destinations
+    # Handles generic objects that respond to write
+    #
+    # @api private
+    class Writer < ProcessExecuter::DestinationBase
+      # Writes data to the destination object
+      #
+      # @param data [String] the data to write
+      # @return [Object] the return value of the destination's write method
+      # @raise [NoMethodError] if the destination doesn't respond to write
+      #
+      # @example
+      #   buffer = StringIO.new
+      #   writer_handler = ProcessExecuter::Destinations::Writer.new(buffer)
+      #   writer_handler.write("Hello world")
+      def write(data)
+        super
+        destination.write data
+      end
+
+      # 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
+      def self.handles?(destination)
+        destination.respond_to?(:write) && (!destination.respond_to?(:fileno) || destination.fileno.nil?)
+      end
+    end
+  end
+end

data/lib/process_executer/destinations.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative 'destinations/child_redirection'
+require_relative 'destinations/file_descriptor'
+require_relative 'destinations/file_path'
+require_relative 'destinations/file_path_mode'
+require_relative 'destinations/file_path_mode_perms'
+require_relative 'destinations/io'
+require_relative 'destinations/monitored_pipe'
+require_relative 'destinations/stderr'
+require_relative 'destinations/stdout'
+require_relative 'destinations/tee'
+require_relative 'destinations/writer'
+
+module ProcessExecuter
+  # Collection of destination handler implementations
+  #
+  # @api public
+  module Destinations
+    # Creates appropriate destination objects based on the given destination
+    #
+    # This factory method dynamically finds and instantiates the appropriate
+    # destination class for handling the provided destination.
+    #
+    # @param destination [Object] the destination to create a handler for
+    # @return [DestinationBase] an instance of the appropriate destination handler
+    # @raise [ArgumentError] if no matching destination class is found
+    #
+    # @example
+    #   ProcessExecuter.destination_factory(1) #=> Returns a Stdout instance
+    #   ProcessExecuter.destination_factory("output.log") #=> Returns a FilePath instance
+    def self.factory(destination)
+      matching_class = matching_destination_class(destination)
+      return matching_class.new(destination) if matching_class
+
+      raise ArgumentError, 'wrong exec redirect action'
+    end
+
+    # Determines if the given destination is compatible with a monitored pipe
+    #
+    # If true, this destination should not be wrapped in a monitored pipe.
+    #
+    # @example
+    #   ProcessExecuter::Destinations.compatible_with_monitored_pipe?(1) #=> true
+    #   ProcessExecuter::Destinations.compatible_with_monitored_pipe?([:child, 6]) #=> false
+    #   ProcessExecuter::Destinations.compatible_with_monitored_pipe?([:close]) #=> false
+    #
+    # @param destination [Object] the destination to check
+    # @return [Boolean, nil] true if the destination is compatible with a monitored pipe
+    # @raise [ArgumentError] if no matching destination class is found
+    # @api public
+    def self.compatible_with_monitored_pipe?(destination)
+      matching_class = matching_destination_class(destination)
+      matching_class&.compatible_with_monitored_pipe?
+    end
+
+    # Determines the destination class that can handle the given destination
+    # @param destination [Object] the destination to check
+    # @return [Class] the destination class that can handle the given destination
+    # @api private
+    def self.matching_destination_class(destination)
+      destination_classes =
+        ProcessExecuter::Destinations.constants
+                                     .map { |const| ProcessExecuter::Destinations.const_get(const) }
+                                     .select { |const| const.is_a?(Class) }
+
+      destination_classes.find { |klass| klass.handles?(destination) }
+    end
+  end
+end

data/lib/process_executer/monitored_pipe.rb

@@ -4,19 +4,16 @@ require 'stringio'
 require 'io/wait'
 
 module ProcessExecuter
-  # Stream data sent through a pipe to one or more writers
+  # Write data sent through a pipe to a destination
   #
   # When a new MonitoredPipe is created, a pipe is created (via IO.pipe) and
   # a thread is created to read data written to the pipe.
   #
-  # Data that is read from that pipe is written one or more writers passed to
-  # `#initialize`.
-  #
-  # If any of the writers raise an exception, the monitoring thread will exit, the
+  # If the destination raises an exception, the monitoring thread will exit, the
   # pipe will be closed, and the exception will be saved in `#exception`.
   #
   # `#close` must be called to ensure that (1) the pipe is closed, (2) all data is
-  # read from the pipe and written to the writers, and (3) the monitoring thread is
+  # read from the pipe and written to the destination, and (3) the monitoring thread is
   # killed.
   #
   # @example Collect pipe data into a string
@@ -52,11 +49,15 @@ module ProcessExecuter
     #   data_collector = StringIO.new
     #   pipe = ProcessExecuter::MonitoredPipe.new(data_collector)
     #
-    # @param writers [Array<#write>] as data is read from the pipe, it is written to these writers
+    # @param redirection_destination [Array<#write>] as data is read from the pipe,
+    #   it is written to this destination
     # @param chunk_size [Integer] the size of the chunks to read from the pipe
     #
-    def initialize(*writers, chunk_size: 100_000)
-      @writers = writers
+    def initialize(redirection_destination, chunk_size: 100_000)
+      @destination = Destinations.factory(redirection_destination)
+
+      assert_destination_is_compatible_with_monitored_pipe
+
       @chunk_size = chunk_size
       @pipe_reader, @pipe_writer = IO.pipe
       @state = :open
@@ -87,12 +88,14 @@ module ProcessExecuter
 
       @state = :closing
       sleep 0.001 until state == :closed
+
+      destination.close
     end
 
     # Return the write end of the pipe so that data can be written to it
     #
     # Data written to this end of the pipe will be read by the monitor thread and
-    # written to the writers passed to `#initialize`.
+    # written to the destination.
     #
     # This is so we can provide a MonitoredPipe to Process.spawn as a FD
     #
@@ -170,24 +173,17 @@ module ProcessExecuter
 
     # @!attribute [r]
     #
-    # An array of writers to write data that is read from the pipe
+    # The redirection destination to write data that is read from the pipe
     #
-    # @example with one writer
+    # @example
     #   require 'stringio'
     #   data_collector = StringIO.new
     #   pipe = ProcessExecuter::MonitoredPipe.new(data_collector)
-    #   pipe.writers #=> [data_collector]
+    #   pipe.destination #=>
     #
-    # @example with an array of writers
-    #   require 'stringio'
-    #   data_collector1 = StringIO.new
-    #   data_collector2 = StringIO.new
-    #   pipe = ProcessExecuter::MonitoredPipe.new(data_collector1, data_collector2)
-    #   pipe.writers #=> [data_collector1, data_collector2]]
-    #
-    # @return [Array<#write>]
+    # @return [Array<ProcessExecuter::Destination::Base>]
     #
-    attr_reader :writers
+    attr_reader :destination
 
     # @!attribute [r]
     #
@@ -246,19 +242,29 @@ module ProcessExecuter
 
     # @!attribute [r]
     #
-    # The exception raised by a writer
+    # The exception raised by a destination
     #
-    # If an exception is raised by a writer, it is stored here. Otherwise, it is `nil`.
+    # If an exception is raised by a destination, it is stored here. Otherwise, it is `nil`.
     #
     # @example
     #   pipe.exception #=> nil
     #
-    # @return [Exception, nil] the exception raised by a writer or `nil` if no exception was raised
+    # @return [Exception, nil] the exception raised by a destination or `nil` if no exception was raised
     #
     attr_reader :exception
 
     private
 
+    # Raise an error if the destination is not compatible with MonitoredPipe
+    # @return [void]
+    # @raise [ArgumentError] if the destination is not compatible with MonitoredPipe
+    # @api private
+    def assert_destination_is_compatible_with_monitored_pipe
+      return if destination.compatible_with_monitored_pipe?
+
+      raise ArgumentError, "Destination #{destination.destination} is not compatible with MonitoredPipe"
+    end
+
     # Read data from the pipe until `#state` is changed to `:closing`
     #
     # The state is changed to `:closed` by calling `#close`.
@@ -275,7 +281,7 @@ module ProcessExecuter
 
     # Read data from the pipe until `#state` is changed to `:closing`
     #
-    # Data read from the pipe is written to the writers given to the constructor.
+    # Data read from the pipe is written to the destination.
     #
     # @return [void]
     # @api private
@@ -286,14 +292,14 @@ module ProcessExecuter
       pipe_reader.wait_readable(0.001)
     end
 
-    # Check if the writer is a file descriptor
-    #
-    # @param writer [#write] the writer to check
-    # @return [Boolean] true if the writer is a file descriptor
-    # @api private
-    def file_descriptor?(writer) = writer.is_a?(Integer) || writer.is_a?(Symbol)
+    # # Check if the writer is a file descriptor
+    # #
+    # # @param writer [#write] the writer to check
+    # # @return [Boolean] true if the writer is a file descriptor
+    # # @api private
+    # def file_descriptor?(writer) = writer.is_a?(Integer) || writer.is_a?(Symbol)
 
-    # Write the data read from the pipe to all destinations
+    # Write the data read from the pipe to the destination
     #
     # If an exception is raised by a writer, set the state to `:closing`
     # so that the pipe can be closed.
@@ -302,35 +308,12 @@ module ProcessExecuter
     # @return [void]
     # @api private
     def write_data(data)
-      writers.each do |w|
-        file_descriptor?(w) ? write_data_to_fd(w, data) : w.write(data)
-      end
+      destination.write(data)
     rescue StandardError => e
       @exception = e
       @state = :closing
     end
 
-    # Write data to the given file_descriptor correctly handling stdout and stderr
-    # @param file_descriptor [Integer, Symbol] the file descriptor to write to (either an integer or :out or :err)
-    # @param data [String] the data to write
-    # @return [void]
-    # @api private
-    def write_data_to_fd(file_descriptor, data)
-      # The case line is not marked as not covered only when using TruffleRuby
-      # :nocov:
-      case file_descriptor
-      # :nocov:
-      when :out, 1
-        $stdout.write data
-      when :err, 2
-        $stderr.write data
-      else
-        io = IO.open(file_descriptor, mode: 'a', autoclose: false)
-        io.write(data)
-        io.close
-      end
-    end
-
     # Read any remaining data from the pipe and close it
     #
     # @return [void]