Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/reugn/equalizer
A set of performant rate limiters for Go
https://github.com/reugn/equalizer
api quota quotas rate rate-limit rate-limiter rate-limiting ratelimit ratelimiter sliding-window throttle throttler throttling tokenbucket
Last synced: about 1 month ago
JSON representation
A set of performant rate limiters for Go
- Host: GitHub
- URL: https://github.com/reugn/equalizer
- Owner: reugn
- License: mit
- Created: 2019-06-14T09:25:13.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-03-14T08:46:32.000Z (9 months ago)
- Last Synced: 2024-07-31T20:53:33.077Z (5 months ago)
- Topics: api, quota, quotas, rate, rate-limit, rate-limiter, rate-limiting, ratelimit, ratelimiter, sliding-window, throttle, throttler, throttling, tokenbucket
- Language: Go
- Homepage: https://pkg.go.dev/github.com/reugn/equalizer
- Size: 37.1 KB
- Stars: 81
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-go - equalizer - Quota manager and rate limiter collection for Go. (Utilities / Utility/Miscellaneous)
- awesome-go-extra - equalizer - 06-14T09:25:13Z|2021-02-16T13:50:24Z| (Utilities / Fail injection)
README
equalizer
The `equalizer` package provides a set of simple and easy-to-use rate limiters for Go.
These rate limiters can be used to limit the rate of requests to any resource, such as a database,
API, or file.
The package includes the following rate limiters:
* [Equalizer](#equalizer)
* [Slider](#slider)
* [Token Bucket](#token-bucket)
## Equalizer
`Equalizer` is a rate limiter that adjusts the rate of requests based on the outcomes of previous requests.
If previous attempts have failed, Equalizer will slow down the rate of requests to avoid overloading the system.
Conversely, if previous attempts have been successful, Equalizer will accelerate the rate of requests to make
the most of the available capacity.
### Usage Example
```go
// a random offset manager
offset := equalizer.NewRandomOffset(96)
// an Equalizer with a bitmap size of 96, 16 reserved positive bits, and the random offset manager
eq := equalizer.NewEqualizer(96, 16, offset)
// non-blocking quota request
haveQuota := eq.TryAcquire()
// update on the successful request
eq.Success(1)
```
### Benchmarks
```console
BenchmarkEqualizer_ShortTryAcquireStep-16 31538967 38.33 ns/op 0 B/op 0 allocs/op
BenchmarkEqualizer_ShortTryAcquireRandom-16 37563639 31.66 ns/op 0 B/op 0 allocs/op
BenchmarkEqualizer_ShortNotify-16 29519719 40.43 ns/op 0 B/op 0 allocs/op
BenchmarkEqualizer_LongTryAcquireStep-16 32084402 38.36 ns/op 0 B/op 0 allocs/op
BenchmarkEqualizer_LongTryAcquireRandom-16 39996501 30.37 ns/op 0 B/op 0 allocs/op
BenchmarkEqualizer_LongNotify-16 29648655 40.46 ns/op 0 B/op 0 allocs/op
```
## Slider
`Slider` tracks the number of requests that have been processed in a recent time window.
If the number of requests exceeds the limit, the rate limiter will block new requests until the window
has moved forward.
Implements the `equalizer.Limiter` interface.
### Usage Example
```go
// a Slider with a one-second window size, a 100-millisecond sliding interval,
// and a capacity of 32
slider := equalizer.NewSlider(time.Second, 100*time.Millisecond, 32)
// non-blocking quota request
haveQuota := slider.TryAcquire()
// blocking call
slider.Acquire(context.Background())
```
### Benchmarks
```console
BenchmarkSlider_TryAcquire-16 293645348 4.033 ns/op 0 B/op 0 allocs/op
BenchmarkRateLimiter_Allow-16 9362382 127.4 ns/op 0 B/op 0 allocs/op
```
* Compared to `rate.Limiter` from the [golang.org/x/time](https://pkg.go.dev/golang.org/x/time/rate) package.
## Token Bucket
`TokenBucket` maintains a fixed number of tokens. Each token represents a request that can be processed.
When a request is made, the rate limiter checks to see if there are any available tokens. If there are,
the request is processed and one token is removed from the bucket. If there are no available tokens,
the request is blocked until a token becomes available.
Implements the `equalizer.Limiter` interface.
### Usage Example
```go
// a TokenBucket with the capacity of 32 and a 100-millisecond refill interval
tokenBucket := equalizer.NewTokenBucket(32, 100*time.Millisecond)
// non-blocking quota request
haveQuota := tokenBucket.TryAcquire()
// blocking call
tokenBucket.Acquire(context.Background())
```
### Benchmarks
```console
BenchmarkTokenBucket_TryAcquire-16 304653043 3.909 ns/op 0 B/op 0 allocs/op
BenchmarkRateLimiter_Allow-16 9362382 127.4 ns/op 0 B/op 0 allocs/op
```
* Compared to `rate.Limiter` from the [golang.org/x/time](https://pkg.go.dev/golang.org/x/time/rate) package.
## License
Licensed under the [MIT](./LICENSE) License.