http 5.3.1 → 6.0.0

data/lib/http/response/status.rb

@@ -1,29 +1,31 @@
 # frozen_string_literal: true
 
-require "delegate"
+require "forwardable"
 
 require "http/response/status/reasons"
 
 module HTTP
   class Response
-    class Status < ::Delegator
+    # Represents an HTTP response status code with reason phrase
+    class Status
+      include Comparable
+      extend Forwardable
+
       class << self
-        # Coerces given value to Status.
+        # Coerces given value to Status
         #
         # @example
-        #
         #   Status.coerce(:bad_request) # => Status.new(400)
-        #   Status.coerce("400")        # => Status.new(400)
-        #   Status.coerce(true)         # => raises HTTP::Error
         #
         # @raise [Error] if coercion is impossible
         # @param [Symbol, #to_i] object
         # @return [Status]
+        # @api public
         def coerce(object)
-          code = case
-                 when object.is_a?(String)  then SYMBOL_CODES[symbolize object]
-                 when object.is_a?(Symbol)  then SYMBOL_CODES[object]
-                 when object.is_a?(Numeric) then object.to_i
+          code = case object
+                 when String  then SYMBOL_CODES.fetch(symbolize(object), nil)
+                 when Symbol  then SYMBOL_CODES.fetch(object, nil)
+                 when Numeric then object
                  end
 
           return new code if code
@@ -36,16 +38,11 @@ module HTTP
 
         # Symbolizes given string
         #
-        # @example
-        #
-        #   symbolize "Bad Request"           # => :bad_request
-        #   symbolize "Request-URI Too Long"  # => :request_uri_too_long
-        #   symbolize "I'm a Teapot"          # => :im_a_teapot
-        #
         # @param [#to_s] str
         # @return [Symbol]
+        # @api private
         def symbolize(str)
-          str.to_s.downcase.tr("-", " ").gsub(/[^a-z ]/, "").gsub(/\s+/, "_").to_sym
+          str.downcase.tr("- ", "_").to_sym
         end
       end
 
@@ -71,66 +68,189 @@ module HTTP
       # @return [Hash<Symbol => Fixnum>]
       SYMBOL_CODES = SYMBOLS.to_h { |k, v| [v, k] }.freeze
 
+      # The numeric status code
+      #
+      # @example
+      #   status.code # => 200
+      #
       # @return [Fixnum] status code
+      # @api public
       attr_reader :code
 
+      # @!method to_i
+      #   Convert status to Integer
+      #   @example
+      #     status.to_i # => 200
+      #   @return [Integer]
+      #   @api public
+
+      # @!method to_int
+      #   Implicit conversion to Integer
+      #   @example
+      #     status.to_int # => 200
+      #   @return [Integer]
+      #   @api public
+      def_delegators :@code, :to_i, :to_int
+
+      # Create a new Status from a value that responds to #to_i
+      #
+      # @example
+      #   Status.new(200)
+      #
+      # @param [#to_i] obj
+      # @return [Status]
+      # @api public
+      def initialize(obj)
+        raise TypeError, "Expected #{obj.inspect} to respond to #to_i" unless obj.respond_to?(:to_i)
+
+        @code = obj.to_i
+      end
+
+      # Compare status codes for ordering
+      #
+      # @example
+      #   Status.new(200) <=> Status.new(404) # => -1
+      #
+      # @param [#to_i] other
+      # @return [Integer, nil]
+      # @api public
+      def <=>(other)
+        return nil unless other.respond_to?(:to_i)
+
+        code <=> other.to_i
+      end
+
+      # Hash value based on status code
+      #
+      # @example
+      #   Status.new(200).hash
+      #
+      # @return [Integer]
+      # @api public
+      def hash
+        code.hash
+      end
+
+      # Return the reason phrase for the status code
+      #
+      # @example
+      #   status.reason # => "OK"
+      #
       # @see REASONS
       # @return [String, nil] status message
+      # @api public
       def reason
         REASONS[code]
       end
 
-      # @return [String] string representation of HTTP status
+      # Return string representation of HTTP status
+      #
+      # @example
+      #   status.to_s # => "200 OK"
+      #
+      # @return [String]
+      # @api public
       def to_s
-        "#{code} #{reason}".strip
+        reason ? "#{code} #{reason}" : code.to_s
       end
 
       # Check if status code is informational (1XX)
+      #
+      # @example
+      #   status.informational? # => false
+      #
       # @return [Boolean]
+      # @api public
       def informational?
         100 <= code && code < 200
       end
 
       # Check if status code is successful (2XX)
+      #
+      # @example
+      #   status.success? # => true
+      #
       # @return [Boolean]
+      # @api public
       def success?
         200 <= code && code < 300
       end
 
       # Check if status code is redirection (3XX)
+      #
+      # @example
+      #   status.redirect? # => false
+      #
       # @return [Boolean]
+      # @api public
       def redirect?
         300 <= code && code < 400
       end
 
       # Check if status code is client error (4XX)
+      #
+      # @example
+      #   status.client_error? # => false
+      #
       # @return [Boolean]
+      # @api public
       def client_error?
         400 <= code && code < 500
       end
 
       # Check if status code is server error (5XX)
+      #
+      # @example
+      #   status.server_error? # => false
+      #
       # @return [Boolean]
+      # @api public
       def server_error?
         500 <= code && code < 600
       end
 
       # Symbolized {#reason}
       #
+      # @example
+      #   status.to_sym # => :ok
+      #
       # @return [nil] unless code is well-known (see REASONS)
       # @return [Symbol]
+      # @api public
       def to_sym
         SYMBOLS[code]
       end
 
-      # Printable version of HTTP Status, surrounded by quote marks,
-      # with special characters escaped.
+      # Printable version of HTTP Status
+      #
+      # @example
+      #   status.inspect # => "#<HTTP::Response::Status 200 OK>"
       #
       # (see String#inspect)
+      # @return [String]
+      # @api public
       def inspect
         "#<#{self.class} #{self}>"
       end
 
+      # Pattern matching interface for matching against status code and reason
+      #
+      # @example
+      #   case response.status
+      #   in { code: 200..299 }
+      #     "success"
+      #   in { code: 400.. }
+      #     "error"
+      #   end
+      #
+      # @param keys [Array<Symbol>, nil] keys to extract, or nil for all
+      # @return [Hash{Symbol => Object}]
+      # @api public
+      def deconstruct_keys(keys)
+        hash = { code: code, reason: reason }
+        keys ? hash.slice(*keys) : hash
+      end
+
       SYMBOLS.each do |code, symbol|
         class_eval <<-RUBY, __FILE__, __LINE__ + 1
           def #{symbol}?      # def bad_request?
@@ -138,16 +258,6 @@ module HTTP
           end                 # end
         RUBY
       end
-
-      def __setobj__(obj)
-        raise TypeError, "Expected #{obj.inspect} to respond to #to_i" unless obj.respond_to? :to_i
-
-        @code = obj.to_i
-      end
-
-      def __getobj__
-        @code
-      end
     end
   end
 end

data/lib/http/response.rb

@@ -2,190 +2,348 @@
 
 require "forwardable"
 
+require "http/errors"
 require "http/headers"
 require "http/content_type"
 require "http/mime_type"
 require "http/response/status"
 require "http/response/inflater"
-require "http/cookie_jar"
+require "http/cookie"
 require "time"
 
 module HTTP
+  # Represents an HTTP response with status, headers, and body
   class Response
     extend Forwardable
 
-    include HTTP::Headers::Mixin
-
-    # @return [Status]
+    # The response status
+    #
+    # @example
+    #   response.status # => #<HTTP::Response::Status 200>
+    #
+    # @return [Status] the response status
+    # @api public
     attr_reader :status
 
-    # @return [String]
+    # The HTTP version
+    #
+    # @example
+    #   response.version # => "1.1"
+    #
+    # @return [String] the HTTP version
+    # @api public
     attr_reader :version
 
-    # @return [Body]
+    # The response body
+    #
+    # @example
+    #   response.body
+    #
+    # @return [Body] the response body
+    # @api public
     attr_reader :body
 
-    # @return [Request]
+    # The original request
+    #
+    # @example
+    #   response.request
+    #
+    # @return [Request] the original request
+    # @api public
     attr_reader :request
 
-    # @return [Hash]
-    attr_reader :proxy_headers
+    # The HTTP headers collection
+    #
+    # @example
+    #   response.headers
+    #
+    # @return [HTTP::Headers] the response headers
+    # @api public
+    attr_reader :headers
 
-    # Inits a new instance
-    #
-    # @option opts [Integer] :status Status code
-    # @option opts [String] :version HTTP version
-    # @option opts [Hash] :headers
-    # @option opts [Hash] :proxy_headers
-    # @option opts [HTTP::Connection] :connection
-    # @option opts [String] :encoding Encoding to use when reading body
-    # @option opts [String] :body
-    # @option opts [HTTP::Request] request The request this is in response to.
-    # @option opts [String] :uri (DEPRECATED) used to populate a missing request
-    def initialize(opts)
-      @version       = opts.fetch(:version)
-      @request       = init_request(opts)
-      @status        = HTTP::Response::Status.new(opts.fetch(:status))
-      @headers       = HTTP::Headers.coerce(opts[:headers] || {})
-      @proxy_headers = HTTP::Headers.coerce(opts[:proxy_headers] || {})
-
-      if opts.include?(:body)
-        @body = opts.fetch(:body)
-      else
-        connection = opts.fetch(:connection)
-        encoding = opts[:encoding] || charset || default_encoding
+    # The proxy headers
+    #
+    # @example
+    #   response.proxy_headers
+    #
+    # @return [Hash] the proxy headers
+    # @api public
+    attr_reader :proxy_headers
 
-        @body = Response::Body.new(connection, :encoding => encoding)
-      end
+    # Create a new Response instance
+    #
+    # @example
+    #   Response.new(status: 200, version: "1.1", request: req)
+    #
+    # @param [Integer] status Status code
+    # @param [String] version HTTP version
+    # @param [Hash] headers
+    # @param [Hash] proxy_headers
+    # @param [HTTP::Connection, nil] connection
+    # @param [String, nil] encoding Encoding to use when reading body
+    # @param [String, nil] body
+    # @param [HTTP::Request, nil] request The request this is in response to
+    # @param [String, nil] uri (DEPRECATED) used to populate a missing request
+    # @return [Response]
+    # @api public
+    def initialize(status:, version:, headers: {}, proxy_headers: {}, connection: nil,
+                   encoding: nil, body: nil, request: nil, uri: nil)
+      @version       = version
+      @request       = init_request(request, uri)
+      @status        = HTTP::Response::Status.new(status)
+      @headers       = HTTP::Headers.coerce(headers)
+      @proxy_headers = HTTP::Headers.coerce(proxy_headers)
+      @body          = init_body(body, connection, encoding)
     end
 
     # @!method reason
-    #   @return (see HTTP::Response::Status#reason)
+    #   Return the reason phrase for the response status
+    #   @example
+    #     response.reason # => "OK"
+    #   @return [String, nil]
+    #   @api public
     def_delegator :@status, :reason
 
     # @!method code
-    #   @return (see HTTP::Response::Status#code)
+    #   Return the numeric status code
+    #   @example
+    #     response.code # => 200
+    #   @return [Integer]
+    #   @api public
     def_delegator :@status, :code
 
     # @!method to_s
-    #   (see HTTP::Response::Body#to_s)
+    #   Consume the response body as a string
+    #   @example
+    #     response.to_s # => "<html>...</html>"
+    #   @return [String]
+    #   @api public
     def_delegator :@body, :to_s
     alias to_str to_s
 
     # @!method readpartial
-    #   (see HTTP::Response::Body#readpartial)
+    #   Read a chunk of the response body
+    #   @example
+    #     response.readpartial # => "chunk"
+    #   @return [String]
+    #   @raise [EOFError] when no more data left
+    #   @api public
     def_delegator :@body, :readpartial
 
     # @!method connection
-    #   (see HTTP::Response::Body#connection)
+    #   Return the underlying connection object
+    #   @example
+    #     response.connection
+    #   @return [HTTP::Connection]
+    #   @api public
     def_delegator :@body, :connection
 
     # @!method uri
+    #   Return the URI of the original request
+    #   @example
+    #     response.uri # => #<HTTP::URI ...>
     #   @return (see HTTP::Request#uri)
+    #   @api public
     def_delegator :@request, :uri
 
     # Returns an Array ala Rack: `[status, headers, body]`
     #
+    # @example
+    #   response.to_a # => [200, {"Content-Type" => "text/html"}, "body"]
+    #
     # @return [Array(Fixnum, Hash, String)]
+    # @api public
     def to_a
       [status.to_i, headers.to_h, body.to_s]
     end
 
+    # @!method deconstruct
+    #   Array pattern matching interface
+    #
+    #   @example
+    #     response.deconstruct
+    #
+    #   @see #to_a
+    #   @return [Array(Integer, Hash, String)]
+    #   @api public
+    alias deconstruct to_a
+
+    # Pattern matching interface for matching against response attributes
+    #
+    # @example
+    #   case response
+    #   in { status: 200..299, body: /success/ }
+    #     "ok"
+    #   in { status: 400.. }
+    #     "error"
+    #   end
+    #
+    # @param keys [Array<Symbol>, nil] keys to extract, or nil for all
+    # @return [Hash{Symbol => Object}]
+    # @api public
+    def deconstruct_keys(keys)
+      hash = {
+        status:        @status,
+        version:       @version,
+        headers:       @headers,
+        body:          @body,
+        request:       @request,
+        proxy_headers: @proxy_headers
+      }
+      keys ? hash.slice(*keys) : hash
+    end
+
     # Flushes body and returns self-reference
     #
+    # @example
+    #   response.flush # => #<HTTP::Response ...>
+    #
     # @return [Response]
+    # @api public
     def flush
       body.to_s
       self
     end
 
-    # Value of the Content-Length header.
+    # Value of the Content-Length header
+    #
+    # @example
+    #   response.content_length # => 438
     #
     # @return [nil] if Content-Length was not given, or it's value was invalid
     #   (not an integer, e.g. empty string or string with non-digits).
     # @return [Integer] otherwise
+    # @api public
     def content_length
       # http://greenbytes.de/tech/webdav/rfc7230.html#rfc.section.3.3.3
       # Clause 3: "If a message is received with both a Transfer-Encoding
       # and a Content-Length header field, the Transfer-Encoding overrides the Content-Length.
       return nil if @headers.include?(Headers::TRANSFER_ENCODING)
 
-      value = @headers[Headers::CONTENT_LENGTH]
-      return nil unless value
+      # RFC 7230 Section 3.3.2: If multiple Content-Length values are present,
+      # they must all be identical; otherwise treat as invalid.
+      values = @headers.get(Headers::CONTENT_LENGTH).uniq
+      return nil unless values.one?
 
-      begin
-        Integer(value)
-      rescue ArgumentError
-        nil
-      end
+      Integer(values.first, exception: false)
     end
 
     # Parsed Content-Type header
     #
+    # @example
+    #   response.content_type # => #<HTTP::ContentType ...>
+    #
     # @return [HTTP::ContentType]
+    # @api public
     def content_type
       @content_type ||= ContentType.parse headers[Headers::CONTENT_TYPE]
     end
 
     # @!method mime_type
     #   MIME type of response (if any)
+    #   @example
+    #     response.mime_type # => "text/html"
     #   @return [String, nil]
+    #   @api public
     def_delegator :content_type, :mime_type
 
     # @!method charset
     #   Charset of response (if any)
+    #   @example
+    #     response.charset # => "utf-8"
     #   @return [String, nil]
+    #   @api public
     def_delegator :content_type, :charset
 
+    # Cookies from Set-Cookie headers
+    #
+    # @example
+    #   response.cookies # => [#<HTTP::Cookie ...>, ...]
+    #
+    # @return [Array<HTTP::Cookie>]
+    # @api public
     def cookies
-      @cookies ||= headers.get(Headers::SET_COOKIE).each_with_object CookieJar.new do |v, jar|
-        jar.parse(v, uri)
-      end
+      @cookies ||= headers.get(Headers::SET_COOKIE).flat_map { |v| HTTP::Cookie.parse(v, uri) }
     end
 
+    # Check if the response uses chunked transfer encoding
+    #
+    # @example
+    #   response.chunked? # => true
+    #
+    # @return [Boolean]
+    # @api public
     def chunked?
       return false unless @headers.include?(Headers::TRANSFER_ENCODING)
 
       encoding = @headers.get(Headers::TRANSFER_ENCODING)
 
-      # TODO: "chunked" is frozen in the request writer. How about making it accessible?
-      encoding.last == "chunked"
+      encoding.last == Headers::CHUNKED
     end
 
-    # Parse response body with corresponding MIME type adapter.
+    # Parse response body with corresponding MIME type adapter
+    #
+    # @example
+    #   response.parse("application/json") # => {"key" => "value"}
     #
     # @param type [#to_s] Parse as given MIME type.
     # @raise (see MimeType.[])
     # @return [Object]
+    # @api public
     def parse(type = nil)
       MimeType[type || mime_type].decode to_s
+    rescue => e
+      raise ParseError, e.message
     end
 
     # Inspect a response
+    #
+    # @example
+    #   response.inspect # => "#<HTTP::Response/1.1 200 OK text/html>"
+    #
+    # @return [String]
+    # @api public
     def inspect
-      "#<#{self.class}/#{@version} #{code} #{reason} #{headers.to_h.inspect}>"
+      "#<#{self.class}/#{@version} #{code} #{reason} #{mime_type}>"
     end
 
     private
 
+    # Determine the default encoding for the body
+    # @return [Encoding]
+    # @api private
     def default_encoding
       return Encoding::UTF_8 if mime_type == "application/json"
 
       Encoding::BINARY
     end
 
-    # Initialize an HTTP::Request from options.
+    # Initialize the response body
+    #
+    # @return [Body]
+    # @api private
+    def init_body(body, connection, encoding)
+      if body
+        body
+      else
+        encoding ||= charset || default_encoding
+
+        Response::Body.new(connection, encoding: encoding)
+      end
+    end
+
+    # Initialize an HTTP::Request
     #
     # @return [HTTP::Request]
-    def init_request(opts)
-      raise ArgumentError, ":uri is for backwards compatibilty and conflicts with :request" \
-        if opts[:request] && opts[:uri]
+    # @api private
+    def init_request(request, uri)
+      raise ArgumentError, ":uri is for backwards compatibilty and conflicts with :request" if request && uri
 
       # For backwards compatibilty
-      if opts[:uri]
-        HTTP::Request.new(:uri => opts[:uri], :verb => :get)
+      if uri
+        HTTP::Request.new(uri: uri, verb: :get)
       else
-        opts.fetch(:request)
+        request
       end
     end
   end