zenrows 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c04285fb07c401d81848da8a4ba763b3e0cd0a550c5e34fc1716101f229fbb7
-  data.tar.gz: 04d35bac2bafd413d8969d5d61b54f414c54390db0deb014dd721e2874944cc2
+  metadata.gz: e684c8840821205883d52bd782aa3d22c8c21404bc9e3a4ab068f9069389e575
+  data.tar.gz: eed9546964086c061082a55aa4fa9218c5c24dfa02b70f20297b04b55fa77891
 SHA512:
-  metadata.gz: 12becd343181666b4dc8b8edccc5fffcb410ecaf7ba74b9b7ed8a6859693d20f7b466e27f5e8a245b9841c56d7f2c4b1d2b3fa7a84b241b3725140acc546ad2c
-  data.tar.gz: '0368ed029138f05de5e2041fb4136caacc04d3ae9b172e7b5983f1204eefa0d12afc2ab70724f124922358d201195aa070e60db2248cee7b9031bb9d64e0c6d2'
+  metadata.gz: 31a6e6f8d95e0431cd7ce0bf545e813c64954021914eb67cf8312155b0c9d7cdea2ab1ede5378972757c1b148be0cd7be13e7ddda5ed2fbdb83cb30aad9fc18a
+  data.tar.gz: 74584d555a2915b1e0f8ac2fd0fb46ca78b21a80430c0e20f252237497a27087b4027e244c450222ae322b2f1ae2f0a02b59652daddc2069ac48783525d5cc69

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2025-12-30
+
+### Added
+
+- Hooks/callbacks system for request lifecycle events
+- Five hook types: `before_request`, `after_request`, `on_response`, `on_error`, `around_request`
+- Global and per-client hook registration
+- `Zenrows::Hooks::LogSubscriber` built-in logging subscriber
+- `InstrumentedClient` wrapper for HTTP client instrumentation
+- Context object with ZenRows header parsing (request_cost, concurrency_remaining, request_id, final_url)
+- RBS type signatures for all hooks classes
+- Monotonic clock for accurate request duration timing
+
+### Changed
+
+- `after_request` hook now always runs (via `ensure`), even on errors
+
 ## [0.2.1] - 2025-12-25
 
 ### Added

data/README.md

@@ -208,6 +208,46 @@ response.concurrency_remaining  # => 199
 | `response_type`  | String       | Output format ('markdown')           |
 | `outputs`        | String       | Extract specific data (headings,links) |
 
+## Hooks
+
+Register callbacks for request lifecycle events:
+
+```ruby
+Zenrows.configure do |c|
+  c.api_key = 'YOUR_KEY'
+
+  # Log responses
+  c.on_response { |resp, ctx| puts "#{ctx[:host]} -> #{resp.status}" }
+
+  # Track errors
+  c.on_error { |err, ctx| Sentry.capture_exception(err) }
+
+  # Monitor costs
+  c.on_response do |resp, ctx|
+    cost = ctx[:zenrows_headers][:request_cost]
+    StatsD.increment('zenrows.cost', cost) if cost
+  end
+end
+```
+
+Per-client hooks:
+
+```ruby
+client = Zenrows::Client.new do |c|
+  c.on_response { |resp, ctx| log_specific(resp) }
+end
+```
+
+Built-in logger:
+
+```ruby
+c.add_subscriber(Zenrows::Hooks::LogSubscriber.new)
+```
+
+Available hooks: `before_request`, `after_request`, `on_response`, `on_error`, `around_request`
+
+Context includes: `method`, `url`, `host`, `duration`, `zenrows_headers` (request_cost, concurrency_remaining, request_id, final_url)
+
 ## Error Handling
 
 ```ruby

data/lib/zenrows/api_client.rb

@@ -25,6 +25,11 @@ module Zenrows
   # @example With markdown output
   #   response = api.get(url, response_type: 'markdown')
   #
+  # @example With per-client hooks
+  #   api = Zenrows::ApiClient.new do |c|
+  #     c.on_response { |resp, ctx| puts "#{ctx[:host]} -> #{resp.status}" }
+  #   end
+  #
   # @author Ernest Bursa
   # @since 0.2.0
   # @api public
@@ -38,15 +43,23 @@ module Zenrows
     # @return [Configuration] Configuration instance
     attr_reader :config
 
+    # @return [Hooks] Hook registry for this client
+    attr_reader :hooks
+
     # Initialize API client
     #
     # @param api_key [String, nil] Override API key (uses global config if nil)
     # @param api_endpoint [String, nil] Override API endpoint (uses global config if nil)
-    def initialize(api_key: nil, api_endpoint: nil)
+    # @yield [config] Optional block for per-client configuration (hooks)
+    # @yieldparam config [HookConfigurator] Hook configuration DSL
+    def initialize(api_key: nil, api_endpoint: nil, &block)
       @config = Zenrows.configuration
       @api_key = api_key || @config.api_key
       @api_endpoint = api_endpoint || @config.api_endpoint
       @config.validate! unless api_key
+
+      # Build hooks: start with global, allow per-client additions
+      @hooks = block ? build_hooks(&block) : Zenrows.configuration.hooks.dup
     end
 
     # Make GET request through ZenRows API
@@ -76,9 +89,11 @@ module Zenrows
     # @raise [AuthenticationError] if API key invalid
     # @raise [RateLimitError] if rate limited
     def get(url, **options)
-      params = build_params(url, options)
-      http_response = build_http_client.get(api_endpoint, params: params)
-      handle_response(http_response, options)
+      instrument(:get, url, options) do
+        params = build_params(url, options)
+        http_response = build_http_client.get(api_endpoint, params: params)
+        handle_response(http_response, options)
+      end
     end
 
     # Make POST request through ZenRows API
@@ -88,13 +103,61 @@ module Zenrows
     # @param options [Hash] Request options (same as #get)
     # @return [ApiResponse] Response wrapper
     def post(url, body: nil, **options)
-      params = build_params(url, options)
-      http_response = build_http_client.post(api_endpoint, params: params, body: body)
-      handle_response(http_response, options)
+      instrument(:post, url, options) do
+        params = build_params(url, options)
+        http_response = build_http_client.post(api_endpoint, params: params, body: body)
+        handle_response(http_response, options)
+      end
     end
 
     private
 
+    # Build hooks registry for this client
+    #
+    # @yield [config] Block for registering per-client hooks
+    # @return [Hooks] Combined hooks registry
+    def build_hooks
+      client_hooks = Zenrows.configuration.hooks.dup
+      hook_config = HookConfigurator.new(client_hooks)
+      yield(hook_config)
+      client_hooks
+    end
+
+    # Instrument a request with hooks
+    #
+    # @param method [Symbol] HTTP method
+    # @param url [String] Target URL
+    # @param options [Hash] Request options
+    # @yield Block that executes the actual request
+    # @return [Object] Response from block
+    def instrument(method, url, options)
+      return yield if hooks.empty?
+
+      context = Hooks::Context.for_request(
+        method: method,
+        url: url,
+        options: options,
+        backend: :api
+      )
+
+      hooks.run(:before_request, context)
+
+      response = hooks.run_around(context) do
+        result = yield
+        Hooks::Context.enrich_with_response(context, result)
+        hooks.run(:on_response, result, context)
+        result
+      end
+
+      response
+    rescue => e
+      context[:error] = e if context
+      hooks.run(:on_error, e, context) if context
+      raise
+    ensure
+      hooks.run(:after_request, context) if context
+    end
+
     def build_http_client
       HTTP
         .timeout(connect: config.connect_timeout, read: config.read_timeout)

data/lib/zenrows/backends/base.rb

@@ -18,11 +18,16 @@ module Zenrows
       # @return [Zenrows::Configuration] Configuration instance
       attr_reader :config
 
+      # @return [Zenrows::Hooks] Hook registry for this backend
+      attr_reader :hooks
+
       # @param proxy [Zenrows::Proxy] Proxy configuration builder
       # @param config [Zenrows::Configuration] Configuration instance
-      def initialize(proxy:, config:)
+      # @param hooks [Zenrows::Hooks, nil] Optional hook registry (defaults to config.hooks)
+      def initialize(proxy:, config:, hooks: nil)
         @proxy = proxy
         @config = config
+        @hooks = hooks || config.hooks&.dup || Hooks.new
       end
 
       # Build a configured HTTP client
@@ -74,6 +79,31 @@ module Zenrows
         {connect: connect, read: read}
       end
 
+      # Wrap HTTP client with instrumentation if hooks are registered
+      #
+      # @param client [Object] The underlying HTTP client
+      # @param options [Hash] Request options used for this client
+      # @return [Object] Instrumented client or original if no hooks
+      def wrap_client(client, options)
+        return client if hooks.empty?
+
+        InstrumentedClient.new(
+          client,
+          hooks: hooks,
+          context_base: {
+            options: options,
+            backend: backend_name
+          }
+        )
+      end
+
+      # Get the backend name for context
+      #
+      # @return [Symbol] Backend identifier
+      def backend_name
+        :base
+      end
+
       private
 
       # Normalize wait value to seconds

data/lib/zenrows/backends/http_rb.rb

@@ -27,7 +27,7 @@ module Zenrows
       # @option options [Boolean, Integer] :wait Wait time
       # @option options [String] :wait_for CSS selector to wait for
       # @option options [Hash] :headers Custom HTTP headers
-      # @return [HTTP::Client] Configured HTTP client
+      # @return [HTTP::Client, InstrumentedClient] Configured HTTP client (instrumented if hooks registered)
       def build_client(options = {})
         opts = options.dup
         headers = opts.delete(:headers) || {}
@@ -42,7 +42,7 @@ module Zenrows
         timeouts = calculate_timeouts(opts)
 
         # Build HTTP client with SSL context and proxy
-        HTTP
+        client = HTTP
           .timeout(connect: timeouts[:connect], read: timeouts[:read])
           .headers(headers)
           .via(
@@ -52,6 +52,14 @@ module Zenrows
             proxy_config[:password],
             ssl_context: ssl_context
           )
+
+        # Wrap with instrumentation if hooks registered
+        wrap_client(client, opts)
+      end
+
+      # @return [Symbol] Backend identifier
+      def backend_name
+        :http_rb
       end
     end
   end

data/lib/zenrows/backends/net_http.rb

@@ -23,7 +23,7 @@ module Zenrows
       # Build a configured HTTP client wrapper
       #
       # @param options [Hash] Request options
-      # @return [NetHttpClient] Configured client wrapper
+      # @return [NetHttpClient, InstrumentedClient] Configured client wrapper (instrumented if hooks registered)
       def build_client(options = {})
         opts = options.dup
         headers = opts.delete(:headers) || {}
@@ -32,12 +32,20 @@ module Zenrows
         proxy_config = proxy.build(opts)
         timeouts = calculate_timeouts(opts)
 
-        NetHttpClient.new(
+        client = NetHttpClient.new(
           proxy_config: proxy_config,
           headers: headers,
           timeouts: timeouts,
           ssl_context: ssl_context
         )
+
+        # Wrap with instrumentation if hooks registered
+        wrap_client(client, opts)
+      end
+
+      # @return [Symbol] Backend identifier
+      def backend_name
+        :net_http
       end
     end
 

data/lib/zenrows/client.rb

@@ -19,6 +19,11 @@ module Zenrows
   #   client = Zenrows::Client.new(api_key: 'KEY', host: 'proxy.zenrows.com')
   #   http = client.http(premium_proxy: true, proxy_country: 'us')
   #
+  # @example 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
   # @api public
@@ -32,17 +37,30 @@ module Zenrows
     # @return [Backends::Base] HTTP backend instance
     attr_reader :backend
 
+    # @return [Hooks] Hook registry for this client
+    attr_reader :hooks
+
     # Initialize a new client
     #
     # @param api_key [String, nil] Override API key from global config
     # @param host [String, nil] Override proxy host
     # @param port [Integer, nil] Override proxy port
     # @param backend [Symbol] Backend to use (:http_rb)
+    # @yield [config] Optional block for per-client configuration (hooks, etc.)
+    # @yieldparam config [Configuration] Client configuration for hook registration
     # @raise [ConfigurationError] if api_key is not configured
-    def initialize(api_key: nil, host: nil, port: nil, backend: nil)
+    #
+    # @example With per-client hooks
+    #   client = Zenrows::Client.new do |c|
+    #     c.on_response { |resp, ctx| puts resp.status }
+    #   end
+    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,
@@ -149,14 +167,31 @@ module Zenrows
       backend_name = resolve_backend
       case backend_name
       when :http_rb
-        Backends::HttpRb.new(proxy: proxy, config: config)
+        Backends::HttpRb.new(proxy: proxy, config: config, hooks: hooks)
       when :net_http
-        Backends::NetHttp.new(proxy: proxy, config: config)
+        Backends::NetHttp.new(proxy: proxy, config: config, hooks: hooks)
       else
         raise ConfigurationError, "Unsupported backend: #{backend_name}. Use :http_rb or :net_http"
       end
     end
 
+    # Build hooks registry for this client
+    #
+    # Starts with global hooks, then applies per-client hooks from block.
+    #
+    # @yield [config] Block for registering per-client hooks
+    # @return [Hooks] Combined hooks registry
+    def build_hooks
+      # Start with a copy of global hooks
+      client_hooks = Zenrows.configuration.hooks.dup
+
+      # Create a temporary config-like object for hook registration
+      hook_config = HookConfigurator.new(client_hooks)
+      yield(hook_config)
+
+      client_hooks
+    end
+
     # Resolve which backend to use
     #
     # @return [Symbol] Backend name
@@ -182,4 +217,52 @@ module Zenrows
       false
     end
   end
+
+  # Helper class for per-client hook configuration
+  #
+  # Provides the same hook registration DSL as Configuration.
+  #
+  # @api private
+  class HookConfigurator
+    # @param hooks [Hooks] Hook registry to configure
+    def initialize(hooks)
+      @hooks = hooks
+    end
+
+    # Register a before_request callback
+    def before_request(callable = nil, &block)
+      @hooks.register(:before_request, callable, &block)
+      self
+    end
+
+    # Register an after_request callback
+    def after_request(callable = nil, &block)
+      @hooks.register(:after_request, callable, &block)
+      self
+    end
+
+    # Register an on_response callback
+    def on_response(callable = nil, &block)
+      @hooks.register(:on_response, callable, &block)
+      self
+    end
+
+    # Register an on_error callback
+    def on_error(callable = nil, &block)
+      @hooks.register(:on_error, callable, &block)
+      self
+    end
+
+    # Register an around_request callback
+    def around_request(callable = nil, &block)
+      @hooks.register(:around_request, callable, &block)
+      self
+    end
+
+    # Add a subscriber object
+    def add_subscriber(subscriber)
+      @hooks.add_subscriber(subscriber)
+      self
+    end
+  end
 end

data/lib/zenrows/configuration.rb

@@ -45,6 +45,9 @@ module Zenrows
     # @return [String] ZenRows API endpoint for ApiClient
     attr_accessor :api_endpoint
 
+    # @return [Zenrows::Hooks] Hook registry for request lifecycle events
+    attr_reader :hooks
+
     # Default configuration values
     DEFAULTS = {
       host: "superproxy.zenrows.com",
@@ -73,9 +76,117 @@ module Zenrows
         @read_timeout = DEFAULTS[:read_timeout]
         @backend = DEFAULTS[:backend]
         @logger = nil
+        @hooks = Hooks.new
       end
     end
 
+    # Register a callback to run before each request
+    #
+    # @param callable [#call, nil] Callable object
+    # @yield [context] Block to execute
+    # @yieldparam context [Hash] Request context
+    # @return [self]
+    #
+    # @example
+    #   config.before_request { |ctx| puts "Starting: #{ctx[:url]}" }
+    def before_request(callable = nil, &block)
+      hooks.register(:before_request, callable, &block)
+      self
+    end
+
+    # Register a callback to run after each request (always runs)
+    #
+    # @param callable [#call, nil] Callable object
+    # @yield [context] Block to execute
+    # @yieldparam context [Hash] Request context
+    # @return [self]
+    #
+    # @example
+    #   config.after_request { |ctx| puts "Finished: #{ctx[:duration]}s" }
+    def after_request(callable = nil, &block)
+      hooks.register(:after_request, callable, &block)
+      self
+    end
+
+    # Register a callback to run on successful response
+    #
+    # @param callable [#call, nil] Callable object
+    # @yield [response, context] Block to execute
+    # @yieldparam response [Object] HTTP response
+    # @yieldparam context [Hash] Request context with ZenRows headers
+    # @return [self]
+    #
+    # @example Log by host
+    #   config.on_response { |resp, ctx| puts "#{ctx[:host]} -> #{resp.status}" }
+    #
+    # @example Track costs
+    #   config.on_response do |resp, ctx|
+    #     cost = ctx[:zenrows_headers][:request_cost]
+    #     StatsD.increment('zenrows.cost', cost) if cost
+    #   end
+    def on_response(callable = nil, &block)
+      hooks.register(:on_response, callable, &block)
+      self
+    end
+
+    # Register a callback to run on request error
+    #
+    # @param callable [#call, nil] Callable object
+    # @yield [error, context] Block to execute
+    # @yieldparam error [Exception] The error that occurred
+    # @yieldparam context [Hash] Request context
+    # @return [self]
+    #
+    # @example
+    #   config.on_error { |err, ctx| Sentry.capture_exception(err) }
+    def on_error(callable = nil, &block)
+      hooks.register(:on_error, callable, &block)
+      self
+    end
+
+    # Register a callback to wrap around requests
+    #
+    # Around callbacks can modify timing, add retries, etc.
+    # The block MUST call the passed block and return its result.
+    #
+    # @param callable [#call, nil] Callable object
+    # @yield [context, &block] Block to execute
+    # @yieldparam context [Hash] Request context
+    # @yieldparam block [Proc] Block to call to execute the request
+    # @return [self]
+    #
+    # @example Timing
+    #   config.around_request do |ctx, &block|
+    #     start = Time.now
+    #     response = block.call
+    #     puts "Request took #{Time.now - start}s"
+    #     response
+    #   end
+    def around_request(callable = nil, &block)
+      hooks.register(:around_request, callable, &block)
+      self
+    end
+
+    # Add a subscriber object for hook events
+    #
+    # Subscribers can implement any of: before_request, after_request,
+    # on_response, on_error, around_request.
+    #
+    # @param subscriber [Object] Object responding to hook methods
+    # @return [self]
+    #
+    # @example
+    #   class MySubscriber
+    #     def on_response(response, context)
+    #       puts response.status
+    #     end
+    #   end
+    #   config.add_subscriber(MySubscriber.new)
+    def add_subscriber(subscriber)
+      hooks.add_subscriber(subscriber)
+      self
+    end
+
     # Validate that required configuration is present
     #
     # @raise [ConfigurationError] if api_key is missing