Class: Zenrows::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/zenrows/client.rb

Overview

Main client for ZenRows proxy

The client builds configured HTTP clients that route through the ZenRows proxy with specified options.

Examples:

Basic usage

Zenrows.configure do |c|
  c.api_key = 'YOUR_API_KEY'
end

client = Zenrows::Client.new
http = client.http(js_render: true)
response = http.get('https://example.com')

With custom configuration

client = Zenrows::Client.new(api_key: 'KEY', host: 'proxy.zenrows.com')
http = client.http(premium_proxy: true, proxy_country: 'us')

With per-client hooks

client = Zenrows::Client.new do |c|
  c.on_response { |resp, ctx| puts "#{ctx[:host]} -> #{resp.status}" }
end

Author:

  • Ernest Bursa

Since:

  • 0.1.0

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key: nil, host: nil, port: nil, backend: nil) {|config| ... } ⇒ Client

Initialize a new client

Examples:

With per-client hooks

client = Zenrows::Client.new do |c|
  c.on_response { |resp, ctx| puts resp.status }
end

Parameters:

  • api_key (String, nil) (defaults to: nil) —

    Override API key from global config

  • host (String, nil) (defaults to: nil) —

    Override proxy host

  • port (Integer, nil) (defaults to: nil) —

    Override proxy port

  • backend (Symbol) (defaults to: nil) —

    Backend to use (:http_rb)

Yields:

  • (config) —

    Optional block for per-client configuration (hooks, etc.)

Yield Parameters:

  • config (Configuration) —

    Client configuration for hook registration

Raises:

Since:

  • 0.1.0



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/zenrows/client.rb', line 57

def initialize(api_key: nil, host: nil, port: nil, backend: nil, &block)
  @config = build_config(api_key: api_key, host: host, port: port, backend: backend)
  @config.validate!

  # Build hooks: start with global, allow per-client additions
  @hooks = block ? build_hooks(&block) : Zenrows.configuration.hooks.dup

  @proxy = Proxy.new(
    api_key: @config.api_key,
    host: @config.host,
    port: @config.port
  )

  @backend = build_backend
end

Instance Attribute Details

#backend ⇒ Backends::Base (readonly)

Returns HTTP backend instance.

Returns:

Since:

  • 0.1.0



38
39
40
 
# File 'lib/zenrows/client.rb', line 38

def backend
  @backend
end

#config ⇒ Configuration (readonly)

Returns Client configuration.

Returns:

Since:

  • 0.1.0



32
33
34
 
# File 'lib/zenrows/client.rb', line 32

def config
  @config
end

#hooks ⇒ Hooks (readonly)

Returns Hook registry for this client.

Returns:

  • (Hooks) —

    Hook registry for this client

Since:

  • 0.1.0



41
42
43
 
# File 'lib/zenrows/client.rb', line 41

def hooks
  @hooks
end

#proxy ⇒ Proxy (readonly)

Returns Proxy builder instance.

Returns:

  • (Proxy) —

    Proxy builder instance

Since:

  • 0.1.0



35
36
37
 
# File 'lib/zenrows/client.rb', line 35

def proxy
  @proxy
end

Instance Method Details

#http(options = {}) ⇒ HTTP::Client

Build a configured HTTP client

Examples:

Basic request

http = client.http(js_render: true)
response = http.get(url)

With premium proxy and country

http = client.http(premium_proxy: true, proxy_country: 'us')
response = http.get(url)

Parameters:

  • options (Hash) (defaults to: {}) —

    Request options

Options Hash (options):

  • :js_render (Boolean) —

    Enable JavaScript rendering

  • :premium_proxy (Boolean) —

    Use residential proxies

  • :proxy_country (String) —

    Country code (us, gb, de, etc.)

  • :wait (Boolean, Integer) —

    Wait time (true=15s, Integer=ms)

  • :wait_for (String) —

    CSS selector to wait for

  • :session_id (Boolean, String, Integer) —

    Session persistence

  • :window_height (Integer) —

    Browser window height

  • :window_width (Integer) —

    Browser window width

  • :js_instructions (Array, String) —

    JavaScript instructions

  • :json_response (Boolean) —

    Return JSON instead of HTML

  • :screenshot (Boolean) —

    Take screenshot

  • :screenshot_fullpage (Boolean) —

    Full page screenshot

  • :screenshot_selector (String) —

    Screenshot specific element

  • :headers (Hash) —

    Custom HTTP headers

  • :block_resources (String) —

    Block resources (image,media,font)

Returns:

  • (HTTP::Client) —

    Configured HTTP client ready for requests

Since:

  • 0.1.0



100
101
102
 
# File 'lib/zenrows/client.rb', line 100

def http(options = {})
  backend.build_client(options)
end

#proxy_config(options = {}) ⇒ Hash

Get proxy configuration for given options

Parameters:

  • options (Hash) (defaults to: {}) —

    Proxy options

Returns:

  • (Hash) —

    Proxy configuration with :host, :port, :username, :password

Since:

  • 0.1.0



119
120
121
 
# File 'lib/zenrows/client.rb', line 119

def proxy_config(options = {})
  proxy.build(options)
end

#proxy_url(options = {}) ⇒ String

Get proxy URL for given options

Parameters:

  • options (Hash) (defaults to: {}) —

    Proxy options

Returns:

  • (String) —

    Proxy URL

Since:

  • 0.1.0



127
128
129
 
# File 'lib/zenrows/client.rb', line 127

def proxy_url(options = {})
  proxy.build_url(options)
end

#ssl_context ⇒ OpenSSL::SSL::SSLContext

Get SSL context for proxy connections

ZenRows proxy requires SSL verification to be disabled. This is automatically applied when using #http, but exposed for advanced use cases.

Returns:

  • (OpenSSL::SSL::SSLContext) —

    SSL context

Since:

  • 0.1.0



111
112
113
 
# File 'lib/zenrows/client.rb', line 111

def ssl_context
  backend.ssl_context
end