zenrows 0.2.1 → 0.3.0

data/sig/zenrows/backends/base.rbs

@@ -1,9 +1,12 @@
 class Zenrows::Backends::Base
   attr_reader proxy: Zenrows::Proxy
   attr_reader config: Zenrows::Configuration
+  attr_reader hooks: Zenrows::Hooks
 
-  def initialize: (proxy: Zenrows::Proxy, config: Zenrows::Configuration) -> void
+  def initialize: (proxy: Zenrows::Proxy, config: Zenrows::Configuration, ?hooks: Zenrows::Hooks?) -> void
   def build_client: (?Hash[Symbol, untyped] options) -> untyped
   def ssl_context: () -> OpenSSL::SSL::SSLContext
   def calculate_timeouts: (?Hash[Symbol, untyped] options) -> Hash[Symbol, Integer]
+  def wrap_client: (untyped client, Hash[Symbol, untyped] options) -> untyped
+  def backend_name: () -> Symbol
 end

data/sig/zenrows/client.rbs

@@ -2,8 +2,9 @@ class Zenrows::Client
   attr_reader config: Zenrows::Configuration
   attr_reader proxy: Zenrows::Proxy
   attr_reader backend: Zenrows::Backends::Base
+  attr_reader hooks: Zenrows::Hooks
 
-  def initialize: (?api_key: String?, ?host: String?, ?port: Integer?, ?backend: Symbol?) -> void
+  def initialize: (?api_key: String?, ?host: String?, ?port: Integer?, ?backend: Symbol?) ?{ (Zenrows::HookConfigurator) -> void } -> void
   def http: (?Hash[Symbol, untyped] options) -> untyped
   def ssl_context: () -> OpenSSL::SSL::SSLContext
   def proxy_config: (?Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]

data/sig/zenrows/configuration.rbs

@@ -11,10 +11,19 @@ class Zenrows::Configuration
   attr_accessor read_timeout: Integer
   attr_accessor backend: Symbol
   attr_accessor logger: Logger?
+  attr_reader hooks: Zenrows::Hooks
 
   def initialize: () -> void
   def reset!: () -> void
   def validate!: () -> true
   def valid?: () -> bool
   def to_h: () -> Hash[Symbol, untyped]
+
+  # Hook registration methods
+  def before_request: (?untyped? callable) ?{ (*untyped) -> untyped } -> self
+  def after_request: (?untyped? callable) ?{ (*untyped) -> untyped } -> self
+  def on_response: (?untyped? callable) ?{ (*untyped) -> untyped } -> self
+  def on_error: (?untyped? callable) ?{ (*untyped) -> untyped } -> self
+  def around_request: (?untyped? callable) ?{ (*untyped) -> untyped } -> self
+  def add_subscriber: (untyped subscriber) -> self
 end

data/sig/zenrows/hook_configurator.rbs

@@ -0,0 +1,9 @@
+class Zenrows::HookConfigurator
+  def initialize: (Zenrows::Hooks hooks) -> void
+  def before_request: (?untyped? callable) ?{ (*untyped) -> untyped } -> self
+  def after_request: (?untyped? callable) ?{ (*untyped) -> untyped } -> self
+  def on_response: (?untyped? callable) ?{ (*untyped) -> untyped } -> self
+  def on_error: (?untyped? callable) ?{ (*untyped) -> untyped } -> self
+  def around_request: (?untyped? callable) ?{ (*untyped) -> untyped } -> self
+  def add_subscriber: (untyped subscriber) -> self
+end

data/sig/zenrows/hooks/context.rbs

@@ -0,0 +1,6 @@
+class Zenrows::Hooks::Context
+  ZENROWS_HEADERS: Hash[String, Symbol]
+
+  def self.for_request: (method: Symbol, url: String, options: Hash[Symbol, untyped], backend: Symbol) -> Hash[Symbol, untyped]
+  def self.enrich_with_response: (Hash[Symbol, untyped] context, untyped response) -> Hash[Symbol, untyped]
+end

data/sig/zenrows/hooks/log_subscriber.rbs

@@ -0,0 +1,15 @@
+class Zenrows::Hooks::LogSubscriber
+  attr_reader logger: Logger?
+
+  def initialize: (?logger: Logger?) -> void
+  def before_request: (Hash[Symbol, untyped] context) -> void
+  def on_response: (untyped response, Hash[Symbol, untyped] context) -> void
+  def on_error: (Exception error, Hash[Symbol, untyped] context) -> void
+
+  private
+
+  def effective_logger: () -> Logger?
+  def log: (Symbol level) { () -> String } -> void
+  def extract_status: (untyped response) -> (Integer | String)
+  def format_duration: (Float? duration) -> String?
+end

data/sig/zenrows/hooks.rbs

@@ -0,0 +1,23 @@
+class Zenrows::Hooks
+  include MonitorMixin
+
+  EVENTS: Array[Symbol]
+
+  def initialize: () -> void
+  def register: (Symbol event, ?_Callable? callable) ?{ (*untyped) -> untyped } -> self
+  def add_subscriber: (untyped subscriber) -> self
+  def run: (Symbol event, *untyped args) -> void
+  def run_around: (Hash[Symbol, untyped] context) { () -> untyped } -> untyped
+  def empty?: () -> bool
+  def merge: (Zenrows::Hooks? other) -> self
+  def dup: () -> Zenrows::Hooks
+
+  private
+
+  def validate_event!: (Symbol event) -> void
+  def execute_chain: (Array[untyped] chain, Hash[Symbol, untyped] context) { () -> untyped } -> untyped
+
+  interface _Callable
+    def call: (*untyped) -> untyped
+  end
+end

data/sig/zenrows/instrumented_client.rbs

@@ -0,0 +1,22 @@
+class Zenrows::InstrumentedClient
+  HTTP_METHODS: Array[Symbol]
+
+  attr_reader http: untyped
+  attr_reader hooks: Zenrows::Hooks
+  attr_reader context_base: Hash[Symbol, untyped]
+
+  def initialize: (untyped http, hooks: Zenrows::Hooks, context_base: Hash[Symbol, untyped]) -> void
+  def get: (String url, **untyped options) -> untyped
+  def post: (String url, **untyped options) -> untyped
+  def put: (String url, **untyped options) -> untyped
+  def patch: (String url, **untyped options) -> untyped
+  def delete: (String url, **untyped options) -> untyped
+  def head: (String url, **untyped options) -> untyped
+  def options: (String url, **untyped options) -> untyped
+
+  private
+
+  def instrument: (Symbol method, String url, Hash[Symbol, untyped] options) { () -> untyped } -> untyped
+  def build_context: (Symbol method, String url, Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]
+  def execute_request: (Hash[Symbol, untyped] context) { () -> untyped } -> untyped
+end

data/test/test_helper.rb

@@ -5,3 +5,45 @@ require "zenrows"
 
 require "minitest/autorun"
 require "webmock/minitest"
+
+# Simple mock helper for tests
+class MockResponse
+  attr_reader :status, :headers
+
+  def initialize(status, headers = {})
+    @status = status
+    @headers = headers
+  end
+end
+
+class MockHttpClient
+  attr_reader :calls
+
+  def initialize
+    @calls = []
+    @responses = {}
+  end
+
+  def stub_response(method, url, response)
+    @responses[[method, url]] = response
+  end
+
+  def get(url, **options)
+    @calls << [:get, url, options]
+    @responses[[:get, url]] || MockResponse.new(200)
+  end
+
+  def post(url, **options)
+    @calls << [:post, url, options]
+    @responses[[:post, url]] || MockResponse.new(200)
+  end
+
+  def respond_to?(method, include_private = false)
+    [:get, :post, :custom_method].include?(method) || super
+  end
+
+  def custom_method(*args)
+    @calls << [:custom_method, *args]
+    :result
+  end
+end

data/test/zenrows/client_hooks_test.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ClientHooksTest < Minitest::Test
+  def setup
+    Zenrows.reset_configuration!
+    Zenrows.configure do |c|
+      c.api_key = "test_api_key"
+    end
+  end
+
+  def teardown
+    Zenrows.reset_configuration!
+  end
+
+  def test_client_inherits_global_hooks
+    global_called = false
+    Zenrows.configure do |c|
+      c.on_response { global_called = true }
+    end
+
+    client = Zenrows::Client.new
+
+    refute_empty client.hooks
+  end
+
+  def test_client_with_per_client_hooks
+    client = Zenrows::Client.new do |c|
+      c.on_response {}
+    end
+
+    refute_empty client.hooks
+  end
+
+  def test_per_client_hooks_dont_modify_global
+    global_empty_before = Zenrows.configuration.hooks.empty?
+
+    Zenrows.configure do |c|
+      c.on_response {}
+    end
+
+    global_not_empty = !Zenrows.configuration.hooks.empty?
+
+    client = Zenrows::Client.new do |c|
+      c.on_error {}
+    end
+
+    # Global hooks should still have same state
+    global_still_not_empty = !Zenrows.configuration.hooks.empty?
+
+    assert global_empty_before
+    assert global_not_empty
+    assert global_still_not_empty
+    refute_empty client.hooks
+  end
+
+  def test_multiple_clients_have_independent_hooks
+    client1 = Zenrows::Client.new do |c|
+      c.on_response { :client1 }
+    end
+
+    client2 = Zenrows::Client.new do |c|
+      c.on_error { :client2 }
+    end
+
+    # Each client should have its own hooks instance
+    refute_same client1.hooks, client2.hooks
+  end
+
+  def test_http_returns_instrumented_client_when_hooks_present
+    client = Zenrows::Client.new do |c|
+      c.on_response {}
+    end
+
+    http = client.http(js_render: true)
+
+    assert_instance_of Zenrows::InstrumentedClient, http
+  end
+
+  def test_http_returns_raw_client_when_no_hooks
+    # Reset to ensure no global hooks
+    Zenrows.reset_configuration!
+    Zenrows.configure { |c| c.api_key = "test" }
+
+    client = Zenrows::Client.new
+    http = client.http(js_render: true)
+
+    assert_instance_of HTTP::Client, http
+  end
+
+  def test_per_client_hook_configurator_methods
+    # Test all DSL methods are available
+    client = Zenrows::Client.new do |c|
+      c.before_request {}
+      c.after_request {}
+      c.on_response {}
+      c.on_error {}
+      c.around_request { |ctx, &block| block.call }
+      c.add_subscriber(Object.new)
+    end
+
+    refute_empty client.hooks
+  end
+end

data/test/zenrows/configuration_hooks_test.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ConfigurationHooksTest < Minitest::Test
+  def setup
+    Zenrows.reset_configuration!
+  end
+
+  def teardown
+    Zenrows.reset_configuration!
+  end
+
+  def test_configuration_has_hooks
+    assert_instance_of Zenrows::Hooks, Zenrows.configuration.hooks
+  end
+
+  def test_on_response_registers_hook
+    called = false
+    Zenrows.configure do |c|
+      c.api_key = "test"
+      c.on_response { called = true }
+    end
+
+    refute_empty Zenrows.configuration.hooks
+  end
+
+  def test_on_error_registers_hook
+    called = false
+    Zenrows.configure do |c|
+      c.api_key = "test"
+      c.on_error { called = true }
+    end
+
+    refute_empty Zenrows.configuration.hooks
+  end
+
+  def test_before_request_registers_hook
+    Zenrows.configure do |c|
+      c.api_key = "test"
+      c.before_request {}
+    end
+
+    refute_empty Zenrows.configuration.hooks
+  end
+
+  def test_after_request_registers_hook
+    Zenrows.configure do |c|
+      c.api_key = "test"
+      c.after_request {}
+    end
+
+    refute_empty Zenrows.configuration.hooks
+  end
+
+  def test_around_request_registers_hook
+    Zenrows.configure do |c|
+      c.api_key = "test"
+      c.around_request { |ctx, &block| block.call }
+    end
+
+    refute_empty Zenrows.configuration.hooks
+  end
+
+  def test_add_subscriber_registers_subscriber
+    subscriber = Object.new
+    def subscriber.on_response(resp, ctx)
+    end
+
+    Zenrows.configure do |c|
+      c.api_key = "test"
+      c.add_subscriber(subscriber)
+    end
+
+    refute_empty Zenrows.configuration.hooks
+  end
+
+  def test_reset_clears_hooks
+    Zenrows.configure do |c|
+      c.api_key = "test"
+      c.on_response {}
+    end
+
+    refute_empty Zenrows.configuration.hooks
+
+    Zenrows.reset_configuration!
+
+    assert_empty Zenrows.configuration.hooks
+  end
+
+  def test_hook_methods_return_self_for_chaining
+    Zenrows.configure do |c|
+      result = c.on_response {}
+        .on_error {}
+        .before_request {}
+        .after_request {}
+
+      assert_equal c, result
+    end
+  end
+end

data/test/zenrows/hooks/context_test.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class HooksContextTest < Minitest::Test
+  def test_for_request_builds_context
+    context = Zenrows::Hooks::Context.for_request(
+      method: :get,
+      url: "https://example.com/path",
+      options: {js_render: true},
+      backend: :http_rb
+    )
+
+    assert_equal :get, context[:method]
+    assert_equal "https://example.com/path", context[:url]
+    assert_equal "example.com", context[:host]
+    assert_equal({js_render: true}, context[:options])
+    assert_equal :http_rb, context[:backend]
+  end
+
+  def test_for_request_initializes_timing_and_headers
+    context = Zenrows::Hooks::Context.for_request(
+      method: :get,
+      url: "https://example.com",
+      options: {},
+      backend: :http_rb
+    )
+
+    assert_instance_of Float, context[:started_at]
+    assert_empty(context[:zenrows_headers])
+  end
+
+  def test_for_request_with_invalid_url
+    context = Zenrows::Hooks::Context.for_request(
+      method: :get,
+      url: "not a valid url::::",
+      options: {},
+      backend: :http_rb
+    )
+
+    assert_nil context[:host]
+  end
+
+  def test_for_request_freezes_options
+    options = {js_render: true}
+    context = Zenrows::Hooks::Context.for_request(
+      method: :get,
+      url: "https://example.com",
+      options: options,
+      backend: :http_rb
+    )
+
+    assert_predicate context[:options], :frozen?
+    # Original should not be frozen
+    refute_predicate options, :frozen?
+  end
+
+  def test_enrich_with_response_parses_zenrows_headers
+    context = Zenrows::Hooks::Context.for_request(
+      method: :get,
+      url: "https://example.com",
+      options: {},
+      backend: :http_rb
+    )
+
+    response = MockResponse.new(200, {
+      "Concurrency-Limit" => "25",
+      "Concurrency-Remaining" => "23",
+      "X-Request-Cost" => "5.5",
+      "X-Request-Id" => "abc123",
+      "Zr-Final-Url" => "https://example.com/final"
+    })
+
+    Zenrows::Hooks::Context.enrich_with_response(context, response)
+
+    assert_equal 25, context[:zenrows_headers][:concurrency_limit]
+    assert_equal 23, context[:zenrows_headers][:concurrency_remaining]
+    assert_in_delta(5.5, context[:zenrows_headers][:request_cost])
+    assert_equal "abc123", context[:zenrows_headers][:request_id]
+    assert_equal "https://example.com/final", context[:zenrows_headers][:final_url]
+  end
+
+  def test_enrich_with_response_sets_timing
+    context = Zenrows::Hooks::Context.for_request(
+      method: :get,
+      url: "https://example.com",
+      options: {},
+      backend: :http_rb
+    )
+
+    response = MockResponse.new(200, {})
+
+    Zenrows::Hooks::Context.enrich_with_response(context, response)
+
+    assert_instance_of Float, context[:completed_at]
+    assert_instance_of Float, context[:duration]
+  end
+
+  def test_enrich_with_response_handles_missing_headers
+    context = Zenrows::Hooks::Context.for_request(
+      method: :get,
+      url: "https://example.com",
+      options: {},
+      backend: :http_rb
+    )
+
+    response = MockResponse.new(200, {})
+
+    Zenrows::Hooks::Context.enrich_with_response(context, response)
+
+    assert_empty(context[:zenrows_headers])
+  end
+
+  def test_enrich_with_response_handles_lowercase_headers
+    context = Zenrows::Hooks::Context.for_request(
+      method: :get,
+      url: "https://example.com",
+      options: {},
+      backend: :http_rb
+    )
+
+    response = MockResponse.new(200, {
+      "concurrency-limit" => "10",
+      "x-request-cost" => "2.0"
+    })
+
+    Zenrows::Hooks::Context.enrich_with_response(context, response)
+
+    assert_equal 10, context[:zenrows_headers][:concurrency_limit]
+    assert_in_delta(2.0, context[:zenrows_headers][:request_cost])
+  end
+
+  def test_enrich_calculates_duration
+    context = Zenrows::Hooks::Context.for_request(
+      method: :get,
+      url: "https://example.com",
+      options: {},
+      backend: :http_rb
+    )
+
+    sleep 0.01 # Small delay
+
+    response = MockResponse.new(200, {})
+
+    Zenrows::Hooks::Context.enrich_with_response(context, response)
+
+    assert_operator context[:duration], :>=, 0.01
+    assert_operator context[:completed_at], :>, context[:started_at]
+  end
+end

data/test/zenrows/hooks/log_subscriber_test.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "logger"
+require "stringio"
+
+class LogSubscriberTest < Minitest::Test
+  def setup
+    @output = StringIO.new
+    @logger = Logger.new(@output)
+    @logger.level = Logger::DEBUG
+    @subscriber = Zenrows::Hooks::LogSubscriber.new(logger: @logger)
+  end
+
+  def test_before_request_logs_debug
+    context = {method: :get, url: "https://example.com"}
+
+    @subscriber.before_request(context)
+
+    assert_includes @output.string, "ZenRows request: GET https://example.com"
+  end
+
+  def test_on_response_logs_info_with_status
+    response = MockResponse.new(200)
+
+    context = {
+      url: "https://example.com",
+      duration: 1.5,
+      zenrows_headers: {request_cost: 5.0}
+    }
+
+    @subscriber.on_response(response, context)
+
+    assert_includes @output.string, "ZenRows https://example.com -> 200"
+    assert_includes @output.string, "1.5s"
+    assert_includes @output.string, "cost: 5.0"
+  end
+
+  def test_on_response_formats_milliseconds
+    response = MockResponse.new(200)
+
+    context = {
+      url: "https://example.com",
+      duration: 0.150,
+      zenrows_headers: {}
+    }
+
+    @subscriber.on_response(response, context)
+
+    assert_includes @output.string, "150ms"
+  end
+
+  def test_on_error_logs_error
+    error = StandardError.new("Connection failed")
+    context = {
+      url: "https://example.com",
+      zenrows_headers: {request_id: "req123"}
+    }
+
+    @subscriber.on_error(error, context)
+
+    assert_includes @output.string, "ZenRows https://example.com failed"
+    assert_includes @output.string, "StandardError"
+    assert_includes @output.string, "Connection failed"
+    assert_includes @output.string, "request_id: req123"
+  end
+
+  def test_uses_global_logger_when_none_provided
+    Zenrows.configure do |c|
+      c.api_key = "test"
+      c.logger = @logger
+    end
+
+    subscriber = Zenrows::Hooks::LogSubscriber.new
+    subscriber.before_request({method: :get, url: "https://test.com"})
+
+    assert_includes @output.string, "https://test.com"
+  ensure
+    Zenrows.reset_configuration!
+  end
+
+  def test_handles_nil_logger
+    subscriber = Zenrows::Hooks::LogSubscriber.new(logger: nil)
+
+    # Should not raise
+    subscriber.before_request({method: :get, url: "https://example.com"})
+    subscriber.on_response(MockResponse.new(200), {url: "x", zenrows_headers: {}})
+    subscriber.on_error(StandardError.new, {url: "x", zenrows_headers: {}})
+  end
+
+  def test_handles_status_object_with_code
+    # Create a response with a status object that has a code method
+    status = Object.new
+    status.define_singleton_method(:code) { 201 }
+
+    response = Object.new
+    response.define_singleton_method(:status) { status }
+
+    context = {url: "https://example.com", zenrows_headers: {}}
+
+    @subscriber.on_response(response, context)
+
+    assert_includes @output.string, "201"
+  end
+end