This gem implements a simple mechanism to throttle or rate-limit operations in Ruby.

Add this line to your application's Gemfile:

gem 'ruby-limiter', require: 'limiter'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ruby-limiter

To rate limit calling an instance method, a mixin is provided. Simply specify the method to me limited, and the maximum rate that the method can be called. This rate is (by default) a number of requests per minute.

class Widget
  extend Limiter::Mixin

  # limit the rate we can call tick to 300 times per minute
  # when the rate has been exceeded, a call to tick will block until the rate limit would not be exceeded
  limit_method :tick, rate: 300

  ...
end

To specify the rate in terms of an interval shorter (or longer) than 1 minute, an optional interval parameter can be provided to specify the throttling period in seconds.

class Widget
  extend Limiter::Mixin

  # limit the rate we can call tick to 5 times per second
  # when the rate has been exceeded, a call to tick will block until the rate limit would not be exceeded
  limit_method :tick, rate: 5, interval: 1

  ...
end

In cases where the mixin is not appropriate the RateQueue class can be used directly. As in the mixin examples above, the interval parameter is optional (and defaults to 1 minute).

class Widget
  def initialize
    # create a rate-limited queue which allows 10000 operations per hour
    @queue = RateQueue.new(10000, interval: 3600)
  end

  def tick
    # this operation will block until less than 10000 shift calls have been made within the last hour
    @queue.shift
    # do something
  end
end

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/Shopify/limiter.

The gem is available as open source under the terms of the MIT License.