.\" Man page generated from reStructuredText.
.
.TH VMOD_VSTHROTTLE 3 "" "" ""
.SH NAME
vmod_vsthrottle \- Throttling VMOD
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.\" 
.
.\" NB:  This file is machine generated, DO NOT EDIT!
.
.\" 
.
.\" Edit vmod.vcc and run make instead
.
.\" 
.
.SH SYNOPSIS
.sp
import vsthrottle [from "path"] ;
.SH DESCRIPTION
.sp
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.
.sp
Keys can be specified from any VCL string, e.g. based on client.ip, a
specific cookie value, an API token, etc.
.sp
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, \(aqlimit\(aq and \(aqperiod\(aq.
.sp
This VMOD implements a \fI\%token\-bucket algorithm\fP\&. State associated
with the token bucket for each key is stored in\-memory using BSD\(aqs
red\-black tree implementation.
.sp
Memory usage is around 100 bytes per key tracked.
.SH CONTENTS
.INDENT 0.0
.IP \(bu 2
\fIfunc_is_denied\fP
.UNINDENT
.SS is_denied
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
BOOL is_denied(STRING jey, INT limit, DURATION period)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B 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
.TP
.B Description
Can be used to rate limit the traffic for a specific key to a
maximum of \(aqlimit\(aq requests per \(aqperiod\(aq time. A token bucket
is uniquely identified by the triplet of its key, limit and
period, so using the same key multiple places with different
rules will create multiple token buckets.
.TP
.B Example
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
sub vcl_recv {
        if (vsthrottle.is_denied(client.identity, 15, 10s)) {
                # Client has exceeded 15 reqs per 10s
                return (synth(429, "Too Many Requests"));
        }

        # ...
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.\" Generated by docutils manpage writer.
.