vmod_vsthrottle.vcc

$Module vsthrottle 3 "Throttling VMOD"
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.

.. _token bucket algorithm: http://en.wikipedia.org/wiki/Token_bucket


.. vcl-start

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

.. vcl-end

$ABI vrt
$Event event_function
$Function 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 hitting the threshold. Default is 0s

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.

  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.

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

			# ...
		}


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

Arguments:
  - Same arguments as is_denied()

Description
  Increment (by one) the number of tokens in the specified bucket. is_denied()
  decrements the bucket by one token and return_token() adds it back.
  Using these two, you can effectively make a token bucket act like a limit on
  concurrent requests instead of requests / time.

  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().

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


$Function 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. 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);
     }

$Function 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 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);
     }

$Function 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.


Example
  ::

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