Rate limiting is crucial in any system to prevent abuse, manage traffic, and protect your resources. By leveraging Redis and Lua, you'll build an efficient, scalable rate limiting system that can handle a large number of requests while keeping your backend services safe.

We will also include an interactive demo where users can simulate traffic, observe rate limits being enforced, and view logs of blocked requests.

What You Will Learn

• How to build a rate limiting system using Redis.

• How to use Lua scripts with Redis to achieve atomic operations.

• Understanding Redis data structures for efficient request tracking.

• Techniques for handling high traffic in a distributed system.

• Using Docker to simulate and scale a distributed rate limiter.

Prerequisites

Before starting, ensure you have the following installed:

• Node.js (v14 or higher)

• Redis

• Docker (for simulating a distributed environment)

• Basic understanding of Node.js, Redis, and Lua scripting.

Table of Contents

• What You Will Learn

• Prerequisites

• Project Overview

• Step 1: How to Set Up the Project

• Step 2: How to Set Up Redis

• Step 3: How to Implement the Rate Limiter with Redis and Lua

• Step 4: How to Create the Node.js API Server

• Step 5: How to Test the Rate Limiter

• Step 6: How to Visualize Rate Limiting Metrics

• Step 7: How to Deploy with Docker

• Conclusion: What You’ve Learned

Project Overview

In this tutorial, you will:

1. Build a rate limiter using Redis and Lua to enforce request quotas.

2. Use Lua scripts to ensure atomic operations, avoiding race conditions.

3. Implement a token bucket algorithm for rate limiting.

4. Create an interactive demo to simulate high traffic and visualize rate limiting in action.

System Architecture

You'll build the system with the following components:

1. API Server: Handles incoming user requests.

2. Redis: Stores request data and enforces rate limits.

3. Lua Scripts: Ensures atomic updates to Redis for rate limiting.

4. Docker: Simulates a distributed environment with multiple instances.

Step 1: How to Set Up the Project

Let's start by setting up our Node.js project:

mkdir distributed-rate-limiter
cd distributed-rate-limiter
npm init -y

Next, install the required dependencies:

npm install express redis dotenv

• express: A lightweight web server framework.

• redis: For interacting with Redis.

• dotenv: For managing environment variables.

Create a .env file with the following content:

REDIS_HOST=localhost
REDIS_PORT=6379
PORT=3000
RATE_LIMIT=5
TIME_WINDOW=60

These variables define the Redis host, port, rate limit (number of allowed requests), and the time window (in seconds).

Step 2: How to Set Up Redis

Before we dive into the code, ensure that Redis is installed and running on your system. If you don’t have Redis installed, you can use Docker to quickly set it up:

docker run -p 6379:6379 --name redis-rate-limiter -d redis

Step 3: How to Implement the Rate Limiter with Redis and Lua

To efficiently handle rate limiting, we'll use a token bucket algorithm. In this algorithm:

1. Each user has a “bucket” of tokens.

2. Each request consumes a token.

3. Tokens refill periodically at a set rate.

To ensure atomicity and avoid race conditions, we'll use Lua scripting with Redis. Lua scripts in Redis execute atomically, which means they can’t be interrupted by other operations while running.

How to Create a Lua Script for Rate Limiting

Create a file called rate_limiter.lua:

local key = KEYS[1]
local limit = tonumber(ARGV[1])
local window = tonumber(ARGV[2])
local current = redis.call("get", key)

if current and tonumber(current) >= limit then
    return 0
else
    if current then
        redis.call("incr", key)
    else
        redis.call("set", key, 1, "EX", window)
    end
    return 1
end

1. Inputs:

   • KEYS[1]: The Redis key representing the user’s request count.

   • ARGV[1]: The rate limit (maximum number of allowed requests).

   • ARGV[2]: The time window (in seconds) for the rate limit.

2. Logic:

   • If the user has reached the rate limit, return 0 (request blocked).

   • If the user is within the limit, increment their request count or set a new count with an expiration if it's the first request.

   • Return 1 (request allowed).

Step 4: How to Create the Node.js API Server

Create a file called server.js:

require('dotenv').config();
const express = require('express');
const redis = require('redis');
const fs = require('fs');
const path = require('path');

const app = express();
const client = redis.createClient({
  host: process.env.REDIS_HOST,
  port: process.env.REDIS_PORT
});

const rateLimitScript = fs.readFileSync(path.join(__dirname, 'rate_limiter.lua'), 'utf8');

const RATE_LIMIT = parseInt(process.env.RATE_LIMIT);
const TIME_WINDOW = parseInt(process.env.TIME_WINDOW);

// Middleware for rate limiting
async function rateLimiter(req, res, next) {
  const ip = req.ip;
  try {
    const allowed = await client.eval(rateLimitScript, 1, ip, RATE_LIMIT, TIME_WINDOW);
    if (allowed === 1) {
      next();
    } else {
      res.status(429).json({ message: 'Too many requests. Please try again later.' });
    }
  } catch (err) {
    console.error('Error in rate limiter:', err);
    res.status(500).json({ message: 'Internal server error' });
  }
}

app.use(rateLimiter);

app.get('/', (req, res) => {
  res.send('Welcome to the Rate Limited API!');
});

const PORT = process.env.PORT;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

1. Rate Limiter Middleware:

   • Retrieves the client's IP address and checks if they are within the rate limit using the Lua script.

   • If the user exceeds the limit, a 429 response is sent.

2. API Endpoint:

   • The root endpoint is rate-limited, so users can only access it a limited number of times within the specified window.

Step 5: How to Test the Rate Limiter

1. Start Redis:

    docker start redis-rate-limiter
   

2. Run the Node.js Server:

    node server.js
   

3. Simulate Requests:

   • Use curl or Postman to test the rate limiter:

       curl http://localhost:3000
     

   • Send multiple requests rapidly to see rate limiting in action.

Step 6: How to Visualize Rate Limiting Metrics

To monitor rate limiting metrics like cache hits and blocked requests, we'll add logging to the middleware in server.js:

async function rateLimiter(req, res, next) {
  const ip = req.ip;
  try {
    const allowed = await client.eval(rateLimitScript, 1, ip, RATE_LIMIT, TIME_WINDOW);
    if (allowed === 1) {
      console.log(`Allowed request from ${ip}`);
      next();
    } else {
      console.log(`Blocked request from ${ip}`);
      res.status(429).json({ message: 'Too many requests. Please try again later.' });
    }
  } catch (err) {
    console.error('Error in rate limiter:', err);
    res.status(500).json({ message: 'Internal server error' });
  }
}

Step 7: How to Deploy with Docker

Let’s containerize the application to run it in a distributed environment.

Create a Dockerfile:

FROM node:14
WORKDIR /app
COPY . .
RUN npm install
EXPOSE 3000
CMD ["node", "server.js"]

Build and Run the Docker Container:

docker build -t rate-limiter .
docker run -p 3000:3000 rate-limiter

Now you can scale the rate limiter by running multiple instances.

Conclusion: What You’ve Learned

Congratulations! You’ve successfully built a distributed rate limiter using Redis and Lua scripts. Throughout this tutorial, you’ve learned how to:

1. Implement rate limiting to control user requests in a distributed system.

2. Use Lua scripts in Redis to perform atomic operations.

3. Apply a token bucket algorithm to manage request quotas.

4. Monitor rate limiting metrics to optimize performance.

5. Use Docker to simulate a scalable distributed environment.

Next Steps:

1. Add Rate Limiting by User ID: Extend the system to support rate limits per user.

2. Integrate with Nginx: Use Nginx as a reverse proxy with Redis-backed rate limiting.

3. Deploy with Kubernetes: Scale your rate limiter using Kubernetes for high availability.

Happy coding!

We just published a full 11-hour game development course on the freeCodeCamp.org YouTube channel that will teach you how to create games using LÖVE 2D and Lua.

Steve from the Steve's Teacher YouTube channel teaches this course. Steve is an experienced game developer and he has created hundreds of programming tutorials.

LÖVE is as framework you can use to make 2D games in Lua. It's free, open-source, and works on Windows, Mac OS X, Linux, Android and iOS.

In this course, you will first learn how to program in Lua. Then you will learn how to use LÖVE 2D with Lua to develop amazing games. You will create two different games during this course.

Here are the sections in this comprehensive course:

LUA BASICS

• Intro to Lua
• Installing Lua
• Running Lua (VSCode)
• Printing and Comments
• Variables & Data Types
• Strings
• Math
• If Statements
• Loops
• User Input
• Tables
• Functions
• Working with Files
• Custom Modules
• OOP

LOVE 2D BASICS

• Setup and LUD basics
• The Config File
• Drawing & Moving Shapes
• Keyboard Input
• Working with Sprites

CREATING A SAVE THE BALL GAME

• Game Setup
• Creating the Enemy
• The Menu Screen
• Adding a Point System
• Game Over Screen

CREATING AN ASTEROIDS GAME

• Game Setup
• The Player
• The Thruster
• The Game State
• Game Text
• Asteroids
• Lasers
• Laser Collision Detection
• Player Collision Detection
• Player Lives
• The Menu
• Installing & Running LuaRocks
• The Score System
• Game Over
• Invincible PLayer & Infinite Levels
• Game Reset & High Score
• BGM & SFX

Watch the full course below or on the freeCodeCamp.org YouTube channel (11-hour watch).

Redis is a popular in-memory grid used for interprocess communication and data storage. You might’ve heard that it lets you run Lua scripts, but you are still not sure why. If this sounds like you, read on.

Prerequisites

You should have Redis installed on your system to follow this guide. It might be helpful to check Redis commands reference while reading.

Why do I need Lua Scripts?

In short: performance gain. Most tasks you do in Redis involve many steps. Instead of doing these steps in the language of your application, you can do it inside Redis with Lua.

• This may result in better performance.
• Also, all steps within a script are executed in an atomic way. No other Redis command can run while a script is executing.

For example, I use Lua scripts to change JSON strings stored in Redis. I describe this in detail closer to the end of this article.

But I don’t know any Lua

A person who doesn't know any lua

Don’t worry, Lua is not very hard to understand. If you know any language of the C family, you should be okay with Lua. Also, I am providing working examples in this article.

Show me an example

Let’s start by running scripts via redis-cli. Start it with:

redis-cli

Now run the following command:

eval “redis.call(‘set’, KEYS[1], ARGV[1])” 1 key:name value

The EVAL command is what tells Redis to run the script which follows. The ”redis.call(‘set’, KEYS[1], ARGV[1])”string is our script which is functionally identical to the Redis’s set command. Three parameters follow the script text:

1. The number of provided keys
2. Key name
3. First argument

Script arguments fall into two groups: KEYS and ARGV.

We specify how many keys the script requires with the number immediately following it. In our example, it is 1. Immediately after this number, we need to provide these keys, one after another. They are accessible as KEYS table within the script. In our case, it contains a single value key:name at index 1.

Note, that Lua indexed tables start with index 1, not 0.

We can provide any number of arguments after the keys, which will be available in Lua as the ARGV table. In this example, we provide a single ARGV-argument: string value. As you already guessed, the above command sets the key key:name to value value.

It is considered a good practice to provide keys which the script uses as KEYS, and all other arguments as ARGV. So you shouldn’t specify KEYS as 0 and then provide all keys within the ARGV table.

Let’s now check if the script completed successfully. We are going to do this by running another script which gets the key from Redis:

eval “return redis.call(‘get’, KEYS[1])” 1 key:name

The output should be ”value”, which means that the previous script successfully set the key “key:name”.

Can you explain the script?

Doge after seeing the script above

Our first script consists of a single statement: the redis.call function:

redis.call(‘set’, KEYS[1], ARGV[1])

Withredis.call you can execute any Redis command. The first argument is the name of this command followed by its parameters. In the case of the set command, these arguments are key and value. All Redis commands are supported. According to the documentation:

Redis uses the same Lua interpreter to run all the commands

Our second script does a little more than just running a single command — it also returns a value:

eval “return redis.call(‘get’, KEYS[1])” 1 key:name

Everything returned by the script is sent to the calling process. In our case, this process is redis-cli and you will see the result in your terminal window.

Something more complex?

A person planning to build a complex Redis script

I once used Lua scripts to return elements from a hash map in a particular order. The order itself was specified by hash keys stored in a sorted set.

Let’s first set up our data by running these commands in redis-cli:

hmset hkeys key:1 value:1 key:2 value:2 key:3 value:3 key:4 value:4 key:5 value:5 key:6 value:6
zadd order 1 key:3 2 key:1 3 key:2

These commands create a hash map at key hkeys and a sorted set at key order which contains selected keys from hkeys in a specific order.

You might want to check hmset and zadd commands reference for details.

Let’s run the following script:

eval “local order = redis.call(‘zrange’, KEYS[1], 0, -1); return redis.call(‘hmget’,KEYS[2],unpack(order));” 2 order hkeys

You should see the following output:

“value:3”
“value:1”
“value:2”

Which means that we got values of the keys we wanted and in the correct order.

Do I have to specify full script text to run it?

No! Redis allows you to preload a script into memory with the SCRIPT LOAD command:

script load “return redis.call(‘get’, KEYS[1])”

You should see an output like this:

“4e6d8fc8bb01276962cce5371fa795a7763657ae”

This is the unique hash of the script which you need to provide to the EVALSHA command to run the script:

evalsha 4e6d8fc8bb01276962cce5371fa795a7763657ae 1 key:name

Note: you should use actual SHA1 hash returned by the SCRIPT LOAD command, the hash above is only an example.

What did you mention about changing JSON?

Sometimes people store JSON objects in Redis. Whether it is a good idea or not is another story, but in practice, this happens a lot.

If you have to change a key in this JSON object, you need to get it from Redis, parse it, change the key, then serialize and set it back to Redis. There are a couple of problems with this approach:

1. Concurrency. Another process can change this JSON between our get and set operations. In this case, the change will be lost.
2. Performance. If you do these changes often enough and if the object is rather big, this might become the bottleneck of your app. You can win some performance by implementing this logic in Lua.

Let’s add a test JSON string to Redis under key obj:

set obj ‘{“a”:”foo”,”b”:”bar”}’

Now let’s run our script:

EVAL ‘local obj = redis.call(“get”,KEYS[1]); local obj2 = string.gsub(obj,”(“ .. ARGV[1] .. “\”:)([^,}]+)”, “%1” .. ARGV[2]); return redis.call(“set”,KEYS[1],obj2);’ 1 obj b bar2

Now we will have the following object under key obj:

{“a”:”foo”,”b”:”bar2"}

You can instead load this script with the SCRIPT LOAD command:

SCRIPT LOAD ‘local obj = redis.call(“get”,KEYS[1]); local obj2 = string.gsub(obj,”(“ .. ARGV[1] .. “\”:)([^,}]+)”, “%1” .. ARGV[2]); return redis.call(“set”,KEYS[1],obj2);’

and then run it like this:

EVALSHA <your_script_sha> 1 obj b bar2

Some notes:

• The .. is the string concatenation operator in Lua.
• We use a RegEx pattern to match key and replace its value. If you don’t understand this Regular Expression, you can check my recent guide.
• One difference of the Lua RegEx flavor from most other flavors is that we use % as both backreference mark and escape character for RegEx special symbols.
• We still escape ” with \ and not % because we escape Lua string delimiter, not RegEx special symbol.

Should I always use Lua scripts?

No. I recommend only using them when you can prove that it results in better performance. Always run benchmarks first.

If all you want is atomicity, then you should check Redis transactions instead.

Also, your script shouldn’t be too long. Remember that while a script is running, everything else is waiting for it to finish. If your script takes quite some time, it can cause bottlenecks instead of improving performance. The script stops after reaching a timeout (5 seconds by default).

Redis scripts should not take too much time

Last Word

For more information on Lua check lua.org.

You can check my node.js library on GitHub for some examples of Lua scripts (see src/lua folder). You can also use this library in node.js to change JSON objects without writing any Lua scripts yourself.

— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —

Thank you for reading this article. Questions and comments are much appreciated. You are also welcome to follow me on Twitter.

This lecture is part of CS50's Introduction to Game Development course from Harvard University. The course explores principles of 2D and 3D graphics, animation, sound, and collision detection using frameworks like Unity and LÖVE 2D, as well as languages like Lua and C#.

By end of the course (we're posting one lecture per day), you will have programmed several of your own games and gained a thorough understanding of the basics of game design and development.

This seventh lecture teaches all the key components of a Pokemon game.

You can watch the lecture on the freeCodeCamp.org YouTube channel. (2 hour watch)