hearth 1.0.0.pre1 → 1.0.0.pre3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b43b47b8abef04f52e1f151032c376b90b3112e23c3084fbba6dd777e3f95180
-  data.tar.gz: a902f668849d1c28d0afd66ce2c3b80eac6a5626187e3c44a1d13d99234576e0
+  metadata.gz: 5a6aa5be0acf82ba6ba9b2d399c702fd0da402764dd4769cc3d72a632074dbb4
+  data.tar.gz: f7b14b1778860d004cb9fcea31c1fb0d230760c330447136414342f37cbd3a52
 SHA512:
-  metadata.gz: 4958477705f77ead625d1bbb49b2c11b0e44542af63bf9aaa95d87bba82a73cdbed65b40461f56e6bc9388cb612cf4cb4c341e7ba1a9b2502076ffa809e3cf14
-  data.tar.gz: 44f0d91c07b0f431b9660f459307daebbbbe8824ad90b4009cfdff63fa139c340201ed88667f80909bbd973bdc40216c74efd4601ce9fbbfb5d3c81e2f2bed2d
+  metadata.gz: dd6f92a2e98ab0942ddd68a6edb86cd4e274389c4d1595ec2ff360a6c6a7a9887a5534a58271009eef0697018bf8327b5c144cc47a541e102d57a0f3fe198be2
+  data.tar.gz: 7ae01e2405d9d7301ea2b9f6b8805fcd438de16d498b9e394f7e0ba5452a3acc6e681b5a32e7371b3cbe9fced1984ded25e4b16bb3512d1bf282f19079490614

data/CHANGELOG.md

@@ -1,12 +1,17 @@
 Unreleased Changes
 ------------------
 
-1.0.0.pre1 (2022-01-10)
+1.0.0.pre3 (2024-05-01)
 ------------------
 
-* Feature - Initial public pre-release for Smithy Ruby SDKs.
+* Feature - Third initial public pre-release for Smithy Ruby SDKs.
+
+1.0.0.pre2 (2023-12-19)
+------------------
 
-0.1.0 (2013-29-04)
+* Feature - Second initial public pre-release for Smithy Ruby SDKs.
+
+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.pre3

data/lib/hearth/anonymous_auth_resolver.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Hearth
+  # Always returns the Anonymous/noAuth auth scheme.
+  # Can be used to effectively disable/skip auth.
+  class AnonymousAuthResolver
+    def resolve(_params)
+      [Hearth::AuthOption.new(scheme_id: 'smithy.api#noAuth')]
+    end
+  end
+end

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 [IdentityProvider, nil]
+      def identity_provider(_identity_providers = {})
+        Hearth::IdentityProvider.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 [IdentityProvider, nil]
+      def identity_provider(identity_provider = {})
+        identity_provider[@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.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative 'client_stubs'
+
+module Hearth
+  # Base Client class for all generated SDK clients.
+  class Client
+    include ClientStubs
+
+    # Plugins applied to all instances of this client.
+    # @return [Hearth::PluginList]
+    def self.plugins
+      @plugins ||= PluginList.new
+    end
+
+    # @param [Hash] options
+    #   Options used to construct an instance of {Config}
+    # @param [Class] config_class
+    #   The configuration class to use.
+    def initialize(options, config_class)
+      @config = initialize_config(options, config_class)
+    end
+
+    # @return [Configuration]
+    attr_reader :config
+
+    private
+
+    def initialize_config(options, config_class)
+      client_interceptors = options.delete(:interceptors) || []
+      config = config_class.new(**options)
+      config.validate!
+      self.class.plugins.each { |p| p.call(config) }
+      config.plugins.each { |p| p.call(config) }
+      config.interceptors.concat(client_interceptors)
+      config.validate!
+      config.freeze
+    end
+
+    def operation_config(options)
+      return @config if options.empty?
+
+      if options.include?(:stub_responses) || options.include?(:stubs)
+        msg = 'Overriding stubs or stub_responses on ' \
+              'operations is not allowed'
+        raise ArgumentError, msg
+      end
+
+      operation_plugins = options.delete(:plugins)
+      operation_interceptors = options.delete(:interceptors) || []
+      config = @config.merge(options)
+      config.validate!
+      operation_plugins&.each { |p| p.call(config) }
+      config.interceptors.concat(operation_interceptors)
+      config.validate!
+      config.freeze
+    end
+
+    def output_stream(options = {}, &block)
+      return options.delete(:output_stream) if options[:output_stream]
+      return Hearth::BlockIO.new(block) if block
+
+      ::StringIO.new
+    end
+  end
+end

data/lib/hearth/client_stubs.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+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
+        @config.stubs.set_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,53 @@
+# 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