| VMOD_VSTHROTTLE(3) | VMOD_VSTHROTTLE(3) |
vmod_vsthrottle - Throttling VMOD
import vsthrottle [as name] [from "path"] BOOL is_denied(STRING key, INT limit, DURATION period, DURATION block) VOID return_token(STRING key, INT limit, DURATION period, DURATION block) INT remaining(STRING key, INT limit, DURATION period, DURATION block) DURATION blocked(STRING key, INT limit, DURATION period, DURATION block)
A Varnish vmod for rate-limiting traffic on a single Varnish server. Offers a simple interface for throttling traffic on a per-key basis to a specific request rate.
Keys can be specified from any VCL string, e.g. based on client.ip, a specific cookie value, an API token, etc.
The request rate is specified as the number of requests permitted over a period. To keep things simple, this is passed as two separate parameters, 'limit' and 'period'.
If an optional duration 'block' is specified, then access is denied altogether for that period of time after the rate limit is reached. This is a way to entirely turn away a particularly troublesome source of traffic for a while, rather than let them back in as soon as the rate slips back under the threshold.
This VMOD implements a token bucket algorithm. State associated with the token bucket for each key is stored in-memory using BSD's red-black tree implementation.
Memory usage is around 100 bytes per key tracked.
Example:
vcl 4.0;
import vsthrottle;
backend default { .host = "192.0.2.11"; .port = "8080"; }
sub vcl_recv {
# Varnish will set client.identity for you based on client IP.
if (vsthrottle.is_denied(client.identity, 15, 10s, 30s)) {
# Client has exceeded 15 reqs per 10s.
# When this happens, block altogether for the next 30s.
return (synth(429, "Too Many Requests"));
}
# There is a quota per API key that must be fulfilled.
if (vsthrottle.is_denied("apikey:" + req.http.Key, 30, 60s)) {
return (synth(429, "Too Many Requests"));
}
# Only allow a few POST/PUTs per client.
if (req.method == "POST" || req.method == "PUT") {
if (vsthrottle.is_denied("rw" + client.identity, 2, 10s)) {
return (synth(429, "Too Many Requests"));
}
}
}
BOOL is_denied(
STRING key,
INT limit,
DURATION period,
DURATION block=0 )
Arguments:
Note: A token bucket is uniquely identified by the 4-tuple of its key, limit, period and block, so using the same key multiple places with different rules will create multiple token buckets.
sub vcl_recv {
if (vsthrottle.is_denied(client.identity, 15, 10s)) {
# Client has exceeded 15 reqs per 10s
return (synth(429, "Too Many Requests"));
}
# ...
}
VOID return_token(
STRING key,
INT limit,
DURATION period,
DURATION block=0 )
Note: This function doesn't enforce anything, it merely credits a token to appropriate bucket.
Warning: If streaming is enabled (beresp.do_stream = true) as it is by default now, vcl_deliver() is called before the response is sent to the client (who may download it slowly). Thus you may credit the token back too early if you use return_token() in vcl_backend_response().
sub vcl_recv {
if (vsthrottle.is_denied(client.identity, 20, 20s)) {
# Client has more than 20 concurrent requests
return (synth(429, "Too Many Requests In Flight"));
}
# ...
}
sub vcl_deliver {
vsthrottle.return_token(client.identity, 10, 10s);
}
INT remaining(
STRING key,
INT limit,
DURATION period,
DURATION block=0 )
Description
sub vcl_deliver {
set resp.http.X-RateLimit-Remaining = vsthrottle.remaining(client.identity, 15, 10s);
}
DURATION blocked(
STRING key,
INT limit,
DURATION period,
DURATION block )
Description
sub vcl_deliver {
set resp.http.Retry-After
= vsthrottle.blocked(client.identity, 15, 10s, 30s);
}