README
¶
RateLimiter
The ratelimiter package provides utilities to control the rate of operations by limiting how frequently actions can be performed. It implements both Token Bucket and Fixed Window rate limiters that are safe for concurrent use.
-
TokenBucket: A thread-safe token bucket rate limiter.
- Controls operation rate by allowing a fixed number of tokens (operations) per time unit
- Supports burst capacity to handle short bursts of traffic
- Provides non-blocking (
Allow()) and blocking (Wait()) methods Wait()supports context cancellation for graceful timeout or abort- Allows dynamic adjustment of capacity and refill rate at runtime
- No external dependencies, lightweight and efficient
-
FixedWindow: A thread-safe fixed window rate limiter.
- Allows up to a specified number of operations per fixed time window
- Window resets after each interval period
- Provides non-blocking (
Allow()) method for immediate rate limiting decisions - Allows dynamic adjustment of limit and interval at runtime
- Simple and predictable rate limiting behavior
- Perfect for scenarios requiring strict rate limits per time period
Examples:
For examples of each function, please checkout EXAMPLES.md
Documentation
¶
Index ¶
- type FixedWindow
- type TokenBucket
- func (t *TokenBucket) Allow() bool
- func (t *TokenBucket) AllowN(n int) bool
- func (t *TokenBucket) SetCapacity(cap int)
- func (t *TokenBucket) SetRefillRate(rate float64)
- func (t *TokenBucket) Tokens() float64
- func (t *TokenBucket) Wait(ctx context.Context) error
- func (t *TokenBucket) WaitN(ctx context.Context, n int) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type FixedWindow ¶ added in v1.23.0
type FixedWindow struct {
// contains filtered or unexported fields
}
FixedWindow implements a fixed window rate limiter. It allows up to 'limit' events per 'interval' duration. The window resets after each interval.
func NewFixedWindow ¶ added in v1.23.0
func NewFixedWindow(limit int, interval time.Duration) *FixedWindow
NewFixedWindow creates a new FixedWindow rate limiter with the given limit and interval. If limit < 1, it defaults to 1. If interval <= 0, it defaults to 1 second.
func (*FixedWindow) Allow ¶ added in v1.23.0
func (l *FixedWindow) Allow() bool
Allow checks if a new event is allowed under the rate limit. Returns true if allowed, false otherwise.
func (*FixedWindow) SetInterval ¶ added in v1.23.0
func (l *FixedWindow) SetInterval(interval time.Duration)
SetInterval updates the interval duration for the rate limiter. If interval <= 0, it defaults to 1 second.
func (*FixedWindow) SetLimit ¶ added in v1.23.0
func (l *FixedWindow) SetLimit(limit int)
SetLimit updates the maximum allowed events per window. If limit <= 0, it defaults to 1.
type TokenBucket ¶
type TokenBucket struct {
// contains filtered or unexported fields
}
TokenBucket implements a thread-safe token bucket rate limiter that allows bursts up to a certain capacity while maintaining a steady refill rate.
func NewTokenBucket ¶
func NewTokenBucket(capacity int, refillRate float64) *TokenBucket
NewTokenBucket creates a new TokenBucket with the specified capacity and refill rate. The capacity determines the maximum number of tokens that can be stored, and refillRate specifies how many tokens are added per second. If capacity is less than 1, it defaults to 1. If refillRate is less than or equal to 0, it defaults to 1. Returns a TokenBucket that starts with full capacity.
func (*TokenBucket) Allow ¶
func (t *TokenBucket) Allow() bool
Allow checks if one token is available and consumes it if so. Returns true if the token was successfully consumed, false otherwise. This is a convenience method that calls AllowN(1).
func (*TokenBucket) AllowN ¶
func (t *TokenBucket) AllowN(n int) bool
AllowN checks if n tokens are available and consumes them atomically. Returns true if n tokens were successfully consumed, false otherwise. Returning true if n is less or equal to 0. This method is thread-safe and non-blocking.
func (*TokenBucket) SetCapacity ¶
func (t *TokenBucket) SetCapacity(cap int)
SetCapacity adjusts the bucket capacity at runtime. If the new capacity is smaller than the current number of tokens, the token count is reduced to match the new capacity. This method is thread-safe. If cap < 1, it is clamped to 1.
func (*TokenBucket) SetRefillRate ¶
func (t *TokenBucket) SetRefillRate(rate float64)
SetRefillRate adjusts the token refill rate (tokens per second) at runtime. The rate must be positive; invalid rates are ignored. This method is thread-safe.
func (*TokenBucket) Tokens ¶
func (t *TokenBucket) Tokens() float64
Tokens returns the current number of available tokens as a float64. This method is thread-safe and does not consume any tokens. The returned value is approximate and may change immediately after the call returns.
func (*TokenBucket) Wait ¶
func (t *TokenBucket) Wait(ctx context.Context) error
Wait blocks until one token is available and consumes it, or until the context is cancelled. Returns an error if the context is cancelled before a token becomes available. This is a convenience method that calls WaitN(ctx, 1).
func (*TokenBucket) WaitN ¶
func (t *TokenBucket) WaitN(ctx context.Context, n int) error
WaitN blocks until n tokens are available and consumes them, or until the context is cancelled. Returns an error if the requested number of tokens exceeds the bucket capacity, or if the context is cancelled before the tokens become available. This method is thread-safe and will wait as long as necessary (respecting context cancellation).
Source Files