Class: Obxcura::Browser

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/obxcura/browser.rb

Overview

The entry point. Owns one Client (one connection) and the pages opened on it.

browser = Obxcura::Browser.new
page    = browser.create_page
browser.quit

Assumes a running obscura serve (default 127.0.0.1:9222). Pass host:/port: to point elsewhere.

Constant Summary collapse

DEFAULT_HOST =

Returns default host for obscura serve.

Returns:

  • (String) —

    default host for obscura serve.

"127.0.0.1"
DEFAULT_PORT =

Returns default CDP port for obscura serve.

Returns:

  • (Integer) —

    default CDP port for obscura serve.

9222
BLANK_PAGE =

The only URL a target may safely be created at; see #create_page.

Returns:

  • (String) 
"about:blank"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(host: DEFAULT_HOST, port: DEFAULT_PORT, timeout: Client::DEFAULT_TIMEOUT) ⇒ Browser

Connect to a running obscura serve.

Parameters:

  • host (String) (defaults to: DEFAULT_HOST) —

    host the browser listens on.

  • port (Integer) (defaults to: DEFAULT_PORT) —

    CDP port the browser listens on.

  • timeout (Integer) (defaults to: Client::DEFAULT_TIMEOUT) —

    default seconds to wait for CDP replies.

Raises:



40
41
42
43
44
45
46
 
# File 'lib/obxcura/browser.rb', line 40

def initialize(host: DEFAULT_HOST, port: DEFAULT_PORT, timeout: Client::DEFAULT_TIMEOUT)
  @host = host
  @port = port
  @timeout = timeout
  @pages = []
  @client = Client.new(browser_ws_url, timeout: @timeout)
end

Instance Attribute Details

#client ⇒ Obxcura::Client, ... (readonly)

Returns:

  • (Obxcura::Client) —

    the underlying CDP transport.

  • (Array<Obxcura::Page>) —

    the pages currently open.

  • (String) —

    the browser host.

  • (Integer) —

    the browser port.



30
31
32
 
# File 'lib/obxcura/browser.rb', line 30

def client
  @client
end

#host ⇒ Obxcura::Client, ... (readonly)

Returns:

  • (Obxcura::Client) —

    the underlying CDP transport.

  • (Array<Obxcura::Page>) —

    the pages currently open.

  • (String) —

    the browser host.

  • (Integer) —

    the browser port.



30
31
32
 
# File 'lib/obxcura/browser.rb', line 30

def host
  @host
end

#pages ⇒ Obxcura::Client, ... (readonly)

Returns:

  • (Obxcura::Client) —

    the underlying CDP transport.

  • (Array<Obxcura::Page>) —

    the pages currently open.

  • (String) —

    the browser host.

  • (Integer) —

    the browser port.



30
31
32
 
# File 'lib/obxcura/browser.rb', line 30

def pages
  @pages
end

#port ⇒ Obxcura::Client, ... (readonly)

Returns:

  • (Obxcura::Client) —

    the underlying CDP transport.

  • (Array<Obxcura::Page>) —

    the pages currently open.

  • (String) —

    the browser host.

  • (Integer) —

    the browser port.



30
31
32
 
# File 'lib/obxcura/browser.rb', line 30

def port
  @port
end

Instance Method Details

#clear_cookies ⇒ void

This method returns an undefined value.

Drop every cookie held on this connection.

Since Obscura 0.1.11 each connection owns its own browser context, so cookies no longer leak between Browser instances and this is only about resetting state within one connection — between logical sessions on the same socket, say. obscura serve is still long-lived and #quit only drops the socket, so a fresh Browser is the other way to get a clean jar.



107
108
109
110
 
# File 'lib/obxcura/browser.rb', line 107

def clear_cookies
  command("Network.clearBrowserCookies")
  nil
end

#close ⇒ void Also known as: quit

This method returns an undefined value.

Close every page, then drop the connection. Aliased as quit.



123
124
125
126
 
# File 'lib/obxcura/browser.rb', line 123

def close
  @pages.dup.each(&:close)
  client.close
end

#create_page(url = BLANK_PAGE) ⇒ Obxcura::Page

Open a fresh page (a CDP target) and attach to it. With a url, the page is navigated there and the call blocks until its load event fires.

The target is always created blank and then navigated, never opened at url directly. Handing a URL to Target.createTarget works exactly once: the second such call on a connection kills obscura serve outright — every command after it fails with connection closed: end of file reached, and the process is gone, not just the socket. Measured on 0.2.0 and deterministic, whatever the URLs are; two blank targets are fine, and so is any amount of navigation. Since the parameter cannot be honoured literally without handing callers a way to kill the browser, it is honoured by navigating.

Parameters:

  • url (String) (defaults to: BLANK_PAGE) —

    URL to open the page at (defaults to a blank page).

Returns:



63
64
65
66
67
68
69
70
71
 
# File 'lib/obxcura/browser.rb', line 63

def create_page(url = BLANK_PAGE)
  target_id = command("Target.createTarget", { url: BLANK_PAGE })["targetId"]
  session_id = command("Target.attachToTarget", { targetId: target_id, flatten: true })["sessionId"]

  page = Page.new(self, target_id: target_id, session_id: session_id)
  @pages << page
  page.goto(url) unless url == BLANK_PAGE
  page
end

#go_to(url) ⇒ Obxcura::Page Also known as: goto

Open a page and navigate to url in one call — the expressive name for #create_page with a URL.

Parameters:

  • url (String) —

    URL to navigate to.

Returns:



78
79
80
 
# File 'lib/obxcura/browser.rb', line 78

def go_to(url)
  create_page(url)
end

#remove_page(page) ⇒ Obxcura::Page?

Stop tracking a page. Called by Page#close.

Parameters:

Returns:



116
117
118
 
# File 'lib/obxcura/browser.rb', line 116

def remove_page(page)
  @pages.delete(page)
end

#targets ⇒ Array<Hash>

Every target the browser knows about (pages, workers, ...).

Returns:

  • (Array<Hash>) —

    raw CDP TargetInfo hashes.



86
87
88
 
# File 'lib/obxcura/browser.rb', line 86

def targets
  command("Target.getTargets")["targetInfos"]
end

#version ⇒ Hash

The browser's /json/version metadata (product, protocol, ws endpoint).

Returns:

  • (Hash) —

    the decoded JSON version document.



93
94
95
96
 
# File 'lib/obxcura/browser.rb', line 93

def version
  uri = URI("http://#{@host}:#{@port}/json/version")
  JSON.parse(Net::HTTP.get(uri))
end