hearth 1.0.0.pre1 → 1.0.0.pre2

data/lib/hearth/http/field.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Hearth
+  module HTTP
+    # Represents an HTTP field.
+    class Field
+      # @param [String] name The name of the field.
+      # @param [Array|#to_s] value (nil) The values for the field. It can be any
+      #   object that responds to `#to_s` or an Array of objects that respond to
+      #  `#to_s`.
+      # @param [Symbol] kind The kind of field, either :header or :trailer.
+      def initialize(name, value = nil, kind: :header)
+        if name.nil? || name.empty?
+          raise ArgumentError, 'Field name must be a non-empty String'
+        end
+
+        @name = name
+        @value = value
+        @kind = kind
+      end
+
+      # @return [String]
+      attr_reader :name
+
+      # @return [Symbol]
+      attr_reader :kind
+
+      # Returns an escaped string representation of the field.
+      # @return [String]
+      def value(encoding = nil)
+        value =
+          if @value.is_a?(Array)
+            @value.compact.map { |v| escape_value(v.to_s) }.join(', ')
+          else
+            @value.to_s
+          end
+        value = value.encode(encoding) if encoding
+        value
+      end
+
+      # @return [Boolean]
+      def header?
+        @kind == :header
+      end
+
+      # @return [Boolean]
+      def trailer?
+        @kind == :trailer
+      end
+
+      # @return [Hash]
+      def to_h
+        { @name => value }
+      end
+
+      private
+
+      def escape_value(str)
+        s = str
+        s.include?('"') || s.include?(',') ? "\"#{s.gsub('"', '\"')}\"" : s
+      end
+    end
+  end
+end

data/lib/hearth/http/fields.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Hearth
+  module HTTP
+    # Provides Hash like access for Headers and Trailers with key normalization
+    class Fields
+      include Enumerable
+
+      # @param [Array<Field>] fields
+      # @param [String] encoding
+      def initialize(fields = [], encoding: 'utf-8')
+        unless fields.is_a?(Enumerable)
+          raise ArgumentError, 'fields must be an Enumerable of Field'
+        end
+
+        @entries = {}
+        fields.each { |field| self[field.name] = field }
+        @encoding = encoding
+      end
+
+      # @return [String]
+      attr_reader :encoding
+
+      # @param [String] key
+      def [](key)
+        @entries[key.downcase]
+      end
+
+      # @param [String] key
+      # @param [Field] value
+      def []=(key, value)
+        raise ArgumentError, 'value must be a Field' unless value.is_a?(Field)
+
+        @entries[key.downcase] = value
+      end
+
+      # @param [String] key
+      # @return [Boolean] Returns `true` if there is a Field with the given key.
+      def key?(key)
+        @entries.key?(key.downcase)
+      end
+
+      # @param [String] key
+      # @return [Field, nil] Returns the Field for the deleted Field key.
+      def delete(key)
+        @entries.delete(key.downcase)
+      end
+
+      # @return [Enumerable<Field>]
+      def each(&block)
+        @entries.values.each(&block)
+      end
+
+      # @return [Integer] Returns the number of Field entries.
+      def size
+        @entries.size
+      end
+
+      # @return [Hash]
+      def clear
+        @entries = {}
+      end
+
+      # @api private
+      def inspect
+        super.gsub(/ @entries={.*},/, '')
+      end
+
+      # Proxy class that wraps Fields to create Headers and Trailers
+      class Proxy
+        include Enumerable
+
+        def initialize(fields, kind)
+          @fields = fields
+          @kind = kind
+        end
+
+        # @param [String] key
+        def [](key)
+          @fields[key].value(@fields.encoding) if key?(key)
+        end
+
+        # @param [String] key
+        # @param [#to_s, Array<#to_s>] value
+        def []=(key, value)
+          @fields[key] = Field.new(key, value, kind: @kind)
+        end
+
+        # @param [String] key
+        # @return [Boolean] Returns `true` if there is a Field with the given
+        #   key and kind.
+        def key?(key)
+          @fields.key?(key) && @fields[key].kind == @kind
+        end
+
+        # @param [String] key
+        # @return [Field, nil] Returns the value for the deleted Field key.
+        def delete(key)
+          @fields.delete(key).value(@fields.encoding) if key?(key)
+        end
+
+        # @return [Enumerable<String,String>]
+        def each(&block)
+          @fields.filter { |f| f.kind == @kind }
+                 .to_h { |f| [f.name, f.value(@fields.encoding)] }
+                 .each(&block)
+        end
+        alias each_pair each
+
+        # @api private
+        def inspect
+          to_h
+        end
+      end
+    end
+  end
+end

data/lib/hearth/http/middleware/content_length.rb

@@ -6,6 +6,8 @@ module Hearth
       # A middleware that sets Content-Length for any body that has a size.
       # @api private
       class ContentLength
+        include Hearth::Middleware::Logging
+
         def initialize(app, _ = {})
           @app = app
         end
@@ -15,10 +17,11 @@ module Hearth
         # @return [Output]
         def call(input, context)
           request = context.request
-          if request&.body.respond_to?(:size) &&
-             !request.headers.key?('Content-Length')
+          if !request.headers.key?('Content-Length') &&
+             request.body.respond_to?(:size)
             length = request.body.size
             request.headers['Content-Length'] = length
+            log_debug(context, "Set Content-Length to #{length}")
           end
 
           @app.call(input, context)

data/lib/hearth/http/middleware/content_md5.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Hearth
+  module HTTP
+    module Middleware
+      # A middleware that sets Content-MD5 for any body.
+      # @api private
+      class ContentMD5
+        include Hearth::Middleware::Logging
+
+        def initialize(app, _ = {})
+          @app = app
+        end
+
+        # @param input
+        # @param context
+        # @return [Output]
+        def call(input, context)
+          request = context.request
+          unless request.headers.key?('Content-MD5')
+            md5 = Hearth::Checksums.md5(request.body)
+            request.headers['Content-MD5'] = md5
+            log_debug(context, "Set Content-MD5 to #{md5}")
+          end
+
+          @app.call(input, context)
+        end
+      end
+    end
+  end
+end

data/lib/hearth/http/middleware/request_compression.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Hearth
+  module HTTP
+    module Middleware
+      # A middleware that compresses the request body and
+      # adds the Content-Encoding header
+      # @api private
+      class RequestCompression
+        include Hearth::Middleware::Logging
+
+        SUPPORTED_ENCODINGS = %w[gzip].freeze
+        CHUNK_SIZE = 1 * 1024 * 1024 # one MB
+
+        # @param [Class] app The next middleware in the stack.
+        # @param [Boolean] disable_request_compression If true, the request
+        #  body is not compressed.
+        # @param [Integer] request_min_compression_size_bytes The minimum size
+        #  of the request body to be compressed.
+        # @param [Array<String>] encodings The encodings to be used for
+        #  compression.
+        # @param [Boolean] streaming If true, the request body is compressed
+        #  in chunks.
+        def initialize(app, disable_request_compression:,
+                       request_min_compression_size_bytes:, encodings:,
+                       streaming:)
+          @app = app
+          @disable_request_compression = disable_request_compression
+          @request_min_compression_size_bytes =
+            request_min_compression_size_bytes
+          @encodings = encodings
+          @streaming = streaming
+        end
+
+        # @param input
+        # @param context
+        # @return [Output]
+        def call(input, context)
+          compress_request(context) unless @disable_request_compression
+          @app.call(input, context)
+        end
+
+        private
+
+        def compress_request(context)
+          selected_encoding = @encodings.find do |encoding|
+            SUPPORTED_ENCODINGS.include?(encoding)
+          end
+          return unless selected_encoding
+
+          log_debug(context, "Compressing request with: #{selected_encoding}")
+          request = context.request
+          if @streaming
+            compress_streaming_body(selected_encoding, request)
+            log_debug(context, 'Compressed request body in chunks')
+          elsif request.body.size >= @request_min_compression_size_bytes
+            compress_body(selected_encoding, request)
+            log_debug(context, 'Compressed request body')
+          end
+        end
+
+        def update_content_encoding(encoding, request)
+          headers = request.headers
+          if headers['Content-Encoding']
+            headers['Content-Encoding'] += ",#{encoding}"
+          else
+            headers['Content-Encoding'] = encoding
+          end
+        end
+
+        def compress_body(encoding, request)
+          case encoding
+          when 'gzip'
+            gzip_compress(request)
+          end
+          update_content_encoding(encoding, request)
+        end
+
+        def gzip_compress(request)
+          compressed = StringIO.new
+          compressed.binmode
+          gzip_writer = Zlib::GzipWriter.new(compressed)
+          if request.body.respond_to?(:read)
+            update_in_chunks(gzip_writer, request.body)
+          else
+            gzip_writer.write(request.body)
+          end
+          gzip_writer.close
+          new_body = StringIO.new(compressed.string)
+          request.body = new_body
+        end
+
+        def update_in_chunks(compressor, io)
+          loop do
+            chunk = io.read(CHUNK_SIZE)
+            break unless chunk
+
+            compressor.write(chunk)
+          end
+        end
+
+        def compress_streaming_body(encoding, request)
+          case encoding
+          when 'gzip'
+            request.body = GzipIO.new(request.body)
+          end
+          update_content_encoding(encoding, request)
+        end
+
+        # @api private
+        class GzipIO
+          def initialize(body)
+            @body = body
+            @buffer = ChunkBuffer.new
+            @gzip_writer = Zlib::GzipWriter.new(@buffer)
+          end
+
+          def read(length, buff = nil)
+            if @gzip_writer.closed?
+              # an empty string to signify an end as
+              # there will be nothing remaining to be read
+              StringIO.new('').read(length, buff)
+              return
+            end
+
+            chunk = @body.read(length)
+            if !chunk || chunk.empty?
+              # closing the writer will write one last chunk
+              # with a trailer (to be read from the @buffer)
+              @gzip_writer.close
+            else
+              # flush happens first to ensure that header fields
+              # are being sent over since write will override
+              @gzip_writer.flush
+              @gzip_writer.write(chunk)
+            end
+
+            StringIO.new(@buffer.last_chunk).read(length, buff)
+          end
+        end
+
+        # @api private
+        class ChunkBuffer
+          def initialize
+            @last_chunk = nil
+          end
+
+          attr_reader :last_chunk
+
+          def write(data)
+            @last_chunk = data
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hearth/http/middleware.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'middleware/content_length'
+require_relative 'middleware/content_md5'
+require_relative 'middleware/request_compression'
+
+module Hearth
+  module HTTP
+    # @api private
+    module Middleware; end
+  end
+end

data/lib/hearth/http/networking_error.rb

@@ -2,19 +2,6 @@
 
 module Hearth
   module HTTP
-    # Thrown by a Client when encountering a networking error while transmitting
-    # a request or receiving a response. You can access the original error
-    # by calling {#original_error}.
-    class NetworkingError < StandardError
-      MSG = 'Encountered an error while transmitting the request: %<message>s'
-
-      def initialize(original_error)
-        @original_error = original_error
-        super(format(MSG, message: original_error.message))
-      end
-
-      # @return [StandardError]
-      attr_reader :original_error
-    end
+    class NetworkingError < Hearth::NetworkingError; end
   end
 end

data/lib/hearth/http/request.rb

@@ -1,83 +1,77 @@
 # frozen_string_literal: true
 
-require 'stringio'
-require 'uri'
-
 module Hearth
   module HTTP
     # Represents an HTTP request.
-    # @api private
-    class Request
+    class Request < Hearth::Request
       # @param [String] http_method
-      # @param [String] url
-      # @param [Headers] headers
-      # @param [IO] body
-      def initialize(http_method: nil, url: nil, headers: Headers.new,
-                     body: StringIO.new)
+      # @param [Fields] fields
+      # @param (see Hearth::Request#initialize)
+      def initialize(http_method: nil, fields: Fields.new, **kwargs)
+        super(**kwargs)
         @http_method = http_method
-        @url = url
-        @headers = headers
-        @body = body
+        @fields = fields
+        @headers = Fields::Proxy.new(@fields, :header)
+        @trailers = Fields::Proxy.new(@fields, :trailer)
       end
 
       # @return [String]
       attr_accessor :http_method
 
-      # @return [String]
-      attr_accessor :url
+      # @return [Fields]
+      attr_reader :fields
 
-      # @return [Headers]
-      attr_accessor :headers
+      # @return [Fields::Proxy]
+      attr_reader :headers
 
-      # @return [IO]
-      attr_accessor :body
+      # @return [Fields::Proxy]
+      attr_reader :trailers
 
-      # Append a path to the HTTP request URL.
+      # Append a path to the HTTP request URI.
       #
-      #     http_req.url = "https://example.com"
+      #     http_req.uri = "https://example.com"
       #     http_req.append_path('/')
-      #     http_req.url
+      #     http_req.uri.to_s
       #     #=> "https://example.com/"
       #
       # Paths will be joined by a single '/':
       #
-      #     http_req.url = "https://example.com/path-prefix/"
+      #     http_req.uri = "https://example.com/path-prefix/"
       #     http_req.append_path('/path-suffix')
-      #     http_req.url
+      #     http_req.uri.to_s
       #     #=> "https://example.com/path-prefix/path-suffix"
       #
-      # Resultant URL preserves the querystring:
+      # Resultant URI preserves the querystring:
       #
-      #     http_req.url = "https://example.com/path-prefix?querystring
+      #     http_req.uri = "https://example.com/path-prefix?querystring
       #     http_req.append_path('/path-suffix')
-      #     http_req.url
+      #     http_req.uri.to_s
       #     #=> "https://example.com/path-prefix/path-suffix?querystring"
       #
       # The provided path should be URI escaped before being passed.
       #
-      #     http_req.url = "https://example.com
+      #     http_req.uri = "https://example.com
       #     http_req.append_path(
       #       Hearth::HTTP.uri_escape_path('/part 1/part 2')
       #     )
-      #     http_req.url
+      #     http_req.uri.to_s
       #     #=> "https://example.com/part%201/part%202"
       #
       # @param [String] path A URI escaped path.
+      #
       def append_path(path)
-        uri = URI.parse(@url)
         base_path = uri.path.sub(%r{/$}, '') # remove trailing slash
         path = path.sub(%r{^/}, '')          # remove prefix slash
         uri.path = "#{base_path}/#{path}"    # join on single slash
-        @url = uri.to_s
       end
 
-      # Append querystring parameter to the HTTP request URL.
+      # Append querystring parameter to the HTTP request URI.
       #
-      #     http_req.url = "https://example.com"
+      #     http_req.uri = "https://example.com"
       #     http_req.append_query_param('query')
       #     http_req.append_query_param('key 1', 'value 1')
       #
-      #     http_req.url
+      #     http_req.uri.to_s
       #     #=> "https://example.com?query&key%201=value%201
       #
       # @overload append_query_param(name)
@@ -93,39 +87,72 @@ module Hearth
       #     The value of the querystring parameter to add. This value
       #     will be URI escaped.
       #
-      def append_query_param(*args)
-        param =
-          case args.size
-          when 1 then escape(args[0])
-          when 2 then "#{escape(args[0])}=#{escape(args[1])}"
-          else raise ArgumentError, 'wrong number of arguments ' \
-                                    "(given #{args.size}, expected 1 or 2)"
-          end
-        uri = URI.parse(@url)
-        uri.query = uri.query ? "#{uri.query}&#{param}" : param
-        @url = uri.to_s
+      def append_query_param(name, value = nil)
+        param = Hearth::Query::Param.new(name, value)
+        uri.query = uri.query ? "#{uri.query}&#{param}" : param.to_s
       end
 
-      # Append a host prefix to the HTTP request URL.
+      # Append querystring parameter list to the HTTP request URI.
+      #
+      #     http_req.uri = "https://example.com"
+      #     query_params = Hearth::Query::ParamList.new
+      #     query_params['key 1'] = nil
+      #     query_params['key 2'] = 'value 2'
+      #     http_req.append_query_param_list(query_params)
       #
-      #     http_req.url = "https://example.com"
+      #     http_req.uri.to_s
+      #     #=> "https://example.com?key%201=&key%202=value%202"
+      #
+      # @param [ParamList] param_list
+      #   An instance of Hearth::Query::ParamList containing the list of
+      #   querystring parameters to add. The names and values are URI escaped.
+      #
+      def append_query_param_list(param_list)
+        return if param_list.empty?
+
+        uri.query = uri.query ? "#{uri.query}&#{param_list}" : param_list.to_s
+      end
+
+      # Remove querystring parameter from the HTTP request URI.
+      #
+      #    http_req.uri = "https://example.com"
+      #    http_req.append_query_param('query')
+      #    http_req.append_query_param('empty', '')
+      #    http_req.append_query_param('deleteme', 'true')
+      #    http_req.append_query_param('key', 'value')
+      #    #=> "https://example.com?query&empty=&deleteme=true&key=value"
+      #
+      #    http_req.remove_query_param('deleteme')
+      #    #=> "query&empty=&key=value"
+      #
+      #    http_req.uri.to_s
+      #    #=> "https://example.com?query&empty=&key=value"
+      #
+      # @param [String] name The name of the querystring parameter to remove.
+      #
+      def remove_query_param(name)
+        parsed = CGI.parse(uri.query)
+        parsed.delete(name)
+        # encode_www_form ignores query params without values
+        # (CGI parses these as empty lists)
+        parsed.each do |key, values|
+          parsed[key] = values.empty? ? nil : values
+        end
+        uri.query = URI.encode_www_form(parsed)
+      end
+
+      # Append a host prefix to the HTTP request URI.
+      #
+      #     http_req.uri = "https://example.com"
       #     http_req.prefix_host('data.')
       #
-      #     http_req.url
+      #     http_req.uri.to_s
       #     #=> "https://data.foo.com
       #
       # @param [String] prefix A dot (.) terminated prefix for the host.
       #
       def prefix_host(prefix)
-        uri = URI.parse(@url)
         uri.host = prefix + uri.host
-        @url = uri.to_s
-      end
-
-      private
-
-      def escape(value)
-        Hearth::HTTP.uri_escape(value.to_s)
       end
     end
   end