process_executer 4.0.4 → 4.1.1

data/lib/process_executer/options/run_with_capture_options.rb

@@ -23,13 +23,15 @@ module ProcessExecuter
       # `encoding`, and finally defaults to `DEFAULT_ENCODING` if neither
       # is available.
       #
-      # @return [Encoding]
+      # The value is canonicalized to an Encoding object, so equivalent
+      # representations (e.g. `Encoding::UTF_8`, `'UTF-8'`, or `:binary` for
+      # `Encoding::BINARY`) all resolve to the same Encoding.
+      #
+      # @return [Encoding, nil] nil if the value names an unknown encoding
       #
       # @api private
       #
-      def effective_stdout_encoding
-        stdout_encoding || encoding || DEFAULT_ENCODING
-      end
+      def effective_stdout_encoding = effective_encoding(stdout_encoding)
 
       # Determines the character encoding to use for stderr
       #
@@ -37,16 +39,35 @@ module ProcessExecuter
       # `encoding`, and finally defaults to `DEFAULT_ENCODING` if neither
       # is available.
       #
-      # @return [Encoding]
+      # The value is canonicalized to an Encoding object, so equivalent
+      # representations (e.g. `Encoding::UTF_8`, `'UTF-8'`, or `:binary` for
+      # `Encoding::BINARY`) all resolve to the same Encoding.
+      #
+      # @return [Encoding, nil] nil if the value names an unknown encoding
       #
       # @api private
       #
-      def effective_stderr_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
@@ -66,6 +87,8 @@ module ProcessExecuter
       # - if the merge_output value is not a Boolean
       # - if merge_output: true and a stderr redirection is given
       # - if merge_output: true and stdout and stderr encodings are different
+      # - if a combined stdout/stderr redirection (e.g. `[:out, :err] =>
+      #   destination`) is given and stdout and stderr encodings are different
       #
       # @param _key [Symbol] the option key (not used)
       # @param _value [Object] the option value (not used)
@@ -76,80 +99,88 @@ module ProcessExecuter
           errors << "merge_output must be true or false but was #{merge_output.inspect}"
         end
 
-        return unless merge_output == true
-
-        errors << 'Cannot give merge_output: true AND a stderr redirection' if stderr_redirection_source
-
-        return if effective_stdout_encoding == effective_stderr_encoding
-
-        errors << 'Cannot give merge_output: true AND give different encodings for stdout and stderr'
+        if merge_output == true
+          errors << 'Cannot give merge_output: true AND a stderr redirection' if stderr_redirection_source
+          validate_uniform_capture_encoding('merge_output: true')
+        elsif combined_stdout_and_stderr_redirection?
+          validate_uniform_capture_encoding('a redirection that combines stdout and stderr')
+        end
       end
 
-      # Note an error if the encoding option is not valid
-      # @param key [Symbol] the option key
-      # @param value [Object] the option value
+      # Note an error if the stdout and stderr encodings are different
+      #
+      # Used when both streams are captured into the single stdout buffer (via
+      # `merge_output: true` or a combined stdout/stderr redirection), which
+      # requires a single encoding.
+      #
+      # Encodings are compared in their canonical form, so equivalent
+      # representations (e.g. `Encoding::UTF_8` and `'UTF-8'`) are not
+      # rejected. A value that does not canonicalize to an Encoding (an
+      # unknown encoding name or an invalid type) is skipped here; the
+      # encoding option's own validator reports it.
+      #
+      # @param description [String] describes the option that requires a single encoding
       # @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)
+      def validate_uniform_capture_encoding(description)
+        stdout_encoding = effective_stdout_encoding
+        stderr_encoding = effective_stderr_encoding
 
-        validate_encoding_symbol(key, value) if value.is_a?(Symbol)
+        return unless stdout_encoding.is_a?(Encoding) && stderr_encoding.is_a?(Encoding)
+        return if stdout_encoding == stderr_encoding
 
-        validate_encoding_string(key, value) if value.is_a?(String)
+        errors << "Cannot give #{description} AND give different encodings for stdout and stderr"
       end
 
-      # False if the value is not a valid encoding type, true otherwise
+      # Convert an encoding option value to its canonical Encoding object
       #
-      # @param key [Symbol] the option key
-      #
-      # @param value [Object] the option value
+      # @param value [Encoding, String, Symbol, Object] the encoding option value
       #
-      # @return [Boolean]
+      # @return [Encoding, Object, nil] the Encoding for a recognized value, nil
+      #   for a String naming an unknown encoding, otherwise the value unchanged
       #
       # @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
+      def canonical_encoding(value)
+        case value
+        when :binary then Encoding::BINARY
+        when :default_external then Encoding.default_external
+        when String then find_encoding(value)
+        else value
+        end
       end
 
-      # Note an error if the encoding symbol is not valid
-      #
-      # @param key [Symbol] the option key
-      #
-      # @param value [Symbol] the option value
-      #
-      # @return [Void]
+      # Find an encoding by name, returning nil if the name is unknown
       #
+      # @param name [String] the encoding name
+      # @return [Encoding, nil]
       # @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}"
+      def find_encoding(name)
+        Encoding.find(name)
+      rescue ::ArgumentError
+        nil
       end
 
-      # Note an error if the encoding string is not valid
-      #
-      # @param key [Symbol] the option key
-      #
-      # @param value [String] the option value
+      # Note an error if the encoding option is not valid
       #
-      # @return [void]
+      # `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 [Object] 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/options/spawn_options.rb

@@ -110,6 +110,19 @@ module ProcessExecuter
         (key = stderr_redirection_source) ? options_hash[key] : nil
       end
 
+      # Determine if a single redirection option key covers both stdout and stderr
+      #
+      # This is the case for a combined redirection such as `[:out, :err] =>
+      # destination`, where both {#stdout_redirection_source} and
+      # {#stderr_redirection_source} resolve to the same key.
+      #
+      # @return [Boolean]
+      # @api private
+      def combined_stdout_and_stderr_redirection?
+        key = stdout_redirection_source
+        !key.nil? && key.equal?(stderr_redirection_source)
+      end
+
       private
 
       # Define the allowed options

data/lib/process_executer/result.rb

@@ -10,6 +10,12 @@ module ProcessExecuter
   # * `elapsed_time`: the seconds the command ran
   # * `timed_out?`: true if the process timed out
   #
+  # In the rare case that the timeout fires after the process was already
+  # reaped, its status is lost: the result delegates to a nil status and
+  # `timed_out?` is true. {#success?} and {#to_s} still work, but methods
+  # forwarded to the status (like `exitstatus` or `signaled?`) will raise
+  # NoMethodError.
+  #
   # @api public
   #
   class Result < SimpleDelegator
@@ -25,7 +31,8 @@ module ProcessExecuter
     #
     #   ProcessExecuter::Result.new(status, command:, options:, timed_out:, elapsed_time:)
     #
-    # @param status [Process::Status] the status to delegate to
+    # @param status [Process::Status, nil] the status to delegate to (nil when the
+    #   timeout raced the wait for the process and the status was lost)
     #
     # @param command [Array] the command that was used to spawn the process
     #
@@ -70,7 +77,11 @@ module ProcessExecuter
     attr_reader :elapsed_time
 
     # @!attribute [r] timed_out?
-    # True if the process timed out and was sent the SIGKILL signal
+    # True if the wait for the process was cut short by `timeout_after` elapsing
+    #
+    # A timed out process is sent the SIGKILL signal, unless it had already
+    # exited in the moment between the timeout firing and the kill (the
+    # raced-timeout corner case described above).
     # @example
     #   result = ProcessExecuter.spawn_with_timeout('sleep 10', timeout_after: 0.01)
     #   result.timed_out? # => true

data/lib/process_executer/version.rb

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

data/lib/process_executer.rb

@@ -32,6 +32,26 @@ module ProcessExecuter
   # * `timeout_after: <Numeric, nil>`: the amount of time (in seconds) to wait before
   #   signaling the process with SIGKILL. 0 or nil means no timeout.
   #
+  #   When a timeout is given, the command is spawned into its own process group
+  #   (`pgroup: true` on POSIX, `new_pgroup: true` on Windows) unless the caller
+  #   passes a `pgroup`/`new_pgroup` option themselves. Note that a new process
+  #   group is a background group for any terminal the command inherits, so an
+  #   interactive command that reads the terminal is stopped by `SIGTTIN` and
+  #   then killed when the timeout fires. A caller who needs an interactive
+  #   command to stay in the foreground process group can pass their own
+  #   `pgroup` option (for example, `pgroup: Process.getpgrp`).
+  #
+  #   On timeout, the whole process group is killed so that descendant
+  #   processes still in that group do not outlive the timeout. A descendant
+  #   that started its own session or moved to another process group (a
+  #   daemon, for example) is not killed. If the group can not be killed (for
+  #   instance, the caller placed the command in an existing process group),
+  #   only the direct child is killed.
+  #
+  #   Killing the process group is only supported on POSIX platforms. On
+  #   Windows, Ruby's `Process.kill` cannot signal a process group, so only the
+  #   direct child is killed and descendant processes may survive the timeout.
+  #
   # Returns a {Result} object. The {Result} class is a decorator for
   # [Process::Status](https://docs.ruby-lang.org/en/3.4/Process/Status.html) that
   # provides additional attributes about the command's status. This includes the
@@ -55,7 +75,10 @@ module ProcessExecuter
   #     the following options are supported: `:timeout_after`
   #
   #   @option options_hash [Numeric] :timeout_after the amount of time (in seconds)
-  #     to wait before signaling the process with SIGKILL
+  #     to wait before killing the process -- and, on POSIX platforms when the
+  #     effective spawn options make the command a new process group leader
+  #     (set automatically, or by an explicit `pgroup: true` or `pgroup: 0`),
+  #     its whole process group
   #
   # @overload spawn_with_timeout(*command, options)
   #
@@ -209,7 +232,10 @@ module ProcessExecuter
   #   and its result at the info level
   #
   #   @option options_hash [Numeric] :timeout_after the amount of time (in seconds)
-  #     to wait before signaling the process with SIGKILL
+  #     to wait before killing the process -- and, on POSIX platforms when the
+  #     effective spawn options make the command a new process group leader
+  #     (set automatically, or by an explicit `pgroup: true` or `pgroup: 0`),
+  #     its whole process group
   #
   # @overload run(*command, options)
   #
@@ -279,6 +305,12 @@ module ProcessExecuter
   # <destination>` or `err: <destination>`). These redirections will receive the
   # output in addition to the internal capture.
   #
+  # A combined redirection whose key covers both stdout and stderr (e.g. `[:out,
+  # :err] => <destination>`) behaves like `merge_output: true`: both streams are
+  # interleaved into the `#stdout` capture and `#stderr` is empty. As with
+  # `merge_output: true`, a `ProcessExecuter::ArgumentError` is raised if
+  # different encodings are given for stdout and stderr.
+  #
   # Unless told otherwise, the internally captured output is assumed to be in UTF-8
   # encoding. This assumption can be changed with the `encoding`,
   # `stdout_encoding`, or `stderr_encoding` options. These options accept any

data/process_spawn_test/README.md

@@ -4,14 +4,43 @@ These tests verify that `Process.spawn`, `Process.wait`, and `Process.wait2` wor
 correctly across different Ruby implementations and operating systems.
 
 This test suite is particularly important for verifying JRuby behavior on Windows,
-where historically there have been issues with subprocess status reporting.
+where historically there have been issues with subprocess status reporting. See
+[jruby/jruby#7515](https://github.com/jruby/jruby/issues/7515).
 
 ## Tests
 
 The test suite includes:
 
 * Test that `Process#wait` sets the global `$CHILD_STATUS` variable
+* Test that `Process#wait` reports the exit status of a child that failed
+* Test that `Process#wait` blocks until the child exits
 * Test that `Process#wait2` returns a non-nil status
+* Test that `Process#wait2` returns the pid and status of a child that failed
+
+## Spawn backends
+
+Set `SPAWN_BACKEND` to choose which spawn implementation the examples exercise:
+
+| Value | Meaning |
+| --- | --- |
+| `stock` (default) | Whatever the running Ruby provides |
+| `subspawn` | [byteit101/subspawn](https://github.com/byteit101/subspawn) replaces `Process.spawn` and the `wait` family |
+
+JRuby has a built-in opt-in for SubSpawn, `USE_SUBSPAWN=true`, but it refuses to
+honor it on the one platform this suite cares about: `Ruby.java` logs
+`env USE_SUBSPAWN=true is unsupported on Windows at this time` and loads nothing.
+So `spec_helper.rb` requires `subspawn/replace-builtin` itself instead.
+
+Two things keep the `subspawn` backend from being a plain `gem install subspawn --pre`:
+
+* The published `subspawn` 0.2.0.pre1 cannot be installed on JRuby at all. Its
+  `engine-hacks` dependency was only ever pushed as a `ruby` platform gem carrying
+  a C extension; the `java` platform build that its gemspec provides for was never
+  published, so RubyGems tries to compile the C extension under JRuby.
+* master is newer than the RC and carries fixes the RC does not have.
+
+So the workflow clones the repo and builds the gemspecs with the active Ruby, which
+produces the java-platform `engine-hacks` gem.
 
 ## Running the Tests
 
@@ -27,10 +56,18 @@ Alternatively, you can stay at the root and run:
 bundle exec rspec process_spawn_test/spec/test_spec.rb
 ```
 
+SubSpawn is not in that Gemfile. To run the `subspawn` backend, install it as a
+system gem and run `rspec` directly, outside the bundle:
+
+```bash
+SPAWN_BACKEND=subspawn rspec spec/test_spec.rb
+```
+
 ## GitHub Actions Workflow
 
 The workflow file `.github/workflows/process-spawn-test.yml` can be manually triggered to run these tests on:
 - MRI Ruby and JRuby
 - Ubuntu (Linux) and Windows
+- the `stock` and `subspawn` spawn backends (`subspawn` on JRuby only)
 
 To run the workflow, go to the Actions tab in GitHub and select "Process.spawn Test" from the workflow list.

data/process_spawn_test/spec/spec_helper.rb

@@ -2,6 +2,17 @@
 
 require 'rspec'
 
+# Which spawn implementation these examples exercise: 'stock' (whatever the
+# running Ruby provides) or 'subspawn' (byteit101/subspawn).
+SPAWN_BACKEND = ENV.fetch('SPAWN_BACKEND', 'stock')
+
+# JRuby has a built-in opt-in for SubSpawn, `USE_SUBSPAWN=true`, but it refuses
+# to honor it on the one platform jruby/jruby#7515 is about: Ruby.java logs
+# "env USE_SUBSPAWN=true is unsupported on Windows at this time" and loads
+# nothing. Require the replacement shim directly so the Windows job actually
+# runs against SubSpawn.
+require 'subspawn/replace-builtin' if SPAWN_BACKEND == 'subspawn'
+
 RSpec.configure do |config|
   # Enable flags like --only-failures and --next-failure
   config.example_status_persistence_file_path = '.rspec_status'
@@ -12,4 +23,11 @@ RSpec.configure do |config|
   config.expect_with :rspec do |c|
     c.syntax = :expect
   end
+
+  config.before(:suite) do
+    warn "Ruby:          #{RUBY_DESCRIPTION}"
+    warn "spawn backend: #{SPAWN_BACKEND}"
+    # Records whether the shim really took effect, and which backend it picked.
+    warn "SubSpawn:      #{defined?(SubSpawn) ? SubSpawn::Platform : '(not loaded)'}"
+  end
 end

data/process_spawn_test/spec/test_spec.rb

@@ -9,6 +9,20 @@ RSpec.describe 'Process#wait' do
     expect($CHILD_STATUS).not_to be_nil
     expect($CHILD_STATUS.pid).to eq(pid)
   end
+
+  it 'reports the exit status of a child that failed' do
+    pid = Process.spawn('ruby', '-e', 'exit 42')
+    Process.wait(pid)
+    expect($CHILD_STATUS&.exitstatus).to eq(42)
+  end
+
+  it 'blocks until the child exits' do
+    pid = Process.spawn('ruby', '-e', 'sleep 2')
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    Process.wait(pid)
+    elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+    expect(elapsed).to be >= 1.5
+  end
 end
 
 RSpec.describe 'Process#wait2' do
@@ -18,4 +32,11 @@ RSpec.describe 'Process#wait2' do
     expect(status).not_to be_nil
     expect(status.pid).to eq(pid)
   end
+
+  it 'returns the pid and status of a child that failed' do
+    pid = Process.spawn('ruby', '-e', 'exit 42')
+    reaped_pid, status = Process.wait2(pid)
+    expect(reaped_pid).to eq(pid)
+    expect(status&.exitstatus).to eq(42)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: process_executer
 version: !ruby/object:Gem::Version
-  version: 4.0.4
+  version: 4.1.1
 platform: ruby
 authors:
 - James Couball
@@ -237,11 +237,13 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".commitlintrc.yml"
+- ".editorconfig"
 - ".husky/commit-msg"
 - ".markdownlint.yml"
 - ".release-please-manifest.json"
 - ".rspec"
 - ".rubocop.yml"
+- ".vscode/extensions.json"
 - ".yardopts"
 - CHANGELOG.md
 - Gemfile
@@ -293,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.0.4
-  changelog_uri: https://rubydoc.info/gems/process_executer/4.0.4/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:
@@ -312,7 +314,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements:
 - 'Platform: Mac, Linux, or Windows'
 - 'Ruby: MRI 3.1 or later, TruffleRuby 24 or later, or JRuby 9.4 or later'
-rubygems_version: 4.0.6
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Enhanced subprocess execution with timeouts, output capture, and flexible
   redirection