This gem implements a simple mechanism to throttle or rate-limit operations in Ruby.
Add this line to your application's Gemfile:
And then execute:
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 be 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 # and the provided block will be executed limit_method(:tick, rate: 5, interval: 1) do puts 'Limit reached' end ... end
By default all calls to the
limit_method will be bursted, e.g. as quick as possible, until the rate is exceeded.
Then we wait for the remainder of the interval to continue. To even out the burst, an optional
balanced parameter can be
provided to enable interleaving between the method calls, e.g:
interleave = interval / size.
... limit_method :tick, rate: 60, balanced: true ...
For example: with an interval of 60 seconds and a rate of 60:
: As quickly as possible we call the method 60 times, then we wait for the remainder of the time.
: We interleave each call with 1 second so we call this method every second.
In cases where the mixin is not appropriate the
RateQueue class can be used directly. As in the mixin examples above,
interval parameter is optional (and defaults to 1 minute). It is also possible
to provide the block to
RateQueue, which will be executed on each limit hit (useful for metrics).
class Widget def initialize # create a rate-limited queue which allows 10000 operations per hour @queue = Limiter::RateQueue.new(10000, interval: 3600) do puts "Hit the limit, waiting" end 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.