http 5.2.0 → 6.0.2

data/lib/http/chainable.rb

@@ -1,125 +1,117 @@
 # frozen_string_literal: true
 
-require "base64"
-
+require "http/base64"
+require "http/chainable/helpers"
+require "http/chainable/verbs"
 require "http/headers"
 
 module HTTP
+  # HTTP verb methods and client configuration DSL
   module Chainable
-    # Request a get sans response body
-    # @param uri
-    # @option options [Hash]
-    def head(uri, options = {})
-      request :head, uri, options
-    end
-
-    # Get a resource
-    # @param uri
-    # @option options [Hash]
-    def get(uri, options = {})
-      request :get, uri, options
-    end
-
-    # Post to a resource
-    # @param uri
-    # @option options [Hash]
-    def post(uri, options = {})
-      request :post, uri, options
-    end
-
-    # Put to a resource
-    # @param uri
-    # @option options [Hash]
-    def put(uri, options = {})
-      request :put, uri, options
-    end
-
-    # Delete a resource
-    # @param uri
-    # @option options [Hash]
-    def delete(uri, options = {})
-      request :delete, uri, options
-    end
-
-    # Echo the request back to the client
-    # @param uri
-    # @option options [Hash]
-    def trace(uri, options = {})
-      request :trace, uri, options
-    end
-
-    # Return the methods supported on the given URI
-    # @param uri
-    # @option options [Hash]
-    def options(uri, options = {})
-      request :options, uri, options
-    end
-
-    # Convert to a transparent TCP/IP tunnel
-    # @param uri
-    # @option options [Hash]
-    def connect(uri, options = {})
-      request :connect, uri, options
-    end
-
-    # Apply partial modifications to a resource
-    # @param uri
-    # @option options [Hash]
-    def patch(uri, options = {})
-      request :patch, uri, options
-    end
+    include HTTP::Base64
+    include Verbs
 
     # Make an HTTP request with the given verb
+    #
+    # @example Without a block
+    #   HTTP.request(:get, "http://example.com")
+    #
+    # @example With a block (auto-closes connection)
+    #   HTTP.request(:get, "http://example.com") { |res| res.status }
+    #
     # @param (see Client#request)
-    def request(*args)
-      branch(default_options).request(*args)
-    end
-
-    # Prepare an HTTP request with the given verb
-    # @param (see Client#build_request)
-    def build_request(*args)
-      branch(default_options).build_request(*args)
+    # @yieldparam response [HTTP::Response] the response
+    # @return [HTTP::Response, Object] the response, or block return value
+    # @api public
+    def request(verb, uri, **, &block)
+      client   = make_client(default_options)
+      response = client.request(verb, uri, **)
+      return response unless block
+
+      yield response
+    ensure
+      client&.close if block
     end
 
+    # Set timeout on the request
+    #
+    # @example
+    #   HTTP.timeout(10).get("http://example.com")
+    #
     # @overload timeout(options = {})
     #   Adds per operation timeouts to the request
     #   @param [Hash] options
     #   @option options [Float] :read Read timeout
     #   @option options [Float] :write Write timeout
     #   @option options [Float] :connect Connect timeout
+    #   @option options [Float] :global Global timeout (combines with per-operation)
     # @overload timeout(global_timeout)
     #   Adds a global timeout to the full request
     #   @param [Numeric] global_timeout
+    # @return [HTTP::Session]
+    # @api public
     def timeout(options)
       klass, options = case options
-                       when Numeric then [HTTP::Timeout::Global, {:global => options}]
-                       when Hash    then [HTTP::Timeout::PerOperation, options.dup]
+                       when Numeric then [HTTP::Timeout::Global, { global_timeout: options }]
+                       when Hash    then resolve_timeout_hash(options)
                        when :null   then [HTTP::Timeout::Null, {}]
-                       else raise ArgumentError, "Use `.timeout(global_timeout_in_seconds)` or `.timeout(connect: x, write: y, read: z)`."
-
+                       else raise ArgumentError,
+                                  "Use `.timeout(:null)`, " \
+                                  "`.timeout(global_timeout_in_seconds)` or " \
+                                  "`.timeout(connect: x, write: y, read: z)`."
                        end
 
-      %i[global read write connect].each do |k|
-        next unless options.key? k
-
-        options["#{k}_timeout".to_sym] = options.delete k
-      end
-
       branch default_options.merge(
-        :timeout_class   => klass,
-        :timeout_options => options
+        timeout_class:   klass,
+        timeout_options: options
       )
     end
 
-    # @overload persistent(host, timeout: 5)
+    # Set a base URI for resolving relative request paths
+    #
+    # The first call must use an absolute URI that includes a scheme
+    # (e.g. "https://example.com"). Once a base URI is set, subsequent chained
+    # calls may use relative paths that are resolved against the existing base.
+    #
+    # @example
+    #   HTTP.base_uri("https://example.com/api/v1").get("users")
+    #
+    # @example Chaining base URIs
+    #   HTTP.base_uri("https://example.com").base_uri("api/v1").get("users")
+    #
+    # @param [String, HTTP::URI] uri the base URI (absolute with scheme when
+    #   no base is set; may be relative when chaining)
+    # @return [HTTP::Session]
+    # @raise [HTTP::Error] if no base URI is set and the given URI has no scheme
+    # @api public
+    def base_uri(uri)
+      branch default_options.with_base_uri(uri)
+    end
+
+    # Open a persistent connection to a host
+    #
+    # Returns an {HTTP::Session} that pools persistent {HTTP::Client}
+    # instances by origin. This allows connection reuse within the same
+    # origin and transparent cross-origin redirect handling.
+    #
+    # When no host is given, the origin is derived from the configured base URI.
+    #
+    # @example
+    #   HTTP.persistent("http://example.com").get("/")
+    #
+    # @example Derive host from base URI
+    #   HTTP.base_uri("https://example.com/api").persistent.get("users")
+    #
+    # @overload persistent(host = nil, timeout: 5)
     #   Flags as persistent
-    #   @param  [String] host
+    #   @param  [String, nil] host connection origin (derived from base URI when nil)
     #   @option [Integer] timeout Keep alive timeout
+    #   @raise  [ArgumentError] if host is nil and no base URI is set
     #   @raise  [Request::Error] if Host is invalid
-    #   @return [HTTP::Client] Persistent client
-    # @overload persistent(host, timeout: 5, &block)
-    #   Executes given block with persistent client and automatically closes
-    #   connection at the end of execution.
+    #   @return [HTTP::Session] Persistent session
+    # @overload persistent(host = nil, timeout: 5, &block)
+    #   Executes given block with persistent session and automatically closes
+    #   all connections at the end of execution.
     #
     #   @example
     #
@@ -139,29 +131,34 @@ module HTTP
     #       end
     #
     #
-    #   @yieldparam [HTTP::Client] client Persistent client
+    #   @yieldparam [HTTP::Session] session Persistent session
     #   @return [Object] result of last expression in the block
-    def persistent(host, timeout: 5)
-      options  = {:keep_alive_timeout => timeout}
-      p_client = branch default_options.merge(options).with_persistent host
-      return p_client unless block_given?
+    # @return [HTTP::Session, Object]
+    # @api public
+    def persistent(host = nil, timeout: 5)
+      host ||= default_options.base_uri&.origin
+      raise ArgumentError, "host is required for persistent connections" unless host
 
-      yield p_client
+      options = default_options.merge(keep_alive_timeout: timeout).with_persistent(host)
+      session = branch(options)
+      return session unless block_given?
+
+      yield session
     ensure
-      p_client&.close
+      session&.close if block_given?
     end
 
     # Make a request through an HTTP proxy
+    #
+    # @example
+    #   HTTP.via("proxy.example.com", 8080).get("http://example.com")
+    #
     # @param [Array] proxy
     # @raise [Request::Error] if HTTP proxy is invalid
+    # @return [HTTP::Session]
+    # @api public
     def via(*proxy)
-      proxy_hash = {}
-      proxy_hash[:proxy_address]  = proxy[0] if proxy[0].is_a?(String)
-      proxy_hash[:proxy_port]     = proxy[1] if proxy[1].is_a?(Integer)
-      proxy_hash[:proxy_username] = proxy[2] if proxy[2].is_a?(String)
-      proxy_hash[:proxy_password] = proxy[3] if proxy[3].is_a?(String)
-      proxy_hash[:proxy_headers]  = proxy[2] if proxy[2].is_a?(Hash)
-      proxy_hash[:proxy_headers]  = proxy[4] if proxy[4].is_a?(Hash)
+      proxy_hash = build_proxy_hash(proxy)
 
       raise(RequestError, "invalid HTTP proxy: #{proxy_hash}") unless (2..5).cover?(proxy_hash.keys.size)
 
@@ -169,88 +166,211 @@ module HTTP
     end
     alias through via
 
-    # Make client follow redirects.
-    # @param options
-    # @return [HTTP::Client]
+    # Make client follow redirects
+    #
+    # @example
+    #   HTTP.follow.get("http://example.com")
+    #
+    # @param [Boolean] strict (true) redirector hops policy
+    # @param [Integer] max_hops (5) maximum allowed redirect hops
+    # @param [#call, nil] on_redirect optional redirect callback
+    # @return [HTTP::Session]
     # @see Redirector#initialize
-    def follow(options = {})
-      branch default_options.with_follow options
+    # @api public
+    def follow(strict: nil, max_hops: nil, on_redirect: nil)
+      opts = { strict: strict, max_hops: max_hops, on_redirect: on_redirect }.compact
+      branch default_options.with_follow(opts)
     end
 
     # Make a request with the given headers
-    # @param headers
+    #
+    # @example
+    #   HTTP.headers("Accept" => "text/plain").get("http://example.com")
+    #
+    # @param [Hash] headers request headers
+    # @return [HTTP::Session]
+    # @api public
     def headers(headers)
       branch default_options.with_headers(headers)
     end
 
     # Make a request with the given cookies
+    #
+    # @example
+    #   HTTP.cookies(session: "abc123").get("http://example.com")
+    #
+    # @param [Hash, Array<HTTP::Cookie>] cookies cookies to set
+    # @return [HTTP::Session]
+    # @api public
     def cookies(cookies)
-      branch default_options.with_cookies(cookies)
+      value = cookies.map do |entry|
+        case entry
+        when HTTP::Cookie then entry.cookie_value
+        else
+          name, val = entry
+          HTTP::Cookie.new(name.to_s, val.to_s).cookie_value
+        end
+      end.join("; ")
+
+      headers(Headers::COOKIE => value)
     end
 
     # Force a specific encoding for response body
+    #
+    # @example
+    #   HTTP.encoding("UTF-8").get("http://example.com")
+    #
+    # @param [String, Encoding] encoding encoding to use
+    # @return [HTTP::Session]
+    # @api public
     def encoding(encoding)
       branch default_options.with_encoding(encoding)
     end
 
     # Accept the given MIME type(s)
-    # @param type
+    #
+    # @example
+    #   HTTP.accept("application/json").get("http://example.com")
+    #
+    # @param [String, Symbol] type MIME type to accept
+    # @return [HTTP::Session]
+    # @api public
     def accept(type)
       headers Headers::ACCEPT => MimeType.normalize(type)
     end
 
     # Make a request with the given Authorization header
+    #
+    # @example
+    #   HTTP.auth("Bearer token123").get("http://example.com")
+    #
     # @param [#to_s] value Authorization header value
+    # @return [HTTP::Session]
+    # @api public
     def auth(value)
       headers Headers::AUTHORIZATION => value.to_s
     end
 
     # Make a request with the given Basic authorization header
+    #
+    # @example
+    #   HTTP.basic_auth(user: "user", pass: "pass").get("http://example.com")
+    #
     # @see http://tools.ietf.org/html/rfc2617
-    # @param [#fetch] opts
-    # @option opts [#to_s] :user
-    # @option opts [#to_s] :pass
-    def basic_auth(opts)
-      user  = opts.fetch(:user)
-      pass  = opts.fetch(:pass)
-      creds = "#{user}:#{pass}"
+    # @param [#to_s] user
+    # @param [#to_s] pass
+    # @return [HTTP::Session]
+    # @api public
+    def basic_auth(user:, pass:)
+      auth("Basic #{encode64("#{user}:#{pass}")}")
+    end
 
-      auth("Basic #{Base64.strict_encode64(creds)}")
+    # Enable HTTP Digest authentication
+    #
+    # Automatically handles 401 Digest challenges by computing the digest
+    # response and retrying the request with proper credentials.
+    #
+    # @example
+    #   HTTP.digest_auth(user: "admin", pass: "secret").get("http://example.com")
+    #
+    # @see https://datatracker.ietf.org/doc/html/rfc2617
+    # @param [#to_s] user
+    # @param [#to_s] pass
+    # @return [HTTP::Session]
+    # @api public
+    def digest_auth(user:, pass:)
+      use(digest_auth: { user: user, pass: pass })
     end
 
     # Get options for HTTP
+    #
+    # @example
+    #   HTTP.default_options
+    #
     # @return [HTTP::Options]
+    # @api public
     def default_options
       @default_options ||= HTTP::Options.new
     end
 
     # Set options for HTTP
-    # @param opts
+    #
+    # @example
+    #   HTTP.default_options = { response: :object }
+    #
+    # @param [Hash, HTTP::Options] opts options to set
     # @return [HTTP::Options]
+    # @api public
     def default_options=(opts)
       @default_options = HTTP::Options.new(opts)
     end
 
     # Set TCP_NODELAY on the socket
+    #
+    # @example
+    #   HTTP.nodelay.get("http://example.com")
+    #
+    # @return [HTTP::Session]
+    # @api public
     def nodelay
       branch default_options.with_nodelay(true)
     end
 
-    # Turn on given features. Available features are:
-    # * auto_inflate
-    # * auto_deflate
-    # * instrumentation
-    # * logging
-    # * normalize_uri
-    # @param features
+    # Enable one or more features
+    #
+    # @example
+    #   HTTP.use(:auto_inflate).get("http://example.com")
+    #
+    # @param [Array<Symbol, Hash>] features features to enable
+    # @return [HTTP::Session]
+    # @api public
     def use(*features)
       branch default_options.with_features(features)
     end
 
+    # Return a retriable session that retries on failure
+    #
+    # @example Usage
+    #
+    #   # Retry max 5 times with randomly growing delay between retries
+    #   HTTP.retriable.get(url)
+    #
+    #   # Retry max 3 times with randomly growing delay between retries
+    #   HTTP.retriable(tries: 3).get(url)
+    #
+    #   # Retry max 3 times with 1 sec delay between retries
+    #   HTTP.retriable(tries: 3, delay: proc { 1 }).get(url)
+    #
+    #   # Retry max 3 times with geometrically progressed delay between retries
+    #   HTTP.retriable(tries: 3, delay: proc { |i| 1 + i*i }).get(url)
+    #
+    # @param (see Performer#initialize)
+    # @return [HTTP::Session]
+    # @api public
+    def retriable(tries: nil, delay: nil, exceptions: nil, retry_statuses: nil,
+                  on_retry: nil, max_delay: nil, should_retry: nil)
+      opts = { tries: tries, delay: delay, exceptions: exceptions, retry_statuses: retry_statuses,
+               on_retry: on_retry, max_delay: max_delay, should_retry: should_retry }.compact
+      branch default_options.with_retriable(opts.empty? || opts)
+    end
+
     private
 
-    # :nodoc:
+    # Create a new session with the given options
+    #
+    # @param [HTTP::Options] options options for the session
+    # @return [HTTP::Session]
+    # @api private
     def branch(options)
+      HTTP::Session.new(options)
+    end
+
+    # Create a new client for executing a request
+    #
+    # @param [HTTP::Options] options options for the client
+    # @return [HTTP::Client]
+    # @api private
+    def make_client(options)
       HTTP::Client.new(options)
     end
   end