Documentation
¶
Overview ¶
Package ratelimit provides token bucket rate limiting for AWS API calls
This implements a thread-safe token bucket algorithm to prevent AWS API throttling by limiting request rates. Key features:
- Configurable rate (tokens per minute) and burst capacity - Thread-safe concurrent access with mutex protection - Automatic token refill based on elapsed time - Metrics tracking for monitoring and debugging - Context-aware operations with timeout support
Example usage:
limiter := ratelimit.NewTokenBucket(10, 20) // 10/min, burst 20
if err := limiter.Allow(ctx); err != nil {
// Rate limit exceeded, handle appropriately
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Metrics ¶
type Metrics struct {
TotalRequests int64 // Total requests attempted
AllowedRequests int64 // Requests that were allowed
RateLimited int64 // Requests that were rate limited
SuccessRate float64 // Percentage of allowed requests (0.0-1.0)
CurrentTokens float64 // Current available tokens
BurstUtilization int64 // Cumulative burst usage
Rate float64 // Configured rate (per minute)
Burst int // Configured burst capacity
Uptime time.Duration // Time since metrics started
}
Metrics contains rate limiter performance metrics
type RateLimitError ¶
type RateLimitError struct {
Rate float64
Burst int
CurrentTokens float64
RetryAfter time.Duration
}
RateLimitError indicates a request was rejected due to rate limiting
func (*RateLimitError) Error ¶
func (e *RateLimitError) Error() string
type TokenBucket ¶
type TokenBucket struct {
// contains filtered or unexported fields
}
TokenBucket implements a thread-safe token bucket rate limiter
The token bucket algorithm allows for burst capacity while maintaining a sustained rate limit over time. Tokens are refilled at a constant rate, and requests consume tokens. When tokens are exhausted, requests are rejected until tokens refill.
func NewTokenBucket ¶
func NewTokenBucket(rate float64, burst int) *TokenBucket
NewTokenBucket creates a new token bucket rate limiter
Parameters:
- rate: Maximum sustained requests per minute
- burst: Maximum burst capacity (initial tokens)
The burst capacity allows for short-term spikes in traffic while maintaining the overall rate limit. For example:
rate=10, burst=20 allows 20 immediate requests, then 10/minute sustained
func (*TokenBucket) Allow ¶
func (tb *TokenBucket) Allow(ctx context.Context) error
Allow checks if a request is allowed under the current rate limit
This method is thread-safe and can be called concurrently from multiple goroutines. It automatically refills tokens based on elapsed time since the last refill.
Returns:
- nil if the request is allowed
- RateLimitError if rate limit is exceeded
- context.DeadlineExceeded if context times out
- context.Canceled if context is canceled
func (*TokenBucket) GetMetrics ¶
func (tb *TokenBucket) GetMetrics() Metrics
GetMetrics returns current rate limiter metrics
Metrics include:
- Total requests attempted
- Requests allowed (successful)
- Requests rate limited (rejected)
- Success rate percentage
- Average burst utilization
- Current token count
- Uptime duration
func (*TokenBucket) ResetMetrics ¶
func (tb *TokenBucket) ResetMetrics()
ResetMetrics resets all metrics counters
This preserves the rate limiter configuration and current token count, but clears historical metrics. Useful for testing or periodic resets.
Source Files