http 5.3.1 → 6.0.0

data/lib/http/connection.rb

@@ -2,20 +2,28 @@
 
 require "forwardable"
 
+require "http/connection/internals"
 require "http/headers"
 
 module HTTP
   # A connection to the HTTP server
   class Connection
     extend Forwardable
+    include Internals
 
     # Allowed values for CONNECTION header
     KEEP_ALIVE = "Keep-Alive"
+    # Connection: close header value
     CLOSE      = "close"
 
     # Attempt to read this much data
     BUFFER_SIZE = 16_384
 
+    # Maximum response body size (in bytes) to auto-flush when reusing
+    # a connection. Bodies larger than this cause the connection to close
+    # instead, to avoid blocking on huge downloads.
+    MAX_FLUSH_SIZE = 1_048_576
+
     # HTTP/1.0
     HTTP_1_0 = "1.0"
 
@@ -23,27 +31,30 @@ module HTTP
     HTTP_1_1 = "1.1"
 
     # Returned after HTTP CONNECT (via proxy)
+    #
+    # @example
+    #   connection.proxy_response_headers
+    #
+    # @return [HTTP::Headers, nil]
+    # @api public
     attr_reader :proxy_response_headers
 
+    # Initialize a new connection to an HTTP server
+    #
+    # @example
+    #   Connection.new(req, options)
+    #
     # @param [HTTP::Request] req
     # @param [HTTP::Options] options
+    # @return [Connection]
     # @raise [HTTP::ConnectionError] when failed to connect
+    # @api public
     def initialize(req, options)
-      @persistent           = options.persistent?
-      @keep_alive_timeout   = options.keep_alive_timeout.to_f
-      @pending_request      = false
-      @pending_response     = false
-      @failed_proxy_connect = false
-      @buffer               = "".b
-
-      @parser = Response::Parser.new
-
-      @socket = options.timeout_class.new(options.timeout_options)
-      @socket.connect(options.socket_class, req.socket_host, req.socket_port, options.nodelay)
-
-      send_proxy_connect_request(req)
-      start_tls(req, options)
-      reset_timer
+      init_state(options)
+      connect_socket(req, options)
+    rescue IO::TimeoutError => e
+      close
+      raise ConnectTimeoutError, e.message, e.backtrace
     rescue IOError, SocketError, SystemCallError => e
       raise ConnectionError, "failed to connect: #{e}", e.backtrace
     rescue TimeoutError
@@ -60,19 +71,37 @@ module HTTP
     # @see (HTTP::Response::Parser#headers)
     def_delegator :@parser, :headers
 
+    # Whether the proxy CONNECT request failed
+    #
+    # @example
+    #   connection.failed_proxy_connect?
+    #
     # @return [Boolean] whenever proxy connect failed
+    # @api public
     def failed_proxy_connect?
       @failed_proxy_connect
     end
 
+    # Set the pending response for auto-flushing before the next request
+    #
+    # @example
+    #   connection.pending_response = response
+    #
+    # @param [HTTP::Response, false] response
+    # @return [void]
+    # @api public
+    attr_writer :pending_response
+
     # Send a request to the server
     #
+    # @example
+    #   connection.send_request(req)
+    #
     # @param [Request] req Request to send to the server
     # @return [nil]
+    # @api public
     def send_request(req)
-      if @pending_response
-        raise StateError, "Tried to send a request while one is pending already. Make sure you read off the body."
-      end
+      flush_pending_response if @pending_response
 
       if @pending_request
         raise StateError, "Tried to send a request while a response is pending. Make sure you read off the body."
@@ -88,24 +117,37 @@ module HTTP
 
     # Read a chunk of the body
     #
+    # @example
+    #   connection.readpartial
+    #
+    # @param [Integer] size maximum bytes to read
+    # @param [String, nil] outbuf buffer to fill with data
     # @return [String] data chunk
-    # @return [nil] when no more data left
-    def readpartial(size = BUFFER_SIZE)
-      return unless @pending_response
+    # @raise [EOFError] when no more data left
+    # @api public
+    def readpartial(size = BUFFER_SIZE, outbuf = nil)
+      raise EOFError unless @pending_response
 
       chunk = @parser.read(size)
-      return chunk if chunk
-
-      finished = (read_more(size) == :eof) || @parser.finished?
-      chunk    = @parser.read(size)
-      finish_response if finished
+      unless chunk
+        eof = read_more(size) == :eof
+        check_premature_eof(eof)
+        finished = eof || @parser.finished?
+        chunk    = @parser.read(size) || "".b
+        finish_response if finished
+      end
 
-      chunk || "".b
+      outbuf ? outbuf.replace(chunk) : chunk
     end
 
     # Reads data from socket up until headers are loaded
+    #
+    # @example
+    #   connection.read_headers!
+    #
     # @return [void]
     # @raise [ResponseHeaderError] when unable to read response headers
+    # @api public
     def read_headers!
       until @parser.headers?
         result = read_more(BUFFER_SIZE)
@@ -116,7 +158,12 @@ module HTTP
     end
 
     # Callback for when we've reached the end of a response
+    #
+    # @example
+    #   connection.finish_response
+    #
     # @return [void]
+    # @api public
     def finish_response
       close unless keep_alive?
 
@@ -128,7 +175,12 @@ module HTTP
     end
 
     # Close the connection
+    #
+    # @example
+    #   connection.close
+    #
     # @return [void]
+    # @api public
     def close
       @socket.close unless @socket&.closed?
 
@@ -136,101 +188,78 @@ module HTTP
       @pending_request  = false
     end
 
+    # Whether there are no pending requests or responses
+    #
+    # @example
+    #   connection.finished_request?
+    #
+    # @return [Boolean]
+    # @api public
     def finished_request?
       !@pending_request && !@pending_response
     end
 
     # Whether we're keeping the conn alive
+    #
+    # @example
+    #   connection.keep_alive?
+    #
     # @return [Boolean]
+    # @api public
     def keep_alive?
-      !!@keep_alive && !@socket.closed?
+      @keep_alive && !@socket.closed?
     end
 
     # Whether our connection has expired
+    #
+    # @example
+    #   connection.expired?
+    #
     # @return [Boolean]
+    # @api public
     def expired?
       !@conn_expires_at || @conn_expires_at < Time.now
     end
 
     private
 
-    # Sets up SSL context and starts TLS if needed.
-    # @param (see #initialize)
+    # Initialize connection state
     # @return [void]
-    def start_tls(req, options)
-      return unless req.uri.https? && !failed_proxy_connect?
-
-      ssl_context = options.ssl_context
-
-      unless ssl_context
-        ssl_context = OpenSSL::SSL::SSLContext.new
-        ssl_context.set_params(options.ssl || {})
-      end
-
-      @socket.start_tls(req.uri.host, options.ssl_socket_class, ssl_context)
-    end
-
-    # Open tunnel through proxy
-    def send_proxy_connect_request(req)
-      return unless req.uri.https? && req.using_proxy?
-
-      @pending_request = true
-
-      req.connect_using_proxy @socket
-
-      @pending_request  = false
-      @pending_response = true
-
-      read_headers!
-      @proxy_response_headers = @parser.headers
-
-      if @parser.status_code != 200
-        @failed_proxy_connect = true
-        return
-      end
-
-      @parser.reset
-      @pending_response = false
+    # @api private
+    def init_state(options)
+      @persistent           = options.persistent?
+      @keep_alive_timeout   = options.keep_alive_timeout.to_f
+      @pending_request      = false
+      @pending_response     = false
+      @failed_proxy_connect = false
+      @buffer               = "".b
+      @parser               = Response::Parser.new
     end
 
-    # Resets expiration of persistent connection.
+    # Check for premature end-of-file and raise if detected
+    #
+    # @example
+    #   check_premature_eof(:eof)
+    #
     # @return [void]
-    def reset_timer
-      @conn_expires_at = Time.now + @keep_alive_timeout if @persistent
-    end
+    # @api private
+    def check_premature_eof(eof)
+      return unless eof && !@parser.finished? && body_framed?
 
-    # Store whether the connection should be kept alive.
-    # Once we reset the parser, we lose all of this state.
-    # @return [void]
-    def set_keep_alive
-      return @keep_alive = false unless @persistent
-
-      @keep_alive =
-        case @parser.http_version
-        when HTTP_1_0 # HTTP/1.0 requires opt in for Keep Alive
-          @parser.headers[Headers::CONNECTION] == KEEP_ALIVE
-        when HTTP_1_1 # HTTP/1.1 is opt-out
-          @parser.headers[Headers::CONNECTION] != CLOSE
-        else # Anything else we assume doesn't supportit
-          false
-        end
+      close
+      raise ConnectionError, "response body ended prematurely"
     end
 
-    # Feeds some more data into parser
+    # Connect socket and set up proxy/TLS
     # @return [void]
-    # @raise [SocketReadError] when unable to read from socket
-    def read_more(size)
-      return if @parser.finished?
-
-      value = @socket.readpartial(size, @buffer)
-      if value == :eof
-        @parser << ""
-        :eof
-      elsif value
-        @parser << value
-      end
-    rescue IOError, SocketError, SystemCallError => e
-      raise SocketReadError, "error reading from socket: #{e}", e.backtrace
+    # @api private
+    def connect_socket(req, options)
+      @socket = options.timeout_class.new(**options.timeout_options) # steep:ignore
+      @socket.connect(options.socket_class, req.socket_host, req.socket_port, nodelay: options.nodelay)
+
+      send_proxy_connect_request(req)
+      start_tls(req, options)
+      reset_timer
     end
   end
 end

data/lib/http/content_type.rb

@@ -1,34 +1,89 @@
 # frozen_string_literal: true
 
 module HTTP
+  # Parsed representation of a Content-Type header
   class ContentType
-    MIME_TYPE_RE = %r{^([^/]+/[^;]+)(?:$|;)}.freeze
-    CHARSET_RE   = /;\s*charset=([^;]+)/i.freeze
+    # Pattern for extracting MIME type from Content-Type header
+    MIME_TYPE_RE = %r{^([^/]+/[^;]+)(?:$|;)}
+    # Pattern for extracting charset from Content-Type header
+    CHARSET_RE   = /;\s*charset=([^;]+)/i
 
-    attr_accessor :mime_type, :charset
+    # MIME type of the content
+    #
+    # @example
+    #   content_type.mime_type # => "text/html"
+    #
+    # @return [String, nil]
+    # @api public
+    attr_accessor :mime_type
+
+    # Character set of the content
+    #
+    # @example
+    #   content_type.charset # => "utf-8"
+    #
+    # @return [String, nil]
+    # @api public
+    attr_accessor :charset
 
     class << self
-      # Parse string and return ContentType struct
+      # Parse string and return ContentType object
+      #
+      # @example
+      #   HTTP::ContentType.parse("text/html; charset=utf-8")
+      #
+      # @param [String] str content type header value
+      # @return [ContentType]
+      # @api public
       def parse(str)
         new mime_type(str), charset(str)
       end
 
       private
 
-      # :nodoc:
+      # Extract MIME type from header string
+      # @return [String, nil]
+      # @api private
       def mime_type(str)
         str.to_s[MIME_TYPE_RE, 1]&.strip&.downcase
       end
 
-      # :nodoc:
+      # Extract charset from header string
+      # @return [String, nil]
+      # @api private
       def charset(str)
         str.to_s[CHARSET_RE, 1]&.strip&.delete('"')
       end
     end
 
+    # Create a new ContentType instance
+    #
+    # @example
+    #   HTTP::ContentType.new("text/html", "utf-8")
+    #
+    # @param [String, nil] mime_type MIME type
+    # @param [String, nil] charset character set
+    # @return [ContentType]
+    # @api public
     def initialize(mime_type = nil, charset = nil)
       @mime_type = mime_type
       @charset   = charset
     end
+
+    # Pattern matching interface for matching against content type attributes
+    #
+    # @example
+    #   case response.content_type
+    #   in { mime_type: /json/ }
+    #     "JSON content"
+    #   end
+    #
+    # @param keys [Array<Symbol>, nil] keys to extract, or nil for all
+    # @return [Hash{Symbol => Object}]
+    # @api public
+    def deconstruct_keys(keys)
+      hash = { mime_type: @mime_type, charset: @charset }
+      keys ? hash.slice(*keys) : hash
+    end
   end
 end

data/lib/http/errors.rb

@@ -9,7 +9,9 @@ module HTTP
 
   # Types of Connection errors
   class ResponseHeaderError < ConnectionError; end
+  # Error raised when reading from a socket fails
   class SocketReadError < ConnectionError; end
+  # Error raised when writing to a socket fails
   class SocketWriteError < ConnectionError; end
 
   # Generic Request error
@@ -23,8 +25,23 @@ module HTTP
 
   # When status code indicates an error
   class StatusError < ResponseError
+    # The HTTP response that caused the error
+    #
+    # @example
+    #   error.response
+    #
+    # @return [HTTP::Response]
+    # @api public
     attr_reader :response
 
+    # Create a new StatusError from a response
+    #
+    # @example
+    #   HTTP::StatusError.new(response)
+    #
+    # @param [HTTP::Response] response the response with error status
+    # @return [StatusError]
+    # @api public
     def initialize(response)
       @response = response
 
@@ -32,10 +49,17 @@ module HTTP
     end
   end
 
+  # Raised when `Response#parse` fails due to any underlying reason (unexpected
+  # MIME type, or decoder fails). See `Exception#cause` for the original exception.
+  class ParseError < ResponseError; end
+
+  # Requested MimeType adapter not found.
+  class UnsupportedMimeTypeError < Error; end
+
   # Generic Timeout error
   class TimeoutError < Error; end
 
-  # Timeout when first establishing the conncetion
+  # Timeout when first establishing the connection
   class ConnectTimeoutError < TimeoutError; end
 
   # Header value is of unexpected format (similar to Net::HTTPHeaderSyntaxError)

data/lib/http/feature.rb

@@ -1,25 +1,85 @@
 # frozen_string_literal: true
 
 module HTTP
+  # Base class for HTTP client features (middleware)
   class Feature
-    def initialize(opts = {})
-      @opts = opts
-    end
-
+    # Wraps an HTTP request
+    #
+    # @example
+    #   feature.wrap_request(request)
+    #
+    # @param request [HTTP::Request]
+    # @return [HTTP::Request]
+    # @api public
     def wrap_request(request)
       request
     end
 
+    # Wraps an HTTP response
+    #
+    # @example
+    #   feature.wrap_response(response)
+    #
+    # @param response [HTTP::Response]
+    # @return [HTTP::Response]
+    # @api public
     def wrap_response(response)
       response
     end
 
-    def on_error(request, error); end
+    # Callback invoked before each request attempt
+    #
+    # Unlike {#wrap_request}, which is called once when the request is built,
+    # this hook is called before every attempt, including retries. Use it for
+    # per-attempt side effects like starting instrumentation spans.
+    #
+    # @example
+    #   feature.on_request(request)
+    #
+    # @param _request [HTTP::Request]
+    # @return [nil]
+    # @api public
+    def on_request(_request); end
+
+    # Wraps the HTTP exchange for a single request attempt
+    #
+    # Called once per attempt (including retries), wrapping the send and
+    # receive cycle. The block performs the I/O and returns the response.
+    # Override this to add behavior that must span the entire exchange,
+    # such as instrumentation spans or circuit breakers.
+    #
+    # @example Timing a request
+    #   def around_request(request)
+    #     start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    #     yield(request).tap { log_duration(Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) }
+    #   end
+    #
+    # @param request [HTTP::Request]
+    # @yield [HTTP::Request] the request to perform
+    # @yieldreturn [HTTP::Response]
+    # @return [HTTP::Response] must return the response from yield
+    # @api public
+    def around_request(request)
+      yield request
+    end
+
+    # Callback for request errors
+    #
+    # @example
+    #   feature.on_error(request, error)
+    #
+    # @param _request [HTTP::Request]
+    # @param _error [Exception]
+    # @return [nil]
+    # @api public
+    def on_error(_request, _error); end
   end
 end
 
 require "http/features/auto_inflate"
 require "http/features/auto_deflate"
+require "http/features/caching"
+require "http/features/digest_auth"
 require "http/features/instrumentation"
 require "http/features/logging"
 require "http/features/normalize_uri"