valkeylimiter

package module
v1.0.80 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 7 Imported by: 5

README

valkeylimiter

valkeylimiter is a high-performance, distributed rate limiting module for Valkey and Redis.

By default, it uses the Fixed Window counter algorithm for simplicity and backward compatibility, while also providing the Generic Cell Rate Algorithm (GCRA) (leaky bucket) for smooth, continuous traffic pacing with burst tolerance.

Features

  • Fixed Window by Default: Proven counter-based rate limiting compatible with existing deployments.
  • Generic Cell Rate Algorithm (GCRA) Support: Smooth leaky-bucket rate limiting that eliminates boundary burst spikes ("double-dipping") and paces requests evenly over time.
  • Single-Key Architecture for GCRA: Operates on a single Valkey key (valkeylimiter:gcra:{<identifier>}), cutting keyspace overhead in half compared to dual-key fixed-window limiters while keeping namespaces isolated to prevent key collision with Fixed Window.
  • Server-Authoritative Clock: For GCRA, time is derived atomically inside Valkey using redis.call('TIME'), eliminating synchronization discrepancies caused by client NTP drift.
  • Valkey Cluster Safe (Zero CROSSSLOT): All operations use cluster hash tags ({...}) to ensure multi-key operations and single-key GCRA calls never trigger CROSSSLOT errors across cluster nodes.
  • Partial Allowance (AllowAtMost): Allows batch jobs or multi-token consumers to acquire "up to" available capacity without failing completely.
  • Programmatic Reset (Reset): Programmatically clears rate limiting state for an identifier.
  • Detailed Timing Diagnostics: Provides RetryAfter (-1 on success, duration to wait on throttle) and ResetAfter (duration until full capacity is restored).
  • Multi-Strategy Extensibility: Seamlessly select between legacy Fixed Window (AlgorithmFixedWindow = 0 default) and GCRA (AlgorithmGCRA = 1).
  • Zero-Allocation Hot Path: Leverages pooled buffers (sync.Pool) for high-throughput, low-allocation execution.

Installation

To install the valkeylimiter module, run:

go get github.com/valkey-io/valkey-go/valkeylimiter

Usage

Basic Rate Limiting Example (Fixed Window Default)
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/valkey-io/valkey-go"
	"github.com/valkey-io/valkey-go/valkeylimiter"
)

func main() {
	// Initialize a limiter: 10 requests per minute (Fixed Window by default)
	limiter, err := valkeylimiter.NewRateLimiter(valkeylimiter.RateLimiterOption{
		ClientOption: valkey.ClientOption{InitAddress: []string{"127.0.0.1:6379"}},
		Limit:        10,
		Window:       time.Minute,
	})
	if err != nil {
		panic(err)
	}
	defer limiter.Close()

	ctx := context.Background()
	userID := "user_12345"

	// Check without consuming capacity
	chk, err := limiter.Check(ctx, userID)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Initial state: Allowed=%v, Remaining=%d\n", chk.Allowed, chk.Remaining)

	// Consume 1 token
	res, err := limiter.Allow(ctx, userID)
	if err != nil {
		panic(err)
	}
	if res.Allowed {
		fmt.Printf("Allowed! Remaining: %d, ResetAfter: %v\n", res.Remaining, res.ResetAfter)
	} else {
		fmt.Printf("Rate limited! Retry after: %v\n", res.RetryAfter)
	}

	// Consume multiple tokens
	res, err = limiter.AllowN(ctx, userID, 3)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Allowed %d tokens! Remaining: %d\n", res.Granted, res.Remaining)
}

Advanced Usage

1. Opting Into Generic Cell Rate Algorithm (GCRA)

To use smooth leaky-bucket rate limiting with burst tolerance, specify Algorithm: valkeylimiter.AlgorithmGCRA:

limiter, err := valkeylimiter.NewRateLimiter(valkeylimiter.RateLimiterOption{
	ClientOption: valkey.ClientOption{InitAddress: []string{"127.0.0.1:6379"}},
	Limit:        10,                                 // 10 req/s sustained
	Window:       time.Second,
	Burst:        50,                                 // burst capacity up to 50 tokens
	Algorithm:    valkeylimiter.AlgorithmGCRA,        // Opt-in GCRA
})
2. Burst Capacity (Burst & WithBurst)

GCRA separates the sustained rate from the burst tolerance. By default, Burst equals Limit. You can configure a larger burst buffer or override it dynamically:

// Override burst dynamically per request:
res, err := limiter.Allow(ctx, "user_123", valkeylimiter.WithBurst(100))
3. Partial Token Consumption (AllowAtMost)

For batch tasks, AllowAtMost grants whatever capacity is currently available up to n tokens:

// Request up to 10 tokens; if only 4 remain, 4 are granted rather than failing completely
res, err := limiter.AllowAtMost(ctx, "batch_job", 10)
if err != nil {
	panic(err)
}

fmt.Printf("Allowed: %v, Granted: %d, Remaining: %d\n", res.Allowed, res.Granted, res.Remaining)
4. Programmatic State Clearance (Reset)

Clear rate limiting state immediately for a specific identifier:

err := limiter.Reset(ctx, "user_123")
if err != nil {
	panic(err)
}
5. Valkey Cluster Usage (Zero CROSSSLOT)

All operations use cluster hash tags ({...}) to ensure multi-key operations and single-key GCRA calls never trigger CROSSSLOT errors across cluster nodes:

limiter, err := valkeylimiter.NewRateLimiter(valkeylimiter.RateLimiterOption{
	ClientOption: valkey.ClientOption{
		InitAddress: []string{"127.0.0.1:7010", "127.0.0.1:7011", "127.0.0.1:7012"},
	},
	Limit:     100,
	Window:    time.Minute,
	Algorithm: valkeylimiter.AlgorithmGCRA,
})
if err != nil {
	panic(err)
}
defer limiter.Close()

// Cluster routes by hash tag {tenant_1}; zero CROSSSLOT errors guaranteed
res, err := limiter.Allow(ctx, "{tenant_1}:user_42")

Implementation Details

The valkeylimiter module executes an atomic Lua script inside Valkey:

  1. Effects Replication (redis.replicate_commands()): Issued on Line 1 of the Lua script for compatibility with older Redis instances (e.g., Redis 6.2 on Memorystore/ElastiCache) where redis.call('TIME') is evaluated.
  2. Authoritative Server Time: Derives the current timestamp via redis.call('TIME'), completely eliminating clock drift across distributed client hosts.
  3. Theoretical Arrival Time (TAT): Tracks the continuous arrival schedule using a single scalar timestamp. If an arrival is within burst tolerance ($\text{TAT} \le \text{now} + \tau$), tokens are granted and the new TAT is committed. Otherwise, the arrival is rejected without modifying state.
  4. Zero Keyspace Leaks: Keys automatically expire based on the exact time required for the bucket to drain completely. Idle keys leave no residual state in Valkey.

Documentation

Index

Constants

View Source
const (
	PlaceholderPrefix = "valkeylimiter"
)

Variables

View Source
var (
	ErrInvalidTokens   = errors.New("number of tokens must be non-negative")
	ErrInvalidResponse = errors.New("invalid response from Valkey")
	ErrInvalidLimit    = errors.New("limit must be positive")
	ErrInvalidWindow   = errors.New("window must be positive")
	ErrNilBuilder      = errors.New("client builder is required")
)

Functions

func DurFromSecString added in v1.0.79

func DurFromSecString(s string) (time.Duration, error)

DurFromSecString parses a float-in-seconds string (e.g., "-1", "0.1", "1.5") into a time.Duration. A value of -1 returns time.Duration(-1), indicating no retry wait is needed.

Types

type Algorithm added in v1.0.79

type Algorithm int

Algorithm specifies the rate limiting algorithm to use.

const (
	// AlgorithmFixedWindow selects the legacy Fixed Window counter algorithm. Default.
	AlgorithmFixedWindow Algorithm = iota
	// AlgorithmGCRA selects the Generic Cell Rate Algorithm (leaky bucket).
	AlgorithmGCRA
)

type GCRAResult added in v1.0.79

type GCRAResult struct {
	Allowed    int64
	Remaining  int64
	RetryAfter time.Duration
	ResetAfter time.Duration
}

GCRAResult contains the raw numeric and timing results returned by the GCRA Lua engine.

func ExecGCRAAllowAtMost added in v1.0.79

func ExecGCRAAllowAtMost(ctx context.Context, client valkey.Client, key string, burst int64, rate int64, period time.Duration, cost int64) (GCRAResult, error)

func ExecGCRAAllowN added in v1.0.79

func ExecGCRAAllowN(ctx context.Context, client valkey.Client, key string, burst int64, rate int64, period time.Duration, cost int64) (GCRAResult, error)

func ParseGCRAResponse added in v1.0.79

func ParseGCRAResponse(resp valkey.ValkeyResult) (GCRAResult, error)

ParseGCRAResponse parses the 4-element array response from the GCRA Lua scripts. The array format is: [0] allowed (int64): count of allowed tokens (0 if rejected, or cost if allowed) [1] remaining (int64): maximum permitted instantaneous tokens [2] retry_after (string): float seconds until next request permitted ("-1" if allowed) [3] reset_after (string): float seconds until full rate limit restoration

type RateLimitOption added in v1.0.51

type RateLimitOption struct {
	// contains filtered or unexported fields
}

func WithAlgorithm added in v1.0.79

func WithAlgorithm(alg Algorithm) RateLimitOption

WithAlgorithm creates a RateLimitOption specifying the algorithm strategy.

func WithBurst added in v1.0.79

func WithBurst(burst int) RateLimitOption

WithBurst creates a RateLimitOption specifying a custom burst capacity.

func WithCustomRateLimit added in v1.0.51

func WithCustomRateLimit(limit int, window time.Duration) RateLimitOption

WithCustomRateLimit creates a RateLimitOption with custom limit and window. Burst defaults to limit.

func WithCustomRateLimitAndBurst added in v1.0.79

func WithCustomRateLimitAndBurst(limit int, window time.Duration, burst int) RateLimitOption

WithCustomRateLimitAndBurst creates a RateLimitOption with custom limit, window, and burst.

type RateLimiterClient

type RateLimiterClient interface {
	Check(ctx context.Context, identifier string, options ...RateLimitOption) (Result, error)
	Allow(ctx context.Context, identifier string, options ...RateLimitOption) (Result, error)
	AllowN(ctx context.Context, identifier string, n int64, options ...RateLimitOption) (Result, error)
	AllowAtMost(ctx context.Context, identifier string, n int64, options ...RateLimitOption) (Result, error)
	Reset(ctx context.Context, identifier string, options ...RateLimitOption) error
	Limit() int
	Close()
}

func NewRateLimiter

func NewRateLimiter(option RateLimiterOption) (RateLimiterClient, error)

type RateLimiterOption

type RateLimiterOption struct {
	ClientBuilder func(option valkey.ClientOption) (valkey.Client, error)
	KeyPrefix     string
	ClientOption  valkey.ClientOption
	Limit         int
	Window        time.Duration
	Burst         int
	Algorithm     Algorithm
}

type Result

type Result struct {
	Allowed    bool
	Remaining  int64
	ResetAtMs  int64
	RetryAfter time.Duration
	ResetAfter time.Duration
	Granted    int64
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址