http 5.3.1 → 6.0.0

data/lib/http/response/body.rb

@@ -9,50 +9,90 @@ module HTTP
     class Body
       extend Forwardable
       include Enumerable
+
       def_delegator :to_s, :empty?
 
-      # The connection object used to make the corresponding request.
+      # The connection object for the request
+      #
+      # @example
+      #   body.connection
       #
       # @return [HTTP::Connection]
+      # @api public
       attr_reader :connection
 
+      # The encoding used for the body content
+      #
+      # @example
+      #   body.encoding # => Encoding::UTF_8
+      #
+      # @return [Encoding]
+      # @api public
+      attr_reader :encoding
+
+      # Create a new Body instance
+      #
+      # @example
+      #   Body.new(stream, encoding: Encoding::UTF_8)
+      #
+      # @param stream [#readpartial] the response stream
+      # @param encoding [Encoding] the encoding to use
+      # @return [Body]
+      # @api public
       def initialize(stream, encoding: Encoding::BINARY)
         @stream     = stream
-        @connection = stream.is_a?(Inflater) ? stream.connection : stream
+        @connection = stream.respond_to?(:connection) ? stream.connection : stream
         @streaming  = nil
         @contents   = nil
         @encoding   = find_encoding(encoding)
       end
 
+      # Read a chunk of the body
+      #
+      # @example
+      #   body.readpartial # => "chunk of data"
+      #
       # (see HTTP::Client#readpartial)
-      def readpartial(*args)
+      # @return [String]
+      # @raise [EOFError] when no more data left
+      # @api public
+      def readpartial(*)
         stream!
-        chunk = @stream.readpartial(*args)
-
-        String.new(chunk, :encoding => @encoding) if chunk
+        chunk = @stream.readpartial(*)
+        String.new(chunk, encoding: @encoding)
       end
 
       # Iterate over the body, allowing it to be enumerable
+      #
+      # @example
+      #   body.each { |chunk| puts chunk }
+      #
+      # @yield [chunk] Passes each chunk to the block
+      # @yieldparam chunk [String]
+      # @return [void]
+      # @api public
       def each
-        while (chunk = readpartial)
-          yield chunk
+        loop do
+          yield readpartial
         end
+      rescue EOFError # rubocop:disable Lint/SuppressedException
       end
 
-      # @return [String] eagerly consume the entire body as a string
+      # Eagerly consume the entire body as a string
+      #
+      # @example
+      #   body.to_s # => "full response body"
+      #
+      # @return [String]
+      # @api public
       def to_s
         return @contents if @contents
 
         raise StateError, "body is being streamed" unless @streaming.nil?
 
         begin
-          @streaming  = false
-          @contents   = String.new("", :encoding => @encoding)
-
-          while (chunk = @stream.readpartial)
-            @contents << String.new(chunk, :encoding => @encoding)
-            chunk = nil # deallocate string
-          end
+          @streaming = false
+          @contents = read_contents
         rescue
           @contents = nil
           raise
@@ -63,20 +103,65 @@ module HTTP
       alias to_str to_s
 
       # Assert that the body is actively being streamed
+      #
+      # @example
+      #   body.stream!
+      #
+      # @return [true]
+      # @api public
       def stream!
-        raise StateError, "body has already been consumed" if @streaming == false
+        raise StateError, "body has already been consumed" if @streaming.eql?(false)
 
         @streaming = true
       end
 
+      # Whether the body content is suitable for logging
+      #
+      # Returns true when the body encoding is not binary. Binary responses
+      # (images, audio, compressed data) produce unreadable log output.
+      #
+      # @example
+      #   body.loggable? # => true
+      #
+      # @return [Boolean]
+      # @api public
+      def loggable?
+        @encoding != Encoding::BINARY
+      end
+
       # Easier to interpret string inspect
+      #
+      # @example
+      #   body.inspect # => "#<HTTP::Response::Body:3ff2 @streaming=false>"
+      #
+      # @return [String]
+      # @api public
       def inspect
         "#<#{self.class}:#{object_id.to_s(16)} @streaming=#{!!@streaming}>"
       end
 
       private
 
-      # Retrieve encoding by name. If encoding cannot be found, default to binary.
+      # Read all chunks into a single string
+      #
+      # @return [String]
+      # @api private
+      def read_contents
+        contents = String.new("", encoding: @encoding)
+
+        loop do
+          contents << String.new(@stream.readpartial, encoding: @encoding)
+        rescue EOFError
+          break
+        end
+
+        contents
+      end
+
+      # Retrieve encoding by name
+      #
+      # @return [Encoding]
+      # @api private
       def find_encoding(encoding)
         Encoding.find encoding
       rescue ArgumentError

data/lib/http/response/inflater.rb

@@ -4,26 +4,54 @@ require "zlib"
 
 module HTTP
   class Response
+    # Decompresses gzip/deflate response body streams
     class Inflater
+      # The underlying connection
+      #
+      # @example
+      #   inflater.connection
+      #
+      # @return [HTTP::Connection] the underlying connection
+      # @api public
       attr_reader :connection
 
+      # Create a new Inflater wrapping a connection
+      #
+      # @example
+      #   Inflater.new(connection)
+      #
+      # @param connection [HTTP::Connection] the connection to inflate
+      # @return [Inflater]
+      # @api public
       def initialize(connection)
         @connection = connection
       end
 
-      def readpartial(*args)
-        chunk = @connection.readpartial(*args)
-        if chunk
-          chunk = zstream.inflate(chunk)
-        elsif !zstream.closed?
-          zstream.finish if zstream.total_in.positive?
+      # Read and inflate a chunk of the response body
+      #
+      # @example
+      #   inflater.readpartial # => "decompressed data"
+      #
+      # @return [String]
+      # @raise [EOFError] when no more data left
+      # @api public
+      def readpartial(*)
+        chunk = @connection.readpartial(*)
+        zstream.inflate(chunk)
+      rescue EOFError
+        unless zstream.closed?
+          zstream.finished? ? zstream.finish : zstream.reset
           zstream.close
         end
-        chunk
+
+        raise
       end
 
       private
 
+      # Return the zlib inflate stream
+      # @return [Zlib::Inflate]
+      # @api private
       def zstream
         @zstream ||= Zlib::Inflate.new(32 + Zlib::MAX_WBITS)
       end

data/lib/http/response/parser.rb

@@ -4,16 +4,41 @@ require "llhttp"
 
 module HTTP
   class Response
+    # HTTP response parser backed by LLHttp
     # @api private
     class Parser
-      attr_reader :parser, :headers, :status_code, :http_version
-
+      # The underlying LLHttp parser
+      # @return [LLHttp::Parser] the underlying parser
+      # @api private
+      attr_reader :parser
+
+      # The parsed response headers
+      # @return [HTTP::Headers] the parsed headers
+      # @api private
+      attr_reader :headers
+
+      # The parsed HTTP status code
+      # @return [Integer, nil] the parsed status code
+      # @api private
+      attr_reader :status_code
+
+      # The parsed HTTP version string
+      # @return [String, nil] the parsed HTTP version
+      # @api private
+      attr_reader :http_version
+
+      # Create a new response parser
+      # @return [Parser]
+      # @api private
       def initialize
         @handler = Handler.new(self)
-        @parser = LLHttp::Parser.new(@handler, :type => :response)
+        @parser = LLHttp::Parser.new(@handler, type: :response)
         reset
       end
 
+      # Reset parser to initial state
+      # @return [void]
+      # @api private
       def reset
         @parser.reset
         @handler.reset
@@ -25,6 +50,9 @@ module HTTP
         @http_version = nil
       end
 
+      # Feed data into the parser
+      # @return [Parser]
+      # @api private
       def add(data)
         parser << data
 
@@ -33,30 +61,63 @@ module HTTP
         raise IOError, e.message
       end
 
+      # @see #add
+      # @api private
       alias << add
 
+      # Reset parser state for informational (1xx) responses
+      # @return [void]
+      # @api private
+      def reset_for_informational
+        @handler.reset
+        @header_finished = false
+        @message_finished = false
+        @headers = Headers.new
+        @chunk = nil
+        @status_code = nil
+        @http_version = nil
+      end
+
+      # Mark headers as finished
+      # @return [void]
+      # @api private
       def mark_header_finished
         @header_finished = true
         @status_code = @parser.status_code
         @http_version = "#{@parser.http_major}.#{@parser.http_minor}"
       end
 
+      # Check if headers have been parsed
+      # @return [Boolean]
+      # @api private
       def headers?
         @header_finished
       end
 
+      # Add a parsed header field and value
+      # @return [void]
+      # @api private
       def add_header(name, value)
         @headers.add(name, value)
       end
 
+      # Mark the message as fully parsed
+      # @return [void]
+      # @api private
       def mark_message_finished
         @message_finished = true
       end
 
+      # Check if the full message has been parsed
+      # @return [Boolean]
+      # @api private
       def finished?
         @message_finished
       end
 
+      # Append a body chunk to the buffer
+      # @return [void]
+      # @api private
       def add_body(chunk)
         if @chunk
           @chunk << chunk
@@ -65,6 +126,9 @@ module HTTP
         end
       end
 
+      # Read up to size bytes from the body buffer
+      # @return [String, nil]
+      # @api private
       def read(size)
         return if @chunk.nil?
 
@@ -79,44 +143,74 @@ module HTTP
         chunk
       end
 
+      # Delegate handler for LLHttp parser callbacks
+      # @api private
       class Handler < LLHttp::Delegate
+        # Create a new parser handler
+        # @return [Handler]
+        # @api private
         def initialize(target)
           @target = target
           super()
           reset
         end
 
+        # Reset handler state
+        # @return [void]
+        # @api private
         def reset
           @reading_header_value = false
           @field_value = +""
           @field = +""
         end
 
+        # Handle a header field token
+        # @return [void]
+        # @api private
         def on_header_field(field)
           append_header if @reading_header_value
           @field << field
         end
 
+        # Handle a header value token
+        # @return [void]
+        # @api private
         def on_header_value(value)
           @reading_header_value = true
           @field_value << value
         end
 
+        # Handle headers complete callback
+        # @return [void]
+        # @api private
         def on_headers_complete
           append_header if @reading_header_value
           @target.mark_header_finished
         end
 
+        # Handle body data callback
+        # @return [void]
+        # @api private
         def on_body(body)
           @target.add_body(body)
         end
 
+        # Handle message complete callback
+        # @return [void]
+        # @api private
         def on_message_complete
-          @target.mark_message_finished
+          if Integer(@target.status_code) < 200
+            @target.reset_for_informational
+          else
+            @target.mark_message_finished
+          end
         end
 
         private
 
+        # Flush the current header to the parser
+        # @return [void]
+        # @api private
         def append_header
           @target.add_header(@field, @field_value)
           @reading_header_value = false

data/lib/http/response/status/reasons.rb

@@ -2,11 +2,9 @@
 
 # AUTO-GENERATED FILE, DO NOT CHANGE IT MANUALLY
 
-require "delegate"
-
 module HTTP
   class Response
-    class Status < ::Delegator
+    class Status
       # Code to Reason map
       #
       # @example Usage
@@ -75,7 +73,7 @@ module HTTP
         508 => "Loop Detected",
         510 => "Not Extended",
         511 => "Network Authentication Required"
-      }.each { |_, v| v.freeze }.freeze
+      }.each_value(&:freeze).freeze
     end
   end
 end