Skip to content

Commit

Permalink
feat: implement rueidislimiter module for distributed rate limiting
Browse files Browse the repository at this point in the history
Signed-off-by: Ernesto Alejandro Santana Hidalgo <[email protected]>
  • Loading branch information
nesty92 committed Nov 4, 2024
1 parent bf8de44 commit 0b1a56f
Show file tree
Hide file tree
Showing 5 changed files with 596 additions and 0 deletions.
142 changes: 142 additions & 0 deletions rueidislimiter/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@

# rueidislimiter

A Redis-based rate limiter for Go, implemented using the `rueidis` client library. This module provides an interface for token bucket rate limiting with precise control over limits and time windows. Inspired by GitHub's approach to scaling their API with a sharded, replicated rate limiter in Redis ([github.blog](https://github.blog/engineering/infrastructure/how-we-scaled-github-api-sharded-replicated-rate-limiter-redis/)), this module offers a robust solution for managing request rates across distributed systems.

## Features

- **Token Bucket Algorithm**: Implements a token bucket algorithm to control the number of actions (e.g., API requests) a user can perform within a specified time window.
- **Customizable Limits**: Allows configuration of request limits and time windows to suit various application requirements.
- **Distributed Rate Limiting**: Leverages Redis to maintain rate limit counters, ensuring consistency across distributed environments.
- **Retry and Reset Information**: Provides `RetryAfter` and `ResetAfter` durations to inform clients when they can retry requests.

## Installation

To install the `rueidislimiter` module, run:

```bash
go get github.com/redis/rueidis/rueidislimiter
```

## Usage

### Basic Rate Limiting Example

The following example demonstrates how to initialize a rate limiter with a custom request limit and time window, and how to check and allow requests based on an identifier (e.g., a user ID or IP address):

```go
package main

import (
"context"
"fmt"
"time"

"github.com/redis/rueidis"
"github.com/redis/rueidis/rueidislimiter"
)

func main() {
client, err := rueidis.NewClient(rueidis.ClientOption{
InitAddress: []string{"localhost:6379"},
})
if err != nil {
panic(err)
}

// Initialize a new rate limiter with a limit of 5 requests per minute
limiter, err := rueidislimiter.NewRateLimiter(rueidislimiter.RateLimiterOption{
ClientOption: rueidis.ClientOption{InitAddress: []string{"localhost:6379"}},
Key: "api_rate_limit",
Limit: 5,
Window: time.Minute,
})
if err != nil {
panic(err)
}

identifier := "user_123"

// Check if a request is allowed
result, err := limiter.Check(context.Background(), identifier)
if err != nil {
panic(err)
}
fmt.Printf("Allowed: %v, Remaining: %d, RetryAfter: %v\n", result.Allowed, result.Remaining, result.RetryAfter)

// Allow a request
result, err = limiter.Allow(context.Background(), identifier)
if err != nil {
panic(err)
}
fmt.Printf("Allowed: %v, Remaining: %d, RetryAfter: %v\n", result.Allowed, result.Remaining, result.RetryAfter)

// Allow multiple requests
result, err = limiter.AllowN(context.Background(), identifier, 3)
if err != nil {
panic(err)
}
fmt.Printf("Allowed: %v, Remaining: %d, RetryAfter: %v\n", result.Allowed, result.Remaining, result.RetryAfter)
}
```

### API

#### `NewRateLimiter`

Creates a new rate limiter with the specified options:

- `ClientOption`: Options to connect to Redis.
- `Key`: Prefix for Redis keys used by this limiter.
- `Limit`: Maximum number of allowed requests per window.
- `Window`: Time window duration for rate limiting.

```go
limiter, err := rueidislimiter.NewRateLimiter(rueidislimiter.RateLimiterOption{
ClientOption: rueidis.ClientOption{InitAddress: []string{"localhost:6379"}},
Key: "api_rate_limit",
Limit: 5,
Window: time.Minute,
})
```

#### `Check`

Checks if a request is allowed under the rate limit without incrementing the count.

```go
result, err := limiter.Check(ctx, "user_identifier")
```

Returns a `Result` struct:

- `Allowed`: Whether the request is allowed.
- `Remaining`: Number of remaining requests in the current window.
- `RetryAfter`: Duration until the next allowed request (0 if allowed).
- `ResetAfter`: Duration until the current rate limit window resets.

#### `Allow`

Allows a single request, incrementing the counter if allowed.

```go
result, err := limiter.Allow(ctx, "user_identifier")
```

#### `AllowN`

Allows `n` requests, incrementing the counter accordingly if allowed.

```go
result, err := limiter.AllowN(ctx, "user_identifier", 3)
```

- `n`: The number of requests to allow.

## Implementation Details

The `rueidislimiter` module employs Lua scripts executed within Redis to ensure atomic operations for checking and updating rate limits. This approach minimizes race conditions and maintains consistency across distributed systems.

By utilizing Redis's expiration capabilities, the module automatically resets rate limits after the specified time window, ensuring efficient memory usage and accurate rate limiting behavior.

For more information on the design and implementation of Redis-based rate limiters, refer to GitHub's detailed account of scaling their API with a sharded, replicated rate limiter in Redis ([github.blog](https://github.blog/engineering/infrastructure/how-we-scaled-github-api-sharded-replicated-rate-limiter-redis/)).
9 changes: 9 additions & 0 deletions rueidislimiter/go.mod
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
module github.com/redis/rueidis/rueidislimiter

go 1.21

replace github.com/redis/rueidis => ../

require github.com/redis/rueidis v1.0.48

require golang.org/x/sys v0.24.0 // indirect
14 changes: 14 additions & 0 deletions rueidislimiter/go.sum
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
github.com/onsi/gomega v1.34.1 h1:EUMJIKUjM8sKjYbtxQI9A4z2o+rruxnzNvpknOXie6k=
github.com/onsi/gomega v1.34.1/go.mod h1:kU1QgUvBDLXBJq618Xvm2LUX6rSAfRaFRTcdOeDLwwY=
golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 h1:2dVuKD2vS7b0QIHQbpyTISPd0LeHDbnYEryqj5Q1ug8=
golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56/go.mod h1:M4RDyNAINzryxdtnbRXRL/OHtkFuWGRjvuhBJpk2IlY=
golang.org/x/net v0.27.0 h1:5K3Njcw06/l2y9vpGCSdcxWOYHOUk3dVNGDXN+FvAys=
golang.org/x/net v0.27.0/go.mod h1:dDi0PyhWNoiUOrAS8uXv/vnScO4wnHQO4mj9fn/RytE=
golang.org/x/sys v0.24.0 h1:Twjiwq9dn6R1fQcyiK+wQyHWfaz/BJB+YIpzU/Cv3Xg=
golang.org/x/sys v0.24.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
golang.org/x/text v0.16.0 h1:a94ExnEXNtEwYLGJSIUxnWoxoRz/ZcCsV63ROupILh4=
golang.org/x/text v0.16.0/go.mod h1:GhwF1Be+LQoKShO3cGOHzqOgRrGaYc9AvblQOmPVHnI=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
Loading

0 comments on commit 0b1a56f

Please sign in to comment.