http 5.3.1 → 6.0.0

data/lib/http/features/auto_deflate.rb

@@ -1,42 +1,69 @@
 # frozen_string_literal: true
 
-require "zlib"
 require "tempfile"
+require "zlib"
 
 require "http/request/body"
 
 module HTTP
   module Features
+    # Automatically compresses request bodies with gzip or deflate
     class AutoDeflate < Feature
+      # Supported compression methods
+      VALID_METHODS = Set.new(%w[gzip deflate]).freeze
+
+      # Compression method name
+      #
+      # @example
+      #   feature.method # => "gzip"
+      #
+      # @return [String] compression method name
+      # @api public
       attr_reader :method
 
-      def initialize(**)
-        super
+      # Initializes the AutoDeflate feature
+      #
+      # @example
+      #   AutoDeflate.new(method: "gzip")
+      #
+      # @param method [String] compression method ("gzip" or "deflate")
+      # @return [AutoDeflate]
+      # @api public
+      def initialize(method: "gzip")
+        super()
 
-        @method = @opts.key?(:method) ? @opts[:method].to_s : "gzip"
+        @method = String(method)
 
-        raise Error, "Only gzip and deflate methods are supported" unless %w[gzip deflate].include?(@method)
+        raise Error, "Only gzip and deflate methods are supported" unless VALID_METHODS.include?(@method)
       end
 
+      # Wraps a request with compressed body
+      #
+      # @example
+      #   feature.wrap_request(request)
+      #
+      # @param request [HTTP::Request]
+      # @return [HTTP::Request]
+      # @api public
       def wrap_request(request)
         return request unless method
-        return request if request.body.size.zero?
+        return request if request.body.empty?
 
         # We need to delete Content-Length header. It will be set automatically by HTTP::Request::Writer
         request.headers.delete(Headers::CONTENT_LENGTH)
         request.headers[Headers::CONTENT_ENCODING] = method
 
-        Request.new(
-          :version        => request.version,
-          :verb           => request.verb,
-          :uri            => request.uri,
-          :headers        => request.headers,
-          :proxy          => request.proxy,
-          :body           => deflated_body(request.body),
-          :uri_normalizer => request.uri_normalizer
-        )
+        build_deflated_request(request)
       end
 
+      # Returns a compressed body for the given body
+      #
+      # @example
+      #   feature.deflated_body(body)
+      #
+      # @param body [HTTP::Request::Body]
+      # @return [GzippedBody, DeflatedBody, nil]
+      # @api public
       def deflated_body(body)
         case method
         when "gzip"
@@ -46,21 +73,62 @@ module HTTP
         end
       end
 
+      private
+
+      # Build a new request with deflated body
+      # @return [HTTP::Request]
+      # @api private
+      def build_deflated_request(request)
+        Request.new(
+          version:        request.version,
+          verb:           request.verb,
+          uri:            request.uri,
+          headers:        request.headers,
+          proxy:          request.proxy,
+          body:           deflated_body(request.body),
+          uri_normalizer: request.uri_normalizer
+        )
+      end
+
       HTTP::Options.register_feature(:auto_deflate, self)
 
+      # Base class for compressed request body wrappers
       class CompressedBody < HTTP::Request::Body
+        # Initializes a compressed body wrapper
+        #
+        # @example
+        #   CompressedBody.new(uncompressed_body)
+        #
+        # @param uncompressed_body [HTTP::Request::Body]
+        # @return [CompressedBody]
+        # @api public
         def initialize(uncompressed_body)
+          super(nil)
           @body       = uncompressed_body
           @compressed = nil
         end
 
+        # Returns the size of the compressed body
+        #
+        # @example
+        #   compressed_body.size
+        #
+        # @return [Integer]
+        # @api public
         def size
           compress_all! unless @compressed
           @compressed.size
         end
 
+        # Yields each chunk of compressed data
+        #
+        # @example
+        #   compressed_body.each { |chunk| io.write(chunk) }
+        #
+        # @return [self, Enumerator]
+        # @api public
         def each(&block)
-          return to_enum __method__ unless block
+          return to_enum(:each) unless block
 
           if @compressed
             compressed_each(&block)
@@ -73,6 +141,9 @@ module HTTP
 
         private
 
+        # Yield each chunk from compressed data
+        # @return [void]
+        # @api private
         def compressed_each
           while (data = @compressed.read(Connection::BUFFER_SIZE))
             yield data
@@ -81,14 +152,25 @@ module HTTP
           @compressed.close!
         end
 
+        # Compress all data to a tempfile
+        # @return [void]
+        # @api private
         def compress_all!
-          @compressed = Tempfile.new("http-compressed_body", :binmode => true)
+          @compressed = Tempfile.new("http-compressed_body", binmode: true)
           compress { |data| @compressed.write(data) }
           @compressed.rewind
         end
       end
 
+      # Gzip-compressed request body wrapper
       class GzippedBody < CompressedBody
+        # Compresses data using gzip
+        #
+        # @example
+        #   gzipped_body.compress { |data| io.write(data) }
+        #
+        # @return [nil]
+        # @api public
         def compress(&block)
           gzip = Zlib::GzipWriter.new(BlockIO.new(block))
           @body.each { |chunk| gzip.write(chunk) }
@@ -96,18 +178,43 @@ module HTTP
           gzip.finish
         end
 
+        # IO adapter that delegates writes to a block
         class BlockIO
+          # Initializes a block-based IO adapter
+          #
+          # @example
+          #   BlockIO.new(block)
+          #
+          # @param block [Proc]
+          # @return [BlockIO]
+          # @api public
           def initialize(block)
             @block = block
           end
 
+          # Writes data by calling the block
+          #
+          # @example
+          #   block_io.write("data")
+          #
+          # @param data [String]
+          # @return [Object]
+          # @api public
           def write(data)
             @block.call(data)
           end
         end
       end
 
+      # Deflate-compressed request body wrapper
       class DeflatedBody < CompressedBody
+        # Compresses data using deflate
+        #
+        # @example
+        #   deflated_body.compress { |data| io.write(data) }
+        #
+        # @return [nil]
+        # @api public
         def compress
           deflater = Zlib::Deflate.new
 

data/lib/http/features/auto_inflate.rb

@@ -1,35 +1,58 @@
 # frozen_string_literal: true
 
-require "set"
-
 module HTTP
   module Features
+    # Automatically decompresses response bodies
     class AutoInflate < Feature
       SUPPORTED_ENCODING = Set.new(%w[deflate gzip x-gzip]).freeze
       private_constant :SUPPORTED_ENCODING
 
+      # Wraps a response with an auto-inflating body
+      #
+      # @example
+      #   feature.wrap_response(response)
+      #
+      # @param response [HTTP::Response]
+      # @return [HTTP::Response]
+      # @api public
       def wrap_response(response)
         return response unless supported_encoding?(response)
 
-        options = {
-          :status        => response.status,
-          :version       => response.version,
-          :headers       => response.headers,
-          :proxy_headers => response.proxy_headers,
-          :connection    => response.connection,
-          :body          => stream_for(response.connection),
-          :request       => response.request
-        }
-
-        Response.new(options)
+        Response.new(**inflated_response_options(response)) # steep:ignore
       end
 
-      def stream_for(connection)
-        Response::Body.new(Response::Inflater.new(connection))
+      # Returns an inflating body stream for a connection
+      #
+      # @example
+      #   feature.stream_for(connection)
+      #
+      # @param connection [HTTP::Connection]
+      # @param encoding [Encoding] encoding to use for the inflated body
+      # @return [HTTP::Response::Body]
+      # @api public
+      def stream_for(connection, encoding: Encoding::BINARY)
+        Response::Body.new(Response::Inflater.new(connection), encoding: encoding)
       end
 
       private
 
+      # Build options hash for an inflated response
+      # @return [Hash]
+      # @api private
+      def inflated_response_options(response)
+        {
+          status:        response.status,
+          version:       response.version,
+          headers:       response.headers,
+          proxy_headers: response.proxy_headers,
+          connection:    response.connection,
+          body:          stream_for(response.connection, encoding: response.body.encoding),
+          request:       response.request
+        }
+      end
+
+      # Check if the response encoding is supported
+      # @api private
       def supported_encoding?(response)
         content_encoding = response.headers.get(Headers::CONTENT_ENCODING).first
         content_encoding && SUPPORTED_ENCODING.include?(content_encoding)

data/lib/http/features/caching/entry.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "time"
+
+module HTTP
+  module Features
+    class Caching < Feature
+      # A cached response entry with freshness logic
+      class Entry
+        # The HTTP status code
+        #
+        # @example
+        #   entry.status # => 200
+        #
+        # @return [Integer] the HTTP status code
+        # @api public
+        attr_reader :status
+
+        # The HTTP version
+        #
+        # @example
+        #   entry.version # => "1.1"
+        #
+        # @return [String] the HTTP version
+        # @api public
+        attr_reader :version
+
+        # The response headers
+        #
+        # @example
+        #   entry.headers
+        #
+        # @return [HTTP::Headers] the response headers
+        # @api public
+        attr_reader :headers
+
+        # The proxy headers from the original response
+        #
+        # @example
+        #   entry.proxy_headers
+        #
+        # @return [HTTP::Headers] the proxy headers
+        # @api public
+        attr_reader :proxy_headers
+
+        # The response body as a string
+        #
+        # @example
+        #   entry.body # => "<html>...</html>"
+        #
+        # @return [String] the response body
+        # @api public
+        attr_reader :body
+
+        # The URI of the original request
+        #
+        # @example
+        #   entry.request_uri
+        #
+        # @return [HTTP::URI] the request URI
+        # @api public
+        attr_reader :request_uri
+
+        # When the response was stored
+        #
+        # @example
+        #   entry.stored_at
+        #
+        # @return [Time] when the response was stored
+        # @api public
+        attr_reader :stored_at
+
+        # Create a new cache entry
+        #
+        # @example
+        #   Entry.new(status: 200, version: "1.1", headers: headers,
+        #             proxy_headers: proxy_headers, body: "hello",
+        #             request_uri: uri, stored_at: Time.now)
+        #
+        # @param status [Integer]
+        # @param version [String]
+        # @param headers [HTTP::Headers]
+        # @param proxy_headers [HTTP::Headers]
+        # @param body [String]
+        # @param request_uri [HTTP::URI]
+        # @param stored_at [Time]
+        # @return [Entry]
+        # @api public
+        def initialize(status:, version:, headers:, proxy_headers:, body:, request_uri:, stored_at:)
+          @status        = status
+          @version       = version
+          @headers       = headers
+          @proxy_headers = proxy_headers
+          @body          = body
+          @request_uri   = request_uri
+          @stored_at     = stored_at
+        end
+
+        # Whether the cached response is still fresh
+        #
+        # @example
+        #   entry.fresh? # => true
+        #
+        # @return [Boolean]
+        # @api public
+        def fresh?
+          return false if no_cache?
+
+          ttl = max_age
+          return age < ttl if ttl
+
+          expires = expires_at
+          return Time.now < expires if expires
+
+          false
+        end
+
+        # Reset the stored_at time to now (after successful revalidation)
+        #
+        # @example
+        #   entry.revalidate!
+        #
+        # @return [Time]
+        # @api public
+        def revalidate!
+          @stored_at = Time.now
+        end
+
+        # Merge response headers from a 304 revalidation into the stored entry
+        #
+        # @example
+        #   entry.update_headers!(response.headers)
+        #
+        # @param response_headers [HTTP::Headers]
+        # @return [void]
+        # @api public
+        def update_headers!(response_headers)
+          response_headers.each { |name, value| @headers[name] = value } # steep:ignore
+        end
+
+        private
+
+        # Age of the entry in seconds
+        # @return [Float]
+        # @api private
+        def age
+          Float(Integer(headers[Headers::AGE], exception: false) || 0) + (Time.now - stored_at)
+        end
+
+        # max-age value from Cache-Control, if present
+        # @return [Integer, nil]
+        # @api private
+        def max_age
+          match = String(headers[Headers::CACHE_CONTROL]).match(/max-age=(\d+)/)
+          return unless match
+
+          Integer(match[1])
+        end
+
+        # Expiration time from Expires header
+        # @return [Time, nil]
+        # @api private
+        def expires_at
+          Time.httpdate(String(headers[Headers::EXPIRES]))
+        rescue ArgumentError
+          nil
+        end
+
+        # Whether the Cache-Control includes no-cache
+        # @return [Boolean]
+        # @api private
+        def no_cache?
+          String(headers[Headers::CACHE_CONTROL]).downcase.include?("no-cache")
+        end
+      end
+    end
+  end
+end

data/lib/http/features/caching/in_memory_store.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module HTTP
+  module Features
+    class Caching < Feature
+      # Simple in-memory cache store backed by a Hash
+      #
+      # Cache keys are derived from the request method and URI.
+      #
+      # @example
+      #   store = InMemoryStore.new
+      #   store.store(request, entry)
+      #   store.lookup(request) # => entry
+      #
+      class InMemoryStore
+        # Create a new empty in-memory store
+        #
+        # @example
+        #   store = InMemoryStore.new
+        #
+        # @return [InMemoryStore]
+        # @api public
+        def initialize
+          @cache = {}
+        end
+
+        # Look up a cached entry for a request
+        #
+        # @example
+        #   store.lookup(request) # => Entry or nil
+        #
+        # @param request [HTTP::Request]
+        # @return [Entry, nil]
+        # @api public
+        def lookup(request)
+          @cache[cache_key(request)]
+        end
+
+        # Store a cache entry for a request
+        #
+        # @example
+        #   store.store(request, entry)
+        #
+        # @param request [HTTP::Request]
+        # @param entry [Entry]
+        # @return [Entry]
+        # @api public
+        def store(request, entry)
+          @cache[cache_key(request)] = entry
+        end
+
+        private
+
+        # Compute the cache key for a request
+        # @return [String]
+        # @api private
+        def cache_key(request)
+          format("%s %s", request.verb, request.uri)
+        end
+      end
+    end
+  end
+end