patient_http 1.0.0

data/lib/patient_http/response.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Represents an HTTP response from an async request.
+  #
+  # This class encapsulates the response data including status, headers, body,
+  # and metadata about the request that generated it.
+  class Response
+    UNDEFINED = Object.new.freeze
+    private_constant :UNDEFINED
+
+    # @return [Integer] HTTP status code
+    attr_reader :status
+
+    # @return [HttpHeaders] response headers
+    attr_reader :headers
+
+    # @return [Float] request duration in seconds
+    attr_reader :duration
+
+    # @return [String] request ID
+    attr_reader :request_id
+
+    # @return [String] request URL
+    attr_reader :url
+
+    # @return [Symbol] HTTP method
+    attr_reader :http_method
+
+    # @return [Array<String>] URLs visited during redirect chain (empty if no redirects)
+    attr_reader :redirects
+
+    class << self
+      # Reconstruct a Response from a hash
+      #
+      # @param hash [Hash] hash representation
+      # @return [Response] reconstructed response
+      def load(hash)
+        new(
+          status: hash["status"],
+          headers: hash["headers"],
+          body: Payload.load(hash["body"])&.value,
+          duration: hash["duration"],
+          request_id: hash["request_id"],
+          url: hash["url"],
+          http_method: hash["http_method"]&.to_sym,
+          callback_args: hash["callback_args"],
+          redirects: hash["redirects"]
+        )
+      end
+    end
+
+    # Initialize a Response from an Async::HTTP::Response
+    #
+    # @param status [Integer] HTTP status code
+    # @param headers [Hash, HttpHeaders] response headers
+    # @param body [String, nil] response body
+    # @param duration [Float] request duration in seconds
+    # @param request_id [String] the request ID
+    # @param url [String] the request URL
+    # @param http_method [Symbol] the HTTP method
+    # @param callback_args [Hash, nil] callback arguments (string keys)
+    # @param redirects [Array<String>, nil] URLs visited during redirect chain
+    def initialize(status:, headers:, body:, duration:, request_id:, url:, http_method:, callback_args: nil, redirects: nil)
+      @status = status
+      @headers = HttpHeaders.new(headers)
+
+      encoding, encoded_body, charset = Payload.encode(body, @headers["content-type"])
+      @payload = Payload.new(encoding, encoded_body, charset) unless body.nil?
+      @body = UNDEFINED
+
+      @duration = duration
+      @request_id = request_id
+      @url = url
+      @http_method = http_method
+      @callback_args_data = callback_args || {}
+      @redirects = redirects || []
+    end
+
+    # Returns the callback arguments as a CallbackArgs object.
+    #
+    # @return [CallbackArgs] the callback arguments
+    def callback_args
+      @callback_args ||= CallbackArgs.load(@callback_args_data)
+    end
+
+    # Returns the response body, decoding it from the payload if necessary.
+    #
+    # @return [String, nil] The decoded response body or nil if there was no body.
+    def body
+      @body = @payload&.value if @body.equal?(UNDEFINED)
+      @body
+    end
+
+    # Check if response is successful (2xx status)
+    #
+    # @return [Boolean]
+    def success?
+      status >= 200 && status < 300
+    end
+
+    # Check if response is a redirect (3xx status)
+    #
+    # @return [Boolean]
+    def redirect?
+      status >= 300 && status < 400
+    end
+
+    # Check if response is a client error (4xx status)
+    #
+    # @return [Boolean]
+    def client_error?
+      status >= 400 && status < 500
+    end
+
+    # Check if response is a server error (5xx status)
+    #
+    # @return [Boolean]
+    def server_error?
+      status >= 500 && status < 600
+    end
+
+    # Check if response is any error (4xx or 5xx status)
+    #
+    # @return [Boolean]
+    def error?
+      status >= 400 && status < 600
+    end
+
+    # Get the Content-Type header
+    #
+    # @return [String, nil]
+    def content_type
+      headers["content-type"]
+    end
+
+    # Return true if Content-Type indicates JSON.
+    #
+    # @return [Boolean]
+    def json?
+      type = content_type.to_s.downcase
+      type.match?(%r{\Aapplication/[^ ]*json\b}) || type == "text/json"
+    end
+
+    # Parse response body as JSON
+    #
+    # @return [Hash, Array] parsed JSON
+    # @raise [RuntimeError] if Content-Type is not application/json
+    # @raise [JSON::ParserError] if body is not valid JSON
+    def json
+      unless json?
+        raise "Response Content-Type is not application/json (got: #{content_type.inspect})"
+      end
+
+      JSON.parse(body)
+    end
+
+    # Serialize to JSON hash.
+    #
+    # @return [Hash]
+    def as_json
+      {
+        "status" => status,
+        "headers" => headers.to_h,
+        "body" => @payload&.as_json,
+        "duration" => duration,
+        "request_id" => request_id,
+        "url" => url,
+        "http_method" => http_method.to_s,
+        "callback_args" => @callback_args_data,
+        "redirects" => @redirects
+      }
+    end
+
+    # Serialize to JSON string.
+    #
+    # @param options [Hash] options to pass to JSON.generate (for ActiveSupport compatibility)
+    # @return [String] JSON representation
+    def to_json(options = nil)
+      JSON.generate(as_json, options)
+    end
+  end
+end

data/lib/patient_http/response_reader.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Reads and validates HTTP response bodies.
+  #
+  # Encapsulates the logic for reading async HTTP responses with size validation
+  # and building Response objects from the raw response data.
+  class ResponseReader
+    # Initialize the reader.
+    #
+    # @param processor [Processor] the processor object
+    def initialize(processor)
+      @processor = processor
+    end
+
+    # Read the response body with size validation.
+    #
+    # Reads the async HTTP response body asynchronously to completion, which allows
+    # the connection to be reused. The async-http client handles connection pooling
+    # and keep-alive internally. Using iteration instead of read() ensures non-blocking
+    # I/O that yields to the reactor.
+    #
+    # @param async_response [Async::HTTP::Protocol::Response] the async HTTP response
+    # @param headers_hash [Hash] the response headers
+    # @return [String, nil] the response body or nil if no body present
+    # @raise [ResponseTooLargeError] if body exceeds max_response_size
+    def read_body(async_response, headers_hash)
+      return nil unless async_response.body
+
+      validate_content_length(headers_hash)
+      body = read_body_chunks(async_response)
+      apply_charset_encoding(body, headers_hash)
+    end
+
+    private
+
+    def max_response_size
+      @processor.config.max_response_size
+    end
+
+    def logger
+      @processor.config.logger
+    end
+
+    # Validate content-length header doesn't exceed max size.
+    #
+    # @param headers_hash [Hash] the response headers
+    # @raise [ResponseTooLargeError] if content-length exceeds max_response_size
+    def validate_content_length(headers_hash)
+      content_length = headers_hash["content-length"]&.to_i
+      if content_length && content_length > max_response_size
+        raise ResponseTooLargeError.new(
+          "Response body size (#{content_length} bytes) exceeds maximum allowed size (#{max_response_size} bytes)"
+        )
+      end
+    end
+
+    # Read body chunks while checking size.
+    #
+    # @param async_response [Async::HTTP::Protocol::Response] the async HTTP response
+    # @return [String, nil] the response body in ASCII-8BIT encoding, or nil if interrupted
+    # @raise [ResponseTooLargeError] if body size exceeds max_response_size during read
+    def read_body_chunks(async_response)
+      chunks = []
+      total_size = 0
+      finished = false
+
+      begin
+        async_response.body.each do |chunk|
+          # Check if processor is stopping/stopped (early exit during shutdown)
+          if @processor.stopping? || @processor.stopped?
+            return nil
+          end
+
+          total_size += chunk.bytesize
+
+          if total_size > max_response_size
+            raise ResponseTooLargeError.new(
+              "Response body size exceeded maximum allowed size (#{max_response_size} bytes)"
+            )
+          end
+
+          chunks << chunk
+        end
+
+        finished = true
+
+        # Join chunks and force to binary encoding to preserve raw bytes
+        chunks.join.force_encoding(Encoding::ASCII_8BIT)
+      ensure
+        # Always close the body if we were interrupted or if an error occurred
+        # This ensures the connection is properly released back to the pool
+        async_response.body.close unless finished
+      end
+    end
+
+    # Extract charset from Content-Type header.
+    #
+    # @param headers_hash [Hash] the response headers
+    # @return [String, nil] the charset name or nil if not specified
+    def extract_charset(headers_hash)
+      content_type = headers_hash["content-type"]
+      return nil unless content_type
+
+      match = content_type.match(/;\s*charset\s*=\s*([^;\s]+)/i)
+      return nil unless match
+
+      charset = match[1].strip
+      charset.gsub(/\A["']|["']\z/, "")
+    end
+
+    # Apply charset encoding to response body.
+    #
+    # Sets the string encoding based on the charset specified in the Content-Type header.
+    # Falls back to ASCII-8BIT if charset is invalid or not recognized.
+    #
+    # @param body [String] the response body
+    # @param headers_hash [Hash] the response headers
+    # @return [String] the body with proper encoding set
+    def apply_charset_encoding(body, headers_hash)
+      return body unless body
+
+      charset = extract_charset(headers_hash)
+      return body unless charset
+
+      begin
+        encoding = Encoding.find(charset)
+        body.force_encoding(encoding)
+      rescue ArgumentError
+        logger&.warn("[PatientHttp] Unknown charset '#{charset}' in Content-Type header")
+        body
+      end
+    end
+  end
+end

data/lib/patient_http/synchronous_executor.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Handles synchronous/inline execution of HTTP requests.
+  #
+  # Used for testing or when synchronous execution is needed.
+  # Accepts configuration and optional callback hooks so it has
+  # no dependency on any module-level singleton state.
+  class SynchronousExecutor
+    include RedirectHelper
+
+    # @param task [RequestTask] the request task to execute
+    # @param config [Configuration] the pool configuration
+    # @param on_complete [Proc, nil] hook called with response on success
+    # @param on_error [Proc, nil] hook called with error on failure
+    def initialize(task, config:, on_complete: nil, on_error: nil)
+      @task = task
+      @config = config
+      @on_complete = on_complete
+      @on_error = on_error
+      @proxy_client = nil
+    end
+
+    # Execute the request synchronously.
+    # @return [void]
+    def call
+      Async do
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        begin
+          http_client = nil
+          response_data = nil
+
+          loop do
+            http_client&.close
+            @proxy_client&.close
+            @proxy_client = nil
+            http_client = create_http_client
+            timeout = @task.request.timeout || @config.request_timeout
+
+            response_data = Async::Task.current.with_timeout(timeout) do
+              headers = @task.request.headers.to_h.merge("x-request-id" => @task.id)
+              headers["user-agent"] ||= @config.user_agent if @config.user_agent
+              body = Protocol::HTTP::Body::Buffered.wrap([@task.request.body.to_s]) if @task.request.body
+
+              endpoint = Async::HTTP::Endpoint.parse(@task.request.url)
+              endpoint = configure_endpoint(endpoint) if @config.connection_timeout
+
+              verb = @task.request.http_method.to_s.upcase
+              options = {
+                headers: headers,
+                body: body,
+                scheme: endpoint.scheme,
+                authority: endpoint.authority
+              }
+
+              request = Protocol::HTTP::Request[verb, endpoint.path, **options]
+              async_response = http_client.call(request)
+              headers_hash = async_response.headers.to_h.transform_values(&:to_s)
+
+              body_content = read_response_body(async_response, headers_hash)
+
+              {
+                status: async_response.status,
+                headers: headers_hash,
+                body: body_content
+              }
+            end
+
+            # Check for redirect
+            break unless should_follow_redirect?(@task, response_data)
+
+            redirect_error = check_redirect_error(@task, response_data)
+            if redirect_error
+              invoke_callback(redirect_error, :error)
+              return
+            end
+
+            location = response_data[:headers]["location"]
+            @task = @task.redirect_task(location: location, status: response_data[:status])
+          end
+
+          end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          duration = end_time - start_time
+
+          response = Response.new(
+            status: response_data[:status],
+            headers: response_data[:headers],
+            body: response_data[:body],
+            duration: duration,
+            request_id: @task.id,
+            url: @task.request.url,
+            http_method: @task.request.http_method,
+            callback_args: @task.callback_args,
+            redirects: @task.redirects
+          )
+
+          if @task.raise_error_responses && !response.success?
+            http_error = HttpError.new(response)
+            invoke_callback(http_error, :error)
+          else
+            invoke_callback(response, :response)
+          end
+        rescue => e
+          end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          duration = end_time - start_time
+
+          error = RequestError.from_exception(
+            e,
+            request_id: @task.id,
+            duration: duration,
+            url: @task.request.url,
+            http_method: @task.request.http_method,
+            callback_args: @task.callback_args
+          )
+          invoke_callback(error, :error)
+        ensure
+          http_client&.close
+          @proxy_client&.close
+          @proxy_client = nil
+        end
+      end
+    end
+
+    private
+
+    # Create HTTP client with config settings (retries, proxy, connection timeout).
+    #
+    # @return [Protocol::HTTP::AcceptEncoding] wrapped HTTP client
+    def create_http_client
+      endpoint = Async::HTTP::Endpoint.parse(@task.request.url)
+      endpoint = configure_endpoint(endpoint) if @config.connection_timeout
+
+      client = if @config.proxy_url
+        create_proxied_client(endpoint)
+      else
+        Async::HTTP::Client.new(endpoint, retries: @config.retries)
+      end
+
+      Protocol::HTTP::AcceptEncoding.new(client)
+    end
+
+    # Create a proxied HTTP client.
+    #
+    # @param endpoint [Async::HTTP::Endpoint] the target endpoint
+    # @return [Async::HTTP::Client] the proxied client
+    def create_proxied_client(endpoint)
+      require "async/http/proxy"
+
+      proxy_endpoint = Async::HTTP::Endpoint.parse(@config.proxy_url)
+      proxy_endpoint = configure_endpoint(proxy_endpoint) if @config.connection_timeout
+      @proxy_client = Async::HTTP::Client.new(proxy_endpoint)
+
+      proxy = @proxy_client.proxy(endpoint)
+      Async::HTTP::Client.new(proxy.wrap_endpoint(endpoint), retries: @config.retries)
+    end
+
+    # Configure endpoint with connection timeout if specified.
+    #
+    # @param endpoint [Async::HTTP::Endpoint] the endpoint to configure
+    # @return [Async::HTTP::Endpoint] the configured endpoint
+    def configure_endpoint(endpoint)
+      Async::HTTP::Endpoint.new(
+        endpoint.url,
+        timeout: @config.connection_timeout
+      )
+    end
+
+    # Read the response body with size validation.
+    #
+    # @param async_response [Async::HTTP::Protocol::Response] the async HTTP response
+    # @param headers_hash [Hash] the response headers
+    # @return [String, nil] the response body
+    def read_response_body(async_response, headers_hash)
+      return nil unless async_response.body
+
+      content_length = headers_hash["content-length"]&.to_i
+      if content_length && content_length > @config.max_response_size
+        raise ResponseTooLargeError.new(
+          "Response body size (#{content_length} bytes) exceeds maximum allowed size (#{@config.max_response_size} bytes)"
+        )
+      end
+
+      chunks = []
+      total_size = 0
+
+      async_response.body.each do |chunk|
+        total_size += chunk.bytesize
+        if total_size > @config.max_response_size
+          raise ResponseTooLargeError.new(
+            "Response body size exceeded maximum allowed size (#{@config.max_response_size} bytes)"
+          )
+        end
+        chunks << chunk
+      end
+
+      body = chunks.join.force_encoding(Encoding::ASCII_8BIT)
+
+      charset = extract_charset(headers_hash)
+      if charset
+        begin
+          encoding = Encoding.find(charset)
+          body.force_encoding(encoding)
+        rescue ArgumentError
+          # Invalid charset, keep binary
+        end
+      end
+
+      body
+    end
+
+    # Extract charset from Content-Type header.
+    def extract_charset(headers_hash)
+      content_type = headers_hash["content-type"]
+      return nil unless content_type
+
+      match = content_type.match(/;\s*charset\s*=\s*([^;\s]+)/i)
+      return nil unless match
+
+      charset = match[1].strip
+      charset.gsub(/\A["']|["']\z/, "")
+    end
+
+    # Invoke callback synchronously.
+    #
+    # @param result [Response, Error] the result to pass to callback
+    # @param type [Symbol] :response or :error
+    def invoke_callback(result, type)
+      callback_class = @task.callback.is_a?(Class) ? @task.callback : ClassHelper.resolve_class_name(@task.callback)
+      callback = callback_class.new
+
+      if type == :response
+        @on_complete&.call(result)
+        callback.on_complete(result)
+      else
+        @on_error&.call(result)
+        callback.on_error(result)
+      end
+    end
+  end
+end

data/lib/patient_http/task_handler.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Abstract base class for handling task lifecycle operations.
+  #
+  # TaskHandler abstracts the job system integration, allowing RequestTask
+  # to work with any job system without direct dependencies. Implementations
+  # handle completion callbacks, error callbacks, and job retry operations.
+  #
+  # @abstract Subclass and implement all methods to create a concrete handler.
+  #
+  # @example Creating a custom handler
+  #   class MyTaskHandler < PatientHttp::TaskHandler
+  #     def on_complete(response, callback)
+  #       # Trigger completion callback
+  #     end
+  #
+  #     def on_error(error, callback)
+  #       # Trigger error callback
+  #     end
+  #
+  #     def retry
+  #       # Re-enqueue the job
+  #     end
+  #   end
+  class TaskHandler
+    # Trigger the completion callback with the response.
+    #
+    # @param response [Response] the HTTP response object
+    # @param callback [String] callback class name
+    # @return [void]
+    def on_complete(response, callback)
+      raise NotImplementedError, "#{self.class}#on_complete must be implemented"
+    end
+
+    # Trigger the error callback with the error.
+    #
+    # @param error [Error] the error object
+    # @param callback [String] callback class name
+    # @return [void]
+    def on_error(error, callback)
+      raise NotImplementedError, "#{self.class}#on_error must be implemented"
+    end
+
+    # Re-enqueue the original job for retry.
+    #
+    # Called when a request cannot be completed (e.g., processor shutdown)
+    # and needs to be retried later.
+    #
+    # @return [String] the new job ID
+    def retry
+      raise NotImplementedError, "#{self.class}#retry must be implemented"
+    end
+  end
+end

data/lib/patient_http/time_helper.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Helper module for time-related operations using monotonic and wall clock time.
+  #
+  # This module provides utilities for accurate timing measurements that are immune
+  # to system clock changes, as well as conversion between monotonic and wall clock time.
+  module TimeHelper
+    extend self
+
+    # Get the current monotonic time.
+    #
+    # Monotonic time is guaranteed to be non-decreasing and immune to system clock changes.
+    #
+    # @return [Float] current monotonic time in seconds since an unspecified starting point
+    def monotonic_time
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
+
+    # Convert a monotonic timestamp to wall clock time.
+    #
+    # @param monotonic_timestamp [Float] monotonic timestamp to convert
+    # @return [Time] wall clock time corresponding to the monotonic timestamp
+    def wall_clock_time(monotonic_timestamp)
+      return nil unless monotonic_timestamp
+
+      now = Time.now
+      elapsed = monotonic_time - monotonic_timestamp
+      now - elapsed
+    end
+  end
+end