Distributed Sliding Window Rate Limiter (Full Setup + Guide)

A production-style rate limiting system using:

• Node.js + Express (backend)
• Redis + Lua (atomic logic)
• React + Vite (dashboard)
• k6 (load testing)

This project shows how real systems handle concurrent traffic safely across multiple servers.

---

What’s Implemented

• Sliding Window Counter algorithm
• Redis-based distributed state
• Lua scripting for atomicity (no race conditions)
• Middleware-based rate limiting
• Real-time dashboard (logs + status)
• k6 load testing setup
• Simulated request buttons (frontend)

---

⚙️ Architecture

sequenceDiagram
    participant Client
    participant Node API (PM2)
    participant Redis

    Client->>Node API (PM2): HTTP Request
    Node API (PM2)->>Redis: Execute Lua Script (Current & Prev Keys)
    Note over Redis: Atomic execution:<br/>1. Read counts<br/>2. Calculate weighted avg<br/>3. Increment
    Redis-->>Node API (PM2): Return { allowed: 1/0, remaining }

    alt Allowed
        Node API (PM2)-->>Client: 200 OK (X-RateLimit Headers)
    else Blocked
        Node API (PM2)-->>Client: 429 Too Many Requests
    end

Loading

---

Backend Setup (core)

1 Install dependencies

pnpm install

---

2 Environment setup

Create .env:

PORT=3000
REDIS_URL=redis://localhost:6379
LIMIT=10
WINDOW_SIZE=10

---

3 Start Redis

If installed locally:

redis-server

Or using Docker:

docker run -p 6379:6379 redis

---

4 Build project

pnpm run build

---

5 Run server

pnpm run prod

Or dev mode:

pnpm run dev

---

Backend Scripts

"scripts": {
  "test": "k6 run dist/tests/k6-test.js",
  "build": "tsc",
  "dev": "nodemon dist/api.js",
  "prod": "node dist/api.js",
  "watch": "tsc -w"
}

---

Frontend Setup (client)

1 Install

pnpm install

---

2 Run dev server

pnpm run dev

Open:

http://localhost:5173

---

Dashboard Features

• Live logs
• Allowed / Blocked requests
• Remaining quota
• Manual testing buttons:
  • Single request
  • Burst mode
  • Gradual requests

---

k6 Setup (Load Testing)

---

Install k6

Linux:

sudo apt update
sudo apt install k6

If not available:

sudo snap install k6

---

Run test

pnpm run test

This executes:

k6 run dist/tests/k6-test.js

---

Optional dashboard

K6_WEB_DASHBOARD=true k6 run dist/tests/k6-test.js

Open:

http://localhost:5665

---

How Sliding Window Counter Works

We approximate a continuous sliding window using:

estimated = (prevCount * overlap) + currCount

Where:

overlap = 1 - (time_into_current_window / window_size)

---

Why It’s Not Perfectly Accurate

Because we assume:

requests in previous window were uniformly distributed

Reality:

• requests can be bursty
• timing info is lost

---

Example Problem

Previous window:

10 requests all happened at end

System assumes:

spread evenly → incorrect weighting

---

Tradeoffs

Pros

• Fast
• Memory efficient
• Works in distributed systems
• Prevents burst attacks

---

Cons

• Approximation (not exact)
• Floating point precision issues
• Depends on Redis
• Slight timing inaccuracies

---

Consistency Model

Strong Consistency (per request)

• Lua script runs atomically inside Redis
• No race conditions

Eventual Consistency (system-wide)

• Multiple servers rely on Redis
• Network delays possible

---

Why Lua Script?

Without Lua:

GET → CHECK → INCR race condition

With Lua:

ALL INSIDE REDIS atomic

---

Testing Scenarios

• Manual frontend clicks
• Burst requests
• Gradual requests
• k6 concurrent load

---

Monitoring

Dashboard shows:

• Timestamp
• User/IP
• Remaining quota
• Allowed/Blocked status

Helps visualize limiter behavior in real-time

---

Important Design Decisions

/logs is NOT rate limited

Why:

• monitoring should always be available
• needed during debugging/high load

---

Rate limiting only applied to:

/test-hit or specific endpoints

---

TL;DR

• Redis → shared state
• Lua → atomic execution
• Sliding window → smooth limiting
• k6 → load testing
• Dashboard → visibility

---

What Makes This Project Strong

• Handles real-world concurrency
• Uses distributed system design
• Includes observability + testing
• Covers tradeoffs (not just implementation)

---