process_executer 3.2.4 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48ed2573bb17348a6b021a3354b360361ed39d4040bda74f6f2a9f1997d79616
-  data.tar.gz: 8697e82bb6713eccbf0f4f58d0709c435b39fc62a53abece990070a53ab81a5d
+  metadata.gz: f8f23dd316f574cbf2194c9e75b825f03e34c86719d38ba626c22ce26c8d213b
+  data.tar.gz: ccc618656594d909774c872706fc27d8440bf6a26170d678ad3058fef3cf6310
 SHA512:
-  metadata.gz: efbeab2d5a4608f322969a2b5c0f7a948ff25cd717a19d32c7bf0708652c5d923c638bb43bee27cea6ac5687d52c10252d6bf92b7a3f07a21f88f3e3d5b580ca
-  data.tar.gz: '09de2958475e4581f86c27208fbb148afc1860f054c4c7651b7adc32255a89fd41072c327284e5afa93dcc0d6456c1d0e680358419304588cbc8250b88859cc1'
+  metadata.gz: 0e06d8087a256e103b0352bb4f6e4215cdd0d3e7810fb3206337c211aa45d309d7deaa8e760c41815fe81171ac9258a441c6a8f22b5a4c4fa2465c4c28f59314
+  data.tar.gz: 7dc33006e39f0f35399741017cb584f132ef89ea50c0dd8081556a12c2dd48ad19a0bf8adbe915f9be241d54374a3d0856ffe54d4c778d1b2b0bc9e4eeef44b3

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.2.4"
+  ".": "4.0.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to the process_executer gem will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.0](https://github.com/main-branch/process_executer/compare/v3.2.4...v4.0.0) (2025-06-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* Users who call ProcessExecuter::Options::Base#with even if from a derived class will need to update to use #merge instead.
+* Users depending on `Result#stdout` or `Result#stderr` will either have to capture this output manually themselves or change from `spawn_and_wait`/`run` to `run_with_capture`.
+* calls to `ProcessExecuter.spawn_with_timeout_with_options` and `ProcessExecuter.run_with_options` have been removed. Use `ProcessExecuter.spawn_with_timeout` and `ProcessExecuter.run` instead.
+* Users who use ProcessExecuter.spawn_and_wait will need to update their calls to spawn_with_timeout. In addition, the following items will need to be updated if used by the user of this gem:
+    * ProcessExecuter.spawn_and_wait_with_options
+    * ProcessExecuter::SpawnAndWaitOptions
+* In places where users of this gem rescued ::ArgumentError, they will have to change the rescued class to ProcessExecuter::ArgumentError.
+
+### Features
+
+* Add `ProcessExecuter.run_with_capture` ([d9e97fe](https://github.com/main-branch/process_executer/commit/d9e97fe7728a0c7fce9520ad5ba9568782243f70))
+* Add encoding, stdout_encoding, stderr_encoding options to RunWithCaptureOptions ([83eaa93](https://github.com/main-branch/process_executer/commit/83eaa93417e810c1a1b569616c19d8facdc2b2f4))
+* Add ProcessExecuter::ArgumentError and raise it instead of ::ArgumentError ([860fc5a](https://github.com/main-branch/process_executer/commit/860fc5a224f86dd4ff525de32b643fc261e456f6))
+* Ensure that all data written by MonitoredPipe is ASCII-8BIT encoded ([8753006](https://github.com/main-branch/process_executer/commit/87530066280ed91afc208714514df845e4455b6b))
+* Make run_with_capture encode captured stdout and stderr based on encoding options ([75c3d92](https://github.com/main-branch/process_executer/commit/75c3d922fa74a17b61b415fe50acd9763a00524f))
+* Remove #spawn_with_timeout_with_options and #run_with_options methods ([446cb51](https://github.com/main-branch/process_executer/commit/446cb510a634ff5171df6b0fcb2d426cb3f9ed9e))
+* Remove Result#stdout and Result#stderr ([2dcad47](https://github.com/main-branch/process_executer/commit/2dcad47bb921170070f8d4bae1ce07244547db5c))
+* Rename ProcessExecuter::Options::Base#with to #merge ([7e8c28e](https://github.com/main-branch/process_executer/commit/7e8c28e33b99945187d272766134e30b5746ddc8))
+* Rename ProcessExecuter.spawn_and_wait to spawn_with_timeout ([b9d19e7](https://github.com/main-branch/process_executer/commit/b9d19e792234996f78c7cd63b22047bb7474a06d))
+
+
+### Bug Fixes
+
+* Fix new rubocop offense Style/EmptyStringInsideInterpolation ([bb610af](https://github.com/main-branch/process_executer/commit/bb610af96519cccd2fe1be62e61b1531711e5d9b))
+
+
+### Other Changes
+
+* Add a JRuby 10 build to the continuous integration workflow ([7a939ba](https://github.com/main-branch/process_executer/commit/7a939ba5bf7b291555a4259db7040b6cb96f494b))
+* Document the new encoding options on ProcessExecuter.run_with_capture ([c86ce62](https://github.com/main-branch/process_executer/commit/c86ce627b8c081981a92414c35eafb85b99e3201))
+* Ensure that binary data is correctly written to file destinations ([0d2db54](https://github.com/main-branch/process_executer/commit/0d2db54d2b9c4354cb880a17a6b683dc8b5f8424))
+* Fix indentation in README ([1837e7a](https://github.com/main-branch/process_executer/commit/1837e7a5cee56ccc7f3ebdc7f71aab43d1a56ab4))
+* Internally refactor classes for clarity and update documentation ([da1db96](https://github.com/main-branch/process_executer/commit/da1db9697e5c2be371d308d5790e44dcccf8e40b))
+* Remove unneeded :nocov: blocks ([7a1fcf5](https://github.com/main-branch/process_executer/commit/7a1fcf500b89d7fe8e7254ba4fa20e38f0b46d45))
+* Update the README with all the changes for the latest release ([38206a5](https://github.com/main-branch/process_executer/commit/38206a57d26dcca3437611291ab3ccdc1d5a442f))
+
 ## [3.2.4](https://github.com/main-branch/process_executer/compare/v3.2.3...v3.2.4) (2025-04-18)
 
 

data/README.md

@@ -15,176 +15,190 @@ It has additional features like capturing output, handling timeouts, streaming o
 to multiple destinations, and providing detailed result information.
 
 This README documents the HEAD version of process_executer which may contain
-unrelease information. To see the README for the version you are using, consult
+unreleased information. To see the README for the version you are using, consult
 RubyGems.org. Go to the [process_executer page in
 RubyGems.org](https://rubygems.org/gems/process_executer), select your version, and
 then click the "Documentation" link.
 
 ## Requirements
 
-* Ruby 3.1.0 or later
-* Compatible with MRI 3.1+, TruffleRuby 24+, and JRuby 9.4+
-* Works on Mac, Linux, and Windows platforms
-
-## Table of Contents
-
-* [Requirements](#requirements)
-* [Table of Contents](#table-of-contents)
-* [Usage](#usage)
-    * [ProcessExecuter::MonitoredPipe](#processexecutermonitoredpipe)
-    * [ProcessExecuter::Result](#processexecuterresult)
-    * [ProcessExecuter.spawn\_and\_wait](#processexecuterspawn_and_wait)
-    * [ProcessExecuter.run](#processexecuterrun)
-* [Breaking Changes](#breaking-changes)
-    * [2.x](#2x)
-        * [`ProcessExecuter.spawn`](#processexecuterspawn)
-        * [`ProcessExecuter.run`](#processexecuterrun-1)
-        * [`ProcessExecuter::Result`](#processexecuterresult-1)
-        * [Other](#other)
-    * [3.x](#3x)
-        * [`ProcessExecuter.run`](#processexecuterrun-2)
-* [Installation](#installation)
-* [Contributing](#contributing)
-    * [Reporting Issues](#reporting-issues)
-    * [Developing](#developing)
-    * [Commit message guidelines](#commit-message-guidelines)
-    * [Pull request guidelines](#pull-request-guidelines)
-    * [Releasing](#releasing)
-* [License](#license)
+- Ruby 3.1.0 or later
+- Compatible with MRI 3.1+, TruffleRuby 24+, and JRuby 9.4+
+- Works on Mac, Linux, and Windows platforms
+
+## Table of contents
+
+- [Requirements](#requirements)
+- [Table of contents](#table-of-contents)
+- [Usage](#usage)
+  - [Key methods](#key-methods)
+  - [ProcessExecuter::MonitoredPipe](#processexecutermonitoredpipe)
+  - [Encoding](#encoding)
+    - [Encoding summary](#encoding-summary)
+    - [Encoding details](#encoding-details)
+- [Breaking Changes](#breaking-changes)
+  - [2.x](#2x)
+    - [`ProcessExecuter.spawn`](#processexecuterspawn)
+    - [`ProcessExecuter.run`](#processexecuterrun)
+    - [`ProcessExecuter::Result`](#processexecuterresult)
+    - [Other](#other)
+  - [3.x](#3x)
+    - [`ProcessExecuter.run`](#processexecuterrun-1)
+  - [4.x](#4x)
+    - [`ProcessExecuter.spawn_and_wait`](#processexecuterspawn_and_wait)
+    - [`ProcessExecuter::Result`](#processexecuterresult-1)
+    - [`ProcessExecuter.spawn_and_wait_with_options`](#processexecuterspawn_and_wait_with_options)
+    - [`ProcessExecuter.run_with_options`](#processexecuterrun_with_options)
+    - [Other](#other-1)
+- [Installation](#installation)
+- [Contributing](#contributing)
+  - [Reporting Issues](#reporting-issues)
+  - [Developing](#developing)
+  - [Commit message guidelines](#commit-message-guidelines)
+  - [Pull request guidelines](#pull-request-guidelines)
+  - [Releasing](#releasing)
+- [License](#license)
 
 ## Usage
 
 [Full YARD documentation](https://rubydoc.info/gems/process_executer/) for this gem
 is hosted on RubyGems.org. Read below for an overview and several examples.
 
-This gem contains two public classes and two public methods:
+### Key methods
 
-Classes:
+ℹ️ See [the ProcessExecuter module
+  documentation](https://rubydoc.info/gems/process_executer/ProcessExecuter) for
+  more details and examples of using the methods described here.
 
-* `ProcessExecuter::MonitoredPipe`: allows use of any object with a `#write` method
-  or an array of objects as a redirection destination in `Process.spawn`
-* `ProcessExecuter::Result`: an extension of `Process::Status` that includes more
-  information about the subprocess including timeout status, the command that was
-  run, the subprocess options given, and (in some cases) stdout and stderr captured
-  from the subprocess.
+The `ProcessExecuter` module provides extended versions of
+[Process.spawn](https://docs.ruby-lang.org/en/3.4/Process.html#method-c-spawn) that
+block while the command is executing. These methods provide enhanced features such as
+timeout handling, more flexible redirection options, logging, error raising, and
+output capturing.
 
-Methods:
+The interface of these methods is the same as the standard library
+[Process.spawn](https://docs.ruby-lang.org/en/3.4/Process.html#method-c-spawn)
+method but with additional options.
 
-* `ProcessExecuter.spawn_and_wait`: execute a subprocess and wait for it to exit with
-  an optional timeout. Supports the same interface and features as `Process.spawn`.
-* `ProcessExecuter.run`: builds upon `.spawn_and_wait` adding (1) automatically
-  wrapping stdout and stderr destinations (if given) in a `MonitoredPipe` and (2)
-  raises errors for any problem executing the subprocess (can be turned off).
+These methods are:
+
+| Method | Description |
+|--------|-------------|
+| `ProcessExecuter.spawn_with_timeout` | Extends [Process.spawn](https://docs.ruby-lang.org/en/3.4/Process.html#method-c-spawn) to run a command and wait (with timeout) for it to finish |
+| `ProcessExecuter.run` | Extends `spawn_with_timeout` with more flexible redirection and other options. |
+| `ProcessExecuter.run_with_capture` | Extends `run` with capture of stdout and stderr |
+
+See the `ProcessExecuter::Error` class for the error architecture for this module.
 
 ### ProcessExecuter::MonitoredPipe
 
-`ProcessExecuter::MonitoredPipe` objects can be used as a redirection destination for
-`Process.spawn` to stream output from a subprocess to one or more destinations.
-Destinations are given in this class's initializer.
+ℹ️ See [the ProcessExecuter::MonitoredPipe class
+  documentation](https://rubydoc.info/gems/process_executer/ProcessExecuter/MonitoredPipe)
+  for more details and examples of using this class.
 
-The destinations are all the redirection destinations allowed by `Process.spawn` plus
-the following:
+`ProcessExecuter::MonitoredPipe` was created to expand the output redirection options
+for `Process.spawn` and methods derived from it within the `ProcessExecuter` module.
 
-* Any object with a #write method even if it does not have a file descriptor (like
-  instances of StringIO)
-* An array of destinations so that output can be tee'd to several sources
+This class's initializer accepts any compatible redirection destination supported by
+`Process.spawn` (this is the `value` part of the file redirection option described in
+[the File Redirection section of
+`Process.spawn`](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-File+Redirection+-28File+Descriptor-29).
 
-Example of capturing stdout to a StringIO (which is not directly possible with
-`Process.spawn`):
+In addition to the standard redirection destinations, `MonitoredPipe` also
+supports these additional types of destinations:
 
-```ruby
-require 'stringio'
-require 'process_executer'
-
-output_buffer = StringIO.new
-out_pipe = ProcessExecuter::MonitoredPipe.new(output_buffer)
-pid, status = Process.wait2(Process.spawn('echo "Hello World"', out: out_pipe))
-out_pipe.close # Close the pipe so all the data is flushed and resources are not leaked
-output_buffer.string #=> "Hello World\n"
-```
+- **Arbitrary writers**
 
-Any object that implements `#write` can be used as a destination (not just StringIO).
-For instance, you can use it to parse process output as a stream which might be useful
-for long XML or JSON output.
+  You can redirect subprocess output to any Ruby object that implements the
+  `#write` method. This is particularly useful for:
 
-Example of tee'ing stdout to multiple destinations:
+  - capturing command output in in-memory buffers like `StringIO`,
+  - sending command output to custom logging objects that do not have a file descriptor, and
+  - processing with a streaming parser to parse and process command output as the
+    command runs
 
-```ruby
-require 'stringio'
-require 'process_executer'
-
-output_buffer = StringIO.new
-output_file = File.open('process.out', 'w')
-out_pipe = ProcessExecuter::MonitoredPipe.new([:tee, output_buffer, output_file])
-pid, status = Process.wait2(Process.spawn('echo "Hello World"', out: out_pipe))
-out_pipe.close
-output_file.close
-output_buffer.string #=> "Hello World\n"
-File.read('process.out') #=> "Hello World\n"
-```
+- **Multiple destinations**
 
-### ProcessExecuter::Result
+  MonitoredPipe supports duplicating (or "teeing") output to multiple
+  destinations simultaneously. This is achieved by providing an array in the
+  format `[:tee, destination1, destination2, ...]`, where each `destination` can
+  be any value that `MonitoredPipe` itself supports (including another tee or
+  MonitoredPipe).
 
-An instance of this class is returned from both `.spawn_and_wait` and `.run`.
+### Encoding
 
-This class is an extension of
-[Process::Status](https://docs.ruby-lang.org/en/3.3/Process/Status.html) so it
-supports the same interface with the following additions:
+#### Encoding summary
 
-* `#command`: the command given to `.spawn_and_wait` or `.run`
-* `#options`: the options given to `.spawn_and_wait` or `.run` (possibly with some
-  changes)
-* `#timed_out?`: true if the process was killed after running for `:timeout_after`
-  seconds
-* `#elapsed_time`: the number of seconds the process was running
-* `#stdout`: the captured stdout from the subprocess (if the stdout destination was
-  wrapped by a `MonitoredPipe`)
-* `#stderr`: the captured stderr from the subprocess (if the stderr destination was
-  wrapped by a `MonitoredPipe`)
+The gem's core (`MonitoredPipe`) passes through raw bytes from the subprocess without
+attempting to interpret or transcode them. `ProcessExecuter.run_with_capture` allows
+text encodings to be specified for the captured stdout and stderr (defaulting to
+`UTF-8`). For these outputs, the raw bytes are interpreted as being in that specified
+encoding. The original byte sequence is preserved and the resulting captured string
+is tagged with the target encoding. No transcoding between different text encodings
+(e.g., `Latin-1` to `UTF-8`) is performed.
 
-### ProcessExecuter.spawn_and_wait
+#### Encoding details
 
-`ProcessExecuter.spawn_and_wait` has the same interface and features as
-[Process.spawn](https://docs.ruby-lang.org/en/3.3/Process.html#method-c-spawn)
-with the following differences:
+`ProcessExecuter::MonitoredPipe` is encoding agnostic. Bytes pass through this class
+from the subprocesses output to the destination object as a stream of unaltered
+bytes. No transcoding is applied. Strings written to the destination are tagged for
+the ASCII-8BIT (aka BINARY) encoding.
 
-1. It waits for the subprocess to exit
-2. A timeout can be specified using the `:timeout_after` option
-3. It returns a `ProcessExecuter::Result` instead of a `Process::Status`
+`ProcessExecuter` methods `.spawn_with_timeout`, `.run`, and `.run_with_capture` are
+also encoding agnostic except with one exception: the user can specify the assumed
+encoding for strings returned from `ResultWithCapture#stdout` and
+`ResultWithCapture#stderr`.
 
-If the command does not terminate before the number of seconds specified by
-`:timeout_after`, the process is killed by sending it the SIGKILL signal. The
-returned Result object's `timed_out?` attribute will return `true`. For example:
+As a convenience, the captured output is assumed to be UTF-8 by default:
 
 ```ruby
-result = ProcessExecuter.spawn_and_wait('sleep 10', timeout_after: 0.01)
-result.signaled? #=> true
-result.termsig #=> 9
-result.timed_out? #=> true
+result = ProcessExecuter.run_with_capture('pwd')
+result.stdout #=> "/Users/James/projects/process_executer\n"
+result.stdout.encoding #=> #<Encoding::UTF-8>
 ```
 
-If the destination for stdout and stderr are wrapped by a
-ProcessExecuter::MonitoredPipe, the result will return the stdout and stderr
-subprocess output from its `#stdout` and `#stderr` methods.
+You can changed the assumed encoding for the captured stdout and stderr via options
+passed to `#run_with_capture`:
 
-### ProcessExecuter.run
+```ruby
+# Set the assumed encoding for both stdout and stderr
+result = ProcessExecuter.run_with_capture('pwd', encoding: Encoding::BINARY)
+result.stdout #=> "/Users/James/projects/process_executer\n"
+result.stdout.encoding #=> #<Encoding:BINARY (ASCII-8BIT)>
+
+# You can set the assumed encoding separately for stdout and stderr
+# Encoding may be different for each
+result = ProcessExecuter.run_with_capture('pwd', stdout_encoding: 'BINARY', stderr_encoding: 'UTF-8')
+result.stdout.encoding #=> #<Encoding:BINARY (ASCII-8BIT)>
+result.stderr.encoding #=> #<Encoding:UTF-8>
+```
 
-`ProcessExecuter.run` builds upon `ProcessExecuter.spawn_and_wait` adding the
-following features:
+It is possible that the bytes captured are not valid in the given encoding. The user
+will need to check the `#valid_encoding?` method to know for sure.
 
-* It automatically wraps any given stdout and stderr destination with a
-  MonitoredPipe. The pipe will be closed when the command exits.
-* It raises an error if there is any problem with the subprocess. This behavior can
-  be turned off with the `raise_errors: false` option.
+```ruby
+File.binwrite('output.txt', "\xFF\xFE") # little-endian BOM marker is not valid UTF-8
+result = ProcessExecuter.run_with_capture('cat output.txt')
+result.stdout #=> "\xFF\xFE"
+result.stdout.encoding #=> #<Encoding:UTF-8>
+result.stdout.valid_encoding? #=> false
+```
 
-  ⚠️ `ProcessIOError` and `SpawnError` errors are not suppressed by giving the
-  `raise_errors: false` option.
+Encoding options accept any encoding objects returned by `Encoding.list` or their
+String equivalent given by `#to_s`:
 
 ```ruby
-result = ProcessExecuter.run('echo "Hello World"', out: StringIO.new)
-result.stdout #=> "Hello World\n"
+Encoding::UTF_8.to_s #=> 'UTF-8'
 ```
 
+Changing the assumed encoding DOES NOT cause transcoding. It simply interprets the
+bytes captured as the given encoding.
+
+These encoding options ONLY affect the internally captured stdout and stderr for
+`ProcessExecuter::run_with_capture`. If you give an `out:` or `err:` option, these
+will result in BINARY encoded strings and you will need to handle setting the right
+encoding or transcoding after collecting the output.
+
 ## Breaking Changes
 
 ### 2.x
@@ -193,26 +207,26 @@ This major release focused on changes to the interface to make it more understan
 
 #### `ProcessExecuter.spawn`
 
-* This method was renamed to `ProcessExecuter.spawn_and_wait`
-* The `:timeout` option was renamed to `:timeout_after`
+- This method was renamed to `ProcessExecuter.spawn_with_timeout`
+- The `:timeout` option was renamed to `:timeout_after`
 
 #### `ProcessExecuter.run`
 
-* The `:timeout` option was renamed to `:timeout_after`
+- The `:timeout` option was renamed to `:timeout_after`
 
 #### `ProcessExecuter::Result`
 
-* The `#timeout` method was renamed to `#timed_out`
+- The `#timeout` method was renamed to `#timed_out`
 
 #### Other
 
-* Dropped support for Ruby 3.0
+- Dropped support for Ruby 3.0
 
 ### 3.x
 
 #### `ProcessExecuter.run`
 
-* The `:merge` option was removed
+- The `:merge` option was removed
 
   This was removed because `Process.spawn` already provides this functionality but in
   a different way. To merge, you will need to define a redirection where the source
@@ -224,7 +238,7 @@ This major release focused on changes to the interface to make it more understan
 
   will merge stdout and stderr from the subprocess into the file output.txt.
 
-* Stdout and stderr redirections are no longer default to a new instance of StringIO
+- Stdout and stderr redirections no longer default to new instances of `StringIO`
 
   Calls to `ProcessExecuter.run` that do not define a redirection for stdout or
   stderr will have to add explicit redirection(s) in order to capture the output.
@@ -233,6 +247,35 @@ This major release focused on changes to the interface to make it more understan
   an explicit redirection is not given for stdout and stderr, this output will be
   passed through to the parent process's stdout and stderr.
 
+### 4.x
+
+#### `ProcessExecuter.spawn_and_wait`
+
+`ProcessExecuter.spawn_and_wait` has been renamed to `ProcessExecuter.spawn_with_timeout`.
+
+#### `ProcessExecuter::Result`
+
+`Result#stdout` and `Result#stderr` were removed. Users depending on these methods
+will either have to capture this output themselves or change from using
+`.spawn_and_wait`/`.run` to `.run_with_capture` which returns a `ResultWithCapture`
+object.
+
+#### `ProcessExecuter.spawn_and_wait_with_options`
+
+`ProcessExecuter.spawn_and_wait_with_options` has been removed. Instead call
+`ProcessExecuter.spawn_with_timeout` which is overloaded to take the same method
+arguments.
+
+#### `ProcessExecuter.run_with_options`
+
+`ProcessExecuter.run_with_options` has been removed. Instead call
+`ProcessExecuter.run` which is overloaded to take the same method arguments.
+
+#### Other
+
+In places where users of this gem rescued `::ArgumentError`, they will have to change
+the rescued class to `ProcessExecuter::ArgumentError`.
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -271,11 +314,11 @@ effectively.
 
 To ensure compliance, this project includes:
 
-* A git commit-msg hook that validates your commit messages before they are accepted.
+- A git commit-msg hook that validates your commit messages before they are accepted.
 
-  To activate the hook, you must have node installed and run `npm install`.
+  To activate the hook, you must have Node.js installed and run `npm install`.
 
-* A GitHub Actions workflow that will enforce the Conventional Commit standard as
+- A GitHub Actions workflow that will enforce the Conventional Commit standard as
   part of the continuous integration pipeline.
 
   Any commit message that does not conform to the Conventional Commits standard will

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