README
¶
Rate limiting for go-redis
❤ Uptrace.dev - distributed traces, logs, and errors in one place
This package is based on rwz/redis-gcra and implements GCRA (aka leaky bucket) for rate limiting based on Redis. The code requires Redis version 3.2 or newer since it relies on replicate_commands feature.
Installation
redis_rate supports 2 last Go versions and requires a Go version with modules support. So make sure to initialize a Go module:
go mod init github.com/my/repo
And then install redis_rate/v9 (note v9 in the import; omitting it is a popular mistake):
go get github.com/go-redis/redis_rate/v9
Example
package redis_rate_test
import (
"context"
"fmt"
"github.com/go-redis/redis/v8"
"github.com/go-redis/redis_rate/v9"
)
func ExampleNewLimiter() {
ctx := context.Background()
rdb := redis.NewClient(&redis.Options{
Addr: "localhost:6379",
})
_ = rdb.FlushDB(ctx).Err()
limiter := redis_rate.NewLimiter(rdb)
res, err := limiter.Allow(ctx, "project:123", redis_rate.PerSecond(10))
if err != nil {
panic(err)
}
fmt.Println("allowed", res.Allowed, "remaining", res.Remaining)
// Output: allowed 1 remaining 9
}
Documentation
¶
Index ¶
- type Limit
- type Limiter
- func (l Limiter) Allow(ctx context.Context, key string, limit Limit) (*Result, error)
- func (l Limiter) AllowAtMost(ctx context.Context, key string, limit Limit, n int) (*Result, error)
- func (l Limiter) AllowN(ctx context.Context, key string, limit Limit, n int) (*Result, error)
- func (l *Limiter) Reset(ctx context.Context, key string) error
- type Result
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Limiter ¶
type Limiter struct {
// contains filtered or unexported fields
}
Limiter controls how frequently events are allowed to happen.
func NewLimiter ¶
func NewLimiter(rdb rediser) *Limiter
NewLimiter returns a new Limiter.
Example ¶
ctx := context.Background()
rdb := redis.NewClient(&redis.Options{
Addr: "localhost:6379",
})
_ = rdb.FlushDB(ctx).Err()
limiter := redis_rate.NewLimiter(rdb)
res, err := limiter.Allow(ctx, "project:123", redis_rate.PerSecond(10))
if err != nil {
panic(err)
}
fmt.Println("allowed", res.Allowed, "remaining", res.Remaining)
Output: allowed 1 remaining 9
func (Limiter) AllowAtMost ¶
func (l Limiter) AllowAtMost( ctx context.Context, key string, limit Limit, n int, ) (*Result, error)
AllowAtMost reports whether at most n events may happen at time now. It returns number of allowed events that is less than or equal to n.
type Result ¶
type Result struct {
// Limit is the limit that was used to obtain this result.
Limit Limit
// Allowed is the number of events that may happen at time now.
Allowed int
// Remaining is the maximum number of requests that could be
// permitted instantaneously for this key given the current
// state. For example, if a rate limiter allows 10 requests per
// second and has already received 6 requests for this key this
// second, Remaining would be 4.
Remaining int
// RetryAfter is the time until the next request will be permitted.
// It should be -1 unless the rate limit has been exceeded.
RetryAfter time.Duration
// ResetAfter is the time until the RateLimiter returns to its
// initial state for a given key. For example, if a rate limiter
// manages requests per second and received one request 200ms ago,
// Reset would return 800ms. You can also think of this as the time
// until Limit and Remaining will be equal.
ResetAfter time.Duration
}
Source Files