Package throttled implements rate limiting access to resources such as HTTP endpoints.
Go Makefile
Latest commit d94de96 Feb 22, 2017 @brandur brandur committed on GitHub Merge pull request #25 from throttled/brandur-link-gcra
Link up GCRA projects page

README.md

Throttled build status GoDoc

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

throttled uses gopkg.in for semantic versioning: go get gopkg.in/throttled/throttled.v2

Documentation

API documentation is available on godoc.org. The following 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:

store, err := memstore.New(65536)
if err != nil {
    log.Fatal(err)
}

quota := throttled.RateQuota{throttled.PerMin(20), 5}
rateLimiter, err := throttled.NewGCRARateLimiter(store, quota)
if err != nil {
    log.Fatal(err)
}

httpRateLimiter := throttled.HTTPRateLimiter{
    RateLimiter: rateLimiter,
    VaryBy:      &throttled.VaryBy{Path: true},
}

http.ListenAndServe(":8080", httpRateLimiter.RateLimit(myHandler))

Contributing

Since throttled uses gopkg.in for versioning, running go get against a fork or cloning from Github to the default path will break imports. Instead, use the following process for setting up your environment and contributing:

# Retrieve the source and dependencies.
go get gopkg.in/throttled/throttled.v2/...

# Fork the project on Github. For all following directions replace
# <username> with your Github username. Add your fork as a remote.
cd $GOPATH/src/gopkg.in/throttled/throttled.v2
git remote add fork git@github.com:<username>/throttled.git

# Create a branch, make your changes, test them and commit.
git checkout -b my-new-feature
# <do some work>
make test 
git commit -a
git push -u fork my-new-feature

When your changes are ready, open a pull request using "compare across forks".

Related Projects

See throttled/gcra for a list of other projects related to rate limiting and GCRA.

License

The BSD 3-clause license. Copyright (c) 2014 Martin Angers and contributors.