1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
|
# Throttled [](http://travis-ci.org/throttled/throttled) [](http://godoc.org/gopkg.in/throttled/throttled.v1)
Package throttled implements different throttling strategies for controlling
access to HTTP handlers.
*As of July 27, 2015, the package is now located under its own GitHub
organization and uses gopkg.in for versioning, please adjust your
imports to `gopkg.in/throttled/throttled.v1`.*
## Installation
`go get gopkg.in/throttled/throttled.v1/...`
## Interval
The Interval function creates a throttler that allows requests to go through at
a controlled, constant interval. The interval may be applied to all requests
(vary argument == nil) or independently based on vary-by criteria.
For example:
th := throttled.Interval(throttled.PerSec(10), 100, &throttled.VaryBy{Path: true}, 50)
h := th.Throttle(myHandler)
http.ListenAndServe(":9000", h)
Creates a throttler that will allow a request each 100ms (10 requests per second), with
a buffer of 100 exceeding requests before dropping requests with a status code 429 (by
default, configurable using th.DeniedHandler or the package-global DefaultDeniedHandler
variable). Different paths will be throttled independently, so that /path_a and /path_b
both can serve 10 requests per second. The last argument, 50, indicates the maximum number
of keys that the throttler will keep in memory.
## MemStats
The MemStats function creates a throttler that allows requests to go through only if
the memory statistics of the current process are below specified thresholds.
For example:
th := throttled.MemStats(throttled.MemThresholds(&runtime.MemStats{NumGC: 10}, 10*time.Millisecond)
h := th.Throttle(myHandler)
http.ListenAndServe(":9000", h)
Creates a throttler that will allow requests to go through until the number of garbage
collections reaches the initial number + 10 (the MemThresholds function creates absolute
memory stats thresholds from offsets). The second argument, 10ms, indicates the refresh
rate of the memory stats.
## RateLimit
The RateLimit function creates a throttler that allows a certain number of requests in
a given time window, as is often implemented in public RESTful APIs.
For example:
th := throttled.RateLimit(throttled.PerMin(30), &throttled.VaryBy{RemoteAddr: true}, store.NewMemStore(1000))
h := th.Throttle(myHandler)
http.ListenAndServe(":9000", h)
Creates a throttler that will limit requests to 30 per minute, based on the remote address
of the client, and will store the counter and remaining time of the current window in the
provided memory store, limiting the number of keys to keep in memory to 1000. The store
sub-package also provides a Redis-based Store implementations.
The RateLimit throttler sets the expected X-RateLimit-* headers on the response, and
also sets a Retry-After header when the limit is exceeded.
## Documentation
The API documentation is available as usual on [godoc.org][doc].
There is also a [blog post explaining the package's usage on 0value.com][blog].
Finally, many examples are provided in the /examples sub-folder of the repository.
## License
The [BSD 3-clause license][bsd]. Copyright (c) 2014 Martin Angers and Contributors.
[doc]: http://godoc.org/gopkg.in/throttled/throttled.v1
[blog]: http://0value.com/throttled--guardian-of-the-web-server
[bsd]: http://opensource.org/licenses/BSD-3-Clause
|
