http 5.3.1 → 6.0.0

data/lib/http/features/caching.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "time"
+
+require "http/features/caching/entry"
+require "http/features/caching/in_memory_store"
+
+module HTTP
+  module Features
+    # HTTP caching feature that stores and reuses responses according to
+    # RFC 7234. Only GET and HEAD responses are cached. Supports
+    # `Cache-Control`, `Expires`, `ETag`, and `Last-Modified` for freshness
+    # checks and conditional revalidation.
+    #
+    # @example Basic usage with in-memory cache
+    #   HTTP.use(:caching).get("https://example.com/")
+    #
+    # @example With a shared store across requests
+    #   store = HTTP::Features::Caching::InMemoryStore.new
+    #   client = HTTP.use(caching: { store: store })
+    #   client.get("https://example.com/")
+    #
+    class Caching < Feature
+      CACHEABLE_METHODS = Set.new(%i[get head]).freeze
+      private_constant :CACHEABLE_METHODS
+
+      # The cache store instance
+      #
+      # @example
+      #   feature.store
+      #
+      # @return [#lookup, #store] the cache store
+      # @api public
+      attr_reader :store
+
+      # Initializes the Caching feature
+      #
+      # @example
+      #   Caching.new(store: InMemoryStore.new)
+      #
+      # @param store [#lookup, #store] cache store instance
+      # @return [Caching]
+      # @api public
+      def initialize(store: InMemoryStore.new)
+        @store = store
+      end
+
+      # Wraps the HTTP exchange with caching logic
+      #
+      # Checks the cache before making a request. Returns a cached response
+      # if fresh; otherwise adds conditional headers and revalidates. Stores
+      # cacheable responses for future use.
+      #
+      # @example
+      #   feature.around_request(request) { |req| perform_exchange(req) }
+      #
+      # @param request [HTTP::Request]
+      # @yield Executes the HTTP exchange
+      # @yieldreturn [HTTP::Response]
+      # @return [HTTP::Response]
+      # @api public
+      def around_request(request)
+        return yield(request) unless cacheable_request?(request)
+
+        entry = store.lookup(request)
+
+        return yield(request) unless entry
+
+        return build_cached_response(entry, request) if entry.fresh?
+
+        response = yield(add_conditional_headers(request, entry))
+
+        return revalidate_entry(entry, response, request) if response.status.not_modified?
+
+        response
+      end
+
+      # Stores cacheable responses in the cache
+      #
+      # @example
+      #   feature.wrap_response(response)
+      #
+      # @param response [HTTP::Response]
+      # @return [HTTP::Response]
+      # @api public
+      def wrap_response(response)
+        return response unless cacheable_request?(response.request)
+        return response unless cacheable_response?(response)
+
+        store_and_freeze_response(response)
+      end
+
+      private
+
+      # Revalidate a cached entry with a 304 response
+      # @return [HTTP::Response]
+      # @api private
+      def revalidate_entry(entry, response, request)
+        entry.update_headers!(response.headers)
+        entry.revalidate!
+        build_cached_response(entry, request)
+      end
+
+      # Store response in cache and return a new response with eagerly-read body
+      # @return [HTTP::Response]
+      # @api private
+      def store_and_freeze_response(response)
+        body_string = String(response)
+        store.store(response.request, build_entry(response, body_string))
+
+        Response.new(
+          status:        response.code,
+          version:       response.version,
+          headers:       response.headers,
+          proxy_headers: response.proxy_headers,
+          body:          body_string,
+          request:       response.request
+        )
+      end
+
+      # Build a cache entry from a response
+      # @return [Entry]
+      # @api private
+      def build_entry(response, body_string)
+        Entry.new(
+          status:        response.code,
+          version:       response.version,
+          headers:       response.headers.dup,
+          proxy_headers: response.proxy_headers,
+          body:          body_string,
+          request_uri:   response.uri,
+          stored_at:     now
+        )
+      end
+
+      # Check whether this request method is cacheable
+      # @return [Boolean]
+      # @api private
+      def cacheable_request?(request)
+        CACHEABLE_METHODS.include?(request.verb)
+      end
+
+      # Check whether this response is cacheable
+      # @return [Boolean]
+      # @api private
+      def cacheable_response?(response)
+        return false if response.status < 200
+        return false if response.status >= 400
+
+        directives = parse_cache_control(response.headers)
+        return false if directives.include?("no-store")
+
+        freshness_info?(response, directives)
+      end
+
+      # Whether the response carries enough information to determine freshness
+      # @return [Boolean]
+      # @api private
+      def freshness_info?(response, directives)
+        return true if directives.any? { |d| d.start_with?("max-age=") }
+        return true if response.headers.include?(Headers::EXPIRES)
+        return true if response.headers.include?(Headers::ETAG)
+
+        response.headers.include?(Headers::LAST_MODIFIED)
+      end
+
+      # Parse Cache-Control header into a list of directives
+      # @return [Array<String>]
+      # @api private
+      def parse_cache_control(headers)
+        String(headers[Headers::CACHE_CONTROL]).downcase.split(",").map(&:strip)
+      end
+
+      # Add conditional headers from a cached entry to the request
+      # @return [HTTP::Request]
+      # @api private
+      def add_conditional_headers(request, entry)
+        headers = request.headers.dup
+        headers[Headers::IF_NONE_MATCH] = entry.headers[Headers::ETAG] # steep:ignore
+        headers[Headers::IF_MODIFIED_SINCE] = entry.headers[Headers::LAST_MODIFIED] # steep:ignore
+
+        Request.new(
+          verb:    request.verb,
+          uri:     request.uri,
+          headers: headers,
+          proxy:   request.proxy,
+          body:    request.body,
+          version: request.version
+        )
+      end
+
+      # Build a response from a cached entry
+      # @return [HTTP::Response]
+      # @api private
+      def build_cached_response(entry, request)
+        Response.new(
+          status:        entry.status,
+          version:       entry.version,
+          headers:       entry.headers,
+          proxy_headers: entry.proxy_headers,
+          body:          entry.body,
+          request:       request
+        )
+      end
+
+      # Current time (extracted for testability)
+      # @return [Time]
+      # @api private
+      def now
+        Time.now
+      end
+
+      HTTP::Options.register_feature(:caching, self)
+    end
+  end
+end

data/lib/http/features/digest_auth.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require "digest"
+require "securerandom"
+
+module HTTP
+  module Features
+    # Implements HTTP Digest Authentication (RFC 2617 / RFC 7616)
+    #
+    # When a server responds with 401 and a Digest challenge, this feature
+    # automatically computes the digest response and retries the request
+    # with the correct Authorization header.
+    class DigestAuth < Feature
+      # Supported hash algorithms
+      ALGORITHMS = {
+        "MD5"          => Digest::MD5,
+        "SHA-256"      => Digest::SHA256,
+        "MD5-sess"     => Digest::MD5,
+        "SHA-256-sess" => Digest::SHA256
+      }.freeze
+
+      # WWW-Authenticate header name
+      # @api private
+      WWW_AUTHENTICATE = "WWW-Authenticate"
+
+      # Initialize the DigestAuth feature
+      #
+      # @example
+      #   DigestAuth.new(user: "admin", pass: "secret")
+      #
+      # @param user [String] username for authentication
+      # @param pass [String] password for authentication
+      # @return [DigestAuth]
+      # @api public
+      def initialize(user:, pass:)
+        @user = user
+        @pass = pass
+      end
+
+      # Wraps the HTTP exchange to handle digest authentication challenges
+      #
+      # On a 401 with a Digest WWW-Authenticate header, flushes the error
+      # response, computes digest credentials, and retries the request.
+      #
+      # @example
+      #   feature.around_request(request) { |req| perform(req) }
+      #
+      # @param request [HTTP::Request]
+      # @yield [HTTP::Request] the request to perform
+      # @yieldreturn [HTTP::Response]
+      # @return [HTTP::Response]
+      # @api public
+      def around_request(request)
+        response = yield request
+        return response unless digest_challenge?(response)
+
+        response.flush
+        yield authorize(request, response)
+      end
+
+      private
+
+      # Check if the response contains a digest authentication challenge
+      #
+      # @param response [HTTP::Response]
+      # @return [Boolean]
+      # @api private
+      def digest_challenge?(response)
+        www_auth = response.headers[WWW_AUTHENTICATE] #: String?
+        response.status.code == 401 && www_auth&.start_with?("Digest ") == true
+      end
+
+      # Build an authorized copy of the request using the digest challenge
+      #
+      # @param request [HTTP::Request] the original request
+      # @param response [HTTP::Response] the 401 response with challenge
+      # @return [HTTP::Request] a new request with Authorization header
+      # @api private
+      def authorize(request, response)
+        www_auth = response.headers[WWW_AUTHENTICATE] #: String
+        challenge = parse_challenge(www_auth)
+        headers   = request.headers.dup
+        headers.set Headers::AUTHORIZATION, build_auth(request, challenge)
+
+        Request.new(
+          verb:           request.verb,
+          uri:            request.uri,
+          headers:        headers,
+          proxy:          request.proxy,
+          body:           request.body.source,
+          version:        request.version,
+          uri_normalizer: request.uri_normalizer
+        )
+      end
+
+      # Parse the WWW-Authenticate header into a parameter hash
+      #
+      # @param header [String] the WWW-Authenticate header value
+      # @return [Hash{String => String}] parsed challenge parameters
+      # @api private
+      def parse_challenge(header)
+        params = {} #: Hash[String, String]
+        header.sub(/\ADigest\s+/i, "").scan(/(\w+)=(?:"([^"]*)"|([\w-]+))/) do |match|
+          key = match[0] #: String
+          params[key] = format("%s", match[1] || match[2])
+        end
+        params
+      end
+
+      # Build the Authorization header value
+      #
+      # @param request [HTTP::Request] the request being authorized
+      # @param challenge [Hash{String => String}] parsed challenge params
+      # @return [String] the Digest authorization header value
+      # @api private
+      def build_auth(request, challenge)
+        algorithm   = challenge.fetch("algorithm", "MD5")
+        qop         = select_qop(challenge["qop"])
+        nonce       = challenge.fetch("nonce")
+        cnonce      = SecureRandom.hex(16)
+        nonce_count = "00000001"
+        uri         = String(request.uri.request_uri)
+        ha1 = compute_ha1(algorithm, challenge.fetch("realm"), nonce, cnonce)
+        ha2 = compute_ha2(algorithm, String(request.verb).upcase, uri)
+
+        compute_auth_header(algorithm: algorithm, qop: qop, nonce: nonce, cnonce: cnonce,
+                            nonce_count: nonce_count, uri: uri, ha1: ha1, ha2: ha2,
+                            challenge: challenge)
+      end
+
+      # Compute digest and build the Authorization header string
+      #
+      # @return [String] formatted authorization header
+      # @api private
+      def compute_auth_header(algorithm:, qop:, nonce:, cnonce:, nonce_count:, uri:, ha1:, ha2:, challenge:)
+        response = compute_response(algorithm, ha1, ha2, nonce: nonce,
+                                    nonce_count: nonce_count, cnonce: cnonce, qop: qop)
+
+        build_header(username: @user, realm: challenge.fetch("realm"), nonce: nonce, uri: uri,
+                     qop: qop, nonce_count: nonce_count, cnonce: cnonce, response: response,
+                     opaque: challenge["opaque"], algorithm: algorithm)
+      end
+
+      # Select the best qop value from the challenge
+      #
+      # @param qop_str [String, nil] comma-separated qop options
+      # @return [String, nil] selected qop value
+      # @api private
+      def select_qop(qop_str)
+        return unless qop_str
+
+        qops = qop_str.split(",").map(&:strip)
+        return "auth" if qops.include?("auth")
+
+        qops.first
+      end
+
+      # Compute HA1 per RFC 2617
+      #
+      # @return [String] hex digest
+      # @api private
+      def compute_ha1(algorithm, realm, nonce, cnonce)
+        base = hex_digest(algorithm, "#{@user}:#{realm}:#{@pass}")
+
+        if algorithm.end_with?("-sess")
+          hex_digest(algorithm, "#{base}:#{nonce}:#{cnonce}")
+        else
+          base
+        end
+      end
+
+      # Compute HA2 per RFC 2617
+      #
+      # @return [String] hex digest
+      # @api private
+      def compute_ha2(algorithm, method, uri)
+        hex_digest(algorithm, "#{method}:#{uri}")
+      end
+
+      # Compute the final digest response value
+      #
+      # @param algorithm [String] algorithm name
+      # @param ha1 [String] HA1 hex digest
+      # @param ha2 [String] HA2 hex digest
+      # @param nonce [String] server nonce
+      # @param nonce_count [String] request counter
+      # @param cnonce [String] client nonce
+      # @param qop [String, nil] quality of protection
+      # @return [String] hex digest
+      # @api private
+      def compute_response(algorithm, ha1, ha2, nonce:, nonce_count:, cnonce:, qop:)
+        if qop
+          hex_digest(algorithm, "#{ha1}:#{nonce}:#{nonce_count}:#{cnonce}:#{qop}:#{ha2}")
+        else
+          hex_digest(algorithm, "#{ha1}:#{nonce}:#{ha2}")
+        end
+      end
+
+      # Compute a hex digest using the specified algorithm
+      #
+      # @param algorithm [String] algorithm name
+      # @param data [String] data to digest
+      # @return [String] hex digest
+      # @api private
+      def hex_digest(algorithm, data)
+        ALGORITHMS.fetch(algorithm.sub(/-sess\z/i, "")).hexdigest(data)
+      end
+
+      # Build the Digest Authorization header string
+      #
+      # @return [String] formatted header value
+      # @api private
+      def build_header(username:, realm:, nonce:, uri:, qop:, nonce_count:, cnonce:,
+                       response:, opaque:, algorithm:)
+        parts = [
+          %(username="#{username}"),
+          %(realm="#{realm}"),
+          %(nonce="#{nonce}"),
+          %(uri="#{uri}")
+        ]
+
+        parts.push(%(qop=#{qop}), %(nc=#{nonce_count}), %(cnonce="#{cnonce}")) if qop
+
+        parts << %(response="#{response}")
+        parts << %(opaque="#{opaque}") if opaque
+        parts << %(algorithm=#{algorithm})
+
+        "Digest #{parts.join(', ')}"
+      end
+
+      HTTP::Options.register_feature(:digest_auth, self)
+    end
+  end
+end

data/lib/http/features/instrumentation.rb

@@ -19,34 +19,100 @@ module HTTP
     #    and `finish` so the duration of the request can be calculated.
     #
     class Instrumentation < Feature
-      attr_reader :instrumenter, :name, :error_name
+      # The instrumenter instance
+      #
+      # @example
+      #   feature.instrumenter
+      #
+      # @return [#instrument] the instrumenter instance
+      # @api public
+      attr_reader :instrumenter
 
+      # The event name for requests
+      #
+      # @example
+      #   feature.name # => "request.http"
+      #
+      # @return [String] the event name for requests
+      # @api public
+      attr_reader :name
+
+      # The event name for errors
+      #
+      # @example
+      #   feature.error_name # => "error.http"
+      #
+      # @return [String] the event name for errors
+      # @api public
+      attr_reader :error_name
+
+      # Initializes the Instrumentation feature
+      #
+      # @example
+      #   Instrumentation.new(instrumenter: ActiveSupport::Notifications.instrumenter)
+      #
+      # @param instrumenter [#instrument] instrumenter instance
+      # @param namespace [String] event namespace
+      # @return [Instrumentation]
+      # @api public
       def initialize(instrumenter: NullInstrumenter.new, namespace: "http")
+        super()
         @instrumenter = instrumenter
         @name = "request.#{namespace}"
         @error_name = "error.#{namespace}"
       end
 
-      def wrap_request(request)
+      # Wraps the HTTP exchange with instrumentation
+      #
+      # Emits a `"start_request.http"` event before the request, then wraps
+      # the exchange in a `"request.http"` span that is guaranteed to close
+      # on both success and failure (via the instrumenter's ensure block).
+      #
+      # @example
+      #   feature.around_request(request) { perform_io }
+      #
+      # @param request [HTTP::Request]
+      # @yield Executes the HTTP exchange
+      # @yieldreturn [HTTP::Response]
+      # @return [HTTP::Response]
+      # @api public
+      def around_request(request)
         # Emit a separate "start" event, so a logger can print the request
         # being run without waiting for a response
-        instrumenter.instrument("start_#{name}", :request => request)
-        instrumenter.start(name, :request => request)
-        request
-      end
-
-      def wrap_response(response)
-        instrumenter.finish(name, :response => response)
-        response
+        instrumenter.instrument("start_#{name}", request: request) {} # rubocop:disable Lint/EmptyBlock
+        instrumenter.instrument(name, request: request) do |payload|
+          response = yield request
+          payload[:response] = response if payload
+          response
+        end
       end
 
+      # Instruments a request error
+      #
+      # @example
+      #   feature.on_error(request, error)
+      #
+      # @param request [HTTP::Request]
+      # @param error [Exception]
+      # @return [Object]
+      # @api public
       def on_error(request, error)
-        instrumenter.instrument(error_name, :request => request, :error => error)
+        instrumenter.instrument(error_name, request: request, error: error) {} # rubocop:disable Lint/EmptyBlock
       end
 
       HTTP::Options.register_feature(:instrumentation, self)
 
+      # No-op instrumenter used as default when none is provided
       class NullInstrumenter
+        # Instruments an event with a name and payload
+        #
+        # @example
+        #   instrumenter.instrument("request.http", request: req)
+        #
+        # @param name [String]
+        # @param payload [Hash]
+        # @return [Object]
+        # @api public
         def instrument(name, payload = {})
           start(name, payload)
           begin
@@ -56,13 +122,27 @@ module HTTP
           end
         end
 
-        def start(_name, _payload)
-          true
-        end
+        # Starts an instrumentation event
+        #
+        # @example
+        #   instrumenter.start("request.http", request: req)
+        #
+        # @param _name [String]
+        # @param _payload [Hash]
+        # @return [nil]
+        # @api public
+        def start(_name, _payload); end
 
-        def finish(_name, _payload)
-          true
-        end
+        # Finishes an instrumentation event
+        #
+        # @example
+        #   instrumenter.finish("request.http", response: resp)
+        #
+        # @param _name [String]
+        # @param _payload [Hash]
+        # @return [nil]
+        # @api public
+        def finish(_name, _payload); end
       end
     end
   end