http 5.3.1 → 6.0.0

data/lib/http/headers.rb

@@ -3,7 +3,6 @@
 require "forwardable"
 
 require "http/errors"
-require "http/headers/mixin"
 require "http/headers/normalizer"
 require "http/headers/known"
 
@@ -14,32 +13,56 @@ module HTTP
     include Enumerable
 
     class << self
-      # Coerces given `object` into Headers.
+      # Coerces given object into Headers
+      #
+      # @example
+      #   headers = HTTP::Headers.coerce("Content-Type" => "text/plain")
       #
       # @raise [Error] if object can't be coerced
       # @param [#to_hash, #to_h, #to_a] object
       # @return [Headers]
+      # @api public
       def coerce(object)
-        unless object.is_a? self
-          object = case
-                   when object.respond_to?(:to_hash) then object.to_hash
-                   when object.respond_to?(:to_h)    then object.to_h
-                   when object.respond_to?(:to_a)    then object.to_a
-                   else raise Error, "Can't coerce #{object.inspect} to Headers"
-                   end
-        end
+        object = if    object.respond_to?(:to_hash) then object.to_hash
+                 elsif object.respond_to?(:to_h)    then object.to_h
+                 elsif object.respond_to?(:to_a)    then object.to_a
+                 else raise Error, "Can't coerce #{object.inspect} to Headers"
+                 end
+
         headers = new
         object.each { |k, v| headers.add k, v }
         headers
       end
+      # @!method [](object)
+      #   Coerces given object into Headers
+      #
+      #   @example
+      #     headers = HTTP::Headers["Content-Type" => "text/plain"]
+      #
+      #   @see .coerce
+      #   @return [Headers]
+      #   @api public
       alias [] coerce
 
+      # Returns the shared normalizer instance
+      #
+      # @example
+      #   HTTP::Headers.normalizer
+      #
+      # @return [Headers::Normalizer]
+      # @api public
       def normalizer
-        @normalizer ||= Headers::Normalizer.new
+        @normalizer ||= Normalizer.new #: Headers::Normalizer
       end
     end
 
-    # Class constructor.
+    # Creates a new empty headers container
+    #
+    # @example
+    #   headers = HTTP::Headers.new
+    #
+    # @return [Headers]
+    # @api public
     def initialize
       # The @pile stores each header value using a three element array:
       #  0 - the normalized header key, used for lookup
@@ -48,26 +71,46 @@ module HTTP
       @pile = []
     end
 
-    # Sets header.
+    # Sets header, replacing any existing values
+    #
+    # @example
+    #   headers.set("Content-Type", "text/plain")
     #
     # @param (see #add)
     # @return [void]
+    # @api public
     def set(name, value)
       delete(name)
       add(name, value)
     end
+    # @!method []=(name, value)
+    #   Sets header, replacing any existing values
+    #
+    #   @example
+    #     headers["Content-Type"] = "text/plain"
+    #
+    #   @see #set
+    #   @return [void]
+    #   @api public
     alias []= set
 
-    # Removes header.
+    # Removes header with the given name
+    #
+    # @example
+    #   headers.delete("Content-Type")
     #
     # @param [#to_s] name header name
     # @return [void]
+    # @api public
     def delete(name)
-      name = normalize_header name.to_s
-      @pile.delete_if { |k, _| k == name }
+      name = normalize_header name
+      @pile.delete_if { |k, _| k.eql?(name) }
     end
 
-    # Appends header.
+    # Appends header value(s) to the given name
+    #
+    # @example
+    #   headers.add("Accept", "text/html")
     #
     # @param [String, Symbol] name header name. When specified as a string, the
     #   name is sent as-is. When specified as a symbol, the name is converted
@@ -77,16 +120,11 @@ module HTTP
     #   is sent as `"auth_key"`.
     # @param [Array<#to_s>, #to_s] value header value(s) to be appended
     # @return [void]
+    # @api public
     def add(name, value)
-      lookup_name = normalize_header(name.to_s)
-      wire_name = case name
-                  when String
-                    name
-                  when Symbol
-                    lookup_name
-                  else
-                    raise HTTP::HeaderError, "HTTP header must be a String or Symbol: #{name.inspect}"
-                  end
+      lookup_name = normalize_header(name)
+      wire_name = wire_name_for(name, lookup_name)
+
       Array(value).each do |v|
         @pile << [
           lookup_name,
@@ -96,139 +134,208 @@ module HTTP
       end
     end
 
-    # Returns list of header values if any.
+    # Returns list of header values if any
+    #
+    # @example
+    #   headers.get("Content-Type")
     #
     # @return [Array<String>]
+    # @api public
     def get(name)
-      name = normalize_header name.to_s
-      @pile.select { |k, _| k == name }.map { |_, _, v| v }
+      name = normalize_header name
+      @pile.filter_map { |k, _, v| v if k.eql?(name) }
     end
 
-    # Smart version of {#get}.
+    # Smart version of {#get}
+    #
+    # @example
+    #   headers["Content-Type"]
     #
     # @return [nil] if header was not set
     # @return [String] if header has exactly one value
     # @return [Array<String>] if header has more than one value
+    # @api public
     def [](name)
       values = get(name)
+      return if values.empty?
 
-      case values.count
-      when 0 then nil
-      when 1 then values.first
-      else        values
-      end
+      return values unless values.one?
+
+      values.join
     end
 
-    # Tells whenever header with given `name` is set or not.
+    # Tells whether header with given name is set
+    #
+    # @example
+    #   headers.include?("Content-Type")
     #
     # @return [Boolean]
+    # @api public
     def include?(name)
-      name = normalize_header name.to_s
-      @pile.any? { |k, _| k == name }
+      name = normalize_header name
+      @pile.any? { |k, _| k.eql?(name) }
     end
 
     # Returns Rack-compatible headers Hash
     #
+    # @example
+    #   headers.to_h
+    #
     # @return [Hash]
+    # @api public
     def to_h
       keys.to_h { |k| [k, self[k]] }
     end
+    # @!method to_hash
+    #   @see #to_h
+    #   @return [Hash]
     alias to_hash to_h
 
-    # Returns headers key/value pairs.
+    # Pattern matching interface
     #
-    # @return [Array<[String, String]>]
-    def to_a
-      @pile.map { |item| item[1..2] }
+    # @example
+    #   headers.deconstruct_keys(%i[content_type])
+    #
+    # @param keys [Array<Symbol>, nil] keys to extract, or nil for all
+    # @return [Hash{Symbol => Object}]
+    # @api public
+    def deconstruct_keys(keys)
+      hash = @pile.map { |_, k, _| k }.to_h { |k| [k.tr("A-Z-", "a-z_").to_sym, self[k]] }
+      keys ? hash.slice(*keys) : hash
     end
 
-    # Returns human-readable representation of `self` instance.
+    # Returns human-readable representation of self instance
+    #
+    # @example
+    #   headers.inspect
     #
     # @return [String]
-    def inspect
-      "#<#{self.class} #{to_h.inspect}>"
-    end
+    # @api public
+    def inspect = "#<#{self.class}>"
 
-    # Returns list of header names.
+    # Returns list of header names
+    #
+    # @example
+    #   headers.keys
     #
     # @return [Array<String>]
+    # @api public
     def keys
       @pile.map { |_, k, _| k }.uniq
     end
 
-    # Compares headers to another Headers or Array of key/value pairs
+    # Compares headers to another Headers or Array of pairs
+    #
+    # @example
+    #   headers == other_headers
     #
     # @return [Boolean]
+    # @api public
     def ==(other)
       return false unless other.respond_to? :to_a
 
-      to_a == other.to_a
+      to_a.eql?(other.to_a)
     end
 
-    # Calls the given block once for each key/value pair in headers container.
+    # Calls the given block once for each key/value pair
+    #
+    # @example
+    #   headers.each { |name, value| puts "#{name}: #{value}" }
     #
     # @return [Enumerator] if no block given
     # @return [Headers] self-reference
+    # @api public
     def each
-      return to_enum(__method__) unless block_given?
+      return to_enum unless block_given?
 
-      @pile.each { |item| yield(item[1..2]) }
+      @pile.each { |item| yield(item.drop(1)) }
       self
     end
 
     # @!method empty?
-    #   Returns `true` if `self` has no key/value pairs
+    #   Returns true if self has no key/value pairs
+    #
+    #   @example
+    #     headers.empty?
     #
     #   @return [Boolean]
+    #   @api public
     def_delegator :@pile, :empty?
 
     # @!method hash
-    #   Compute a hash-code for this headers container.
-    #   Two containers with the same content will have the same hash code.
+    #   Computes a hash-code for this headers container
+    #
+    #   @example
+    #     headers.hash
     #
     #   @see http://www.ruby-doc.org/core/Object.html#method-i-hash
     #   @return [Fixnum]
+    #   @api public
     def_delegator :@pile, :hash
 
-    # Properly clones internal key/value storage.
+    # Properly clones internal key/value storage
     #
+    # @return [void]
     # @api private
-    def initialize_copy(orig)
-      super
+    def initialize_copy(_orig)
       @pile = @pile.map(&:dup)
     end
 
-    # Merges `other` headers into `self`.
+    # Merges other headers into self
+    #
+    # @example
+    #   headers.merge!("Accept" => "text/html")
     #
     # @see #merge
     # @return [void]
+    # @api public
     def merge!(other)
-      self.class.coerce(other).to_h.each { |name, values| set name, values }
+      coerced = self.class.coerce(other)
+      names = coerced.keys
+      names.each { |name| set name, coerced.get(name) }
     end
 
-    # Returns new instance with `other` headers merged in.
+    # Returns new instance with other headers merged in
+    #
+    # @example
+    #   new_headers = headers.merge("Accept" => "text/html")
     #
     # @see #merge!
     # @return [Headers]
+    # @api public
     def merge(other)
       dup.tap { |dupped| dupped.merge! other }
     end
 
     private
 
-    # Transforms `name` to canonical HTTP header capitalization
-    def normalize_header(name)
-      self.class.normalizer.call(name)
+    # Returns the wire name for a header
+    #
+    # @return [String]
+    # @api private
+    def wire_name_for(name, lookup_name)
+      case name
+      when String then name
+      when Symbol then lookup_name
+      else raise HeaderError, "HTTP header must be a String or Symbol: #{name.inspect}"
+      end
     end
 
+    # Transforms name to canonical HTTP header capitalization
+    #
+    # @return [String]
+    # @api private
+    def normalize_header(name) = self.class.normalizer.call(name)
+
     # Ensures there is no new line character in the header value
     #
     # @param [String] value
     # @raise [HeaderError] if value includes new line character
     # @return [String] stringified header value
+    # @api private
     def validate_value(value)
       v = value.to_s
-      return v unless v.include?("\n")
+      return v unless v.include?("\n") || v.include?("\r")
 
       raise HeaderError, "Invalid HTTP header field value: #{v.inspect}"
     end

data/lib/http/mime_type/adapter.rb

@@ -11,18 +11,33 @@ module HTTP
 
       class << self
         extend Forwardable
-        def_delegators :instance, :encode, :decode
+
+        def_delegators :instance, :encode, :decode # steep:ignore
+      end
+
+      # Encodes data into the MIME type format
+      #
+      # @example
+      #   adapter.encode("foo" => "bar")
+      #
+      # @return [String] encoded representation
+      # @raise [Error] if not implemented by subclass
+      # @api public
+      def encode(*)
+        raise Error, "#{self.class} does not supports #encode"
       end
 
-      # rubocop:disable Style/DocumentDynamicEvalDefinition
-      %w[encode decode].each do |operation|
-        class_eval <<-RUBY, __FILE__, __LINE__ + 1
-          def #{operation}(*)
-            fail Error, "\#{self.class} does not supports ##{operation}"
-          end
-        RUBY
+      # Decodes data from the MIME type format
+      #
+      # @example
+      #   adapter.decode("{\"foo\":\"bar\"}")
+      #
+      # @return [Object] decoded data
+      # @raise [Error] if not implemented by subclass
+      # @api public
+      def decode(*)
+        raise Error, "#{self.class} does not supports #decode"
       end
-      # rubocop:enable Style/DocumentDynamicEvalDefinition
     end
   end
 end

data/lib/http/mime_type/json.rb

@@ -4,17 +4,32 @@ require "json"
 require "http/mime_type/adapter"
 
 module HTTP
+  # MIME type registry and adapter interface
   module MimeType
     # JSON encode/decode MIME type adapter
     class JSON < Adapter
       # Encodes object to JSON
+      #
+      # @example
+      #   adapter = HTTP::MimeType::JSON.new
+      #   adapter.encode(foo: "bar")
+      #
+      # @param [Object] obj object to encode
+      # @api public
+      # @return [String]
       def encode(obj)
-        return obj.to_json if obj.respond_to?(:to_json)
-
-        ::JSON.dump obj
+        obj.to_json
       end
 
-      # Decodes JSON
+      # Decodes JSON string into Ruby object
+      #
+      # @example
+      #   adapter = HTTP::MimeType::JSON.new
+      #   adapter.decode('{"foo":"bar"}')
+      #
+      # @param [String] str JSON string to decode
+      # @api public
+      # @return [Object]
       def decode(str)
         ::JSON.parse str
       end

data/lib/http/mime_type.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "http/errors"
+
 module HTTP
   # MIME type encode/decode adapters
   module MimeType
@@ -24,6 +26,7 @@ module HTTP
       #
       # @param [#to_s] type
       # @param [#encode, #decode] adapter
+      # @api public
       # @return [void]
       def register_adapter(type, adapter)
         adapters[type.to_s] = adapter
@@ -31,11 +34,15 @@ module HTTP
 
       # Returns adapter associated with MIME type
       #
+      # @example
+      #   HTTP::MimeType["application/json"]
+      #
       # @param [#to_s] type
       # @raise [Error] if no adapter found
+      # @api public
       # @return [Class]
       def [](type)
-        adapters[normalize type] || raise(Error, "Unknown MIME type: #{type}")
+        adapters[normalize type] || raise(UnsupportedMimeTypeError, "Unknown MIME type: #{type}")
       end
 
       # Register a shortcut for MIME type
@@ -46,6 +53,7 @@ module HTTP
       #
       # @param [#to_s] type
       # @param [#to_sym] shortcut
+      # @api public
       # @return [void]
       def register_alias(type, shortcut)
         aliases[shortcut.to_sym] = type.to_s
@@ -53,7 +61,11 @@ module HTTP
 
       # Resolves type by shortcut if possible
       #
+      # @example
+      #   HTTP::MimeType.normalize(:json)
+      #
       # @param [#to_s] type
+      # @api public
       # @return [String]
       def normalize(type)
         aliases.fetch type, type.to_s
@@ -61,12 +73,18 @@ module HTTP
 
       private
 
-      # :nodoc:
+      # Returns the adapters registry hash
+      #
+      # @api private
+      # @return [Hash]
       def adapters
         @adapters ||= {}
       end
 
-      # :nodoc:
+      # Returns the aliases registry hash
+      #
+      # @api private
+      # @return [Hash]
       def aliases
         @aliases ||= {}
       end