NAME

       vmod_vsthrottle - Throttling VMOD

SYNOPSIS

          import vsthrottle [from "path"] ;

          BOOL is_denied(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)

DESCRIPTION

       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"));
                  }
              }
          }

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

       Arguments:

          · key: A unique identifier to define what is 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 meeting the threshold

       Description
              Can be used 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. 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.

       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"));
                         }

                         # ...
                 }

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

       Arguments:

              · key: A unique identifier to define what is being throttled

              · limit: How many requests in the specified period

              · period: The time period

              · block: duration to block, defaults to 0s

       Description
          Get the current number of tokens for a given token bucket. This can be used to create a
          response header to inform clients of their current quota.

       Example

                 sub vcl_deliver {
                    set resp.http.X-RateLimit-Remaining = vsthrottle.remaining(client.identity, 15, 10s);
                 }

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

       Arguments:

              · key: A unique identifier to define what is being throttled

              · limit: How many requests in the specified period

              · period: The time period

              · block: duration to block

       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
          is not blocked, return 0s. This can be used to inform clients how  long  they  will  be
          locked out.

       Example

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

                                                                               VMOD_VSTHROTTLE(3)