Implementing Token Bucket Rate Limiting With Redis

Implementing Token Bucket Rate Limiting With Redis

What You’ll Need

  • A high-performance server running Ubuntu 22.04 or 24.04, such as a Hetzner VPS, Contabo VPS, or DigitalOcean instance.
  • A custom domain managed through Namecheap if you intend to expose your API via TLS.
  • Node.js runtime (v18.x or v20.x LTS) installed on your system.
  • Redis server (v7.x or later) accessible locally or over a secure private network.

Table of Contents

Understanding the Token Bucket Algorithm

Rate limiting is an absolute necessity when building scalable web applications and public APIs. Unrestricted endpoints invite denial of service attacks, brute force authentication attempts, and infrastructure resource exhaustion. When securing authentication endpoints alongside techniques like Implementing JWT Refresh Token Rotation In Express, rate limiting forms your first line of defense against credential stuffing.

Several algorithms exist for rate limiting, including Fixed Window, Sliding Window Log, and Leaky Bucket. However, the Token Bucket algorithm strikes the ideal balance between memory efficiency and support for legitimate traffic bursts.

How the Token Bucket Model Works

Imagine a bucket that holds a maximum capacity of tokens (for example, 10 tokens).

  1. Token Refill: The bucket is refilled at a constant rate (for example, 2 tokens per second) up to its maximum capacity. Excess tokens spill over and are discarded.
  2. Token Consumption: When an HTTP request arrives, the application attempts to draw a predetermined number of tokens from the bucket (usually 1 token per request).
  3. Decision Rule: If enough tokens exist in the bucket, the requested tokens are removed, and the request is processed. If the bucket lacks sufficient tokens, the request is rejected immediately with an HTTP 429 (Too Many Requests) status code.
       [ Token Refill Generator ]
                 |
                 v  (2 tokens / sec)
          +--------------+
          |  \ / \ / \ / |
          | Token Bucket |  <--- Max Capacity: 10 Tokens
          |  (Current: 7)|
          +--------------+
                 |
        [ Incoming Request ]
                 |
     Is tokens >= 1 requested?
        /                \
      YES                 NO
      /                    \
Consume 1 Token         Return 429
Process Request         Too Many Requests

The Naive Implementation vs. Centralized Redis

A naive implementation might track token counts in memory inside your application process. This fails in modern cloud deployments. As soon as you scale horizontally across multiple application instances, local in-memory buckets lose synchronicity. An attacker could bypass limits by rotating requests across instance IPs behind your load balancer.

To solve this, we centralize our state in Redis. However, naive Redis implementations suffer from race conditions. Reading the current state, computing the new token balance in application code, and writing the state back requires multiple round-trips. Under high concurrency, two parallel requests can read the same token count and bypass limits.

To guarantee atomicity without lock contention, we execute the token bucket calculations inside Redis using a custom Lua script.

Writing the Atomic Redis Lua Script

Redis executes Lua scripts atomically. No other command or script can run while a Lua script executes. This prevents race conditions entirely without requiring complex distributed locks.

Deploying your Redis instance on a dedicated Hetzner VPS ensures ultra-low latency operations when executing these scripts.

Here is the complete production-grade Lua script. It handles mathematical precision, calculates fractional token replenishment based on precise microsecond or second timestamps, enforces dynamic bucket capacities, sets automatic key expiration to prevent memory leaks, and returns structured responses to the application server.

Save the following content to a file named token_bucket.lua:

local key = KEYS[1]
local capacity = tonumber(ARGV[1])
local fill_rate = tonumber(ARGV[2])
local now = tonumber(ARGV[3])
local requested = tonumber(ARGV[4])

local ttl = math.ceil(capacity / fill_rate) * 2

local data = redis.call('HMGET', key, 'tokens', 'last_updated')
local current_tokens = tonumber(data[1])
local last_updated = tonumber(data[2])

if current_tokens == nil then
    current_tokens = capacity
    last_updated = now
else
    local delta = math.max(0, now - last_updated)
    local tokens_to_add = delta * fill_rate
    current_tokens = math.min(capacity, current_tokens + tokens_to_add)
    last_updated = now
end

local allowed = 0
local remaining_tokens = current_tokens

if current_tokens >= requested then
    allowed = 1
    remaining_tokens = current_tokens - requested
    redis.call('HSET', key, 'tokens', remaining_tokens, 'last_updated', last_updated)
    redis.call('EXPIRE', key, ttl)
else
    redis.call('HSET', key, 'tokens', current_tokens, 'last_updated', last_updated)
    redis.call('EXPIRE', key, ttl)
end

local retry_after = 0
if allowed == 0 then
    local missing_tokens = requested - current_tokens
    retry_after = math.ceil(missing_tokens / fill_rate)
end

return { allowed, math.floor(remaining_tokens), retry_after }

Breaking Down the Lua Logic

  • KEYS[1]: The unique key representing the client (for example, rate_limit:ip:203.0.113.195 or rate_limit:user:1082).
  • ARGV[1] to ARGV[4]: Dynamic arguments representing maximum bucket capacity, fill rate per second, current timestamp, and requested tokens.
  • Lazy Evaluation: Instead of running a background cron job to refill tokens, we calculate how many tokens should have been generated between last_updated and now. This approach saves CPU cycles.
  • Automatic TTL: We set a dynamic Time To Live (TTL) on the Redis Hash key using math.ceil(capacity / fill_rate) * 2. If a user stops sending requests, the key automatically expires from memory, preventing memory bloat.

💡 Fast-Track Your Project: Don’t want to configure this yourself? I build custom n8n pipelines and bots. Message me with code SYS3-HUGO.

Implementing the Express Rate Limiter Middleware

Now we will build a complete Node.js service using Express and ioredis. If your system architecture relies on external worker processes or scheduled background jobs using tools such as Executing Scheduled Python Tasks Using APScheduler, you can reuse this identical token bucket concept across API clients to ensure background jobs do not overwhelm external service quotas.

First, initialize your project and install the required dependencies:

mkdir redis-rate-limiter
cd redis-rate-limiter
npm init -y
npm install express ioredis

Create a file named rateLimiter.js. This module loads the Lua script into Redis during startup using SHA1 hashing for optimal execution performance (EVALSHA), falling back to full script evaluation if script caches reset.

const fs = require('fs');
const path = require('path');
const Redis = require('ioredis');

const redisClient = new Redis({
  host: process.env.REDIS_HOST || '127.0.0.1',
  port: parseInt(process.env.REDIS_PORT || '6379', 10),
  password: process.env.REDIS_PASSWORD || undefined,
  lazyConnect: false
});

const luaScriptPath = path.join(__dirname, 'token_bucket.lua');
const luaScriptContent = fs.readFileSync(luaScriptPath, 'utf8');

let luaSha = null;

redisClient.script('LOAD', luaScriptContent).then((sha) => {
  luaSha = sha;
  console.log('Token bucket Lua script loaded into Redis. SHA:', sha);
}).catch((err) => {
  console.error('Failed to load Lua script into Redis:', err);
});

function createRateLimiter(options) {
  const capacity = options.capacity || 10;
  const fillRate = options.fillRate || 2;
  const requestedTokens = options.requestedTokens || 1;
  const keyPrefix = options.keyPrefix || 'rate_limit';

  return async function rateLimiterMiddleware(req, res, next) {
    if (!luaSha) {
      return next();
    }

    const identifier = options.customIdentifier 
      ? options.customIdentifier(req)
      : req.ip || req.headers['x-forwarded-for'] || 'unknown';

    const redisKey = `${keyPrefix}:${identifier}`;
    const nowInSeconds = Math.floor(Date.now() / 1000);

    try {
      let result;
      try {
        result = await redisClient.evalsha(
          luaSha,
          1,
          redisKey,
          capacity,
          fillRate,
          nowInSeconds,
          requestedTokens
        );
      } catch (evalErr) {
        if (evalErr.message.includes('NOSCRIPT')) {
          result = await redisClient.eval(
            luaScriptContent,
            1,
            redisKey,
            capacity,
            fillRate,
            nowInSeconds,
            requestedTokens
          );
        } else {
          throw evalErr;
        }
      }

      const allowed = result[0] === 1;
      const remainingTokens = result[1];
      const retryAfterSeconds = result[2];

      res.setHeader('X-RateLimit-Limit', capacity);
      res.setHeader('X-RateLimit-Remaining', remainingTokens);
      res.setHeader('X-RateLimit-Reset', nowInSeconds + retryAfterSeconds);

      if (allowed) {
        return next();
      } else {
        res.setHeader('Retry-After', retryAfterSeconds);
        return res.status(429).json({
          error: 'Too Many Requests',
          message: 'Rate limit exceeded. Please try again later.',
          retryAfterSeconds: retryAfterSeconds
        });
      }
    } catch (error) {
      console.error('Rate limiting error occurred:', error);
      return next();
    }
  };
}

module.exports = {
  createRateLimiter,
  redisClient
};

Next, create the primary application file named server.js. This application defines public endpoints, authentication routes with stricter rate limits, and standard API routes.

const express = require('express');
const { createRateLimiter, redisClient } = require('./rateLimiter');

const app = express();
app.use(express.json());
app.set('trust proxy', true);

const globalLimiter = createRateLimiter({
  capacity: 20,
  fillRate: 5,
  keyPrefix: 'global_limit'
});

const strictAuthLimiter = createRateLimiter({
  capacity: 3,
  fillRate: 0.1,
  keyPrefix: 'auth_limit',
  customIdentifier: (req) => {
    const email = req.body && req.body.email ? req.body.email : '';
    return `${req.ip}:${email}`;
  }
});

app.use(globalLimiter);

app.get('/api/v1/public/status', (req, res) => {
  return res.status(200).json({
    status: 'online',
    timestamp: new Date().toISOString()
  });
});

app.post('/api/v1/auth/login', strictAuthLimiter, (req, res) => {
  const { email, password } = req.body;

  if (!email || !password) {
    return res.status(400).json({ error: 'Missing required credentials' });
  }

  if (email === 'admin@example.com' && password === 'secret123') {
    return res.status(200).json({
      message: 'Authentication successful',
      token: 'jwt-sample-token-string'
    });
  }

  return res.status(401).json({ error: 'Invalid credentials' });
});

app.get('/api/v1/data/resource', (req, res) => {
  return res.status(200).json({
    payload: 'Protected resource payload successfully retrieved'
  });
});

const PORT = process.env.PORT || 3000;
const server = app.listen(PORT, () => {
  console.log(`Rate limiting server listening on port ${PORT}`);
});

process.on('SIGTERM', async () => {
  console.log('Shutting down server gracefully...');
  server.close(async () => {
    await redisClient.quit();
    process.exit(0);
  });
});

Start the application by executing:

node server.js

Production Hardening and Testing

When deploying this system behind a reverse proxy, follow our Nginx SSL certificate renewal automation guide to terminate TLS securely while maintaining client real IP headers like X-Forwarded-For. Make sure your proxy updates headers properly so req.ip reflects the origin address rather than the local proxy loopback.

Load Testing with curl

You can test your newly configured rate limiter directly from your command line.

Execute a quick request to check response headers:

curl -i http://localhost:3000/api/v1/public/status

You will see output containing standard HTTP rate limit headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 19
X-RateLimit-Reset: 1711920000
Content-Type: application/json; charset=utf-8

To test the restrictive authentication endpoint limits, issue rapid consecutive requests:

for i in {1..5}; do
  curl -i -X POST http://localhost:3000/api/v1/auth/login \
    -H "Content-Type: application/json" \
    -d '{"email":"test@example.com","password":"wrong"}'
  echo "---"
done

By request 4, the token bucket exhausts its initial capacity of 3. The server immediately responds with HTTP 429:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 3
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1711920010
Retry-After: 10
Content-Type: application/json; charset=utf-8

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again later.",
  "retryAfterSeconds": 10
}

Redis Server Configuration Best Practices

  1. Maxmemory Policy: Configure your Redis instance with maxmemory-policy volatile-lru. This policy ensures that if Redis reaches memory capacity limits, it selectively drops rate limit keys that have an explicit TTL defined rather than dropping persistent application keys.
  2. Network Topology: Deploy Redis on the same local network or private VPC interface as your application servers (such as a private network on DigitalOcean). Eliminating public internet network latency keeps script evaluation times under 1 millisecond.
  3. Fail-Open Strategy: Notice how the try/catch block in our Express middleware defaults to invoking next() if Redis becomes unreachable. This design pattern ensures an unexpected Redis outage does not result in a total outage for your public application traffic.

Getting Started

By combining Redis Lua scripting with the Token Bucket algorithm, you get atomic rate limiting that scales effortlessly across distributed app clusters. You can deploy Redis and Node.js on a fast cloud server such as a Hetzner VPS or Contabo VPS. If you need custom domains for your microservices, secure them quickly via Namecheap.

Outsource Your Automation

Don’t have time? I build production n8n workflows, WhatsApp bots, and fully automated YouTube Shorts pipelines. Hire me on Fiverr, mention SYS3-HUGO for priority. Or DM at chasebot.online.

Want to automate this yourself?

Start with n8n Cloud (free tier available) or self-host on a Hetzner VPS for full control.

Want this engine running on your own VPS?

This blog publishes itself — daily, unattended, on free API tiers. The full engine, Hugo theme, and setup guide are available as System 3.

Get System 3
system online