shrimple 0.8.0

data/lib/shrimple/phantom.rb

@@ -0,0 +1,108 @@
+# Adds a pleasant API on top of Shrimple::Process
+
+require 'shrimple/process'
+require 'stringio'
+
+class Shrimple
+  class PhantomError < StandardError; end
+  class TimedOut < StandardError; end
+
+  class Phantom < Process
+    attr_reader :options, :config
+
+    def initialize options
+      @options = options
+      @onSuccess = options.delete(:onSuccess)
+      @onError = options.delete(:onError)
+
+      # write the file required by phantom's --config option
+      if options[:config]
+        @config = Tempfile.new(File.basename(options[:output] || 'shrimple') + '.config')
+        @config.write(options[:config].to_json)
+        @config.close
+      end
+
+      # create the ios to supply input and read output
+      @stdin  = new_io(options[:stdin] || StringIO.new(options.to_json))
+      @stdout = new_io(options[:output], 'wb')
+      @stderr = new_io(options[:stderr], 'wt')
+
+      if options[:debug]
+        # hm, should this be replaced with methods?  or maybe a superclass?
+        $stderr.puts "COMMAND: #{command_line}"
+        $stderr.puts "STDIN: #{options.to_json}"
+      end
+
+      super(command_line, @stdin, @stdout, @stderr, options[:timeout])
+    end
+
+    # blocks until the PhantomJS process is finished. raises an exception if it failed.
+    def wait
+      stop
+      unless @child.value.success?
+        raise Shrimple::TimedOut.new if timed_out?
+        raise Shrimple::PhantomError.new("PhantomJS returned #{@child.value.exitstatus}: #{stderr}")
+      end
+    end
+
+    def stdout
+      read_io @stdout
+    end
+
+    def stderr
+      read_io @stderr
+    end
+
+
+    # cleans up after the process.  synchronized so it's guaranteed to only be called once.
+    # process is removed from the process table after this call returns
+    def _cleanup
+      super
+
+      proc = (success? ? @onSuccess : @onError)
+      proc.call(self) if proc
+
+      @config.unlink if @config
+    end
+
+
+  private
+    def command_line
+      if @options[:executable].nil?
+        raise "PhantomJS not found. Specify its executable with 'executable' option."
+      end
+      if @options[:executable].kind_of? Array 
+        # if executable is an array then we assume it contains all necessary args (so :renderer is ignored)
+        command = @options[:executable]
+      else
+        command = [@options[:executable]]
+        command << "--config=#{@config.path}" if @config
+        command << @options[:renderer]
+      end
+    end
+
+    # pass a filepath, an IO object or equivlanet, or nil to create an empty StringIO ready for data.
+    def new_io name, *opt
+      if name
+        if name.kind_of? String
+          return File.open(name, *opt)
+        else
+          name
+        end
+      else
+        StringIO.new
+      end
+    end
+
+    def read_io io
+      if io.kind_of?(StringIO)
+        # can't rewind because then writes go to wrong place
+        io.string
+      else
+        io.rewind
+        io.read
+      end
+    end
+  end
+end
+

data/lib/shrimple/process.rb

@@ -0,0 +1,131 @@
+# Fires off a child process, feeds it, and keeps track of the results.
+
+require 'open3'
+require 'json'
+require 'tempfile'
+require 'shrimple/process_monitor'
+
+
+class Shrimple
+  class Process
+    attr_reader :start_time, :stop_time  # start and finish times of Phantom process
+
+    # runs cmd, passes instr on its stdin, and fills outio and
+    # errio with the command's output.
+    def initialize cmd, inio, outio, errio, timeout=nil
+      @start_time = Time.now
+      @chin, @chout, @cherr, @child = Open3.popen3(*cmd)
+
+      Shrimple.processes._add(self)
+      @chout.binmode
+
+      @killed = false
+      @timed_out = false
+
+      @thrin  = Thread.new { drain(inio, @chin) }
+      @throut = Thread.new { drain(@chout, outio) }
+      @threrr = Thread.new { drain(@cherr, errio) }
+
+      # ensure cleanup is called when the child exits. (strange it requires a whole new thread...?)
+      @thrchild = Thread.new {
+        if timeout
+          outatime unless @child.join(timeout)
+        else
+          @child.join
+        end
+        stop
+      }
+    end
+
+
+    def finished?
+      @stop_time != nil
+    end
+
+    # returns false if the process hasn't finished yet
+    def success?
+      finished? && @child.value.success? ? true : false
+    end
+
+    def killed?
+      @killed
+    end
+
+    def timed_out?
+      @timed_out
+    end
+
+    # kill-o-zaps the phantom process now (using -9 if needed), then waits until it's truly gone
+    def kill seconds_until_panic=2
+      @killed = true
+      if @child.alive?
+        # rescue because process might have died between previous line and this one
+        ::Process.kill("TERM", @child.pid) rescue Errno::ESRCH
+      end
+      if !@child.join(seconds_until_panic)
+        ::Process.kill("KILL", @child.pid) if @child.alive?
+      end
+      # ensure kill doesn't return until process is truly gone
+      # (there may be a chance of this deadlocking with a blocking callback... not sure)
+      @thrchild.join unless Thread.current == @thrchild
+    end
+
+    # waits patiently until phantom process terminates, then cleans up
+    def stop
+      wait_for_the_end   # do all our waiting outside the sync loop
+      Shrimple.processes._remove(self) do
+        _cleanup
+      end
+    end
+
+
+    # only meant to be used by the ProcessMonitor
+    def _child_thread
+      @child
+    end
+
+    # may only be called once, synchronized by stop()
+    def _cleanup
+      raise "Someone else already stopped this process??!!" if @stop_time
+      @stop_time = Time.now
+    end
+
+    # returns true if process was previously active.  must be externally synchronized.
+    def _deactivate
+      retval = @inactive
+      @inactive = true
+      return !retval
+    end
+
+
+  private
+    def wait_for_the_end
+      [@thrin, @throut, @threrr, @child].each(&:join)
+      @thrchild.join unless Thread.current == @thrchild
+    end
+
+    def outatime
+      @timed_out = true
+      kill
+    end
+
+    # reads every last drop, then closes both files.  must be threadsafe.
+    def drain reader, writer
+      begin
+        # randomly chosen buffer size
+        loop { writer.write(reader.readpartial(256*1024)) }
+      rescue EOFError
+        # not an error
+        # puts "EOF STDOUT" if reader == @chout
+        # puts "EOF STDERR" if reader == @cherr
+        # puts "EOF STDIN #{reader}" if writer == @chin
+      rescue Errno::EPIPE
+        # child was killed, no problem
+      ensure
+        reader.close
+        writer.close rescue Errno::EPIPE
+      end
+    end
+
+  end
+end

data/lib/shrimple/process_monitor.rb

@@ -0,0 +1,84 @@
+# keeps track of running Shrimple processes
+
+require 'thwait'
+
+
+class Shrimple
+  class TooManyProcessesError < StandardError; end
+
+  class ProcessMonitor
+    attr_accessor :max_processes
+
+    # pass 0 to disable max_processes
+    def initialize(max_processes=20)
+      @mutex ||= Mutex.new
+      @processes ||= []   # TODO: convert this to a hash by child thread?
+      @max_processes = max_processes
+    end
+
+    def first
+      @mutex.synchronize do
+        @processes.first
+      end
+    end
+
+    def count
+      @mutex.synchronize do
+        @processes.count
+      end
+    end
+
+    def kill_all
+      while f = first
+        f.kill
+      end
+    end
+
+    # blocks until any child process returns (unless nonblock is true)
+    # raises an exception if no processes are running, or if called nonblocking
+    # and no processes have finished (see ThreadsWait#next_wait for details).
+    def wait_next nonblock=nil
+      # we wait on child threads since calling waitpid would produce a race condition.
+
+      threads = {}
+      @processes.each { |p|
+        threads[p._child_thread] = p
+      }
+
+      thread = ThreadsWait.new(threads.keys).next_wait(nonblock)
+      process = threads[thread]
+      process.stop # otherwise process will be in an indeterminite state
+      process
+    end
+
+
+    def _add process
+      @mutex.synchronize do
+        if @max_processes >= 0 && @processes.count >= @max_processes
+          raise Shrimple::TooManyProcessesError.new("launched process #{@processes.count+1} of #{@max_processes} maximum")
+        end
+        @processes.push process
+      end
+    end
+
+    # removes process from process table.  pass a block that cleans up after the process.
+    # _remove may be called lots of times but block will only be called once
+    def _remove process
+      cleanup = false
+
+      @mutex.synchronize do
+        cleanup = process._deactivate
+        raise "process not in process table??" if cleanup && !@processes.include?(process)
+      end
+
+      # don't want to hold mutex when calling callback because it might block
+      if cleanup
+        yield
+        @mutex.synchronize do
+          value = @processes.delete(process)
+          raise "someone else deleted process??" unless value
+        end
+      end
+    end
+  end
+end

data/shrimple.gemspec

@@ -0,0 +1,21 @@
+Gem::Specification.new do |s|
+  s.name     = 'shrimple'
+  s.version  = '0.8.0'
+  s.authors  = ['Scott Bronson']
+  s.email    = ['brons_shrimple@rinspin.com']
+  s.homepage = 'http://github.com/bronson/shrimple'
+  s.summary  = 'A simple Ruby interface to PhantomJS'
+  s.description = 'Use PhantomJS to generate PDFs, PNGs, text files, etc.'
+  s.license = 'MIT'
+
+  s.files         = `git ls-files -z`.split("\x0")
+  s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths = ['lib']
+
+  s.add_runtime_dependency 'hashie'
+
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'dimensions'
+end

data/spec/parse_and_print_stdin.js

@@ -0,0 +1,10 @@
+// ensures config correctly arrives via stdin
+//
+// reads json from stdin, adds "processed: true", and writes it to stdout.
+
+var system = require('system')
+
+config = JSON.parse(system.stdin.read())
+config.processed = true
+console.log(JSON.stringify(config))
+phantom.exit(0)

data/spec/shrimple/phantom_spec.rb

@@ -0,0 +1,93 @@
+
+require 'spec_helper'
+
+describe Shrimple::Phantom do
+  it "doesn't create a config file if no options are set" do
+    s = Shrimple.new(executable: ['sleep', '1'], background: true)
+
+    phantom = s.render('/dev/null')
+    expect(phantom.config).to eq nil
+    phantom.kill
+
+    expect(phantom.config).to eq nil
+    expect(phantom.stdout).to eq ""
+    expect(phantom.stderr).to eq ""
+  end
+
+  it "creates a config file when there are config options and cleans on kill" do
+    s = Shrimple.new(executable: ['sleep', '1'], background: true)
+    s.config.ignoreSslErrors = true
+
+    phantom = s.render('infile')
+    expect(phantom.config).to be_a Tempfile
+    path = phantom.config.path
+    expect(File).to exist(path)
+    config = File.read(path)
+    phantom.kill
+
+    expect(File).not_to exist(path)
+    expect(JSON.parse(config)).to eq ({'ignoreSslErrors' => true})
+    expect(phantom.stdout).to eq ""
+    expect(phantom.stdout).to eq ""
+    expect(phantom.stderr).to eq ""
+  end
+
+  it "cleans up the config file when exiting normally" do
+    s = Shrimple.new(executable: ['/bin/cat'], background: true)
+    s.config.ignoreSslErrors = true
+
+    rd,wr = IO.pipe
+    phantom = s.render(stdin: rd)
+
+    expect(phantom.config).to be_a Tempfile
+    path = phantom.config.path
+    expect(File).to exist(path)
+    wr.write("done.\n")
+    wr.close
+    phantom.stop
+
+    expect(File).not_to exist(path)
+    expect(phantom.stdout).to eq "done.\n"
+  end
+
+  it "times out when running in the foreground" do
+    s = Shrimple.new(executable: ['sleep', '10'], timeout: 0)
+    expect {
+      phantom = s.render('/dev/null')
+    }.to raise_exception(Shrimple::TimedOut)
+  end
+
+  it "times out when running in the background" do
+    s = Shrimple.new(executable: ['sleep', '10'], background: true, timeout: 0)
+    phantom = s.render('/dev/null')
+    Shrimple.processes.wait_next
+    expect(phantom.timed_out?).to eq true
+    expect(phantom.killed?).to eq true
+    expect(phantom.success?).to eq false
+  end
+
+  it "can call multiple callbacks from the same renderer" do
+    success = 0
+    failure = 0
+    s = Shrimple.new(executable: ['cat'])
+    s.onSuccess = Proc.new { |result| success += 1 }
+    s.onError = Proc.new { |result| failure += 1 }
+    s.render('/dev/null')
+    s.render('/dev/null')
+    s.render('/dev/null')
+    s.render('/dev/null')
+    expect(success).to eq 4
+    expect(failure).to eq 0
+  end
+
+  it "can read partial string contents while writing" do
+    # ensure writes still go on the end of the buffer after reading
+    # pending
+  end
+
+  it "can read partial file contents while writing" do
+    # ensure writes still go on the end of the buffer after reading
+    # pending
+  end
+end
+