distlimit

package module
v1.1.1 Latest Latest
Warning

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

 Go to latest Published: Jul 24, 2026 License: MIT Imports: 5 Imported by: 0

README

⚡ distlimit

Go Reference

distlimit is an ultra-high performance, distributed, pluggable rate-limiting library for Go. Engineered for microservices, high-concurrency APIs, and financial-grade applications requiring nanosecond-level execution speeds, zero memory allocation, and multi-tier failover capabilities.

🚀 Why distlimit?

Most Go rate-limiting libraries force you into a single algorithm, lock global mutexes during background cleanup, or collapse when Redis goes down. distlimit solves these architectural flaws with enterprise-grade resilience:

  • 🔌 100% Pluggable Strategy Architecture: Swap algorithms seamlessly without changing your storage driver or HTTP framework middleware.
  • ⚡ Zero Allocation & Nanosecond Latency: Memory evaluation runs in sub-100 nanoseconds with 0 B/op memory overhead across all standard algorithms.
  • 🔒 64-Sharded Memory Architecture: Eliminates global lock contention during concurrent HTTP requests and background state cleanups.
  • 🛡️ Half-Open Circuit Breaker (Hybrid Driver): Automatic failover from Redis to In-Memory with single-request probing to prevent Thundering Herd spikes upon Redis recovery.
  • 🔐 Security-First Middlewares: Built-in protection against IP Spoofing via CIDR-validated WithTrustedProxies headers inspection.
  • 🌐 Native Redis Cluster Safety: Enforces Redis Hash Tags {} to prevent CROSSSLOT cluster routing errors.

📐 Architecture Overview

                    +----------------------------+
                    |  HTTP / gRPC Incoming Req  |
                    +----------------------------+
                                  |
                     [ Trusted Proxies Check ]  <-- IP Spoofing Shield
                                  |
                    +----------------------------+
                    |     distlimit.Limiter      |
                    +----------------------------+
                                  |
           +----------------------+----------------------+
           |                                             |
 [ Pluggable Algorithm ]                         [ Storage Driver ]

* Token Bucket                                 - Memory (64-Sharded)
* Leaky Bucket                                 - Redis (Cluster Hash-Tagged)
* Fixed Window                                 - Hybrid (Circuit Breaker)
* Sliding Window Log
* Sliding Window Counter

🧮 Supported Algorithms

Algorithm Traffic Pattern Memory Redis Data Structure Best Use Case
Token Bucket Burst Friendly $O(1)$ Hash General-purpose API rate limiting with burst support.
Leaky Bucket Traffic Shaping $O(1)$ Hash Smoothing spikes for third-party integrations (e.g., Payment Gateways).
Fixed Window Interval Reset $O(1)$ String Counter Ultra-lightweight endpoint protection & login brute-force shielding.
Sliding Window Log 100% Exact Precision $O(N)$ Sorted Set (ZSET) Strict quota allocation, financial transactions, and zero-compromise limits.
Sliding Window Counter Weighted Moving Avg $O(1)$ Hash High-throughput distributed rate limiting with $O(1)$ memory precision.

📋 Prerequisites

  • Go: 1.20 or higher
  • Redis (Optional for distributed driver): Standalone, Sentinel, or Cluster v6.0+

📦 Installation

go get github.com/balramadan/distlimit

⚡ Quickstart

1. Basic In-Memory Limiter with Sliding Window Counter
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/balramadan/distlimit"
	"github.com/balramadan/distlimit/algorithm/slidingcounter"
	"github.com/balramadan/distlimit/driver/memory"
)

func main() {
	// Initialize 64-Sharded Memory Driver (TTL 5 minutes)
	memDriver := memory.New(5 * time.Minute)
	defer memDriver.Close(context.Background())

	// Create Limiter: 10 requests per 1 minute using Sliding Window Counter
	limiter, err := distlimit.New(
		memDriver,
		distlimit.WithLimit(10),
		distlimit.WithWindow(1*time.Minute),
		distlimit.WithAlgorithm(slidingcounter.New()),
	)
	if err != nil {
		panic(err)
	}

	// Evaluate Rate Limit for a key
	res, err := limiter.AllowKey(context.Background(), "user:123")
	if err != nil {
		panic(err)
	}

	if res.Allowed {
		fmt.Printf("Allowed! Remaining: %d\n", res.Remaining)
	} else {
		fmt.Printf("Blocked! Retry after: %v\n", res.ResetIn)
	}
}
2. Secure Web Framework Middleware (Fiber / Gin / Echo / net/http)

Protect your HTTP endpoints with built-in Anti-IP Spoofing protection using WithTrustedProxies:

package main

import (
	"context"
	"time"

	"github.com/balramadan/distlimit"
	"github.com/balramadan/distlimit/algorithm/tokenbucket"
	"github.com/balramadan/distlimit/driver/memory"
	distlimitfiber "github.com/balramadan/distlimit/middleware/fiber"
	"github.com/gofiber/fiber/v3"
)

func main() {
	memDriver := memory.New(5 * time.Minute)
	defer memDriver.Close(context.Background())

	limiter, _ := distlimit.New(
		memDriver,
		distlimit.WithLimit(100),
		distlimit.WithWindow(1*time.Minute),
		distlimit.WithAlgorithm(tokenbucket.New()),
	)

	app := fiber.New()

	// Enable Middleware with Strict Trusted Proxies (Cloudflare / Nginx Subnet)
	app.Use(distlimitfiber.New(
		limiter,
		distlimitfiber.WithTrustedProxies([]string{"10.0.0.0/8", "172.16.0.0/12"}),
	))

	app.Get("/api/data", func(c fiber.Ctx) error {
		return c.SendString("Hello World!")
	})

	app.Listen(":3000")
}
3. Resilient Dual-Tier Hybrid Driver (Redis Primary + Memory Fallback)

Automatic failover to in-memory fallback with Half-Open Circuit Breaker if Redis connection drops:

package main

import (
	"context"
	"log"
	"time"

	"github.com/balramadan/distlimit"
	"github.com/balramadan/distlimit/algorithm/slidingcounter"
	distlimithybrid "github.com/balramadan/distlimit/driver/hybrid"
	distlimitmemory "github.com/balramadan/distlimit/driver/memory"
	distlimitredis "github.com/balramadan/distlimit/driver/redis"
	"github.com/redis/go-redis/v9"
)

func main() {
	rdb := redis.NewClient(&redis.Options{Addr: "localhost:6379"})
	primary := distlimitredis.New(rdb)
	fallback := distlimitmemory.New(5 * time.Minute)

	// Hybrid Driver with 5s Cool-Off and Half-Open Probing
	hybridDriver := distlimithybrid.New(
		primary,
		fallback,
		distlimithybrid.WithCoolOffDuration(5*time.Second),
		distlimithybrid.WithOnError(func(err error) {
			log.Printf("[DISTLIMIT WARN] Redis Primary down, failing over to memory: %v", err)
		}),
	)

	limiter, _ := distlimit.New(
		hybridDriver,
		distlimit.WithLimit(500),
		distlimit.WithWindow(1*time.Minute),
		distlimit.WithAlgorithm(slidingcounter.New()),
	)

	_, _ = limiter.AllowKey(context.Background(), "api_key_abc")
}

📊 Performance & Benchmarks

Benchmarks executed on AMD 3020e Linux x86_64 (go test -bench=. -benchmem ./algorithm/...):

pkg: github.com/balramadan/distlimit/algorithm/*
cpu: AMD 3020e with Radeon Graphics

BenchmarkSlidingLog_EvaluateMemory-2         60,631,044    20.36 ns/op    0 B/op    0 allocs/op
BenchmarkTokenBucket_EvaluateMemory-2        22,322,690    46.18 ns/op    0 B/op    0 allocs/op
BenchmarkLeakyBucket_EvaluateMemory-2        22,839,754    47.76 ns/op    0 B/op    0 allocs/op
BenchmarkFixedWindow_EvaluateMemory-2        14,618,232    77.27 ns/op    0 B/op    0 allocs/op
BenchmarkSlidingCounter_EvaluateMemory-2      8,917,860   129.10 ns/op    0 B/op    0 allocs/op

Key Takeaway: All 5 algorithms achieve zero memory allocations (0 B/op, 0 allocs/op) during in-memory evaluation, allowing your Go application to handle tens of millions of rate-check operations per second without GC pause overhead.

🛡️ Framework & Middleware Adapters

distlimit provides native, zero-dependency middleware adapters for all popular Go web frameworks:

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Overview

Package distlimit provides a high-performance, resilient, and pluggable rate limiting library for Go applications. It supports pluggable algorithm strategies (Token Bucket, Leaky Bucket, Sliding Window Counter, Sliding Window Log, Fixed Window), multiple storage drivers (In-Memory, Redis, Hybrid Dual-Tier), and turn-key middleware adapters for popular frameworks.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidLimit is returned when the configured rate limit is less than or equal to 0.
	ErrInvalidLimit = errors.New("distlimit: limit must be greater than 0")

	// ErrInvalidWindow is returned when the configured rate limit window is less than or equal to 0.
	ErrInvalidWindow = errors.New("distlimit: window must be greater than 0")

	// ErrNilDriver is returned when a nil Driver is supplied during Limiter initialization.
	ErrNilDriver = errors.New("distlimit: storage driver cannot be nil")

	// ErrNilAlgorithm is returned when a nil Algorithm is supplied to WithAlgorithm.
	ErrNilAlgorithm = errors.New("distlimit: algorithm strategy cannot be nil")
)

Sentinels errors returned by distlimit.

Functions

This section is empty.

Types

type Config added in v1.1.0 

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

Config holds configuration parameters used during Limiter construction.

type Driver 

type Driver interface {
	// Allow evaluates rate limit rules for the specified key using the given algorithm strategy.
	Allow(ctx context.Context, key string, limit int64, window time.Duration, alg algorithm.Algorithm) (algorithm.Result, error)

	// Reset clears the rate limit state entry for the specified key in the storage driver.
	Reset(ctx context.Context, key string) error

	// Close gracefully releases any storage connections, background routines, or resources held by the driver.
	Close(ctx context.Context) error
}

Driver defines the interface that all rate limiting storage backends (Memory, Redis, Hybrid) must implement.

type KeyFunc 

type KeyFunc func(ctx context.Context) string

KeyFunc defines a function signature for dynamically extracting a rate limit key from a Context.

type Limiter 

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

Limiter is the central rate limiting coordinator. It combines a storage Driver, rate rules, and an algorithm strategy to evaluate incoming requests.

Limiter is thread-safe and designed for concurrent use by multiple goroutines.

func New 

func New(driver Driver, opts ...Option) (*Limiter, error)

New creates and initializes a new Limiter instance with the specified storage driver and optional options. If WithAlgorithm is omitted, it defaults to the Sliding Window Counter algorithm strategy for backward compatibility. Returns an error if driver is nil, or if limit or window are invalid (<= 0).

func (*Limiter) Allow 

func (l *Limiter) Allow(ctx context.Context) (Result, error)

Allow evaluates the rate limit key extracted via the configured KeyFunc against the active limits.

func (*Limiter) AllowKey 

func (l *Limiter) AllowKey(ctx context.Context, key string) (Result, error)

AllowKey evaluates the rate limit for an explicitly specified key string against the active limits.

func (*Limiter) Close 

func (l *Limiter) Close(ctx context.Context) error

Close gracefully closes the underlying storage driver and releases associated resources.

func (*Limiter) ResetKey added in v1.1.1 

func (l *Limiter) ResetKey(ctx context.Context, key string) error

ResetKey clears the rate limit state for the specified key in the underlying storage driver.

type Option 

type Option func(*Config)

Option configures functional parameters for Limiter initialization.

func WithAlgorithm added in v1.1.0 

func WithAlgorithm(alg algorithm.Algorithm) Option

WithAlgorithm sets the pluggable rate limiting algorithm strategy (e.g., tokenbucket, leakybucket, slidingcounter).

func WithKeyFunc 

func WithKeyFunc(fn KeyFunc) Option

WithKeyFunc configures a custom key extraction function for extracting rate limit keys from context.

func WithLimit 

func WithLimit(limit int64) Option

WithLimit sets the maximum number of requests allowed within the configured time window.

func WithWindow 

func WithWindow(window time.Duration) Option

WithWindow sets the duration of the rate limiting time window.

type Result 

type Result = algorithm.Result

Result is a type alias for algorithm.Result for backward compatibility with v1.0.0.

type State added in v1.1.0 

type State = algorithm.State

State is a type alias for algorithm.State for backward compatibility with v1.0.0.

Source Files

View all Source files

Directories

Path Synopsis
Package algorithm defines core interfaces and shared data structures for rate limiting algorithm strategies.
 Package algorithm defines core interfaces and shared data structures for rate limiting algorithm strategies.
fixedwindow
Package fixedwindow implements the Fixed Window rate limiting algorithm.
 Package fixedwindow implements the Fixed Window rate limiting algorithm.
leakybucket
Package leakybucket implements the Leaky Bucket rate limiting algorithm for traffic shaping.
 Package leakybucket implements the Leaky Bucket rate limiting algorithm for traffic shaping.
slidingcounter
Package slidingcounter implements the Sliding Window Counter rate limiting algorithm.
 Package slidingcounter implements the Sliding Window Counter rate limiting algorithm.
slidinglog
Package slidinglog implements the Sliding Window Log rate limiting algorithm.
 Package slidinglog implements the Sliding Window Log rate limiting algorithm.
tokenbucket
Package tokenbucket implements the Token Bucket rate limiting algorithm.
 Package tokenbucket implements the Token Bucket rate limiting algorithm.
driver
hybrid
Package hybrid implements a dual-tier resilient rate limiting driver with a Half-Open Circuit Breaker.
 Package hybrid implements a dual-tier resilient rate limiting driver with a Half-Open Circuit Breaker.
memory
Package memory implements a fast, thread-safe, sharded in-memory rate limiting driver.
 Package memory implements a fast, thread-safe, sharded in-memory rate limiting driver.
redis
Package redis implements a distributed rate limiting driver using Redis as the backend.
 Package redis implements a distributed rate limiting driver using Redis as the backend.
examples
echo command
echov5 command
fiber-slidingcounter command
gin-hybrid command
grpc command
nethttp command
middleware
echo
Package echo provides rate limiting middleware for the Echo v4 web framework.
 Package echo provides rate limiting middleware for the Echo v4 web framework.
echov5
Package echov5 provides rate limiting middleware for the Echo v5 web framework.
 Package echov5 provides rate limiting middleware for the Echo v5 web framework.
fiber
Package fiber provides rate limiting middleware for the Fiber v3 web framework.
 Package fiber provides rate limiting middleware for the Fiber v3 web framework.
gin
Package gin provides rate limiting middleware for the Gin web framework.
 Package gin provides rate limiting middleware for the Gin web framework.
grpc
Package grpc provides gRPC server interceptor middleware for rate limiting.
 Package grpc provides gRPC server interceptor middleware for rate limiting.
nethttp
Package nethttp provides rate limiting middleware for Go's standard net/http package.
 Package nethttp provides rate limiting middleware for Go's standard net/http package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.