DEV Community: Yussuf Ajao

Building a stateless process supervisor in Go: what the OS fights you on

Yussuf Ajao — Tue, 09 Jun 2026 16:13:16 +0000

Most "run my stack locally" setups converge on one of:

a pile of terminal tabs and shell history,
Docker Compose (great when you want containers, heavy when you want a binary and a log file),
a real supervisor (supervisord, systemd user units) — powerful, but you are signing up for install surface, config dialects, and often a long-lived daemon.

I wanted something narrower: declare processes in YAML, start them in the background, know if they are alive, stop them predictably, tail logs, and reconcile config changes — without a resident agent. That constraint is the core design: each CLI invocation is a fresh process that reads YAML, inspects the filesystem under a well-known home, and mutates OS state (spawn, signal / terminate, unlink PID files).

This post is implementation-oriented: what invariants we keep, where the OS fights you, and why the boring parts (PID files, digests, polling) matter more than the CLI glue.

Model: stateless supervision

ops does not keep an in-memory registry. "What is running?" is always derived from:

On-disk PID files — ~/.ops/pids/<name>.pid (override base dir with OPS_HOME for tests and hermetic CI).
OS liveness — "does this PID still denote a live process?"

That makes the tool trivial to reason about in CI: no socket, no coordinator, no leader election. It also means no automatic restart unless something external calls ops start again. That is an explicit trade: simplicity and auditability over availability.

Filesystem contract: OpsHome and PID layout

Persistence is intentionally boring: default ~/.ops, overridable with OPS_HOME for tests and hermetic automation.

// internal/process/pid.go
func OpsHome() (string, error) {
    if override := os.Getenv("OPS_HOME"); override != "" {
        return override, nil
    }
    home, err := os.UserHomeDir()
    if err != nil {
        return "", fmt.Errorf("could not determine home directory: %w", err)
    }
    return filepath.Join(home, ".ops"), nil
}

PID files live under pids/; applied spec fingerprints under applied/ (shown next). Every CLI run re-derives "what is running?" from PID file + kernel, not from memory.

Under the ops home:

Path	Role
`pids/<name>.pid`	Integer PID written at successful start; removed on clean stop / stale cleanup
`applied/<name>.digest`	SHA-256 fingerprint of the applied process spec (see reload)

Invariant: a PID file is meaningful only if paired with a successful liveness check. Stale PIDs must converge to "not running" on status/stop paths, or operators stop trusting the tool.

Starting a child: isolation of concerns

At a high level, start:

validates config and name,
refuses double-start when PID file + liveness agree the child is up,
merges environment,
redirects child stdout/stderr to the configured log file (append semantics on disk),
records the child PID,
writes the applied digest so reload can tell whether the running world matches the declared world.

The parent CLI exits immediately after the child is spawned and recorded. There is no follow-up goroutine in the parent holding pipes open for streaming — logs are file-backed, which matters for the follow implementation below.

Reload: digest over the fields that actually matter

reload compares the YAML spec to the last applied digest. The fingerprint is deterministic: command, args, sorted env lines, log_file, and stop_timeout, then SHA-256. Sorting keys avoids spurious reloads when map iteration order changes.

// internal/process/applied.go
func ProcessDigest(p config.Process) string {
    var b strings.Builder
    b.WriteString(p.Command)
    b.WriteByte('\n')
    for _, a := range p.Args {
        b.WriteString(a)
        b.WriteByte('\n')
    }
    keys := make([]string, 0, len(p.Env))
    for k := range p.Env {
        keys = append(keys, k)
    }
    sort.Strings(keys)
    for _, k := range keys {
        fmt.Fprintf(&b, "%s=%s\n", k, p.Env[k])
    }
    b.WriteString(p.LogFile)
    fmt.Fprintf(&b, "\nstop_timeout=%d\n", p.StopTimeout)
    sum := sha256.Sum256([]byte(b.String()))
    return hex.EncodeToString(sum[:])
}

The interesting engineering point is not the hash — it is choosing which fields belong in the fingerprint. Omit something material and reload lies; include volatile fields and reload thrashes.

The reconcile loop unions names in YAML with names that still have PID files, then classifies each:

removed from YAML but still running → stop
unchanged digest → noop
changed digest while running → stop + restart
changed digest while stopped → update digest only

// internal/process/manager.go (excerpt)
func (m *Manager) Reload(dryRun bool) ([]ReloadStep, error) {
    // ...
    for _, name := range names {
        _, inYAML := m.Config.Processes[name]
        st, err := m.statusOne(name)
        // ...
        if !inYAML {
            if st.State == StateRunning || st.State == StateUnknown {
                // stopped_removed → Stop(...)
                continue
            }
            // noop: not in yaml, not running
            continue
        }
        proc := m.Config.Processes[name]
        want := ProcessDigest(proc)
        old, err := ReadAppliedDigest(name)
        // ...
        if old == want {
            // noop: spec unchanged
            continue
        }
        if st.State == StateRunning {
            // restarted → Stop then Start
            continue
        }
        // updated_stopped → WriteAppliedDigest only
    }
    return steps, nil
}

That structure is what keeps a stateless CLI honest: you can always print --dry-run steps, then execute the same transitions for real.

Logs: file-backed, follow without holding the child

ops logs opens the log path independently of whether the process is still running. That is a deliberate decoupling:

crash investigation still works after exit,
tailing does not require attaching to the original os/exec session.

--follow seeks to EOF and polls the file on a ticker, with a signal.NotifyContext cancellation path for SIGINT/SIGTERM when the CLI itself is in follow mode.

// internal/process/logs.go (excerpt)
func Follow(ctx context.Context, w io.Writer, path string, poll time.Duration) error {
    if poll <= 0 {
        poll = 300 * time.Millisecond
    }
    f, err := os.Open(path)
    if err != nil {
        return fmt.Errorf("%w: open log: %w", ErrOperation, err)
    }
    defer f.Close()
    // seek to end so we only see new content
    if _, err := f.Seek(0, io.SeekEnd); err != nil {
        return fmt.Errorf("%w: seek log: %w", ErrOperation, err)
    }
    ticker := time.NewTicker(poll)
    defer ticker.Stop()
    for {
        select {
        case <-ctx.Done():
            return nil
        case <-ticker.C:
            if err := followDrainGrowth(ctx, w, f, &pending, readChunk); err != nil {
                return err
            }
        }
    }
}

Polling costs a wake every few hundred milliseconds; the win is portable behavior without tying log tailing to the original exec session or platform-specific notify APIs (inotify, kqueue). For a dev tool, that tradeoff is correct.

isAlive: same symbol, mutually exclusive files

On Unix, "signal 0" via os.Process.Signal is the traditional existence probe: it does not deliver a signal, but errors if the process is gone or permissions deny the check.

On Windows, that story breaks down for arbitrary child PIDs. The implementation opens the process with limited rights, checks GetExitCodeProcess for the well-known STILL_ACTIVE (259) sentinel, and uses a zero-timeout WaitForSingleObject as a second check.

Unix:

// internal/process/isalive_unix.go
//go:build !windows

func isAlive(pid int) bool {
    proc, err := os.FindProcess(pid)
    if err != nil {
        return false
    }
    err = proc.Signal(syscall.Signal(0))
    return err == nil
}

Windows:

// internal/process/isalive_windows.go
//go:build windows

const stillActiveExitCode = 259

func isAlive(pid int) bool {
    if pid <= 0 {
        return false
    }
    access := uint32(windows.SYNCHRONIZE | windows.PROCESS_QUERY_LIMITED_INFORMATION)
    h, err := windows.OpenProcess(access, false, uint32(pid))
    if err != nil {
        return false
    }
    defer windows.CloseHandle(h)
    var exitCode uint32
    if err := windows.GetExitCodeProcess(h, &exitCode); err == nil && exitCode == stillActiveExitCode {
        return true
    }
    ev, werr := windows.WaitForSingleObject(h, 0)
    if werr != nil {
        return false
    }
    switch ev {
    case windows.WAIT_OBJECT_0:
        return false
    case 258: // WAIT_TIMEOUT
        return true
    default:
        return false
    }
}

Build tags (//go:build windows vs //go:build !windows) ensure exactly one implementation is linked per target GOOS — no #ifdef, no runtime dispatch table for this boundary. Same symbol, mutually exclusive compilation units.

Stopping: the Unix vs Windows semantic gap

Unix supervision has a comfortable story: SIGTERM for cooperative shutdown, SIGKILL as the irreversible backstop. You can encode product policy in that split — refusing SIGKILL unless the operator passes --force.

Windows is not a POSIX signal machine. A naive taskkill without /F often leaves a Go HTTP server happily running, which produces the classic failure mode: poll until timeout, then error — even though the operator asked to stop.

The Stop loop resolves timeout, calls gracefulStop, polls isAlive until deadline, then either errors (Unix, no --force) or proceeds to forceStop:

// internal/process/manager.go (excerpt)
deadline := time.Now().Add(stopTimeout)
for time.Now().Before(deadline) {
    if !isAlive(pid) {
        if err := RemovePID(name); err != nil {
            return fmt.Errorf("%w: remove pid for %q: %w", ErrOperation, name, err)
        }
        return nil
    }
    time.Sleep(500 * time.Millisecond)
}
if !isAlive(pid) {
    if err := RemovePID(name); err != nil {
        return fmt.Errorf("%w: remove pid for %q: %w", ErrOperation, name, err)
    }
    return nil
}
if !force && runtime.GOOS != "windows" {
    return fmt.Errorf("%w: process %q did not stop within %s", ErrOperation, name, stopTimeout)
}
if err := forceStop(pid); err != nil {
    // ...
}

The runtime.GOOS != "windows" branch is the policy seam: Unix keeps "no SIGKILL without --force" meaningful; Windows still gets a hard terminate path after the grace window because there is no separate SIGKILL tier in the kernel API you are targeting.

Unix — SIGTERM / SIGKILL:

// internal/process/stop_signal_unix.go
//go:build !windows

func gracefulStop(pid int) error {
    proc, err := os.FindProcess(pid)
    if err != nil {
        return fmt.Errorf("find process %d: %w", pid, err)
    }
    return proc.Signal(syscall.SIGTERM)
}

func forceStop(pid int) error {
    proc, err := os.FindProcess(pid)
    if err != nil {
        return fmt.Errorf("find process %d: %w", pid, err)
    }
    return proc.Signal(syscall.SIGKILL)
}

Windows — tree kill + TerminateProcess:

// internal/process/stop_signal_windows.go
//go:build windows

func gracefulStop(pid int) error {
    _ = exec.Command("taskkill", "/F", "/PID", strconv.Itoa(pid), "/T").Run()
    return nil
}

func forceStop(pid int) error {
    if !isAlive(pid) {
        return nil
    }
    h, err := windows.OpenProcess(windows.PROCESS_TERMINATE, false, uint32(pid))
    // ...
    if err := windows.TerminateProcess(h, 1); err != nil {
        // ...
    }
    return nil
}

gracefulStop intentionally ignores taskkill errors: the authority for "is it dead yet?" is isAlive polling in Stop, not the external tool's exit code.

Failure modes worth keeping in mind

Security: YAML selects arbitrary commands; treat it like code. Same class of risk as Make or CI YAML.
Permissions: terminating another user's process or protected processes will fail regardless of tool quality.
PID reuse race: narrow but real — short-lived processes and aggressive PID cycling on some systems mean "PID file says X" is always a hint until corroborated by the kernel.

Why Go for this

Go gives a single static binary distribution story, solid os/exec ergonomics, reasonable cross-compilation, and golang.org/x/sys/windows for the handful of syscalls you do not want to hand-roll. Cobra handles command routing and flag parsing. The intellectual weight is entirely in process state, not CLI glue.

Closing

ops is intentionally small: a filesystem-backed contract between CLI invocations, with explicit OS-specific adapters for the two places kernels disagree — liveness and termination. If that sounds interesting, the code is at https://github.com/carissaayo/go-ops-cli. The README is the operator manual; this post is the rationale.

Try it in one minute:

git clone https://github.com/carissaayo/go-ops-cli
cd go-ops-cli
go build -o ops ./internal/cmd/ops
# drop an ops.yaml beside the binary, then:
ops start <name>
ops status

If you have built something similar — or hit the Windows termination edge cases from a different angle — I'd like to hear how you handled it.

ops runs commands from your configuration. Only point it at projects and binaries you trust.

I Built a Tiny Database in Go to Understand How Real Ones Work

Yussuf Ajao — Fri, 01 May 2026 16:13:20 +0000

Most backend tutorials stop at the same point: put some data in a map, wrap it in an HTTP handler, call it a key-value store.

That's not wrong — it's just incomplete. It skips the question that separates backend engineers from storage engineers:

If the process dies mid-write, what do you still have on disk?

I built go-durable-kv to practice that question deliberately — Go standard library only, no external database, no ORM, no shortcuts.

Why This Problem Is Worth Practicing

Every production system that writes data eventually has to answer for a crash. Whether it's a database, a message queue, or a cache with persistence — the difference between "we lost some writes" and "we lost nothing" comes down to decisions made before the crash happened.

Those decisions are what this project is about.

What I Built

Component	What it does
Write-Ahead Log (WAL)	Persists every mutation to disk before updating memory
CRC32 checksums	Detects corruption during replay so recovery stops cleanly
Snapshots	Periodic full-state checkpoints that keep start-up time bounded
WAL Compaction	Resets the log after a snapshot so it doesn't grow forever
Multiple transports	HTTP, TCP, CLI — all backed by the same engine core

The One Invariant That Everything Else Depends On

Before walking through the implementation, this rule needs to be stated plainly:

WAL append happens before the in-memory map is updated. Always.

If you flip that order — update memory first, then write to disk — you create a window where the server can crash after acknowledging a write to the client, but before that write hits the log. The client thinks the data is safe. It isn't.

This ordering is the foundation. Everything else is built on top of it.

The Write Path

For a Set operation:

1. Validate — enforce constraints like maximum value size before touching disk.

2. Append to WAL — write a binary record with this layout:

Field	Size
Op (`Set` or `Delete`)	1 byte
Key length	4 bytes
Value length	4 bytes
Key bytes	variable
Value bytes	variable
CRC32 checksum	4 bytes

The CRC covers everything before it in the record. During recovery, any record that fails this check stops replay at the last clean prefix — no silent corruption, no poisoned state.

3. Apply durability policy — three modes, each a different tradeoff:

SyncAlways — flush + fsync after every write. Safest. Slowest.
SyncPeriodic — background goroutine syncs on a ticker. Middle ground.
SyncNone — relies on flush/close behavior. Fastest. Most data at risk in a crash.

This is the part many engineers treat as a binary ("durable" or "not durable"). It's actually a spectrum, and the right choice depends on what your application can tolerate losing.

4. Update the map — only after the WAL append succeeds.

5. Check compaction threshold — if the WAL has grown past MaxWALSizeBytes, trigger a snapshot and reset.

Delete follows the same path: append a tombstone record (zero-length value), then remove the key from the map.

The Read Path

Get acquires a read lock and returns directly from the in-memory map.

It does not touch disk.

This is intentional. Reads are the hot path. Once state is recovered on startup, they should be as fast as possible — a lock acquisition and a map lookup.

Recovery: How the Engine Restarts

On startup:

1. Load the snapshot — deserialize snapshot.gob into the in-memory map. This gives a fast baseline without replaying the entire log history.

2. Replay the WAL — read wal.log from the beginning, re-applying each record in order.

The tail policy matters here. If the WAL ends cleanly, replay succeeds. If it ends with a partial record or a CRC mismatch — which can happen on a hard crash — replay stops at the last known-good position. The partially-written record is discarded. This is how real storage engines handle torn writes, and it's a meaningful design choice: stop safely rather than panic the process.

Snapshots and Compaction

A snapshot is a full serialization of current state, written to disk using a three-step durability pattern:

1. Serialize state → snapshot.tmp
2. fsync snapshot.tmp
3. Atomically rename snapshot.tmp → snapshot.gob
4. Reset the WAL

The atomic rename is the key. If the process crashes between steps 1 and 3, the old snapshot.gob is still intact. You never read a partial snapshot because a partial snapshot never becomes the canonical file.

After the snapshot is confirmed, the WAL is reset. This bounds how much replay work the engine has to do on the next startup — no matter how long the process has been running.

Windows caveat: You can't truncate an open append file handle on Windows the same way you can on POSIX systems. The compaction step closes and reopens the WAL file rather than truncating in place. OS semantics are part of the implementation, not an afterthought.

Concurrency

A single sync.RWMutex protects the in-memory map and coordinates with the engine lifecycle:

Mutations acquire the write lock — they serialize
Get acquires the read lock — multiple readers proceed concurrently
The background sync goroutine must be stopped before the WAL closes — if it's still running when shutdown happens and tries to acquire a lock that the shutdown path holds, you get a deadlock

The HTTP server uses Server.Shutdown for graceful drain — in-flight requests complete before the engine flushes and closes.

Transports Are Adapters, Not the Engine

The core engine lives in internal/engine. It has no knowledge of HTTP or TCP. Transports are thin wrappers:

HTTP — PUT/GET/DELETE /keys/{key}, /health, /metrics using Go 1.22+ route patterns
TCP — newline-delimited JSON (set, get, delete, ping)
CLI — one TCP request per invocation; useful for scripts and manual testing

This separation is a design discipline, not just an organizational preference. It means the engine can be tested without spinning up a server. It means durability logic can't accidentally bleed into transport logic. And it means you can add a new transport without touching the storage layer.

Observability

A metrics struct tracks operation counters using sync/atomic — lock-free increments from multiple goroutines (handlers, replay, compaction, sync loop). /metrics returns JSON.

Atomics here instead of a mutex because the counters are hot-path and contention on a dedicated metrics lock would be unnecessary overhead for what is essentially fire-and-forget accounting.

Testing

Every durability claim has a test. The test suite covers:

Set/Get/Delete correctness, closed-engine behavior, value size limits
WAL encode/decode and full WAL integration paths
Replay across simulated process restarts (shared temp data directory)
Truncated tail and corrupt tail handling — not just happy-path recovery
Snapshot + compaction + "snapshot then WAL tail" restart scenarios
HTTP transport behavior including /metrics
Benchmarks in engine_bench_test.go for baseline performance numbers

The goal wasn't coverage for its own sake. It was: every claim this system makes about durability has a test that would catch a regression.

How to Run It

# Tests
go test ./...

# HTTP server on :4000
go run ./cmd/server

# TCP server on :5000
go run ./cmd/tcpserver

# CLI
go run ./cmd/cli --addr 127.0.0.1:5000 ping
go run ./cmd/cli --addr 127.0.0.1:5000 set mykey hello
go run ./cmd/cli --addr 127.0.0.1:5000 get mykey

Don't point both servers at the same ./data directory simultaneously — there's no cross-process locking, and a single engine owner per data directory is assumed.

What This Is Not

To be precise about scope:

Not a distributed system — no replication, no consensus
Not tuned for high throughput at scale
No multi-key transactions
SyncNone / SyncPeriodic leave some writes at risk in a hard crash — SyncAlways is the mode to reach for when durability matters more than write speed

What I Took Away

Durability is a policy, not a boolean. fsync costs something real. The right answer depends on what your application can tolerate losing, and that's a product decision as much as a technical one.

Recovery is where the real complexity lives. The write path is straightforward once you have the invariant. Recovery — especially torn writes, corrupt tails, the interaction between snapshot state and WAL replay — is where edge cases accumulate.

Thin transports pay off in testing. When the engine is a pure Go struct with no HTTP knowledge, you can test every failure scenario directly without mocking servers or parsing HTTP responses.

OS behavior is part of the implementation. File handle semantics on Windows, fsync guarantees on different filesystems, test cleanup when files are still open — these aren't platform footnotes. They're part of writing correct systems code.

Repo

👉 github.com/carissaayo/go-durable-kv

More detail in docs/architecture.md and the README.

If you're a senior engineer reading this — I'd be curious how you'd approach the compaction trigger. Size-based thresholds are simple, but time-based or operation-count-based have their own trade-offs. Drop it in the comments.

If you're earlier in your career: building something that has to survive a crash is one of the fastest ways to understand what databases are actually doing. You don't need to build PostgreSQL. You need to build something where the data has to still be there on restart.

Building a Production-Ready Rate Limiter with Redis in NestJS (Part 2: Multi-Tenant & Plan-Based Logic)

Yussuf Ajao — Wed, 07 Jan 2026 09:44:22 +0000

Building a Production-Ready Rate Limiter with Redis in NestJS (Part 2: Workspace-Aware Business Logic)

In Part 1, we built the core Redis rate limiter with atomic Lua scripts. Now we'll add the intelligence that makes it production-ready for a multi-tenant SaaS application.

What we're building:

Workspace-isolated rate limiting (Slack-style)
Plan-based limits (Free, Pro, Enterprise)
Security-focused limits for authentication
Standard HTTP rate limit headers
Smart identifier generation

This is the business logic layer that sits on top of our Redis implementation. Let's dive in.

The Challenge: Multi-Tenant Rate Limiting

In a SaaS application, you can't treat all requests equally. Consider these scenarios:

Workspace A on a Free plan shouldn't be able to exhaust the rate limit for Workspace B on an Enterprise plan
A user in Workspace A has different limits than the same user in Workspace B
Authentication endpoints need stricter limits regardless of subscription plan
Different HTTP methods need different limits (writes are more expensive than reads)

Traditional rate limiters use simple identifiers like IP address or user ID. We need something smarter.

Architecture Overview

Our RateLimitHandler service orchestrates the rate limiting strategy:

import { Injectable, HttpStatus, Logger } from '@nestjs/common';
import type { Request, Response } from 'express';
import { RateLimitConfig } from '../interfaces/security.interface';
import { RedisRateLimiter } from './redis-rate-limiter.service';

interface RequestWithWorkspace extends Request {
  workspace?: {
    id: string;
    slug: string;
    plan: string;
  };
  workspaceId?: string;
  user?: {
    id: string;
    _id?: string;
  };
}

@Injectable()
export class RateLimitHandler {
  private readonly logger = new Logger(RateLimitHandler.name);

  constructor(private readonly redisRateLimiter: RedisRateLimiter) {}
}

The RequestWithWorkspace interface extends Express's Request to include workspace context, which your authentication middleware should populate.

Smart Identifier Generation

The identifier is crucial - it determines the scope of rate limiting. Here's how we generate workspace-aware identifiers:

private getRateLimitIdentifier(req: RequestWithWorkspace): string {
  const ip = this.getClientIP(req);
  const userId = req.user?.id || req.user?._id || 'anonymous';
  const endpoint = req.route?.path || req.path;

  // Global routes (no workspace context needed)
  if (this.isGlobalRoute(req.path)) {
    return `global:${ip}:${userId}:${endpoint}`;
  }

  // Workspace routes (include workspace ID)
  const workspaceId = req.workspaceId || req.workspace?.id || 'unknown';
  return `workspace:${workspaceId}:${ip}:${userId}:${endpoint}`;
}

private isGlobalRoute(path: string): boolean {
  const globalRoutes = [
    '/auth/login',
    '/auth/register',
    '/auth/forgot-password',
    '/auth/reset-password',
    '/health',
    '/metrics',
  ];

  return globalRoutes.some((route) => path.startsWith(route));
}

private getClientIP(req: Request): string {
  const xfwd = (req.headers['x-forwarded-for'] as string | undefined)
    ?.split(',')[0]
    ?.trim();
  const xreal = (req.headers['x-real-ip'] as string | undefined)?.trim();
  const conn = (req as any).connection?.remoteAddress as string | undefined;
  const sock = (req.socket as any)?.remoteAddress as string | undefined;
  return xfwd || xreal || conn || sock || '127.0.0.1';
}

Why this structure matters:

Global routes - Authentication and health checks are identified by global: prefix. They're not workspace-specific, so a login attempt from Workspace A doesn't affect Workspace B.
Workspace routes - Include the workspace ID. This means:
- Each workspace has independent rate limits
- User Alice in Workspace A has separate limits from Alice in Workspace B
- This prevents "noisy neighbor" problems in multi-tenant systems
IP + User + Endpoint - The combination prevents:
- Single IP exhausting limits for all users (important in corporate networks)
- Single user exhausting limits across multiple IPs
- Different endpoints interfering with each other

Real-world example:

# Same user, different workspaces = different limits
workspace:ws_123:192.168.1.1:user_abc:/api/projects
workspace:ws_456:192.168.1.1:user_abc:/api/projects

# Same workspace, different endpoints = different limits  
workspace:ws_123:192.168.1.1:user_abc:/api/projects
workspace:ws_123:192.168.1.1:user_abc:/api/tasks

# Global routes = isolated from workspaces
global:192.168.1.1:anonymous:/auth/login

Context-Aware Rate Limit Configuration

Different routes need different strategies. Authentication endpoints need strict limits for security, while workspace operations vary by subscription plan:

private getRateLimitConfig(req: RequestWithWorkspace): RateLimitConfig {
  const path = req.path;
  const method = req.method;
  const plan = req.workspace?.plan || 'free';

  // Authentication routes - STRICT (global, no plan variation)
  if (path.includes('/auth/login')) {
    return {
      windowMs: 15 * 60 * 1000,        // 15 minutes
      maxRequests: 5,                   // Only 5 attempts
      blockDurationMs: 60 * 60 * 1000,  // 1 hour block
    };
  }

  if (path.includes('/auth/register')) {
    return {
      windowMs: 60 * 60 * 1000,         // 1 hour
      maxRequests: 3,                    // Only 3 registrations
      blockDurationMs: 24 * 60 * 60 * 1000, // 24 hour block
    };
  }

  if (path.includes('/auth/')) {
    return {
      windowMs: 5 * 60 * 1000,          // 5 minutes
      maxRequests: 10,
      blockDurationMs: 30 * 60 * 1000,  // 30 minutes block
    };
  }

  // Workspace-specific routes - PLAN-BASED
  return this.getWorkspaceRateLimitByPlan(plan, method);
}

Security-first design decisions:

Login limits are aggressive - 5 attempts in 15 minutes protects against brute force attacks. After 5 failures, the attacker is blocked for an hour.
Registration is even stricter - 3 registrations per hour prevents automated account creation. 24-hour block discourages abuse.
Authentication limits are global - They don't vary by subscription plan. Security is not a premium feature.
Progressive blocking - The blockDurationMs temporarily bans abusive users, giving your system time to recover.

Plan-Based Rate Limits

Here's where subscription tiers translate into actual technical limits:

private getWorkspaceRateLimitByPlan(
  plan: string,
  method: string,
): RateLimitConfig {
  const planLimits = {
    free: {
      POST: { windowMs: 60 * 1000, maxRequests: 20 },
      PUT: { windowMs: 60 * 1000, maxRequests: 20 },
      DELETE: { windowMs: 60 * 1000, maxRequests: 10 },
      PATCH: { windowMs: 60 * 1000, maxRequests: 20 },
      GET: { windowMs: 60 * 1000, maxRequests: 100 },
    },
    pro: {
      POST: { windowMs: 60 * 1000, maxRequests: 100 },
      PUT: { windowMs: 60 * 1000, maxRequests: 100 },
      DELETE: { windowMs: 60 * 1000, maxRequests: 50 },
      PATCH: { windowMs: 60 * 1000, maxRequests: 100 },
      GET: { windowMs: 60 * 1000, maxRequests: 500 },
    },
    enterprise: {
      POST: { windowMs: 60 * 1000, maxRequests: 1000 },
      PUT: { windowMs: 60 * 1000, maxRequests: 1000 },
      DELETE: { windowMs: 60 * 1000, maxRequests: 500 },
      PATCH: { windowMs: 60 * 1000, maxRequests: 1000 },
      GET: { windowMs: 60 * 1000, maxRequests: 5000 },
    },
  };

  const limits = planLimits[plan] || planLimits.free;
  const methodLimit = limits[method] || limits.GET;

  return {
    ...methodLimit,
    blockDurationMs: 5 * 60 * 1000, // 5 minutes block for all workspace operations
  };
}

Design rationale:

Write operations cost more - POST/PUT/PATCH operations are more expensive (database writes, validation, business logic). They get stricter limits.
DELETE is most restricted - Data deletion is sensitive and often irreversible. Even Enterprise gets fewer DELETE operations than other writes.
GET requests are abundant - Read operations are cheaper and more common. Free tier gets 100/min, Enterprise gets 5000/min.
Clear value ladder - Free → Pro = 5x increase, Pro → Enterprise = 10x increase. This creates a tangible reason to upgrade.
Consistent windows - All plans use 60-second windows for predictability. Users can easily reason about their limits.

Real-world comparison:

Free tier:    20 writes/min  = 1,200/hour   = ~29K/day
Pro tier:     100 writes/min = 6,000/hour   = ~144K/day  
Enterprise:   1,000 writes/min = 60,000/hour = ~1.4M/day

The Main Rate Limit Check

Now let's implement the method that ties it all together:

async checkRateLimit(
  req: RequestWithWorkspace,
  res: Response,
): Promise<boolean> {
  const identifier = this.getRateLimitIdentifier(req);
  const config = this.getRateLimitConfig(req);

  this.logger.debug(`Rate limit check - Identifier: ${identifier}`);

  const result = await this.redisRateLimiter.checkRateLimit(
    identifier,
    config,
    1, // increment by 1
  );

  // Set standard rate limit headers
  res.setHeader('X-RateLimit-Limit', config.maxRequests.toString());
  res.setHeader(
    'X-RateLimit-Remaining',
    Math.max(0, result.remaining).toString(),
  );
  res.setHeader('X-RateLimit-Reset', result.resetTime.toISOString());

  if (result.isBlocked) {
    if (result.retryAfter) {
      res.setHeader('Retry-After', result.retryAfter.toString());
    }

    this.logger.warn(`Rate limit exceeded for identifier: ${identifier}`);

    res.status(HttpStatus.TOO_MANY_REQUESTS).json({
      success: false,
      message: 'Too many requests. Please try again later.',
      retryAfter: result.retryAfter,
      timestamp: new Date().toISOString(),
    });
    return false;
  }

  return true;
}

What's happening here:

Generate context-aware identifier - Uses workspace, user, IP, and endpoint
Get appropriate config - Based on route type and subscription plan
Check with Redis - Our atomic Lua script handles the logic
Set response headers - Standard rate limit headers (more on this below)
Return structured error - If blocked, send 429 with retry information
Return boolean - Calling code can easily check if request should proceed

Standard Rate Limit Headers

Your API clients need to know their rate limit status. These headers follow RFC 6585 and common conventions:

// Always present
X-RateLimit-Limit: 100           // Maximum requests allowed in window
X-RateLimit-Remaining: 73        // Requests remaining before limit
X-RateLimit-Reset: 2026-01-07T15:30:00.000Z  // When counter resets

// Present when blocked (429 response)
Retry-After: 300                 // Seconds until unblocked

These headers let client applications:

Display accurate "X requests remaining" to users
Implement intelligent retry logic with exponential backoff
Show countdown timers until rate limit reset
Warn users before hitting limits

Client implementation example:

// Client-side handling
const response = await fetch('/api/projects', {
  method: 'POST',
  body: JSON.stringify(project),
});

if (response.status === 429) {
  const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
  console.log(`Rate limited. Retry in ${retryAfter} seconds`);

  // Show user-friendly message
  toast.error(`Too many requests. Please wait ${retryAfter} seconds.`);

  // Automatically retry after delay
  setTimeout(() => retryRequest(), retryAfter * 1000);
} else {
  const remaining = response.headers.get('X-RateLimit-Remaining');
  if (parseInt(remaining) < 10) {
    toast.warning('Approaching rate limit');
  }
}

Integration with NestJS Guards

To use this in your NestJS application, create a guard:

import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { RateLimitHandler } from './rate-limit-handler.service';
import { SKIP_RATE_LIMIT_KEY } from './decorators/skip-rate-limit.decorator';

@Injectable()
export class RateLimitGuard implements CanActivate {
  constructor(
    private readonly rateLimitHandler: RateLimitHandler,
    private readonly reflector: Reflector,
  ) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    // Check if rate limiting should be skipped
    const skipRateLimit = this.reflector.getAllAndOverride<boolean>(
      SKIP_RATE_LIMIT_KEY,
      [context.getHandler(), context.getClass()],
    );

    if (skipRateLimit) {
      return true;
    }

    const request = context.switchToHttp().getRequest();
    const response = context.switchToHttp().getResponse();

    return await this.rateLimitHandler.checkRateLimit(request, response);
  }
}

Custom Decorator for Skipping Rate Limits

For endpoints that shouldn't be rate limited (like health checks or internal admin routes), create a custom decorator:

// decorators/skip-rate-limit.decorator.ts
import { SetMetadata } from '@nestjs/common';

export const SKIP_RATE_LIMIT_KEY = 'skipRateLimit';
export const SkipRateLimit = () => SetMetadata(SKIP_RATE_LIMIT_KEY, true);

Then update your guard to respect this decorator (the guard code shown above already includes this):

Usage:

@Controller('health')
export class HealthController {
  @Get()
  @SkipRateLimit()  // This endpoint won't be rate limited
  check() {
    return { status: 'ok' };
  }
}

Apply globally:

// main.ts
import { RateLimitGuard } from './security/guards/rate-limit.guard';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Apply rate limiting to all routes
  app.useGlobalGuards(app.get(RateLimitGuard));

  await app.listen(3000);
}

Or selectively:

// controller.ts
@Controller('projects')
@UseGuards(RateLimitGuard)  // Apply to entire controller
export class ProjectsController {
  @Post()
  create(@Body() dto: CreateProjectDto) {
    // This endpoint is rate limited
  }

  @Get()
  @SkipRateLimit()  // Custom decorator to skip rate limiting
  findAll() {
    // This endpoint is NOT rate limited
  }
}

Real-World Production Scenarios

Let's walk through some practical examples:

Scenario 1: Normal User Activity

// User in Free tier workspace making requests
Request 1: POST /api/projects
→ Identifier: workspace:ws_free:192.168.1.1:user_123:/api/projects
→ Limit: 20/min
→ Result: ✅ Allowed (1/20 used)
→ Headers: X-RateLimit-Remaining: 19

Request 2: POST /api/projects (10 seconds later)
→ Same identifier
→ Result: ✅ Allowed (2/20 used)
→ Headers: X-RateLimit-Remaining: 18

Scenario 2: Hitting Rate Limit

// User makes 21st POST request in same minute
Request 21: POST /api/projects
→ Limit: 20/min
→ Result: ❌ Blocked
→ Status: 429 Too Many Requests
→ Headers:
    X-RateLimit-Limit: 20
    X-RateLimit-Remaining: 0
    X-RateLimit-Reset: 2026-01-07T15:31:00.000Z
    Retry-After: 37
→ Response: {
    success: false,
    message: "Too many requests. Please try again later.",
    retryAfter: 37
  }

Scenario 3: Workspace Isolation

// Same user, different workspaces
Workspace A (Free): POST /api/projects
→ Identifier: workspace:ws_free:192.168.1.1:user_123:/api/projects
→ Result: ❌ Blocked (hit 20/min limit)

Workspace B (Enterprise): POST /api/projects
→ Identifier: workspace:ws_ent:192.168.1.1:user_123:/api/projects
→ Result: ✅ Allowed (1/1000 used)
→ Different workspace = independent rate limit!

Scenario 4: Brute Force Protection

// Attacker trying to brute force login
Attempt 1-5: POST /auth/login (wrong password)
→ Identifier: global:192.168.1.1:anonymous:/auth/login
→ Result: ✅ Allowed (but login fails)

Attempt 6: POST /auth/login
→ Result: ❌ Blocked for 1 hour
→ Status: 429
→ Headers: Retry-After: 3600

// Even if they switch IPs, user-based blocking kicks in
// (if you track user ID in login attempts)

Module Setup

Wire everything together in your NestJS module:

// security.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { RedisRateLimiter } from './services/redis-rate-limiter.service';
import { RateLimitHandler } from './services/rate-limit-handler.service';
import { RateLimitGuard } from './guards/rate-limit.guard';

@Module({
  imports: [ConfigModule],
  providers: [
    RedisRateLimiter,
    RateLimitHandler,
    RateLimitGuard,
  ],
  exports: [
    RedisRateLimiter,
    RateLimitHandler,
    RateLimitGuard,
  ],
})
export class SecurityModule {}

Monitoring and Alerting

In production, you need visibility into rate limiting behavior:

// Add a monitoring endpoint (admin only)
@Controller('admin/rate-limits')
export class RateLimitMonitoringController {
  constructor(private readonly redisRateLimiter: RedisRateLimiter) {}

  @Get('top-consumers')
  async getTopConsumers() {
    return await this.redisRateLimiter.getTopConsumers(50);
  }

  @Get('health')
  async getHealth() {
    return await this.redisRateLimiter.healthCheck();
  }

  @Get('metrics')
  async getMetrics() {
    return await this.redisRateLimiter.getMetrics();
  }

  @Post('reset/:identifier')
  async resetLimit(@Param('identifier') identifier: string) {
    await this.redisRateLimiter.resetRateLimit(identifier);
    return { success: true, message: 'Rate limit reset' };
  }
}

Set up alerts:

// Use your monitoring service (DataDog, New Relic, etc.)
this.logger.warn(`Rate limit exceeded for ${identifier}`, {
  workspace: req.workspace?.id,
  user: req.user?.id,
  endpoint: req.path,
  plan: req.workspace?.plan,
});

// Alert if too many 429 responses
if (result.isBlocked) {
  this.metrics.increment('rate_limit.blocked', {
    plan: req.workspace?.plan,
    endpoint: req.path,
  });
}

Advanced Patterns

Per-Endpoint Overrides

// Some endpoints need custom limits
if (path.includes('/api/exports')) {
  return {
    windowMs: 60 * 60 * 1000,  // 1 hour
    maxRequests: 5,             // Only 5 exports/hour
    blockDurationMs: 0,         // Don't block, just limit
  };
}

User-Specific Overrides

// VIP users get higher limits
const userTier = await this.getUserTier(req.user?.id);
if (userTier === 'vip') {
  config.maxRequests *= 2;  // Double their limit
}

Burst Handling (Future Enhancement)

The current implementation uses fixed windows. For burst handling, you'd need to implement a token bucket algorithm:

// Future enhancement: Token bucket for burst handling
// This would require extending RateLimitConfig:
interface TokenBucketConfig extends RateLimitConfig {
  burstLimit: number;  // Maximum burst capacity
  refillRate: number;  // Tokens per second
}

// Example usage (not implemented in current version):
return {
  windowMs: 60 * 1000,
  maxRequests: 100,      // Average rate
  burstLimit: 150,       // Allow short bursts up to 150
  refillRate: 100 / 60,  // Refill at average rate
};

Note: This requires modifying the Lua script to implement token bucket logic. The current fixed-window implementation is simpler and sufficient for most use cases.

Testing Strategies

Unit Tests

describe('RateLimitHandler', () => {
  it('should use workspace-scoped identifiers', () => {
    const req = {
      workspace: { id: 'ws_123', plan: 'pro' },
      user: { id: 'user_456' },
      path: '/api/projects',
    } as any;

    const identifier = handler['getRateLimitIdentifier'](req);
    expect(identifier).toContain('workspace:ws_123');
    expect(identifier).toContain('user_456');
  });

  it('should apply stricter limits to free plans', () => {
    const freeConfig = handler['getWorkspaceRateLimitByPlan']('free', 'POST');
    const proConfig = handler['getWorkspaceRateLimitByPlan']('pro', 'POST');

    expect(freeConfig.maxRequests).toBe(20);
    expect(proConfig.maxRequests).toBe(100);
  });
});

Integration Tests

describe('Rate Limiting E2E', () => {
  it('should enforce plan-based limits', async () => {
    // Make 21 requests (Free tier limit is 20)
    const requests = Array(21).fill(null).map(() =>
      request(app.getHttpServer())
        .post('/api/projects')
        .set('Authorization', `Bearer ${freeUserToken}`)
        .send({ name: 'Test Project' })
    );

    const responses = await Promise.all(requests);

    const blocked = responses.filter(r => r.status === 429);
    expect(blocked.length).toBeGreaterThan(0);
  });
});

Performance Considerations

Based on production usage:

Latency Impact:

Rate limit check adds ~3-5ms per request (Redis latency)
Lua script execution: <1ms
Total overhead: ~5-7ms per request

Redis Memory:

~200 bytes per active rate limit key
100,000 active users = ~20MB
With TTL cleanup: memory stays stable

Throughput:

Single Redis instance: ~10,000 checks/second
Redis Cluster: 50,000+ checks/second
Bottleneck is usually network, not Redis

Common Pitfalls to Avoid

Don't use client IP alone - NAT and proxies mean multiple users share IPs
Don't forget X-Forwarded-For - You'll rate limit your load balancer instead of users
Don't block global routes by workspace - Authentication should be globally scoped
Don't use the same limits for all HTTP methods - Writes cost more than reads
Don't fail closed - If Redis is down, allow requests (fail open)
Don't forget about workspace isolation - Multi-tenancy is critical in SaaS

Key Takeaways

Building production-grade rate limiting for multi-tenant SaaS taught me:

Context is everything - Workspace-aware identifiers prevent noisy neighbor problems
Plan-based limits are a feature - Rate limits differentiate your pricing tiers
Security doesn't tier - Authentication limits should be strict for everyone
Headers matter - Standard rate limit headers enable smart client behavior
Fail open - Availability is more important than perfect rate limiting
Monitor everything - You need visibility into who's hitting limits and why

This implementation has been running in production for months, handling millions of requests across thousands of workspaces. It's proven reliable, performant, and maintainable.

What's Next?

Potential enhancements:

Sliding window algorithm for more precise limiting
Token bucket algorithm for burst handling
Distributed rate limiting across regions
Machine learning for anomaly detection
Dynamic limits based on system load

Have questions or improvements? I'd love to hear how you've implemented rate limiting in your SaaS applications!

Series recap:

Part 1: Core Redis implementation with Lua scripts
Part 2 (this article): Workspace-aware business logic

GitHub: Complete implementation with tests available in my repositories.

Tags: #nestjs #redis #ratelimiting #typescript #saas #multitenant #backend #nodejs

Building a Production-Ready Rate Limiter with Redis & Lua in NestJS (Part 1)

Yussuf Ajao — Wed, 07 Jan 2026 09:40:26 +0000

Building a Production-Ready Rate Limiter with Redis in NestJS (Part 1: Core Redis Implementation)

Rate limiting is critical for any production API - it protects your infrastructure from abuse, prevents DDoS attacks, and ensures fair resource allocation across users. After building several SaaS applications, I've learned that a good rate limiter needs to be more than just "X requests per minute."

In this two-part series, I'll walk you through building a production-grade rate limiter that I'm currently using in production. This isn't a basic tutorial - it's a battle-tested implementation that handles Redis cluster support, atomic operations with Lua scripts, and graceful degradation.

Part 1 (this article) covers the core Redis implementation with Lua scripts for atomic operations.

Part 2 will cover workspace-aware business logic, plan-based limits, and multi-tenancy considerations.

Why Redis for Rate Limiting?

Before diving into code, let's address the fundamental question: why Redis?

In-memory solutions (like storing counters in your Node.js process) work fine for single-server setups, but they break in distributed systems. If you're running multiple instances of your API (which you should be), each instance would have its own counter, making your rate limits ineffective.

Redis solves this by providing a centralized, extremely fast storage layer that all your API instances can share. It's perfect for rate limiting because:

Sub-millisecond read/write operations
Atomic operations via Lua scripts (no race conditions)
Built-in TTL (automatic key expiration)
Supports both single-instance and cluster deployments

The TypeScript Interfaces

First, let's define the contracts our rate limiter will work with:

export interface RateLimitConfig {
  windowMs: number;           // Time window in milliseconds
  maxRequests: number;        // Max requests allowed in window
  blockDurationMs?: number;   // How long to block after exceeding limit
}

export interface RateLimitResult {
  totalHits: number;          // Current request count
  resetTime: Date;            // When the window resets
  remaining: number;          // Requests remaining
  isBlocked: boolean;         // Whether the user is blocked
  retryAfter?: number;        // Seconds until unblocked
}

Setting Up the Redis Connection

Our RedisRateLimiter service needs to support multiple deployment scenarios - local development with a single Redis instance, production with Redis clusters, and cloud providers like Upstash or Railway.

import {
  Injectable,
  Logger,
  OnModuleInit,
  OnModuleDestroy,
} from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import Redis, { Cluster } from 'ioredis';
import { RateLimitResult, RateLimitConfig } from '../interfaces/security.interface';

@Injectable()
export class RedisRateLimiter implements OnModuleInit, OnModuleDestroy {
  private readonly logger = new Logger(RedisRateLimiter.name);
  private redis!: Redis | Cluster;
  private readonly keyPrefix = 'rate_limit:';
  private readonly blockPrefix = 'rate_limit_block:';

  constructor(private readonly configService: ConfigService) {}

  async onModuleInit() {
    await this.initializeRedis();
    this.startPeriodicCleanup();
  }

  async onModuleDestroy() {
    if (this.redis) {
      await this.redis.disconnect?.();
    }
  }

  private async initializeRedis(): Promise<void> {
    const redisConfig = this.getRedisConfig();

    try {
      if (redisConfig.cluster && redisConfig.cluster.length > 0) {
        // Redis Cluster for high availability
        this.redis = new Redis.Cluster(redisConfig.cluster, {
          redisOptions: {
            password: redisConfig.password,
            db: redisConfig.db,
            keyPrefix: this.keyPrefix,
            maxRetriesPerRequest: 3,
            lazyConnect: true,
            keepAlive: 30000,
            connectTimeout: 10000,
            commandTimeout: 5000,
          },
          enableOfflineQueue: false,
          retryDelayOnFailover: 100,
          scaleReads: 'slave',
        });
      } else if (redisConfig.url) {
        // Single instance via URL (Render, Upstash, Railway)
        this.redis = new Redis(redisConfig.url, {
          keyPrefix: this.keyPrefix,
          lazyConnect: true,
          maxRetriesPerRequest: 3,
          keepAlive: 30000,
          connectTimeout: 10000,
          commandTimeout: 5000,
        });
      } else {
        // Single instance via host/port (local development)
        this.redis = new Redis({
          host: redisConfig.host,
          port: redisConfig.port,
          password: redisConfig.password,
          db: redisConfig.db,
          keyPrefix: this.keyPrefix,
          lazyConnect: true,
          maxRetriesPerRequest: 3,
          keepAlive: 30000,
          connectTimeout: 10000,
          commandTimeout: 5000,
        });
      }

      // Event handlers for monitoring
      this.redis.on('connect', () => this.logger.log('Connected to Redis'));
      this.redis.on('error', (error) =>
        this.logger.error('Redis connection error:', error),
      );
      this.redis.on('close', () => this.logger.warn('Redis connection closed'));
      this.redis.on('reconnecting', () =>
        this.logger.log('Reconnecting to Redis...'),
      );

      await this.redis.ping();
      this.logger.log('Redis rate limiter initialized successfully');
    } catch (error) {
      this.logger.error('Failed to initialize Redis:', error);
      throw error;
    }
  }

  private getRedisConfig() {
    const clusterNodes = this.configService.get<string>('REDIS_CLUSTER_NODES');
    return {
      url: this.configService.get<string>('REDIS_URL'),
      host: this.configService.get<string>('REDIS_HOST', 'localhost'),
      port: Number(this.configService.get<number>('REDIS_PORT', 6379)),
      password: this.configService.get<string>('REDIS_PASSWORD'),
      db: Number(this.configService.get<number>('REDIS_DB', 0)),
      cluster: clusterNodes
        ? clusterNodes.split(',').map((node: string) => {
            const [host, port] = node.split(':');
            return { host, port: parseInt(port || '6379', 10) };
          })
        : undefined,
    };
  }
}

Key design decisions here:

Flexible configuration - Works with Redis URLs, host/port combos, or cluster nodes
Lazy connection - Doesn't block app startup if Redis is temporarily unavailable
Comprehensive event handlers - Logs all connection state changes for debugging
Sensible timeouts - 10s connect timeout, 5s command timeout prevents hanging requests

The Magic: Lua Scripts for Atomic Operations

Here's where things get interesting. Rate limiting requires multiple operations:

Check if user is currently blocked
Get current request count
Check if time window expired
Increment counter
Set/update expiry
Determine if limit exceeded
Optionally block the user

If you do these as separate Redis commands, you'll have race conditions. Two requests arriving simultaneously could both read the counter before either increments it, allowing both through even if they should exceed the limit.

The solution: Lua scripts. Redis executes Lua scripts atomically - no other operation can run while your script is executing.

private readonly rateLimitScript = `
  local key = KEYS[1]
  local block_key = KEYS[2]
  local window = tonumber(ARGV[1])
  local limit = tonumber(ARGV[2])
  local now = tonumber(ARGV[3])
  local block_duration = tonumber(ARGV[4])
  local increment = tonumber(ARGV[5])

  -- Check if currently blocked
  local blocked_until = redis.call('GET', block_key)
  if blocked_until then
    blocked_until = tonumber(blocked_until)
    if now < blocked_until then
      local remaining_block = blocked_until - now
      return {0, blocked_until, 0, 1, remaining_block}
    else
      redis.call('DEL', block_key)
    end
  end

  -- Get current count and expiry
  local current = redis.call('HMGET', key, 'count', 'reset_time')
  local count = tonumber(current[1]) or 0
  local reset_time = tonumber(current[2]) or 0

  -- Check if window has expired
  if now >= reset_time then
    count = 0
    reset_time = now + window
  end

  -- Increment counter
  if increment > 0 then
    count = count + increment
  end

  -- Store new values with TTL
  redis.call('HMSET', key, 'count', count, 'reset_time', reset_time)
  redis.call('EXPIRE', key, math.ceil(window / 1000))

  local remaining = math.max(0, limit - count)
  local is_blocked = 0
  local retry_after = 0

  -- Block if limit exceeded
  if count > limit then
    is_blocked = 1
    if block_duration > 0 then
      local block_until = now + block_duration
      redis.call('SETEX', block_key, math.ceil(block_duration / 1000), block_until)
      retry_after = block_duration
    else
      retry_after = reset_time - now
    end
  end

  return {count, reset_time, remaining, is_blocked, retry_after}
`;

What this script does:

Block checking first - If the user is blocked, we return immediately without even checking the counter. This is a performance optimization.
Fixed window algorithm - We use fixed time windows (e.g., "60 seconds starting from first request"). This is simpler than sliding windows but can allow brief bursts at window boundaries.
Progressive blocking - When limit is exceeded, we can temporarily block the user for a specified duration. This prevents repeated violations.
Single round-trip - All operations happen in one Redis call, minimizing latency.
Automatic cleanup - The EXPIRE command ensures keys are automatically deleted after the window passes.

The Rate Limit Check Method

Now let's implement the method that calls our Lua script:

async checkRateLimit(
  identifier: string,
  config: RateLimitConfig,
  increment: number = 1,
): Promise<RateLimitResult> {
  try {
    const key = this.getRateLimitKey(identifier);
    const blockKey = this.getBlockKey(identifier);
    const now = Date.now();

    const result = await this.redis.eval(
      this.rateLimitScript,
      2, // number of keys
      key,
      blockKey,
      config.windowMs.toString(),
      config.maxRequests.toString(),
      now.toString(),
      (config.blockDurationMs || 0).toString(),
      increment.toString(),
    );

    const [count, resetTime, remaining, isBlocked, retryAfter] = result;

    return {
      totalHits: count,
      resetTime: new Date(resetTime),
      remaining: remaining,
      isBlocked: Boolean(isBlocked),
      retryAfter: retryAfter > 0 ? Math.ceil(retryAfter / 1000) : undefined,
    };
  } catch (error) {
    this.logger.error(
      `Rate limit check failed for ${identifier}:`,
      error as Error,
    );
    // FAIL OPEN - allow request if Redis is down
    return {
      totalHits: 0,
      resetTime: new Date(Date.now() + config.windowMs),
      remaining: config.maxRequests,
      isBlocked: false,
    };
  }
}

private getRateLimitKey(identifier: string): string {
  return `${this.keyPrefix}${identifier}`;
}

private getBlockKey(identifier: string): string {
  return `${this.blockPrefix}${identifier}`;
}

Critical decision: Fail open, not closed

Notice the catch block - when Redis fails, we return a permissive result rather than blocking all requests. This is intentional. A rate limiter outage shouldn't take down your entire API. Temporary over-usage is better than a complete service outage.

In production, you should:

Monitor Redis health closely
Set up alerts for rate limiter failures
Have a plan to scale or failover Redis quickly

Utility Methods for Observability

Production systems need visibility. Here are essential utility methods:

// Manual reset (for customer support)
async resetRateLimit(identifier: string): Promise<void> {
  try {
    const key = this.getRateLimitKey(identifier);
    const blockKey = this.getBlockKey(identifier);
    await Promise.all([
      this.redis.del(key),
      this.redis.del(blockKey),
    ]);
    this.logger.log(`Rate limit reset for ${identifier}`);
  } catch (error) {
    this.logger.error(
      `Failed to reset rate limit for ${identifier}:`,
      error as Error,
    );
  }
}

// Get current status (for debugging)
async getRateLimitInfo(identifier: string): Promise<{
  count: number;
  resetTime: Date;
  isBlocked: boolean;
  blockedUntil?: Date;
} | null> {
  try {
    const key = this.getRateLimitKey(identifier);
    const blockKey = this.getBlockKey(identifier);

    const [rateLimitData, blockedUntil] = await Promise.all([
      this.redis.hmget(key, 'count', 'reset_time'),
      this.redis.get(blockKey),
    ]);

    if ((!rateLimitData || !rateLimitData[0]) && !blockedUntil) {
      return null;
    }

    return {
      count: parseInt(rateLimitData?.[0] || '0', 10),
      resetTime: new Date(parseInt(rateLimitData?.[1] || '0', 10)),
      isBlocked: Boolean(blockedUntil),
      blockedUntil: blockedUntil
        ? new Date(parseInt(blockedUntil, 10))
        : undefined,
    };
  } catch (error) {
    this.logger.error(
      `Failed to get rate limit info for ${identifier}:`,
      error as Error,
    );
    return null;
  }
}

// Find abusive users (for monitoring)
async getTopConsumers(limit: number = 10): Promise<
  Array<{
    identifier: string;
    count: number;
    resetTime: Date;
  }>
> {
  try {
    const consumers = [];
    let cursor = '0';
    const batchSize = 100;

    // Use SCAN instead of KEYS to avoid blocking Redis
    do {
      const [nextCursor, keys] = await this.redis.scan(
        cursor,
        'MATCH',
        `${this.keyPrefix}*`,
        'COUNT',
        batchSize,
      );
      cursor = nextCursor;

      if (keys.length > 0) {
        const pipeline = this.redis.pipeline();
        keys.forEach((key) => {
          pipeline.hmget(key, 'count', 'reset_time');
        });

        const results = await pipeline.exec();

        results?.forEach((result, index) => {
          const data = result?.[1];
          if (data) {
            const [count, resetTime] = data;
            consumers.push({
              identifier: keys[index].replace(this.keyPrefix, ''),
              count: parseInt(count || '0', 10),
              resetTime: new Date(parseInt(resetTime || '0', 10)),
            });
          }
        });
      }
    } while (cursor !== '0');

    return consumers.sort((a, b) => b.count - a.count).slice(0, limit);
  } catch (error) {
    this.logger.error('Failed to get top consumers:', error as Error);
    return [];
  }
}

// Health check for monitoring systems
async healthCheck(): Promise<{
  status: 'healthy' | 'unhealthy';
  latency?: number;
  error?: string;
}> {
  try {
    const start = Date.now();
    await this.redis.ping();
    const latency = Date.now() - start;
    return { status: 'healthy', latency };
  } catch (error) {
    return {
      status: 'unhealthy',
      error: error instanceof Error ? error.message : 'Unknown error',
    };
  }
}

// Get metrics for monitoring dashboards
async getMetrics(): Promise<{
  totalKeys: number;
  memoryUsage: string;
  topConsumers: Array<{
    identifier: string;
    count: number;
    resetTime: Date;
  }>;
  health: {
    status: 'healthy' | 'unhealthy';
    latency?: number;
    error?: string;
  };
}> {
  try {
    const [topConsumers, health] = await Promise.all([
      this.getTopConsumers(10),
      this.healthCheck(),
    ]);

    // Count total keys using SCAN (non-blocking)
    let totalKeys = 0;
    let cursor = '0';
    do {
      const [nextCursor, keys] = await this.redis.scan(
        cursor,
        'MATCH',
        `${this.keyPrefix}*`,
        'COUNT',
        1000,
      );
      cursor = nextCursor;
      totalKeys += keys.length;
    } while (cursor !== '0');

    // Get memory info if available
    let memoryUsage = 'N/A';
    try {
      const info = await this.redis.info('memory');
      const usedMemoryMatch = info.match(/used_memory:(\d+)/);
      if (usedMemoryMatch) {
        const bytes = parseInt(usedMemoryMatch[1], 10);
        memoryUsage = `${(bytes / 1024 / 1024).toFixed(2)} MB`;
      }
    } catch {
      // Memory info not available in all Redis configurations
    }

    return {
      totalKeys,
      memoryUsage,
      topConsumers,
      health,
    };
  } catch (error) {
    this.logger.error('Failed to get metrics:', error as Error);
    return {
      totalKeys: 0,
      memoryUsage: 'Error',
      topConsumers: [],
      health: {
        status: 'unhealthy',
        error: error instanceof Error ? error.message : 'Unknown error',
      },
    };
  }
}

Memory Management: Automated Cleanup

Rate limiting can create thousands of keys. Even with TTL, you want proactive cleanup:

private readonly cleanupScript = `
  local pattern = ARGV[1]
  local batch_size = tonumber(ARGV[2]) or 100
  local cursor = "0"
  local deleted = 0

  repeat
    local scan_result = redis.call('SCAN', cursor, 'MATCH', pattern, 'COUNT', batch_size)
    cursor = scan_result[1]
    local keys = scan_result[2]

    if #keys > 0 then
      -- Use table.unpack for Lua 5.2+, fallback to unpack for 5.1
      local unpack_func = table.unpack or unpack
      deleted = deleted + redis.call('DEL', unpack_func(keys))
    end
  until cursor == "0"

  return deleted
`;

async cleanupExpiredKeys(): Promise<number> {
  try {
    const deleted = await this.redis.eval(
      this.cleanupScript,
      0,
      `${this.keyPrefix}*`,
      '1000', // batch size
    );

    if (deleted > 0) {
      this.logger.log(`Cleaned up ${deleted} expired rate limit keys`);
    }

    return deleted;
  } catch (error) {
    this.logger.error('Failed to cleanup expired keys:', error as Error);
    return 0;
  }
}

private startPeriodicCleanup(): void {
  // Clean up expired keys every 5 minutes
  setInterval(
    async () => {
      await this.cleanupExpiredKeys();
    },
    5 * 60 * 1000,
  );
}

Why automated cleanup matters:

Redis's passive expiration might not be aggressive enough under load
Proactive cleanup prevents memory bloat
The SCAN command (not KEYS) won't block Redis for other operations

Environment Variables Setup

# Single Redis instance via URL (recommended for cloud providers)
REDIS_URL=redis://username:password@host:port/db

# Or separate configuration (for local development)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your-password
REDIS_DB=0

# Redis Cluster (for high availability)
REDIS_CLUSTER_NODES=node1:6379,node2:6379,node3:6379

Testing the Rate Limiter

For unit tests, mock the Redis client:

describe('RedisRateLimiter', () => {
  let rateLimiter: RedisRateLimiter;
  let mockRedis: jest.Mocked<Redis>;

  beforeEach(() => {
    mockRedis = {
      eval: jest.fn(),
      ping: jest.fn().mockResolvedValue('PONG'),
      on: jest.fn(),
      disconnect: jest.fn(),
    } as any;

    // Inject mock
    rateLimiter = new RedisRateLimiter(configService);
    (rateLimiter as any).redis = mockRedis;
  });

  it('should allow requests under limit', async () => {
    mockRedis.eval.mockResolvedValue([5, Date.now() + 60000, 95, 0, 0]);

    const result = await rateLimiter.checkRateLimit('test-user', {
      windowMs: 60000,
      maxRequests: 100,
    });

    expect(result.isBlocked).toBe(false);
    expect(result.remaining).toBe(95);
  });

  it('should block requests over limit', async () => {
    mockRedis.eval.mockResolvedValue([101, Date.now() + 60000, 0, 1, 300000]);

    const result = await rateLimiter.checkRateLimit('test-user', {
      windowMs: 60000,
      maxRequests: 100,
      blockDurationMs: 300000,
    });

    expect(result.isBlocked).toBe(true);
    expect(result.retryAfter).toBe(300);
  });

  it('should fail open when Redis is down', async () => {
    mockRedis.eval.mockRejectedValue(new Error('Redis connection failed'));

    const result = await rateLimiter.checkRateLimit('test-user', {
      windowMs: 60000,
      maxRequests: 100,
    });

    expect(result.isBlocked).toBe(false);
    expect(result.remaining).toBe(100);
  });
});

Performance Characteristics

In production, this implementation handles:

~10,000 checks/second on a single Redis instance (t3.small)
Sub-5ms latency for rate limit checks (including network)
Millions of unique identifiers without memory issues
Zero race conditions thanks to Lua scripts

What's Next?

In Part 2, we'll build the business logic layer that uses this Redis rate limiter. We'll cover:

Workspace-aware rate limiting for multi-tenant SaaS
Plan-based limits (Free vs Pro vs Enterprise)
Security-focused limits for authentication endpoints
Standard rate limit HTTP headers
Handling different routes with different strategies
Real production configuration examples

The core Redis implementation we built today provides the foundation - atomic, fast, and reliable. In the next article, we'll add the intelligence that makes it production-ready for a real SaaS application.

Questions about the implementation? Drop a comment below! I'd love to hear about your rate limiting challenges.

Coming up in Part 2: Workspace-aware business logic, plan-based limits, and multi-tenancy strategies.

Tags: #nestjs #redis #ratelimiting #typescript #backend #nodejs #lua #performance