exec_service 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb132c5eeab64f1edb3663b8f609e75711e3f5b2e890e435c4730463b428383f
-  data.tar.gz: c9c05cb63d481e46d9702c8033b41f375518256d8ff3af476d1a56c10d1cb05e
+  metadata.gz: 33a8ad6fafa08f5efe31aba23468497bace9859453d3a12d23189c73eb57cc4e
+  data.tar.gz: c38f315c6ed811d2e284847473c184e01dba57847e05266c9c88b4706214626a
 SHA512:
-  metadata.gz: 8c599381f5f3fcb5571e1fd85c7f7e1efc0534aee121e0ef80c6a846741a727c141b6f215ced7c2e7acc7470ae63b24e5b54fa8067b644df54dc00777316d5c1
-  data.tar.gz: 188571ba3dbcb56090f0ce3ebf19c09c82dda3de8972122d2b055646dab37658e282b170a8347b656590b287d7bab48ecc2b6f68d171aeeacdacbfd977a5cb11
+  metadata.gz: ab846b2e66984966fdddff8a9ed7c815473484f80508eeeedc42fc2bc48e3756529e332efb497d8913a62db3412c1063589c37a98f91e28c3404bf8622494938
+  data.tar.gz: 82f3c1943930fffe8d0b96d48087e648e0b39ff8dba5601b1c595e6dde362ca16cc987cc924a381534676ba3553285af24f942550433914ec8c56bf857207d18

data/.yardopts

@@ -0,0 +1,10 @@
+--no-private
+--title=ExecService
+--markup=markdown
+--markup-provider redcarpet
+--main=README.md
+./lib/exec_service.rb
+-
+README.md
+LICENSE.md
+CHANGELOG.md

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Release History
+
+### v0.1.0 / 2026-04-29
+
+* ADDED: Initial extraction from toys-core

data/LICENSE.md

@@ -0,0 +1,21 @@
+# License
+
+Copyright 2026 Daniel Azuma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

data/README.md

@@ -1,9 +1,103 @@
-# Placeholder for exec_service
+# ExecService
 
-This is a placeholder gem, which was generated on 2026-04-28 to
-reserve the gem "exec_service".
-The actual gem is planned for release in the near future.
+`ExecService` is a full-featured Ruby service class for running and managing
+subprocesses. It provides a rich interface for spawning processes, controlling
+and monitoring those processes, setting up and redirecting streams, and
+interpreting results. It also provides shortcuts for common cases such as
+invoking Ruby in a subprocess or capturing output in a string. Use
+`ExecService` when existing interfaces such as the `system()` method or the
+`Open3` library are not sufficiently powerful or expressive for your needs.
 
-If this is a problem, or if the actual gem has not been released
-in a timely manner, you can contact the owner at
-`dazuma@gmail.com`.
+## Getting started
+
+Install `ExecService` via the
+[exec_service gem](https://rubygems.org/gems/exec_service).
+
+```sh
+% gem install exec_service
+```
+
+or add it to your Gemfile:
+
+```ruby
+gem "exec_service"
+```
+
+To use the service, instantiate `ExecService`, and call the convenient methods
+on it to spawn subprocesses:
+
+```ruby
+require "exec_service"
+exec_service = ExecService.new
+git_version = exec_service.capture(["git", "--version"]).chomp
+```
+
+## Features
+
+ *  Execute subprocesses in the foreground (i.e. blocking until completion) or
+    background (returning immediately)
+ *  Fork (execute a proc in a subprocess) or spawn (specify a command to run)
+ *  Environment setup for the subprocess, including
+     *  Working directory
+     *  Environment variables
+     *  Optionally disabling any existing bundle
+     *  Umask
+     *  Process group
+ *  Rich process control interface, including:
+     *  Access to process state and results
+     *  Read/write access to non-redirected streams
+     *  Signalling
+     *  Joining
+ *  Robust setup and redirect of streams, including:
+     *  Inheriting parent process streams
+     *  Redirecting to/from files
+     *  Redirecting to/from pipes
+     *  Redirecting to/from arbitrary IO objects
+     *  Redirecting error to out and vice versa
+     *  Reading input from strings
+     *  Capturing output streams
+     *  Tees for output streams
+     *  Redirecting to/from null
+     *  Closing streams
+ *  Rich result reporting, including exit status, signals, and exceptions
+ *  Convenience methods for common use cases, including:
+     *  Simple output captures
+     *  Running Ruby processes
+     *  Executing a string in the shell
+ *  Customizable logging
+
+## Contributing
+
+Development is done in GitHub at https://github.com/dazuma/exec_service.
+
+ *  To file issues: https://github.com/dazuma/exec_service/issues.
+ *  For questions and discussion, please do not file an issue. Instead, use the
+    discussions feature: https://github.com/dazuma/exec_service/discussions.
+ *  Pull requests are welcome, but in general please open an issue first before
+    contributing significant changes.
+
+The library uses [toys](https://dazuma.github.io/toys) for testing and CI. To
+run the test suite, `gem install toys` and then run `toys ci`. You can also run
+unit tests, rubocop, and build tests independently.
+
+## License
+
+Copyright 2026 Daniel Azuma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

data/lib/exec_service/controller.rb

@@ -0,0 +1,359 @@
+# frozen_string_literal: true
+
+class ExecService
+  ##
+  # An object that controls a subprocess. This object is returned from an
+  # execution running in the background, or is yielded to a control block
+  # for an execution running in the foreground.
+  # You can use this object to interact with the subcommand's streams,
+  # send signals to the process, and get its result.
+  #
+  class Controller
+    ##
+    # The subcommand's name.
+    # @return [Object]
+    #
+    attr_reader :name
+
+    ##
+    # The subcommand's standard input stream (which can be written to).
+    #
+    # @return [IO] if the command was configured with `in: :controller`
+    # @return [nil] if the command was not configured with
+    #     `in: :controller`
+    #
+    attr_reader :in
+
+    ##
+    # The subcommand's standard output stream (which can be read from).
+    #
+    # @return [IO] if the command was configured with `out: :controller`
+    # @return [nil] if the command was not configured with
+    #     `out: :controller`
+    #
+    attr_reader :out
+
+    ##
+    # The subcommand's standard error stream (which can be read from).
+    #
+    # @return [IO] if the command was configured with `err: :controller`
+    # @return [nil] if the command was not configured with
+    #     `err: :controller`
+    #
+    attr_reader :err
+
+    ##
+    # The process ID.
+    #
+    # Exactly one of {#exception} and {#pid} will be non-nil.
+    #
+    # @return [Integer] if the process start was successful
+    # @return [nil] if the process could not be started.
+    #
+    attr_reader :pid
+
+    ##
+    # The exception raised when the process failed to start.
+    #
+    # Exactly one of {#exception} and {#pid} will be non-nil.
+    #
+    # @return [Exception] if the process failed to start.
+    # @return [nil] if the process start was successful.
+    #
+    attr_reader :exception
+
+    ##
+    # Captures the remaining data in the given stream.
+    # After calling this, do not read directly from the stream.
+    #
+    # @param which [:out,:err] Which stream to capture
+    #
+    # @return [self] if the stream was captured
+    # @return [nil] if the stream was not captured because the process has
+    #     completed or did not start successfully
+    #
+    def capture(which)
+      @streams_mutex.synchronize do
+        return nil unless @streams_open
+        stream = stream_for(which, allow_in: false)
+        @join_threads << ::Thread.new do
+          data = stream.read
+          @captures_mutex.synchronize do
+            @captures[which] = data
+          end
+        ensure
+          stream.close
+        end
+      end
+      self
+    end
+
+    ##
+    # Captures the remaining data in the standard output stream.
+    # After calling this, do not read directly from the stream.
+    #
+    # @return [self]
+    #
+    def capture_out
+      capture(:out)
+    end
+
+    ##
+    # Captures the remaining data in the standard error stream.
+    # After calling this, do not read directly from the stream.
+    #
+    # @return [self]
+    #
+    def capture_err
+      capture(:err)
+    end
+
+    ##
+    # Redirects the remainder of the given stream.
+    #
+    # You can specify the stream as an IO or IO-like object, or as a file
+    # specified by its path. If specifying a file, you can optionally
+    # provide the mode and permissions for the call to `File#open`. You can
+    # also specify the value `:null` to indicate the null file.
+    #
+    # If the stream is redirected to an IO-like object, it is _not_ closed
+    # when the process is completed. (If it is redirected to a file
+    # specified by path, the file is closed on completion.)
+    #
+    # After calling this, do not interact directly with the stream.
+    #
+    # @param which [:in,:out,:err] Which stream to redirect
+    # @param io [IO,StringIO,String,:null] Where to redirect the stream
+    # @param io_args [Object...] The mode and permissions for opening the
+    #     file, if redirecting to/from a file.
+    #
+    # @return [self] if the stream was redirected
+    # @return [nil] if the stream was not redirected because the process
+    #     has completed or did not start successfully
+    #
+    def redirect(which, io, *io_args)
+      @streams_mutex.synchronize do
+        return nil unless @streams_open
+        io = ::File::NULL if io == :null
+        close_afterward = false
+        if io.is_a?(::String)
+          io_args = which == :in ? ["r"] : ["w"] if io_args.empty?
+          io = ::File.open(io, *io_args)
+          close_afterward = true
+        end
+        stream = stream_for(which, allow_in: true)
+        @join_threads << ::Thread.new do
+          if which == :in
+            ::IO.copy_stream(io, stream)
+          else
+            ::IO.copy_stream(stream, io)
+          end
+        ensure
+          stream.close
+          io.close if close_afterward
+        end
+      end
+      self
+    end
+
+    ##
+    # Redirects the remainder of the standard input stream.
+    #
+    # You can specify the stream as an IO or IO-like object, or as a file
+    # specified by its path. If specifying a file, you can optionally
+    # provide the mode and permissions for the call to `File#open`. You can
+    # also specify the value `:null` to indicate the null file.
+    #
+    # After calling this, do not interact directly with the stream.
+    #
+    # @param io [IO,StringIO,String,:null] Where to redirect the stream
+    # @param io_args [Object...] The mode and permissions for opening the
+    #     file, if redirecting from a file.
+    #
+    # @return [self] if the stream was redirected
+    # @return [nil] if the stream was not redirected because the process
+    #     has completed or did not start successfully
+    #
+    def redirect_in(io, *io_args)
+      redirect(:in, io, *io_args)
+    end
+
+    ##
+    # Redirects the remainder of the standard output stream.
+    #
+    # You can specify the stream as an IO or IO-like object, or as a file
+    # specified by its path. If specifying a file, you can optionally
+    # provide the mode and permissions for the call to `File#open`. You can
+    # also specify the value `:null` to indicate the null file.
+    #
+    # After calling this, do not interact directly with the stream.
+    #
+    # @param io [IO,StringIO,String,:null] Where to redirect the stream
+    # @param io_args [Object...] The mode and permissions for opening the
+    #     file, if redirecting to a file.
+    #
+    # @return [self] if the stream was redirected
+    # @return [nil] if the stream was not redirected because the process
+    #     has completed or did not start successfully
+    #
+    def redirect_out(io, *io_args)
+      redirect(:out, io, *io_args)
+    end
+
+    ##
+    # Redirects the remainder of the standard error stream.
+    #
+    # You can specify the stream as an IO or IO-like object, or as a file
+    # specified by its path. If specifying a file, you can optionally
+    # provide the mode and permissions for the call to `File#open`. You can
+    # also specify the value `:null` to indicate the null file.
+    #
+    # After calling this, do not interact directly with the stream.
+    #
+    # @param io [IO,StringIO,String,:null] Where to redirect the stream
+    # @param io_args [Object...] The mode and permissions for opening the
+    #     file, if redirecting to a file.
+    #
+    # @return [self] if the stream was redirected
+    # @return [nil] if the stream was not redirected because the process
+    #     has completed or did not start successfully
+    #
+    def redirect_err(io, *io_args)
+      redirect(:err, io, *io_args)
+    end
+
+    ##
+    # Send the given signal to the process. The signal can be specified
+    # by name or number.
+    #
+    # @param sig [Integer,String] The signal to send.
+    # @return [self]
+    #
+    def kill(sig)
+      ::Process.kill(sig, pid) if pid
+      self
+    end
+    alias signal kill
+
+    ##
+    # Determine whether the subcommand is still executing
+    #
+    # @return [boolean]
+    #
+    def executing?
+      @completion_thread&.status ? true : false
+    end
+
+    ##
+    # Wait for the subcommand to complete, and return a result object.
+    #
+    # @param timeout [Numeric,nil] The timeout in seconds, or `nil` to
+    #     wait indefinitely.
+    # @return [ExecService::Result] The result object
+    # @return [nil] if a timeout occurred.
+    #
+    def result(timeout: nil)
+      return nil if @completion_thread && !@completion_thread.join(timeout)
+      # @completion_thread sets @result, so the final value is guaranteed
+      # to be stable once the thread has joined above.
+      @result
+    end
+
+    ##
+    # @private
+    #
+    def initialize(name:, controller_streams:, captures:, pid_or_exception:,
+                   join_threads:, background_callback:, captures_mutex:)
+      @name = name
+      @in = controller_streams[:in]
+      @out = controller_streams[:out]
+      @err = controller_streams[:err]
+      @captures = captures
+      @join_threads = join_threads
+      @background_callback = background_callback
+      @captures_mutex = captures_mutex
+      @streams_open = false
+      @streams_mutex = ::Mutex.new
+      @pid = @exception = @completion_thread = @result = nil
+      case pid_or_exception
+      when ::Integer
+        @pid = pid_or_exception
+        @streams_open = true
+        @completion_thread = ::Thread.new do
+          _pid, status = ::Process.wait2(@pid)
+          cleanup(status)
+        end
+      when ::Exception
+        @exception = pid_or_exception
+        cleanup(nil)
+      end
+    end
+
+    ##
+    # Close the controller's input stream, if any.
+    #
+    # @private
+    #
+    def close_in_stream
+      @streams_mutex.synchronize do
+        @in&.close
+      end
+      self
+    end
+
+    ##
+    # Close the controller's output streams, if any.
+    #
+    # @private
+    #
+    def close_out_streams
+      @streams_mutex.synchronize do
+        @out&.close
+        @err&.close
+      end
+      self
+    end
+
+    private
+
+    ##
+    # Cleanup after the child process ends.
+    # Blocks any further captures/redirects, joins all stream processing
+    # threads, and sets the result. Also kicks off the callback if run in
+    # the background.
+    #
+    def cleanup(status)
+      @streams_mutex.synchronize do
+        @streams_open = false
+      end
+      @join_threads.each(&:join)
+      @result = Result.new(@name, @captures[:out], @captures[:err], status, @exception)
+      if @background_callback
+        ::Thread.new do
+          @background_callback.call(@result)
+        end
+      end
+    end
+
+    def stream_for(which, allow_in: false)
+      stream = nil
+      case which
+      when :out
+        stream = @out
+        @out = nil
+      when :err
+        stream = @err
+        @err = nil
+      when :in
+        if allow_in
+          stream = @in
+          @in = nil
+        end
+      else
+        raise ::ArgumentError, "Unknown stream #{which}"
+      end
+      raise ::ArgumentError, "Stream #{which} not available" unless stream
+      stream
+    end
+  end
+end