process_executer 4.1.0 → 4.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63acfcf3541790f98d140feac5a9badc901f8b4e475b3c97d125f6b549556bfc
-  data.tar.gz: 7c42a5cfa8b66fea530be0821443a974c1fabc1002fc2b3f2f35e533812c9c6e
+  metadata.gz: a6dbea0ce77694bd73783f7191fc9b32957fefda87f9db6108d97ebf26bb1a9f
+  data.tar.gz: e710378f301c56c649063d6bfef0525f0c0c8dcf6adf6329e12184ec24d02894
 SHA512:
-  metadata.gz: b8d54aa2b9c5e1c153a4c92dbaeec6d96c3b80f31f6517ad2026519d070eff6d6c5b6fdc447cfbff481a6c15599c06ace734068f784e1f1ca8ba78831e84e0d7
-  data.tar.gz: fef70d1e6342139152e498dd72572f591f5f330f8617e7ad0603898638c08db8e2ec09aeb302e486949432d80a7635611654959869314946df13c1bf87ed4dd0
+  metadata.gz: 756a9aacc5d173fa2cedd68f178c9e321e141d3ef75f61ddcfe7e3ebe67f236a0603192f24c49aaedbc0dcf209d61dd16b593477f67d974fa1f2e875ec17dd7d
+  data.tar.gz: a9ce354984f37839c54abfb453eef726d6467467dc529aaa2108643c2e153005022b097b9a1ecfea368391ff9ebbf8ba20b32b9cd73db11c5076394824d81528

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.1](https://github.com/main-branch/process_executer/compare/v4.1.0...v4.1.1) (2026-08-31)
+
+
+### Other Changes
+
+* Characterize validation ordering when unknown and invalid options are given together ([#192](https://github.com/main-branch/process_executer/issues/192)) ([15d6e06](https://github.com/main-branch/process_executer/commit/15d6e063170484f309efd30867238b867484288b))
+* Collapse encoding validators and clarify capture-redirection assembly ([#194](https://github.com/main-branch/process_executer/issues/194)) ([bab8610](https://github.com/main-branch/process_executer/commit/bab86101ac4cdbd3747e72d0d7f841623a6e9b20))
+* Contribute subclass redirections via an internal_redirections hook ([#190](https://github.com/main-branch/process_executer/issues/190)) ([8ecbda5](https://github.com/main-branch/process_executer/commit/8ecbda54874de933ab07a64d91e0a07e17f7ece0))
+* Derive the process-group isolation decision from a single source ([#191](https://github.com/main-branch/process_executer/issues/191)) ([5d8ac7d](https://github.com/main-branch/process_executer/commit/5d8ac7dc38a369a7fe6d6cf3d05bd1eec799f3dc))
+* Describe every source of MonitoredPipe#exception ([#193](https://github.com/main-branch/process_executer/issues/193)) ([333b7bd](https://github.com/main-branch/process_executer/commit/333b7bd4c552c246d7d7505b5aa3e1a123ac5f9b))
+* Extract shared validate! from Options::Base#initialize and #merge! ([#192](https://github.com/main-branch/process_executer/issues/192)) ([422956a](https://github.com/main-branch/process_executer/commit/422956acaab46e29ecc1373d017d719ea6eb497f))
+* Remove the release-as 4.1.0 override from the release-please config ([65de5b8](https://github.com/main-branch/process_executer/commit/65de5b8b4a7f926c4e71b094ead5ff9abc6ff102))
+* Track opened pipes as per-call instance state instead of an out-parameter ([#190](https://github.com/main-branch/process_executer/issues/190)) ([f279f1e](https://github.com/main-branch/process_executer/commit/f279f1e0672b91b966ee73cbadf00749522e488d))
+
 ## [4.1.0](https://github.com/main-branch/process_executer/compare/v4.0.4...v4.1.0) (2026-08-30)
 
 

data/lib/process_executer/commands/run.rb

@@ -21,29 +21,16 @@ 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.
+    # The wrapper pipes are kept in internal per-call state that is combined
+    # with the user's options only when `Process.spawn` is called. Subclasses
+    # contribute additional redirections by overriding `#internal_redirections`.
+    # 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
@@ -72,29 +59,60 @@ module ProcessExecuter
       # @return [ProcessExecuter::Result] The result of the completed subprocess
       #
       def call
-        opened_pipes = {}
-        wrap_stdout_stderr(opened_pipes)
+        @opened_pipes = {}
+        @redirection_overrides = internal_redirections
+        wrap_stdout_stderr
         super.tap do
           log_result
           raise_errors if options.raise_errors
         end
       ensure
-        close_pipes_and_check_errors(opened_pipes, $ERROR_INFO)
+        close_pipes_and_check_errors($ERROR_INFO)
       end
 
       private
 
       # 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}
+      # Reset at the start of each {#call}: seeded with
+      # {#internal_redirections} and then updated by {#wrap_stdout_stderr},
+      # which replaces each eligible destination with its {MonitoredPipe}
+      # wrapper. Keeping these here instead of writing them into {#options}
       # leaves the caller's options object unmodified.
       #
+      # Unlike {#opened_pipes}, this hash may hold values that are not
+      # {MonitoredPipe}s (for example, the `[:child, 1]` redirection a subclass
+      # adds for merged output).
+      #
       # @return [Hash<Object, Object>]
       #
       attr_reader :redirection_overrides
 
+      # Redirections this class adds on top of the user's options
+      #
+      # Called once at the start of each {#call} to seed
+      # {#redirection_overrides}, before {#wrap_stdout_stderr} runs. Returns an
+      # empty hash; subclasses override this method to contribute their own
+      # redirections (such as {RunWithCapture}'s capture redirections) instead
+      # of mutating this object's state.
+      #
+      # @return [Hash<Object, Object>]
+      #
+      def internal_redirections = {}
+
+      # The wrapper pipes created by {#wrap_stdout_stderr}
+      #
+      # Keyed by the redirection option key. Reset at the start of each {#call}. By construction this hash contains
+      # exactly the pipes this object created during the current call -- never
+      # a destination supplied by the caller -- so `#call`'s ensure block can
+      # close everything in it without ever closing a caller-owned pipe (a
+      # caller's own {MonitoredPipe} destination is wrapped like any other
+      # destination, and only the wrapper is recorded here).
+      #
+      # @return [Hash<Object, ProcessExecuter::MonitoredPipe>]
+      #
+      attr_reader :opened_pipes
+
       # The options to pass to Process.spawn
       #
       # The user's spawn options with the redirection destinations replaced by
@@ -106,20 +124,19 @@ module ProcessExecuter
 
       # 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.
+      # Each wrapper pipe is recorded in two collections with different roles:
+      # {#opened_pipes}, the pipes this object owns and must close, and
+      # {#redirection_overrides}, the destinations to hand `Process.spawn`.
+      # Neither is written into {#options}, so the caller's options object is
+      # not modified.
       #
-      # @param opened_pipes [Hash<Object, ProcessExecuter::MonitoredPipe>] an
-      #   accumulator for the opened pipes (the Object is the option key)
+      # Each pipe is recorded as soon as it is created so that, if creating a
+      # later pipe raises, `#call`'s ensure block can close the pipes created
+      # so far.
       #
-      # @return [Hash<Object, ProcessExecuter::MonitoredPipe>] the given `opened_pipes`
+      # @return [void]
       #
-      def wrap_stdout_stderr(opened_pipes)
+      def wrap_stdout_stderr
         effective_redirections.each do |key, value|
           next unless should_wrap?(key, value)
 
@@ -127,7 +144,6 @@ module ProcessExecuter
           opened_pipes[key] = wrapped_destination
           redirection_overrides[key] = wrapped_destination
         end
-        opened_pipes
       end
 
       # The options as given by the user with {#redirection_overrides} applied
@@ -136,14 +152,12 @@ module ProcessExecuter
       #
       def effective_redirections = options.to_h.merge(redirection_overrides)
 
-      # Close the given pipes and raise any pipe error unless already unwinding
+      # Close the opened 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
@@ -153,8 +167,8 @@ module ProcessExecuter
       #
       # @return [void]
       #
-      def close_pipes_and_check_errors(opened_pipes, in_flight_error)
-        close_error = close_pipes(opened_pipes)
+      def close_pipes_and_check_errors(in_flight_error)
+        close_error = close_pipes
         return if in_flight_error
 
         opened_pipes.each do |option_key, pipe|
@@ -164,7 +178,7 @@ module ProcessExecuter
         raise close_error if close_error
       end
 
-      # Close the given pipes, continuing if closing one of them raises
+      # Close the opened 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.
@@ -176,11 +190,9 @@ module ProcessExecuter
       # 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)
+      def close_pipes
         first_close_error = nil
         deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + MonitoredPipe::DEFAULT_CLOSE_TIMEOUT
         opened_pipes.each_value do |pipe|

data/lib/process_executer/commands/run_with_capture.rb

@@ -50,8 +50,6 @@ module ProcessExecuter
         @stderr_buffer = StringIO.new
         stderr_buffer.set_encoding(options.effective_stderr_encoding)
 
-        add_capture_redirections
-
         begin
           super
         ensure
@@ -89,10 +87,11 @@ module ProcessExecuter
         )
       end
 
-      # Add the stdout and stderr capture redirections to {#redirection_overrides}
+      # The stdout and stderr capture redirections
       #
-      # The capture redirections are not written into {options} so the caller's
-      # options object is not modified.
+      # Called by {Run#call} to seed the redirection overrides, so the capture
+      # redirections are layered on top of the user's options at spawn time
+      # without writing into {#options} or mutating the parent's state.
       #
       # When the user gives a combined redirection whose key covers both stdout
       # and stderr (e.g. `[:out, :err] => destination`), a single capture
@@ -100,80 +99,98 @@ module ProcessExecuter
       # {#stdout_buffer} and {#stderr_buffer} is left empty, mirroring the
       # `merge_output: true` contract.
       #
-      # @return [Void]
+      # @return [Hash<Object, Object>]
       #
-      def add_capture_redirections
+      def internal_redirections
         if options.combined_stdout_and_stderr_redirection?
-          add_combined_capture_redirection
+          combined_capture_redirection
         else
-          add_stdout_and_stderr_capture_redirections
+          stdout_and_stderr_capture_redirections
         end
       end
 
-      # Add a single capture redirection for a combined stdout/stderr key
+      # A single capture redirection for a combined stdout/stderr key
       #
       # Both streams are interleaved into {#stdout_buffer}; {#stderr_buffer} is
       # left empty.
       #
-      # @return [Void]
+      # @return [Hash<Object, Object>]
       #
-      def add_combined_capture_redirection
-        redirection_overrides.merge!(
-          capture_option(:out, stdout_redirection_source, stdout_redirection_destination, stdout_buffer)
+      def combined_capture_redirection
+        tee_capture_redirection(
+          options.stdout_redirection_source, options.stdout_redirection_destination, stdout_buffer
         )
       end
 
-      # Add separate capture redirections for stdout and stderr
+      # 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]
+      # @return [Hash<Object, Object>]
       #
-      def add_stdout_and_stderr_capture_redirections
-        out = stdout_buffer
-        err = options.merge_output ? [:child, 1] : stderr_buffer
-
-        redirection_overrides.merge!(
-          capture_option(:out, stdout_redirection_source, stdout_redirection_destination, out),
-          capture_option(:err, stderr_redirection_source, stderr_redirection_destination, err)
-        )
+      def stdout_and_stderr_capture_redirections
+        stdout_capture_redirection.merge(stderr_capture_redirection)
       end
 
-      # The source for stdout redirection
-      # @return [Object]
-      def stdout_redirection_source = options.stdout_redirection_source
+      # The redirection that captures stdout into {#stdout_buffer}
+      #
+      # Tees the buffer onto the user's stdout redirection if one was given;
+      # otherwise installs the plain default capture redirection.
+      #
+      # @return [Hash<Object, Object>]
+      #
+      def stdout_capture_redirection
+        source = options.stdout_redirection_source
+        return default_capture_redirection(:out, stdout_buffer) unless source
 
-      # The source for stderr redirection
-      # @return [Object]
-      def stderr_redirection_source = options.stderr_redirection_source
+        tee_capture_redirection(source, options.stdout_redirection_destination, stdout_buffer)
+      end
 
-      # The destination for stdout redirection
-      # @return [Object]
-      def stdout_redirection_destination = options.stdout_redirection_destination
+      # The redirection that captures stderr
+      #
+      # Stderr is captured into {#stderr_buffer}, or into stdout (and thereby
+      # {#stdout_buffer}) if `merge_output: true` was given. Tees the capture
+      # destination onto the user's stderr redirection if one was given;
+      # otherwise installs the plain default capture redirection.
+      #
+      # @return [Hash<Object, Object>]
+      #
+      def stderr_capture_redirection
+        capture_destination = options.merge_output ? [:child, 1] : stderr_buffer
+        source = options.stderr_redirection_source
+        return default_capture_redirection(:err, capture_destination) unless source
 
-      # The destination for stderr redirection
-      # @return [Object]
-      def stderr_redirection_destination = options.stderr_redirection_destination
+        tee_capture_redirection(source, options.stderr_redirection_destination, capture_destination)
+      end
 
-      # 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)
+      # Tee the capture destination onto the redirection the user gave
+      #
+      # If the user's destination is already a tee, the capture destination is
+      # added to it; otherwise the user's destination and the capture
+      # destination are wrapped in a new tee.
+      #
+      # @param source [Symbol, Integer, Array] The redirection source the user gave
+      # @param destination [Object] The redirection destination the user gave
       # @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
+      # @return [Hash] The redirection to merge into options
+      def tee_capture_redirection(source, destination, capture_destination)
+        if Destinations::Tee.handles?(destination)
+          { source => destination + [capture_destination] }
         else
-          { redirection_source => capture_destination }
+          { source => [:tee, destination, capture_destination] }
         end
       end
 
+      # The plain capture redirection used when the user gave no redirection
+      #
+      # @param source [Symbol] The redirection source (:out or :err)
+      # @param capture_destination [Object] The destination to capture output to
+      # @return [Hash] The redirection to merge into options
+      def default_capture_redirection(source, capture_destination)
+        { source => capture_destination }
+      end
+
       # Log the captured command output to the given logger at debug level
       # @return [Void]
       def log_command_output

data/lib/process_executer/commands/spawn_with_timeout.rb

@@ -48,7 +48,8 @@ module ProcessExecuter
       #
       def call
         begin
-          @pid = Process.spawn(*command, **spawn_options)
+          @effective_spawn_options = spawn_options
+          @pid = Process.spawn(*command, **effective_spawn_options)
         rescue StandardError => e
           raise ProcessExecuter::SpawnError, "Failed to spawn process: #{e.message}"
         end
@@ -132,6 +133,17 @@ module ProcessExecuter
       #
       def spawn_options = options.spawn_options.merge(process_group_options)
 
+      # The spawn options that were passed to Process.spawn
+      #
+      # Captured once by {#call} -- after any {#spawn_options} additions a
+      # subclass contributed -- so the kill path inspects the options actually
+      # used instead of recomputing the merge. nil until {#call} spawns the
+      # subprocess; the kill path only runs after that.
+      #
+      # @return [Hash, nil]
+      #
+      attr_reader :effective_spawn_options
+
       # Spawn options that place the subprocess into its own process group
       #
       # When `timeout_after` is set to a value that can fire (`nil` and `0`
@@ -141,6 +153,13 @@ module ProcessExecuter
       # direct child. Empty when no timeout can fire or when the caller gave a
       # `pgroup`/`new_pgroup` option themselves (their setting is honored).
       #
+      # This method never reflects a subclass's {#spawn_options} override, so
+      # {#isolated_in_new_process_group?} never counts an option a subclass
+      # contributes as isolation by this class -- though such an option can
+      # still make the subprocess a process group leader (see
+      # {#process_group_leader?}) -- and a subclass that removes the option
+      # added here prevents the isolation (and its cleanup) altogether.
+      #
       # A new process group is a background group for any terminal the
       # subprocess inherits, so an interactive subprocess that reads the
       # terminal is stopped by `SIGTTIN` and then killed when the timeout
@@ -148,6 +167,11 @@ module ProcessExecuter
       # needs an interactive subprocess to stay in the foreground process
       # group can pass their own `pgroup` option.
       #
+      # Deterministic: the result depends only on {#options} -- not mutated
+      # during {#call} -- and the platform, so the kill path's
+      # {#isolated_in_new_process_group?} re-read agrees with the value that
+      # was merged into the spawn options.
+      #
       # @return [Hash]
       #
       def process_group_options
@@ -302,19 +326,25 @@ module ProcessExecuter
       # @return [Boolean]
       #
       def process_group_leader?
-        [true, 0].include?(spawn_options[:pgroup]) || spawn_options[:new_pgroup] == true
+        [true, 0].include?(effective_spawn_options[:pgroup]) || effective_spawn_options[:new_pgroup] == true
       end
 
       # Whether this class isolated the subprocess into its own process group
       #
-      # True when the subprocess is a new process group leader and that came
-      # from {#process_group_options} rather than from a `pgroup`/`new_pgroup`
-      # option the caller supplied.
+      # True when {#process_group_options} -- the single source of truth for
+      # the isolation decision -- added a process group option and the
+      # subprocess actually became a new process group leader
+      # ({#process_group_leader?} over the captured options). The leader
+      # check matters only when a subclass's {#spawn_options} override
+      # removed or overrode the added option: then no isolation happened and
+      # the abandoned-wait cleanup must leave the subprocess alone. False
+      # when the subprocess's process group (if any) came from a
+      # `pgroup`/`new_pgroup` option the caller supplied.
       #
       # @return [Boolean]
       #
       def isolated_in_new_process_group?
-        process_group_leader? && options.pgroup == :not_set && options.new_pgroup == :not_set
+        !process_group_options.empty? && process_group_leader?
       end
 
       # Send SIGKILL to the subprocess's process group

data/lib/process_executer/monitored_pipe.rb

@@ -44,9 +44,10 @@ module ProcessExecuter
   # a thread is created to read data written to the pipe. As data is read from the pipe,
   # it is written to the destination provided in the MonitoredPipe initializer.
   #
-  # If the destination raises an exception (of any class, not just
-  # `StandardError`), the monitoring thread will exit, the pipe will be closed,
-  # and the exception will be saved in `#exception`.
+  # If an exception (of any class, not just `StandardError`) is raised while
+  # collecting output -- by the destination's `#write`, by the monitor loop,
+  # or by pipe cleanup -- the monitoring thread exits, the pipe is closed, and
+  # the exception is saved in {#exception}.
   #
   # > **⚠️ WARNING**
   # >
@@ -347,14 +348,22 @@ module ProcessExecuter
 
     # @!attribute [r]
     #
-    # The exception raised by a destination
+    # The first exception recorded while collecting output
     #
-    # If an exception is raised by a destination, it is stored here. Otherwise, it is `nil`.
+    # Any failure while collecting output is recorded here, not only a
+    # destination error: the destination's `#write` raising, the monitor loop
+    # raising, or pipe cleanup raising. `nil` if no exception was raised.
+    #
+    # When more than one exception is raised, the first one *recorded* wins
+    # and the rest are discarded. Recording order has one corner: when the
+    # monitor loop raises and pipe cleanup then also raises, the cleanup
+    # error is the one recorded, because the monitor-loop exception is still
+    # in flight while cleanup runs and reaches its recording site last.
     #
     # @example
     #   pipe.exception #=> nil
     #
-    # @return [Exception, nil] the exception raised by a destination or `nil` if no exception was raised
+    # @return [Exception, nil] the first recorded exception or `nil` if no exception was raised
     #
     attr_reader :exception
 

data/lib/process_executer/options/base.rb

@@ -62,10 +62,8 @@ module ProcessExecuter
       #
       def initialize(**options_hash)
         @options_hash = allowed_options.transform_values(&:default).merge(options_hash)
-        @errors = []
-        assert_no_unknown_options
         define_accessor_methods
-        validate_options
+        validate!
       end
 
       # All the allowed options as a hash whose keys are the option names
@@ -183,13 +181,10 @@ module ProcessExecuter
       def merge!(*other_options_hashes)
         original_options_hash = @options_hash
         @options_hash = original_options_hash.dup.merge!(*other_options_hashes)
-        @errors = []
-        assert_no_unknown_options
-        validate_options
+        validate!
         self
       rescue ProcessExecuter::ArgumentError
         @options_hash = original_options_hash
-        @errors = []
         raise
       end
 
@@ -262,6 +257,23 @@ module ProcessExecuter
       #
       attr_reader :options_hash
 
+      # Run the full validation sequence over the current options hash
+      #
+      # Checks for unknown options and then validates option values, leaving
+      # `errors` empty on exit whether validation passes or raises.
+      #
+      # @return [void]
+      # @raise [ProcessExecuter::ArgumentError] if an unknown option or an
+      #   invalid option value is found
+      # @api private
+      def validate!
+        @errors = []
+        assert_no_unknown_options
+        validate_options
+      ensure
+        @errors = []
+      end
+
       # Raise an argument error for invalid option values
       # @return [void]
       # @raise [ProcessExecuter::ArgumentError] if any invalid option values are found
@@ -296,7 +308,7 @@ module ProcessExecuter
         return if unknown_options.empty?
 
         raise(
-          ArgumentError,
+          ProcessExecuter::ArgumentError,
           "Unknown option#{'s' if unknown_options.count > 1}: #{unknown_options.join(', ')}"
         )
       end

data/lib/process_executer/options/run_with_capture_options.rb

@@ -31,9 +31,7 @@ module ProcessExecuter
       #
       # @api private
       #
-      def effective_stdout_encoding
-        canonical_encoding(stdout_encoding || encoding || DEFAULT_ENCODING)
-      end
+      def effective_stdout_encoding = effective_encoding(stdout_encoding)
 
       # Determines the character encoding to use for stderr
       #
@@ -49,12 +47,27 @@ module ProcessExecuter
       #
       # @api private
       #
-      def effective_stderr_encoding
-        canonical_encoding(stderr_encoding || encoding || DEFAULT_ENCODING)
-      end
+      def effective_stderr_encoding = effective_encoding(stderr_encoding)
 
       private
 
+      # The encoding to use for a stream given its stream-specific option value
+      #
+      # Prioritizes the stream-specific value if set, otherwise falls back to
+      # `encoding`, and finally defaults to `DEFAULT_ENCODING`. The result is
+      # canonicalized with {#canonical_encoding}.
+      #
+      # @param stream_encoding [Encoding, String, Symbol, nil] the value of
+      #   `stdout_encoding` or `stderr_encoding`
+      #
+      # @return [Encoding, nil] nil if the value names an unknown encoding
+      #
+      # @api private
+      #
+      def effective_encoding(stream_encoding)
+        canonical_encoding(stream_encoding || encoding || DEFAULT_ENCODING)
+      end
+
       # The options allowed for objects of this class
       # @return [Array<OptionDefinition>]
       # @api private
@@ -148,70 +161,26 @@ module ProcessExecuter
       end
 
       # Note an error if the encoding option is not valid
-      # @param key [Symbol] the option key
-      # @param value [Object] the option value
-      # @return [Void]
-      # @api private
-      def validate_encoding_option(key, value)
-        return unless valid_encoding_type?(key, value)
-
-        return if value.nil? || value.is_a?(Encoding)
-
-        validate_encoding_symbol(key, value) if value.is_a?(Symbol)
-
-        validate_encoding_string(key, value) if value.is_a?(String)
-      end
-
-      # False if the value is not a valid encoding type, true otherwise
-      #
-      # @param key [Symbol] the option key
       #
-      # @param value [Object] the option value
-      #
-      # @return [Boolean]
-      #
-      # @api private
-      #
-      def valid_encoding_type?(key, value)
-        return true if value.nil? || value.is_a?(Encoding) || value.is_a?(Symbol) || value.is_a?(String)
-
-        errors << "#{key} must be an Encoding object, String, Symbol (:binary, :default_external), " \
-                  "or nil, but was #{value.inspect}"
-
-        false
-      end
-
-      # Note an error if the encoding symbol is not valid
+      # `nil`, an Encoding object, `:binary`, and `:default_external` are
+      # valid as given. A String is valid if {#canonical_encoding} recognizes
+      # it as an encoding name. Any other value is invalid.
       #
       # @param key [Symbol] the option key
-      #
-      # @param value [Symbol] the option value
-      #
+      # @param value [Object] the option value
       # @return [Void]
-      #
       # @api private
-      #
-      def validate_encoding_symbol(key, value)
-        return if %i[binary default_external].include?(value)
-
-        errors << "#{key} when given as a symbol must be :binary or :default_external, " \
-                  "but was #{value.inspect}"
-      end
-
-      # Note an error if the encoding string is not valid
-      #
-      # @param key [Symbol] the option key
-      #
-      # @param value [String] the option value
-      #
-      # @return [void]
-      #
-      # @api private
-      #
-      def validate_encoding_string(key, value)
-        Encoding.find(value)
-      rescue ::ArgumentError
-        errors << "#{key} specifies an unknown encoding name: #{value.inspect}"
+      def validate_encoding_option(key, value)
+        case value
+        when nil, Encoding, :binary, :default_external then nil
+        when Symbol
+          errors << "#{key} when given as a symbol must be :binary or :default_external, but was #{value.inspect}"
+        when String
+          errors << "#{key} specifies an unknown encoding name: #{value.inspect}" if canonical_encoding(value).nil?
+        else
+          errors << "#{key} must be an Encoding object, String, Symbol (:binary, :default_external), " \
+                    "or nil, but was #{value.inspect}"
+        end
       end
     end
   end

data/lib/process_executer/version.rb

@@ -3,5 +3,5 @@
 module ProcessExecuter
   # The current Gem version
   # @return [String]
-  VERSION = '4.1.0'
+  VERSION = '4.1.1'
 end

data/release-please-config.json

@@ -4,7 +4,6 @@
     ".": {
       "release-type": "ruby",
       "package-name": "process_executer",
-      "release-as": "4.1.0",
       "changelog-path": "CHANGELOG.md",
       "version-file": "lib/process_executer/version.rb",
       "bump-minor-pre-major": true,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: process_executer
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.1.1
 platform: ruby
 authors:
 - James Couball
@@ -295,8 +295,8 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/main-branch/process_executer
   source_code_uri: https://github.com/main-branch/process_executer
-  documentation_uri: https://rubydoc.info/gems/process_executer/4.1.0
-  changelog_uri: https://rubydoc.info/gems/process_executer/4.1.0/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/process_executer/4.1.1
+  changelog_uri: https://rubydoc.info/gems/process_executer/4.1.1/file/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: