webkit_remote 0.1.0

data/lib/webkit_remote/client.rb

@@ -0,0 +1,114 @@
+module WebkitRemote
+
+# Client for the Webkit remote debugging protocol
+#
+# A client manages a single tab.
+class Client
+  # Connects to the remote debugging server in a Webkit tab.
+  #
+  # @param [Hash] opts info on the tab to connect to
+  # @option opts [WebkitRemote::Tab] tab reference to the tab whose debugger
+  #     server this RPC client connects to
+  # @option opts [Boolean] close_browser if true, the session to the brower
+  #     that the tab belongs to will be closed when this RPC client's connection
+  #     is closed
+  def initialize(opts = {})
+    unless tab = opts[:tab]
+      raise ArgumentError, 'Target tab not specified'
+    end
+    @rpc = WebkitRemote::Rpc.new opts
+    @browser = tab.browser
+    @close_browser = opts.fetch :close_browser, false
+    @closed = false
+    initialize_modules
+  end
+
+  # Closes the remote debugging connection.
+  #
+  # Call this method to avoid leaking resources.
+  #
+  # @return [WebkitRemote::Rpc] self
+  def close
+    return if @closed
+    @closed = true
+    @rpc.close
+    @rpc = nil
+    @browser.close if @close_browser
+    self
+  end
+
+  # @return [Boolean] if true, the connection to the remote debugging server
+  #     has been closed, and this instance is mostly useless
+  attr_reader :closed
+  alias_method :closed?, :closed
+
+  # @return [Boolean] if true, the master debugging connection to the browser
+  #     associated with the client's tab will be automatically closed when this
+  #     RPC client's connection is closed; in turn, this might stop the browser
+  #     process
+  attr_accessor :close_browser
+  alias_method :close_browser?, :close_browser
+
+  # Continuously reports events sent by the remote debugging server.
+  #
+  # @yield once for each RPC event received from the remote debugger; break to
+  #     stop the event listening loop
+  # @yieldparam [WebkitRemote::Event] event an instance of an Event sub-class
+  #     that best represents the received event
+  # @return [WebkitRemote::Client] self
+  def each_event
+    @rpc.each_event do |rpc_event|
+      yield WebkitRemote::Event.for(rpc_event)
+    end
+    self
+  end
+
+  # Waits for the remote debugging server to send a specific event.
+  #
+  # @param (see WebkitRemote::Event#matches?)
+  # @return [WebkitRemote::Event] the event that matches the class requirement
+  def wait_for(conditions)
+    unless WebkitRemote::Event.can_receive? self, conditions
+      raise ArgumentError, "Cannot receive event with #{conditions.inspect}"
+    end
+
+    returned_event = nil
+    each_event do |event|
+      if event.matches? conditions
+        returned_event = event
+        break
+      end
+    end
+    returned_event
+  end
+
+  # @return [WebkitRemote::Rpc] the WebSocket RPC client; useful for making raw
+  #     RPC calls to unsupported methods
+  attr_reader :rpc
+
+  # @return [WebkitRemote::Browser] master session to the browser that owns the
+  #     tab debugged by this client
+  attr_reader :browser
+
+  # Call by the constructor. Replaced by the module initializers.
+  #
+  # @private Hook for module initializers to do their own setups.
+  def initialize_modules
+    # NOTE: this gets called after all the module initializers complete
+  end
+
+  # Registers a module initializer.
+  def self.initializer(name)
+    before_name = :"initialize_modules_before_#{name}"
+    alias_method before_name, :initialize_modules
+    remove_method :initialize_modules
+    eval <<END_METHOD
+      def initialize_modules
+        #{name}
+        #{before_name.to_s}
+      end
+END_METHOD
+  end
+end  # class WebkitRemote::Client
+
+end  # namespace WebkitRemote

data/lib/webkit_remote/event.rb

@@ -0,0 +1,138 @@
+module WebkitRemote
+
+# An event received via a RPC notification from a Webkit remote debugger.
+#
+# This is a generic super-class for events.
+class Event
+  # @return [String] event's domain, e.g. "Page", "DOM".
+  attr_reader :domain
+
+  # @return [String] event's name, e.g. "Page.loadEventFired".
+  attr_reader :name
+
+  # @return [Hash<String, Object>] the raw event information provided by the
+  #     RPC client
+  attr_reader :raw_data
+
+  # Checks if the event meets a set of conditions.
+  #
+  # This is used in WebkitRemote::Client#wait_for.
+  #
+  # @param [Hash<Symbol, Object>] conditions the conditions that must be met
+  #     by an event to get out of the waiting loop
+  # @option conditions [Class] class the class of events to wait for; this
+  #     condition is met if the event's class is a sub-class of the given class
+  # @option conditions [Class] type synonym for class that can be used with the
+  #     Ruby 1.9 hash syntax
+  # @option conditions [String] name the event's name, e.g.
+  #     "Page.loadEventFired"
+  # @return [Boolean] true if this event matches all the given conditions
+  def matches?(conditions)
+    conditions.all? do |key, value|
+      case key
+      when :class, :type
+        kind_of? value
+      when :name
+        name == value
+      else
+        # Simple cop-out.
+        send(key) == value
+      end
+    end
+  end
+
+  # Checks if a client can possibly meet an event meeting the given conditions.
+  #
+  # @private This is used by Client#wait_for to prevent hard-to-find bugs.
+  #
+  # @param [WebkitRemote::Client] client the client to be checked
+  # @param (see WebkitRemote::Event#matches?)
+  # @return [Boolean] false if calling WebkitRemote::Client#wait_for with the
+  #     given conditions would get the client stuck
+  def self.can_receive?(client, conditions)
+    conditions.all? do |key, value|
+      case key
+      when :class, :type
+        value.can_reach?(client)
+      when :name
+        class_for(value).can_reach?(client)
+      end
+    end
+  end
+
+  # Wraps raw event data received via a RPC notification.
+  #
+  # @param [Hash<Symbol, Object>] rpc_event event information yielded by a call
+  #     to WebkitRemote::Rpc.each_event
+  # @return [WebkitRemote::Event] an instance of an Event subclass that best
+  #     represents the given event
+  def self.for(rpc_event)
+    klass = class_for rpc_event[:name]
+    klass.new rpc_event
+  end
+
+  # The WebkitRemote::Event subclass registered to handle an event.
+  #
+  # @private Use WebkitRemote::Event#for instead of calling this directly.
+  #
+  # @param [String] rpc_event_name the value of the 'name' property of an event
+  #     notice received via the remote debugging RPC
+  # @return [Class] WebkitRemote::Event or one of its subclasses
+  def self.class_for(rpc_event_name)
+    @registry[rpc_event_name] || Event
+  end
+
+  # Wraps raw event data received via a RPC notification.
+  #
+  # @private API clients should use Event#for instead of calling the
+  #     constructor directly.
+  #
+  # @param [Hash<Symbol, Object>] rpc_event event information yielded by a call
+  #     to WebkitRemote::Rpc.each_event
+  def initialize(rpc_event)
+    @name = rpc_event[:name]
+    @domain = rpc_event[:name].split('.', 2).first
+    @raw_data = rpc_event[:data] || {}
+  end
+
+  # Registers an Event sub-class for to be instantiated when parsing an event.
+  #
+  # @private Only Event sub-classes should use this API.
+  #
+  # @param [String] name fully qualified event name, e.g. "Page.loadEventFired"
+  # @return [Class] self
+  def self.register(name)
+    WebkitRemote::Event.register_class self, name
+    self
+  end
+
+  # Registers an Event sub-class for to be instantiated when parsing an event.
+  #
+  # @private Event sub-classes should call #register on themselves instead of
+  #     calling this directly.
+  #
+  # @param [String] klass the Event subclass to be registered
+  # @param [String] name fully qualified event name, e.g. "Page.loadEventFired"
+  # @return [Class] self
+  def self.register_class(klass, name)
+    if @registry.has_key? name
+      raise ArgumentError, "#{@registry[name].name} already registered #{name}"
+    end
+    @registry[name] = klass
+    self
+  end
+  @registry = {}
+
+  # Checks if a client is set up to receive an event of this class.
+  #
+  # @private Use Event# instead of calling this directly.
+  #
+  # This method is overridden in Event sub-classes. For example, events in the
+  # Page domain can only be received if WebkitRemote::Client::Page#page_events
+  # is true.
+  def self.can_reach?(client)
+    true
+  end
+end  # class WebkitRemote::Event
+
+end  # namespace WebkitRemote

data/lib/webkit_remote/process.rb

@@ -0,0 +1,160 @@
+require 'fileutils'
+require 'net/http'
+require 'posix/spawn'
+require 'tmpdir'
+
+module WebkitRemote
+
+# Tracks a Webkit process.
+class Process
+  # Tracker for a yet-unlaunched process.
+  #
+  # @param [Hash] opts tweak the options below
+  # @option opts [Integer] port the port used by the remote debugging server;
+  #     the default port is 9292
+  # @option opts [Number] timeout number of seconds to wait for the browser
+  #     to start; the default timeout is 10 seconds
+  def initialize(opts = {})
+    @port = opts[:port] || 9292
+    @timeout = opts[:timeout] || 10
+    @running = false
+    @data_dir = Dir.mktmpdir 'webkit-remote'
+    @pid = nil
+    @cli = chrome_cli opts
+  end
+
+  # Starts the browser process.
+  #
+  # @return [WebkitRemote::Browser] self
+  def start
+    return self if running?
+    unless @pid = POSIX::Spawn.spawn(*@cli)
+      # The launch failed
+      return nil
+    end
+
+    (@timeout * 20).times do
+      # Check if the browser exited.
+      begin
+        break if status = ::Process.wait(@pid, ::Process::WNOHANG)
+      rescue SystemCallError  # no children
+        break
+      end
+
+      # Check if the browser finished starting up.
+      begin
+        browser = WebkitRemote::Browser.new process: self
+        @running = true
+        return browser
+      rescue SystemCallError  # most likely ECONNREFUSED
+        Kernel.sleep 0.05
+      end
+    end
+    # The browser failed, or was too slow to start.
+    nil
+  end
+
+  # @return [Boolean] true if the Webkit process is running
+  attr_reader :running
+  alias_method :running?, :running
+
+  # Stops the browser process.
+  #
+  # Only call this after you're done with the process.
+  #
+  # @return [WebkitRemote::Process] self
+  def stop
+    return self unless running?
+    begin
+      ::Process.kill 'TERM', @pid
+      ::Process.wait @pid
+    end
+    FileUtils.rm_rf @data_dir if File.exists?(@data_dir)
+    @running = false
+    self
+  end
+
+  # @return [Integer] port that the process' remote debugging server listens to
+  attr_reader :port
+
+  # Remove temporary directory if it's still there at garbage collection time.
+  def finalize
+    PathUtils.rm_rf @data_dir if File.exists?(@data_dir)
+  end
+
+  # Command-line that launches Google Chrome / Chromium
+  #
+  # @param [Hash] opts options passed to the WebkitRemote::Process constructor
+  # @return [Array<String>] command line for launching Chrome
+  def chrome_cli(opts)
+    # The Chromium wiki recommends this page for available flags:
+    #     http://peter.sh/experiments/chromium-command-line-switches/
+    [
+      self.class.chrome_binary,
+      '--disable-default-apps',  # no bundled apps
+      '--disable-desktop-shortcuts',  # don't mess with the desktop
+      '--disable-extensions',  # no extensions
+      '--disable-internal-flash',  # no plugins
+      '--disable-java',  # no plugins
+      '--disable-logging',  # don't trash stdout / stderr
+      '--disable-plugins',  # no native content
+      '--disable-prompt-on-repost',   # no confirmation dialog on POST refresh
+      '--disable-sync',  # no talking with the Google servers
+      '--incognito',  # don't use old state, don't preserve state
+      '--homepage=about:blank',  # don't go to Google in new tabs
+      '--keep-alive-for-test',  # don't kill process if the last window dies
+      '--lang=en-US',  # set a default language
+      '--log-level=3',  # FATAL, because there's no setting for "none"
+      '--no-default-browser-check',  # don't hang when Chrome isn't default
+      '--no-experiments',  # not sure this is useful
+      '--no-first-run',  # don't show the help UI
+      '--no-js-randomness',  # consistent Date.now() and Math.random()
+      '--no-message-box',  # don't let user scripts show dialogs
+      '--no-service-autorun',  # don't mess with autorun settings
+      '--noerrdialogs',  # don't hang on error dialogs
+      "--remote-debugging-port=#{@port}",  # Webkit remote debugging
+      "--user-data-dir=#{@data_dir}",  # really ensure a clean slate
+      '--window-position=0,0',  # remove randomness source
+      '--window-size=128,128',  # remove randomness source
+      'about:blank'  # don't load the homepage
+    ]
+  end
+
+  # Path to a Google Chrome / Chromium binary.
+  #
+  # @return [String] full-qualified path to a binary that launches Chrome
+  def self.chrome_binary
+    return @chrome_binary unless @chrome_binary == false
+
+    case RUBY_PLATFORM
+    when /linux/
+      [
+        'google-chrome',
+        'google-chromium',
+      ].each do |binary|
+        path = `which #{binary}`
+        unless path.empty?
+          @chrome_binary = path.strip
+          break
+        end
+      end
+    when /darwin/
+      [
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+      ].each do |path|
+        if File.exist? path
+          @chrome_binary = path
+          break
+        end
+      end
+    else
+      raise "Unsupported platform #{RUBY_PLATFORM}"
+    end
+    @chrome_binary ||= nil
+  end
+  @chrome_binary = false
+end  # class WebkitRemote::Browser
+
+end  # namespace WebkitRemote

data/lib/webkit_remote/rpc.rb

@@ -0,0 +1,205 @@
+require 'eventmachine'
+require 'faye/websocket'
+require 'json'
+require 'thread'
+
+module WebkitRemote
+
+# RPC client for the Webkit remote debugging protocol.
+class Rpc
+  # Connects to the remote debugging server in a Webkit tab.
+  #
+  # @param [Hash] opts info on the tab to connect to
+  # @option opts [WebkitRemote::Tab] tab reference to the tab whose debugger
+  #     server this RPC client connects to
+  def initialize(opts = {})
+    unless tab = opts[:tab]
+      raise ArgumentError, 'Target tab not specified'
+    end
+    @closed = false
+    @send_queue = EventMachine::Queue.new
+    @recv_queue = Queue.new
+    @next_id = 2
+    @events = []
+
+    self.class.em_start
+    @web_socket = Faye::WebSocket::Client.new tab.debug_url
+    setup_web_socket
+  end
+
+  # Remote debugging RPC call.
+  #
+  # See the following URL for implemented calls.
+  #     https://developers.google.com/chrome-developer-tools/docs/protocol/1.0/index
+  #
+  # @param [String] method name of the RPC method to be invoked
+  # @param [Hash<String, Object>, nil] params parameters for the RPC method to
+  #     be invoked
+  # @return [Hash<String, Object>] the return value of the RPC method
+  def call(method, params = nil)
+    request_id = @next_id
+    @next_id += 1
+    request = {
+      jsonrpc: '2.0',
+      id: request_id,
+      method: method,
+    }
+    request[:params] = params if params
+    request_json = JSON.dump request
+    @send_queue.push request_json
+
+    loop do
+      result = receive_message request_id
+      return result if result
+    end
+  end
+
+  # Continuously reports events sent by the remote debugging server.
+  #
+  # @yield once for each RPC event received from the remote debugger; break to
+  #     stop the event listening loop
+  # @yieldparam [Hash<Symbol, Object>] event the name and information hash of
+  #     the event, under the keys :name and :data
+  # @return [WebkitRemote::Rpc] self
+  def each_event
+    loop do
+      if @events.empty?
+        receive_message nil
+      else
+        yield @events.shift
+      end
+    end
+    self
+  end
+
+  # Closes the connection to the remote debugging server.
+  #
+  # Call this method to avoid leaking resources.
+  #
+  # @return [WebkitRemote::Rpc] self
+  def close
+    return if @closed
+    @closed = true
+    @web_socket.close
+    @web_socket = nil
+    self.class.em_stop
+    self
+  end
+
+  # @return [Boolean] if true, the connection to the remote debugging server
+  #     has been closed, and this instance is mostly useless
+  attr_reader :closed
+  alias_method :closed?, :closed
+
+  # Hooks up the event handlers of the WebSocket client.
+  def setup_web_socket
+    @web_socket.onopen = lambda do |event|
+      send_request
+      @web_socket.onmessage = lambda do |event|
+        data = event.data
+        EventMachine.defer do
+          @recv_queue.push data
+        end
+      end
+      @web_socket.onclose = lambda do |event|
+        code = event.code
+        EventMachine.defer do
+          @recv_queue.push code
+        end
+      end
+    end
+  end
+  private :setup_web_socket
+
+  # One iteration of the request sending loop.
+  #
+  # RPC requests are JSON-serialized on the sending thread, then pushed into
+  # the send queue, which is an EventMachine queue. On the reactor thread, the
+  # serialized message is sent as a WebSocket frame.
+  def send_request
+    @send_queue.pop do |json|
+      @web_socket.send json
+      send_request
+    end
+  end
+  private :send_request
+
+  # Blocks until a WebKit message is received, then parses it.
+  #
+  # RPC notifications are added to the @events array.
+  #
+  # @param [Integer, nil] expected_id if a RPC response is expected, this
+  #     argument has the response id; otherwise, the argument should be nil
+  # @return [Hash<String, Object>, nil] a Hash containing the RPC result if an
+  #     expected RPC response was received; nil if an RPC notice was received
+  def receive_message(expected_id)
+    json = @recv_queue.pop
+    unless json.respond_to? :to_str
+      close
+      raise RuntimeError, 'The Webkit debugging server closed the WebSocket'
+    end
+    begin
+      data = JSON.parse json
+    rescue JSONError
+      close
+      raise RuntimeError, 'Invalid JSON received'
+    end
+    if data['id']
+      # RPC result.
+      if data['id'] != expected_id
+        close
+        raise RuntimeError, 'Out of sequence RPC response id'
+      end
+      if data['error']
+        raise RuntimeError, "Error #{data['error']['code']}"
+      end
+      return data['result']
+    elsif data['method']
+      # RPC notice.
+      event = { name: data['method'], data: data['params'] }
+      @events << event
+      return nil
+    else
+      close
+      raise RuntimeError, "Unexpected / invalid RPC message #{data.inspect}"
+    end
+  end
+  private :receive_message
+
+  # Sets up an EventMachine reactor if necessary.
+  def self.em_start
+    @em_start_lock.synchronize do
+      if @em_clients == 0 and @em_thread.nil?
+        em_ready = ConditionVariable.new
+        @em_thread = Thread.new do
+          EventMachine.run do
+            @em_start_lock.synchronize { em_ready.signal }
+          end
+        end
+        em_ready.wait @em_start_lock
+      end
+      @em_clients += 1
+    end
+  end
+  @em_clients = 0
+  @em_start_lock = Mutex.new
+  @em_thread = nil
+
+  # Shuts down an EventMachine reactor if necessary.
+  def self.em_stop
+    @em_start_lock.synchronize do
+      @em_clients -= 1
+      if @em_clients == 0
+        if @em_thread
+          EventMachine.stop_event_loop
+          # HACK(pwnall): having these in slows down the code a lot
+          # EventMachine.reactor_thread.join
+          # @em_thread.join
+        end
+        @em_thread = nil
+      end
+    end
+  end
+end  # class WebkitRemote::Rpc
+
+end  # namespace webkitRemote