process-helper 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 431e13e66be2c781ee2d2e0d8206870561def2f5
+  data.tar.gz: 5aee51f7852b3f5d9761efb0e21eea406aba6750
+SHA512:
+  metadata.gz: 6c5db494b6bbb22a99e13f0062d6874275c937a7475471f76fcdec2116c7f6b6dda355a1c63d885534f5e69ff05e69c55f87ff80468dbae3a2c3ef5adc251048
+  data.tar.gz: f2e2a59c501eb7bbfe687a35be7c413b25fa54c8874ef200dfd0496104247bd46068b4d7d8095f2715346b037dd3a6b2b0ae0c0c55bcf764e2afa1f4d4ac7cdb

data/lib/process-helper.rb

@@ -0,0 +1,163 @@
+# rubocop:disable Style/FileName
+require 'English'
+
+module ProcessHelper
+  class ProcessHelper
+    attr_reader :pid, :exit_status
+
+    # opts can contain:
+    # :print_lines:: echo the STDOUT and STDERR of the process to STDOUT as well as capturing them.
+    # :poll_rate:: rate, in seconds (default is 0.25) to poll the capturered output for matching lines.
+    def initialize(opts = {})
+      @opts =
+        {
+          :print_lines => false
+        }.merge!(opts)
+    end
+
+    # Starts a process defined by `command_and_args`
+    # command_and_args:: Array with the first element as the process to start, the rest being the parameters to the new process.
+    # output_to_wait_for:: Regex containing expected output, +start+ will block until a line of STDOUT matches this regex, if this is nil, then no waiting occurs.
+    # wait_timeout:: Timeout while waiting for particular output.
+    # env:: Hash of extra environment variables with which to start the process.
+    def start(command_and_args = [], output_to_wait_for = nil, wait_timeout = nil, env = {})
+      out_r, out_w = IO.pipe
+      err_r, err_w = IO.pipe
+      @pid = spawn(env, *command_and_args, :out => out_w, :err => err_w)
+      out_w.close
+      err_w.close
+
+      log = []
+
+      @out_log = ProcessLog.new(out_r, @opts, log).start
+      @err_log = ProcessLog.new(err_r, @opts).start
+
+      @out_log.wait_for_output(output_to_wait_for, :timeout => wait_timeout) if output_to_wait_for
+    end
+
+    # returns true if the process exited with an exit code of 0.
+    def wait_for_exit
+      @out_log.wait
+      @err_log.wait
+
+      Process.wait @pid
+      @exit_status = $CHILD_STATUS
+
+      @pid = nil
+      @exit_status == 0
+    end
+
+    # Send the specified signal to the wrapped process.
+    def kill(signal = 'TERM')
+      Process.kill(signal, @pid)
+    end
+
+    # Gets an array containing all the lines for the specified output stream.
+    # +which+ can be either of:
+    # * +:out+
+    # * +:err+
+    def get_log(which)
+      _get_log(which).to_a
+    end
+
+    # Gets an array containing all the lines for the specified stream, emptying the stored buffer.
+    # +which+ can be either of:
+    # * +:out+
+    # * +:err+
+    def get_log!(which)
+      _get_log(which).drain
+    end
+
+    # Blocks the current thread until the specified regex has been matched in the output.
+    # +which+ can be either of:
+    # * +:out+
+    # * +:err+
+    # opts can contain:
+    # :timeout:: timeout in seconds to wait for the specified output.
+    # :poll_rate:: rate, in seconds (default is 0.25) to poll the capturered output for matching lines.
+    def wait_for_output(which, regexp, opts = {})
+      _get_log(which).wait_for_output(regexp, opts)
+    end
+
+    private
+
+    def _get_log(which)
+      case which
+      when :out
+        @out_log
+      when :err
+        @err_log
+      else
+        fail "Unknown log '#{which}'"
+      end
+    end
+  end
+
+  class ProcessLog
+    def initialize(io, opts, prefill = [])
+      @io = io
+      @lines = prefill.dup
+      @mutex = Mutex.new
+      @opts = opts
+    end
+
+    def start
+      @thread = Thread.new do
+        @io.each_line do |l|
+          l = TimestampedString.new(l)
+          STDOUT.puts l if @opts[:print_lines]
+          @mutex.synchronize { @lines.push l }
+        end
+      end
+      self
+    end
+
+    def wait_for_output(regex, opts = {})
+      opts = { :poll_rate => 0.25 }.merge(opts)
+      opts[:timeout] ||= 30
+      cutoff = DateTime.now + Rational(opts[:timeout].to_i, 86_400)
+      until _any_line_matches(regex)
+        sleep(opts[:poll_rate])
+        fail "Timeout of #{opts[:timeout]} seconds exceeded while waiting for output that matches '#{regex}'" if DateTime.now > cutoff
+      end
+    end
+
+    def wait
+      @thread.join
+      @thread = nil
+      self
+    end
+
+    def to_a
+      @mutex.synchronize { @lines.dup }
+    end
+
+    def drain
+      @mutex.synchronize do
+        r = @lines.dup
+        @lines.clear
+        r
+      end
+    end
+
+    def to_s
+      @mutex.synchronize { @lines.join '' }
+    end
+
+    private
+
+    def _any_line_matches(regex)
+      to_a.any? { |line| line.match(regex) }
+    end
+  end
+
+  class TimestampedString < String
+    attr_reader :time
+
+    def initialize(string, time = nil)
+      time ||= Time.now
+      super(string)
+      @time = time
+    end
+  end
+end

data/spec/process_helper_spec.rb

@@ -0,0 +1,147 @@
+require 'spec_helper'
+
+module ProcessHelper
+  describe ProcessHelper do
+    context 'Things...' do
+      it 'It should start a process and capture the exit status (success)' do
+        process = ProcessHelper.new
+        process.start('true')
+        expect(process.wait_for_exit).to eq(true)
+        expect(process.exit_status).to eq(0)
+      end
+
+      it 'It should start a process and capture the exit status (failure)' do
+        process = ProcessHelper.new
+        process.start('false')
+        expect(process.wait_for_exit).to eq(false)
+        expect(process.exit_status).to eq(1 << 8)
+      end
+
+      it 'It should pass arguments' do
+        process = ProcessHelper.new
+        process.start(['sh', '-c', 'exit 4'])
+        expect(process.wait_for_exit).to eq(false)
+        expect(process.exit_status).to eq(4 << 8)
+      end
+
+      it 'It capture the exit status (signal)' do
+        process = ProcessHelper.new
+        process.start(%w(sleep 10))
+        process.kill
+        expect(process.wait_for_exit).to eq(false)
+        expect(Signal.signame(process.exit_status.to_i)).to eq('TERM')
+      end
+
+      it 'It should expose stdout' do
+        process = ProcessHelper.new
+        process.start(['sh', '-c', 'echo hello ; echo there'])
+        process.wait_for_exit
+        out = process.get_log(:out)
+        expect(out.count).to eq(2)
+        expect(out[0]).to eq("hello\n")
+        expect(out[1]).to eq("there\n")
+      end
+
+      it 'It should expose stderr' do
+        process = ProcessHelper.new
+        process.start(['sh', '-c', 'echo hello >&2; echo there >&2'])
+        process.wait_for_exit
+        err = process.get_log(:err)
+        expect(err.count).to eq(2)
+        expect(err[0]).to eq("hello\n")
+        expect(err[1]).to eq("there\n")
+      end
+
+      it 'It should expose the pid' do
+        process = ProcessHelper.new
+        process.start(['sh', '-c', 'echo this is process $$'])
+        pid = process.pid
+        process.wait_for_exit
+        out = process.get_log(:out)
+        expect(out[0]).to eq("this is process #{pid}\n")
+      end
+
+      it 'It should timestamp the logs' do
+        t0 = Time.now
+        process = ProcessHelper.new
+        process.start(['sh', '-c', 'echo a ; sleep 1 ; echo b ; sleep 1 ; echo c'])
+        process.wait_for_exit
+        t1 = Time.now
+
+        out = process.get_log(:out)
+        expect(out[0].time).to be >= t0
+        # For some reason my attempts to use be_within failed...
+        expect(out[1].time).to be > out[0].time - 1.1
+        expect(out[1].time).to be < out[0].time + 1.1
+        expect(out[2].time).to be > out[1].time - 1.1
+        expect(out[2].time).to be < out[1].time + 1.1
+        expect(t1).to be >= out[2].time
+
+        expect(out.join('')).to eq("a\nb\nc\n")
+      end
+
+      it 'It should wait for a pattern in stdout' do
+        t0 = Time.now
+        process = ProcessHelper.new
+        process.start(
+          ['sh', '-c', 'echo frog >&2 ; sleep 1 ; echo cat ; sleep 1 ; echo dog ; sleep 1 ; echo frog'],
+          /fro/
+        )
+        t1 = Time.now
+
+        expect(t1).to be > (t0 + 3)
+        expect(t1).to be < (t0 + 5)
+
+        startup_log = process.get_log(:out)
+        expect(startup_log.size).to eq(3)
+        expect(startup_log[-1]).to eq("frog\n")
+      end
+
+      it 'It should be able to arbitrarly wait for output' do
+        t0 = Time.now
+        process = ProcessHelper.new
+        process.start(
+          ['sh', '-c', 'echo frog >&2 ; sleep 1 ; echo cat ; sleep 1 ; echo dog ; sleep 1 ; echo frog; sleep 3; echo goat'],
+          /fro/
+        )
+        t1 = Time.now
+
+        expect(t1).to be > t0 + 3
+        expect(t1).to be < t0 + 5
+
+        process.wait_for_output(:out, /goat/)
+        t2 = Time.now
+        expect(t2).to be > t0 + 6
+        expect(t2).to be < t0 + 8
+      end
+
+      it 'It should support draining the logs' do
+        process = ProcessHelper.new
+        process.start(
+          ['bash', '-c', 'for ((i=0; $i<10; i=$i+1)) ; do echo out $i ; echo err $i >&2 ; sleep 1 ; done']
+        )
+
+        sleep 3
+        out = process.get_log! :out
+        err = process.get_log! :err
+        expect(out.size).to be > 1
+        expect(err.size).to be > 1
+
+        process.wait_for_exit
+        out2 = process.get_log :out
+        err2 = process.get_log :err
+
+        expect((out + out2).size).to eq(10)
+        expect((err + err2).size).to eq(10)
+
+        out3 = process.get_log! :out
+        err3 = process.get_log! :err
+        expect(out3).to eq(out2)
+        expect(err3).to eq(err2)
+
+        expect(process.get_log(:out).size).to eq(0)
+        expect(process.get_log(:err).size).to eq(0)
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require_relative '../lib/process-helper'

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: process-helper
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- alex hutter
+- andrew wheat
+- tristan hill
+- robert shield
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-06-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Utility for managing sub processes.
+email: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/process-helper.rb
+- spec/process_helper_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/bbc/process-helper
+licenses:
+- Apache 2
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Utility for managing sub processes.
+test_files:
+- spec/process_helper_spec.rb
+- spec/spec_helper.rb