diff options
Diffstat (limited to 'vendor/gopkg.in/throttled/throttled.v1/README.md')
| -rw-r--r-- | vendor/gopkg.in/throttled/throttled.v1/README.md | 82 |
1 files changed, 82 insertions, 0 deletions
diff --git a/vendor/gopkg.in/throttled/throttled.v1/README.md b/vendor/gopkg.in/throttled/throttled.v1/README.md new file mode 100644 index 000000000..fbb4a01fc --- /dev/null +++ b/vendor/gopkg.in/throttled/throttled.v1/README.md @@ -0,0 +1,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 |