Prop
A gem to rate limit requests/actions of any kind.
Define thresholds, register usage and finally act on exceptions once thresholds get exceeded.
Prop supports two limiting strategies:
- Basic strategy (default): Prop will use an interval to define a window of time using simple div arithmetic. This means that it's a worst-case throttle that will allow up to two times the specified requests within the specified interval.
- Leaky bucket strategy: Prop also supports the Leaky Bucket algorithm, which is similar to the basic strategy but also supports bursts up to a specified threshold.
To store values, prop needs a cache:
# config/initializers/prop.rb
Prop.cache = Rails.cache # needs read/write/increment methods
When using the interval strategy, prop sets a key expiry to its interval. Because the leaky bucket strategy does not set a ttl, it is best to use memcached or similar for all prop caching, not redis.
Setting a Callback
You can define an optional callback that is invoked when a rate limit is reached. In a Rails application you could use such a handler to add notification support:
Prop.before_throttle do |handle, key, threshold, interval|
ActiveSupport::Notifications.instrument('throttle.prop', handle: handle, key: key, threshold: threshold, interval: interval)
end
Defining thresholds
Example: Limit on accepted emails per hour from a given user, by defining a threshold and interval (in seconds):
Prop.configure(:mails_per_hour, threshold: 100, interval: 1.hour, description: "Mail rate limit exceeded")
# Block requests by setting threshold to 0
Prop.configure(:mails_per_hour, threshold: 0, interval: 1.hour, description: "All mail is blocked")
# Throws Prop::RateLimited if the threshold/interval has been reached
Prop.throttle!(:mails_per_hour)
# Prop can be used to guard a block of code
Prop.throttle!(:expensive_request) { calculator.something_very_hard }
# Returns true if the threshold/interval has been reached
Prop.throttled?(:mails_per_hour)
# Sets the throttle count to 0
Prop.reset(:mails_per_hour)
# Returns the value of this throttle, usually a count, but see below for more
Prop.count(:mails_per_hour)
Prop will raise a KeyError
if you attempt to operate on an undefined handle.
Scoping a throttle
Example: scope the throttling to a specific sender rather than running a global "mails per hour" throttle:
Prop.throttle!(:mails_per_hour, mail.from)
Prop.throttled?(:mails_per_hour, mail.from)
Prop.reset(:mails_per_hour, mail.from)
Prop.query(:mails_per_hour, mail.from)
The throttle scope can also be an array of values:
Prop.throttle!(:mails_per_hour, [ account.id, mail.from ])
Error handling
If the threshold for a given handle and key combination is exceeded, Prop throws a Prop::RateLimited
.
This exception contains a "handle" reference and a "description" if specified during the configuration.
The handle allows you to rescue Prop::RateLimited
and differentiate action depending on the handle.
For example, in Rails you can use this in e.g. ApplicationController
:
rescue_from Prop::RateLimited do |e|
if e.handle == :authorization_attempt
render status: :forbidden, message: I18n.t(e.description)
elsif ...
end
end
Using the Middleware
Prop ships with a built-in Rack middleware that you can use to do all the exception handling.
When a Prop::RateLimited
error is caught, it will build an HTTP
429 Too Many Requests
response and set the following headers:
Retry-After: 32
Content-Type: text/plain
Content-Length: 72
Where Retry-After
is the number of seconds the client has to wait before retrying this end point.
The body of this response is whatever description Prop has configured for the throttle that got violated,
or a default string if there's none configured.
If you wish to do manual error messaging in these cases, you can define an error handler in your Prop configuration.
Here's how the default error handler looks - you use anything that responds to .call
and
takes the environment and a RateLimited
instance as argument:
error_handler = Proc.new do |env, error|
body = error.description || "This action has been rate limited"
headers = { "Content-Type" => "text/plain", "Content-Length" => body.size, "Retry-After" => error.retry_after }
[ 429, headers, [ body ]]
end
ActionController::Dispatcher.middleware.insert_before(ActionController::ParamsParser, error_handler: error_handler)
An alternative to this, is to extend Prop::Middleware
and override the render_response(env, error)
method.
Disabling Prop
In case you need to perform e.g. a manual bulk operation:
Prop.disabled do
# No throttles will be tested here
end
Overriding threshold
You can chose to override the threshold for a given key:
Prop.throttle!(:mails_per_hour, mail.from, threshold: current_account.mail_throttle_threshold)
When throttle
is invoked without argument, the key is nil and as such a scope of its own, i.e. these are equivalent:
Prop.throttle!(:mails_per_hour)
Prop.throttle!(:mails_per_hour, nil)
The default (and smallest possible) increment is 1, you can set that to any integer value using
:increment
which is handy for building time based throttles:
Prop.configure(:execute_time, threshold: 10, interval: 1.minute)
Prop.throttle!(:execute_time, account.id, increment: (Benchmark.realtime { execute }).to_i)
Decrement can be used to for example throttle before an expensive action and then give quota back when some condition is met.
Prop.throttle!(:api_counts, request.remote_ip, decrement: 1)
Optional configuration
You can add optional configuration to a prop and retrieve it using Prop.configurations[:foo]
:
Prop.configure(:api_query, threshold: 10, interval: 1.minute, category: :api)
Prop.configure(:api_insert, threshold: 50, interval: 1.minute, category: :api)
Prop.configure(:password_failure, threshold: 5, interval: 1.minute, category: :auth)
Prop.configurations[:api_query][:category]
You can use Prop::RateLimited#config
to distinguish between errors:
rescue Prop::RateLimited => e
case e.config[:category]
when :api
raise APIRateLimit
when :auth
raise AuthFailure
...
end
First throttled
You can opt to be notified when the throttle is breached for the first time.
This can be used to send notifications on breaches but prevent spam on multiple throttle breaches.
Prop.configure(:mails_per_hour, threshold: 100, interval: 1.hour, first_throttled: true)
throttled = Prop.throttle(:mails_per_hour, user.id, increment: 60)
if throttled
if throttled == :first_throttled
ApplicationMailer.spammer_warning(user).deliver_now
end
Rails.logger.warn("Not sending emails")
else
send_emails
end
# return values of throttle are: false, :first_throttled, true
Prop.first_throttled(:mails_per_hour, 1, increment: 60) # -> false
Prop.first_throttled(:mails_per_hour, 1, increment: 60) # -> :first_throttled
Prop.first_throttled(:mails_per_hour, 1, increment: 60) # -> true
# can also be accesses on `Prop::RateLimited` exceptions as `.first_throttled`
Using Leaky Bucket Algorithm
You can add two additional configurations: :strategy
and :burst_rate
to use the
leaky bucket algorithm.
Prop will handle the details after configured, and you don't have to specify :strategy
again when using throttle
, throttle!
or any other methods.
The leaky bucket algorithm used is "leaky bucket as a meter".
Prop.configure(:api_request, strategy: :leaky_bucket, burst_rate: 20, threshold: 5, interval: 1.minute)
:threshold
value here would be the "leak rate" of leaky bucket algorithm.
License
Copyright 2015 Zendesk
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.