ratelimit

ratelimit

Distributed rate limiting for Go, backed by Redis. Three algorithms behind one interface, plus net/http middleware to put them in front of an API.

Try the live playground → Send requests, spam 50 at once, and watch each algorithm decide in real time. It runs browser ports of the library's Lua scripts, checked against the Go library decision for decision.

• Token bucket: bursts up to a capacity, then a steady refill rate.
• Sliding window log: exact "at most N requests in any window".
• Sliding window counter: approximate sliding window in constant memory.

Every decision is a single atomic Lua script (one round trip, no race conditions between app instances) and uses the Redis server clock, so instances with skewed clocks still agree.

Install

go get github.com/RanggaEghaPermana/ratelimit

Requires Go 1.22+ and Redis 5+ (or a compatible server such as Valkey). Works with *redis.Client, *redis.ClusterClient and any redis.UniversalClient from go-redis v9.

Quick start

rdb := redis.NewClient(&redis.Options{Addr: "localhost:6379"})

// Bursts of up to 20 requests, then a steady 10 per second.
limiter, err := ratelimit.NewTokenBucket(rdb, ratelimit.TokenBucketConfig{
	Capacity: 20,
	Rate:     10,
	Period:   time.Second,
})
if err != nil {
	log.Fatal(err)
}

res, err := limiter.Allow(ctx, "user:42")
if err != nil {
	// Redis is unavailable: decide whether to fail open or closed.
}
if !res.Allowed {
	// Reject, and tell the client to retry after res.RetryAfter.
}

Every limiter implements the same interface:

type Limiter interface {
	Allow(ctx context.Context, key string) (Result, error)
	AllowN(ctx context.Context, key string, n int) (Result, error) // charge n at once
	Reset(ctx context.Context, key string) error                   // e.g. after a successful login
}

type Result struct {
	Allowed    bool
	Limit      int           // capacity, or limit per window
	Remaining  int           // requests left right now
	RetryAfter time.Duration // wait before retrying (0 when allowed)
	ResetAfter time.Duration // until the full limit is back
}

Choosing an algorithm

Not sure? Start with the token bucket. The algorithms are explained in detail, with worked timelines, in docs/algorithms.md.

// At most 5 login attempts in any 15 minutes, counted exactly.
logins, _ := ratelimit.NewSlidingWindowLog(rdb, ratelimit.SlidingWindowConfig{
	Limit:  5,
	Window: 15 * time.Minute,
}, ratelimit.WithPrefix("login"))

// 10,000 requests per hour per API key, in constant memory.
hourly, _ := ratelimit.NewSlidingWindowCounter(rdb, ratelimit.SlidingWindowConfig{
	Limit:  10_000,
	Window: time.Hour,
}, ratelimit.WithPrefix("api-hourly"))

Give each limiter its own prefix. Limiters with the same prefix and algorithm share counters, which is what you want across app instances but not between a "login" limit and an "api" limit.

HTTP middleware

mux.Handle("/api/", ratelimit.Middleware(limiter)(apiHandler))

Responses carry these headers:

Options:

ratelimit.Middleware(limiter,
	ratelimit.WithKeyFunc(ratelimit.KeyByHeader("X-API-Key")), // default: KeyByIP
	ratelimit.WithFailOpen(),                                  // default: 503 when Redis fails
	ratelimit.WithLimitedHandler(myJSON429Handler),            // default: plain-text 429
	ratelimit.WithErrorHook(func(r *http.Request, err error) { // log or count errors
		log.Printf("rate limit: %v", err)
	}),
)

Keys. KeyByIP uses r.RemoteAddr and groups IPv6 clients by their /64 prefix, since one client usually controls a whole /64. KeyByHeader rejects requests without the header with 400, so clients cannot bypass the limit by leaving it out. Write your own KeyFunc for anything else, such as a user ID from your auth middleware.

Behind a proxy or load balancer, RemoteAddr is the proxy's address, so every client would share one limit. Rewrite RemoteAddr from the header your proxy sets before this middleware runs, and only trust that header when it comes from your proxy: clients can send any X-Forwarded-For they like.

Fail open or closed? When Redis is unreachable the middleware answers 503 by default. WithFailOpen lets traffic through instead, keeping your API up during a Redis outage without limiting. Keep the default for limits that are a security control, such as login.

Using gin, echo or another framework? Middleware is standard func(http.Handler) http.Handler, so it works with chi, gorilla/mux and http.ServeMux directly and with most frameworks through their net/http adapter. Or call limiter.Allow in your own middleware.

Example: rate limited API gateway

examples/gateway is a small reverse proxy with an exact 5-per-minute limit on /login (fails closed) and a token bucket per API key on everything else (fails open):

docker compose up -d
go run ./examples/gateway                     # proxies to a built-in echo backend
for i in $(seq 1 7); do curl -s -o /dev/null -w '%{http_code}\n' -X POST localhost:8080/login; done
# 200 200 200 200 200 429 429

Production tips

• Fail fast. The limiter runs on every request, so configure the Redis client with short timeouts and few retries. With go-redis defaults a dead Redis stalls each request for about two seconds; with the settings below it takes about 0.2s:

  redis.NewClient(&redis.Options{
  	Addr:          addr,
  	DialTimeout:   200 * time.Millisecond,
  	ReadTimeout:   100 * time.Millisecond,
  	WriteTimeout:  100 * time.Millisecond,
  	MaxRetries:    1,
  	DialerRetries: 1,
  })
  

• Redis Cluster works out of the box: every call touches exactly one key.

• Keys expire on their own. Each key's TTL is set to when it would be back to its full limit, so idle clients cost no memory.

• Changing a limit takes effect immediately for existing keys; no migration is needed.

• Redis key layout is <prefix>:<tb|swl|swc>:<key>, handy for debugging with redis-cli.

Development

make test              # unit tests with the race detector (in-memory Redis, no setup)
make redis-up          # start Redis 7 in Docker
make test-integration  # run the same contract tests against real Redis
make bench-redis       # benchmarks against real Redis
make memory            # Redis memory used per key, per algorithm

The playground in playground/ is a Vite + React app with separate desktop and mobile front ends (npm install && npm run dev there).

Unit tests run against miniredis with a controllable clock, so time-based behaviour (refill, window sliding, exact RetryAfter, key expiry) is tested deterministically without sleeping. The same contract suite, including a check that 200 concurrent callers never exceed the limit, also runs against real Redis 6, Redis 7 and Valkey 8 in CI.

Benchmarks

bench_test.go measures, for each algorithm:

• BenchmarkAllow/*/hot_key: one client hammering a single key (mostly denied).
• BenchmarkAllow/*/10k_keys: traffic spread over 10,000 clients (mostly allowed).
• BenchmarkAllowParallel: concurrent callers over 10,000 keys.
• BenchmarkRoundTrip and BenchmarkRoundTripParallel: a bare PING, the floor for any Redis-backed limiter.

Run them against a real Redis with make bench-redis. Without REDIS_ADDR they fall back to miniredis, whose numbers mostly measure miniredis itself (it builds a fresh Lua VM per script call) and say nothing about production throughput.

Results

Laptop with an Intel i5-12450H (8 cores, 12 threads), Linux, Redis 7.0.15 on localhost, Go 1.22, median of 5 runs. Absolute numbers on a busy laptop varied by up to 2x between runs, so read them as orders of magnitude and compare the algorithms with each other rather than with your hardware.

Latency and throughput

Each call allocates about 610–670 B in 18–21 allocations on the client, mostly inside go-redis.

Redis CPU per decision (script execution time from INFO commandstats, excluding network I/O)

Denied calls record nothing, and the token bucket and counter skip writing entirely (the log only prunes entries that already expired), so a client hammering the limit costs Redis less than normal traffic does. That matters most during an attack. Skipping the write cut the hot-key cost of the token bucket from 7.4 µs and of the counter from 8.3 µs.

Redis memory per key (MEMORY USAGE with a full limit's worth of requests)

What limits throughput. During the parallel benchmark redis-server sat at 100% of one core: Redis runs scripts on a single thread, so one instance is the ceiling, here around 50k decisions per second. Every call touches exactly one key, so Redis Cluster spreads keys across shards and throughput grows with the number of shards. Across a real network, add your round-trip time to the latencies above. Within a data centre that is often 100 µs or more, which dwarfs the script itself.

License

MIT