hearth 1.0.0.pre1 → 1.0.0.pre3

data/lib/hearth/query/param.rb

@@ -0,0 +1,56 @@
+# 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>, nil] 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)
+          serialize_array(name, value)
+        else
+          serialize(name, value)
+        end
+      end
+
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(Param) &&
+          other.name == name &&
+          other.value == value
+      end
+
+      # @return [Integer]
+      def <=>(other)
+        name <=> other.name
+      end
+
+      private
+
+      def serialize(name, value)
+        value.nil? ? escape(name) : "#{escape(name)}=#{escape(value)}"
+      end
+
+      def serialize_array(name, values)
+        values.map { |v| serialize(name, v) }.join('&')
+      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,31 @@
+# frozen_string_literal: true
+
+require 'rspec/expectations'
+
+# Provides an rspec matcher for CGI.parse to check Float precision.
+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.
+
+        float = Float(a0)
+        expect(float).to eq(e0.to_f)
+      rescue StandardError
+        expect(a0).to eq(e0)
+      end
+    end
+  end
+
+  diffable
+end

data/lib/hearth/refreshing_identity_provider.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 RefreshingIdentityProvider
+    SYNC_EXPIRATION_LENGTH = 300 # 5 minutes
+    ASYNC_EXPIRATION_LENGTH = 600 # 10 minutes
+
+    def initialize
+      @mutex = Mutex.new
+    end
+
+    # @return [Identities::Base]
+    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, StringIO] body (StringIO.new)
+    def initialize(uri: URI(''), body: StringIO.new)
+      @uri = uri
+      @body = body
+    end
+
+    # @return [URI]
+    attr_accessor :uri
+
+    # @return [IO, StringIO]
+    attr_accessor :body
+  end
+end

data/lib/hearth/response.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Hearth
+  # Represents a base response.
+  class Response
+    # @param [IO, StringIO] body (StringIO.new)
+    def initialize(body: StringIO.new)
+      @body = body
+    end
+
+    # @return [IO, StringIO]
+    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
+      # IO does not respond to #truncate but it does respond to #rewind
+      # however it returns an illegal seek error.
+      @body.truncate(0) if @body.respond_to?(:truncate)
+      @body.rewind if @body.respond_to?(:rewind) && !@body.instance_of?(IO)
+      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
+      # @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 = 0
+      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

data/lib/hearth/retry/client_rate_limiter.rb

@@ -0,0 +1,145 @@
+# 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
+            # 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
+
+      def rate_to_use
+        if @enabled
+          [@measured_tx_rate, @fill_rate].min
+        else
+          @measured_tx_rate
+        end
+      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 || 0
+      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
+      # @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 = 0
+      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.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+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
+    # Represents a token that can be used to retry an operation.
+    # @!attribute retry_count
+    #   The number of times the operation has been retried.
+    #   @return [Integer]
+    # @!attribute retry_delay
+    #   The delay before the next retry.
+    #   @return [Numeric]
+    Token = Struct.new(:retry_count, :retry_delay, keyword_init: true) do
+      # @option args [Integer] :retry_count (0)
+      # @option args [Numeric] :retry_delay (0)
+      def initialize(*args)
+        super
+        self.retry_count ||= 0
+        self.retry_delay ||= 0
+      end
+    end
+  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