patient_http 1.0.0

data/lib/patient_http/redirect_error.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Base class for redirect-related errors.
+  # These errors occur when redirect handling fails due to too many redirects
+  # or a redirect loop.
+  class RedirectError < Error
+    # @return [String] Request URL
+    attr_reader :url
+
+    # @return [Symbol] HTTP method
+    attr_reader :http_method
+
+    # @return [Float] Request duration in seconds
+    attr_reader :duration
+
+    # @return [String] Unique request identifier
+    attr_reader :request_id
+
+    # @return [Array<String>] URLs that were visited during redirect chain
+    attr_reader :redirects
+
+    class << self
+      # Reconstruct a RedirectError from a hash
+      #
+      # @param hash [Hash] hash representation
+      # @return [RedirectError] reconstructed error
+      def load(hash)
+        error_class = ClassHelper.resolve_class_name(hash["error_class"])
+        error_class.new(
+          url: hash["url"],
+          http_method: hash["http_method"]&.to_sym,
+          duration: hash["duration"],
+          request_id: hash["request_id"],
+          redirects: hash["redirects"] || [],
+          callback_args: hash["callback_args"]
+        )
+      end
+    end
+
+    # Initializes a new RedirectError.
+    #
+    # @param message [String] Error message
+    # @param url [String] Request URL
+    # @param http_method [Symbol, String] HTTP method
+    # @param duration [Float] Request duration in seconds
+    # @param request_id [String] Unique request identifier
+    # @param redirects [Array<String>] URLs visited during redirect chain
+    # @param callback_args [Hash, nil] callback arguments (string keys)
+    def initialize(message, url:, http_method:, duration:, request_id:, redirects:, callback_args: nil)
+      super(message)
+      @url = url
+      @http_method = http_method&.to_sym
+      @duration = duration
+      @request_id = request_id
+      @redirects = redirects || []
+      @callback_args_data = callback_args || {}
+    end
+
+    # Returns the error type symbol.
+    #
+    # @return [Symbol] the error type
+    def error_type
+      :redirect
+    end
+
+    # @return [Class] the class of the exception. This is for compatibility with RequestError.
+    def error_class
+      self.class
+    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
+
+    # Convert to hash with string keys for serialization
+    #
+    # @return [Hash] hash representation
+    def as_json
+      {
+        "error_class" => self.class.name,
+        "url" => url,
+        "http_method" => http_method.to_s,
+        "duration" => duration,
+        "request_id" => request_id,
+        "redirects" => redirects,
+        "callback_args" => @callback_args_data
+      }
+    end
+  end
+
+  # Error raised when too many redirects are encountered.
+  class TooManyRedirectsError < RedirectError
+    # @param url [String] The URL that would have been redirected to
+    # @param http_method [Symbol, String] HTTP method
+    # @param duration [Float] Request duration in seconds
+    # @param request_id [String] Unique request identifier
+    # @param redirects [Array<String>] URLs visited during redirect chain
+    # @param callback_args [Hash, nil] callback arguments (string keys)
+    def initialize(url:, http_method:, duration:, request_id:, redirects:, callback_args: nil)
+      super(
+        "Too many redirects (#{redirects.size}) while requesting #{http_method.to_s.upcase} #{redirects.first || url}",
+        url: url,
+        http_method: http_method,
+        duration: duration,
+        request_id: request_id,
+        redirects: redirects,
+        callback_args: callback_args
+      )
+    end
+  end
+
+  # Error raised when a recursive redirect is detected.
+  class RecursiveRedirectError < RedirectError
+    # @param url [String] The URL that caused the loop
+    # @param http_method [Symbol, String] HTTP method
+    # @param duration [Float] Request duration in seconds
+    # @param request_id [String] Unique request identifier
+    # @param redirects [Array<String>] URLs visited during redirect chain
+    # @param callback_args [Hash, nil] callback arguments (string keys)
+    def initialize(url:, http_method:, duration:, request_id:, redirects:, callback_args: nil)
+      super(
+        "Recursive redirect detected: #{url} was already visited in redirect chain",
+        url: url,
+        http_method: http_method,
+        duration: duration,
+        request_id: request_id,
+        redirects: redirects,
+        callback_args: callback_args
+      )
+    end
+  end
+end

data/lib/patient_http/redirect_helper.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Shared redirect-checking logic used by both the async Processor
+  # and the SynchronousExecutor.
+  #
+  # @api private
+  module RedirectHelper
+    private
+
+    # Check if a redirect response should be followed.
+    #
+    # @param task [RequestTask] the request task
+    # @param response_data [Hash] the response data with status, headers, body
+    # @return [Boolean] true if the redirect should be followed
+    def should_follow_redirect?(task, response_data)
+      status = response_data[:status]
+      return false unless FOLLOWABLE_REDIRECT_STATUSES.include?(status)
+      return false if task.max_redirects == 0
+
+      location = response_data[:headers]["location"]
+      return false if location.nil? || location.empty?
+
+      true
+    end
+
+    # Check for either too-many-redirects or recursive redirect.
+    #
+    # @param task [RequestTask] the request task
+    # @param response_data [Hash] the response data with status, headers, body
+    # @return [RedirectError, nil] error if redirect should not proceed, nil otherwise
+    def check_redirect_error(task, response_data)
+      location = response_data[:headers]["location"]
+      redirect_url = resolve_redirect_url(task.request.url, location)
+
+      check_too_many_redirects(task, location) || check_recursive_redirect(task, redirect_url)
+    end
+
+    # Check if the redirect count has exceeded the maximum.
+    #
+    # @param task [RequestTask] the request task
+    # @param location [String] the redirect location URL
+    # @return [TooManyRedirectsError, nil] error if exceeded, nil otherwise
+    def check_too_many_redirects(task, location)
+      return nil if task.redirects.size < task.max_redirects
+
+      TooManyRedirectsError.new(
+        url: location,
+        http_method: task.request.http_method,
+        duration: task.duration,
+        request_id: task.id,
+        redirects: task.redirects + [task.request.url],
+        callback_args: task.callback_args
+      )
+    end
+
+    # Check if the redirect URL has already been visited (redirect loop).
+    #
+    # @param task [RequestTask] the request task
+    # @param redirect_url [String] the resolved redirect URL
+    # @return [RecursiveRedirectError, nil] error if loop detected, nil otherwise
+    def check_recursive_redirect(task, redirect_url)
+      visited_urls = task.redirects + [task.request.url]
+      return nil unless visited_urls.include?(redirect_url)
+
+      RecursiveRedirectError.new(
+        url: redirect_url,
+        http_method: task.request.http_method,
+        duration: task.duration,
+        request_id: task.id,
+        redirects: visited_urls,
+        callback_args: task.callback_args
+      )
+    end
+
+    # Resolve a redirect URL, handling relative URLs.
+    #
+    # @param base_url [String] The base URL
+    # @param location [String] The Location header value
+    # @return [String] The resolved absolute URL
+    def resolve_redirect_url(base_url, location)
+      base_uri = URI.parse(base_url)
+      redirect_uri = URI.parse(location)
+
+      return location if redirect_uri.absolute?
+
+      base_uri.merge(redirect_uri).to_s
+    end
+  end
+end

data/lib/patient_http/request.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Represents an async HTTP request that will be processed by the async processor.
+  #
+  # @example Creating a request
+  #   request = PatientHttp::Request.new(:get, "https://api.example.com/users/123")
+  #
+  # @example Creating a POST request with JSON body
+  #   request = PatientHttp::Request.new(
+  #     :post,
+  #     "https://api.example.com/users",
+  #     json: {name: "John", email: "john@example.com"}
+  #   )
+  class Request
+    UNDEFINED = Object.new.freeze
+    private_constant :UNDEFINED
+
+    # Valid HTTP methods
+    VALID_METHODS = %i[get post put patch delete].freeze
+
+    # @return [Symbol] HTTP method (:get, :post, :put, :patch, :delete)
+    attr_reader :http_method
+
+    # @return [String] The request URL
+    attr_reader :url
+
+    # @return [HttpHeaders] Request headers
+    attr_reader :headers
+
+    # @return [Numeric, nil] Overall timeout in seconds
+    attr_reader :timeout
+
+    # @return [Integer, nil] Maximum number of redirects to follow (nil uses config default, 0 disables)
+    attr_reader :max_redirects
+
+    class << self
+      # Reconstruct a Request from a hash
+      #
+      # @param hash [Hash] hash representation
+      # @return [Request] reconstructed request
+      def load(hash)
+        new(
+          hash["http_method"].to_sym,
+          hash["url"],
+          headers: hash["headers"],
+          body: Payload.load(hash["body"])&.value,
+          timeout: hash["timeout"],
+          max_redirects: hash["max_redirects"]
+        )
+      end
+    end
+
+    # Initializes a new Request.
+    #
+    # @param http_method [Symbol, String] HTTP method (:get, :post, :put, :patch, :delete).
+    # @param url [String, URI::Generic] The request URL.
+    # @param headers [Hash, HttpHeaders] Request headers.
+    # @param body [String, nil] Request body.
+    # @param json [Object, nil] JSON body to be serialized (alternative to body).
+    # @param params [Hash, nil] Query parameters to append to the URL.
+    # @param timeout [Numeric, nil] Overall timeout in seconds.
+    # @param max_redirects [Integer, nil] Maximum redirects to follow (nil uses config, 0 disables).
+    def initialize(
+      http_method,
+      url,
+      headers: {},
+      body: nil,
+      json: nil,
+      params: nil,
+      timeout: nil,
+      max_redirects: nil
+    )
+      @http_method = http_method.is_a?(String) ? http_method.downcase.to_sym : http_method
+
+      unless url.nil? || url.is_a?(String) || url.is_a?(URI::Generic)
+        raise ArgumentError.new("url must be a String or URI, got: #{url.class}")
+      end
+
+      @url = normalized_url(url, params)
+      @headers = headers.is_a?(HttpHeaders) ? headers : HttpHeaders.new(headers)
+      @body = (body == "") ? nil : body
+      @timeout = timeout
+      @max_redirects = max_redirects
+
+      if json
+        raise ArgumentError.new("Cannot provide both body and json") if @body
+
+        @body = JSON.generate(json)
+        @headers["content-type"] ||= "application/json; charset=utf-8"
+      end
+
+      validate!
+
+      encoding, encoded_body, charset = Payload.encode(@body, @headers["content-type"])
+      @payload = Payload.new(encoding, encoded_body, charset) unless @body.nil?
+      @body = UNDEFINED
+    end
+
+    # Returns the request body, decoding it from the payload if necessary.
+    #
+    # @return [String, nil] The decoded request body or nil if there was no body.
+    def body
+      @body = @payload&.value if @body.equal?(UNDEFINED)
+      @body
+    end
+
+    # Serialize to JSON hash.
+    #
+    # @return [Hash]
+    def as_json
+      {
+        "http_method" => @http_method.to_s,
+        "url" => @url.to_s,
+        "headers" => @headers.to_h,
+        "body" => @payload&.as_json,
+        "timeout" => @timeout,
+        "max_redirects" => @max_redirects
+      }
+    end
+
+    private
+
+    def normalized_url(url, params)
+      uri = url.is_a?(URI::Generic) ? url.dup : URI(url.to_s)
+      return uri.to_s unless params&.any?
+
+      serialized_params = URI.encode_www_form(params)
+      uri.query = [uri.query, serialized_params].compact.reject(&:empty?).join("&")
+      uri.to_s
+    end
+
+    # Validate the request has required HTTP parameters.
+    # @raise [ArgumentError] if method or url is invalid
+    # @return [self] for chaining
+    def validate!
+      unless VALID_METHODS.include?(@http_method)
+        raise ArgumentError.new("method must be one of #{VALID_METHODS.inspect}, got: #{@http_method.inspect}")
+      end
+
+      raise ArgumentError.new("url is required") if @url.nil? || (@url.is_a?(String) && @url.empty?)
+
+      unless @url.is_a?(String) || @url.is_a?(URI::Generic)
+        raise ArgumentError.new("url must be a String or URI, got: #{@url.class}")
+      end
+
+      if %i[get delete].include?(@http_method) && !@body.nil?
+        raise ArgumentError.new("body is not allowed for #{@http_method.upcase} requests")
+      end
+
+      if @body && !@body.is_a?(String)
+        raise ArgumentError.new("body must be a String, got: #{@body.class}")
+      end
+
+      self
+    end
+  end
+end

data/lib/patient_http/request_error.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Error object representing an exception from making an HTTP request. Note that this
+  # is not for HTTP error responses (4xx/5xx), but from actual exceptions raised
+  # during the request (timeouts, connection errors, SSL errors, etc).
+  #
+  # This is how errors are passed back to the error continuation jobs for processing.
+  class RequestError < Error
+    # Valid error types
+    ERROR_TYPES = [:timeout, :connection, :ssl, :response_too_large, :unknown].freeze
+
+    # @return [String] Request URL
+    attr_reader :url
+
+    # @return [Symbol] HTTP method
+    attr_reader :http_method
+
+    # @return [Float] Request duration in seconds
+    attr_reader :duration
+
+    # @return [String] Unique request identifier
+    attr_reader :request_id
+
+    # @return [Symbol] Categorized error type. This provides a higher level categorization
+    # of the error (e.g., :connection is used to group IO and socket errors).
+    attr_reader :error_type
+
+    class << self
+      # Reconstruct a RequestError from a hash
+      #
+      # @param hash [Hash] hash representation
+      # @return [RequestError] reconstructed error
+      def load(hash)
+        new(
+          class_name: hash["class_name"],
+          message: hash["message"],
+          backtrace: hash["backtrace"],
+          request_id: hash["request_id"],
+          error_type: hash["error_type"]&.to_sym,
+          duration: hash["duration"],
+          url: hash["url"],
+          http_method: hash["http_method"],
+          callback_args: hash["callback_args"]
+        )
+      end
+
+      # Create a RequestError from an exception using pattern matching
+      #
+      # @param exception [Exception] the exception to convert
+      # @param duration [Float] request duration in seconds
+      # @param request_id [String] the request ID
+      # @param url [String] the request URL
+      # @param http_method [Symbol, String] the HTTP method
+      # @param callback_args [Hash, nil] callback arguments (string keys)
+      # @return [RequestError] the error object
+      def from_exception(exception, duration:, request_id:, url:, http_method:, callback_args: nil)
+        type = error_type(exception)
+
+        new(
+          class_name: exception.class.name,
+          message: exception.message,
+          backtrace: exception.backtrace || [],
+          request_id: request_id,
+          error_type: type,
+          duration: duration,
+          url: url,
+          http_method: http_method,
+          callback_args: callback_args
+        )
+      end
+
+      # Determine error type from exception.
+      #
+      # @param exception [Exception] the exception to categorize
+      # @return [Symbol] the error type
+      def error_type(exception)
+        case exception
+        in Async::TimeoutError
+          :timeout
+        in OpenSSL::SSL::SSLError
+          :ssl
+        in Errno::ECONNREFUSED | Errno::ECONNRESET | Errno::EHOSTUNREACH | Errno::EPIPE | SocketError | IOError
+          :connection
+        else
+          if exception.is_a?(PatientHttp::ResponseTooLargeError)
+            :response_too_large
+          else
+            :unknown
+          end
+        end
+      end
+    end
+
+    # Initializes a new RequestError.
+    #
+    # @param class_name [String] Name of the exception class
+    # @param message [String] Exception message
+    # @param backtrace [Array<String>] Exception backtrace
+    # @param error_type [Symbol] Categorized error type
+    # @param duration [Float] Request duration in seconds
+    # @param request_id [String] Unique request identifier
+    # @param url [String] Request URL
+    # @param http_method [Symbol, String] HTTP method
+    # @param callback_args [Hash, nil] callback arguments (string keys)
+    def initialize(class_name:, message:, backtrace:, error_type:, duration:, request_id:, url:, http_method:,
+      callback_args: nil)
+      super(message)
+      set_backtrace(backtrace)
+      @class_name = class_name
+      @error_type = error_type
+      @duration = duration
+      @request_id = request_id
+      @url = url
+      @http_method = http_method&.to_sym
+      @callback_args_data = callback_args || {}
+    end
+
+    # Convert to hash with string keys for serialization
+    #
+    # @return [Hash] hash representation
+    def as_json
+      {
+        "class_name" => @class_name,
+        "message" => message,
+        "backtrace" => backtrace,
+        "request_id" => request_id,
+        "error_type" => error_type.to_s,
+        "duration" => duration,
+        "url" => url,
+        "http_method" => http_method.to_s,
+        "callback_args" => @callback_args_data
+      }
+    end
+
+    # Get the actual Exception class constant from the class_name
+    #
+    # @return [Class, nil] the exception class or nil if not found
+    def error_class
+      ClassHelper.resolve_class_name(@class_name)
+    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
+  end
+end