js

Build High-Performance Distributed Rate Limiting with Redis, Node.js and Lua Scripts: Complete Tutorial

Learn to build production-ready distributed rate limiting with Redis, Node.js & Lua scripts. Covers Token Bucket, Sliding Window algorithms & failover handling.

Build High-Performance Distributed Rate Limiting with Redis, Node.js and Lua Scripts: Complete Tutorial

Recently, I faced an API meltdown during a traffic surge. Our services buckled under unexpected load, exposing our rate limiting as a single-point failure. This experience drove me to design a distributed solution using Redis, Node.js, and Lua. Why these tools? They combine atomic operations, shared state management, and high throughput - essential for modern distributed systems.

Traditional approaches fail in distributed environments. Imagine ten servers each allowing 100 requests per minute. Without coordination, one client could send 1,000 requests across all servers. We need centralized state management. Redis solves this with its in-memory data store and atomic operations.

But race conditions lurk in naive implementations. Consider this flawed approach:

async function faultyRateLimit(key: string) {
  const current = await redis.get(key);
  if (parseInt(current) > 100) return false;
  // Race condition gap here
  await redis.incr(key);
  return true;
}

Between get() and incr(), other requests can slip through. How do we close this gap? Lua scripts execute atomically in Redis, eliminating race conditions.

Let’s implement the Token Bucket algorithm. It allows short bursts while enforcing long-term averages. We’ll store tokens and last refill time in a Redis hash:

-- Token Bucket Lua Script
local key = KEYS[1]
local capacity = tonumber(ARGV[1])
local now = redis.call('TIME')
local current_time = tonumber(now[1]) * 1000 + math.floor(tonumber(now[2]) / 1000)
local bucket = redis.call('HMGET', key, 'tokens', 'last_refill')

-- Calculate new tokens based on elapsed time
local elapsed = current_time - tonumber(bucket[2])
local new_tokens = elapsed * (tokens_per_ms)
local tokens = math.min(capacity, (tonumber(bucket[1]) or capacity) + new_tokens)

if tokens >= 1 then
  redis.call('HMSET', key, 'tokens', tokens - 1, 'last_refill', current_time)
  return {1, tokens - 1} -- Allowed
else
  return {0, tokens} -- Rejected
end

Notice we use Redis’ TIME command instead of server clocks. Why? Server time drift would cause inconsistencies.

For sliding windows, we combine sorted sets and transactions:

async function slidingWindow(key: string, windowMs: number, limit: number) {
  const now = Date.now();
  const windowStart = now - windowMs;
  
  const transaction = redis.multi();
  transaction.zremrangebyscore(key, 0, windowStart); // Clean old requests
  transaction.zcard(key); // Count current requests
  transaction.zadd(key, now, `${now}-${Math.random()}`); // Add new request
  transaction.expire(key, Math.ceil(windowMs / 1000) * 2); // Set TTL
  
  const [_, count] = await transaction.exec();
  return count < limit;
}

This maintains precise counts within moving time windows. But is it production-ready? Not yet - we need fault tolerance.

When Redis fails, we must fail open. Rejecting all requests during outages creates denial-of-service:

async function resilientRateLimit(userId: string) {
  try {
    return await strictRateLimit(userId);
  } catch (e) {
    metrics.increment('redis_failures');
    return true; // Fail open
  }
}

Monitor failures with metrics like:

  • Redis latency
  • Error rates
  • Rejection percentages

For Express middleware, we inject rate checks before handlers:

app.use((req, res, next) => {
  const ip = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
  const result = await rateLimiter.check(ip);
  
  if (!result.allowed) {
    res.header('Retry-After', result.retryAfter);
    return res.status(429).send('Too many requests');
  }
  
  next();
});

Include Retry-After headers - they’re crucial for good API citizenship.

Performance testing revealed optimizations:

  • Pipeline batched operations
  • Use EVALSHA instead of EVAL
  • Set enableOfflineQueue: false in Redis config
  • Local caches for frequent offenders

After implementing, our API handled 3x more traffic with zero outages. The system rejects abusive patterns while allowing legitimate bursts. What thresholds work for your use case? Experiment with different algorithms.

I’ve shared the core techniques that saved our infrastructure. If this helped you, share it with others facing similar scaling challenges. Have questions about implementation details? Let’s discuss in the comments!

Keywords: distributed rate limiting redis, node.js redis rate limiting, lua scripts redis atomic operations, token bucket algorithm implementation, sliding window rate limiter, redis failover handling, rate limiting middleware express, distributed systems rate limiting, redis lua scripts performance, production rate limiting system



Similar Posts
Blog Image
Complete Guide: Build Multi-Tenant SaaS with NestJS, Prisma and Row-Level Security

Learn to build secure multi-tenant SaaS apps with NestJS, Prisma & PostgreSQL RLS. Complete guide with code examples, tenant isolation & deployment tips.

Blog Image
Complete Guide to Integrating Next.js with Prisma ORM for Type-Safe Full-Stack Applications

Learn how to integrate Next.js with Prisma ORM for building type-safe, full-stack web applications with seamless database operations and unified codebase.

Blog Image
Build High-Performance GraphQL API with NestJS, Prisma, and Redis Caching Guide

Learn to build a high-performance GraphQL API with NestJS, Prisma ORM, and Redis caching. Master subscriptions, authentication, and optimization techniques for production-ready applications.

Blog Image
Build Type-Safe Event-Driven Architecture with TypeScript, EventEmitter2, and Redis Complete Guide

Master TypeScript event-driven architecture with EventEmitter2 & Redis. Build scalable, type-safe systems with distributed event handling, error resilience & monitoring best practices.

Blog Image
Complete Guide to Integrating Next.js with Prisma ORM for Type-Safe Database Operations

Learn how to integrate Next.js with Prisma ORM for type-safe, scalable web apps. Discover seamless database operations, API routes, and developer experience benefits.

Blog Image
Build a Real-time Collaborative Document Editor with Socket.io, Operational Transform, and Redis Complete Guide

Learn to build a real-time collaborative document editor using Socket.io, Operational Transform & Redis. Master conflict resolution, scaling & deployment.