hearth 1.0.0.pre1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b43b47b8abef04f52e1f151032c376b90b3112e23c3084fbba6dd777e3f95180
+  data.tar.gz: a902f668849d1c28d0afd66ce2c3b80eac6a5626187e3c44a1d13d99234576e0
+SHA512:
+  metadata.gz: 4958477705f77ead625d1bbb49b2c11b0e44542af63bf9aaa95d87bba82a73cdbed65b40461f56e6bc9388cb612cf4cb4c341e7ba1a9b2502076ffa809e3cf14
+  data.tar.gz: 44f0d91c07b0f431b9660f459307daebbbbe8824ad90b4009cfdff63fa139c340201ed88667f80909bbd973bdc40216c74efd4601ce9fbbfb5d3c81e2f2bed2d

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+Unreleased Changes
+------------------
+
+1.0.0.pre1 (2022-01-10)
+------------------
+
+* Feature - Initial public pre-release for Smithy Ruby SDKs.
+
+0.1.0 (2013-29-04)
+------------------
+
+Not intended for public usage. Used as an internal detail of AWS SDK For Ruby v2 and v3.

data/VERSION

@@ -0,0 +1 @@
+1.0.0.pre1

data/lib/hearth/api_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Hearth
+  # Base class for errors returned from an API. This excludes networking
+  # errors and errors generated on the client-side.
+  class ApiError < StandardError
+    def initialize(error_code:, message: nil)
+      @error_code = error_code
+      super(message)
+    end
+
+    # @return [String]
+    attr_reader :error_code
+  end
+end

data/lib/hearth/block_io.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Hearth
+  # Given a block, BlockIO will call it with data to write and return the
+  # bytesize written. BlockIO keeps track of all bytes yielded.
+  class BlockIO
+    # @param [Proc] block
+    def initialize(block)
+      @block = block
+      @bytes_yielded = 0
+    end
+
+    # @return [Integer]
+    attr_reader :bytes_yielded
+
+    # @param [String] data
+    # @return [Integer] Returns the number of bytes written.
+    def write(data)
+      @block.call(data)
+      @bytes_yielded += data.bytesize
+      data.bytesize
+    end
+  end
+end

data/lib/hearth/context.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Hearth
+  # Stores request and response objects, and other useful things used by
+  # multiple Middleware.
+  class Context
+    def initialize(options = {})
+      @operation_name = options[:operation_name]
+      @request = options[:request]
+      @response = options[:response]
+      @logger = options[:logger]
+      @params = options[:params]
+      @metadata = options[:metadata] || {}
+    end
+
+    # @return [Symbol] Name of the API operation called.
+    attr_reader :operation_name
+
+    # @return [Hearth::HTTP::Request]
+    attr_reader :request
+
+    # @return [Hearth::HTTP::Response]
+    attr_reader :response
+
+    # @return [Logger] An instance of the logger configured for the Client.
+    attr_reader :logger
+
+    # @return [Hash] The hash of the original request parameters.
+    attr_reader :params
+
+    # @return [Hash]
+    attr_reader :metadata
+  end
+end

data/lib/hearth/http/api_error.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Hearth
+  module HTTP
+    # Base class for HTTP errors returned from an API. Inherits from
+    # {Hearth::ApiError}.
+    class ApiError < Hearth::ApiError
+      def initialize(http_resp:, **kwargs)
+        @http_status = http_resp.status
+        @http_headers = http_resp.headers
+        @http_body = http_resp.body
+        @request_id = http_resp.headers['x-request-id']
+        super(**kwargs)
+      end
+
+      # @return [Integer]
+      attr_reader :http_status
+
+      # @return [Hash<String, String>]
+      attr_reader :http_headers
+
+      # @return [String]
+      attr_reader :http_body
+
+      # @return [String]
+      attr_reader :request_id
+    end
+  end
+end

data/lib/hearth/http/client.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'logger'
+require 'openssl'
+
+module Hearth
+  module HTTP
+    # Transmits an HTTP {Request} object, returning an HTTP {Response}.
+    # @api private
+    class Client
+      # Initialize an instance of this HTTP client.
+      #
+      # @param [Hash] options The options for this HTTP Client
+      #
+      # @option options [Boolean] :http_wire_trace (false) When `true`,
+      #   HTTP debug output will be sent to the `:logger`.
+      #
+      # @option options [Logger] :logger A logger where debug output is sent.
+      #
+      # @option options [URI::HTTP,String] :http_proxy A proxy to send
+      #   requests through. Formatted like 'http://proxy.com:123'.
+      #
+      # @option options [Boolean] :ssl_verify_peer (true) When `true`,
+      #   SSL peer certificates are verified when establishing a
+      #   connection.
+      #
+      # @option options [String] :ssl_ca_bundle Full path to the SSL
+      #   certificate authority bundle file that should be used when
+      #   verifying peer certificates.  If you do not pass
+      #   `:ssl_ca_bundle` or `:ssl_ca_directory` the system default
+      #   will be used if available.
+      #
+      # @option options [String] :ssl_ca_directory Full path of the
+      #   directory that contains the unbundled SSL certificate
+      #   authority files for verifying peer certificates.  If you do
+      #   not pass `:ssl_ca_bundle` or `:ssl_ca_directory` the
+      #   system default will be used if available.
+      def initialize(options = {})
+        @http_wire_trace = options[:http_wire_trace]
+        @logger = options[:logger]
+        @http_proxy = options[:http_proxy]
+        @http_proxy = URI.parse(@http_proxy.to_s) if @http_proxy
+        @ssl_verify_peer = options[:ssl_verify_peer]
+        @ssl_ca_bundle = options[:ssl_ca_bundle]
+        @ssl_ca_directory = options[:ssl_ca_directory]
+        @ssl_ca_store = options[:ssl_ca_store]
+      end
+
+      # @param [Request] request
+      # @param [Response] response
+      # @return [Response]
+      def transmit(request:, response:)
+        uri = URI.parse(request.url)
+        http = create_http(uri)
+        http.set_debug_output(@logger) if @http_wire_trace
+
+        if uri.scheme == 'https'
+          configure_ssl(http)
+        else
+          http.use_ssl = false
+        end
+
+        _transmit(http, request, response)
+        response.body.rewind if response.body.respond_to?(:rewind)
+        response
+      rescue ArgumentError => e
+        # Invalid verb, ArgumentError is a StandardError
+        raise e
+      rescue StandardError => e
+        raise Hearth::HTTP::NetworkingError, e
+      end
+
+      private
+
+      def _transmit(http, request, response)
+        http.start do |conn|
+          conn.request(build_net_request(request)) do |net_resp|
+            response.status = net_resp.code.to_i
+            response.headers = extract_headers(net_resp)
+            net_resp.read_body do |chunk|
+              response.body.write(chunk)
+            end
+          end
+        end
+      end
+
+      # Creates an HTTP connection to the endpoint
+      # Applies proxy if set
+      def create_http(endpoint)
+        args = []
+        args << endpoint.host
+        args << endpoint.port
+        args += http_proxy_parts if @http_proxy
+        # Net::HTTP.new uses positional arguments: host, port, proxy_args....
+        Net::HTTP.new(*args.compact)
+      end
+
+      # applies ssl settings to the HTTP object
+      def configure_ssl(http)
+        http.use_ssl = true
+        if @ssl_verify_peer
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          http.ca_file = @ssl_ca_bundle if @ssl_ca_bundle
+          http.ca_path = @ssl_ca_directory if @ssl_ca_directory
+          http.cert_store = @ssl_ca_store if @ssl_ca_store
+        else
+          http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        end
+      end
+
+      # Constructs and returns a Net::HTTP::Request object from
+      # a {Http::Request}.
+      # @param [Http::Request] request
+      # @return [Net::HTTP::Request]
+      def build_net_request(request)
+        request_class = net_http_request_class(request)
+        req = request_class.new(request.url, request.headers.to_h)
+        req.body_stream = request.body
+        req
+      end
+
+      # @param [Net::HTTP::Response] response
+      # @return [Hash<String, String>]
+      def extract_headers(response)
+        response.to_hash.transform_values(&:first)
+      end
+
+      # @param [Http::Request] request
+      # @raise [InvalidHttpVerbError]
+      # @return Returns a base `Net::HTTP::Request` class, e.g.,
+      #   `Net::HTTP::Get`, `Net::HTTP::Post`, etc.
+      def net_http_request_class(request)
+        Net::HTTP.const_get(request.http_method.capitalize)
+      rescue NameError
+        msg = "`#{request.http_method}` is not a valid http verb"
+        raise ArgumentError, msg
+      end
+
+      # Extract the parts of the http_proxy URI
+      # @return [Array(String)]
+      def http_proxy_parts
+        [
+          @http_proxy.host,
+          @http_proxy.port,
+          (@http_proxy.user && CGI.unescape(@http_proxy.user)),
+          (@http_proxy.password && CGI.unescape(@http_proxy.password))
+        ]
+      end
+    end
+  end
+end

data/lib/hearth/http/error_parser.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Hearth
+  module HTTP
+    # Uses HTTP specific logic + Protocol defined Errors and
+    # Error Code function to determine if a response should
+    # be parsed as an Error. Contains generic Error parsing
+    # logic as well.
+    # @api private
+    class ErrorParser
+      # @api private
+      HTTP_3XX = (300..399).freeze
+
+      # @api private
+      HTTP_4XX = (400..499).freeze
+
+      # @api private
+      HTTP_5XX = (500..599).freeze
+
+      # @param [Module] error_module The code generated Errors module.
+      #   Must contain service specific implementations of
+      #   ApiRedirectError, ApiClientError, and ApiServerError
+      #
+      # @param [Integer] success_status The status code of a
+      #   successful response as defined by the model for
+      #   this operation. If this is a non 2XX value,
+      #   the request will be considered successful if
+      #   it has the success_status and does not
+      #   have an error code.
+      #
+      # @param [Array<Class<ApiError>>] errors Array of Error classes
+      #   modeled for the operation.
+      #
+      # @param [callable] error_code_fn Protocol specific function
+      #   that will return the error code from a response, or nil if
+      #   there is none.
+      def initialize(error_module:, success_status:, errors:, error_code_fn:)
+        @error_module = error_module
+        @success_status = success_status
+        @errors = errors
+        @error_code_fn = error_code_fn
+      end
+
+      # Parse and return the error if the response is not successful.
+      #
+      # @param [Response] response The HTTP response
+      def parse(response)
+        extract_error(response) if error?(response)
+      end
+
+      private
+
+      # Implements the following order of precedence
+      # 1. Response has error_code -> error
+      # 2. Response code == http trait status code? -> success
+      # 3. Response code matches any error status codes? -> error
+      #   [EXCLUDED, covered by error_code]
+      # 4. Response code is 2xx? -> success
+      # 6. Response code 5xx -> unknown server error
+      #   [MODIFIED, 3xx, 4xx, 5xx mapped, everything else is Generic ApiError]
+      # 7. Everything else -> unknown client error
+      def error?(http_resp)
+        return true if @error_code_fn.call(http_resp)
+        return false if http_resp.status == @success_status
+
+        !(200..299).cover?(http_resp.status)
+      end
+
+      def extract_error(http_resp)
+        error_code = @error_code_fn.call(http_resp)
+        error_class = error_class(error_code) if error_code
+
+        error_opts = {
+          http_resp: http_resp,
+          error_code: error_code,
+          message: error_code # default message
+        }
+
+        if error_class
+          error_class.new(**error_opts)
+        else
+          generic_error(error_opts)
+        end
+      end
+
+      def error_class(error_code)
+        @errors.find do |e|
+          e.name.include? error_code
+        end
+      end
+
+      def generic_error(error_opts)
+        http_resp = error_opts[:http_resp]
+        case http_resp.status
+        when HTTP_3XX then @error_module::ApiRedirectError.new(
+          location: http_resp.headers['location'], **error_opts
+        )
+        when HTTP_4XX then @error_module::ApiClientError.new(**error_opts)
+        when HTTP_5XX then @error_module::ApiServerError.new(**error_opts)
+        else @error_module::ApiError.new(**error_opts)
+        end
+      end
+    end
+  end
+end

data/lib/hearth/http/headers.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Hearth
+  module HTTP
+    # Provides Hash like access for Headers with key normalization
+    # @api private
+    class Headers
+      # @param [Hash<String,String>] headers
+      def initialize(headers: {})
+        @headers = {}
+        headers.each_pair do |key, value|
+          self[key] = value
+        end
+      end
+
+      # @param [String] key
+      def [](key)
+        @headers[normalize(key)]
+      end
+
+      # @param [String] key
+      # @param [String] value
+      def []=(key, value)
+        @headers[normalize(key)] = value.to_s
+      end
+
+      # @param [String] key
+      # @return [Boolean] Returns `true` if there is a header with
+      #   the given key.
+      def key?(key)
+        @headers.key?(normalize(key))
+      end
+
+      # @return [Array<String>]
+      def keys
+        @headers.keys
+      end
+
+      # @param [String] key
+      # @return [String, nil] Returns the value for the deleted key.
+      def delete(key)
+        @headers.delete(normalize(key))
+      end
+
+      # @return [Enumerable<String,String>]
+      def each_pair(&block)
+        @headers.each(&block)
+      end
+      alias each each_pair
+
+      # @return [Hash]
+      def to_hash
+        @headers.dup
+      end
+      alias to_h to_hash
+
+      # @return [Integer] Returns the number of entries in the headers
+      #   hash.
+      def size
+        @headers.size
+      end
+
+      private
+
+      def normalize(key)
+        key.to_s.gsub(/[^-]+/, &:capitalize)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Hearth
+  module HTTP
+    module Middleware
+      # A middleware that sets Content-Length for any body that has a size.
+      # @api private
+      class ContentLength
+        def initialize(app, _ = {})
+          @app = app
+        end
+
+        # @param input
+        # @param context
+        # @return [Output]
+        def call(input, context)
+          request = context.request
+          if request&.body.respond_to?(:size) &&
+             !request.headers.key?('Content-Length')
+            length = request.body.size
+            request.headers['Content-Length'] = length
+          end
+
+          @app.call(input, context)
+        end
+      end
+    end
+  end
+end

data/lib/hearth/http/networking_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+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
+  end
+end

data/lib/hearth/http/request.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'stringio'
+require 'uri'
+
+module Hearth
+  module HTTP
+    # Represents an HTTP request.
+    # @api private
+    class 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)
+        @http_method = http_method
+        @url = url
+        @headers = headers
+        @body = body
+      end
+
+      # @return [String]
+      attr_accessor :http_method
+
+      # @return [String]
+      attr_accessor :url
+
+      # @return [Headers]
+      attr_accessor :headers
+
+      # @return [IO]
+      attr_accessor :body
+
+      # Append a path to the HTTP request URL.
+      #
+      #     http_req.url = "https://example.com"
+      #     http_req.append_path('/')
+      #     http_req.url
+      #     #=> "https://example.com/"
+      #
+      # Paths will be joined by a single '/':
+      #
+      #     http_req.url = "https://example.com/path-prefix/"
+      #     http_req.append_path('/path-suffix')
+      #     http_req.url
+      #     #=> "https://example.com/path-prefix/path-suffix"
+      #
+      # Resultant URL preserves the querystring:
+      #
+      #     http_req.url = "https://example.com/path-prefix?querystring
+      #     http_req.append_path('/path-suffix')
+      #     http_req.url
+      #     #=> "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.append_path(
+      #       Hearth::HTTP.uri_escape_path('/part 1/part 2')
+      #     )
+      #     http_req.url
+      #     #=> "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.
+      #
+      #     http_req.url = "https://example.com"
+      #     http_req.append_query_param('query')
+      #     http_req.append_query_param('key 1', 'value 1')
+      #
+      #     http_req.url
+      #     #=> "https://example.com?query&key%201=value%201
+      #
+      # @overload append_query_param(name)
+      #   @param [String] name
+      #     The name of the querystring parameter to add. This name
+      #     will be URI escaped.
+      #
+      # @overload append_query_param(name, value)
+      #   @param [String] name
+      #     The name of the querystring parameter to add. This name
+      #     will be URI escaped.
+      #   @param [String] value
+      #     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
+      end
+
+      # Append a host prefix to the HTTP request URL.
+      #
+      #     http_req.url = "https://example.com"
+      #     http_req.prefix_host('data.')
+      #
+      #     http_req.url
+      #     #=> "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
+end

data/lib/hearth/http/response.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Hearth
+  module HTTP
+    # Represents an HTTP Response.
+    # @api private
+    class Response
+      # @param [Integer] status
+      # @param [Headers] headers
+      # @param [IO] body
+      def initialize(status: 200, headers: Headers.new, body: StringIO.new)
+        @status = status
+        @headers = headers
+        @body = body
+      end
+
+      # @return [Integer]
+      attr_accessor :status
+
+      # @return [Headers]
+      attr_accessor :headers
+
+      # @return [IO]
+      attr_accessor :body
+    end
+  end
+end