patient_http 1.0.0

data/lib/patient_http/callback_args.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Container for callback arguments that are passed to completion and error callbacks.
+  #
+  # CallbackArgs provides a structured way to access arguments passed from the original
+  # job to the callback workers. Arguments are stored with string keys internally
+  # (for JSON serialization compatibility) but can be accessed using either strings
+  # or symbols. All hash keys, including nested hashes and hashes within arrays, are
+  # deeply converted to strings.
+  #
+  # @example Basic usage
+  #   args = CallbackArgs.new(user_id: 123, action: "fetch")
+  #   args[:user_id]      # => 123
+  #   args["user_id"]     # => 123
+  #   args.fetch(:missing, "default")  # => "default"
+  #   args.include?(:user_id)  # => true
+  #   args.to_h           # => {user_id: 123, action: "fetch"}
+  #
+  # @example Nested hashes
+  #   args = CallbackArgs.new(metadata: {tags: ["a", "b"], level: 1})
+  #   args[:metadata]     # => {"tags" => ["a", "b"], "level" => 1}
+  #
+  # @example From a response object
+  #   response.callback_args[:user_id]
+  class CallbackArgs
+    # JSON-native types that are allowed as values
+    ALLOWED_TYPES = [NilClass, TrueClass, FalseClass, String, Integer, Float].freeze
+
+    class << self
+      # Reconstruct a CallbackArgs from a hash (used during deserialization).
+      #
+      # @param hash [Hash, nil] hash with string keys
+      # @return [CallbackArgs] reconstructed CallbackArgs
+      def load(hash)
+        new(hash || {}, validate: false)
+      end
+
+      # Validate that a value is a JSON-native type (recursively for arrays and hashes).
+      #
+      # @param value [Object] the value to validate
+      # @param path [String] the path to the value (for error messages)
+      # @raise [ArgumentError] if the value is not a JSON-native type
+      # @return [void]
+      def validate_value!(value, path = "value")
+        case value
+        when *ALLOWED_TYPES
+          # Valid primitive type
+        when Array
+          value.each_with_index do |element, index|
+            validate_value!(element, "#{path}[#{index}]")
+          end
+        when Hash
+          value.each do |key, val|
+            unless key.is_a?(String) || key.is_a?(Symbol)
+              raise ArgumentError.new("#{path} hash key must be a String or Symbol, got #{key.class.name}")
+            end
+
+            validate_value!(val, "#{path}[#{key.inspect}]")
+          end
+        else
+          raise ArgumentError.new("#{path} must be a JSON-native type (nil, true, false, String, Integer, Float, Array, or Hash), got #{value.class.name}")
+        end
+      end
+
+      # Deep convert all hash keys to strings, including nested hashes and hashes in arrays.
+      #
+      # @param value [Object] the value to convert
+      # @return [Object] the converted value with all hash keys as strings
+      def deep_stringify_keys(value)
+        case value
+        when Hash
+          value.transform_keys(&:to_s).transform_values { |v| deep_stringify_keys(v) }
+        when Array
+          value.map { |element| deep_stringify_keys(element) }
+        else
+          value
+        end
+      end
+    end
+
+    # Initialize a CallbackArgs with a hash.
+    #
+    # @param args [Hash, nil] arguments to store (keys will be deeply converted to strings)
+    # @param validate [Boolean] whether to validate values are JSON-native types
+    # @raise [ArgumentError] if args is not nil and doesn't respond to to_h
+    # @raise [ArgumentError] if any value is not a JSON-native type (when validate is true)
+    def initialize(args = nil, validate: true)
+      if args.nil?
+        @data = {}
+      elsif args.respond_to?(:to_h)
+        hash = args.to_h
+        if validate
+          hash.each do |key, value|
+            self.class.validate_value!(value, key.to_s)
+          end
+        end
+        @data = self.class.deep_stringify_keys(hash)
+      else
+        raise ArgumentError.new("callback_args must respond to to_h, got #{args.class.name}")
+      end
+    end
+
+    # Access an argument by key.
+    #
+    # @param key [String, Symbol] the key to access
+    # @return [Object] the value
+    # @raise [KeyError] if the key does not exist
+    def [](key)
+      string_key = key.to_s
+      unless @data.include?(string_key)
+        raise KeyError.new("key not found: #{key.inspect}. Available keys: #{@data.keys.join(", ")}")
+      end
+
+      @data[string_key]
+    end
+
+    # Access an argument by key with an optional default.
+    #
+    # @param key [String, Symbol] the key to access
+    # @param default [Object] the default value to return if key doesn't exist
+    # @return [Object] the value or default
+    def fetch(key, default = nil)
+      @data.fetch(key.to_s, default)
+    end
+
+    # Check if a key exists.
+    #
+    # @param key [String, Symbol] the key to check
+    # @return [Boolean] true if the key exists
+    def include?(key)
+      @data.include?(key.to_s)
+    end
+
+    # Convert to a hash with symbol keys (shallow).
+    #
+    # Only top-level keys are symbolized. Nested hash keys remain as strings.
+    #
+    # @return [Hash] hash with symbol keys
+    def to_h
+      @data.transform_keys(&:to_sym)
+    end
+
+    # Convert to hash with string keys for serialization.
+    #
+    # @return [Hash] hash with string keys
+    def as_json
+      @data.dup
+    end
+
+    alias_method :dump, :as_json
+
+    # Check if there are no arguments.
+    #
+    # @return [Boolean] true if empty
+    def empty?
+      @data.empty?
+    end
+
+    # Return the number of arguments.
+    #
+    # @return [Integer] the count
+    def size
+      @data.size
+    end
+
+    alias_method :length, :size
+
+    # Return the keys.
+    #
+    # @return [Array<String>] the keys
+    def keys
+      @data.keys
+    end
+  end
+end

data/lib/patient_http/callback_validator.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  module CallbackValidator
+    class << self
+      # Validate that the callback class defines the required methods.
+      #
+      # @param callback [Class, String] the callback class or its name
+      # @return [void]
+      # @raise [ArgumentError] if the callback class is invalid
+      def validate!(callback)
+        callback_class = callback.is_a?(Class) ? callback : ClassHelper.resolve_class_name(callback)
+
+        validate_callback_method!(callback_class, :on_complete)
+        validate_callback_method!(callback_class, :on_error)
+      end
+
+      # Validate callback_args and convert to a hash with string keys.
+      #
+      # @param callback_args [#to_h, nil] the callback arguments
+      # @return [Hash, nil] validated hash with string keys, or nil
+      # @raise [ArgumentError] if callback_args is invalid
+      def validate_callback_args(callback_args)
+        return nil if callback_args.nil?
+
+        unless callback_args.respond_to?(:to_h)
+          raise ArgumentError.new("callback_args must respond to to_h, got #{callback_args.class.name}")
+        end
+
+        hash = callback_args.to_h
+        hash.each do |key, value|
+          CallbackArgs.validate_value!(value, key.to_s)
+        end
+        hash.transform_keys(&:to_s)
+      end
+
+      private
+
+      def validate_callback_method!(callback_class, method_name)
+        unless callback_class.method_defined?(method_name)
+          raise ArgumentError.new("callback class must define ##{method_name} instance method")
+        end
+
+        method = callback_class.instance_method(method_name)
+        # arity of 1 = exactly 1 required arg, -1 = any args (*args), -2 = 1 required + splat
+        unless method.arity == 1 || method.arity == -1 || method.arity == -2
+          raise ArgumentError.new("callback class ##{method_name} must accept exactly 1 positional argument")
+        end
+      end
+    end
+  end
+end

data/lib/patient_http/class_helper.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Helper module for class-related operations.
+  #
+  # Provides utilities for resolving class names to class objects,
+  # which is useful for dynamic class loading.
+  module ClassHelper
+    extend self
+
+    # Resolve a class from its name class name to the class object.
+    #
+    # @param class_name [String] the fully qualified class name
+    # @return [Class, nil] the class object or nil if no class_name given
+    # @raise [NameError] if class cannot be found
+    def resolve_class_name(class_name)
+      return class_name if class_name.is_a?(Class)
+      return nil if class_name.nil? || class_name.empty?
+
+      hierarchy = class_name.split("::")
+      hierarchy.shift if hierarchy.first.to_s.empty? # strip leading :: for absolute names
+
+      hierarchy.reduce(Object) { |mod, name| mod.const_get(name) }
+    end
+  end
+end

data/lib/patient_http/client.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  class Client
+    def initialize(processor)
+      @processor = processor
+      @client_pool = ClientPool.new(
+        max_size: config.connection_pool_size,
+        connection_timeout: config.connection_timeout,
+        proxy_url: config.proxy_url,
+        retries: config.retries
+      )
+      @response_reader = ResponseReader.new(@processor)
+    end
+
+    # Make an asynchronous HTTP request.
+    #
+    # @param request [Request] the request to make
+    # @param request_id [String] unique request identifier
+    # @return [Hash] the response data with keys for :status, :headers, and :body
+    def make_request(request, request_id)
+      async_response = nil
+
+      begin
+        headers = request_headers(request, request_id)
+        body = Protocol::HTTP::Body::Buffered.wrap([request.body.to_s]) if request.body
+        timeout = request.timeout || config.request_timeout
+
+        Async::Task.current.with_timeout(timeout) do
+          async_response = @client_pool.request(request.http_method, request.url, headers, body)
+          headers_hash = async_response.headers.to_h.transform_values(&:to_s)
+          body = @response_reader.read_body(async_response, headers_hash)
+
+          {
+            status: async_response.status,
+            headers: headers_hash,
+            body: body
+          }
+        end
+      rescue => e
+        # Close the response and evict the client for this host to ensure the
+        # stale connection is not reused for subsequent requests.
+        async_response&.close
+        if connection_error?(e)
+          @client_pool.evict(request.url)
+        end
+        raise
+      end
+    end
+
+    # Close all clients and release resources.
+    #
+    # @return [void]
+    def close
+      @client_pool.close
+    end
+
+    private
+
+    def config
+      @processor.config
+    end
+
+    def connection_error?(exception)
+      case exception
+      when Async::TimeoutError, Errno::ECONNRESET, Errno::EPIPE, Errno::ECONNREFUSED,
+           Errno::EHOSTUNREACH, SocketError, IOError
+        true
+      else
+        false
+      end
+    end
+
+    def request_headers(request, request_id)
+      headers = request.headers.to_h.merge("x-request-id" => request_id)
+      headers["user-agent"] ||= config.user_agent if config.user_agent
+      headers
+    end
+  end
+end

data/lib/patient_http/client_pool.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Pool of HTTP clients with LRU eviction.
+  #
+  # Maintains a pool of clients lazily instantiated for each host. The pool
+  # is capped with an LRU algorithm - when a new client is needed and the
+  # pool is at capacity, the least recently used client is closed and removed.
+  class ClientPool
+    def initialize(max_size:, connection_timeout: nil, proxy_url: nil, retries: 3)
+      @clients = {}
+      @max_size = max_size
+      @connection_timeout = connection_timeout
+      @proxy_url = proxy_url
+      @retries = retries
+      @mutex = Mutex.new
+      @proxy_client = nil
+    end
+
+    attr_reader :max_size, :connection_timeout, :proxy_url, :retries
+
+    # Get or create a client for the given endpoint.
+    #
+    # @param endpoint [Async::HTTP::Endpoint] the target endpoint
+    # @return [Protocol::HTTP::AcceptEncoding] wrapped client
+    def client_for(endpoint)
+      key = host_key(endpoint)
+
+      @mutex.synchronize do
+        if @clients.key?(key)
+          # Move to end (most recently used) by re-inserting
+          client = @clients.delete(key)
+          @clients[key] = client
+          return client
+        end
+
+        evict_lru if @clients.size >= @max_size
+        @clients[key] = make_client(endpoint)
+      end
+    end
+
+    # Make a request.
+    #
+    # @param http_method [String, Symbol] HTTP method
+    # @param url [String] request URL
+    # @param headers [Hash] request headers
+    # @param body [String, nil] request body
+    # @param block [Proc] optional block to process the response
+    # @return [Protocol::HTTP::Response] the response
+    def request(http_method, url, headers, body, &block)
+      endpoint = Async::HTTP::Endpoint.parse(url)
+      client = client_for(endpoint)
+
+      verb = http_method.to_s.upcase
+
+      options = {
+        headers: headers,
+        body: body,
+        scheme: endpoint.scheme,
+        authority: endpoint.authority
+      }
+
+      request = ::Protocol::HTTP::Request[verb, endpoint.path, **options]
+      response = client.call(request)
+
+      return response unless block_given?
+
+      begin
+        yield response
+      ensure
+        response.close
+      end
+    end
+
+    # Close all clients and release resources.
+    #
+    # @return [void]
+    def close
+      @mutex.synchronize do
+        @clients.each_value do |client|
+          client.close
+        rescue
+          nil
+        end
+        @clients.clear
+
+        begin
+          @proxy_client&.close
+        rescue
+          nil
+        end
+        @proxy_client = nil
+      end
+    end
+
+    # Evict and close the client for the given URL.
+    #
+    # This forces a new connection to be established on the next request to this host.
+    #
+    # @param url [String] the request URL whose host client should be evicted
+    # @return [void]
+    def evict(url)
+      endpoint = Async::HTTP::Endpoint.parse(url)
+      key = host_key(endpoint)
+
+      @mutex.synchronize do
+        client = @clients.delete(key)
+        begin
+          client&.close
+        rescue
+          nil
+        end
+      end
+    end
+
+    # @return [Integer] number of clients in the pool
+    def size
+      @mutex.synchronize { @clients.size }
+    end
+
+    private
+
+    def evict_lru
+      lru_key, lru_client = @clients.first
+      return unless lru_key
+
+      @clients.delete(lru_key)
+      begin
+        lru_client.close
+      rescue
+        nil
+      end
+    end
+
+    def host_key(endpoint)
+      url = endpoint.url.dup
+      url.path = ""
+      url.fragment = nil
+      url.query = nil
+      url
+    end
+
+    def make_client(endpoint)
+      client = @proxy_url ? make_proxied_client(endpoint) : make_direct_client(endpoint)
+      ::Protocol::HTTP::AcceptEncoding.new(client)
+    end
+
+    def make_direct_client(endpoint)
+      configured_endpoint = configure_endpoint(endpoint)
+      Async::HTTP::Client.new(configured_endpoint, retries: @retries)
+    end
+
+    def make_proxied_client(endpoint)
+      require "async/http/proxy"
+
+      @proxy_client ||= create_proxy_client
+      configured_endpoint = configure_endpoint(endpoint)
+
+      proxy = @proxy_client.proxy(configured_endpoint)
+      Async::HTTP::Client.new(proxy.wrap_endpoint(configured_endpoint), retries: @retries)
+    end
+
+    def create_proxy_client
+      proxy_endpoint = Async::HTTP::Endpoint.parse(@proxy_url)
+      proxy_endpoint = configure_endpoint(proxy_endpoint) if @connection_timeout
+      Async::HTTP::Client.new(proxy_endpoint)
+    end
+
+    def configure_endpoint(endpoint)
+      return endpoint unless @connection_timeout
+
+      Async::HTTP::Endpoint.new(
+        endpoint.url,
+        timeout: @connection_timeout
+      )
+    end
+  end
+end