Simple middleware to rate-limit HTTP requests.
This is a generic middleware to rate-limit HTTP requests.
NOTE 1: This library is considered finished.
NOTE 2: Major version changes are backward-incompatible. v2.0.0 streamlines the ugliness of the old API.
v1.0.0: This version maintains the old API but all the thirdparty modules are moved to their own repo.
v2.x.x: Brand-new API for the sake of code cleanup, thread safety, & auto-expiring data structures.
v3.x.x: Apparently we have been using golang.org/x/time/rate incorrectly. See issue #48. It always limits X number per 1 second. The time duration is not changeable, so it does not make sense to pass TTL to tollbooth.
v4.x.x: Float64 for max requests per second
v5.x.x: go.mod and go.sum
v6.x.x: Replaced go-cache with github.com/go-pkgz/expirable-cache because go-cache leaks goroutines.
v7.x.x: Replaced time/rate with embedded time/rate so that we can support more rate limit headers.
v8.x.x: Address RemoteIP vulnerability concern by replacing SetIPLookups with SetIPLookup, an explicit way to pick the IP address. New HTTPMiddleware function which is compatible with standard routers.
…
…
Compose your own middleware by using LimitByKeys().
Header entries and basic auth users can expire over time (to conserve memory).
import "time"
lmt := tollbooth.NewLimiter(1, nil)
// Set a custom expiration TTL for token bucket.
lmt.SetTokenBucketExpirationTTL(time.Hour)
// Set a custom expiration TTL for basic auth users.
lmt.SetBasicAuthExpirationTTL(time.Hour)
// Set a custom expiration TTL for header entries.
lmt.SetHeaderEntryExpirationTTL(time.Hour)
Upon rejection, the following HTTP response headers are available to users:
X-Rate-Limit-Limit The maximum request limit.
X-Rate-Limit-Duration The rate-limiter duration.
X-Rate-Limit-Request-Forwarded-For The rejected request X-Forwarded-For.
X-Rate-Limit-Request-Remote-Addr The rejected request RemoteAddr.
Upon both success and rejection RateLimit headers are sent:
RateLimit-Limit The maximum request limit within the time window (1s).
RateLimit-Reset The rate-limiter time window duration in seconds (always 1s).
RateLimit-Remaining The remaining tokens.
Customize your own message or function when limit is reached.
lmt := tollbooth.NewLimiter(1, nil)
// New in version >= 8, you must explicitly define how to pick the IP address.
lmt.SetIPLookup(limiter.IPLookup{
Name: "X-Forwarded-For",
IndexFromRight: 0,
})
// Set a custom message.
lmt.SetMessage("You have reached maximum request limit.")
// Set a custom content-type.
lmt.SetMessageContentType("text/plain; charset=utf-8")
// Set a custom function for rejection.
lmt.SetOnLimitReached(func(w http.ResponseWriter, r *http.Request) { fmt.Println("A request was rejected") })
Tollbooth does not require external storage since it uses an algorithm called Token Bucket (Go library: golang.org/x/time/rate).
Sometimes, other frameworks require a little bit of shim to use Tollbooth. These shims below are contributed by the community, so I make no promises on how well they work. The one I am familiar with are: Chi, Gin, and Negroni.
ErrStack: A small library to combine errors and also display filename and line number.
Stopwatch: A small library to measure latency of things. Useful if you want to report latency data to Graphite.
LaborUnion: A dynamic worker pool library.
Gomet: Simple HTTP client & server long poll library for Go. Useful for receiving live updates without needing Websocket.
Before sending a PR with code changes, please make sure altered code is covered with tests which are passing, and that golangci-lint shows no errors.
To check the linter output, install it and then run golangci-lint run in the root directory of the repository.
No open issues yet, or sync has not completed.