bucketdist

A high-performance distributed rate limiting library for Go that implements a hybrid token bucket algorithm using both local and remote token storage.

Features

Hybrid Token Management: Combines local in-memory buckets for low-latency operations with remote distributed buckets for cross-service coordination
Atomic Operations: Uses CAS operations and atomic primitives to ensure thread-safety and consistency without locks
Zero Dependencies: Pure Go implementation using only standard library primitives for maximum compatibility

Use Cases

API rate limiting across multiple service instances
Resource throttling in distributed systems
Traffic shaping with both local burst handling and global rate enforcement

Performance

4.28M ops/sec on Apple M1 (233.4 ns/op)
Zero allocations on hot path
Lock-free atomic operations
Fast path optimization - avoids time syscall when tokens available

$ go test -bench=. -benchmem -benchtime=5s
goos: darwin
goarch: arm64
pkg: github.com/yourusername/bucketdist
cpu: Apple M1
BenchmarkRateLimit-8   	24807210	       233.4 ns/op	       0 B/op	       0 allocs/op
PASS

Installation

go get github.com/yourusername/bucketdist

package main

import "github.com/flaticols/bucketdist"

func main() {
    limiter := bucketdist.New(bucketdist.Config{
        Rate:     100,  // requests per second
        Capacity: 200,  // burst capacity
    })
    
    if limiter.Allow("client-123") {
        // Process request
        handleRequest()
    } else {
        // Rate limited
        http.Error(w, "Too Many Requests", 429)
    }
}

Documentation

Config: Rate (tokens/sec) and Capacity (burst size)
Allow(clientID): Returns true if request allowed, false if rate limited
Per-client isolation: Each clientID gets independent token bucket
Automatic refill: Tokens refill based on elapsed time