Awesome
Throttled
Package throttled implements rate limiting using the generic cell rate algorithm to limit access to resources such as HTTP endpoints.
The 2.0.0 release made some major changes to the throttled API. If this change broke your code in problematic ways or you wish a feature of the old API had been retained, please open an issue. We don't guarantee any particular changes but would like to hear more about what our users need. Thanks!
Installation
Go Modules are required to use Throttled (check that there's a go.mod
in your
package's root). Import Throttled:
import (
"github.com/throttled/throttled/v2"
)
Then any of the standard Go tooling like go build
, go test
, will find the
package automatically.
You can also pull it into your project using go get
:
go get -u github.com/throttled/throttled/v2
Upgrading from the pre-Modules version
The current /v2
of Throttled is perfectly compatible with the pre-Modules
version of Throttled, but when upgrading, you'll have to add /v2
to your
imports. Sorry about the churn, but because Throttled was already on its
semantic version 2 by the time Go Modules came around, its tooling didn't play
nice because it expects the major version in the path to match the major in
its tags.
Documentation
API documentation is available on godoc.org.
Usage
This example demonstrates the usage of HTTPLimiter
for rate-limiting access to
an http.Handler
to 20 requests per path per minute with bursts of up to 5
additional requests:
package main
import (
"fmt"
"log"
"net/http"
"github.com/throttled/throttled/v2"
"github.com/throttled/throttled/v2/store/memstore"
)
func myHandlerFunc(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Hello, world")
}
func main() {
store, err := memstore.NewCtx(65536)
if err != nil {
log.Fatal(err)
}
quota := throttled.RateQuota{
MaxRate: throttled.PerMin(20),
MaxBurst: 5,
}
rateLimiter, err := throttled.NewGCRARateLimiterCtx(store, quota)
if err != nil {
log.Fatal(err)
}
httpRateLimiter := throttled.HTTPRateLimiterCtx{
RateLimiter: rateLimiter,
VaryBy: &throttled.VaryBy{Path: true},
}
handler := http.HandlerFunc(myHandlerFunc)
http.ListenAndServe(":8080", httpRateLimiter.RateLimit(handler))
}
Upgrading to context.Context
aware version of throttled
To upgrade to the new context.Context
aware version of throttled
, update
the package to the latest version and replace the following function with their
context-aware equivalent:
memstore.New
=>memstore.NewCtx
goredisstore.New
=>goredisstore.NewCtx
redigostore.New
=>redigostore.NewCtx
throttled.NewGCRARateLimiter
=>throttled.NewGCRARateLimiterCtx
throttled.HTTPRateLimiter
=>throttled.HTTPRateLimiterCtx
Please note that not all stores make use of the passed context.Context
yet.
Related Projects
See throttled/gcra for a list of other projects related to rate limiting and GCRA.
Release
- Update
CHANGELOG.md
. Please use semantic versioning and the existing conventions established in the file. Commit the changes with a message likeBump version to 2.2.0
. - Tag
master
with a new version prefixed withv
. For example,v2.2.0
. git push origin master --tags
.- Publish a new release on the releases page. Copy the body from the
contents of
CHANGELOG.md
for the version and follow other conventions from previous releases.
License
The BSD 3-clause license. Copyright (c) 2014 Martin Angers and contributors.
<!-- # vim: set tw=79: -->