Storage Drivers Comparison

distlimit abstracts storage state behind the distlimit.Driver interface. Choosing the right driver depends on your deployment topology, latency budgets, and availability requirements.

---

Driver Selection Matrix

Driver	Deployment Architecture	Latency Overhead	Data Persistence	Fault Tolerance	Best For
Memory	Single Instance / Edge	Sub-microsecond (200 ns)	No (Ephemeral)	High (Local process)	Monoliths, microservices with local limits, edge proxies
Redis	Multi-node Cluster	Low (1 - 3 ms)	Yes (Configurable)	Depends on Redis Cluster	Global distributed rate limiting across replicas
Hybrid	High-Availability Cluster	Sub-microsecond / Low	Partial (Primary Redis)	Extreme (Half-Open Circuit Breaker)	Mission-critical APIs, payment gateways, zero-downtime microservices

---

1. In-Memory Driver (driver/memory)

The In-Memory driver is built for hyper-performance single-node applications or services that do not require state sharing across server instances.

Key Characteristics

• 64 Shards Architecture: Uses fnv32a hashing to distribute key locks across 64 mutexes.
• Zero Allocations: Evaluation routines achieve 0 B/op memory overhead.
• Automatic TTL Cleanup: Stale rate limit keys are automatically purged in the background based on the configured cleanup interval.

Code Example

import (
  "context"
  "time"

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

// Initialize Memory Driver with a 5-minute key TTL cleanup interval
memDriver := memory.New(5 * time.Minute)
defer memDriver.Close(context.Background())

---

2. Distributed Redis Driver (driver/redis)

The Redis driver connects to external Redis instances (Standalone, Sentinel, or Cluster) using go-redis/v9.

Key Characteristics

• Atomic Lua Scripts: Evaluates limits in a single atomic script execution in Redis.
• Cluster Hash Tags {}: Key format distlimit:{key} ensures single hash slot execution on Redis Clusters.
• Fail-Open Safe: Handles connection drop gracefully when wrapped in middleware.

Code Example

import (
  "context"

  distlimitredis "github.com/balramadan/distlimit/driver/redis"
  "github.com/redis/go-redis/v9"
)

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

// Initialize Redis Driver
redisDriver := distlimitredis.New(rdb)
defer redisDriver.Close(context.Background())

---

3. Dual-Tier Hybrid Driver (driver/hybrid)

The Hybrid Driver provides enterprise-grade resiliency by layering a Primary Redis Driver over an In-Memory Fallback Driver.

Key Characteristics

• Automatic Failover: If Redis fails, requests switch to memory instantly without throwing errors or blocking traffic.
• Circuit Breaker Cool-Off: Configurable cool-off window (e.g., 5s) prevents flooding recovering Redis nodes.
• Atomic Half-Open Probing: Uses CompareAndSwap (CAS) lock so only a single probing request pings Redis when cool-off expires.
• Failover Callback (WithOnError): Trigger alerting hooks (e.g. Slack, PagerDuty, Prometheus metric) when Redis drops.

Code Example

import (
  "context"
  "log"
  "time"

  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"
)

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

primary := distlimitredis.New(rdb)
fallback := distlimitmemory.New(5 * time.Minute)

// Configure Hybrid Driver
hybridDriver := distlimithybrid.New(
  primary,
  fallback,
  distlimithybrid.WithCoolOffDuration(5*time.Second),
  distlimithybrid.WithOnError(func(err error) {
    log.Printf("[ALERT] Redis primary down, failing over to memory: %v", err)
  }),
)
defer hybridDriver.Close(context.Background())