Go Rate Limiter
This package provides a rate limiter in Go (Golang), suitable for use in HTTP
servers and distributed workloads. It's specifically designed for
configurability and flexibility without compromising throughput.
Usage
-
Create a store. This example uses an in-memory store:
store, err := memorystore.New(&memorystore.Config{ // Number of tokens allowed per interval. Tokens: 15, // Interval until tokens reset. Interval: time.Minute, }) if err != nil { log.Fatal(err) } -
Determine the limit by calling
Take()on the store:ctx := context.Background() // key is the unique value upon which you want to rate limit, like an IP or // MAC address. key := "127.0.0.1" tokens, remaining, reset, ok, err := store.Take(ctx, key) // tokens is the configured tokens (15 in this example). _ = tokens // remaining is the number of tokens remaining (14 now). _ = remaining // reset is the unix nanoseconds at which the tokens will replenish. _ = reset // ok indicates whether the take was successful. If the key is over the // configured limit, ok will be false. _ = ok // Here's a more realistic example: if !ok { return fmt.Errorf("rate limited: retry at %v", reset) }
There's also HTTP middleware via the httplimit package. After creating a
store, wrap Go's standard HTTP handler:
middleware, err := httplimit.NewMiddleware(store, httplimit.IPKeyFunc())
if err != nil {
log.Fatal(err)
}
mux1 := http.NewServeMux()
mux1.Handle("/", middleware.Handle(doWork)) // doWork is your original handler
The middleware automatically set the following headers, conforming to the latest
RFCs:
X-RateLimit-Limit- configured rate limit (constant).X-RateLimit-Remaining- number of remaining tokens in current interval.X-RateLimit-Reset- UTC time when the limit resets.Retry-After- Time at which to retry
Why another Go rate limiter?
I really wanted to learn more about the topic and possibly implementations. The
existing packages in the Go ecosystem either lacked flexibility or traded
flexibility for performance. I wanted to write a package that was highly
extensible while still offering the highest levels of performance.
Speed and performance
How fast is it? You can run the benchmarks yourself, but here's a few sample
benchmarks with 100,000 unique keys. I added commas to the output for clarity,
but you can run the benchmarks via make benchmarks:
$ make benchmarks
BenchmarkSethVargoMemory/memory/serial-7 13,706,899 81.7 ns/op 16 B/op 1 allocs/op
BenchmarkSethVargoMemory/memory/parallel-7 7,900,639 151 ns/op 61 B/op 3 allocs/op
BenchmarkSethVargoMemory/sweep/serial-7 19,601,592 58.3 ns/op 0 B/op 0 allocs/op
BenchmarkSethVargoMemory/sweep/parallel-7 21,042,513 55.2 ns/op 0 B/op 0 allocs/op
BenchmarkThrottled/memory/serial-7 6,503,260 176 ns/op 0 B/op 0 allocs/op
BenchmarkThrottled/memory/parallel-7 3,936,655 297 ns/op 0 B/op 0 allocs/op
BenchmarkThrottled/sweep/serial-7 6,901,432 171 ns/op 0 B/op 0 allocs/op
BenchmarkThrottled/sweep/parallel-7 5,948,437 202 ns/op 0 B/op 0 allocs/op
BenchmarkTollbooth/memory/serial-7 3,064,309 368 ns/op 0 B/op 0 allocs/op
BenchmarkTollbooth/memory/parallel-7 2,658,014 448 ns/op 0 B/op 0 allocs/op
BenchmarkTollbooth/sweep/serial-7 2,769,937 430 ns/op 192 B/op 3 allocs/op
BenchmarkTollbooth/sweep/parallel-7 2,216,211 546 ns/op 192 B/op 3 allocs/op
BenchmarkUber/memory/serial-7 13,795,612 94.2 ns/op 0 B/op 0 allocs/op
BenchmarkUber/memory/parallel-7 7,503,214 159 ns/op 0 B/op 0 allocs/op
BenchmarkUlule/memory/serial-7 2,964,438 405 ns/op 24 B/op 2 allocs/op
BenchmarkUlule/memory/parallel-7 2,441,778 469 ns/op 24 B/op 2 allocs/op
There's likely still optimizations to be had, pull requests are welcome!
Ecosystem
Many of the existing packages in the ecosystem take dependencies on other
packages. I'm an advocate of very thin libraries, and I don't think a rate
limiter should be pulling external packages. That's why go-limit uses only the
Go standard library.
Flexible and extensible
Most of the existing rate limiting libraries make a strong assumption that rate
limiting is only for HTTP services. Baked in that assumption are more
assumptions like rate limiting by "IP address" or are limited to a resolution of
"per second". While go-limit supports rate limiting at the HTTP layer, it can
also be used to rate limit literally anything. It rate limits on a user-defined
arbitrary string key.
Stores
Memory
Memory is the fastest store, but only works on a single container/virtual
machine since there's no way to share the state.
Learn more.
Redis
Redis uses Redis + Lua as a shared pool, but comes at a performance cost.
Learn more.
Noop
Noop does no rate limiting, but still implements the interface - useful for
testing and local development.
Learn more.