resolve #642 - Add Pattern Matching

Resolves feature request #642 requesting the addition of Pattern
Matching hooks for Ruby 2.7+ by introducing `to_h`, `deconstruct`, and
`deconstruct_keys` to core classes.

This change also addresses spec changes by gating pattern matching specs
on Ruby 2.7+ to prevent failures in older versions. All specs have also
been given a pattern matching spec matching their implementation to
demonstrate potential usages.

While demonstrational usages could dive into nested classes that are in
`HTTP` this was avoided to keep tests isolated from eachother.

Author: baweaver

lib/http/client.rb

@@ -102,6 +102,26 @@ def close
       @state = :clean
     end
 
+    # Hash representation of a client
+    #
+    # @return [Hash[Symbol, Any]]
+    def to_h
+      {
+        connection: @connection,
+        state: @state,
+      }
+    end
+
+    # Pattern matching interface
+    #
+    # @param keys [Array]
+    #   Keys to be extracted
+    #
+    # @return [Hash[Symbol, Any]]
+    def deconstruct_keys(keys)
+      to_h.slice(*keys)
+    end
+
     private
 
     def build_response(req, options)

lib/http/connection.rb

@@ -145,6 +145,35 @@ def expired?
       !@conn_expires_at || @conn_expires_at < Time.now
     end
 
+    # Hash representation of a connection
+    #
+    # @return [Hash[Symbol, Any]]
+    def to_h
+      {
+        persistent: @persistent,
+        keep_alive_timeout: @keep_alive_timeout,
+        pending_request: @pending_request,
+        pending_response: @pending_response,
+        failed_proxy_connect: @failed_proxy_connect,
+        buffer: @buffer,
+        parser: @parser,
+        socket: @socket,
+        status_code: status_code,
+        http_version: http_version,
+        headers: headers
+      }
+    end
+
+    # Pattern matching interface
+    #
+    # @param keys [Array]
+    #   Keys to be extracted
+    #
+    # @return [Hash[Symbol, Any]]
+    def deconstruct_keys(keys)
+      to_h.slice(*keys)
+    end
+
     private
 
     # Sets up SSL context and starts TLS if needed.

lib/http/content_type.rb

@@ -30,5 +30,25 @@ def initialize(mime_type = nil, charset = nil)
       @mime_type = mime_type
       @charset   = charset
     end
+
+    # Hash representaiton of ContentType
+    #
+    # @return [Hash[Symbol, Any]]
+    def to_h
+      {
+        mime_type: @mime_type,
+        charset: @charset,
+      }
+    end
+
+    # Pattern matching interface
+    #
+    # @param keys [Array[Symbol]]
+    #   Keys to extract
+    #
+    # @return [Hash[Symbol, Any]]
+    def deconstruct_keys(keys)
+      to_h.slice(*keys)
+    end
   end
 end

lib/http/headers.rb

@@ -115,13 +115,32 @@ def to_h
     end
     alias to_hash to_h
 
+    # Pattern matching interface
+    #
+    # @param keys [Array[Symbol]]
+    #   Keys to extract
+    #
+    # @return [Hash[Symbol, Any]]
+    def deconstruct_keys(keys)
+      underscored_keys_map = underscored_keys_mapping
+
+      self
+        .to_h
+        .map { |k, v| [underscored_keys_map[k], v] }
+        .to_h
+        .slice(*keys)
+    end
+
     # Returns headers key/value pairs.
     #
     # @return [Array<[String, String]>]
     def to_a
       @pile.map { |item| item[1..2] }
     end
 
+    # Adds pattern matching interface using `to_a` as a base
+    alias_method :deconstruct, :to_a
+
     # Returns human-readable representation of `self` instance.
     #
     # @return [String]
@@ -219,6 +238,14 @@ def coerce(object)
 
     private
 
+    # Underscored version of HTTP Header keys for
+    # Pattern Matching
+    #
+    # @return [Hash[String, Symbol]]
+    def underscored_keys_mapping
+      Hash[keys.map { |k| [k, k.tr('A-Z-', 'a-z_').to_sym] }]
+    end
+
     # Transforms `name` to canonical HTTP header capitalization
     #
     # @param [String] name

lib/http/options.rb

@@ -169,6 +169,16 @@ def to_hash
       Hash[*hash_pairs]
     end
 
+    # Pattern matching interface
+    #
+    # @param keys [Array]
+    #   Keys to be extracted
+    #
+    # @return [Hash[Symbol, Any]]
+    def deconstruct_keys(keys)
+      to_hash.slice(*keys)
+    end
+
     def dup
       dupped = super
       yield(dupped) if block_given?

lib/http/request.rb

@@ -199,6 +199,32 @@ def inspect
       "#<#{self.class}/#{@version} #{verb.to_s.upcase} #{uri}>"
     end
 
+    # Hash representation of a request
+    #
+    # @return [Hash[Symbol, Any]]
+    def to_h
+      {
+        verb: @verb,
+        uri: @uri,
+        scheme: @scheme,
+        proxy: @proxy,
+        version: @version,
+        headers: @headers,
+        body: @body,
+        port: port
+      }
+    end
+
+    # Pattern matching interface
+    #
+    # @param keys [Array]
+    #   Keys to be extracted
+    #
+    # @return [Hash[Symbol, Any]]
+    def deconstruct_keys(keys)
+      to_h.slice(*keys)
+    end
+
     private
 
     # @!attribute [r] host

lib/http/request/body.rb

@@ -49,6 +49,26 @@ def ==(other)
         self.class == other.class && self.source == other.source # rubocop:disable Style/RedundantSelf
       end
 
+      # Hash representation of a
+      #
+      # @return [Hash[Symbol, Any]]
+      def to_h
+        {
+          source: @source,
+          size: size
+        }
+      end
+
+      # Pattern matching interface
+      #
+      # @param keys [Array]
+      #   Keys to be extracted
+      #
+      # @return [Hash[Symbol, Any]]
+      def deconstruct_keys(keys)
+        to_h.slice(*keys)
+      end
+
       private
 
       def rewind(io)

lib/http/request/writer.rb

@@ -102,6 +102,28 @@ def chunked?
         @headers[Headers::TRANSFER_ENCODING] == CHUNKED
       end
 
+      # Hash representation of a
+      #
+      # @return [Hash[Symbol, Any]]
+      def to_h
+        {
+          body: @body,
+          socket: @socket,
+          headers: @headers,
+          request_header: @request_header,
+        }
+      end
+
+      # Pattern matching interface
+      #
+      # @param keys [Array]
+      #   Keys to be extracted
+      #
+      # @return [Hash[Symbol, Any]]
+      def deconstruct_keys(keys)
+        to_h.slice(*keys)
+      end
+
       private
 
       def write(data)

lib/http/response.rb

@@ -90,6 +90,34 @@ def to_a
       [status.to_i, headers.to_h, body.to_s]
     end
 
+    # Adds pattern matching interface using `to_a` as a base
+    alias_method :deconstruct, :to_a
+
+    # Returns a Hash of accessible properties
+    #
+    # @return [Hash[Symbol, Any]]
+    def to_h
+      {
+        version: @version,
+        request: @request,
+        status: @status,
+        headers: @headers,
+        proxy_headers: @proxy_headers,
+        body: @body,
+        status: @status,
+      }
+    end
+
+    # Pattern matching interface
+    #
+    # @param keys [Array]
+    #   Keys to be extracted
+    #
+    # @return [Hash[Symbol, Any]]
+    def deconstruct_keys(keys)
+      to_h.slice(*keys)
+    end
+
     # Flushes body and returns self-reference
     #
     # @return [Response]

lib/http/response/body.rb

@@ -72,6 +72,29 @@ def inspect
         "#<#{self.class}:#{object_id.to_s(16)} @streaming=#{!!@streaming}>"
       end
 
+      # Hash representation of a body
+      #
+      # @return [Hash[Symbol, Any]]
+      def to_h
+        {
+          stream: @stream,
+          connection: @connection,
+          streaming: @streaming,
+          contents: @contents,
+          encoding: @encoding,
+        }
+      end
+
+      # Pattern matching interface
+      #
+      # @param keys [Array[Symbol]]
+      #   Keys to extract
+      #
+      # @return [Hash[Symbol, Any]]
+      def deconstruct_keys(keys)
+        to_h.slice(*keys)
+      end
+
       private
 
       # Retrieve encoding by name. If encoding cannot be found, default to binary.