hearth 1.0.0.pre1 → 1.0.0.pre2

data/lib/hearth/retry/client_rate_limiter.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Retry
+    # @api private
+    # Used only in 'adaptive' retry mode
+    class ClientRateLimiter
+      MIN_CAPACITY = 1
+      MIN_FILL_RATE = 0.5
+      SMOOTH = 0.8
+      # How much to scale back after a throttling response
+      BETA = 0.7
+      # Controls how aggressively we scale up after being throttled
+      SCALE_CONSTANT = 0.4
+
+      def initialize
+        @mutex                = Mutex.new
+        @fill_rate            = nil
+        @max_capacity         = nil
+        @current_capacity     = 0
+        @last_timestamp       = nil
+        @enabled              = false
+        @measured_tx_rate     = 0
+        @last_tx_rate_bucket  = monotonic_seconds
+        @request_count        = 0
+        @last_max_rate        = 0
+        @last_throttle_time   = monotonic_seconds
+        @calculated_rate      = nil
+      end
+
+      def token_bucket_acquire(amount, wait_to_fill: true)
+        # Client side throttling is not enabled until we see a
+        # throttling error
+        return unless @enabled
+
+        @mutex.synchronize do
+          token_bucket_refill
+
+          # Next see if we have enough capacity for the requested amount
+          while @current_capacity < amount
+            raise CapacityNotAvailableError unless wait_to_fill
+
+            @mutex.sleep((amount - @current_capacity) / @fill_rate)
+            token_bucket_refill
+          end
+          @current_capacity -= amount
+        end
+      end
+
+      def update_sending_rate(is_throttling_error)
+        @mutex.synchronize do
+          update_measured_rate
+
+          if is_throttling_error
+            rate_to_use = if @enabled
+                            [@measured_tx_rate, @fill_rate].min
+                          else
+                            @measured_tx_rate
+                          end
+
+            # The fill_rate is from the token bucket
+            @last_max_rate = rate_to_use
+            calculate_time_window
+            @last_throttle_time = monotonic_seconds
+            @calculated_rate = cubic_throttle(rate_to_use)
+            enable_token_bucket
+          else
+            calculate_time_window
+            @calculated_rate = cubic_success(monotonic_seconds)
+          end
+
+          new_rate = [@calculated_rate, 2 * @measured_tx_rate].min
+          token_bucket_update_rate(new_rate)
+        end
+      end
+
+      private
+
+      def monotonic_seconds
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def token_bucket_refill
+        timestamp = monotonic_seconds
+        unless @last_timestamp
+          @last_timestamp = timestamp
+          return
+        end
+
+        fill_amount = (timestamp - @last_timestamp) * @fill_rate
+        @current_capacity = [
+          @max_capacity, @current_capacity + fill_amount
+        ].min
+
+        @last_timestamp = timestamp
+      end
+
+      def token_bucket_update_rate(new_rps)
+        # Refill based on our current rate before we update to the
+        # new fill rate
+        token_bucket_refill
+        @fill_rate = [new_rps, MIN_FILL_RATE].max
+        @max_capacity = [new_rps, MIN_CAPACITY].max
+        # When we scale down we can't have a current capacity that exceeds our
+        # max_capacity.
+        @current_capacity = [@current_capacity, @max_capacity].min
+      end
+
+      def enable_token_bucket
+        @enabled = true
+      end
+
+      def update_measured_rate
+        t = monotonic_seconds
+        time_bucket = (t * 2).floor / 2.0
+        @request_count += 1
+        return unless time_bucket > @last_tx_rate_bucket
+
+        current_rate = @request_count / (time_bucket - @last_tx_rate_bucket)
+        @measured_tx_rate = (current_rate * SMOOTH) +
+                            (@measured_tx_rate * (1 - SMOOTH))
+        @request_count = 0
+        @last_tx_rate_bucket = time_bucket
+      end
+
+      def calculate_time_window
+        # This is broken out into a separate calculation because it only
+        # gets updated when @last_max_rate changes so it can be cached.
+        base = ((@last_max_rate * (1 - BETA)) / SCALE_CONSTANT)
+        @time_window = base**(1.0 / 3)
+      end
+
+      def cubic_success(timestamp)
+        dt = timestamp - @last_throttle_time
+        (SCALE_CONSTANT * ((dt - @time_window)**3)) + @last_max_rate
+      end
+
+      def cubic_throttle(rate_to_use)
+        rate_to_use * BETA
+      end
+    end
+  end
+end

data/lib/hearth/retry/exponential_backoff.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Retry
+    # Computes an exponential backoff delay for a retry attempt.
+    class ExponentialBackoff
+      # Max backoff (in seconds)
+      MAX_BACKOFF = 20
+
+      def call(attempts)
+        [Kernel.rand * (2**attempts), MAX_BACKOFF].min
+      end
+    end
+  end
+end

data/lib/hearth/retry/retry_quota.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Retry
+    # @api private
+    # Used in 'standard' and 'adaptive' retry modes.
+    class RetryQuota
+      INITIAL_RETRY_TOKENS = 500
+      RETRY_COST = 5
+      NO_RETRY_INCREMENT = 1
+      TIMEOUT_RETRY_COST = 10
+
+      def initialize
+        @mutex              = Mutex.new
+        @max_capacity       = INITIAL_RETRY_TOKENS
+        @available_capacity = @max_capacity
+      end
+
+      # Check if there is sufficient capacity to retry and return it.
+      # If there is insufficient capacity, return 0
+      # @return [Integer] The amount of capacity checked out
+      def checkout_capacity(error_info)
+        @mutex.synchronize do
+          capacity_amount =
+            if error_info.error_type == 'Transient'
+              TIMEOUT_RETRY_COST
+            else
+              RETRY_COST
+            end
+
+          # unable to acquire capacity
+          return 0 if capacity_amount > @available_capacity
+
+          @available_capacity -= capacity_amount
+          capacity_amount
+        end
+      end
+
+      # capacity_amount refers to the amount of capacity requested from
+      # the last retry.  It can either be RETRY_COST, TIMEOUT_RETRY_COST,
+      # or unset.
+      def release(capacity_amount)
+        # Implementation note:  The release() method is called for
+        # every API call.  In the common case where the request is
+        # successful and we're at full capacity, we can avoid locking.
+        # We can't exceed max capacity so there's no work we have to do.
+        return if @available_capacity == @max_capacity
+
+        @mutex.synchronize do
+          @available_capacity += capacity_amount || NO_RETRY_INCREMENT
+          @available_capacity = [@available_capacity, @max_capacity].min
+        end
+      end
+    end
+  end
+end

data/lib/hearth/retry/standard.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Retry
+    # Standard retry strategy for retrying requests.
+    class Standard < 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.
+      def initialize(backoff: ExponentialBackoff.new, max_attempts: 3)
+        super()
+        @backoff = backoff
+        @max_attempts = max_attempts
+
+        # instance state
+        @retry_quota = RetryQuota.new
+        @capacity_amount = nil
+      end
+
+      def acquire_initial_retry_token(_token_scope = nil)
+        Token.new(retry_count: 0)
+      end
+
+      def refresh_retry_token(retry_token, error_info)
+        return unless error_info.retryable?
+
+        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)
+        @retry_quota.release(@capacity_amount)
+        retry_token
+      end
+    end
+  end
+end

data/lib/hearth/retry/strategy.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Retry
+    # Interface for retry strategies.
+    class Strategy
+      def acquire_initial_retry_token(_token_scope = nil)
+        raise NotImplementedError
+      end
+
+      def refresh_retry_token(_retry_token, _error_info)
+        raise NotImplementedError
+      end
+
+      def record_success(_retry_token)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/hearth/retry.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'retry/strategy'
+
+require_relative 'retry/adaptive'
+require_relative 'retry/capacity_not_available_error'
+require_relative 'retry/client_rate_limiter'
+require_relative 'retry/exponential_backoff'
+require_relative 'retry/retry_quota'
+require_relative 'retry/standard'
+
+module Hearth
+  module Retry
+    Token = Struct.new(:retry_count, :retry_delay, keyword_init: true)
+  end
+end

data/lib/hearth/signers/anonymous.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Signers
+    # A signer that does not sign requests.
+    class Anonymous < Signers::Base
+      def sign(request:, identity:, properties:)
+        # Do nothing.
+      end
+
+      def reset(request:, properties:)
+        # Do nothing.
+      end
+    end
+  end
+end

data/lib/hearth/signers/http_api_key.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Signers
+    # A signer that signs requests using the HTTP API Key Auth scheme.
+    class HTTPApiKey < Signers::Base
+      def sign(request:, identity:, properties:)
+        case properties[:in]
+        when 'header'
+          value = "#{properties[:scheme]} #{identity.key}".strip
+          request.headers[properties[:name]] = value
+        when 'query'
+          name = properties[:name]
+          request.append_query_param(name, identity.key)
+        end
+      end
+
+      def reset(request:, properties:)
+        case properties[:in]
+        when 'header'
+          request.headers.delete(properties[:name])
+        when 'query'
+          name = properties[:name]
+          request.remove_query_param(name)
+        end
+      end
+    end
+  end
+end

data/lib/hearth/signers/http_basic.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Hearth
+  module Signers
+    # A signer that signs requests using the HTTP Basic Auth scheme.
+    class HTTPBasic
+      # rubocop:disable Lint/UnusedMethodArgument
+      def sign(request:, identity:, properties:)
+        # TODO: does not handle realm or other properties
+        identity_string = "#{identity.username}:#{identity.password}"
+        encoded = Base64.strict_encode64(identity_string)
+        request.headers['Authorization'] = "Basic #{encoded}"
+      end
+
+      def reset(request:, properties:)
+        request.headers.delete('Authorization')
+      end
+      # rubocop:enable Lint/UnusedMethodArgument
+    end
+  end
+end

data/lib/hearth/signers/http_bearer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Signers
+    # A signer that signs requests using the HTTP Bearer Auth scheme.
+    class HTTPBearer < Signers::Base
+      # rubocop:disable Lint/UnusedMethodArgument
+      def sign(request:, identity:, properties:)
+        # TODO: does not handle realm or other properties
+        request.headers['Authorization'] = "Bearer #{identity.token}"
+      end
+
+      def reset(request:, properties:)
+        request.headers.delete('Authorization')
+      end
+      # rubocop:enable Lint/UnusedMethodArgument
+    end
+  end
+end

data/lib/hearth/signers/http_digest.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Hearth
+  module Signers
+    # A signer that signs requests using the HTTP Digest Auth scheme.
+    class HTTPDigest < Signers::Base
+      def sign(request:, identity:, properties:)
+        # TODO: requires a nonce from the server - this cannot
+        # be implemented unless we rescue from a 401 and retry
+        # with the nonce
+        raise NotImplementedError
+      end
+
+      def reset(request:, properties:)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/hearth/signers.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Hearth
+  # Namespace for all Signer classes.
+  module Signers
+    # Base class for all Signer classes.
+    class Base
+      def sign(request:, identity:, properties:)
+        raise NotImplementedError
+      end
+
+      def reset(request:, properties:)
+        raise NotImplementedError
+      end
+    end
+  end
+end
+
+require_relative 'signers/anonymous'
+require_relative 'signers/http_api_key'
+require_relative 'signers/http_basic'
+require_relative 'signers/http_bearer'
+require_relative 'signers/http_digest'

data/lib/hearth/stubs.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Hearth
+  # Provides a thread safe data structure for adding and getting stubs
+  # per operation.
+  # @api private
+  class Stubs
+    def initialize
+      @stubs = {}
+      @stub_mutex = Mutex.new
+    end
+
+    def add_stubs(operation_name, stubs)
+      @stub_mutex.synchronize do
+        @stubs[operation_name.to_sym] = stubs
+      end
+    end
+
+    def next(operation_name)
+      @stub_mutex.synchronize do
+        stubs = @stubs[operation_name] || []
+        case stubs.length
+        when 0 then nil
+        when 1 then stubs.first
+        else stubs.shift
+        end
+      end
+    end
+  end
+end

data/lib/hearth/time_helper.rb

@@ -11,11 +11,12 @@ module Hearth
       # @param [Time] time
       # @return [String<Date Time>] The time as an ISO8601 string.
       def to_date_time(time)
-        time.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+        optional_ms_digits = time.subsec.zero? ? nil : 3
+        time.utc.iso8601(optional_ms_digits)
       end
 
       # @param [Time] time
-      # @return [Float<Epoch Seconds>] Returns float value of
+      # @return [Float<Epoch Seconds>] Returns the float value of
       #   epoch seconds with millisecond precision.
       def to_epoch_seconds(time)
         time = time.utc
@@ -28,7 +29,8 @@ module Hearth
       # @return [String<Http Date>] Returns the time formatted
       #   as an HTTP header date.
       def to_http_date(time)
-        time.utc.httpdate
+        fractional = '.%L' unless time.subsec.zero?
+        time.utc.strftime("%a, %d %b %Y %H:%M:%S#{fractional} GMT")
       end
     end
   end

data/lib/hearth/validator.rb

@@ -3,18 +3,57 @@
 module Hearth
   # Utility module for working with request parameters.
   #
-  # * Validate structure of parameters against the expected type.
+  # * Validate structure of parameters against the expected input.
   # * Raise errors with context when validation fails.
   # @api private
   module Validator
-    # Validate the given values is of the given type(s).
+    # Validate the given value is of the given type(s).
+    # @param value [Object] The value to validate.
+    # @param types [Array<Class>] The types to validate against.
+    # @param context [String] The context of the value being validated.
     # @raise [ArgumentError] Raises when the value is not one of given type(s).
-    def self.validate!(value, *types, context:)
-      return if !value || types.any? { |type| value.is_a?(type) }
+    def self.validate_types!(value, *types, context:)
+      return if value.nil? || types.any? { |type| value.is_a?(type) }
 
       raise ArgumentError,
-            "Expected #{context} to be in "\
+            "Expected #{context} to be in " \
             "[#{types.map(&:to_s).join(', ')}], got #{value.class}."
     end
+
+    # Validate a value is present and not nil.
+    # @param value [Object] The value to validate.
+    # @param context [String] The context of the value being validated.
+    # @raise [ArgumentError] Raises when the value is nil.
+    def self.validate_required!(value, context:)
+      raise ArgumentError, "Expected #{context} to be set." if value.nil?
+    end
+
+    # Validate unknown parameters are not present for a given Struct.
+    # @param struct [Struct] The Struct to validate against.
+    # @param params [Hash] The parameters to validate.
+    # @param context [String] The context of the value being validated.
+    # @raise [ArgumentError] Raises when unknown parameters are present.
+    def self.validate_unknown!(struct, params, context:)
+      unknown = params.keys - struct.members
+      return if unknown.empty?
+
+      unknown = unknown.map { |key| "#{context}[:#{key}]" }
+      raise ArgumentError,
+            "Unexpected members: [#{unknown.join(', ')}]"
+    end
+
+    # Validate the given value is within the expected range (inclusive).
+    # @param value [Object] The value to validate.
+    # @param min [Numeric] The minimum that the given value should be.
+    # @param max [Numeric] The maximum that the given value should be.
+    # @param context [String] The context of the value being validated.
+    # @raise [ArgumentError] Raises when the value is not within expected range.
+    def self.validate_range!(value, min:, max:, context:)
+      return if value.nil? || value.between?(min, max)
+
+      raise ArgumentError,
+            "Expected #{context} to be between " \
+            "#{min} to #{max}, got #{value}."
+    end
   end
 end

data/lib/hearth/waiters/poller.rb

@@ -6,8 +6,8 @@ module Hearth
   module Waiters
     # Abstract Poller used by generated service Waiters. This class handles
     # sending the request and matching input or output.
+    # @api private
     class Poller
-      # @api private
       def initialize(options = {})
         @operation_name = options[:operation_name]
         @acceptors = options[:acceptors]
@@ -42,7 +42,7 @@ module Hearth
       # @return [Array<Symbol,Response>]
       def call(client, params = {}, options = {})
         begin
-          options = options.merge(input_output_middleware)
+          options = options.merge(input_output_interceptor)
           response = client.send(@operation_name, params, options)
         rescue Hearth::ApiError => e
           error = e
@@ -58,11 +58,10 @@ module Hearth
 
       private
 
-      def input_output_middleware
-        middleware = lambda do |input, _context|
-          @input = input # get internal details of middleware
-        end
-        { middleware: MiddlewareBuilder.before_send(middleware) }
+      def input_output_interceptor
+        # get internal details - capture input before send
+        interceptor = proc { |context| @input = context.input }
+        { interceptors: [Interceptor.new(read_before_transmit: interceptor)] }
       end
 
       def acceptor_matches?(matcher, response, error)

data/lib/hearth/waiters/waiter.rb

@@ -2,9 +2,22 @@
 
 module Hearth
   module Waiters
+    # A super class error that is raised when a waiter detects a condition
+    # where the waiter can never succeed.
+    class WaiterFailed < StandardError; end
+
+    # Raised when the waiter reached an expected failure state.
+    class FailureStateError < WaiterFailed; end
+
+    # Raised when the waiter has reached the maximum waiting time.
+    class MaxWaitTimeExceededError < WaiterFailed; end
+
+    # Raised when the waiter received an unexpected error.
+    class UnexpectedError < WaiterFailed; end
+
     # Abstract waiter class with high level logic for polling and waiting.
+    # @api private
     class Waiter
-      # @api private
       def initialize(options = {})
         unless options[:max_wait_time].is_a?(Integer)
           raise ArgumentError,
@@ -42,11 +55,11 @@ module Hearth
           case state
           when :retry then nil
           when :success then return
-          when :failure then raise Errors::FailureStateError, resp_or_error
-          when :error   then raise Errors::UnexpectedError, resp_or_error
+          when :failure then raise FailureStateError, resp_or_error
+          when :error   then raise UnexpectedError, resp_or_error
           end
 
-          raise Errors::MaxWaitTimeExceeded if @one_more_retry
+          raise MaxWaitTimeExceededError if @one_more_retry
 
           delay = delay(n)
           @remaining_time -= delay

data/lib/hearth/xml/formatter.rb

@@ -45,7 +45,7 @@ module Hearth
       end
 
       def text_node(node, pad)
-        text = node.text.encode(xml: :text)
+        text = escape(node.text, :text)
         "#{pad}<#{node.name}#{attrs(node)}>#{text}</#{node.name}>#{@eol}"
       end
 
@@ -60,9 +60,18 @@ module Hearth
 
       def attrs(node)
         node.attributes.map do |key, value|
-          " #{key}=#{value.to_s.encode(xml: :attr)}"
+          " #{key}=#{escape(value, :attr)}"
         end.join
       end
+
+      def escape(string, text_or_attr)
+        string.to_s
+              .encode(xml: text_or_attr)
+              .gsub("\u{000D}", '&#xD;') # Carriage Return
+              .gsub("\u{000A}", '&#xA;') # Line Feed
+              .gsub("\u{0085}", '&#x85;') # Next Line
+              .gsub("\u{2028}", '&#x2028;') # Line Separator
+      end
     end
   end
 end

data/lib/hearth/xml/node.rb

@@ -9,9 +9,9 @@ module Hearth
       BOTH_TYPES = 'Nodes may not have both text and child nodes'
 
       # @param [String] name
-      def initialize(name, *children)
+      def initialize(name, *children, attributes: {})
         @name = name
-        @attributes = {}
+        @attributes = attributes
         @child_nodes = []
         @child_node_map = {}
         @text = []