sproc 0.2.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b21c852197676569f95bf84f37a1e2d070a06ee5fb1bbe1b627e2eb9f83500da
-  data.tar.gz: 3f8fe794b2afcb54d50af93e774091ef1fd72e27c221eb2f38a82686ec214f89
+  metadata.gz: a736ea3eebf9855455803021aa1dd57589e1784f92f841f63984d64c1bb5cce2
+  data.tar.gz: 0ead0dc9e4609cb8adc976dd743f427bbe9d8ee9be39d78b6ab743804b0c13d8
 SHA512:
-  metadata.gz: e76140b5a74de9977e60a657ce8c40ad5cf070f3b8c856f954d87ecda0b2cc61a601016b8c8beafd6dd5840dc6dd4cac81eb44b85a3c811fbb38612ea97b0236
-  data.tar.gz: e8999dfdf2a0aa3f577d9c3ed49184989595ac545088b506befcea989782f502c8776fbb851746d696679a2dd84453ef8ebce732e69c53346283c01e024e9fd6
+  metadata.gz: ee15b0602c7b22c813a47aca5c0c3a824624ad0794145aaa9382763e6f6ce54eaf5418fe0df9b2974c7c1945609c74d8f6f32630bc987e10eaa5bed137a8fffb
+  data.tar.gz: ac59da1176212f4d34b9100ba6353bb81923a059fbd7229c91622386e320e1a96514319deacf920ad3b0347796e6adf15f856422d987fb63bdd29935e2fb9dc3

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sproc (0.1.0)
+    sproc (0.3.0)
 
 GEM
   remote: https://rubygems.org/

data/lib/sproc.rb

@@ -2,6 +2,7 @@
 
 require_relative "sproc/version"
 require_relative "sproc/core"
+require_relative "sproc/osinfo"
 
 module SProc
   class Error < StandardError; end

data/lib/sproc/core.rb

@@ -7,17 +7,16 @@ module SProc
   # Defines the shell under which to invoke the sub-process
   module ShellType
     SHELL_TYPES = [
-      # Use the default shell for the platform we're on.
-      # - For Windows, it seems to be the 'cmd prompt'
-      # - For current ubuntu, it seems to be 'dash'
-      NATIVE = 0, 
+      # Start the process without any shell
+      NONE = 0,
       # Will create a 'bash' instance and run the subprocess
       # within that instance.
       BASH = 1
     ].freeze
   end
 
-  # The possible states of this subprocess
+  # The available execution states of a the subprocess
+  # running within an SProc instance.
   module ExecutionState
     NOT_STARTED = 0
     RUNNING = 1
@@ -58,10 +57,13 @@ module SProc
     #                        from the process as it is running (default nil)
     # @param stderr_callback a callback that will receive all stderr output
     #                        from the process as it is running (default nil)
+    # @param env             a hash containing key/value pairs of strings that
+    #                        set the environment variable 'key' to 'value'. If value
+    #                        is nil, that env variable is unset
     #
     # example callback signature: def my_stdout_cb(line)
-    def initialize(type = ShellType::NATIVE, stdout_callback = nil,
-                   stderr_callback = nil)
+    def initialize(type: ShellType::NONE, stdout_callback: nil,
+                   stderr_callback: nil, env: {})
       @run_opts = {
         type: type,
         stdout_callback: stdout_callback,
@@ -69,10 +71,50 @@ module SProc
       }
       @runner = TaskRunner.new(@run_opts)
       @execution_thread = nil
+      @env = env
+    end
+
+    # Start the sub-process and block until it has completed.
+    #
+    #
+    # @cmd    the command to execute
+    # @args   an array with all arguments to the cmd
+    # @opts   a hash with options that influence the spawned process
+    #         the supported options are: chdir umask unsetenv_others
+    #         See Process.spawn for definitions
+    #
+    # @return this SubProcess instance
+    def exec_sync(cmd, *args, **opts)
+      exec(true, @env, cmd, *args, **opts)
+    end
+
+    # Start the process non-blocking. Use one of the wait... methods
+    # to later block on the process.
+    # @return this SubProcess instance
+    def exec_async(cmd, *args, **opts)
+      exec(false, @env, cmd, *args, **opts)
+    end
+
+    # check if this process has completed with exit code 0
+    # (success) or not
+    def exit_zero?
+      return false unless execution_state == ExecutionState::COMPLETED
+
+      task_info[:process_status].exitstatus.zero?
+    end
+
+    # Block caller until this subprocess has completed or aborted
+    # @return the TaskInfo struct of the completed process
+    def wait_on_completion
+      return if @execution_thread.nil?
+
+      @execution_thread.join
+      task_info
     end
 
     # Return the execution state of this SubProcess. Note that it is not
     # identical with the life-cycle of the underlying ProcessStatus object
+    #
     # @return current ExecutionState
     def execution_state
       return ExecutionState::NOT_STARTED if @execution_thread.nil?
@@ -106,35 +148,10 @@ module SProc
       raise RuntimeError("Unhandled process status: #{status.inspect}")
     end
 
-    # Start the process non-blocking. Use one of the wait... methods
-    # to later block on the process.
-    # @return this SubProcess instance
-    def exec_sync(cmd, *args, **opts)
-      exec(true, cmd, *args, **opts)
-    end
-
-    # Start the process non-blocking. Use one of the wait... methods
-    # to later block on the process.
-    # @return this SubProcess instance
-    def exec_async(cmd, *args, **opts)
-      exec(false, cmd, *args, **opts)
-    end
-
-    # check if this process has completed with exit code 0
-    # (success) or not
-    def exit_zero?
-      return false unless execution_state == ExecutionState::COMPLETED
-
-      task_info[:process_status].exitstatus.zero?
-    end
-
-    # Block caller until this subprocess has completed or aborted
-    # @return the TaskInfo struct of the completed process
-    def wait_on_completion
-      return if @execution_thread.nil?
-
-      @execution_thread.join
-      task_info
+    # @return the TaskInfo representing this SubProcess, nil if
+    #         process has not started
+    def task_info
+      @runner.task_info
     end
 
     # blocks until all processes in the given array are completed/aborted.
@@ -170,7 +187,7 @@ module SProc
     # # start 3 processes asyncronously
     # nof_processes = 3
     # p_array = (1..nof_processes).collect do
-    #   SubProcess.new(SubProcess::NATIVE).exec_async('ping', ['127.0.0.1'])
+    #   SubProcess.new(SubProcess::NONE).exec_async('ping', ['127.0.0.1'])
     # end
     #
     # # block until a process completes and then immediately start a new process
@@ -201,12 +218,6 @@ module SProc
       all_proc
     end
 
-    # @return the TaskInfo representing this SubProcess, nil if
-    #         process has not started
-    def task_info
-      @runner.task_info
-    end
-
     # return processes that are no longer running
     def self.get_finished(running_proc)
       running_proc.select do |p|
@@ -218,13 +229,15 @@ module SProc
 
     private
 
-    def exec(synch, cmd, *args, **opts)
-      raise RuntimeError,"Subprocess already running!" unless @execution_thread.nil? || !@execution_thread.alive?
+    # a helper method that supports both synch/async execution
+    # depending on the supplied args
+    def exec(synch, env, cmd, *args, **opts)
+      raise 'Subprocess already running!' unless @execution_thread.nil? || !@execution_thread.alive?
 
       # kick-off a fresh task runner and execution thread
       @runner = TaskRunner.new(@run_opts)
       @execution_thread = Thread.new do
-        @runner.execute(cmd, *args, **opts)
+        @runner.execute(env, cmd, *args, **opts)
       end
       @execution_thread.join if synch
       self
@@ -238,8 +251,11 @@ module SProc
 
       include ShellType
 
+      # Restrict the options to Process.spawn that we support to these
+      SUPPORTED_SPAWN_OPTS = %i[chdir umask unsetenv_others]
+
       DEFAULT_OPTS = {
-        type: NATIVE,
+        type: NONE,
         stdout_callback: nil,
         stderr_callback: nil
       }.freeze
@@ -250,12 +266,12 @@ module SProc
       end
 
       # Runs the process and blocks until it is completed or aborted.
-      # The stdout and stdin streams are continuously read in parallal with
+      # The stdout and stdin streams are continuously read in parallel with
       # the process execution.
-      def execute(cmd, *args, **opts)
+      def execute(env, cmd, *args, **opts)
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         begin
-          shell_out_via_popen(cmd, *args, **opts)
+          shell_out_via_popen(env, cmd, *args, **opts)
         rescue StandardError => e
           @task_info[:exception] = e
         end
@@ -266,14 +282,26 @@ module SProc
 
       private
 
-      def shell_out_via_popen(cmd, *args, **opts)
+      def valid_opts(**opts)
+        return opts if opts.nil? || opts.empty?
+
+        supported = {}
+        SUPPORTED_SPAWN_OPTS.each { |o| supported[o] = opts[o] if opts.has_key?(o) }
+        supported
+      end
+
+      def shell_out_via_popen(env, cmd, *args, **opts)
+        opts = valid_opts(**opts)
         args = case @opts[:type]
-               when NATIVE then get_args_native(cmd, *args, **opts)
-               when BASH   then get_args_bash(cmd, *args, **opts)
+               when NONE then get_args_native(cmd, *args, **opts)
+               when BASH then get_args_bash(cmd, *args, **opts)
                else raise ArgumentError, "Unknown task type: #{@type}!!"
                end
+
         SProc.logger&.debug { "Start: #{task_info[:cmd_str]}" }
-        Open3.popen3(*args) do |stdin, stdout, stderr, thread|
+        SProc.logger&.debug { "Supplying env: #{env}" } unless env.nil?
+        SProc.logger&.debug { "Spawn options: #{opts}" } unless opts.nil?
+        Open3.popen3(env, *args) do |stdin, stdout, stderr, thread|
           @task_info[:popen_thread] = thread
           threads = do_while_process_running(stdin, stdout, stderr)
           @task_info[:process_status] = thread.value
@@ -306,16 +334,14 @@ module SProc
       def process_output_stream(stream, stream_cache = nil,
                                 process_callback = nil)
         Thread.new do
-          begin
-            until (raw_line = stream.gets).nil?
-              process_callback&.call(raw_line)
-              stream_cache << raw_line unless stream_cache.nil?
-            end
-          rescue IOError => e
-            l = SProc.logger
-            l&.warn { 'Stream closed before all output were read!' }
-            l&.warn { e.message }
+          until (raw_line = stream.gets).nil?
+            process_callback&.call(raw_line)
+            stream_cache << raw_line unless stream_cache.nil?
           end
+        rescue IOError => e
+          l = SProc.logger
+          l&.warn { 'Stream closed before all output were read!' }
+          l&.warn { e.message }
         end
       end
     end

data/lib/sproc/osinfo.rb

@@ -0,0 +1,55 @@
+require 'rbconfig'
+
+# helper methods to find out os and execution environment
+module SProc
+  module OSInfo
+    # the supported exec environments
+    module OS
+      WINDOWS = 0
+      LINUX = 1
+      MINGW = 2
+      CYGWIN = 3
+      OSX = 4
+      BSD = 5
+      UNKNOWN = 100
+    end
+
+    # returns the current execution environment
+    def self.os_context
+      case RbConfig::CONFIG['host_os']
+      when /mswin/ then OS::WINDOWS
+      when /mingw/ then OS::MINGW
+      when /cygwin/ then OS::CYGWIN
+      when /darwin/ then OS::OSX
+      when /linux/ then OS::LINUX
+      when /bsd/ then OS::BSD
+      else OS::UNKNOWN
+      end
+    end
+
+    # return the current underlying operating system
+    def self.host_os
+      if [OS::WINDOWS, OS::MINGW, OS::CYGWIN].include?(os_context)
+        OS::WINDOWS
+      else
+        os_context
+      end
+    end
+
+    def on_windows?
+      host_os == OS::WINDOWS
+    end
+
+    def on_linux?
+      os_context == OS::LINUX
+    end
+
+    def on_bsd?
+      os_context == OS::BSD
+    end
+
+    def on_osx?
+      os_context == OS::OSX
+    end
+  end
+end

data/lib/sproc/reporting.rb

@@ -0,0 +1,196 @@
+require_relative 'core'
+
+# This module is written to provide sub-process
+# execution with some human readable logging of process start/stop/errors
+#
+# It wraps SProc instances and execution with calls to logging methods
+# that tries to make the resulting log user friendly
+module SProc
+  module Reporting
+    class << self
+      attr_accessor :logger
+    end
+
+    def logger
+      Reporting.logger
+    end
+
+    # Run a process synchronuously via the native shell and log
+    # output suitable for a build log
+    #
+    # @param cmd_name   a String containing a descriptive
+    #                        name for what the process will do.
+    # @param cmd, args, opts see SProc.exec_sync
+    #
+    # @return                the SProc instance containing the completed process
+    def report_sync(cmd_name, cmd, *args, **opts)
+      p = create_proc_and_log(cmd_name,
+                              ShellType::NONE, :exec_sync,
+                              cmd, args, opts)
+      report_completed(p)
+      p
+    end
+
+    # Run a process asynchronuously via the native shell and log
+    # output suitable for a build log
+    #
+    # @param cmd_name   a String containing a descriptive
+    #                        name for what the process will do.
+    # @param cmd, args, opts see SProc.exec_sync
+    #
+    # @return                the created SProc instance
+    def report_async(cmd_name, cmd, *args, **opts)
+      create_proc_and_log(cmd_name,
+                          ShellType::NONE, :exec_async,
+                          cmd, args, opts)
+    end
+
+    # Run a process asynchronuously via the Bash shell and log
+    # output suitable for a build log
+    #
+    # @param cmd_name   a String containing a descriptive
+    #                        name for what the process will do.
+    # @param cmd, args, opts see SProc.exec_sync
+    #
+    # @return                the created SProc instance
+    def report_async_within_bash(cmd_name, cmd, *args, **opts)
+      create_proc_and_log(cmd_name,
+                          ShellType::BASH, :exec_async,
+                          cmd, args, opts)
+    end
+
+    # Log output from a completed/aborted process
+    #
+    # @param process   the SProc instance that has run
+    # @return          true/false corresponding to process success
+    def report_completed(process)
+      friendly_name = if @log_friendly_name_map&.key?(process)
+                  "#{@log_friendly_name_map[process]}"
+                else
+                  process.task_info[:cmd_str][0,10] + "..."
+                end
+      started_ok = true
+      case process.execution_state
+      when ExecutionState::COMPLETED
+        process.exit_zero? && log_completed_ok(friendly_name, process.task_info)
+        !process.exit_zero? && log_completed_err(friendly_name, process.task_info)
+      when ExecutionState::ABORTED
+        log_aborted(friendly_name, process.task_info)
+        started_ok = false
+      when ExecutionState::FAILED_TO_START
+        log_failed_start(friendly_name, process.task_info)
+        started_ok = false
+      else
+        log_unexpected(friendly_name, process.task_info)
+      end
+      started_ok && process.exit_zero?
+    end
+
+    private
+
+    def create_proc_and_log(cmd_name, type, method, cmd, args, opts)
+      log_start(cmd_name, type, method, cmd, args, **opts)
+      p = SProc.new(type: type).send(method, cmd, args, **opts)
+      @log_friendly_name_map ||= {}
+      @log_friendly_name_map[p] = cmd_name
+      p
+    end
+
+    def log_method_result_ok(friendly_name, delta)
+      logger.info do
+        "#{friendly_name} completed successfully after #{delta.round(3)}s"
+      end
+    end
+
+    def log_method_result_error(friendly_name_method, delta, exc)
+      logger.error do
+        "#{friendly_name_method} aborted by #{exc.class} after #{delta.round(3)}s\n"\
+        "Exception info: #{exc.message}"
+      end
+
+      logger.debug do
+        exc.backtrace.to_s
+      end
+    end
+
+    def log_start(cmd_name, type, method, cmd, *args, **opts)
+      logger.info do
+        async_str = method == :exec_async ? 'asynchronuously' : 'synchronuously'
+        type_str = type == ShellType::NONE ? 'without shell' : 'within the bash shell'
+        "'#{cmd_name}' executing #{async_str} #{type_str}..."
+      end
+      logger.debug do
+        msg = String.new("Starting #{cmd}")
+        msg << " with args: #{args.flatten.inspect}" unless args.nil? || args.empty?
+        msg << " and opts: #{opts.inspect}" unless opts.nil? || opts.empty?
+        msg
+      end
+    end
+
+    def log_one_dll(regex, cmd_str, time)
+      m = regex.match(cmd_str)
+      s = m.nil? ? cmd_str : m[1]
+      max = 45
+      s = s.length > max ? s.slice(0..max - 1) : s.ljust(max)
+      logger.info { "#{s} took #{time.round(3)}s." }
+    end
+
+    def log_aborted(friendly_name, p_info)
+      logger.error do
+        "'#{friendly_name}' aborted!\n"\
+        "When running: #{p_info[:cmd_str]}\n"\
+        "#{merge_proc_output(p_info)}"\
+        "#{p_info[:process_status] unless p_info[:process_status].nil?}"
+      end
+    end
+
+    def log_failed_start(friendly_name, p_info)
+      logger.error do
+        "'#{friendly_name}' not run!\n"\
+        "Could not start process using: #{p_info[:cmd_str]}\n"\
+        "#{merge_proc_output(p_info)}"
+      end
+    end
+
+    def log_completed_ok(friendly_name, p_info)
+      logger.info do
+        "'#{friendly_name}' completed successfully after #{p_info[:wall_time].round(3)}s"
+      end
+      logger.debug do
+        "Cmd: #{p_info[:cmd_str]}"
+      end
+    end
+
+    def log_completed_err(friendly_name, p_info)
+      logger.error do
+        "'#{friendly_name}' completed with exit code "\
+        "#{p_info[:process_status].exitstatus}\n"\
+        "When running: #{p_info[:cmd_str]}\n"\
+        "after #{p_info[:wall_time].round(3)}s\n"\
+        "#{merge_proc_output(p_info)}"
+      end
+    end
+
+    def log_unexpected(friendly_name, p_info)
+      logger.error do
+        "'#{friendly_name}' caused unexpected error!"\
+        ' Trying to display info on a running process'\
+        "(#{p_info[:cmd_str]})"
+      end
+    end
+
+    # @return String with sections for each non-empty output stream
+    #                and exception messages
+    def merge_proc_output(p_info)
+      inf_str = %i[stdout stderr].collect do |sym|
+        next('') if p_info[sym].empty?
+
+        "--- #{sym} ---\n#{p_info[sym]}"
+      end.join("\n")
+
+      exc = p_info[:exception]
+      inf_str << "--- exception ---\n#{exc}\n" unless exc.nil?
+      inf_str
+    end
+  end
+end

data/lib/sproc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SProc
-  VERSION = "0.2.0"
+  VERSION = "0.6.0"
 end

data/sproc.gemspec

@@ -1,39 +1,40 @@
 # frozen_string_literal: true
 
-require_relative "lib/sproc/version"
+require_relative 'lib/sproc/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "sproc"
+  spec.name          = 'sproc'
   spec.version       = SProc::VERSION
-  spec.authors       = ["Anders Rillbert"]
-  spec.email         = ["anders.rillbert@kutso.se"]
+  spec.authors       = ['Anders Rillbert']
+  spec.email         = ['anders.rillbert@kutso.se']
 
-  spec.summary       = "Run subprocess asynch/synch."
-  spec.description   = "Run subprocess asynch/synch."
-  spec.homepage      = "https://github.com/rillbert/sproc"
-  spec.license       = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.7.0")
+  spec.summary       = 'Spawn commands as asynch/synch subprocesses.'
+  spec.description   = 'Easier invokation of asynch/synch commands with '\
+                       'a reasonable easy and flexible interface for processing stdout and stderr'
+  spec.homepage      = 'https://github.com/rillbert/sproc'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.7.0')
 
-  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
 
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = spec.homepage
-  spec.metadata["changelog_uri"] = spec.homepage
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = spec.homepage
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
   end
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
   # Developer dependencies
-  spec.add_development_dependency "minitest", "~> 5.1"
+  spec.add_development_dependency 'minitest', '~> 5.1'
 
   # Uncomment to register a new dependency of your gem
-#  spec.add_dependency "example-gem", "~> 1.0"
+  #  spec.add_dependency "example-gem", "~> 1.0"
 
   # For more information and examples about making a new gem, checkout our
   # guide at: https://bundler.io/guides/creating_gem.html

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sproc
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Anders Rillbert
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-02-19 00:00:00.000000000 Z
+date: 2021-03-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -24,7 +24,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.1'
-description: Run subprocess asynch/synch.
+description: Easier invokation of asynch/synch commands with a reasonable easy and
+  flexible interface for processing stdout and stderr
 email:
 - anders.rillbert@kutso.se
 executables: []
@@ -42,7 +43,8 @@ files:
 - bin/setup
 - lib/sproc.rb
 - lib/sproc/core.rb
-- lib/sproc/utils.rb
+- lib/sproc/osinfo.rb
+- lib/sproc/reporting.rb
 - lib/sproc/version.rb
 - sproc.gemspec
 homepage: https://github.com/rillbert/sproc
@@ -71,5 +73,5 @@ requirements: []
 rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
-summary: Run subprocess asynch/synch.
+summary: Spawn commands as asynch/synch subprocesses.
 test_files: []

data/lib/sproc/utils.rb

@@ -1,53 +0,0 @@
-require 'rbconfig'
-
-# utility to find out info about our execution environment
-module OSInfo
-  # the supported exec environments
-  module OS
-    WINDOWS = 0
-    LINUX = 1
-    MINGW = 2
-    CYGWIN = 3
-    OSX = 4
-    BSD = 5
-    UNKNOWN = 100
-  end
-
-  # returns the current execution environment
-  def self.os_context
-    case RbConfig::CONFIG['host_os']
-    when /mswin/ then OS::WINDOWS
-    when /mingw/ then OS::MINGW
-    when /cygwin/ then OS::CYGWIN
-    when /darwin/ then OS::OSX
-    when /linux/ then OS::LINUX
-    when /bsd/ then OS::BSD
-    else OS::UNKNOWN
-    end
-  end
-
-  # return the current underlying operating system
-  def self.host_os
-    if [OS::WINDOWS, OS::MINGW, OS::CYGWIN].include?(os_context)
-      OS::WINDOWS
-    else
-      os_context
-    end
-  end
-
-  def on_windows?
-    host_os == OS::WINDOWS
-  end
-
-  def on_linux?
-    os_context == OS::LINUX
-  end
-
-  def on_bsd?
-    os_context == OS::BSD
-  end
-
-  def on_osx?
-    os_context == OS::OSX
-  end
-end