Documentation
¶
Overview ¶
rate package contains abstraction over the rate-limiting concept which is a strategy for limiting mostly network traffic. It allows putting a cap on how often someone can repeat an action within a certain timeframe. The package does not contain any certain implementation since multiple algorithms exist that are already implemented by the Golang community. Use this package to abstract away the specific implementations provided by third party libraries. It still would require to write an adapter for implementation to fulfill rate interfaces in your infrastracture layer.
Index ¶
- Variables
- func ConsumeAndWait(ctx context.Context, l Limiter) error
- func ConsumeNAndWait(ctx context.Context, l BurstLimiter, n uint64) error
- func IsFalseToken(token Token) bool
- func Wait(ctx context.Context, deadline time.Time) error
- type BurstLimiter
- type BurstReservationLimiter
- type CancellableToken
- type Limiter
- type LimiterStore
- type ReservationLimiter
- type Token
Constants ¶
This section is empty.
Variables ¶
var ( // ErrRateLimitExceeded is the error returned by Token.Use when the rate limit exceeds the limit. ErrRateLimitExceeded = errors.New("maximum rate limit exceeded") // ErrInvalidTokenValue is the error returned by Token.Use when Token is always falsy. ErrInvalidTokenValue = errors.New("token value exceeds limit") // MinTime is minimum time value. MinTime = time.Unix(-2208988800, 0) // MaxTime is maximum time value. MaxTime = MinTime.Add(1<<63 - 1) // FalseToken should be returned from Take/TakeN methods to compare with IsFalseToken function. FalseToken CancellableToken = &falseToken{} )
Functions ¶
func ConsumeAndWait ¶
ConsumeAndWait calls Take() on Limiter and immedietely Use the Token. If ErrRateLimitExceeded error occurs it pauses the current goroutine until Limiter's ResetsAt() time deadline exceeds. If Take() returns any other error it'll immediately return this error. When ctx is canceled or ctx deadline exceeds before reset time it'll return this error.
func ConsumeNAndWait ¶
func ConsumeNAndWait(ctx context.Context, l BurstLimiter, n uint64) error
ConsumeNAndWait is extended ConsumeAndWait() function that supports BurstLimiter.TakeN().
func IsFalseToken ¶
IsFalseToken reports if token is always false meaning Limiter would never allow such token to be consumed.
Types ¶
type BurstLimiter ¶
type BurstLimiter interface {
Limiter
// TakeN returns a new Token that allows to consume n tokens at once. This function does not consume the token
// and should not consider the Token in availability calculation. If n is higher than Burst() it should return
// rate.FalseToken.
TakeN(n uint64) Token
// Burst is the maximum number of tokens that can be consumed in a single call to TakeN, so higher Burst
// value allow more events to happen at once. A zero value means none token can be consumed and TakeN
// should always return rate.FalseToken.
Burst() uint64
}
BurstLimiter extends Limiter functionality to accept burst, so it adds an additional limit to allow multiple events to be consumed at once.
type BurstReservationLimiter ¶
type BurstReservationLimiter interface {
BurstLimiter
ReservationLimiter
ReserveN(n uint64) CancellableToken
}
BurstLimiter extends BurstLimiter and ReservationLimiter functionality to accept burst reservation, so it allow to reserve multiple tokens at once with single composed token.
type CancellableToken ¶
type CancellableToken interface {
Token
// Cancel frees up tokens to ReservationLimiter.
Cancel()
}
CancellableToken is a controlled token by ReservationLimiter. It extends the Token functionality with Cancel function that allows to free up the reserved tokens.
type Limiter ¶
type Limiter interface {
// Take returns a new Token. This should not consume the token and not consider the Token in availability calculation.
// If Limit() is zero then this should return rate.FalseToken.
Take() Token
// Tokens should return the remaining token amount that can be consumed at now time with Take, so higher
// Tokens value allow more events to happen without a delay. A zero value means none token can be consumed.
Tokens() uint64
// Limit should return the maximum amount of token that can be consumed within defined period with Take, so higher Limit
// value allow more events to happen without a limit delay. A zero value means none token can be consumed and Take
// should return rate.FalseToken.
Limit() uint64
}
Limiter controls how frequently events are allowed to happen. The implementation decides which algorithm should be used that can fulfill the interface. The Token name is syntactic and does not restrict implementation to use token/leaky bucket algorithms. The interface serves as a simple API to rate limiting and any other algorithms like a fixed window can be used.
type LimiterStore ¶
type LimiterStore interface {
// Limit returns Limiter that was persisted before in store with corresponding key string.
// If there was no entry found it should return default Limiter and persist it with specified key.
Limit(key string) Limiter
}
LimiterStore is store for different Limiters indicated with key string.
type ReservationLimiter ¶
type ReservationLimiter interface {
Limiter
Reserve() CancellableToken
}
ReservationLimiter extends Limiter functionality with reservations that are cancellable tokens so the caller can reserve a token which affects rate limiting calculation and decide later if he want to consume it or cancel and free up token allocation.
type Token ¶
type Token interface {
// Use consumes token and returns no error if succeeded. Returns ErrRateLimitExceeded when limit rate was exceeded.
// If used with BurstLimiter it will not consume tokens below the limit before returning error. It will return ErrInvalidTokenValue
// when Limiter Limit/Burst is lower than value provided in Take/TakeN.
Use() error
// Allow reports whether an token can be consumed.
Allow() bool
// ResetsAt returns a time when token will be available to be consumed. At returned time Allow() should report true.
ResetsAt() time.Time
}
Token is a controlled token by Limiter. It allows the caller to consume it or check if it can be consumed and the actual time that it'll be allowed to be consumed.
Source Files