README
¶
local
These ratelimiters only exist within the context of your process and do not share state. If you want a distributed ratelimiter that throttles your clients regardless of restarts, or multiple processes, you should use the Redis ratelimiters instead.
These ratelimiters are thread safe through the use of mutexes, they do not spin up worker goroutines (unless you use WaitFunc) and lazily clean themselves up as they're called.
For example, I use SlidingWindow for throttling connection writes to Twitch chat.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrCapacity is returned when the sliding window max size provided is less than or equal to 0 ErrCapacity = errors.New("capacity must be more than 0") // ErrDuration is returned when the sliding window duration provided is less than or equal to 0 ErrDuration = errors.New("duration must be more than 0") )
Functions ¶
This section is empty.
Types ¶
type LeakyBucket ¶ added in v0.0.2
type LeakyBucket interface {
// Wait will block the goroutine til a ratelimit token is available. You can use context to cancel the ratelimiter.
Wait(ctx context.Context)
// WaitFunc is equivalent to Wait except it calls a callback when it's able to accquire a token. Iif you cancel the context, cb is not called. This
// function does spawn a goroutine per invocation. If you want something more efficient, consider writing your own implementation using TryTakeWithDuration()
WaitFunc(ctx context.Context, cb func())
// Size will return how many tokens are currently available
Size() int
// Take will attempt to accquire a token, it will return a boolean indicating whether it was able to accquire a token or not.
TryTake() bool
// Take will attempt to accquire a token, it will return a boolean indicating whether it was able to accquire a token or not,
// and a duration for when you should next try.
TryTakeWithDuration() (bool, time.Duration)
}
LeakyBucket is a ratelimiter that fills a given bucket at a constant rate you define (calculated based on your window duration, and the max tokens) that may exist in the window at any given time.
Leaky buckets have the advantage of being able to burst up to the max tokens you define, and then slowly leak out tokens at a constant rate. This makes it a good fit for situations where you want caller buckets to slowly fill if they decide to burst your service, whereas a sliding window ratelimiter will free all tokens at once.
Leaky buckets slowly fill your window over time, and will not fill above the size of the window. For example, if you allow 10 tokens per a window of 1 second, your bucket fills at a fixed rate of 100ms.
See: https://en.wikipedia.org/wiki/Leaky_bucket
func NewLeakyBucket ¶ added in v0.0.2
func NewLeakyBucket(tokensPerWindow int, window time.Duration) LeakyBucket
NewLeakyBucket creates a new leaky bucket ratelimiter. See the LeakyBucket interface for more info about what this ratelimiter does.
type SlidingWindow ¶
type SlidingWindow interface {
// Wait will block the goroutine til a ratelimit token is available. You can use context to cancel the ratelimiter.
Wait(ctx context.Context)
// WaitFunc is equivalent to Wait except it calls a callback when it's able to accquire a token. Iif you cancel the context, cb is not called. This
// function does spawn a goroutine per invocation. If you want something more efficient, consider writing your own implementation using TryTakeWithDuration()
WaitFunc(ctx context.Context, cb func())
// Size will return how many items are currently sitting in the window
Size() int
// Take will attempt to accquire a ratelimit window, it will return a boolean indicating whether it was able to accquire a token or not.
TryTake() bool
// Take will attempt to accquire a ratelimit window, it will return a boolean indicating whether it was able to accquire a token or not,
// and a duration for when you should next try.
TryTakeWithDuration() (bool, time.Duration)
}
SlidingWindow provides an interface for the sliding window ratelimiter.
The sliding window ratelimiter is a fixed size window that holds a set of timestamps. When a token is taken, the current time is added to the window. The window is constantly cleaned, and evicting old tokens, which allows new ones to be added as the window discards old tokens.
func NewSlidingWindow ¶
func NewSlidingWindow(capacity int, duration time.Duration) (SlidingWindow, error)
NewSlidingWindow creates a new sliding window ratelimiter. See the SlidingWindow interface for more info about what this ratelimiter does.
Source Files