process_watcher 0.2

data/.gitignore

@@ -0,0 +1,4 @@
+pkg/*
+*.gem
+.bundle
+doc

data/Gemfile

@@ -0,0 +1,8 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in process_watcher.gemspec
+gemspec
+
+group :win32 do
+  gem "win32-process", "~> 0.6.1"
+end

data/Gemfile.lock

@@ -0,0 +1,25 @@
+PATH
+  remote: .
+  specs:
+    process_watcher (0.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    rspec (1.3.0)
+    win32-api (1.4.6)
+    win32-process (0.6.2)
+      windows-pr (>= 1.0.5)
+    windows-api (0.4.0)
+      win32-api (>= 1.4.5)
+    windows-pr (1.0.9)
+      win32-api (>= 1.4.5)
+      windows-api (>= 0.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  process_watcher!
+  rspec (~> 1.3)
+  win32-process (~> 0.6.1)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 RightScale, Inc.
+
+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.rdoc

@@ -0,0 +1,66 @@
+= ProcessWatcher
+
+== DESCRIPTION
+
+=== Synopsis
+
+ProcessWatcher is a cross platform interface for running subprocesses
+safely.  Unlike backticks or popen in Ruby 1.8, it will not invoke a
+shell.  Unlike system, it will permits capturing the output.  Unlike
+all native Ruby interfaces, it permits killing the subprocess if it
+consume too much space or takes too long.  And it is easier to use on
+Windows than rolling it by hand.
+
+== USAGE
+
+=== Simple Example
+
+ require 'rubygems'
+ require 'process_watcher'
+
+ # Will raise ProcessWatcher::NonzeroExitCode if the exit code is not 0
+ output = ProcessWatcher.watch(command, [arguments])
+
+ # Will just run to completion and return the exit status
+ output, status = ProcessWatcher.run(command, arg1, arg2, ...)
+
+== INSTALLATION
+
+This gem can be installed by entering the following at the command
+prompt:
+
+ gem install process_watcher
+
+== TESTING
+
+Install the following RubyGems required for testing:
+- rspec
+
+The build can be tested using the RSpec gem.
+
+ rake spec
+
+== LICENSE
+
+<b>ProcessWatcher</b>
+
+Copyright:: Copyright (c) 2010 RightScale, Inc.
+
+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/Rakefile

@@ -0,0 +1,69 @@
+require 'rubygems'
+require 'bundler'
+require 'rake'
+require 'spec/rake/spectask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/clean'
+
+Bundler::GemHelper.install_tasks
+
+# == Gem == #
+
+gemtask = Rake::GemPackageTask.new(Gem::Specification.load("process_watcher.gemspec")) do |package|
+  package.package_dir = ENV['PACKAGE_DIR'] || 'pkg'
+  package.need_zip = true
+  package.need_tar = true
+end
+
+directory gemtask.package_dir
+
+CLEAN.include(gemtask.package_dir)
+
+# == Unit Tests == #
+
+task :specs => :spec
+
+desc "Run unit tests"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = Dir['spec/**/*_spec.rb']
+  t.spec_opts = lambda do
+    IO.readlines(File.join(File.dirname(__FILE__), 'spec', 'spec.opts')).map {|l| l.chomp.split " "}.flatten
+  end
+end
+
+desc "Run unit tests with RCov"
+Spec::Rake::SpecTask.new(:rcov) do |t|
+  t.spec_files = Dir['spec/**/*_spec.rb']
+  t.rcov = true
+  t.rcov_opts = lambda do
+    IO.readlines(File.join(File.dirname(__FILE__), 'spec', 'rcov.opts')).map {|l| l.chomp.split " "}.flatten
+  end
+end
+
+desc "Print Specdoc for unit tests"
+Spec::Rake::SpecTask.new(:doc) do |t|
+   t.spec_opts = ["--format", "specdoc", "--dry-run"]
+   t.spec_files = Dir['spec/**/*_spec.rb']
+end
+
+# == Documentation == #
+
+desc "Generate API documentation to doc/rdocs/index.html"
+Rake::RDocTask.new do |rd|
+  rd.rdoc_dir = 'doc/rdocs'
+  rd.main = 'README.rdoc'
+  rd.rdoc_files.include 'README.rdoc', "lib/**/*.rb"
+
+  rd.options << '--inline-source'
+  rd.options << '--line-numbers'
+  rd.options << '--all'
+  rd.options << '--fileboxes'
+  rd.options << '--diagram'
+end
+
+# == Emacs integration == #
+desc "Rebuild TAGS file"
+task :tags do
+  sh "rtags -R lib spec"
+end

data/lib/process_watcher.rb

@@ -0,0 +1,155 @@
+#--
+# Copyright: Copyright (c) 2010 RightScale, Inc.
+#
+# 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.
+#++
+
+require 'shellwords'
+require File.expand_path(File.join(File.dirname(__FILE__), 'process_watcher', 'watcher'))
+
+# Convenient interface to process watching functionality.
+module ProcessWatcher
+  # Raised when a subprocess took too much time to run.
+  class TimeoutError < RuntimeError
+    # Describe the error.
+    def to_s
+      "Command took too much time"
+    end
+  end
+  # Raised when a subprocess consumed too much space while running.
+  class TooMuchSpaceError < RuntimeError
+    # Describe the error.
+    def to_s
+      "Command took too much space"
+    end
+  end
+  # Raised when a subprocess completed, but with a nonzero exit code.
+  class NonzeroExitCode < RuntimeError
+    # (Fixnum) exit code returned by the subprocess
+    attr_reader :exit_code
+    # (String) process output (hopefully explaining the situation)
+    attr_reader :output
+
+    def initialize(exit_code, output)
+      @exit_code = exit_code
+      @output = output
+    end
+
+    # Describe the error.
+    def to_s
+      "Exit code nonzero: #{@exit_code}\nOutput was #{@output}"
+    end
+  end
+  # Watch command, respecting +max_bytes+ and +max_seconds+.  Returns
+  # the output of the command, with STDOUT and STDERR interleaved, if
+  # the command completed successfully.  Will raise one of three
+  # errors in exceptional cases:
+  # TimeoutError:: if the process takes longer than max_seconds to run
+  # TooMuchSpaceError:: if the process consumes too much space in +dir+
+  # NonzeroExitCode:: if the process exits, but with a nonzero exit code
+  #
+  # This method accepts a block.  If that block exists, it is called
+  # at most twice with three arguments, +phase+, +command+ and
+  # +exception+.  The block is called once with +phase+ set to :begin,
+  # +command+ describing the command run, and +exception+ being nil.
+  # If execution completes normally, the block is called with +phase+
+  # set to :commit, +command+ again describing the command, and
+  # +exception+ nil.  If an abnormal termination occurs (for example,
+  # running out of space), the block is called with +phase+ set to
+  # :abort, +command+ again describing the command and +exception+ set
+  # to the exception in question.
+  #
+  # === Parameters
+  # command(String):: command to run
+  # args(Array):: arguments for the command
+  # dir(String):: directory to monitor (defaults to '.')
+  # max_bytes(Integer):: maximum number of bytes to permit
+  #                      (defaults to no restriction)
+  # max_seconds(Integer):: maximum number of seconds to permit to run
+  #                        (defaults to no restriction)
+  #
+  # === Block parameters
+  # phase(Keyword):: one of :begin, :commit, or :abort
+  # command(String):: description of what command is being run and
+  #                   where it is being run
+  # exception(Exception):: if non nil, the exception raised during
+  #                        the running of the subprocess
+  #
+  # === Returns
+  # String:: output of command
+  def self.watch(command, args, dir='.', max_bytes=-1, max_seconds=-1) # :yields: phase, command, exception
+    watcher = ProcessWatcher::Watcher.new(max_bytes, max_seconds)
+    text = "in #{dir}, running #{command} #{Shellwords.join(args)}"
+    block_given? and yield :begin, text, nil
+    begin
+      result = watcher.launch_and_watch(command, args, dir)
+      if result.status == :timeout
+        raise TimeoutError, "command took too much time"
+      elsif result.status == :size_exceeded
+        raise TooMuchSpaceError, "command took too much space"
+      elsif result.exit_code != 0
+        raise NonzeroExitCode.new(result.exit_code, result.output), "nonzero exit code"
+      else
+        result.output
+      end
+    rescue => e
+      block_given? and yield :abort, text, e
+      raise
+    else
+      block_given? and yield :commit, text, nil
+      result.output
+    end
+  end
+
+  # Spawn given process, wait for it to complete, and return its
+  # output and the exit status of the process. Functions similarly to
+  # the backtick operator, only it avoids invoking the command
+  # interpreter under operating systems that support fork-and-exec.
+  #
+  # This method accepts a variable number of parameters; the first
+  # param is always the command to run; successive parameters are
+  # command-line arguments for the process.
+  #
+  # === Parameters
+  # cmd(String):: Name of the command to run
+  # arg1(String):: Optional, first command-line argumument
+  # arg2(String):: Optional, first command-line argumument
+  # ...
+  # argN(String):: Optional, Nth command-line argumument
+  #
+  # === Return
+  # output(String):: The process's output
+  # status(Process::Status):: The process's exit status
+  def self.run(cmd, *args)
+    pm = ProcessWatcher::ProcessMonitor.new
+    status = nil
+    output = StringIO.new
+
+    pm.spawn(cmd, *args) do |options|
+      output << options[:output] if options[:output]
+      status = options[:exit_status] if options[:exit_status]
+    end
+
+    pm.cleanup
+    output.close
+    output = output.string
+    return [output, status]
+  end
+end

data/lib/process_watcher/linux/process_monitor.rb

@@ -0,0 +1,102 @@
+#--
+# Copyright: Copyright (c) 2010 RightScale, Inc.
+#
+# 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.
+#++
+
+module ProcessWatcher
+  # *nix specific watcher implementation
+  class ProcessMonitor
+    # Spawn given process and callback given block with output and exit code. This method
+    # accepts a variable number of parameters; the first param is always the command to
+    # run; successive parameters are command-line arguments for the process.
+    #
+    # === Parameters
+    # cmd(String):: Name of the command to run
+    # arg1(String):: Optional, first command-line argumument
+    # arg2(String):: Optional, first command-line argumument
+    # ...
+    # argN(String):: Optional, Nth command-line argumument
+    #
+    # === Block
+    # Given block should take one argument which is a hash which may contain
+    # the keys :output and :exit_code. The value associated with :output is a chunk
+    # of output while the value associated with :exit_code is the process exit code
+    # This block won't be called anymore once the :exit_code key has associated value
+    #
+    # === Return
+    # pid(Integer):: Spawned process pid
+    def spawn(cmd, *args)
+      args = args.map { |a| a.to_s } #exec only likes string arguments
+
+      #Run subprocess; capture its output using a pipe
+      pr, pw = IO::pipe
+      @pid = fork do
+        oldstderr = STDERR.clone
+        pr.close
+        STDIN.reopen(File.open('/dev/null', 'r'))
+        STDOUT.reopen(pw)
+        STDERR.reopen(pw)
+        begin
+          exec(cmd, *args)
+        rescue
+          oldstderr.puts "Couldn't exec: #{$!}"
+        end
+      end
+
+      #Monitor subprocess output and status in a dedicated thread
+      pw.close
+      @io = pr
+      @reader = Thread.new do
+        status = nil
+        loop do
+          status = Process.waitpid(@pid, Process::WNOHANG)
+          break unless $?.nil?
+          array = select([@io], nil, [@io], 0.1)
+          array[0].each do |fdes|
+            unless fdes.eof?
+              # HACK HACK HACK 4096 is a magic number I pulled out of my
+              # ass, the real one should depend on the kernel's buffer
+              # sizes.
+              result = fdes.readpartial(4096)
+              yield(:output => result)
+            end
+          end unless array.nil?
+          array[2].each do |fdes|
+            # Do something with erroneous condition.
+          end unless array.nil?
+        end
+        yield(:exit_code => $?.exitstatus, :exit_status => $?)
+      end
+
+      return @pid
+    end
+
+    # Close io and join reader thread
+    #
+    # === Return
+    # true:: Always return true
+    def cleanup
+      @reader.join
+      @io.close
+    end
+
+  end
+end

data/lib/process_watcher/version.rb

@@ -0,0 +1,3 @@
+module ProcessWatcher
+  VERSION = "0.2"
+end

data/lib/process_watcher/watcher.rb

@@ -0,0 +1,156 @@
+#--
+# Copyright: Copyright (c) 2010 RightScale, Inc.
+#
+# 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.
+#++
+
+require 'find'
+if RUBY_PLATFORM =~ /mswin/
+  require File.expand_path(File.join(File.dirname(__FILE__), 'win32', 'process_monitor'))
+else
+  require File.expand_path(File.join(File.dirname(__FILE__), 'linux', 'process_monitor'))
+end
+
+module ProcessWatcher
+  # Encapsulate information returned by watcher
+  class WatchStatus
+
+    # Potential outcome of watcher
+    VALID_STATUSES = [ :success, :timeout, :size_exceeded ]
+
+    attr_reader :status    # One of VALID_STATUSES
+    attr_reader :exit_code # Watched process exit code or -1 if process was killed
+    attr_reader :output    # Watched process combined output
+
+    # Initialize attibutes
+    def initialize(status, exit_code, output)
+      @status    = status
+      @exit_code = exit_code
+      @output    = output
+    end
+
+  end
+
+  class Watcher
+
+    attr_reader :max_bytes   # Maximum size in bytes of watched directory before process is killed
+    attr_reader :max_seconds # Maximum number of elapased seconds before external process is killed
+
+    # Initialize attributes
+    #
+    # max_bytes(Integer):: Maximum size in bytes of watched directory before process is killed
+    # max_seconds(Integer):: Maximum number of elapased seconds before external process is killed
+    def initialize(max_bytes, max_seconds)
+      @max_bytes   = max_bytes
+      @max_seconds = max_seconds
+    end
+
+    # Launch given command as external process and watch given directory
+    # so it doesn't exceed given size. Also watch time elapsed and kill
+    # external process if either the size of the watched directory exceed
+    # @max_bytes or the time elapsed exceeds @max_seconds.
+    # Note: This method is not thread-safe, instantiate one watcher per thread
+    #
+    # === Parameters
+    # cmd(String):: command to run
+    # args(Array):: arguments for +cmd+
+    # dest_dir(String):: Watched directory
+    #
+    # === Return
+    # res(RightScale::WatchStatus):: Outcome of watch, see RightScale::WatchStatus
+    def launch_and_watch(cmd, args, dest_dir)
+      exit_code = nil
+      output    = ''
+      monitor   = ProcessMonitor.new
+
+      # Run external process and monitor it in a new thread, platform specific
+      pid = monitor.spawn(cmd, *args) do |data|
+        output << data[:output] if data[:output]
+        exit_code = data[:exit_code] if data.include?(:exit_code)
+      end
+
+      # Loop until process is done or times out or takes too much space
+      timed_out = repeat(1, @max_seconds) do
+        if @max_bytes < 0
+          exit_code
+        else
+          size = 0
+          Find.find(dest_dir) { |f| size += File.stat(f).size rescue 0 if File.file?(f) } if File.directory?(dest_dir)
+          size > @max_bytes || exit_code
+        end
+      end
+
+      # Cleanup and report status
+      # Note: We need to store the exit status before we kill the underlying process so that
+      # if it finished in the mean time we still report -1 as exit code
+      if exit_code
+        exit_status = exit_code
+        outcome = :success
+      else
+        exit_status = -1
+        outcome = (timed_out ? :timeout : :size_exceeded)
+        Process.kill('INT', pid)
+      end
+
+      # Cleanup any open handle etc., platform specific
+      monitor.cleanup
+
+      res = WatchStatus.new(outcome, exit_status, output)
+    end
+
+    protected
+
+    # Run given block in thread and time execution
+    #
+    # === Block
+    # Block whose execution is timed
+    #
+    # === Return
+    # elapsed(Integer):: Number of seconds elapsed while running given block
+    def timed
+      start_at = Time.now
+      yield
+      elapsed = Time.now - start_at
+    end
+
+    # Repeat given block at regular intervals
+    #
+    # === Parameters
+    # seconds(Integer):: Number of seconds between executions
+    # timeout(Integer):: Timeout after which execution stops and method returns
+    #
+    # === Block
+    # Given block gets executed every period seconds until timeout is reached
+    # *or* block returns true
+    #
+    # === Return
+    # res(TrueClass|FalseClass):: true if timeout is reached, false otherwise.
+    def repeat(period, timeout)
+      end_at = Time.now + timeout
+      while res = (timeout < 0 || Time.now < end_at)
+        exit = false
+        elapsed = timed { exit = yield }
+        break if exit
+        sleep(period - elapsed) if elapsed < period
+      end
+      !res
+    end
+  end
+end

data/lib/process_watcher/win32/process_monitor.rb

@@ -0,0 +1,96 @@
+#--
+# Copyright: Copyright (c) 2010 RightScale, Inc.
+#
+# 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.
+#++
+
+require 'win32/process'
+
+module ProcessWatcher
+  # Windows specific watcher implementation
+  class ProcessMonitor
+
+    include ::Windows::Process
+    include ::Windows::Synchronize
+    include ::Windows::Handle
+
+    # Spawn given process and callback given block with output and exit code
+    #
+    # === Parameters
+    # cmd(String):: Process command line (including arguments)
+    # arg1(String):: Optional, first command-line argumument
+    # arg2(String):: Optional, first command-line argumument
+    # ...
+    # argN(String):: Optional, Nth command-line argumument
+    #
+    # === Block
+    # Given block should take one argument which is a hash which may contain
+    # the keys :output and :exit_code. The value associated with :output is a chunk
+    # of output while the value associated with :exit_code is the process exit code
+    # This block won't be called anymore once the :exit_code key has associated value
+    #
+    # === Return
+    # pid(Integer):: Spawned process pid
+    def spawn(cmd, *args)
+      args = args.map { |a| a.to_s }
+      cmd = ([cmd] + args).join(' ')
+
+      # Run external process and monitor it in a new thread
+      @io = IO.popen(cmd)
+      @handle = OpenProcess(PROCESS_ALL_ACCESS, 0, @io.pid)
+      case @handle
+      when INVALID_HANDLE_VALUE
+        # Something bad happened
+        yield(:exit_code => 1)
+      when 0
+        # Process already finished
+        yield(:exit_code => 0)
+      else
+        # Start output read
+        @reader = Thread.new do
+          o = @io.read
+          until o == ''
+            yield(:output => o)
+            o = @io.read
+          end
+          status = WaitForSingleObject(@handle, INFINITE)
+          exit_code = [0].pack('L')
+          if GetExitCodeProcess(@handle, exit_code)
+            exit_code = exit_code.unpack('L').first
+          else
+            exit_code = 1
+          end
+          yield(:exit_code => exit_code)
+        end
+      end
+      @io.pid
+    end
+
+    # Cleanup underlying handle
+    #
+    # === Return
+    # true:: Always return true
+    def cleanup
+      @reader.join
+      CloseHandle(@handle) if @handle > 0
+      @io.close
+    end
+  end
+end

data/process_watcher.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "process_watcher/version"
+
+Gem::Specification.new do |s|
+  s.name        = "process_watcher"
+  s.version     = ProcessWatcher::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Graham Hughes", "Raphael Simon"]
+  s.email       = ["graham@rightscale.com"]
+  s.homepage    = "http://rubygems.org/gems/process_watcher"
+  s.summary     = %q{Cross platform interface to running subprocesses}
+  s.description = <<-EOF
+ProcessWatcher is a cross platform interface for running subprocesses
+safely.  Unlike backticks or popen in Ruby 1.8, it will not invoke a
+shell.  Unlike system, it will permits capturing the output.  Unlike
+rolling it by hand, it runs on Windows.
+EOF
+
+  s.rubyforge_project = "process_watcher"
+
+  s.requirements << 'win32-process ~> 0.6.1 gem on Windows systems'
+  s.add_development_dependency('rspec', "~> 1.3")
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/spec/process_watcher/watcher_spec.rb

@@ -0,0 +1,80 @@
+#--
+# Copyright: Copyright (c) 2010 RightScale, Inc.
+#
+# 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.
+#++
+
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'spec_helper'))
+
+describe ProcessWatcher::Watcher do
+
+  before(:each) do
+    @dest_dir = File.join(File.dirname(__FILE__), '__destdir')
+    FileUtils.mkdir_p(@dest_dir)
+  end
+
+  after(:each) do
+    FileUtils.rm_rf(@dest_dir)
+  end
+
+  it 'should launch and watch well-behaved processes' do
+    watcher = ProcessWatcher::Watcher.new(max_bytes=1, max_seconds=5)
+    ruby = "trap('INT', 'IGNORE'); puts 42; exit 42"
+    status = watcher.launch_and_watch('ruby', ['-e', ruby], @dest_dir)
+    status.status.should == :success
+    status.exit_code.should == 42
+    status.output.should == "42\n"
+  end
+
+  it 'should report timeouts' do
+    watcher = ProcessWatcher::Watcher.new(max_bytes=1, max_seconds=2)
+    ruby = "trap('INT', 'IGNORE'); STDOUT.sync = true; puts 42; sleep 5"
+    status = watcher.launch_and_watch('ruby',  ['-e', ruby], @dest_dir)
+    status.status.should == :timeout
+    status.exit_code.should == -1
+    status.output.should == "42\n"
+  end
+
+  it 'should report size exceeded' do
+    watcher = ProcessWatcher::Watcher.new(max_bytes=1, max_seconds=5)
+    ruby = "trap('INT', 'IGNORE'); STDOUT.sync = true; puts 42; File.open(File.join('#{@dest_dir}', 'test'), 'w') { |f| f.puts 'MORE THAN 2 CHARS' }; sleep 5 rescue nil"
+    status = watcher.launch_and_watch('ruby', ['-e', ruby], @dest_dir)
+    status.status.should == :size_exceeded
+    status.exit_code.should == -1
+    status.output.should == "42\n"
+  end
+
+  it 'should allow infinite size and timeout' do
+    watcher = ProcessWatcher::Watcher.new(max_bytes=-1, max_seconds=-1)
+    ruby = "trap('INT', 'IGNORE'); STDOUT.sync = true; puts 42; File.open(File.join('#{@dest_dir}', 'test'), 'w') { |f| f.puts 'MORE THAN 2 CHARS' }; sleep 2 rescue nil"
+    status = watcher.launch_and_watch('ruby', ['-e', ruby], @dest_dir)
+    status.status.should == :success
+    status.exit_code.should == 0
+    status.output.should == "42\n"
+  end
+
+  it 'should permit array arguments' do
+    watcher = ProcessWatcher::Watcher.new(max_bytes=-1, max_seconds=-1)
+    status = watcher.launch_and_watch("echo", ["$HOME", ";", "echo", "broken"], @dest_dir)
+    status.status.should == :success
+    status.exit_code.should == 0
+    status.output.should == "$HOME ; echo broken\n"
+  end
+end

data/spec/process_watcher_spec.rb

@@ -0,0 +1,112 @@
+#--
+# Copyright: Copyright (c) 2010 RightScale, Inc.
+#
+# 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.
+#++
+
+require File.expand_path(File.join(File.dirname(__FILE__), 'spec_helper'))
+
+describe ProcessWatcher do
+  before(:each) do
+    @dest_dir = File.join(File.dirname(__FILE__), '__destdir')
+    FileUtils.mkdir_p(@dest_dir)
+  end
+
+  after(:each) do
+    FileUtils.rm_rf(@dest_dir)
+  end
+
+  context :watch do
+    it 'should launch and watch well-behaved processes' do
+      ruby = "trap('INT', 'IGNORE'); puts 42; exit 0"
+      ProcessWatcher.watch("ruby", ["-e", ruby]).should == "42\n"
+    end
+
+    it 'should call the block as appropriate' do
+      ruby = "trap('INT', 'IGNORE'); puts 42; exit 0"
+      times = 0
+      ProcessWatcher.watch("ruby", ["-e", ruby], @dest_dir) { |type, text|
+        case times
+        when 0 then type.should == :begin
+        when 1 then type.should == :commit
+        else fail_with("callback should only be called twice", nil, times)
+        end
+        times += 1
+        text.should =~ /^in #{Regexp.escape(@dest_dir)}, running ruby -e #{Regexp.escape(Shellwords.escape(ruby))}/
+      }.should == "42\n"
+    end
+
+    it 'should report weird error codes' do
+      ruby = "trap('INT', 'IGNORE'); puts 42; exit 42"
+      lambda {
+        ProcessWatcher.watch("ruby", ["-e", ruby], @dest_dir, 1, 2)
+      }.should raise_exception(ProcessWatcher::NonzeroExitCode) {|e| e.exit_code.should == 42}
+    end
+
+    it 'should report timeouts' do
+      ruby = "trap('INT', 'IGNORE'); puts 42; sleep 5"
+      lambda {
+        ProcessWatcher.watch("ruby", ["-e", ruby], @dest_dir, 1, 2)
+      }.should raise_exception(ProcessWatcher::TimeoutError)
+    end
+
+    it 'should report size exceeded' do
+      ruby = "trap('INT', 'IGNORE'); STDOUT.sync = true; puts 42; File.open" +
+        "(File.join('#{@dest_dir}', 'test'), 'w') { |f| f.puts 'MORE THAN 2 CHARS' }; sleep 5 rescue nil"
+      lambda {
+        ProcessWatcher.watch("ruby", ["-e", ruby], @dest_dir, 1, -1)
+      }.should raise_exception(ProcessWatcher::TooMuchSpaceError)
+    end
+
+    it 'should allow infinite size and timeout' do
+      ruby = "trap('INT', 'IGNORE'); STDOUT.sync = true; puts 42; " +
+        "File.open(File.join('#{@dest_dir}', 'test'), 'w') { |f| " +
+        "f.puts 'MORE THAN 2 CHARS' }; sleep 2 rescue nil"
+      ProcessWatcher.watch("ruby", ["-e", ruby]).should == "42\n"
+    end
+
+    it 'should permit array arguments' do
+      ProcessWatcher.watch("echo", ["$HOME", ";", "echo", "broken"]).should == "$HOME ; echo broken\n"
+    end
+  end
+
+  context :run do
+    it 'should launch well-behaved processes' do
+      ruby = "trap('INT', 'IGNORE'); puts 42; exit 0"
+      output, status = ProcessWatcher.run("ruby", "-e", ruby)
+      output.should == "42\n"
+      status.exitstatus.should == 0
+    end
+
+    it 'should record weird error codes in $?' do
+      ruby = "trap('INT', 'IGNORE'); puts 42; exit 42"
+      output, status = ProcessWatcher.run("ruby", "-e", ruby)
+      output.should == "42\n"
+      status.exitstatus.should == 42
+    end
+
+    it 'should run in the current directory' do
+      ruby = "trap('INT', 'IGNORE'); puts File.expand_path('.')"
+      output, status = ProcessWatcher.run("ruby", "-e", ruby)
+      output.should == File.expand_path('.') + "\n"
+      status.exitstatus.should == 0
+    end
+  end
+end

data/spec/rcov.opts

@@ -0,0 +1 @@
+--exclude "spec/*"~

data/spec/spec.opts

@@ -0,0 +1,2 @@
+--format=nested
+--backtrace

data/spec/spec_helper.rb

@@ -0,0 +1,29 @@
+#--
+# Copyright: Copyright (c) 2010 RightScale, Inc.
+#
+# 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.
+#++
+
+require 'rubygems'
+$:.unshift(File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib')))
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'process_watcher'))
+
+require 'spec'
+

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification 
+name: process_watcher
+version: !ruby/object:Gem::Version 
+  hash: 15
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  version: "0.2"
+platform: ruby
+authors: 
+- Graham Hughes
+- Raphael Simon
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-10-14 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  type: :development
+  prerelease: false
+  name: rspec
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 9
+        segments: 
+        - 1
+        - 3
+        version: "1.3"
+  requirement: *id001
+description: |
+  ProcessWatcher is a cross platform interface for running subprocesses
+  safely.  Unlike backticks or popen in Ruby 1.8, it will not invoke a
+  shell.  Unlike system, it will permits capturing the output.  Unlike
+  rolling it by hand, it runs on Windows.
+
+email: 
+- graham@rightscale.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.rdoc
+- Rakefile
+- lib/process_watcher.rb
+- lib/process_watcher/linux/process_monitor.rb
+- lib/process_watcher/version.rb
+- lib/process_watcher/watcher.rb
+- lib/process_watcher/win32/process_monitor.rb
+- process_watcher.gemspec
+- spec/process_watcher/watcher_spec.rb
+- spec/process_watcher_spec.rb
+- spec/rcov.opts
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://rubygems.org/gems/process_watcher
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: 
+- win32-process ~> 0.6.1 gem on Windows systems
+rubyforge_project: process_watcher
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Cross platform interface to running subprocesses
+test_files: 
+- spec/process_watcher/watcher_spec.rb
+- spec/process_watcher_spec.rb
+- spec/rcov.opts
+- spec/spec.opts
+- spec/spec_helper.rb