zenrows 0.2.1 → 0.3.0

data/lib/zenrows/hooks/context.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Zenrows
+  class Hooks
+    # Builds context hashes for hook callbacks
+    #
+    # Provides methods to create and enrich context objects passed to hooks.
+    # Handles parsing of ZenRows-specific response headers.
+    #
+    # @author Ernest Bursa
+    # @since 0.3.0
+    # @api private
+    class Context
+      # ZenRows response headers to parse
+      ZENROWS_HEADERS = {
+        "Concurrency-Limit" => :concurrency_limit,
+        "Concurrency-Remaining" => :concurrency_remaining,
+        "X-Request-Cost" => :request_cost,
+        "X-Request-Id" => :request_id,
+        "Zr-Final-Url" => :final_url
+      }.freeze
+
+      class << self
+        # Build context for a request
+        #
+        # @param method [Symbol] HTTP method (:get, :post, etc.)
+        # @param url [String] Target URL
+        # @param options [Hash] ZenRows options used for the request
+        # @param backend [Symbol] Backend name (:http_rb, :net_http)
+        # @return [Hash] Request context
+        def for_request(method:, url:, options:, backend:)
+          uri = parse_uri(url)
+
+          {
+            method: method,
+            url: url,
+            host: uri&.host,
+            options: options.dup.freeze,
+            started_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
+            backend: backend,
+            zenrows_headers: {}
+          }
+        end
+
+        # Enrich context with response data
+        #
+        # Adds timing information and parses ZenRows headers from response.
+        #
+        # @param context [Hash] Existing request context
+        # @param response [Object] HTTP response object
+        # @return [Hash] Enriched context
+        def enrich_with_response(context, response)
+          headers = extract_headers(response)
+          context[:zenrows_headers] = parse_zenrows_headers(headers)
+          context[:completed_at] = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          context[:duration] = context[:completed_at] - context[:started_at]
+          context
+        end
+
+        private
+
+        # Safely parse URI
+        #
+        # @param url [String] URL to parse
+        # @return [URI, nil] Parsed URI or nil if invalid
+        def parse_uri(url)
+          URI.parse(url.to_s)
+        rescue URI::InvalidURIError
+          nil
+        end
+
+        # Extract headers from response object
+        #
+        # Handles different response object types (http.rb, Net::HTTP, etc.)
+        #
+        # @param response [Object] HTTP response object
+        # @return [Hash] Headers as hash
+        def extract_headers(response)
+          case response
+          when ->(r) { r.respond_to?(:headers) }
+            headers_to_hash(response.headers)
+          when ->(r) { r.respond_to?(:to_hash) }
+            response.to_hash
+          when ->(r) { r.respond_to?(:each_header) }
+            # Net::HTTPResponse
+            {}.tap { |h| response.each_header { |k, v| h[k] = v } }
+          else
+            {}
+          end
+        end
+
+        # Convert headers object to hash
+        #
+        # @param headers [Object] Headers object
+        # @return [Hash] Headers as hash
+        def headers_to_hash(headers)
+          if headers.respond_to?(:to_h)
+            headers.to_h
+          elsif headers.respond_to?(:to_hash)
+            headers.to_hash
+          else
+            {}
+          end
+        end
+
+        # Parse ZenRows-specific headers
+        #
+        # @param headers [Hash] Response headers
+        # @return [Hash] Parsed ZenRows headers with typed values
+        def parse_zenrows_headers(headers)
+          result = {}
+
+          ZENROWS_HEADERS.each do |header, key|
+            # Try both exact case and lowercase
+            value = headers[header] || headers[header.downcase]
+            next unless value
+
+            result[key] = cast_header_value(key, value)
+          end
+
+          result
+        end
+
+        # Cast header value to appropriate type
+        #
+        # @param key [Symbol] Header key
+        # @param value [String] Raw header value
+        # @return [Object] Typed value
+        def cast_header_value(key, value)
+          case key
+          when :request_cost
+            value.to_f
+          when :concurrency_limit, :concurrency_remaining
+            value.to_i
+          else
+            value.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zenrows/hooks/log_subscriber.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Zenrows
+  class Hooks
+    # Built-in logging subscriber for ZenRows requests
+    #
+    # Logs request lifecycle events using a configurable logger.
+    # Uses lazy evaluation (blocks) to avoid string interpolation overhead
+    # when log level is not enabled.
+    #
+    # @example Basic usage
+    #   Zenrows.configure do |c|
+    #     c.logger = Logger.new(STDOUT)
+    #     c.add_subscriber(Zenrows::Hooks::LogSubscriber.new)
+    #   end
+    #
+    # @example With custom logger
+    #   subscriber = Zenrows::Hooks::LogSubscriber.new(logger: Rails.logger)
+    #   Zenrows.configure { |c| c.add_subscriber(subscriber) }
+    #
+    # @author Ernest Bursa
+    # @since 0.3.0
+    # @api public
+    class LogSubscriber
+      # @return [Logger, nil] Logger instance
+      attr_reader :logger
+
+      # Create a new log subscriber
+      #
+      # @param logger [Logger, nil] Logger instance. If nil, uses Zenrows.configuration.logger
+      def initialize(logger: nil)
+        @logger = logger
+      end
+
+      # Log before request starts
+      #
+      # @param context [Hash] Request context
+      def before_request(context)
+        log(:debug) do
+          "ZenRows request: #{context[:method].to_s.upcase} #{context[:url]}"
+        end
+      end
+
+      # Log successful response
+      #
+      # @param response [Object] HTTP response
+      # @param context [Hash] Request context
+      def on_response(response, context)
+        status = extract_status(response)
+        duration = format_duration(context[:duration])
+        cost = context.dig(:zenrows_headers, :request_cost)
+
+        message = "ZenRows #{context[:url]} -> #{status}"
+        message += " (#{duration})" if duration
+        message += " [cost: #{cost}]" if cost
+
+        log(:info) { message }
+      end
+
+      # Log error
+      #
+      # @param error [Exception] The error that occurred
+      # @param context [Hash] Request context
+      def on_error(error, context)
+        request_id = context.dig(:zenrows_headers, :request_id)
+
+        message = "ZenRows #{context[:url]} failed: #{error.class} - #{error.message}"
+        message += " [request_id: #{request_id}]" if request_id
+
+        log(:error) { message }
+      end
+
+      private
+
+      # Get the effective logger
+      #
+      # @return [Logger, nil] Logger to use
+      def effective_logger
+        @logger || Zenrows.configuration.logger
+      end
+
+      # Log a message at the specified level
+      #
+      # @param level [Symbol] Log level (:debug, :info, :warn, :error)
+      # @yield Block returning the message to log
+      def log(level, &block)
+        return unless effective_logger
+
+        if effective_logger.respond_to?(level)
+          effective_logger.public_send(level, &block)
+        end
+      end
+
+      # Extract status from response object
+      #
+      # @param response [Object] HTTP response
+      # @return [String] Status string
+      def extract_status(response)
+        if response.respond_to?(:status)
+          status = response.status
+          status.respond_to?(:code) ? status.code : status.to_s
+        elsif response.respond_to?(:code)
+          response.code
+        else
+          "unknown"
+        end
+      end
+
+      # Format duration for display
+      #
+      # @param duration [Float, nil] Duration in seconds
+      # @return [String, nil] Formatted duration
+      def format_duration(duration)
+        return nil unless duration
+
+        if duration < 1
+          "#{(duration * 1000).round}ms"
+        else
+          "#{duration.round(2)}s"
+        end
+      end
+    end
+  end
+end

data/lib/zenrows/hooks.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Zenrows
+  # Thread-safe hook registry for request lifecycle events
+  #
+  # Manages registration and execution of callbacks for HTTP request events.
+  # Supports both block-based callbacks and subscriber objects.
+  #
+  # @example Register a block callback
+  #   hooks = Zenrows::Hooks.new
+  #   hooks.register(:on_response) { |response, context| puts response.status }
+  #
+  # @example Register a subscriber object
+  #   class MySubscriber
+  #     def on_response(response, context)
+  #       puts response.status
+  #     end
+  #   end
+  #   hooks.add_subscriber(MySubscriber.new)
+  #
+  # @author Ernest Bursa
+  # @since 0.3.0
+  # @api public
+  class Hooks
+    include MonitorMixin
+
+    # Available hook events
+    EVENTS = %i[before_request after_request on_response on_error around_request].freeze
+
+    def initialize
+      super # Initialize MonitorMixin
+      @callbacks = Hash.new { |h, k| h[k] = [] }
+      @subscribers = []
+    end
+
+    # Register a callback for an event
+    #
+    # @param event [Symbol] Event name (:before_request, :after_request, :on_response, :on_error, :around_request)
+    # @param callable [#call, nil] Callable object (proc, lambda, or object responding to #call)
+    # @yield Block to execute when event fires
+    # @return [self] Returns self for chaining
+    # @raise [ArgumentError] if event is unknown or handler doesn't respond to #call
+    #
+    # @example With block
+    #   hooks.register(:on_response) { |response, ctx| log(response) }
+    #
+    # @example With callable
+    #   hooks.register(:on_response, ->(response, ctx) { log(response) })
+    def register(event, callable = nil, &block)
+      validate_event!(event)
+      handler = callable || block
+      raise ArgumentError, "Handler must respond to #call" unless handler.respond_to?(:call)
+
+      synchronize { @callbacks[event] << handler }
+      self
+    end
+
+    # Add a subscriber object that responds to hook methods
+    #
+    # Subscriber objects can implement any of the hook methods:
+    # - before_request(context)
+    # - after_request(context)
+    # - on_response(response, context)
+    # - on_error(error, context)
+    # - around_request(context, &block)
+    #
+    # @param subscriber [Object] Object responding to one or more hook methods
+    # @return [self] Returns self for chaining
+    #
+    # @example
+    #   class MetricsSubscriber
+    #     def on_response(response, context)
+    #       StatsD.increment('requests')
+    #     end
+    #   end
+    #   hooks.add_subscriber(MetricsSubscriber.new)
+    def add_subscriber(subscriber)
+      unless EVENTS.any? { |e| subscriber.respond_to?(e) }
+        warn "ZenRows: Subscriber #{subscriber.class} doesn't respond to any hook events"
+      end
+      synchronize { @subscribers << subscriber }
+      self
+    end
+
+    # Run callbacks for an event
+    #
+    # @param event [Symbol] Event name
+    # @param args [Array] Arguments to pass to callbacks
+    # @return [void]
+    def run(event, *args)
+      handlers, subscribers = synchronize do
+        [@callbacks[event].dup, @subscribers.dup]
+      end
+
+      # Run registered callbacks
+      handlers.each { |h| h.call(*args) }
+
+      # Run subscriber methods
+      subscribers.each do |sub|
+        sub.public_send(event, *args) if sub.respond_to?(event)
+      end
+    end
+
+    # Run around callbacks (wrapping)
+    #
+    # Executes a chain of around handlers, each wrapping the next.
+    # If no around handlers exist, simply yields to the block.
+    #
+    # @param context [Hash] Request context
+    # @yield Block to wrap (the actual HTTP request)
+    # @return [Object] Result of the wrapped block
+    def run_around(context, &block)
+      handlers, subscribers = synchronize do
+        [@callbacks[:around_request].dup, @subscribers.dup]
+      end
+
+      # Build chain of around handlers
+      chain = handlers + subscribers.select { |s| s.respond_to?(:around_request) }
+
+      if chain.empty?
+        block.call
+      else
+        execute_chain(chain, context, &block)
+      end
+    end
+
+    # Check if any hooks are registered
+    #
+    # @return [Boolean] true if no hooks registered
+    def empty?
+      synchronize { @callbacks.values.all?(&:empty?) && @subscribers.empty? }
+    end
+
+    # Merge hooks from another registry
+    #
+    # Used for per-client hooks that inherit from global hooks.
+    #
+    # @param other [Hooks, nil] Another hooks registry to merge
+    # @return [self]
+    def merge(other)
+      return self unless other
+
+      synchronize do
+        EVENTS.each do |event|
+          @callbacks[event].concat(other.callbacks_for(event))
+        end
+        @subscribers.concat(other.subscribers_list)
+      end
+      self
+    end
+
+    # Duplicate the hooks registry
+    #
+    # @return [Hooks] New hooks registry with copied callbacks
+    def dup
+      copy = Hooks.new
+      synchronize do
+        EVENTS.each { |e| @callbacks[e].each { |h| copy.register(e, h) } }
+        @subscribers.each { |s| copy.add_subscriber(s) }
+      end
+      copy
+    end
+
+    protected
+
+    # Get callbacks for a specific event (for merging)
+    #
+    # @param event [Symbol] Event name
+    # @return [Array] Copy of callbacks for the event
+    def callbacks_for(event)
+      synchronize { @callbacks[event].dup }
+    end
+
+    # Get subscribers list (for merging)
+    #
+    # @return [Array] Copy of subscribers
+    def subscribers_list
+      synchronize { @subscribers.dup }
+    end
+
+    private
+
+    # Validate event name
+    #
+    # @param event [Symbol] Event name
+    # @raise [ArgumentError] if event is unknown
+    def validate_event!(event)
+      return if EVENTS.include?(event)
+
+      raise ArgumentError, "Unknown event: #{event}. Valid events: #{EVENTS.join(", ")}"
+    end
+
+    # Execute chain of around handlers
+    #
+    # @param chain [Array] Array of around handlers
+    # @param context [Hash] Request context
+    # @yield Block to wrap
+    # @return [Object] Result of the wrapped block
+    def execute_chain(chain, context, &block)
+      chain.reverse.reduce(block) do |next_block, handler|
+        lambda {
+          if handler.respond_to?(:around_request)
+            handler.around_request(context, &next_block)
+          else
+            handler.call(context, &next_block)
+          end
+        }
+      end.call
+    end
+  end
+end

data/lib/zenrows/instrumented_client.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Zenrows
+  # Wrapper around HTTP clients that executes hooks on requests
+  #
+  # Decorates an HTTP client (from http.rb or Net::HTTP) to add
+  # hook execution before, during, and after requests.
+  #
+  # @example
+  #   client = InstrumentedClient.new(http_client,
+  #     hooks: hooks_registry,
+  #     context_base: { backend: :http_rb, options: { js_render: true } }
+  #   )
+  #   response = client.get("https://example.com")
+  #
+  # @author Ernest Bursa
+  # @since 0.3.0
+  # @api private
+  class InstrumentedClient
+    # HTTP methods to instrument
+    HTTP_METHODS = %i[get post put patch delete head options].freeze
+
+    # @return [Object] Underlying HTTP client
+    attr_reader :http
+
+    # @return [Hooks] Hook registry
+    attr_reader :hooks
+
+    # @return [Hash] Base context for all requests
+    attr_reader :context_base
+
+    # Create a new instrumented client
+    #
+    # @param http [Object] Underlying HTTP client (HTTP::Client, NetHttpClient, etc.)
+    # @param hooks [Hooks] Hook registry to use
+    # @param context_base [Hash] Base context to merge into all requests
+    def initialize(http, hooks:, context_base:)
+      @http = http
+      @hooks = hooks
+      @context_base = context_base
+    end
+
+    # Instrumented GET request
+    #
+    # @param url [String] URL to request
+    # @param options [Hash] Request options
+    # @return [Object] HTTP response
+    def get(url, **options)
+      instrument(:get, url, options) { @http.get(url, **options) }
+    end
+
+    # Instrumented POST request
+    #
+    # @param url [String] URL to request
+    # @param options [Hash] Request options
+    # @return [Object] HTTP response
+    def post(url, **options)
+      instrument(:post, url, options) { @http.post(url, **options) }
+    end
+
+    # Instrumented PUT request
+    #
+    # @param url [String] URL to request
+    # @param options [Hash] Request options
+    # @return [Object] HTTP response
+    def put(url, **options)
+      instrument(:put, url, options) { @http.put(url, **options) }
+    end
+
+    # Instrumented PATCH request
+    #
+    # @param url [String] URL to request
+    # @param options [Hash] Request options
+    # @return [Object] HTTP response
+    def patch(url, **options)
+      instrument(:patch, url, options) { @http.patch(url, **options) }
+    end
+
+    # Instrumented DELETE request
+    #
+    # @param url [String] URL to request
+    # @param options [Hash] Request options
+    # @return [Object] HTTP response
+    def delete(url, **options)
+      instrument(:delete, url, options) { @http.delete(url, **options) }
+    end
+
+    # Instrumented HEAD request
+    #
+    # @param url [String] URL to request
+    # @param options [Hash] Request options
+    # @return [Object] HTTP response
+    def head(url, **options)
+      instrument(:head, url, options) { @http.head(url, **options) }
+    end
+
+    # Instrumented OPTIONS request
+    #
+    # @param url [String] URL to request
+    # @param options [Hash] Request options
+    # @return [Object] HTTP response
+    def options(url, **options)
+      instrument(:options, url, options) { @http.options(url, **options) }
+    end
+
+    # Delegate unknown methods to underlying client
+    #
+    # @param method [Symbol] Method name
+    # @param args [Array] Method arguments
+    # @param kwargs [Hash] Keyword arguments
+    # @param block [Proc] Block to pass
+    # @return [Object] Result of delegated method
+    def method_missing(method, *args, **kwargs, &block)
+      if @http.respond_to?(method)
+        @http.public_send(method, *args, **kwargs, &block)
+      else
+        super
+      end
+    end
+
+    # Check if method is supported
+    #
+    # @param method [Symbol] Method name
+    # @param include_private [Boolean] Include private methods
+    # @return [Boolean] true if method is supported
+    def respond_to_missing?(method, include_private = false)
+      @http.respond_to?(method, include_private) || super
+    end
+
+    private
+
+    # Instrument an HTTP request with hooks
+    #
+    # @param method [Symbol] HTTP method
+    # @param url [String] Request URL
+    # @param options [Hash] Request options
+    # @yield Block that executes the actual HTTP request
+    # @return [Object] HTTP response
+    def instrument(method, url, options, &block)
+      context = build_context(method, url, options)
+
+      # Run before hooks
+      hooks.run(:before_request, context)
+
+      # Run around hooks and execute request
+      response = hooks.run_around(context) do
+        execute_request(context, &block)
+      end
+
+      response
+    ensure
+      # Run after hooks (always, even on error)
+      hooks.run(:after_request, context) if context
+    end
+
+    # Build context for a request
+    #
+    # @param method [Symbol] HTTP method
+    # @param url [String] Request URL
+    # @param options [Hash] Request options
+    # @return [Hash] Request context
+    def build_context(method, url, options)
+      Hooks::Context.for_request(
+        method: method,
+        url: url,
+        options: context_base[:options].merge(options),
+        backend: context_base[:backend]
+      )
+    end
+
+    # Execute the actual request with error handling
+    #
+    # @param context [Hash] Request context
+    # @yield Block that executes the HTTP request
+    # @return [Object] HTTP response
+    def execute_request(context)
+      response = yield
+      Hooks::Context.enrich_with_response(context, response)
+      hooks.run(:on_response, response, context)
+      response
+    rescue => e
+      context[:error] = e
+      hooks.run(:on_error, e, context)
+      raise
+    end
+  end
+end

data/lib/zenrows/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zenrows
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/zenrows.rb

@@ -2,9 +2,13 @@
 
 require_relative "zenrows/version"
 require_relative "zenrows/errors"
+require_relative "zenrows/hooks"
+require_relative "zenrows/hooks/context"
+require_relative "zenrows/hooks/log_subscriber"
 require_relative "zenrows/configuration"
 require_relative "zenrows/proxy"
 require_relative "zenrows/js_instructions"
+require_relative "zenrows/instrumented_client"
 require_relative "zenrows/backends/base"
 require_relative "zenrows/backends/net_http"
 begin

data/sig/zenrows/api_client.rbs

@@ -2,13 +2,16 @@ class Zenrows::ApiClient
   attr_reader api_key: String
   attr_reader api_endpoint: String
   attr_reader config: Zenrows::Configuration
+  attr_reader hooks: Zenrows::Hooks
 
-  def initialize: (?api_key: String?, ?api_endpoint: String?) -> void
+  def initialize: (?api_key: String?, ?api_endpoint: String?) ?{ (Zenrows::HookConfigurator) -> void } -> void
   def get: (String url, **untyped options) -> Zenrows::ApiResponse
   def post: (String url, ?body: String?, **untyped options) -> Zenrows::ApiResponse
 
   private
 
+  def build_hooks: () { (Zenrows::HookConfigurator) -> void } -> Zenrows::Hooks
+  def instrument: (Symbol method, String url, Hash[Symbol, untyped] options) { () -> untyped } -> untyped
   def build_http_client: () -> untyped
   def build_params: (String url, Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]
   def handle_response: (untyped http_response, Hash[Symbol, untyped] options) -> Zenrows::ApiResponse