process_executer 4.0.3 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80aa4031ab96fafeb8d1c1126fe4646145b59208221aec2188f21904cede7b7d
-  data.tar.gz: 1007e6fb46320b51bfe9d216a0ef9646d357bcff20c60313c32885b31db8b7f2
+  metadata.gz: 63acfcf3541790f98d140feac5a9badc901f8b4e475b3c97d125f6b549556bfc
+  data.tar.gz: 7c42a5cfa8b66fea530be0821443a974c1fabc1002fc2b3f2f35e533812c9c6e
 SHA512:
-  metadata.gz: c2cb8d71448b21f256d03011b20492eb8f5b766d668c564a3a836e01fe4aa68bdbf2d5135f8461d576cccb54ca3e189f59999f93aa51d33dcd65bb00b3be15f9
-  data.tar.gz: d6cb1188669658fed64b92f5bdce4262bb87b1e38f6fff710cfe9e15773d753b70e6d4aff9b73def4ff1e823428ddf7dd8356518c33deccfb88de3658f706787
+  metadata.gz: b8d54aa2b9c5e1c153a4c92dbaeec6d96c3b80f31f6517ad2026519d070eff6d6c5b6fdc447cfbff481a6c15599c06ace734068f784e1f1ca8ba78831e84e0d7
+  data.tar.gz: fef70d1e6342139152e498dd72572f591f5f330f8617e7ad0603898638c08db8e2ec09aeb302e486949432d80a7635611654959869314946df13c1bf87ed4dd0

data/.editorconfig

@@ -0,0 +1,10 @@
+root = true
+
+[*]
+end_of_line = lf
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "4.0.3"
+  ".": "4.1.0"
 }

data/.rubocop.yml

@@ -5,3 +5,16 @@ AllCops:
   # Pin this project to Ruby 3.1 in case the shared config above is upgraded to 3.2
   # or later.
   TargetRubyVersion: 3.1
+
+# The default `native` style expects CRLF on Windows, but this project's files
+# are LF everywhere. Pin the style so RuboCop gives the same result on Windows
+# as it does on Linux and macOS.
+Layout/EndOfLine:
+  EnforcedStyle: lf
+
+# MonitoredPipe grew past the default limit when the close deadline handling
+# was added for issue #164. Its pipe lifecycle logic (open, monitor, drain,
+# close) is cohesive and would not be clearer split across classes.
+Metrics/ClassLength:
+  Exclude:
+    - "lib/process_executer/monitored_pipe.rb"

data/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["editorconfig.editorconfig"]
+}

data/CHANGELOG.md

@@ -5,6 +5,60 @@ 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.1.0](https://github.com/main-branch/process_executer/compare/v4.0.4...v4.1.0) (2026-08-30)
+
+
+### Bug Fixes
+
+* Make timeout_after bound execution even when descendants hold stdout/stderr open ([a1298d3](https://github.com/main-branch/process_executer/commit/a1298d3f98fd8e57f58f50a0566dd3be78079189))
+* **monitored_pipe:** Close acquired resources when #initialize fails partway ([8f10a86](https://github.com/main-branch/process_executer/commit/8f10a86b42c4d72f0f34004071cfeb91116d6bd4)), closes [#178](https://github.com/main-branch/process_executer/issues/178)
+* **monitored_pipe:** Do not hold the mutex while writing to the pipe ([91d7fe8](https://github.com/main-branch/process_executer/commit/91d7fe88b9950d24f8c28ccbea400be0063ec99a)), closes [#165](https://github.com/main-branch/process_executer/issues/165)
+* **monitored_pipe:** Handle a destination raising a non-StandardError ([a7de23b](https://github.com/main-branch/process_executer/commit/a7de23b5699ef4d32518e988ac76dd6a957277e3)), closes [#170](https://github.com/main-branch/process_executer/issues/170)
+* Replace the monitor thread's 1ms poll with an event-driven wakeup pipe ([44068a3](https://github.com/main-branch/process_executer/commit/44068a35f4f87de9b7b46ce1deffda636f7c1138))
+* Return a timed out result when the timeout races Process.wait2 reaping the child ([84a6a11](https://github.com/main-branch/process_executer/commit/84a6a11df7d736f26d98700e90a76f5d65e2d35c)), closes [#171](https://github.com/main-branch/process_executer/issues/171)
+* **run_with_capture:** Capture combined [:out, :err] redirection into stdout ([17199b8](https://github.com/main-branch/process_executer/commit/17199b8ea332278680c46accce072763f0d67a4a)), closes [#167](https://github.com/main-branch/process_executer/issues/167)
+* **run:** Close created pipes and keep the original error when pipe creation fails ([909eaa1](https://github.com/main-branch/process_executer/commit/909eaa177fa53ee4cd4e773595a8658ea94ca6a4)), closes [#166](https://github.com/main-branch/process_executer/issues/166)
+* **run:** Stop mutating caller options and closing caller-owned pipes ([96d922b](https://github.com/main-branch/process_executer/commit/96d922b4bff5586189b30d9a1f83b0d47159710f)), closes [#169](https://github.com/main-branch/process_executer/issues/169)
+* Validate options merged via Options::Base#merge! ([#173](https://github.com/main-branch/process_executer/issues/173)) ([da0a956](https://github.com/main-branch/process_executer/commit/da0a956bcb085378b1315dafb87351174500c966))
+
+
+### Other Changes
+
+* Add failing tests for merge! bypassing option validation ([#173](https://github.com/main-branch/process_executer/issues/173)) ([325f16e](https://github.com/main-branch/process_executer/commit/325f16e589821571f3250e86a82f51f0e6b70f9a))
+* Add failing tests for the monitor thread 1ms polling loop ([#172](https://github.com/main-branch/process_executer/issues/172)) ([e202909](https://github.com/main-branch/process_executer/commit/e202909f99074a8ceb331f13290c224c35904e7a))
+* Add failing tests for the timeout vs Process.wait2 reap race ([#171](https://github.com/main-branch/process_executer/issues/171)) ([647739a](https://github.com/main-branch/process_executer/commit/647739ad7233059aafb54dad70eef14998892c5d))
+* Add failing tests for timeout_after not bounding execution ([#164](https://github.com/main-branch/process_executer/issues/164)) ([8e5115c](https://github.com/main-branch/process_executer/commit/8e5115c9236347e77ba6e6d0631f5f1bfe826b26))
+* **coverage:** Only enforce code coverage on MRI builds not on Windows ([160815e](https://github.com/main-branch/process_executer/commit/160815ecb091d1f155406f9a1b37f73e13690627))
+* Enforce LF line endings on all platforms ([e94bfea](https://github.com/main-branch/process_executer/commit/e94bfeaf4bd93506090277b4020859cd23dfc625))
+* Explain stdin redirection via the in: option ([f7bded7](https://github.com/main-branch/process_executer/commit/f7bded743a204a99c7f6e272b0330d4ba1e4a037)), closes [#159](https://github.com/main-branch/process_executer/issues/159)
+* **monitored_pipe:** Accept the documented IOError and confine failures ([002274d](https://github.com/main-branch/process_executer/commit/002274d421afc84c7c441c6f56dbbc32506e1de2)), closes [#182](https://github.com/main-branch/process_executer/issues/182)
+* **monitored_pipe:** Add a failing test for the #write deadlock ([9826558](https://github.com/main-branch/process_executer/commit/9826558035b03fe7becdc729053519141ba8d00d))
+* **monitored_pipe:** Add failing tests for a destination raising a non-StandardError ([0177329](https://github.com/main-branch/process_executer/commit/0177329fb47f3c185d9ea768f9f80028c54fb7ab))
+* **monitored_pipe:** Add failing tests for resource leaks when #initialize fails ([b2e3151](https://github.com/main-branch/process_executer/commit/b2e31519ea7a38f774b90f6e9e1f17fa0b31baa3)), closes [#178](https://github.com/main-branch/process_executer/issues/178)
+* **monitored_pipe:** Make the writer-exception race deterministic ([c72f1e4](https://github.com/main-branch/process_executer/commit/c72f1e400ef3d78e4b092ecde0d0704cf79ebc36)), closes [#182](https://github.com/main-branch/process_executer/issues/182)
+* **monitored_pipe:** Stub the monitor loop on the class, not the live instance ([799177f](https://github.com/main-branch/process_executer/commit/799177f6046d661013ce6b68b19c6b220294d00f))
+* **process-spawn:** Check exit status and blocking, and add a subspawn backend ([99021d2](https://github.com/main-branch/process_executer/commit/99021d2144a21210f793b7ae94d36875eef504e6))
+* **process-spawn:** Run the spawn tests against the subspawn backend ([573086f](https://github.com/main-branch/process_executer/commit/573086f194e790f25d916de32bb5e94437a5ae86))
+* **rake:** Skip RuboCop in the default task on TruffleRuby ([3d2a118](https://github.com/main-branch/process_executer/commit/3d2a1186d65e76f170f5428d611822d95d8fdc2d))
+* Release the hardening changes as v4.1.0 instead of v4.0.5 ([70b6327](https://github.com/main-branch/process_executer/commit/70b63278f334bd8b714c2fc28ded1520921add09))
+* **run_with_capture:** Add failing tests for combined [:out, :err] redirection ([61e97cb](https://github.com/main-branch/process_executer/commit/61e97cb09c816cbe30d81dc33f268accf76ab396))
+* **run:** Add failing tests for options mutation and caller-owned pipe closing ([cf32615](https://github.com/main-branch/process_executer/commit/cf326156381fe81562597906d43134a08ebbef17))
+* **run:** Add failing tests for pipe creation failure in Run#call ([21521d9](https://github.com/main-branch/process_executer/commit/21521d9a9b5141d9bb6d22fb5fd3e7de0e497ca2))
+* **run:** Update the JRuby expectation for an invalid chdir path ([2712f0b](https://github.com/main-branch/process_executer/commit/2712f0bdf060fa1831edb428183283dec5f2727a))
+* Use RbConfig.ruby to locate the Ruby interpreter ([82e65e2](https://github.com/main-branch/process_executer/commit/82e65e202a4f884a3283b4af00fcd2b5eda3a394))
+
+## [4.0.4](https://github.com/main-branch/process_executer/compare/v4.0.3...v4.0.4) (2026-04-24)
+
+
+### Bug Fixes
+
+* **rubocop:** Fix offenses introduced by new rubocop cops ([b21ca99](https://github.com/main-branch/process_executer/commit/b21ca991641784146b0c92c1dd3205fc9d2c0f4f))
+
+
+### Other Changes
+
+* **dependencies:** Update dependencies for all GitHub Actions workflows ([3524dbf](https://github.com/main-branch/process_executer/commit/3524dbf8b5945c233be96381f4555407b537f236))
+
 ## [4.0.3](https://github.com/main-branch/process_executer/compare/v4.0.2...v4.0.3) (2026-01-04)
 
 

data/README.md

@@ -26,6 +26,7 @@ then click the "Documentation" link.
 - [Usage](#usage)
   - [Key methods](#key-methods)
   - [ProcessExecuter::MonitoredPipe](#processexecutermonitoredpipe)
+  - [Redirecting stdin](#redirecting-stdin)
   - [Encoding](#encoding)
     - [Encoding summary](#encoding-summary)
     - [Encoding details](#encoding-details)
@@ -119,6 +120,25 @@ supports these additional types of destinations:
   be any value that `MonitoredPipe` itself supports (including another tee or
   MonitoredPipe).
 
+### Redirecting stdin
+
+The `in:` option is passed directly to `Process.spawn` and is not wrapped in a
+`MonitoredPipe`. It accepts any stdin redirection value that `Process.spawn`
+supports, such as a filename (`in: 'input.txt'`) or an IO object with a file
+descriptor. Unlike `out:` and `err:`, redirecting stdin from a `StringIO` is not
+supported and will raise `ProcessExecuter::SpawnError`. To feed in-memory data
+to a command's stdin, write it to a `Tempfile` and pass that:
+
+```ruby
+require 'tempfile'
+
+Tempfile.create do |file|
+  file.write("HEAD\n")
+  file.rewind
+  result = ProcessExecuter.run('git cat-file --batch-check', in: file)
+end
+```
+
 ### Encoding
 
 #### Encoding summary

data/Rakefile

@@ -6,6 +6,9 @@ desc 'Run the same tasks that the CI build will run'
 
 if RUBY_PLATFORM == 'java'
   task default: %w[spec rubocop bundle:audit build]
+elsif RUBY_ENGINE == 'truffleruby'
+  # RuboCop raises internal errors when run on TruffleRuby, so skip it there
+  task default: %w[spec yard bundle:audit build]
 else
   task default: %w[spec rubocop yard bundle:audit build]
 end

data/lib/process_executer/commands/run.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'English'
+
 require_relative '../errors'
 require_relative 'spawn_with_timeout'
 
@@ -19,9 +21,29 @@ module ProcessExecuter
     # destination. This means that you can redirect to a StringIO which is not possible
     # with `Process.spawn`.
     #
+    # The wrapper pipes are kept in an internal hash that is combined with the
+    # user's options only when `Process.spawn` is called. The options object the
+    # caller gave is never modified, so it can be reused for another run and
+    # `result.options` returns the destinations as the user configured them.
+    #
     # @api private
     #
     class Run < SpawnWithTimeout
+      # Create a new Run instance
+      #
+      # @example
+      #   options = ProcessExecuter::Options::RunOptions.new(raise_errors: true)
+      #   result = ProcessExecuter::Commands::Run.new('echo hello', options).call
+      #   result.success? # => true
+      #
+      # @param command [Array<String>] The command to run in the subprocess
+      # @param options [ProcessExecuter::Options::RunOptions] The options to use when running the command
+      #
+      def initialize(command, options)
+        super
+        @redirection_overrides = {}
+      end
+
       # Run a command and return the result
       #
       # Wrap the stdout and stderr redirection destinations in pipes and then execute
@@ -44,35 +66,130 @@ module ProcessExecuter
       # @raise [ProcessExecuter::TimeoutError] If the command timed out
       #
       # @raise [ProcessExecuter::ProcessIOError] If there was an exception while
-      #   collecting subprocess output
+      #   collecting subprocess output, or the output was truncated because it
+      #   could not be fully collected before the close timeout
       #
       # @return [ProcessExecuter::Result] The result of the completed subprocess
       #
       def call
-        opened_pipes = wrap_stdout_stderr
+        opened_pipes = {}
+        wrap_stdout_stderr(opened_pipes)
         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) }
+        close_pipes_and_check_errors(opened_pipes, $ERROR_INFO)
       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
+      # Redirection options to apply on top of the user's options at spawn time
+      #
+      # Holds the {MonitoredPipe} wrappers created by {#wrap_stdout_stderr} (and
+      # the capture redirections added by subclasses) keyed by the redirection
+      # option key. Keeping them here instead of writing them into {#options}
+      # leaves the caller's options object unmodified.
+      #
+      # @return [Hash<Object, Object>]
+      #
+      attr_reader :redirection_overrides
 
+      # The options to pass to Process.spawn
+      #
+      # The user's spawn options with the redirection destinations replaced by
+      # their internal {MonitoredPipe} wrappers.
+      #
+      # @return [Hash]
+      #
+      def spawn_options = super.merge(redirection_overrides)
+
+      # Wrap the stdout and stderr redirection options with a MonitoredPipe
+      #
+      # The wrapper pipes are recorded in {#redirection_overrides} instead of
+      # being written into {#options} so the caller's options object is not
+      # modified.
+      #
+      # Each pipe is added to `opened_pipes` as soon as it is created so that,
+      # if creating a later pipe raises, the caller's ensure block can close the
+      # pipes created so far.
+      #
+      # @param opened_pipes [Hash<Object, ProcessExecuter::MonitoredPipe>] an
+      #   accumulator for the opened pipes (the Object is the option key)
+      #
+      # @return [Hash<Object, ProcessExecuter::MonitoredPipe>] the given `opened_pipes`
+      #
+      def wrap_stdout_stderr(opened_pipes)
+        effective_redirections.each do |key, value|
           next unless should_wrap?(key, value)
 
           wrapped_destination = ProcessExecuter::MonitoredPipe.new(value)
           opened_pipes[key] = wrapped_destination
-          options.merge!({ key => wrapped_destination })
+          redirection_overrides[key] = wrapped_destination
         end
+        opened_pipes
+      end
+
+      # The options as given by the user with {#redirection_overrides} applied
+      #
+      # @return [Hash<Object, Object>]
+      #
+      def effective_redirections = options.to_h.merge(redirection_overrides)
+
+      # Close the given pipes and raise any pipe error unless already unwinding
+      #
+      # When `in_flight_error` is set, `#call` is unwinding from an exception
+      # and that exception (not a pipe destination error or a pipe cleanup
+      # error) must be the one the caller sees, so nothing is raised here.
+      #
+      # @param opened_pipes [Hash<Object, ProcessExecuter::MonitoredPipe>] the pipes to close
+      #
+      # @param in_flight_error [Exception, nil] the exception `#call` is unwinding from, if any
+      #
+      # @raise [ProcessExecuter::ProcessIOError] if a pipe recorded a destination
+      #   exception or gave up draining before reaching EOF (truncated output)
+      #
+      # @raise [StandardError] the first error raised while closing the pipes
+      #
+      # @return [void]
+      #
+      def close_pipes_and_check_errors(opened_pipes, in_flight_error)
+        close_error = close_pipes(opened_pipes)
+        return if in_flight_error
+
+        opened_pipes.each do |option_key, pipe|
+          raise_pipe_error(option_key, pipe)
+          raise_truncation_error(option_key, pipe)
+        end
+        raise close_error if close_error
+      end
+
+      # Close the given pipes, continuing if closing one of them raises
+      #
+      # Closing continues past a failure so that one pipe's error does not leak
+      # the monitoring threads and file descriptors of the pipes after it.
+      #
+      # All pipes share a single close deadline so that this method -- called
+      # from `#call`'s ensure block -- returns in bounded time even when a
+      # process outside this object's control (such as an orphaned descendant
+      # of a timed out command) still holds a pipe's write fd open. A pipe
+      # whose drain is cut short by the deadline records it via
+      # {MonitoredPipe#truncated?}.
+      #
+      # @param opened_pipes [Hash<Object, ProcessExecuter::MonitoredPipe>] the pipes to close
+      #
+      # @return [StandardError, nil] the first error raised while closing, or nil if none was raised
+      #
+      def close_pipes(opened_pipes)
+        first_close_error = nil
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + MonitoredPipe::DEFAULT_CLOSE_TIMEOUT
+        opened_pipes.each_value do |pipe|
+          remaining_time = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          pipe.close(timeout: [remaining_time, 0].max)
+        rescue StandardError => e
+          first_close_error ||= e
+        end
+        first_close_error
       end
 
       # Should the redirection option be wrapped by a MonitoredPipe
@@ -119,6 +236,31 @@ module ProcessExecuter
         error = ProcessExecuter::ProcessIOError.new("Pipe Exception for #{command}: #{option_key.inspect}")
         raise(error, cause: pipe.exception)
       end
+
+      # Raises a ProcessIOError if the given pipe's output was truncated
+      #
+      # Truncation means the pipe gave up draining before reaching EOF
+      # ({MonitoredPipe#truncated?}): output the subprocess (or a descendant
+      # holding the inherited write fd) produced was discarded instead of
+      # being written to the destination. Raising makes that data loss loud
+      # rather than letting the command appear to succeed with silently
+      # incomplete output.
+      #
+      # @param option_key [Object] The redirection option key
+      #
+      # @param pipe [ProcessExecuter::MonitoredPipe] The pipe whose output was truncated
+      #
+      # @raise [ProcessExecuter::ProcessIOError] If the pipe's output was truncated
+      #
+      # @return [void]
+      #
+      def raise_truncation_error(option_key, pipe)
+        return unless pipe.truncated?
+
+        raise ProcessExecuter::ProcessIOError,
+              "Output truncated for #{command}: #{option_key.inspect} " \
+              'could not be fully collected before the close timeout'
+      end
     end
   end
 end

data/lib/process_executer/commands/run_with_capture.rb

@@ -50,7 +50,7 @@ module ProcessExecuter
         @stderr_buffer = StringIO.new
         stderr_buffer.set_encoding(options.effective_stderr_encoding)
 
-        update_capture_options
+        add_capture_redirections
 
         begin
           super
@@ -89,15 +89,52 @@ module ProcessExecuter
         )
       end
 
-      # Updates {options} to include the stdout and stderr capture options
+      # Add the stdout and stderr capture redirections to {#redirection_overrides}
+      #
+      # The capture redirections are not written into {options} so the caller's
+      # options object is not modified.
+      #
+      # When the user gives a combined redirection whose key covers both stdout
+      # and stderr (e.g. `[:out, :err] => destination`), a single capture
+      # redirection is built for that key so both streams are interleaved into
+      # {#stdout_buffer} and {#stderr_buffer} is left empty, mirroring the
+      # `merge_output: true` contract.
+      #
+      # @return [Void]
+      #
+      def add_capture_redirections
+        if options.combined_stdout_and_stderr_redirection?
+          add_combined_capture_redirection
+        else
+          add_stdout_and_stderr_capture_redirections
+        end
+      end
+
+      # Add a single capture redirection for a combined stdout/stderr key
+      #
+      # Both streams are interleaved into {#stdout_buffer}; {#stderr_buffer} is
+      # left empty.
+      #
+      # @return [Void]
+      #
+      def add_combined_capture_redirection
+        redirection_overrides.merge!(
+          capture_option(:out, stdout_redirection_source, stdout_redirection_destination, stdout_buffer)
+        )
+      end
+
+      # Add separate capture redirections for stdout and stderr
+      #
+      # If `merge_output: true` was given, stderr is redirected into stdout so
+      # both streams are interleaved into {#stdout_buffer}.
       #
       # @return [Void]
       #
-      def update_capture_options
+      def add_stdout_and_stderr_capture_redirections
         out = stdout_buffer
         err = options.merge_output ? [:child, 1] : stderr_buffer
 
-        options.merge!(
+        redirection_overrides.merge!(
           capture_option(:out, stdout_redirection_source, stdout_redirection_destination, out),
           capture_option(:err, stderr_redirection_source, stderr_redirection_destination, err)
         )