Forem: Ajao Yussuf

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

Ajao Yussuf — 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)

Ajao Yussuf — 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