README
¶
redis
These ratelimiters are for usage with Redis. They're persistent, able to be scaled across multiple instances of your app, and are fully atomic Lua scripts.
These are used in many places in Fossabot: including but not limited to API ratelimiting, chat abuse detection, follower alert spam limiting, etc.
Library Agnostic
Given the fragmented community preferences for Redis clients in Go, this library is designed to be compatible with whatever Redis client you choose, making this library ideal for any Redis-based project you build! We achieve this through the Adapter interface - an adapter is essentially a very thin wrapper around your Redis client.
We provide native support for go-redis and redigo, though, you are more than welcome to add support for your own Redis client through the adapter interface. The underlying implementations are extremely simple, feel free to look at the premade ones for a reference point.
Example Usage
The following implements a HTTP server that has a handler ratelimited to 300 requests every 60 seconds.
package main
import (
"log"
"net/http"
"github.com/aidenwallis/go-ratelimiting/redis"
adapter "github.com/aidenwallis/go-ratelimiting/redis/adapters/go-redis"
"github.com/aidenwallis/go-write/write"
goredis "github.com/redis/go-redis/v9"
)
func main() {
client := goredis.NewClient(&goredis.Options{Addr: "127.0.0.1:6379"})
ratelimiter := redis.NewLeakyBucket(adapter.NewAdapter(client))
log.Fatalln((&http.Server{
Addr: ":8000",
Handler: http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
// this endpoint should throttle all requests to it in a leaky bucket called "my-api-endpoint", with a maximum
// of 300 requests every minute.
resp, err := ratelimiter.Use(req.Context(), &redis.LeakyBucketOptions{
KeyPrefix: "my-api-endpoint",
MaximumCapacity: 300,
WindowSeconds: 60,
})
if err != nil {
write.InternalServerError(w).Empty()
return
}
if !resp.Success {
// request got ratelimited!
write.TooManyRequests(w).Text("You are being ratelimited.")
return
}
write.Teapot(w).Text("this endpoint is indeed a teapot")
}),
}).ListenAndServe())
}
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type LeakyBucket ¶
type LeakyBucket interface {
// Use atomically attempts to use the leaky bucket. Use takeAmount to set how many tokens should be attempted to be removed
// from the bucket: they are atomic, either all tokens are taken, or the ratelimit is unsuccessful.
Use(ctx context.Context, bucket *LeakyBucketOptions, takeAmount int) (*UseLeakyBucketResponse, error)
}
LeakyBucket defines an interface compatible with LeakyBucketImpl
type LeakyBucketImpl ¶
type LeakyBucketImpl struct {
// Adapter defines the Redis adapter
Adapter adapters.Adapter
// contains filtered or unexported fields
}
LeakyBucketImpl implements a leaky bucket ratelimiter, this struct is compatible with the LeakyBucket interface
func NewLeakyBucket ¶
func NewLeakyBucket(adapter adapters.Adapter) *LeakyBucketImpl
NewLeakyBucket creates a new leaky bucket instance
func (*LeakyBucketImpl) Use ¶
func (r *LeakyBucketImpl) Use(ctx context.Context, bucket *LeakyBucketOptions, takeAmount int) (*UseLeakyBucketResponse, error)
Use atomically attempts to use the leaky bucket. Use takeAmount to set how many tokens should be attempted to be removed from the bucket: they are atomic, either all tokens are taken, or the ratelimit is unsuccessful.
type LeakyBucketOptions ¶
type LeakyBucketOptions struct {
// KeyPrefix is the bucket key name in Redis.
//
// Note that this ratelimiter will create two keys in Redis, and suffix them with :last_fill and :tokens.
KeyPrefix string
// MaximumCapacity defines the maximum number of tokens in the leaky bucket. If a bucket has expired or otherwise doesn't exist,
// the bucket is set to this size, it also ensures the bucket can never contain more than this number of tokens at any time.
//
// Note that if you decrease the number of tokens in an existing bucket, that bucket is automatically reduced to the new max size,
// however, if you increase the maximum capacity of the bucket, it will refill faster, but not immediately be placed to the new, higher
// capacity.
MaximumCapacity int
// WindowSeconds defines the maximum amount of time it takes to refill the bucket, the refill rate of the bucket is calculated using
// maximumCapacity/windowSeconds, in other words, if your capacity was 60 tokens, and the window was 1 minute, you would refill at a constant
// rate of 1 token per second.
//
// Windows have a maximum resolution of 1 second.
WindowSeconds int
}
LeakyBucketOptions defines the options available to LeakyBucket ratelimiters
type UseLeakyBucketResponse ¶
type UseLeakyBucketResponse struct {
// Success is true when we were successfully able to take tokens from the bucket.
Success bool
// RemainingTokens defines hwo many tokens are left in the bucket
RemainingTokens int
// ResetAt is the time at which the bucket will be fully refilled
ResetAt time.Time
}
UseLeakyBucketResponse defines the response parameters for LeakyBucket.Use()
Source Files
Directories