vmod_vsthrottle(3)

💖 vmod_vsthrottle — Throttling VMOD 💖

okay bestie, this is vmod_vsthrottle(3) from the Library Functions Manual, and it's literally the girl who keeps the line at the door. rate-limiting, but make it cute. ✨

---

🌸 SYNOPSIS 🌸

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)

VOID remove_bucket(STRING key, INT limit, DURATION period, DURATION block)

---

🦋 DESCRIPTION 🦋

So this is a Varnish vmod for rate-limiting traffic on a single Varnish server. it gives you a super simple interface for throttling traffic on a per-key basis to a specific request rate. no cap. 💅

Keys can be any VCL string you want, like based on client.ip, a specific cookie value, an API token, whatever. you pick. 🎀

The request rate is expressed as the number of requests permitted over a period. and because we keep things simple around here, that's passed as two separate parameters: limit and period. periodt.

If you pass an optional duration block, then access gets denied altogether for that stretch of time after the rate limit is hit. it's the move for entirely turning away a particularly troublesome source of traffic for a while, instead of letting them waltz back in the second the rate slips back under the threshold. bye bestie 👋

This VMOD implements a token bucket algorithm <http://en.wikipedia.org/wiki/Token_bucket>. the state for each key's token bucket lives in memory using BSD's red-black tree implementation. 🌳

Memory usage is around 100 bytes per key tracked. so cute, so cheap.

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)

BOOL is_denied(
   STRING key,
   INT limit,
   DURATION period,
   DURATION block=0
)

Arguments:

• key: a unique identifier to define what's being throttled — more examples below 💫
• limit: how many requests in the specified period
• period: the time period
• block: a period to deny all access after hitting the threshold. default is 0s

✨ Description ✨

Use this to rate limit the traffic for a specific key to a maximum of limit requests per period time. If block is > 0s (0s by default), then always deny for key for that length of time after hitting the threshold. it's giving bouncer energy 🫶

Note: a token bucket is uniquely identified by the 4-tuple of its key, limit, period and block. so using the same key in multiple places with different rules will create multiple token buckets. don't be confused bestie, they're different buckets fr fr.

🌈 Example

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)

VOID return_token(
   STRING key,
   INT limit,
   DURATION period,
   DURATION block=0
)

Arguments:

• Same arguments as is_denied()

✨ Description ✨

Increments (by one) the number of tokens in the specified bucket. is_denied() decrements the bucket by one token and return_token() adds it back. use these two together and you can effectively make a token bucket act like a limit on concurrent requests instead of requests / time. iconic behaviour honestly 💅

Note: this function doesn't enforce anything, it merely credits a token to the appropriate bucket. it's just doing a lil favour.

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(). be so careful, this one bites 😭

🌈 Example

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)

INT remaining(
   STRING key,
   INT limit,
   DURATION period,
   DURATION block=0
)

Arguments:

• Same arguments as is_denied()

✨ Description ✨

Get the current number of tokens for a given token bucket. you can use this to create a response header to inform clients of their current quota. transparency queen ✨

🌈 Example

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)

DURATION blocked(
   STRING key,
   INT limit,
   DURATION period,
   DURATION block
)

Arguments:

• Same arguments as is_denied()

✨ Description ✨

If the token bucket identified by the four parameters has been blocked by use of the block parameter in is_denied(), then return the time remaining in the block. If it's not blocked, return 0s. use this to inform clients how long they'll be locked out. 🔒

heads up: notice this one has no default for block in the signature — you gotta pass all four, bestie.

🌈 Example

sub vcl_deliver {
   set resp.http.Retry-After
           = vsthrottle.blocked(client.identity, 15, 10s, 30s);
}

---

🍓 VOID remove_bucket(STRING key, INT limit, DURATION period, DURATION block)

VOID remove_bucket(
   STRING key,
   INT limit,
   DURATION period,
   DURATION block=0
)

Arguments:

• Same arguments as is_denied()

✨ Description ✨

Remove the token bucket identified by the four parameters, if it exists. gone. deleted. we don't know her 💀

🌈 Example

sub vcl_deliver {
       vsthrottle.remove_bucket(client.identity, 15, 10s, 30s);
}

---

and that's the whole page, bestie!! that was vmod_vsthrottle(3) straight out of the Library Functions Manual — same title, same vibes, all facts intact. throttle responsibly, love u, bye 💖✨🎀🦋