hearth 1.0.0.pre1 → 1.0.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b43b47b8abef04f52e1f151032c376b90b3112e23c3084fbba6dd777e3f95180
-  data.tar.gz: a902f668849d1c28d0afd66ce2c3b80eac6a5626187e3c44a1d13d99234576e0
+  metadata.gz: bace852980aa4785929fce82aeb1a0b683fd6cf1f77d83d1dee39315d8177361
+  data.tar.gz: bff4b301d6940ccb485973b728b761e0d773489068cb093bf1789fcfe8cd1c35
 SHA512:
-  metadata.gz: 4958477705f77ead625d1bbb49b2c11b0e44542af63bf9aaa95d87bba82a73cdbed65b40461f56e6bc9388cb612cf4cb4c341e7ba1a9b2502076ffa809e3cf14
-  data.tar.gz: 44f0d91c07b0f431b9660f459307daebbbbe8824ad90b4009cfdff63fa139c340201ed88667f80909bbd973bdc40216c74efd4601ce9fbbfb5d3c81e2f2bed2d
+  metadata.gz: 27e9e5a1c32430314c3df34e843efef873231e5691d4d7df262615e4a9b65fb1f29dbdf8c0b4037e2a86d13d7597e2ff29b45d8eea8db87b2ed1559740b4c53c
+  data.tar.gz: ae6db7148e7cc6b98d8a2d0cc0bab09327ff10774c78e5b3fd76ef8a219ac07ebff636fd7636c7c17ed53f3fcbf964ce111a8e3d11d090120d59f95d2eafb227

data/CHANGELOG.md

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

data/VERSION

@@ -1 +1 @@
-1.0.0.pre1
+1.0.0.pre2

data/lib/hearth/api_error.rb

@@ -4,12 +4,26 @@ 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)
+    def initialize(error_code:, metadata: {}, message: nil)
       @error_code = error_code
+      @metadata = metadata
       super(message)
     end
 
     # @return [String]
     attr_reader :error_code
+
+    # @return [Hash]
+    attr_reader :metadata
+
+    # @return [Boolean]
+    def retryable?
+      false
+    end
+
+    # @return [Boolean]
+    def throttling?
+      false
+    end
   end
 end

data/lib/hearth/auth_option.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Hearth
+  # Object that represents an auth option, returned by Auth Resolvers.
+  class AuthOption
+    def initialize(scheme_id:, identity_properties: {}, signer_properties: {})
+      @scheme_id = scheme_id
+      @identity_properties = identity_properties
+      @signer_properties = signer_properties
+    end
+
+    # @return [String]
+    attr_reader :scheme_id
+
+    # @return [Hash]
+    attr_reader :identity_properties
+
+    # @return [Hash]
+    attr_reader :signer_properties
+  end
+end

data/lib/hearth/auth_schemes/anonymous.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Hearth
+  module AuthSchemes
+    # Anonymous authentication scheme.
+    class Anonymous < AuthSchemes::Base
+      def initialize
+        super(
+          scheme_id: 'smithy.api#noAuth',
+          signer: Signers::Anonymous.new,
+          identity_type: Identities::Anonymous
+        )
+      end
+
+      # @return [IdentityResolver, nil]
+      def identity_resolver(_identity_resolvers = {})
+        Hearth::IdentityResolver.new(proc { Identities::Anonymous.new })
+      end
+    end
+  end
+end

data/lib/hearth/auth_schemes/http_api_key.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Hearth
+  module AuthSchemes
+    # HTTP API Key authentication scheme.
+    class HTTPApiKey < AuthSchemes::Base
+      def initialize
+        super(
+          scheme_id: 'smithy.api#httpApiKeyAuth',
+          signer: Signers::HTTPApiKey.new,
+          identity_type: Identities::HTTPApiKey
+        )
+      end
+    end
+  end
+end

data/lib/hearth/auth_schemes/http_basic.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Hearth
+  module AuthSchemes
+    # HTTP Basic authentication scheme.
+    class HTTPBasic < AuthSchemes::Base
+      def initialize
+        super(
+          scheme_id: 'smithy.api#httpBasicAuth',
+          signer: Signers::HTTPBasic.new,
+          identity_type: Identities::HTTPLogin
+        )
+      end
+    end
+  end
+end

data/lib/hearth/auth_schemes/http_bearer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Hearth
+  module AuthSchemes
+    # HTTP Bearer authentication scheme.
+    class HTTPBearer < AuthSchemes::Base
+      def initialize
+        super(
+          scheme_id: 'smithy.api#httpBearerAuth',
+          signer: Signers::HTTPBearer.new,
+          identity_type: Identities::HTTPBearer
+        )
+      end
+    end
+  end
+end

data/lib/hearth/auth_schemes/http_digest.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Hearth
+  module AuthSchemes
+    # HTTP Digest authentication scheme.
+    class HTTPDigest < AuthSchemes::Base
+      def initialize
+        super(
+          scheme_id: 'smithy.api#httpDigestAuth',
+          signer: Signers::HTTPDigest.new,
+          identity_type: Identities::HTTPLogin
+        )
+      end
+    end
+  end
+end

data/lib/hearth/auth_schemes.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Hearth
+  # Namespace for all AuthScheme classes.
+  module AuthSchemes
+    # Base class for all AuthScheme classes.
+    class Base
+      def initialize(scheme_id:, signer:, identity_type:)
+        @scheme_id = scheme_id
+        @signer = signer
+        @identity_type = identity_type
+      end
+
+      # @return [String]
+      attr_reader :scheme_id
+
+      # @return [IdentityResolver, nil]
+      def identity_resolver(identity_resolvers = {})
+        identity_resolvers[@identity_type]
+      end
+
+      # @return [Signers::Base]
+      attr_reader :signer
+    end
+  end
+end
+
+require_relative 'auth_schemes/anonymous'
+require_relative 'auth_schemes/http_api_key'
+require_relative 'auth_schemes/http_basic'
+require_relative 'auth_schemes/http_bearer'
+require_relative 'auth_schemes/http_digest'

data/lib/hearth/checksums.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+
+module Hearth
+  # A utility module for calculating checksums.
+  # @api private
+  module Checksums
+    CHUNK_SIZE = 1 * 1024 * 1024 # one MB
+
+    # @param [File, Tempfile, StringIO#read, String] value
+    # @return [String<MD5>]
+    def self.md5(value)
+      if value.is_a?(File) || value.is_a?(Tempfile)
+        OpenSSL::Digest.new('MD5').file(value).base64digest
+      elsif value.respond_to?(:read)
+        md5 = OpenSSL::Digest.new('MD5')
+        loop do
+          chunk = value.read(CHUNK_SIZE)
+          break unless chunk
+
+          md5.update(chunk)
+        end
+        value.rewind
+        md5.base64digest
+      else
+        OpenSSL::Digest.new('MD5').base64digest(value)
+      end
+    end
+  end
+end

data/lib/hearth/client_stubs.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative 'stubs'
+
+module Hearth
+  # This module provides the ability to specify the data and/or errors to
+  # return when a client is using stubbed responses.
+  # This module should be included in generated service clients.
+  #
+  # Pass `stub_responses: true` to a Client's Config constructor
+  # to enable this behavior.
+  module ClientStubs
+    # Configures what data / errors should be returned from the named operation
+    # when response stubbing is enabled.
+    #
+    # ## Basic usage
+    #
+    # When you enable response stubbing, the client will generate fake
+    # responses and will not make any HTTP requests. The SDK will default
+    # to generate fake responses with placeholder values. You can override
+    # the data returned using {#stub_responses}. You can also specify errors
+    # (with error data) that it should raise.
+    #
+    #     client = Service::Client.new(stub_responses: true)
+    #     client.operation
+    #     #=> #<struct Service:Types::Operation param1=[], param2=nil>
+    #
+    # You can specify the modeled stub data using the :data key.
+    #
+    #     client = Service::Client.new(stub_responses: true)
+    #     client.stub_responses(
+    #       :operation,
+    #       data: { param1: [{ name: 'value1' }] }
+    #     )
+    #     client.operation.param1.map(&:name)
+    #     #=> ['value1']
+    #
+    # Stub data can also be provided as an output Type.
+    #
+    #     client = Service::Client.new(stub_responses: true)
+    #     output = Service::Types::OperationOutput.new(
+    #       param1: [{ name: 'value1' }]
+    #     )
+    #     client.stub_responses(:operation, output)
+    #     client.operation(param1: 'value')
+    #     #=> #<struct Service:Types::OperationOutput ..>
+    #
+    # You can also specify modeled errors or exceptions it should raise using
+    # the :error key. The error hash must have a :class and optionally any
+    # :data to populate the error with.
+    #
+    #     client = Service::Client.new(stub_responses: true)
+    #     client.stub_responses(
+    #       :operation,
+    #       error: { class: ModeledError, data: { message: 'error message' } }
+    #     )
+    #     #=> raises ModeledError.new('error message')
+    #
+    # Constructed Exceptions will also be raised if provided.
+    #
+    #     client.stub_responses(:operation, Hearth::NetworkingError.new)
+    #     client.operation(param1: 'value')
+    #     #=> raises Hearth::NetworkingError
+    #
+    # ## Dynamic Stubbing
+    #
+    # In addition to creating static stubs, it's also possible to generate
+    # stubs dynamically based on the input with which operations were
+    # called, by passing a `Proc` object:
+    #
+    #     client.stub_responses(:operation, -> (input) {
+    #       if input[:param] == 'foo'
+    #         # return a data stub
+    #         { data: { param1: [{ name: 'value1'}]} }
+    #       else
+    #         # return an error stub
+    #         { error: Service::Errors::NotFound }
+    #       end
+    #     })
+    #
+    # ## Stubbing Raw Protocol Responses
+    #
+    # As an alternative to providing the response data, you can provide an
+    # instance of Hearth::Response to stub with.
+    #
+    #     response = Hearth::HTTP::Response.new(
+    #       status: 200,
+    #       body: StringIO.new('{param1: "value1"}'),
+    #     )
+    #     client.stub_responses(:operation, response)
+    #     #=> #<struct Service:Types::OperationOutput param1="value1">
+    #
+    # ## Stubbing Multiple Responses
+    #
+    # Calling an operation multiple times will return similar responses.
+    # You can configure multiple stubs and they will be returned in sequence.
+    #
+    #     client.stub_responses(
+    #       :operation,
+    #       { error: Service::Errors::NotFound },
+    #       { data: { content_length: 150 } },
+    #     ])
+    #
+    #     client.operation(param1: 'value1')
+    #     #=> raises Service::Errors::NotFound
+    #
+    #     resp = client.operation(param1: 'value2')
+    #     resp.data.content_length #=> 150
+    #
+    # @param [Symbol] operation_name
+    #
+    # @param [Mixed] stubs One or more responses to return from the named
+    #   operation.
+    #
+    # @return [void]
+    #
+    # @raise [RuntimeError] Raises a runtime error when called
+    #   on a client that has not enabled response stubbing via
+    #   `:stub_responses => true`.
+    def stub_responses(operation_name, *stubs)
+      if @config.stub_responses
+        @stubs.add_stubs(operation_name, stubs.flatten)
+      else
+        msg = 'Stubbing is not enabled. Enable stubbing in Config ' \
+              'with `stub_responses: true`'
+        raise ArgumentError, msg
+      end
+    end
+  end
+end

data/lib/hearth/config/env_provider.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Hearth
+  # @api private
+  module Config
+    # Parses and validates values provided in ENV
+    class EnvProvider
+      def initialize(env_key, type: 'String')
+        @env_key = env_key
+        @type = type
+      end
+
+      def call(_cfg)
+        return unless (value = ENV.fetch(@env_key, nil))
+
+        case @type
+        when 'Float' then parse_float(value)
+        when 'Integer' then parse_integer(value)
+        when 'Boolean' then parse_boolean(value)
+        else
+          value
+        end
+      end
+
+      private
+
+      def parse_float(value)
+        Float(value)
+      rescue ArgumentError
+        raise_error(value)
+      end
+
+      def parse_integer(value)
+        Integer(value)
+      rescue ArgumentError
+        raise_error(value)
+      end
+
+      def parse_boolean(value)
+        case value.downcase
+        when 'true' then true
+        when 'false' then false
+        else raise_error(value)
+        end
+      end
+
+      def raise_error(value)
+        raise ArgumentError,
+              "Expected ENV['#{@env_key}'] to be a #{@type}, got #{value}."
+      end
+    end
+  end
+end

data/lib/hearth/config/resolver.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Hearth
+  # @api private
+  module Config
+    # Resolves configuration options.
+    class Resolver
+      private_class_method :new
+
+      # @param config [Struct]
+      # @param options [Hash]
+      # @param defaults [Hash<Array<Proc>>]
+      # @return [Struct]
+      def self.resolve(config, options, defaults = {})
+        new(config).send(:resolve, options, defaults)
+      end
+
+      def key(key)
+        @options[key] = resolve_default(key) unless @options.key?(key)
+        @options[key]
+      end
+      alias [] key
+
+      private
+
+      # @param config [Struct]
+      def initialize(config)
+        @config = config
+      end
+
+      def resolve(options, defaults)
+        @options = options
+        @defaults = defaults
+        @config.members.each do |key|
+          @config[key] = key(key)
+        end
+      end
+
+      def resolve_default(key)
+        @defaults[key]&.each do |default|
+          value = if default.respond_to?(:call)
+                    default.call(self)
+                  else
+                    default
+                  end
+          return value unless value.nil?
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/hearth/configuration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Hearth
+  # A module mixed into Config structs that resolves default value providers.
+  module Configuration
+    def initialize(**options)
+      Hearth::Config::Resolver.resolve(self, options, defaults)
+      super
+    end
+
+    def merge(configuration)
+      self.class.new(**to_h.merge(configuration.to_h))
+    end
+  end
+end

data/lib/hearth/connection_pool.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Hearth
+  # @api private
+  class ConnectionPool
+    @pools_mutex = Mutex.new
+    @pools = {}
+
+    class << self
+      # @return [ConnectionPool]
+      def for(config = {})
+        @pools_mutex.synchronize do
+          @pools[config] ||= new
+        end
+      end
+
+      # @return [Array<ConnectionPool>] Returns a list of the
+      #   constructed connection pools.
+      def pools
+        @pools_mutex.synchronize do
+          @pools.values
+        end
+      end
+    end
+
+    # @api private
+    def initialize
+      @pool_mutex = Mutex.new
+      @pool = {}
+    end
+
+    # @param [URI::HTTP, URI::HTTPS] endpoint The HTTP(S) endpoint
+    #   to connect to (e.g. 'https://domain.com').
+    # @param [Proc] block A block that returns a new connection if
+    #   there are no connections present.
+    # @return [Connection, nil]
+    def connection_for(endpoint, &block)
+      connection = nil
+      endpoint = remove_path_and_query(endpoint)
+      # attempt to recycle an already open connection
+      @pool_mutex.synchronize do
+        clean
+        connection = @pool[endpoint].shift if @pool.key?(endpoint)
+      end
+      connection || (block.call if block_given?)
+    end
+
+    # @param [URI::HTTP, URI::HTTPS] endpoint The HTTP(S) endpoint
+    # @param [Object] connection The connection to check back into the pool.
+    # @return [nil]
+    def offer(endpoint, connection)
+      endpoint = remove_path_and_query(endpoint)
+      @pool_mutex.synchronize do
+        @pool[endpoint] = [] unless @pool.key?(endpoint)
+        @pool[endpoint] << connection
+      end
+    end
+
+    private
+
+    # Removes stale connections from the pool.  This method *must* be called
+    # @note **Must** be called behind a `@pool_mutex` synchronize block.
+    def clean
+      @pool.each_pair do |_endpoint, connections|
+        connections.delete_if(&:stale?)
+      end
+    end
+
+    # Connection pools should be keyed by endpoint and port.
+    def remove_path_and_query(endpoint)
+      endpoint.dup.tap do |e|
+        e.path = ''
+        e.query = nil
+      end.to_s
+    end
+  end
+end

data/lib/hearth/context.rb

@@ -1,19 +1,26 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
 module Hearth
   # Stores request and response objects, and other useful things used by
   # multiple Middleware.
+  # @api private
   class Context
     def initialize(options = {})
+      @invocation_id = SecureRandom.uuid
       @operation_name = options[:operation_name]
       @request = options[:request]
       @response = options[:response]
       @logger = options[:logger]
-      @params = options[:params]
+      @interceptors = options[:interceptors] || InterceptorList.new
       @metadata = options[:metadata] || {}
     end
 
-    # @return [Symbol] Name of the API operation called.
+    # @return [String] The invocation ID for the request.
+    attr_reader :invocation_id
+
+    # @return [Symbol] The name of the API operation called.
     attr_reader :operation_name
 
     # @return [Hearth::HTTP::Request]
@@ -25,10 +32,27 @@ module Hearth
     # @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 [Array] An ordered list of interceptors
+    attr_reader :interceptors
+
+    # @return [ResolvedAuth, nil] The resolved auth for the request.
+    attr_accessor :auth
 
     # @return [Hash]
     attr_reader :metadata
+
+    # Returns the metadata for the given `key`.
+    # @param [Symbol] key
+    # @return [Object]
+    def [](key)
+      @metadata[key]
+    end
+
+    # Sets metadata for the given `key`.
+    # @param [Symbol] key
+    # @param [Object] value
+    def []=(key, value)
+      @metadata[key] = value
+    end
   end
 end

data/lib/hearth/dns/host_address.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Hearth
+  module DNS
+    # Address results from a DNS lookup in {HostResolver}.
+    class HostAddress
+      def initialize(address_type:, address:, hostname:)
+        @address_type = address_type
+        @address = address
+        @hostname = hostname
+      end
+
+      # @return [Symbol]
+      attr_reader :address_type
+
+      # @return [String]
+      attr_reader :address
+
+      # @return [String]
+      attr_reader :hostname
+    end
+  end
+end