r4r 0.1.0

data/ext/r4r/system_clock_ext/extconf.rb

@@ -0,0 +1,8 @@
+require "mkmf"
+
+$CFLAGS = "-O2 -Wall -std=c99"
+
+extension_name = 'system_clock_ext'
+dir_config(extension_name)
+create_makefile "#{extension_name}"
+

data/ext/r4r/system_clock_ext/system_clock_ext.c

@@ -0,0 +1,31 @@
+#include <ruby.h>
+#include <sys/time.h>
+
+/**
+ * Returns current system time in milliseconds.
+ */
+static VALUE
+system_clock_call(VALUE self) {
+  struct timeval tv;
+  long long millis;
+
+  gettimeofday(&tv, NULL);
+
+  millis = ((long long)tv.tv_sec) * 1000;
+  millis = millis + (tv.tv_usec / 1000);
+
+  return LONG2NUM(millis);
+}
+
+/**
+ * Module entry point.
+ */
+void
+Init_system_clock_ext() {
+  VALUE mR4r;
+  VALUE cSystemClock;
+
+  mR4r = rb_define_module("R4r");
+  cSystemClock = rb_define_class_under(mR4r, "SystemClockExt", rb_cObject);
+  rb_define_method(cSystemClock, "call", system_clock_call, 0);
+}

data/lib/r4r.rb

@@ -0,0 +1,17 @@
+require "r4r/version"
+
+require "r4r/system_clock_ext"
+require "r4r/clock"
+
+require "r4r/ring_bits_ext"
+require "r4r/ring_bits"
+
+require "r4r/windowed_adder"
+require "r4r/token_bucket"
+
+require "r4r/retry_budget"
+require "r4r/retry_policy"
+require "r4r/retry"
+
+module R4r
+end

data/lib/r4r/clock.rb

@@ -0,0 +1,40 @@
+module R4r
+  # A system clock
+  #
+  # @abstract
+  class Clock
+    # Returns current system time in milliseconds
+    def call
+      raise NotImplementedError
+    end
+  end
+
+  # A frozen clock for testing
+  class FrozenClock < Clock
+    # Creates a new instance of frozen clock.
+    #
+    # @param [R4r::Clock] parent an initial time clock
+    def initialize(parent: nil)
+      @time = (parent || R4r.clock).call
+    end
+
+    # @see R4r::Clock#call
+    def call
+      @time
+    end
+
+    # Increase clock time by given seconds.
+    #
+    # @param [Fixnum] seconds a number of seconds to increase time
+    def advance(seconds:)
+      @time += (seconds.to_i * 1_000)
+    end
+  end
+
+  @@clock = R4r::SystemClockExt.new
+
+  # Default {R4r::Clock} instance.
+  def self.clock
+    @@clock
+  end
+end

data/lib/r4r/retry.rb

@@ -0,0 +1,136 @@
+module R4r
+
+  # An error raises when retry was failed.
+  #
+  class NonRetriableError < RuntimeError
+    attr_reader :cause
+
+    # @param [String] message an error message
+    # @param [Exception] cause a error cause
+    def initialize(message:, cause:)
+      super(message)
+      @cause = cause
+    end
+  end
+
+  # Decorator that wrap blocks and call it within retries.
+  #
+  # @attr [Array[Float]] backoff
+  # @attr [R4r::RetryBudget] budget
+  #
+  # @example constant backoff, it will never pause between retries and will try 3 times.
+  #   retry = R4r::Retry.constant_backoff(num_retries: 3)
+  #   retry.call { get_http_request }
+  #
+  # @example exponential backoff, it will pause between invocations using given backoff invtervals and will try 4 times
+  #   retry = R4r::Retry.backoff(backoff: [0.1, 0.3, 1, 5])
+  #   retry.call { get_http_request }
+  #
+  class Retry
+
+    attr_reader :backoff
+    attr_reader :budget
+
+    # Creates a new retries dectorator.
+    #
+    # @param [Array[Float]] backoff an array with backoff intervals (in seconds)
+    # @param [R4r::RetryPolicy] policy a policy used for error filtiring
+    # @param [R4r::RetryBudget] budget a retry budget
+    #
+    # @raise [ArgumentError] when backoff is empty
+    # @raise [ArgumentError] when backoff has negative values
+    def initialize(backoff:, policy: nil, budget: nil)
+      @policy = (policy || R4r::RetryPolicy.always)
+      @backoff = Array.new(backoff).map { |i| i.to_f }
+      @budget = budget != nil ? budget : R4r::RetryBudget.create
+
+      raise ArgumentError, "backoff cannot be empty" if @backoff.empty?
+      raise ArgumentError, "backoff values cannot be negative" unless @backoff.all? {|i| i.to_f >= 0.0 }
+    end
+
+    # Decorates a given block within retries.
+    #
+    # @return [Proc]
+    def decorate(&block)
+      ->() { call { yield } }
+    end
+
+    # Calls given block within retries.
+    #
+    # @raise [NonRetriableError]
+    def call(&block)
+      return unless block_given?
+
+      num_retry = 0
+      @budget.deposit
+
+      while num_retry < @backoff.size
+
+        begin
+          return yield(num_retry)
+        rescue => err
+          raise err if err.is_a?(NonRetriableError)
+
+          if (num_retry + 1 == @backoff.size)
+            raise NonRetriableError.new(message: "Retry limit [#{@backoff.size}] reached: #{err}", cause: err)
+          end
+
+          unless @policy.call(error: err, num_retry: num_retry)
+            raise NonRetriableError.new(message: "An error was rejected by policy: #{err}", cause: err)
+          end
+
+          unless @budget.try_withdraw
+            raise NonRetriableError.new(message: "Budget was exhausted: #{err}", cause: err)
+          end
+        end
+
+        sleep @backoff[num_retry]
+        num_retry += 1
+      end
+    end
+
+    # Creates a {R4r::Retry} with fixed backoff rates.
+    #
+    # @param [R4r::RetryPolicy] policy a policy used for error filtiring
+    # @param [R4r::RetryBudget] budget a retry budget
+    # @return [R4r::Retry]
+    #
+    # @raise [ArgumentError] when num_retries is negative
+    # @raise [ArgumentError] when backoff is negative
+    #
+    # @example without sleep between invocations
+    #   R4r::Retry.constant_backoff(num_retries:3)
+    #
+    # @example with sleep 1s between invocations
+    #   R4r::Retry.constant_backoff(num_retries: 3, backoff: 1)
+    def self.constant_backoff(num_retries:, backoff: 0.0, policy: nil, budget: nil)
+      raise ArgumentError, "num_retries cannot be negative" unless num_retries.to_i >= 0
+      raise ArgumentError, "backoff cannot be negative" unless backoff.to_f >= 0.0
+
+      backoff = Array.new(num_retries.to_i) { backoff.to_f }
+      R4r::Retry.new(backoff: backoff, policy: policy, budget: budget)
+    end
+
+    # Creates a {R4r::Retry} with backoff intervals.
+    #
+    # @param [Array[Float]] backoff a list of sleep intervals (in seconds)
+    # @param [R4r::RetryPolicy] policy a policy used for error filtiring
+    # @param [R4r::RetryBudget] budget a retry budget
+    # @return [R4r::Retry]
+    #
+    # @raise [ArgumentError] when backoff is nil
+    # @raise [ArgumentError] when backoff isn't array
+    # @raise [ArgumentError] when backoff has negative values
+    #
+    # @example exponential backoff between invocations
+    #   R4r::Retry.backoff(backoff: [0.1, 0.5, 1, 3])
+    def self.backoff(backoff:, policy: nil, budget: nil)
+      raise ArgumentError, "backoff cannot be nil" if backoff.nil?
+      raise ArgumentError, "backoff must be an array" unless backoff.is_a?(Array)
+      raise ArgumentError, "backoff values cannot be negative" unless backoff.all? {|i| i.to_f >= 0.0 }
+
+      R4r::Retry.new(backoff: backoff, policy: policy, budget: budget)
+    end
+
+  end
+end

data/lib/r4r/retry_budget.rb

@@ -0,0 +1,150 @@
+module R4r
+  # Represents a budget for retrying requests.
+  #
+  # A retry budget is useful for attenuating the amplifying effects
+  # of many clients within a process retrying requests multiple
+  # times. This acts as a form of coordination between those retries.
+  #
+  # A Ruby port of the finagle's RetryBudget.
+  #
+  # @abstract
+  # @see https://github.com/twitter/finagle/blob/master/finagle-core/src/main/scala/com/twitter/finagle/service/RetryBudget.scala
+  class RetryBudget
+
+    # Indicates a deposit, or credit, which will typically
+    # permit future withdrawals.
+    def deposit
+      raise NotImplementedError
+    end
+
+    # Check whether or not there is enough balance remaining
+    # to issue a retry, or make a withdrawal.
+    #
+    # @return [Boolean]
+    #   `true`, if the retry is allowed and a withdrawal will take place.
+    #   `false`, the balance should remain untouched.
+    def try_withdraw
+      raise NotImplementedError
+    end
+
+    # The balance or number of retries that can be made now.
+    def balance
+      raise NotImplementedError
+    end
+
+    # Creates a {R4r::RetryBudget} that allows for about `percent_can_retry` percent
+    # of the total {R4r::RetryBudget#deposit} requests to be retried.
+    #
+    # @param [Fixnum] ttl_ms deposits created by {R4r::RetryBudget#deposit} expire after
+    #   approximately `ttl_ms` time has passed. Must be `>= 1 second`
+    #   and `<= 60 seconds`.
+    # @param [Fixnum] min_retries_per_second the minimum rate of retries allowed in order to
+    #   accommodate clients that have just started issuing requests as well as clients
+    #   that do not issue many requests per window.
+    #   Must be non-negative and if `0`, then no reserve is given.
+    # @param [Float] percent_can_retry the percentage of calls to `deposit()` that can be
+    #   retried. This is in addition to any retries allowed for via `min_retries_per_second`.
+    #   Must be >= 0 and <= 1000. As an example, if `0.1` is used, then for every
+    #   10 calls to `deposit()`, 1 retry will be allowed. If `2.0` is used then every
+    #   `deposit` allows for 2 retries.
+    # @param [R4r::Clock] clock the current time for testing
+    #
+    # @raise [ArgumentError]
+    def self.create(ttl_ms: nil, min_retries_per_second: nil, percent_can_retry: nil, clock: nil)
+      ttl_ms = (ttl_ms || R4r::TokenRetryBudget::DEFAULT_TTL_MS).to_i
+      min_retries_per_second = (min_retries_per_second || 10).to_i
+      percent_can_retry = (percent_can_retry.to_f || 0.2).to_f
+
+      unless ttl_ms >= 0 && ttl_ms <= 60 * 1000
+        raise ArgumentError, "ttl_ms must be in [1.second, 60.seconds], got #{ttl_ms}"
+      end
+      unless min_retries_per_second >= 0
+        raise ArgumentError, "min_retries_per_second cannot be nagative, got #{min_retries_per_second}"
+      end
+      unless percent_can_retry >= 0.0
+        raise ArgumentError, "percent_can_retry cannot be negative, got #{percent_can_retry}"
+      end
+      unless percent_can_retry <= R4r::TokenRetryBudget::SCALE_FACTOR
+        raise ArgumentError, "percent_can_retry cannot be greater then #{R4r::TokenRetryBudget::SCALE_FACTOR}, got #{percent_can_retry}"
+      end
+
+      if min_retries_per_second == 0 && percent_can_retry == 0.0
+        return R4r::RetryBudget.empty
+      end
+
+      deposit_amount = percent_can_retry == 0.0 ? 0 : R4r::TokenRetryBudget::SCALE_FACTOR.to_i
+      withdrawal_amount = percent_can_retry == 0.0 ? 1 : (R4r::TokenRetryBudget::SCALE_FACTOR / percent_can_retry).to_i
+      reserve = min_retries_per_second * (ttl_ms / 1000) * withdrawal_amount
+      bucket = R4r::LeakyTokenBucket.new(ttl_ms: ttl_ms, reserve: reserve, clock: clock)
+      R4r::TokenRetryBudget.new(bucket: bucket, deposit_amount: deposit_amount, withdrawal_amount: withdrawal_amount)
+    end
+
+    # Creates an empty retry budget.
+    def self.empty
+      EmptyRetryBudget.new
+    end
+
+    # Creates an infinite retry budget.
+    def self.infinite
+      InfiniteRetryBudget.new
+    end
+  end
+
+  # A {R4r::RetryBudget} that never has a balance,
+  # and as such, will never allow a retry.
+  class EmptyRetryBudget < RetryBudget
+    def deposit ; end
+    def try_withdraw ; false ; end
+    def balance ; 0 ; end
+  end
+
+  # A {R4r::RetryBudget} that always has a balance of `100`,
+  # and as such, will always allow a retry.
+  class InfiniteRetryBudget < RetryBudget
+    def deposit ; end
+    def try_withdraw ; true end
+    def balance ; 100 end
+  end
+
+  class TokenRetryBudget < RetryBudget
+    # This scaling factor allows for `percent_can_retry` > 1 without
+    # having to use floating points (as the underlying mechanism
+    # here is a {R4r::TokenBucket} which is not floating point based).
+    SCALE_FACTOR = 1000.0
+    DEFAULT_TTL_MS = 60 * 1000
+
+    # Creates a new {R4r::TokenRetryBudget}.
+    #
+    # @param [R4r::TokenBucket] bucket
+    # @param [Fixnum] deposit_amount
+    # @param [Fixnum] withdrawal_amount
+    def initialize(bucket:, deposit_amount:, withdrawal_amount:)
+      raise ArgumentError, "bucket cannot be nil" if bucket.nil?
+      raise ArgumentError, "deposit_amount cannot be nil" if deposit_amount.nil?
+      raise ArgumentError, "withdrawal_amount cannot be nil" if withdrawal_amount.nil?
+
+      @bucket = bucket
+      @deposit_amount = deposit_amount.to_i
+      @withdrawal_amount = withdrawal_amount.to_i
+    end
+
+    # @see R4r::RetryBudget#deposit
+    def deposit
+      @bucket.put(@deposit_amount)
+    end
+
+    # @see R4r::RetryBudget#try_withdraw
+    def try_withdraw
+      @bucket.try_get(@withdrawal_amount)
+    end
+
+    # @see R4r::RetryBudget#balance
+    def balance
+      @bucket.count / @withdrawal_amount
+    end
+
+    def to_s
+      "R4r::TokenRetryBudget{deposit=#{@deposit_amount}, withdrawal=#{@withdrawal_amount}, balance=#{balance}}"
+    end
+  end
+end

data/lib/r4r/retry_policy.rb

@@ -0,0 +1,55 @@
+module R4r
+
+  # Pluggable retry strategy.
+  #
+  # @abstract
+  class RetryPolicy
+    # Check that given error can be retried or not.
+    #
+    # @param [Exception] error an error was occured
+    # @param [Fixnum] num_retry a number of current retry, started from zero
+    #
+    # @return [Boolean] true if retry can be recovered
+    def call(error:, num_retry:)
+      raise NotImplementedError
+    end
+
+    # Creates a policy that always recover from any kind of errors.
+    #
+    # @return [R4r::RetryPolicy]
+    def self.always
+      ->(error:, num_retry:) { true }
+    end
+
+    # Creates a policy that never recover from any kind of errors.
+    #
+    # @return [R4r::RetryPolicy]
+    def self.never
+      ->(error:, num_retry:) { false }
+    end
+
+    # Creates a policy that recover from specified kind of errors
+    #
+    # @example
+    #   R4r::RetryPolicy.instance_of(Some::Error, Service::Error)
+    #
+    # @return [R4r::RetryPolicy]
+    def self.instance_of(*klass)
+      R4r::InstanceOfRetryPolicy.new(klass: klass)
+    end
+  end
+
+  # A retry policy that catch specified kind of errors
+  class InstanceOfRetryPolicy < RetryPolicy
+    # @param [Array[Class]] klass an error classes list that used for filtering
+    def initialize(klass:)
+      @klass = klass
+    end
+
+    # @return [Boolean]
+    # @see R4r::RetryPolicy#call
+    def call(error:, num_retry:)
+      @klass.any? { |kind| error.is_a?(kind) }
+    end
+  end
+end

data/lib/r4r/ring_bits.rb

@@ -0,0 +1,59 @@
+module R4r ; class RingBits
+  attr_reader :index, :length, :cardinality
+
+  # Creates a ring bit set whose size is large enough to explicitly
+  # represent bits with indices in the range 0 through
+  # size-1. All bits are initially set to false.
+  #
+  # @param [Fixnum] size the size of ring bits buffer
+  # @raise [ArgumentError] if the specified size is negitive
+  def initialize(size:, bit_set_class: nil)
+    @size = size
+    @bit_set = (bit_set_class || RingBitsExt).new(size.to_i)
+    @is_full = false
+    @index = -1
+    @length = 0
+    @cardinality = 0
+  end
+
+  # Current ring bits buffer size.
+  def size
+    @size
+  end
+
+  # An actual ring bits buffer capacity.
+  def bit_set_size
+    @bit_set.size
+  end
+
+  # Sets the bit at the next index to the specified value.
+  #
+  # @param [Boolean] value is a boolean value to set
+  # @return [Fixnum] the number of bits set to true
+  def set_next(value)
+    increase_length
+
+    new_index = (@index + 1) % @size
+    previous = @bit_set.set(new_index, value == true) ? 1 : 0
+    current = value == true ? 1 : 0
+
+
+    @index = new_index
+    @cardinality = @cardinality - previous + current
+  end
+
+  private
+
+  def increase_length
+    return if @is_full
+
+    next_length = @length + 1
+    if (next_length < @size)
+      @length = next_length
+    else
+      @length = size
+      @is_full = true
+    end
+  end
+
+end ; end