http 5.2.0 → 6.0.2

data/lib/http/retriable/delay_calculator.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module HTTP
+  module Retriable
+    # Calculates retry delays with support for Retry-After headers
+    # @api private
+    class DelayCalculator
+      # Initializes the delay calculator
+      #
+      # @param [#call, Numeric, nil] delay delay value or proc
+      # @param [#to_f] max_delay maximum delay cap
+      # @api private
+      # @return [HTTP::Retriable::DelayCalculator]
+      def initialize(delay: nil, max_delay: Float::MAX)
+        @max_delay = Float(max_delay)
+        if delay.respond_to?(:call)
+          @delay_proc = delay
+        else
+          @delay = delay
+        end
+      end
+
+      # Calculates delay for the given iteration
+      #
+      # @param [Integer] iteration
+      # @param [HTTP::Response, nil] response
+      # @api private
+      # @return [Numeric]
+      def call(iteration, response)
+        delay = if response && (retry_header = response.headers["Retry-After"])
+                  delay_from_retry_header(retry_header)
+                else
+                  calculate_delay_from_iteration(iteration)
+                end
+
+        ensure_delay_in_bounds(delay)
+      end
+
+      # Pattern matching RFC 2822 formatted dates in Retry-After headers
+      RFC2822_DATE_REGEX = /^
+        (?:Sun|Mon|Tue|Wed|Thu|Fri|Sat),\s+
+        (?:0[1-9]|[1-2]?[0-9]|3[01])\s+
+        (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s+
+        (?:19[0-9]{2}|[2-9][0-9]{3})\s+
+        (?:2[0-3]|[0-1][0-9]):(?:[0-5][0-9]):(?:60|[0-5][0-9])\s+
+        GMT
+      $/x
+
+      # Parses delay from Retry-After header value
+      #
+      # @param [String] value
+      # @api private
+      # @return [Numeric]
+      def delay_from_retry_header(value)
+        value = String(value).strip
+
+        case value
+        when RFC2822_DATE_REGEX then DateTime.rfc2822(value).to_time - Time.now.utc
+        when /\A\d+$/           then value.to_i
+        else 0
+        end
+      end
+
+      # Calculates delay based on iteration number
+      #
+      # @param [Integer] iteration
+      # @api private
+      # @return [Numeric]
+      def calculate_delay_from_iteration(iteration)
+        if @delay_proc
+          @delay_proc.call(iteration)
+        elsif @delay
+          @delay
+        else
+          delay = (2**(iteration - 1)) - 1
+          delay_noise = rand
+          delay + delay_noise
+        end
+      end
+
+      # Clamps delay to configured bounds
+      #
+      # @param [Numeric] delay
+      # @api private
+      # @return [Numeric]
+      def ensure_delay_in_bounds(delay)
+        Float(delay.clamp(0, @max_delay))
+      end
+    end
+  end
+end

data/lib/http/retriable/errors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module HTTP
+  # Retriable performance ran out of attempts
+  class OutOfRetriesError < Error
+    # The last response received before failure
+    #
+    # @example
+    #   error.response
+    #
+    # @return [HTTP::Response, nil] the last response received
+    # @api public
+    attr_accessor :response
+
+    # Set the underlying exception
+    #
+    # @example
+    #   error.cause = original_error
+    #
+    # @return [Exception, nil]
+    # @api public
+    attr_writer :cause
+
+    # Returns the cause of the error
+    #
+    # @example
+    #   error.cause
+    #
+    # @api public
+    # @return [Exception, nil]
+    def cause
+      @cause || super
+    end
+  end
+end

data/lib/http/retriable/performer.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "date"
+require "http/retriable/errors"
+require "http/retriable/delay_calculator"
+require "openssl"
+
+module HTTP
+  # Retry logic for failed HTTP requests
+  module Retriable
+    # Request performing watchdog.
+    # @api private
+    class Performer
+      # Exceptions we should retry
+      RETRIABLE_ERRORS = [
+        HTTP::TimeoutError,
+        HTTP::ConnectionError,
+        IO::EAGAINWaitReadable,
+        Errno::ECONNRESET,
+        Errno::ECONNREFUSED,
+        Errno::EHOSTUNREACH,
+        OpenSSL::SSL::SSLError,
+        EOFError,
+        IOError
+      ].freeze
+
+      # Create a new retry performer
+      #
+      # @param [#to_i] tries maximum number of attempts
+      # @param [#call, #to_i, nil] delay delay between retries
+      # @param [Array<Exception>] exceptions exception classes to retry
+      # @param [Array<#to_i>, nil] retry_statuses status codes to retry
+      # @param [#call] on_retry callback invoked on each retry
+      # @param [#to_f] max_delay maximum delay between retries
+      # @param [#call, nil] should_retry custom retry predicate
+      # @api private
+      # @return [HTTP::Retriable::Performer]
+      def initialize(tries: 5, delay: nil, exceptions: RETRIABLE_ERRORS, retry_statuses: nil,
+                     on_retry: ->(*_args) {}, max_delay: Float::MAX, should_retry: nil)
+        @exception_classes = exceptions
+        @retry_statuses = retry_statuses
+        @tries = tries.to_i
+        @on_retry = on_retry
+        @should_retry_proc = should_retry
+        @delay_calculator = DelayCalculator.new(delay: delay, max_delay: max_delay)
+      end
+
+      # Execute request with retry logic
+      #
+      # @see #initialize
+      # @return [HTTP::Response]
+      # @api private
+      def perform(client, req, &block)
+        1.upto(Float::INFINITY) do |attempt| # infinite loop with index
+          err, res = try_request(&block)
+
+          if retry_request?(req, err, res, attempt)
+            retry_attempt(client, req, err, res, attempt)
+          elsif err
+            finish_attempt(client, err)
+          elsif res
+            return res
+          end
+        end
+      end
+
+      # Calculates delay between retries
+      #
+      # @param [Integer] iteration
+      # @param [HTTP::Response, nil] response
+      # @api private
+      # @return [Numeric]
+      def calculate_delay(iteration, response)
+        @delay_calculator.call(iteration, response)
+      end
+
+      private
+
+      # Executes a single retry attempt
+      #
+      # @api private
+      # @return [void]
+      def retry_attempt(client, req, err, res, attempt)
+        # Some servers support Keep-Alive on any response. Thus we should
+        # flush response before retry, to avoid state error (when socket
+        # has pending response data and we try to write new request).
+        # Alternatively, as we don't need response body here at all, we
+        # are going to close client, effectively closing underlying socket
+        # and resetting client's state.
+        wait_for_retry_or_raise(req, err, res, attempt)
+      ensure
+        client.close
+      end
+
+      # Closes client and raises the error
+      #
+      # @api private
+      # @return [void]
+      def finish_attempt(client, err)
+        client.close
+        raise err
+      end
+
+      # Attempts to execute the request block
+      #
+      # @api private
+      # @return [Array]
+      # rubocop:disable Lint/RescueException
+      def try_request
+        err, res = nil
+
+        begin
+          res = yield
+        rescue Exception => e
+          err = e
+        end
+
+        [err, res]
+      end
+      # rubocop:enable Lint/RescueException
+
+      # Checks whether the request should be retried
+      #
+      # @api private
+      # @return [Boolean]
+      def retry_request?(req, err, res, attempt)
+        if @should_retry_proc
+          @should_retry_proc.call(req, err, res, attempt)
+        elsif err
+          retry_exception?(err)
+        else
+          retry_response?(res)
+        end
+      end
+
+      # Checks whether the exception is retriable
+      #
+      # @api private
+      # @return [Boolean]
+      def retry_exception?(err)
+        @exception_classes.any? { |e| err.is_a?(e) }
+      end
+
+      # Checks whether the response status warrants retry
+      #
+      # @api private
+      # @return [Boolean]
+      def retry_response?(res)
+        return false unless @retry_statuses
+
+        response_status = Integer(res.status)
+        retry_matchers = [@retry_statuses].flatten
+
+        retry_matchers.any? do |matcher|
+          case matcher
+          when Range then matcher.cover?(response_status)
+          when Numeric then matcher == response_status
+          else matcher.call(response_status)
+          end
+        end
+      end
+
+      # Waits for retry delay or raises if out of attempts
+      #
+      # @api private
+      # @return [void]
+      def wait_for_retry_or_raise(req, err, res, attempt)
+        if attempt < @tries
+          @on_retry.call(req, err, res)
+          sleep(calculate_delay(attempt, res))
+        else
+          res&.flush
+          raise out_of_retries_error(req, res, err)
+        end
+      end
+
+      # Builds OutOfRetriesError
+      #
+      # @param request [HTTP::Request]
+      # @param response [HTTP::Response, nil]
+      # @param exception [Exception, nil]
+      # @api private
+      # @return [HTTP::OutOfRetriesError]
+      def out_of_retries_error(request, response, exception)
+        message = format("%s <%s> failed", String(request.verb).upcase, request.uri)
+
+        message += " with #{response.status}" if response
+        message += ":#{exception}" if exception
+
+        OutOfRetriesError.new(message).tap do |ex|
+          ex.cause = exception
+          ex.response = response
+        end
+      end
+    end
+  end
+end

data/lib/http/session.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+require "http/cookie_jar"
+require "http/headers"
+require "http/redirector"
+require "http/request/builder"
+
+module HTTP
+  # Thread-safe options builder for configuring HTTP requests.
+  #
+  # Session objects are returned by all chainable configuration methods
+  # (e.g., {Chainable#headers}, {Chainable#timeout}, {Chainable#cookies}).
+  # They hold an immutable {Options} object and create a new {Client}
+  # for each request, making them safe to share across threads.
+  #
+  # When configured for persistent connections (via {Chainable#persistent}),
+  # the session maintains a pool of {Client} instances keyed by origin,
+  # enabling connection reuse within the same origin and transparent
+  # cross-origin redirect handling.
+  #
+  # @example Reuse a configured session across threads
+  #   session = HTTP.headers("Accept" => "application/json").timeout(10)
+  #   threads = 5.times.map do
+  #     Thread.new { session.get("https://example.com") }
+  #   end
+  #   threads.each(&:join)
+  #
+  # @example Persistent session with cross-origin redirects
+  #   HTTP.persistent("https://example.com").follow do |http|
+  #     http.get("/redirect-to-other-domain")  # follows cross-origin redirect
+  #   end
+  #
+  # @see Chainable
+  # @see Client
+  class Session
+    extend Forwardable
+    include Chainable
+
+    # @!method persistent?
+    #   Indicate whether the session has persistent connection options
+    #
+    #   @example
+    #     session = HTTP::Session.new(persistent: "http://example.com")
+    #     session.persistent?
+    #
+    #   @see Options#persistent?
+    #   @return [Boolean]
+    #   @api public
+    def_delegator :default_options, :persistent?
+
+    # Initialize a new Session
+    #
+    # @example
+    #   session = HTTP::Session.new(headers: {"Accept" => "application/json"})
+    #
+    # @param default_options [HTTP::Options, nil] existing options instance
+    # @param clients [Hash, nil] shared connection pool (internal use)
+    # @param options [Hash] keyword options (see HTTP::Options#initialize)
+    # @return [HTTP::Session] a new session instance
+    # @api public
+    def initialize(default_options = nil, clients: nil, **)
+      @default_options = HTTP::Options.new(default_options, **)
+      @clients = clients || {}
+    end
+
+    # Close all persistent connections held by this session
+    #
+    # When the session is persistent, this closes every pooled {Client}
+    # and clears the pool. Safe to call on non-persistent sessions (no-op).
+    #
+    # @example
+    #   session = HTTP.persistent("https://example.com")
+    #   session.get("/")
+    #   session.close
+    #
+    # @return [void]
+    # @api public
+    def close
+      @clients.each_value(&:close)
+      @clients.clear
+    end
+
+    # Make an HTTP request
+    #
+    # For non-persistent sessions a fresh {Client} is created for each
+    # request, ensuring thread safety. For persistent sessions the pooled
+    # {Client} for the request's origin is reused.
+    #
+    # Manages cookies across redirect hops when following redirects.
+    #
+    # @example Without a block
+    #   session = HTTP::Session.new
+    #   session.request(:get, "https://example.com")
+    #
+    # @example With a block (auto-closes connection)
+    #   session = HTTP::Session.new
+    #   session.request(:get, "https://example.com") { |res| res.status }
+    #
+    # @param verb [Symbol] the HTTP method
+    # @param uri [#to_s] the URI to request
+    # @yieldparam response [HTTP::Response] the response
+    # @return [HTTP::Response, Object] the response, or block return value
+    # @api public
+    def request(verb, uri,
+                headers: nil, params: nil, form: nil, json: nil, body: nil,
+                response: nil, encoding: nil, follow: nil, ssl: nil, ssl_context: nil,
+                proxy: nil, nodelay: nil, features: nil, retriable: nil,
+                socket_class: nil, ssl_socket_class: nil, timeout_class: nil,
+                timeout_options: nil, keep_alive_timeout: nil, base_uri: nil, persistent: nil, &block)
+      merged = default_options.merge(
+        { headers: headers, params: params, form: form, json: json, body: body,
+          response: response, encoding: encoding, follow: follow, ssl: ssl,
+          ssl_context: ssl_context, proxy: proxy, nodelay: nodelay, features: features,
+          retriable: retriable, socket_class: socket_class, ssl_socket_class: ssl_socket_class,
+          timeout_class: timeout_class, timeout_options: timeout_options,
+          keep_alive_timeout: keep_alive_timeout, base_uri: base_uri, persistent: persistent }.compact
+      )
+      client = persistent? ? nil : make_client(default_options)
+      res    = perform_request(client, verb, uri, merged)
+
+      return res unless block
+
+      yield res
+    ensure
+      if block
+        persistent? ? close : client&.close
+      end
+    end
+
+    private
+
+    # Create a new session with the given options
+    #
+    # When the current session is persistent, the child session shares the
+    # same connection pool so that chaining methods like {Chainable#headers}
+    # or {Chainable#auth} do not break connection reuse.
+    #
+    # @param options [HTTP::Options] options for the new session
+    # @return [HTTP::Session]
+    # @api private
+    def branch(options)
+      if persistent?
+        self.class.new(options, clients: @clients)
+      else
+        self.class.new(options)
+      end
+    end
+
+    # Execute a request with cookie management
+    #
+    # @param client [HTTP::Client, nil] the client (nil when persistent; looked up from pool)
+    # @param verb [Symbol] the HTTP method
+    # @param uri [#to_s] the URI to request
+    # @param merged [HTTP::Options] the merged options
+    # @return [HTTP::Response] the response
+    # @api private
+    def perform_request(client, verb, uri, merged)
+      cookie_jar = CookieJar.new
+      builder = Request::Builder.new(merged)
+      req = builder.build(verb, uri)
+      client ||= client_for_origin(req.uri.origin)
+      load_cookies(cookie_jar, req)
+      res = client.perform(req, merged)
+      store_cookies(cookie_jar, res)
+
+      return res unless merged.follow
+
+      perform_redirects(cookie_jar, client, req, res, merged)
+    end
+
+    # Follow redirects with cookie management
+    #
+    # For persistent sessions, each redirect hop may target a different
+    # origin. The session looks up (or creates) a pooled {Client} for
+    # the redirect target's origin, allowing cross-origin redirects
+    # without raising {StateError}.
+    #
+    # @param jar [HTTP::CookieJar] the cookie jar
+    # @param client [HTTP::Client] the client for the initial request
+    # @param req [HTTP::Request] the original request
+    # @param res [HTTP::Response] the initial redirect response
+    # @param opts [HTTP::Options] the merged options
+    # @return [HTTP::Response] the final non-redirect response
+    # @api private
+    def perform_redirects(jar, client, req, res, opts)
+      builder = Request::Builder.new(opts)
+      follow = opts.follow || {} #: Hash[untyped, untyped]
+      Redirector.new(**follow).perform(req, res) do |redirect_req|
+        wrapped = builder.wrap(redirect_req)
+        apply_cookies(jar, wrapped)
+        apply_cookies(jar, redirect_req)
+        response = redirect_client(client, wrapped).perform(wrapped, opts)
+        store_cookies(jar, response)
+        response
+      end
+    end
+
+    # Return the appropriate client for a redirect hop
+    #
+    # @param client [HTTP::Client] the client for the original request
+    # @param request [HTTP::Request] the redirect request
+    # @return [HTTP::Client] the client for the redirect target
+    # @api private
+    def redirect_client(client, request)
+      persistent? ? client_for_origin(request.uri.origin) : client
+    end
+
+    # Return a pooled persistent {Client} for the given origin
+    #
+    # Creates a new {Client} if one does not already exist for this origin.
+    # For the session's primary persistent origin, the default options are
+    # used directly. For other origins (e.g. redirect targets), the
+    # persistent origin is overridden and base_uri is cleared.
+    #
+    # @param origin [String] the URI origin (scheme + host + port)
+    # @return [HTTP::Client] a persistent client for the origin
+    # @api private
+    def client_for_origin(origin)
+      @clients[origin] ||= make_client(options_for_origin(origin))
+    end
+
+    # Build {Options} for a persistent client targeting the given origin
+    #
+    # @param origin [String] the URI origin
+    # @return [HTTP::Options] options configured for this origin
+    # @api private
+    def options_for_origin(origin)
+      return default_options if origin == default_options.persistent
+
+      default_options.merge(persistent: origin, base_uri: nil)
+    end
+
+    # Load cookies from the request's Cookie header into the jar
+    #
+    # @param jar [HTTP::CookieJar] the cookie jar
+    # @param request [HTTP::Request] the request
+    # @return [void]
+    # @api private
+    def load_cookies(jar, request)
+      header = request.headers[Headers::COOKIE]
+      cookies = HTTP::Cookie.cookie_value_to_hash(header.to_s)
+
+      cookies.each do |name, value|
+        jar.add(HTTP::Cookie.new(name, value, path: request.uri.path, domain: request.host))
+      end
+    end
+
+    # Store cookies from the response's Set-Cookie headers into the jar
+    #
+    # @param jar [HTTP::CookieJar] the cookie jar
+    # @param response [HTTP::Response] the response
+    # @return [void]
+    # @api private
+    def store_cookies(jar, response)
+      response.cookies.each do |cookie|
+        if cookie.value == ""
+          jar.delete(cookie)
+        else
+          jar.add(cookie)
+        end
+      end
+    end
+
+    # Apply cookies from the jar to the request's Cookie header
+    #
+    # @param jar [HTTP::CookieJar] the cookie jar
+    # @param request [HTTP::Request] the request
+    # @return [void]
+    # @api private
+    def apply_cookies(jar, request)
+      if jar.empty?
+        request.headers.delete(Headers::COOKIE)
+      else
+        request.headers.set(Headers::COOKIE, jar.map { |c| "#{c.name}=#{c.value}" }.join("; "))
+      end
+    end
+  end
+end