1VMOD_VSTHROTTLE(3) VMOD_VSTHROTTLE(3)
2
6 vmod_vsthrottle - Throttling VMOD
7
9 import vsthrottle [from "path"] ;
10 BOOL is_denied(STRING key, INT limit, DURATION period, DURATION block)
12 INT remaining(STRING key, INT limit, DURATION period, DURATION block)
14 DURATION blocked(STRING key, INT limit, DURATION period, DURATION block)
16
18 A Varnish vmod for rate-limiting traffic on a single Varnish server.
19 Offers a simple interface for throttling traffic on a per-key basis to
20 a specific request rate.
21 Keys can be specified from any VCL string, e.g. based on client.ip, a
23 specific cookie value, an API token, etc.
24 The request rate is specified as the number of requests permitted over
26 a period. To keep things simple, this is passed as two separate parame‐
27 ters, 'limit' and 'period'.
28 If an optional duration 'block' is specified, then access is denied
30 altogether for that period of time after the rate limit is reached.
31 This is a way to entirely turn away a particularly troublesome source
32 of traffic for a while, rather than let them back in as soon as the
33 rate slips back under the threshold.
34 This VMOD implements a token bucket algorithm. State associated with
36 the token bucket for each key is stored in-memory using BSD's red-black
37 tree implementation.
38 Memory usage is around 100 bytes per key tracked.
40 Example:
42 vcl 4.0;
44 import vsthrottle;
45 backend default { .host = "192.0.2.11"; .port = "8080"; }
47 sub vcl_recv {
49 # Varnish will set client.identity for you based on client IP.
50 if (vsthrottle.is_denied(client.identity, 15, 10s, 30s)) {
52 # Client has exceeded 15 reqs per 10s.
53 # When this happens, block altogether for the next 30s.
54 return (synth(429, "Too Many Requests"));
55 }
56 # There is a quota per API key that must be fulfilled.
58 if (vsthrottle.is_denied("apikey:" + req.http.Key, 30, 60s)) {
59 return (synth(429, "Too Many Requests"));
60 }
61 # Only allow a few POST/PUTs per client.
63 if (req.method == "POST" || req.method == "PUT") {
64 if (vsthrottle.is_denied("rw" + client.identity, 2, 10s)) {
65 return (synth(429, "Too Many Requests"));
66 }
67 }
68 }
69 is_denied(...)
71 BOOL is_denied(
72 STRING key,
73 INT limit,
74 DURATION period,
75 DURATION block=0
76 )
77 Arguments:
79 · key: A unique identifier to define what is being throttled - more
81 examples below
82 · limit: How many requests in the specified period
84 · period: The time period
86 · block: a period to deny all access after meeting the threshold
88 Description
90 Can be used to rate limit the traffic for a specific key to a
91 maximum of 'limit' requests per 'period' time. If 'block' is >
92 0s, (0s by default), then always deny for 'key' for that length
93 of time after hitting the threshold. A token bucket is uniquely
94 identified by the 4-tuple of its key, limit, period and block,
95 so using the same key multiple places with different rules will
96 create multiple token buckets.
97 Example
99 sub vcl_recv {
101 if (vsthrottle.is_denied(client.identity, 15, 10s)) {
102 # Client has exceeded 15 reqs per 10s
103 return (synth(429, "Too Many Requests"));
104 }
105 # ...
107 }
108 remaining(...)
110 INT remaining(
111 STRING key,
112 INT limit,
113 DURATION period,
114 DURATION block=0
115 )
116 Arguments:
118 · key: A unique identifier to define what is being throttled
120 · limit: How many requests in the specified period
122 · period: The time period
124 · block: duration to block, defaults to 0s
126 Description
128 Get the current number of tokens for a given token bucket. This can
129 be used to create a response header to inform clients of their cur‐
130 rent quota.
131 Example
133 sub vcl_deliver {
135 set resp.http.X-RateLimit-Remaining = vsthrottle.remaining(client.identity, 15, 10s);
136 }
137 blocked(...)
139 DURATION blocked(
140 STRING key,
141 INT limit,
142 DURATION period,
143 DURATION block
144 )
145 Arguments:
147 · key: A unique identifier to define what is being throttled
149 · limit: How many requests in the specified period
151 · period: The time period
153 · block: duration to block
155 Description
157 If the token bucket identified by the four parameters has been
158 blocked by use of the 'block' parameter in 'is_denied()', then
159 return the time remaining in the block. If it is not blocked, return
160 0s. This can be used to inform clients how long they will be locked
161 out.
162 Example
164 sub vcl_deliver {
166 set resp.http.Retry-After
167 = vsthrottle.blocked(client.identity, 15, 10s, 30s);
168 }
169 VMOD_VSTHROTTLE(3)