A Ruby library for limiting the number of times a method can be invoked within a specified time period.

The rate-limiting is simple if somewhat naïve. Throttled methods are blocked using sleep.

You might wish to use this library to throttle code that:

• Accesses a 3rd-party API that imposes a maximum rate-limit.

• Scrapes data from any website where rapid repeated access is banned.

For example, EchoNest API requests need to be limited to 120 every minute.

sudo gem install glutton_ratelimit

The gem is hosted at: rubygems.org/gems/glutton_ratelimit

There are two types of rate limiting provided by this library:

• Average Throttle Limiting (GluttonRatelimit::AveragedThrottle) DEFAULT

• Bursty Token Bucket Limiting (GluttonRatelimit::BurstyTokenBucket)

If executions are limited to n times per m seconds then:

1. The first execution will occur immediately.

2. Before each of the remaining n-1 executions the process will attempt to sleep so that the executions are evenly spaced within the m second time period.

3. The process is repeated.

The amount of time slept before each execution will depend on the time period m and the average elapsed time of each execution.

If executions are limited to n times per m seconds then:

1. n executions will be allowed immediately.

2. Before the next execution the process will sleep for the remainder of the m second time period.

3. The process is repeated.

The amount of time slept in step 2 will depend on how long the n executions took in step 1.

The rate_limit method can be used at the end of a class definition to limit specific instance methods.

rate_limit :name_of_instance_method, number_of_executions, timeframe_in_seconds

The specified instance method will be throlled to maintain an execution rate of:

timeframe_in_seconds / number_of_executions

class RateLimitTest
  # The class must be extended to permit limiting.
  extend GluttonRatelimit

  def initialize
    @start = Time.now
  end

  def limit_me
    puts "#{Time.now - @start}"
  end

  # Throttle the limit_me method to five executions every sixty seconds.
  rate_limit :limit_me, 5, 60
end

t = RateLimitTest.new

10.times { t.limit_me }

When using the rate_limit method the limiting defaults to GluttonRatelimit::AveragedThrottle. Token Bucket limiting can also be specified:

rate_limite :limit_me, 5, 60, GluttonRatelimit::BurstyTokenBucket

Chunks of code can also be manually throttled using the times method of a specific GluttonRatelimit object.

# Maximum of twelve executions every five seconds.
rl = GluttonRatelimit::BurstyTokenBucket.new 12, 5
# BurstyTokenBucket will allow for a full burst of executions followed by a pause.

rl.times(25) do
  # Simulating a constant-time task:
  sleep 0.1
end

# Maximum of six executions every six seconds.
rl = GluttonRatelimit::AveragedThrottle.new 6, 6
# AverageThrottle will attempt to evenly space executions within the allowed period.

rl.times(13) do
  # Simulating a 0 to 1 second random-time task:
  sleep rand
end

More examples can be found within the examples folder.

Before using the library you should be aware of the following warnings.

The inaccuracy of Ruby’s sleep method may cause timing issues with the AveragedThrottle limiting. Specifically, the limiting accuracy may be slightly-off when trying to rate-limit quick methods (sub-millisecond tasks).

See: codeidol.com/other/rubyckbk/Date-and-Time/Waiting-a-Certain-Amount-of-Time

It is recommend that you use the BurstyTokenBucket limiting when throttling very short tasks.

As mentioned above, throttling is accomplish by blocking script execution using sleep. There is no support for dropping or queuing throttled method invocations.

This library is not thread safe.

The tests integration/timing tests with a tolerance of 0.5 of a percent outside the expected timings.

The tests can be run using: ‘bundle exec rake test`

Some of the algorithms were inspired by these discussions:

• stackoverflow.com/questions/667508/whats-a-good-rate-limiting-algorithm

• stackoverflow.com/questions/1407113/throttling-method-calls-to-m-requests-in-n-seconds

This is free and unencumbered software released into the public domain. See LICENSE for details.