http 5.3.1 → 6.0.0

data/lib/http/retriable/delay_calculator.rb

@@ -2,17 +2,30 @@
 
 module HTTP
   module Retriable
+    # Calculates retry delays with support for Retry-After headers
     # @api private
     class DelayCalculator
-      def initialize(opts)
-        @max_delay = opts.fetch(:max_delay, Float::MAX).to_f
-        if (delay = opts[:delay]).respond_to?(:call)
-          @delay_proc = opts.fetch(:delay)
+      # 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)
@@ -20,9 +33,10 @@ module HTTP
                   calculate_delay_from_iteration(iteration)
                 end
 
-        ensure_dealy_in_bounds(delay)
+        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+
@@ -32,18 +46,26 @@ module HTTP
         GMT
       $/x
 
-      # Spec for Retry-After header
-      # https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
+      # Parses delay from Retry-After header value
+      #
+      # @param [String] value
+      # @api private
+      # @return [Numeric]
       def delay_from_retry_header(value)
-        value = value.to_s.strip
+        value = String(value).strip
 
         case value
         when RFC2822_DATE_REGEX then DateTime.rfc2822(value).to_time - Time.now.utc
-        when /^\d+$/            then value.to_i
+        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)
@@ -56,8 +78,13 @@ module HTTP
         end
       end
 
-      def ensure_dealy_in_bounds(delay)
-        delay.clamp(0, @max_delay)
+      # 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

data/lib/http/retriable/errors.rb

@@ -3,10 +3,31 @@
 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

data/lib/http/retriable/performer.rb

@@ -6,6 +6,7 @@ require "http/retriable/delay_calculator"
 require "openssl"
 
 module HTTP
+  # Retry logic for failed HTTP requests
   module Retriable
     # Request performing watchdog.
     # @api private
@@ -23,62 +24,87 @@ module HTTP
         IOError
       ].freeze
 
-      # @param [Hash] opts
-      # @option opts [#to_i] :tries (5)
-      # @option opts [#call, #to_i] :delay (DELAY_PROC)
-      # @option opts [Array(Exception)] :exceptions (RETRIABLE_ERRORS)
-      # @option opts [Array(#to_i)] :retry_statuses
-      # @option opts [#call] :on_retry
-      # @option opts [#to_f] :max_delay (Float::MAX)
-      # @option opts [#call] :should_retry
-      def initialize(opts)
-        @exception_classes = opts.fetch(:exceptions, RETRIABLE_ERRORS)
-        @retry_statuses = opts[:retry_statuses]
-        @tries = opts.fetch(:tries, 5).to_i
-        @on_retry = opts.fetch(:on_retry, ->(*) {})
-        @should_retry_proc = opts[:should_retry]
-        @delay_calculator = DelayCalculator.new(opts)
+      # 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
 
-      # Watches request/response execution.
-      #
-      # If any of {RETRIABLE_ERRORS} occur or response status is `5xx`, retries
-      # up to `:tries` amount of times. Sleeps for amount of seconds calculated
-      # with `:delay` proc before each retry.
+      # 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)
-            begin
-              wait_for_retry_or_raise(req, err, res, attempt)
-            ensure
-              # 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, effectivle closing underlying socket
-              # and resetting client's state.
-              client.close
-            end
+            retry_attempt(client, req, err, res, attempt)
           elsif err
-            client.close
-            raise 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
@@ -93,6 +119,10 @@ module HTTP
       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)
@@ -103,14 +133,22 @@ module HTTP
         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 = res.status.to_i
+        response_status = Integer(res.status)
         retry_matchers = [@retry_statuses].flatten
 
         retry_matchers.any? do |matcher|
@@ -122,10 +160,14 @@ module HTTP
         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)
+          sleep(calculate_delay(attempt, res))
         else
           res&.flush
           raise out_of_retries_error(req, res, err)
@@ -135,15 +177,17 @@ module HTTP
       # Builds OutOfRetriesError
       #
       # @param request [HTTP::Request]
-      # @param status [HTTP::Response, nil]
+      # @param response [HTTP::Response, nil]
       # @param exception [Exception, nil]
+      # @api private
+      # @return [HTTP::OutOfRetriesError]
       def out_of_retries_error(request, response, exception)
-        message = "#{request.verb.to_s.upcase} <#{request.uri}> failed"
+        message = format("%s <%s> failed", String(request.verb).upcase, request.uri)
 
         message += " with #{response.status}" if response
         message += ":#{exception}" if exception
 
-        HTTP::OutOfRetriesError.new(message).tap do |ex|
+        OutOfRetriesError.new(message).tap do |ex|
           ex.cause = exception
           ex.response = response
         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