hearth 1.0.0.pre1 → 1.0.0.pre3

data/lib/hearth/middleware/retry.rb

@@ -2,41 +2,122 @@
 
 module Hearth
   module Middleware
-    # A middleware that retries the request.
-    # @api private
+    # A middleware that retries the request using a retry strategy.
     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}")
+            break unless retryable?(context.request)
+
+            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')
+        log_debug(context, "Total retries: #{@retries}")
+        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 retryable?(request)
+        # IO responds to #rewind however it returns an illegal seek error
+        request.body.respond_to?(:rewind) && !request.body.instance_of?(IO)
+      end
+
+      def reset_request(context)
+        request = context.request
+        request.body.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

@@ -3,60 +3,171 @@
 module Hearth
   module Middleware
     # 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

data/lib/hearth/middleware/sign.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Middleware
+    # A middleware that signs requests using the resolved identity.
+    # @api private
+    class Sign
+      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::MODIFY_BEFORE_SIGNING,
+          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_SIGNING,
+          input: input,
+          context: context,
+          output: nil,
+          aggregate_errors: false
+        )
+        return Hearth::Output.new(error: interceptor_error) if interceptor_error
+
+        sign_request(context)
+        output = @app.call(input, context)
+
+        interceptor_error = Interceptors.invoke(
+          hook: Interceptor::READ_AFTER_SIGNING,
+          input: input,
+          context: context,
+          output: output,
+          aggregate_errors: false
+        )
+        output.error = interceptor_error if interceptor_error
+
+        output
+      end
+
+      private
+
+      def sign_request(context)
+        log_debug(context, "Signing request with: #{context.auth.signer}")
+        context.auth.signer.sign(
+          request: context.request,
+          identity: context.auth.identity,
+          properties: context.auth.signer_properties
+        )
+        log_debug(context, "Signed request: #{context.request.inspect}")
+      end
+    end
+  end
+end

data/lib/hearth/middleware/validate.rb

@@ -5,6 +5,8 @@ module Hearth
     # A middleware used to validate input.
     # @api private
     class Validate
+      include Middleware::Logging
+
       # @param [Class] app The next middleware in the stack.
       # @param [Boolean] validate_input If true, the input is validated against
       #   the model and an error is raised for unexpected types.
@@ -21,9 +23,17 @@ module Hearth
       # @param context
       # @return [Output]
       def call(input, context)
-        @validator.validate!(input, context: 'input') if @validate_input
+        validate_input(input, context) if @validate_input
         @app.call(input, context)
       end
+
+      private
+
+      def validate_input(input, context)
+        log_debug(context, "Validating input with: #{input}")
+        @validator.validate!(input, context: 'input')
+        log_debug(context, 'Validated input')
+      end
     end
   end
 end

data/lib/hearth/middleware.rb

@@ -1,16 +1,28 @@
 # frozen_string_literal: true
 
-require_relative 'middleware/around_handler'
+module Hearth
+  # @api private
+  module Middleware
+    # Helper methods for logging to middleware.
+    module Logging
+      # Logs a debug message to the logger on context. The message is prefixed
+      # with the invocation id and the class name.
+      def log_debug(context, message)
+        context.logger.debug(
+          "[#{context.invocation_id}] [#{self.class}] #{message}"
+        )
+      end
+    end
+  end
+end
+
+require_relative 'middleware/auth'
 require_relative 'middleware/build'
+require_relative 'middleware/endpoint'
 require_relative 'middleware/host_prefix'
 require_relative 'middleware/parse'
-require_relative 'middleware/request_handler'
-require_relative 'middleware/response_handler'
 require_relative 'middleware/retry'
 require_relative 'middleware/send'
+require_relative 'middleware/sign'
 require_relative 'middleware/validate'
-
-module Hearth
-  # @api private
-  module Middleware; end
-end
+require_relative 'middleware/initialize'

data/lib/hearth/middleware_stack.rb

@@ -11,53 +11,11 @@ module Hearth
       @middleware.push([middleware, middleware_kwargs])
     end
 
-    def use_before(before, middleware, **middleware_kwargs)
-      new_middleware = []
-      @middleware.each do |klass, args|
-        new_middleware << [middleware, middleware_kwargs] if before == klass
-        new_middleware << [klass, args]
-      end
-      unless new_middleware.size == @middleware.size + 1
-        raise ArgumentError,
-              "Failed to insert #{middleware} before #{before}"
-      end
-
-      @middleware = new_middleware
-    end
-
-    def use_after(after, middleware, **middleware_kwargs)
-      new_middleware = []
-      @middleware.each do |klass, args|
-        new_middleware << [klass, args]
-        new_middleware << [middleware, middleware_kwargs] if after == klass
-      end
-      unless new_middleware.size == @middleware.size + 1
-        raise ArgumentError,
-              "Failed to insert #{middleware} after #{after}"
-      end
-
-      @middleware = new_middleware
-    end
-
-    def remove(remove)
-      new_middleware = []
-      @middleware.each do |klass, args|
-        new_middleware << [klass, args] unless klass == remove
-      end
-
-      unless new_middleware.size == @middleware.size - 1
-        raise ArgumentError,
-              "Failed to remove #{remove}"
-      end
-
-      @middleware = new_middleware
-    end
-
     # @param input
     # @param context
     # @return [Output]
-    def run(input:, context:)
-      stack.call(input, context)
+    def run(input, context)
+      stack&.call(input, context) || Output.new
     end
 
     private

data/lib/hearth/networking_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Hearth
+  # 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

data/lib/hearth/number_helper.rb

@@ -6,8 +6,8 @@ module Hearth
   # @api private
   module NumberHelper
     class << self
-      # @param [Number,String] input
-      # @return [String] The serialized number
+      # @param [Number] input
+      # @return [Number, String] The serialized number
       def serialize(input)
         if input == ::Float::INFINITY then 'Infinity'
         elsif input == -::Float::INFINITY then '-Infinity'
@@ -18,7 +18,7 @@ module Hearth
       end
 
       # @param [String] str
-      # @return [Number] The input as a number
+      # @return [Float, nil] The input as a number
       def deserialize(str)
         case str
         when 'Infinity' then ::Float::INFINITY

data/lib/hearth/output.rb

@@ -2,19 +2,23 @@
 
 module Hearth
   # A wrapper class that contains an error or data from the response.
-  # @api private
   class Output
-    # @param [StandardError] error The error class to be raised.
+    # @param [ApiError] error The error class to be raised.
     # @param [Struct] data The data returned by a client.
-    def initialize(error: nil, data: nil)
+    # @param [Hash] metadata Response metadata set by client middleware.
+    def initialize(error: nil, data: nil, metadata: {})
       @error = error
       @data = data
+      @metadata = metadata
     end
 
-    # @return [StandardError, nil]
+    # @return [ApiError, nil]
     attr_accessor :error
 
     # @return [Struct, nil]
     attr_accessor :data
+
+    # @return [Hash]
+    attr_accessor :metadata
   end
 end

data/lib/hearth/plugin_list.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Hearth
+  # A list of plugins that can be applied to config. Plugins are callables
+  # that take one argument (config) and are called during client initialization
+  # or operation invocation to modify config.
+  class PluginList
+    include Enumerable
+
+    # Initialize a PluginList.
+    #
+    # @param [Array] plugins ([]) A list of plugins to initialize with
+    def initialize(plugins = [])
+      unless plugins.respond_to?(:each)
+        raise ArgumentError, 'Plugins must be an enumerable'
+      end
+
+      @plugins = []
+      plugins.each { |p| add(p) }
+    end
+
+    # Add a plugin
+    #
+    # @param [Callable] plugin
+    def add(plugin)
+      unless valid_plugin?(plugin)
+        raise ArgumentError,
+              'Plugin must be callable and take one argument (config)'
+      end
+
+      @plugins << plugin
+    end
+
+    alias << add
+
+    def each(&block)
+      @plugins.each(&block)
+    end
+
+    private
+
+    # plugins must be callable and take exactly 1 argument (config)
+    def valid_plugin?(plugin)
+      case plugin
+      when Proc
+        # the arity of a proc.method(:call) is -1, need to special case
+        plugin.arity == 1
+      else
+        plugin.respond_to?(:call) && plugin.method(:call).arity == 1
+      end
+    end
+  end
+end