ratelimit.check_rates
BOOLratelimit.check_ratesSTRINGentryIDrc1INTEGERdelta1INTEGERwindow1INTEGERlimit1IDrc2INTEGERdelta2INTEGERwindow2INTEGERlimit2IDpbTIMEttl
Available inall subroutines.
Increment the same entry in two distinct ratecounters, each with different windowing and limit parameters, as well as check if the client has exceeded some average number of requests per second (RPS) for either ratecounter.
The lowest rate limit supported by this feature to demonstrate effective behavior is 10 RPS. Using a limit below 10 RPS may result in unpredictable accuracy and detection time.
Parameters
entry
- The entry to keep track of. Typically client.ip
and any associated
metadata. An entry can be, at maximum, 256 bytes long.
rc1
- The first ratecounter that tracks requests. When a user makes a
request, a ratecounter tracks that users average rate of requests over time.
delta1
- The integer value to increment the entry in the rate counter by.
Typically, a value of 1 is used. The value must be between 0 and 100000.
window1
- The last N seconds of data to compute the requests-per-second over.
Must be 1, 10, or 60.
limit1
- The RPS limit. If the user goes above this limit, over the given
window, then they are penalized and their entry is put into the penalty box
pb
. Must be between 10 and 70000000.
rc2
- The second ratecounter that tracks requests.
delta2
- The integer value to increment the entry in the rate counter by.
Typically, a value of 1 is used. The value must be between 0 and 100000.
window2
- The last N seconds of data to compute the requests-per-second over.
Must be 1, 10, or 60.
limit2
- The RPS limit. If the user goes above this limit, over the given
window, then they are penalized and their entry is put into the penalty box
pb
. Must be between 10 and 70000000.
pb
- The penalty box. Keeps track of penalized users. If a user is penalized,
their entry is put into this penalty box.
ttl
- The penalty box TTL. Specifies how long a user remains penalized. Must
be between 1m and 1h, and has minute granularity (rounded to the nearest
minute).
Return value
Upon completion, this function returns true
if the user is penalized (i.e.
should be rate limited), or false
if not.
In the event an error occurs, the default return value is false
; therefore
errors (via fastly.error
) must be handled specifically.
Errors
If the given entry
is longer than 256 bytes, then false
is returned, and
fastly.error
is set to EINVAL
.
Example
The following example will immediately halt and return a 429 to the client if they exceed a rate of 1000 requests per second over the last 60 seconds, OR a rate of 150 requests over the last 1 second. The user will be penalized for 20 minutes afterword:
penaltybox pbox { }ratecounter rc1 { }ratecounter rc2 { }
sub vcl_recv { if (ratelimit.check_rates(client.ip, rc1, 1, 60, 1000, rc2, 1, 1, 150, pbox, 20m)) { error 429 "Too many requests"; }}
Try it out
ratelimit.check_rates
is used in the following code examples. Examples apply VCL to real-world use cases and can be deployed as they are, or adapted for your own service. See the full list of code examples for more inspiration.
Click RUN on a sample below to provision a Fastly service, execute the code on Fastly, and see how the function behaves.
Rate limit requests
Use ratecounters and penalty boxes to stop high-volume automated attacks against your website.