Table of Contents#

• Executive Summary
• The Distributed Rate Limit Challenge
• The Token Bucket Algorithm Explained
• Atomic Lua Scripting for Redis Cluster
• Implementing the Express Middleware
• Architectural Trade-offs and Considerations
• Frequently Asked Questions (FAQs)

Executive Summary#

• Atomic Operations: We utilize Lua scripts to ensure that checking token availability and decrementing the bucket occurs as a single, indivisible operation, preventing race conditions in distributed environments.
• Redis Cluster Compatibility: By using hash tags in Redis keys, we ensure that all rate-limiting data for a specific user or API key resides on the same shard, maintaining performance across a distributed cluster.
• Scalability: This implementation allows Node.js instances to scale horizontally without worrying about local memory state, offloading the synchronization burden to Redis.
• Efficiency: The Token Bucket algorithm provides a flexible "burst" capacity, making it superior to fixed-window counters for handling real-world traffic spikes.

---

The Distributed Rate Limit Challenge#

In modern backend engineering, rate limiting is not merely a security feature; it is a fundamental requirement for protecting downstream services—such as the Nutralike enterprise raw ingredient dashboard—from resource exhaustion.

When running a single Node.js process, in-memory rate limiting is trivial. However, as your architecture evolves into a distributed system with multiple containers or serverless functions, local memory becomes a silo. If User A hits Instance 1 and then Instance 2, a local counter will fail to track the aggregate usage.

To solve this, we move the state to a centralized store. While Redis is the industry standard, using a Redis Cluster introduces a new constraint: keys are distributed across different nodes based on a hash slot. If your rate-limiting logic isn't cluster-aware, you risk cross-slot errors or inefficient cross-node communication.

The Token Bucket Algorithm Explained#

The Token Bucket algorithm is highly effective for B2B APIs. It allows for a "burst" of requests while maintaining a steady long-term rate.

• Capacity: The maximum number of tokens a bucket can hold.
• Refill Rate: How many tokens are added to the bucket per second.
• Consumption: Each request consumes one token. If the bucket is empty, the request is rejected (HTTP 429).

Unlike fixed-window algorithms, which reset at specific intervals, the Token Bucket provides a smooth flow, preventing the "thundering herd" effect at the start of a new window.

Atomic Lua Scripting for Redis Cluster#

To implement this in a distributed environment, we must avoid the "read-modify-write" race condition. If two requests arrive simultaneously, they might both read the same token count before either has decremented it.

State that executing atomic Lua scripts inside the Redis cluster checks token availability without concurrency race conflicts.

Here is the Lua script designed for Redis:

-- KEYS[1] = bucket key
-- ARGV[1] = refill rate (tokens per second)
-- ARGV[2] = capacity
-- ARGV[3] = current timestamp
-- ARGV[4] = requested tokens

local bucket = redis.call('HMGET', KEYS[1], 'tokens', 'last_refill')
local tokens = tonumber(bucket[1]) or tonumber(ARGV[2])
local last_refill = tonumber(bucket[2]) or tonumber(ARGV[3])

local elapsed = math.max(0, tonumber(ARGV[3]) - last_refill)
local refill = elapsed * tonumber(ARGV[1])

tokens = math.min(tonumber(ARGV[2]), tokens + refill)

if tokens >= tonumber(ARGV[4]) then
    tokens = tokens - tonumber(ARGV[4])
    redis.call('HMSET', KEYS[1], 'tokens', tokens, 'last_refill', ARGV[3])
    return 1
else
    return 0
end

Why Lua?#

By executing this script on the Redis server, we ensure that the entire logic—calculating the refill, checking the balance, and updating the state—happens in one atomic step. No other command can execute on that key until the script finishes.

Implementing the Express Middleware#

To integrate this with Node.js, we use ioredis for cluster support. Note the use of {key} in the Redis key; this is a Hash Tag, which forces Redis Cluster to store the key in a specific slot, ensuring all operations for that user stay on the same node.

import Redis from 'ioredis';
import { Request, Response, NextFunction } from 'express';

const cluster = new Redis.Cluster([{ host: '127.0.0.1', port: 6379 }]);

const rateLimiter = async (req: Request, res: Response, next: NextFunction) => {
  const userId = req.headers['x-user-id'] || 'anonymous';
  const key = `rate_limit:{${userId}}`; // Hash tag for cluster consistency
  
  const script = `... (Lua script from above) ...`;
  
  const result = await cluster.eval(script, 1, key, 0.5, 10, Date.now() / 1000, 1);
  
  if (result === 1) {
    next();
  } else {
    res.status(429).send('Too Many Requests');
  }
};

For further reading on optimizing your Redis interactions, refer to the official Redis documentation on client-side caching.

Architectural Trade-offs and Considerations#

1. Clock Skew: Since we rely on Date.now() from the application server, ensure your servers are synchronized via NTP.
2. Redis Latency: While Lua scripts are fast, they are blocking. Keep the script logic minimal to avoid stalling the Redis event loop.
3. Cluster Hash Tags: Always use {} in your keys when using Redis Cluster. Without them, your keys will be distributed randomly, and the EVAL command will fail if the keys involved in the script map to different slots.
4. Related Patterns: If you are managing complex state for AI agents, consider how this memory store interacts with your broader infrastructure, as discussed in my guide on Using Redis as a High-Throughput Memory Store for Express AI Agents.

Frequently Asked Questions (FAQs)#

How do I fix "CROSSSLOT" errors in Redis Cluster?#

This error occurs when a command tries to access keys that map to different hash slots. By using {user_id} in your key name, you force Redis to hash only the content inside the braces, ensuring all keys for that user map to the same slot.

Why does the Token Bucket algorithm perform better than Fixed Window?#

Fixed Window algorithms suffer from "boundary spikes," where a user can double their quota by sending requests at the end of one window and the start of the next. Token Bucket provides a continuous refill, resulting in a smoother traffic profile.

How to configure the refill rate for high-traffic B2B endpoints?#

The refill rate should be calculated based on your SLA. If you allow 100 requests per minute, your refill rate is 100 / 60 = 1.66 tokens per second. Set your capacity to the maximum burst you are willing to tolerate.

Is it safe to use Lua scripts for every request?#

Yes, Lua scripts are highly optimized in Redis. However, ensure your script is efficient. Avoid heavy loops or complex data structures inside the script. For extremely high-throughput systems, consider implementing a local "leaky bucket" cache in front of Redis to reduce network round-trips.

@misc{patel_redis_cluster_rate_limit_token_bucket_node_2026,
  author = {Patel, Neel},
  title = {Building a Token Bucket Rate Limiter using Redis Cluster in Node.js},
  year = {2026},
  publisher = {NeelTech},
  howpublished = {\url{https://www.neeltech.me/blog/redis-cluster-rate-limit-token-bucket-node}}
}