hearth 1.0.0.pre1 → 1.0.0.pre2

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,27 @@
 # 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/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,52 +11,10 @@ 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:)
+    def run(input, context)
       stack.call(input, context)
     end
 

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'

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

data/lib/hearth/query/param.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Query
+    # A class used to represent a query parameter before serialization.
+    class Param
+      # @param [String] name
+      # @param [String, Array<String>] value (nil)
+      def initialize(name, value = nil)
+        @name = name
+        @value = value
+      end
+
+      # @return [String]
+      attr_reader :name
+
+      # @return [String, Array<String>, nil]
+      attr_reader :value
+
+      # @return [String]
+      def to_s
+        if value.is_a?(Array)
+          value.map { |v| serialize(name, v) }.join('&')
+        else
+          serialize(name, value)
+        end
+      end
+
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(Param) &&
+          other.name == name &&
+          other.value == value
+      end
+
+      # @return [Boolean]
+      def <=>(other)
+        name <=> other.name
+      end
+
+      private
+
+      def serialize(name, value)
+        value.nil? ? escape(name) : "#{escape(name)}=#{escape(value)}"
+      end
+
+      def escape(value)
+        Hearth::HTTP.uri_escape(value.to_s)
+      end
+    end
+  end
+end

data/lib/hearth/query/param_list.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Query
+    # A class used to collect query params before serialization.
+    class ParamList
+      include Enumerable
+
+      def initialize
+        @params = {}
+      end
+
+      # @param [String] param_name
+      # @param [String, nil] param_value
+      # @return [Param]
+      def set(param_name, param_value = nil)
+        param = Param.new(param_name, param_value)
+        @params[param.name] = param
+      end
+      alias []= set
+
+      # @return [Param, nil]
+      def [](param_name)
+        @params[param_name]
+      end
+
+      # @param [String] param_name
+      # @return [Param, nil]
+      def delete(param_name)
+        @params.delete(param_name)
+      end
+
+      # @return [Enumerable]
+      def each(&block)
+        to_a.each(&block)
+      end
+
+      # @return [Boolean]
+      def empty?
+        @params.empty?
+      end
+
+      # @return [Array<Param>] Returns an array of sorted {Param} objects.
+      def to_a
+        @params.values.sort
+      end
+
+      # @return [String]
+      def to_s
+        to_a.map(&:to_s).join('&')
+      end
+    end
+  end
+end

data/lib/hearth/query/param_matcher.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'rspec/expectations'
+
+# Provides an rspec matcher for CGI.parse to check Float precision.
+# @api private
+RSpec::Matchers.define :match_query_params do |expected|
+  match do |actual|
+    return true if actual == expected
+    return false unless actual.instance_of?(expected.class)
+
+    expect(actual.keys.length).to eq(expected.keys.length)
+    expect(actual.values.length).to eq(expected.values.length)
+
+    expected.each do |ek, e|
+      expect(actual.keys).to include(ek)
+      a = actual[ek]
+      expect(e.length).to eq(a.length)
+
+      a.zip(e).each do |a0, e0|
+        # Timestamps can have optional precision.
+        if (float = Float(a0) rescue false)
+          expect(float).to eq(e0.to_f)
+        else
+          expect(a0).to eq(e0)
+        end
+      end
+    end
+  end
+
+  diffable
+end

data/lib/hearth/refreshing_identity_resolver.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Hearth
+  # A module that can be included in a class to provide a #identity method.
+  # The class must implement #refresh(properties) that sets @identity. The
+  # refresh method will be called when #identity is called and the identity
+  # is nil or near expiration.
+  module RefreshingIdentityResolver
+    SYNC_EXPIRATION_LENGTH = 300 # 5 minutes
+    ASYNC_EXPIRATION_LENGTH = 600 # 10 minutes
+
+    def initialize
+      @mutex = Mutex.new
+    end
+
+    # @return [Identity]
+    def identity(properties = {})
+      if @identity
+        refresh_if_near_expiration!(properties)
+      else # initialization
+        @mutex.synchronize { refresh(properties) }
+      end
+      @identity
+    end
+
+    private
+
+    def sync_expiration_length
+      self.class::SYNC_EXPIRATION_LENGTH
+    end
+
+    def async_expiration_length
+      self.class::ASYNC_EXPIRATION_LENGTH
+    end
+
+    # Refreshes identity asynchronously and synchronously.
+    # If we are near to expiration, block while refreshing the identity.
+    # Otherwise, if we're approaching expiration, use the existing identity
+    # but attempt a refresh in the background.
+    def refresh_if_near_expiration!(properties)
+      # NOTE: This check is an optimization. Rather than acquire the mutex on
+      # every #refresh_if_near_expiration call, we check before doing so, and
+      # then we check within the mutex to avoid a race condition.
+      if near_expiration?(sync_expiration_length)
+        @mutex.synchronize do
+          refresh(properties) if near_expiration?(sync_expiration_length)
+        end
+      elsif @async_refresh && near_expiration?(async_expiration_length)
+        unless @mutex.locked?
+          Thread.new do
+            @mutex.synchronize do
+              refresh(properties) if near_expiration?(async_expiration_length)
+            end
+          end
+        end
+      end
+    end
+
+    def near_expiration?(expiration_length)
+      (Time.now.to_i + expiration_length) > @identity.expiration.to_i
+    end
+  end
+end

data/lib/hearth/request.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'stringio'
+require 'uri'
+
+module Hearth
+  # Represents a base request.
+  class Request
+    # @param [URI] uri (URI(''))
+    # @param [IO] body (StringIO.new)
+    def initialize(uri: URI(''), body: StringIO.new)
+      @uri = uri
+      @body = body
+    end
+
+    # @return [URI]
+    attr_accessor :uri
+
+    # @return [IO]
+    attr_accessor :body
+  end
+end

data/lib/hearth/response.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Hearth
+  # Represents a base response.
+  class Response
+    # @param [IO] body (StringIO.new)
+    def initialize(body: StringIO.new)
+      @body = body
+    end
+
+    # @return [IO]
+    attr_accessor :body
+
+    # Replace attributes from other response
+    # @param [Response] other
+    # @return [Response]
+    def replace(other)
+      @body.truncate(0)
+      IO.copy_stream(other.body, @body)
+      @body.rewind
+      self
+    end
+
+    # Resets the response.
+    # @return [Response]
+    def reset
+      @body.truncate(0) if @body.respond_to?(:truncate)
+      self
+    end
+  end
+end

data/lib/hearth/retry/adaptive.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Retry
+    # Adaptive retry strategy for retrying requests.
+    class Adaptive < Strategy
+      # @param [#call] backoff (ExponentialBackoff) A callable object that
+      #   calculates a backoff delay for a retry attempt.
+      # @param [Integer] max_attempts (3) The maximum number of attempts that
+      #   will be made for a single request, including the initial attempt.
+      # @param [Boolean] wait_to_fill When true, the request will sleep until
+      #   there is sufficient client side capacity to retry the request. When
+      #   false, the request will raise a `CapacityNotAvailableError` and will
+      #   not retry instead of sleeping.
+      def initialize(backoff: ExponentialBackoff.new, max_attempts: 3,
+                     wait_to_fill: true)
+        super()
+        @backoff = backoff
+        @max_attempts = max_attempts
+        @wait_to_fill = wait_to_fill
+
+        # instance state
+        @client_rate_limiter = ClientRateLimiter.new
+        @retry_quota = RetryQuota.new
+        @capacity_amount = nil
+      end
+
+      def acquire_initial_retry_token(_token_scope = nil)
+        @client_rate_limiter.token_bucket_acquire(
+          1, wait_to_fill: @wait_to_fill
+        )
+        Token.new(retry_count: 0)
+      end
+
+      def refresh_retry_token(retry_token, error_info)
+        return unless error_info.retryable?
+
+        @client_rate_limiter.update_sending_rate(
+          error_info.error_type == 'Throttling'
+        )
+        return if retry_token.retry_count >= @max_attempts - 1
+
+        @capacity_amount = @retry_quota.checkout_capacity(error_info)
+        return unless @capacity_amount.positive?
+
+        delay = error_info.hints[:retry_after]
+        delay ||= @backoff.call(retry_token.retry_count)
+        retry_token.retry_count += 1
+        retry_token.retry_delay = delay
+        retry_token
+      end
+
+      def record_success(retry_token)
+        @client_rate_limiter.update_sending_rate(false)
+        @retry_quota.release(@capacity_amount)
+        retry_token
+      end
+    end
+  end
+end

data/lib/hearth/retry/capacity_not_available_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Retry
+    # Raised by Retry::Adaptive when the client rate limiter
+    # doesn't have capacity.
+    class CapacityNotAvailableError < RuntimeError; end
+  end
+end