hearth 1.0.0.pre1 → 1.0.0.pre2

data/lib/hearth/middleware/auth.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Middleware
+    # A middleware that resolves identities for signing requests.
+    # @api private
+    class Auth
+      include Middleware::Logging
+
+      # @param [Class] app The next middleware in the stack.
+      # @param [#resolve(auth_params)] auth_resolver A class that responds to a
+      #  `resolve(auth_params)` method where `auth_params` is a struct with an
+      #  operation_name. For a given operation_name, the method must return an
+      #  ordered list of {Hearth::AuthOption} objects to be considered for
+      #  authentication.
+      # @param [Struct] auth_params A struct with an operation_name and other
+      #  parameters that may be used to resolve auth options.
+      # @param [Array<Hearth::AuthScheme::Base>] auth_schemes A list of
+      #  auth schemes to consider for authentication.
+      def initialize(app, auth_resolver:, auth_params:, auth_schemes:, **kwargs)
+        @app = app
+        @auth_resolver = auth_resolver
+        @auth_params = auth_params
+        @auth_schemes = auth_schemes.to_h { |s| [s.scheme_id, s] }
+
+        @identity_resolvers = {}
+        kwargs.each do |key, value|
+          next unless key.superclass == Hearth::Identities::Base
+
+          @identity_resolvers[key] = value
+        end
+      end
+
+      # @param input
+      # @param context
+      # @return [Output]
+      def call(input, context)
+        log_debug(context, 'Resolving auth')
+        auth_options = @auth_resolver.resolve(@auth_params)
+        log_debug(context, "Resolved auth options: #{auth_options}")
+        context.auth = resolve_auth(auth_options)
+        log_debug(context, "Resolved auth: #{context.auth}")
+        @app.call(input, context)
+      end
+
+      private
+
+      ResolvedAuth = Struct.new(
+        :signer,
+        :signer_properties,
+        :identity,
+        :identity_properties,
+        keyword_init: true
+      )
+
+      def resolve_auth(auth_options)
+        failures = []
+
+        auth_options.each do |auth_option|
+          auth_scheme = @auth_schemes[auth_option.scheme_id]
+          resolved_auth = try_load_auth_scheme(
+            auth_option,
+            auth_scheme,
+            failures
+          )
+
+          return resolved_auth if resolved_auth
+        end
+
+        raise failures.join("\n")
+      end
+
+      def try_load_auth_scheme(auth_option, auth_scheme, failures)
+        scheme_id = auth_option.scheme_id
+        unless auth_scheme
+          failures << "Auth scheme #{scheme_id} was not enabled " \
+                      'for this request'
+          return
+        end
+
+        identity_resolver = auth_scheme.identity_resolver(@identity_resolvers)
+        unless identity_resolver
+          failures << "Auth scheme #{scheme_id} did not have an " \
+                      'identity resolver configured'
+          return
+        end
+
+        identity_properties = auth_option.identity_properties
+        identity = identity_resolver.identity(identity_properties)
+
+        ResolvedAuth.new(
+          identity: identity,
+          identity_properties: auth_option.identity_properties,
+          signer: auth_scheme.signer,
+          signer_properties: auth_option.signer_properties
+        )
+      end
+    end
+  end
+end

data/lib/hearth/middleware/build.rb

@@ -5,6 +5,8 @@ module Hearth
     # A middleware that builds a request object.
     # @api private
     class Build
+      include Middleware::Logging
+
       # @param [Class] app The next middleware in the stack.
       # @param [Class] builder A builder object responsible for building the
       #  request. It must respond to #build and take the request and input as
@@ -18,7 +20,37 @@ module Hearth
       # @param context
       # @return [Output]
       def call(input, context)
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::MODIFY_BEFORE_SERIALIZATION,
+          input: input,
+          context: context,
+          output: nil,
+          aggregate_errors: false
+        )
+        return Hearth::Output.new(error: interceptor_error) if interceptor_error
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::READ_BEFORE_SERIALIZATION,
+          input: input,
+          context: context,
+          output: nil,
+          aggregate_errors: false
+        )
+        return Hearth::Output.new(error: interceptor_error) if interceptor_error
+
+        log_debug(context, "Building request with: #{input}")
         @builder.build(context.request, input: input)
+        log_debug(context, "Built request: #{context.request.inspect}")
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::READ_AFTER_SERIALIZATION,
+          input: input,
+          context: context,
+          output: nil,
+          aggregate_errors: false
+        )
+        return Hearth::Output.new(error: interceptor_error) if interceptor_error
+
         @app.call(input, context)
       end
     end

data/lib/hearth/middleware/host_prefix.rb

@@ -5,6 +5,8 @@ module Hearth
     # A middleware that prefixes the host.
     # @api private
     class HostPrefix
+      include Middleware::Logging
+
       # @param [Class] app The next middleware in the stack.
       # @param [Boolean] disable_host_prefix If true, this option will not
       #  modify the host url.
@@ -21,25 +23,27 @@ module Hearth
       # @param context
       # @return [Output]
       def call(input, context)
-        unless @disable_host_prefix
-          prefix = apply_labels(@host_prefix, input)
-          context.request.prefix_host(prefix)
-        end
+        prefix_host(input, context) unless @disable_host_prefix
         @app.call(input, context)
       end
 
       private
 
+      def prefix_host(input, context)
+        log_debug(context, "Prefixing host with #{@host_prefix}")
+        prefix = apply_labels(@host_prefix, input)
+        context.request.prefix_host(prefix)
+        log_debug(context, "Prefixed host: #{context.request.uri.host}")
+      end
+
       def apply_labels(host_prefix, input)
         host_prefix.gsub(/\{.+?\}/) do |host_label|
           key = host_label.delete('{}')
           value = input[key.to_sym]
-
           if value.nil? || value.empty?
             raise ArgumentError,
                   "Host label #{key} cannot be nil or empty."
           end
-
           value
         end
       end

data/lib/hearth/middleware/initialize.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Middleware
+    # A middleware used to initialize the request, called first in the stack
+    # @api private
+    class Initialize
+      include Middleware::Logging
+
+      # @param [Class] app The next middleware in the stack.
+      def initialize(app)
+        @app = app
+      end
+
+      # @param input
+      # @param context
+      # @return [Output]
+      def call(input, context)
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::READ_BEFORE_EXECUTION,
+          input: input,
+          context: context,
+          output: nil,
+          aggregate_errors: true
+        )
+
+        output =
+          if interceptor_error
+            Hearth::Output.new(error: interceptor_error)
+          else
+            log_debug(context, "Initializing request with #{input}")
+            @app.call(input, context)
+          end
+        log_debug(context, 'Finished request')
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::MODIFY_BEFORE_COMPLETION,
+          input: input,
+          context: context,
+          output: output,
+          aggregate_errors: false
+        )
+        output.error = interceptor_error if interceptor_error
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::READ_AFTER_EXECUTION,
+          input: input,
+          context: context,
+          output: output,
+          aggregate_errors: true
+        )
+        output.error = interceptor_error if interceptor_error
+
+        output
+      end
+    end
+  end
+end

data/lib/hearth/middleware/parse.rb

@@ -5,6 +5,8 @@ module Hearth
     # A middleware that parses a response object.
     # @api private
     class Parse
+      include Middleware::Logging
+
       # @param [Class] app The next middleware in the stack.
       # @param [Class] error_parser A parser object responsible for parsing the
       #  response if there is an error. It must respond to #parse and take the
@@ -23,19 +25,56 @@ module Hearth
       # @return [Output]
       def call(input, context)
         output = @app.call(input, context)
-        parse_error(context.response, output) unless output.error
-        parse_data(context.response, output) unless output.error
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::MODIFY_BEFORE_DESERIALIZATION,
+          input: input,
+          context: context,
+          output: output,
+          aggregate_errors: false
+        )
+        if interceptor_error
+          output.error = interceptor_error
+          return output
+        end
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::READ_BEFORE_DESERIALIZATION,
+          input: input,
+          context: context,
+          output: output,
+          aggregate_errors: false
+        )
+        if interceptor_error
+          output.error = interceptor_error
+          return output
+        end
+
+        parse_error(context, output) unless output.error
+        parse_data(context, output) unless output.error
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::READ_AFTER_DESERIALIZATION,
+          input: input,
+          context: context,
+          output: output,
+          aggregate_errors: false
+        )
+        output.error = interceptor_error if interceptor_error
+
         output
       end
 
       private
 
-      def parse_error(response, output)
-        output.error = @error_parser.parse(response)
+      def parse_error(context, output)
+        output.error = @error_parser.parse(context.response, output.metadata)
+        log_debug(context, "Parsed error: #{output.error}") if output.error
       end
 
-      def parse_data(response, output)
-        output.data = @data_parser.parse(response)
+      def parse_data(context, output)
+        output.data = @data_parser.parse(context.response)
+        log_debug(context, "Parsed data: #{output.data}") if output.data
       end
     end
   end

data/lib/hearth/middleware/retry.rb

@@ -2,41 +2,115 @@
 
 module Hearth
   module Middleware
-    # A middleware that retries the request.
+    # A middleware that retries the request using a retry strategy.
     # @api private
     class Retry
+      include Middleware::Logging
+
       # @param [Class] app The next middleware in the stack.
-      # @param [Integer] max_attempts The maximum number of attempts to make
-      #  before giving up.
-      # @param [Integer] max_delay The maximum delay between attempts.
-      def initialize(app, max_attempts:, max_delay:)
+      # @param [Strategy] retry_strategy (Standard) The retry strategy
+      #   to use. Hearth has two built in classes, Standard and Adaptive.
+      #   * `Retry::Standard` - A standardized set of retry rules across
+      #     the AWS SDKs. This includes support for retry quotas, which limit
+      #     the number of unsuccessful retries a client can make.
+      #   * `Retry::Adaptive` - An experimental retry mode that includes
+      #     all the functionality of `standard` mode along with automatic
+      #     client side throttling. This is a provisional mode that may change
+      #     behavior in the future.
+      def initialize(app, retry_strategy:, error_inspector_class:)
         @app = app
-        @max_attempts = max_attempts
-        @max_delay = max_delay
+        @retry_strategy = retry_strategy
+        @error_inspector_class = error_inspector_class
+
+        @retries = 0
       end
 
-      # @param input
-      # @param context
-      # @return [Output]
       def call(input, context)
-        attempt = 1
-        begin
-          @app.call(input, context)
-        rescue Hearth::HTTP::NetworkingError => e
-          raise e if attempt >= @max_attempts
-
-          Kernel.sleep(backoff_with_jitter(attempt))
-          attempt += 1
-          retry
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::MODIFY_BEFORE_RETRY_LOOP,
+          input: input,
+          context: context,
+          output: nil,
+          aggregate_errors: false
+        )
+        return Hearth::Output.new(error: interceptor_error) if interceptor_error
+
+        output = nil
+        token = @retry_strategy.acquire_initial_retry_token(nil)
+        log_debug(context, "Starting retry loop with token: #{token}")
+        loop do
+          interceptor_error = Interceptors.invoke(
+            hook: Interceptor::READ_BEFORE_ATTEMPT,
+            input: input,
+            context: context,
+            output: nil,
+            aggregate_errors: true
+          )
+
+          output =
+            if interceptor_error
+              Hearth::Output.new(error: interceptor_error)
+            else
+              log_debug(context, 'Attempting request in retry loop')
+              @app.call(input, context)
+            end
+
+          interceptor_error = Interceptors.invoke(
+            hook: Interceptor::MODIFY_BEFORE_ATTEMPT_COMPLETION,
+            input: input,
+            context: context,
+            output: output,
+            aggregate_errors: false
+          )
+          output.error = interceptor_error if interceptor_error
+
+          interceptor_error = Interceptors.invoke(
+            hook: Interceptor::READ_AFTER_ATTEMPT,
+            input: input,
+            context: context,
+            output: output,
+            aggregate_errors: true
+          )
+          output.error = interceptor_error if interceptor_error
+
+          if (error = output.error)
+            log_debug(context, "Request failed with error: #{error}")
+            error_info = @error_inspector_class.new(error, context.response)
+            token = @retry_strategy.refresh_retry_token(token, error_info)
+            break unless token
+
+            log_debug(context, "Retry token refreshed: #{token}")
+            log_debug(context, "Sleeping for #{token.retry_delay} seconds")
+            Kernel.sleep(token.retry_delay)
+          else
+            @retry_strategy.record_success(token)
+            log_debug(context, 'Request succeeded')
+            break
+          end
+
+          reset_request(context)
+          reset_response(context, output)
+          @retries += 1
         end
+        log_debug(context, 'Finished retry loop')
+        output
       end
 
       private
 
-      # https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
-      def backoff_with_jitter(attempt)
-        # scales like 1,2,4,8
-        Kernel.rand * [@max_delay, 2**(attempt - 1)].min
+      def reset_request(context)
+        request = context.request
+        request.body.rewind if request.body.respond_to?(:rewind)
+
+        context.auth.signer.reset(
+          request: request,
+          properties: context.auth.signer_properties
+        )
+      end
+
+      def reset_response(context, output)
+        context.response.reset
+        output.error = nil
       end
     end
   end

data/lib/hearth/middleware/send.rb

@@ -5,58 +5,170 @@ module Hearth
     # A middleware used to send the request.
     # @api private
     class Send
+      include Middleware::Logging
+
       # @param [Class] _app The next middleware in the stack.
       # @param [Boolean] stub_responses If true, a request is not sent and a
       #   stubbed response is returned.
-      # @param [Class] stub_class A stub object that is responsible for creating
-      #   a stubbed response. It must respond to #stub and take the response
-      #   and stub data as arguments.
-      # @param [Stubs] stubs A {Hearth::Stubbing:Stubs} object containing
+      # @param [Class] stub_data_class A stub object that is responsible for
+      #   creating a stubbed data response. It must respond to #stub and take
+      #   the response and stub data as arguments.
+      # @param [Array<Class>] stub_error_classes An array of error classes
+      #   that are responsible for creating a stubbed error response. They
+      #   must respond to #stub and take the response and stub data as
+      #   arguments.
+      # @param [Stubs] stubs A {Hearth::Stubs} object containing
       #   stubbed data for any given operation.
-      def initialize(_app, client:, stub_responses:, stub_class:, stubs:)
+      def initialize(_app, client:, stub_responses:,
+                     stub_data_class:, stub_error_classes:, stubs:)
         @client = client
         @stub_responses = stub_responses
-        @stub_class = stub_class
+        @stub_data_class = stub_data_class
+        @stub_error_classes = stub_error_classes
         @stubs = stubs
       end
 
-      # @param _input
+      # @param input
       # @param context
       # @return [Output]
-      def call(_input, context)
+      def call(input, context)
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::MODIFY_BEFORE_TRANSMIT,
+          input: input,
+          context: context,
+          output: nil,
+          aggregate_errors: false
+        )
+        return Hearth::Output.new(error: interceptor_error) if interceptor_error
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::READ_BEFORE_TRANSMIT,
+          input: input,
+          context: context,
+          output: nil,
+          aggregate_errors: false
+        )
+        return Hearth::Output.new(error: interceptor_error) if interceptor_error
+
+        output = Output.new
         if @stub_responses
-          stub = @stubs.next(context.operation_name)
-          output = Output.new
-          apply_stub(stub, context, output)
-          output
+          stub_response(input, context, output)
         else
-          @client.transmit(
-            request: context.request,
-            response: context.response
-          )
-          Output.new
+          send_request(context, output)
         end
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::READ_AFTER_TRANSMIT,
+          input: input,
+          context: context,
+          output: output,
+          aggregate_errors: false
+        )
+        output.error = interceptor_error if interceptor_error
+
+        output
       end
 
       private
 
-      def apply_stub(stub, context, output)
+      def stub_response(input, context, output)
+        stub = @stubs.next(context.operation_name)
+        log_debug(context, "Stubbing response with stub: #{stub}")
+        apply_stub(stub, input, context, output)
+        log_debug(context, "Stubbed response: #{context.response.inspect}")
+        return unless context.response.body.respond_to?(:rewind)
+
+        context.response.body.rewind
+      end
+
+      def send_request(context, output)
+        log_debug(context, "Sending request: #{context.request.inspect}")
+        @client.transmit(
+          request: context.request,
+          response: context.response,
+          logger: context.logger
+        )
+        log_debug(context, "Received response: #{context.response.inspect}")
+      rescue Hearth::NetworkingError => e
+        output.error = e
+      end
+
+      def apply_stub(stub, input, context, output)
         case stub
         when Proc
-          stub = stub.call(context)
-          apply_stub(stub, context, output) if stub
-        when Exception
+          stub = stub.call(input)
+          apply_stub(stub, input, context, output)
+        when Exception, ApiError
           output.error = stub
-        when Class
-          output.error = stub.new
         when Hash
-          @stub_class.stub(context.response, stub: stub)
+          apply_stub_hash(stub, context)
         when NilClass
-          @stub_class.stub(context.response, stub: @stub_class.default)
+          apply_stub_nil(context)
+        when Hearth::Structure
+          apply_stub_hearth_structure(stub, context)
+        when Hearth::Response
+          context.response.replace(stub)
         else
           raise ArgumentError, 'Unsupported stub type'
         end
       end
+
+      def apply_stub_hash(stub, context)
+        if stub.key?(:error) && !stub.key?(:data)
+          apply_stub_hash_error(stub, context)
+        elsif stub.key?(:data) && !stub.key?(:error)
+          apply_stub_hash_data(stub, context)
+        else
+          raise ArgumentError, 'Unsupported stub hash, must be :data or :error'
+        end
+      end
+
+      def apply_stub_hash_data(stub, context)
+        output = @stub_data_class.build(stub[:data], context: 'stub')
+        @stub_data_class.validate!(output, context: 'stub')
+        @stub_data_class.stub(context.response, stub: output)
+      end
+
+      def apply_stub_hash_error(stub, context)
+        stub_error_class = stub_error_class(stub[:error][:class])
+        output = stub_error_class.build(
+          stub[:error][:data] || {},
+          context: 'stub'
+        )
+        stub_error_class.validate!(output, context: 'stub')
+        stub_error_class.stub(context.response, stub: output)
+      end
+
+      def stub_error_class(error_class)
+        raise ArgumentError, 'Missing stub error class' unless error_class
+
+        unless error_class.is_a?(Class)
+          raise ArgumentError, 'Stub error class must be a class'
+        end
+
+        error_base_name = error_class.name.split('::').last
+        stub_class = @stub_error_classes.find do |stub_error_class|
+          stub_base_name = stub_error_class.name.split('::').last
+          error_base_name == stub_base_name
+        end
+        raise ArgumentError, 'Unsupported stub error class' unless stub_class
+
+        stub_class
+      end
+
+      def apply_stub_nil(context)
+        output = @stub_data_class.build(
+          @stub_data_class.default,
+          context: 'stub'
+        )
+        @stub_data_class.validate!(output, context: 'stub')
+        @stub_data_class.stub(context.response, stub: output)
+      end
+
+      def apply_stub_hearth_structure(stub, context)
+        @stub_data_class.validate!(stub, context: 'stub')
+        @stub_data_class.stub(context.response, stub: stub)
+      end
     end
   end
 end