nestjs-cluster-throttle 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 White Rabbit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,308 @@
+# nestjs-cluster-throttle
+
+Cluster-ready rate limiting module for NestJS with Redis support and multiple rate limiting strategies.
+
+## Features
+
+- 🚀 **Cluster-ready** - Works seamlessly in clustered environments
+- 🔴 **Redis support** - Distributed rate limiting with Redis
+- 💾 **Memory storage** - In-memory storage for single-instance applications
+- 🎯 **Flexible strategies** - Support for fixed-window, token-bucket, and sliding-window algorithms
+- 🎨 **Decorator-based** - Easy-to-use decorators for route protection
+- ⚙️ **Highly configurable** - Customize limits, windows, and behavior
+- 🔒 **Type-safe** - Written in TypeScript with full type support
+- 🛡️ **Fail-open strategy** - Gracefully handles storage failures
+
+## Installation
+
+```bash
+npm install nestjs-cluster-throttle ioredis
+# or
+yarn add nestjs-cluster-throttle ioredis
+```
+
+## Quick Start
+
+### Basic Usage (In-Memory)
+
+```typescript
+import { Module } from '@nestjs/common';
+import { RateLimitModule } from 'nestjs-cluster-throttle';
+
+@Module({
+  imports: [
+    RateLimitModule.forRoot({
+      windowMs: 15 * 60 * 1000, // 15 minutes
+      max: 100, // limit each IP to 100 requests per windowMs
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Redis-based (Cluster Mode)
+
+```typescript
+import { Module } from '@nestjs/common';
+import { RateLimitModule } from 'nestjs-cluster-throttle';
+
+@Module({
+  imports: [
+    RateLimitModule.forRoot({
+      windowMs: 15 * 60 * 1000,
+      max: 100,
+      clusterMode: true,
+      redisOptions: {
+        host: 'localhost',
+        port: 6379,
+        password: 'your-password', // optional
+        db: 0,
+        keyPrefix: 'rate-limit:',
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Async Configuration
+
+```typescript
+import { Module } from '@nestjs/common';
+import { RateLimitModule } from 'nestjs-cluster-throttle';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+
+@Module({
+  imports: [
+    RateLimitModule.forRootAsync({
+      imports: [ConfigModule],
+      useFactory: async (configService: ConfigService) => ({
+        windowMs: configService.get('RATE_LIMIT_WINDOW_MS'),
+        max: configService.get('RATE_LIMIT_MAX'),
+        clusterMode: true,
+        redisOptions: {
+          host: configService.get('REDIS_HOST'),
+          port: configService.get('REDIS_PORT'),
+          password: configService.get('REDIS_PASSWORD'),
+        },
+      }),
+      inject: [ConfigService],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Usage in Controllers
+
+### Route-specific Rate Limiting
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { RateLimit } from 'nestjs-cluster-throttle';
+
+@Controller('api')
+export class ApiController {
+  @Get('limited')
+  @RateLimit({
+    windowMs: 60 * 1000, // 1 minute
+    max: 10, // 10 requests per minute
+    message: 'Too many requests from this IP',
+    statusCode: 429,
+  })
+  limitedEndpoint() {
+    return { message: 'This endpoint is rate limited' };
+  }
+
+  @Get('public')
+  publicEndpoint() {
+    return { message: 'This endpoint uses global rate limits' };
+  }
+}
+```
+
+### Skip Rate Limiting
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { SkipRateLimit } from 'nestjs-cluster-throttle';
+
+@Controller('api')
+export class ApiController {
+  @Get('health')
+  @SkipRateLimit()
+  healthCheck() {
+    return { status: 'ok' };
+  }
+}
+```
+
+## Advanced Configuration
+
+### Custom Key Generator
+
+Use custom logic to generate rate limit keys:
+
+```typescript
+RateLimitModule.forRoot({
+  windowMs: 15 * 60 * 1000,
+  max: 100,
+  keyGenerator: (request) => {
+    // Rate limit by user ID instead of IP
+    return request.user?.id || request.ip;
+  },
+})
+```
+
+### Skip Requests Conditionally
+
+```typescript
+RateLimitModule.forRoot({
+  windowMs: 15 * 60 * 1000,
+  max: 100,
+  skip: (request) => {
+    // Skip rate limiting for admin users
+    return request.user?.role === 'admin';
+  },
+})
+```
+
+### Custom Handler
+
+```typescript
+RateLimitModule.forRoot({
+  windowMs: 15 * 60 * 1000,
+  max: 100,
+  handler: (request, response) => {
+    // Custom handling when rate limit is exceeded
+    response.status(429).json({
+      error: 'Rate limit exceeded',
+      retryAfter: response.getHeader('X-RateLimit-Reset'),
+    });
+  },
+})
+```
+
+### Skip Successful Requests
+
+Only count failed requests towards the rate limit:
+
+```typescript
+RateLimitModule.forRoot({
+  windowMs: 15 * 60 * 1000,
+  max: 100,
+  skipSuccessfulRequests: true,
+})
+```
+
+## Rate Limiting Strategies
+
+### Fixed Window (Default)
+
+```typescript
+RateLimitModule.forRoot({
+  windowMs: 60 * 1000,
+  max: 100,
+  strategy: 'fixed-window',
+})
+```
+
+### Token Bucket
+
+```typescript
+RateLimitModule.forRoot({
+  windowMs: 60 * 1000,
+  max: 100,
+  strategy: 'token-bucket',
+  burstCapacity: 150, // Allow bursts up to 150 requests
+  fillRate: 100, // Refill 100 tokens per windowMs
+})
+```
+
+### Sliding Window
+
+```typescript
+RateLimitModule.forRoot({
+  windowMs: 60 * 1000,
+  max: 100,
+  strategy: 'sliding-window',
+})
+```
+
+## Programmatic Usage
+
+Inject `RateLimitService` to check rate limits programmatically:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { RateLimitService } from 'nestjs-cluster-throttle';
+
+@Injectable()
+export class MyService {
+  constructor(private rateLimitService: RateLimitService) {}
+
+  async checkLimit(request: any) {
+    const result = await this.rateLimitService.checkRateLimit(request, {
+      windowMs: 60 * 1000,
+      max: 10,
+    });
+
+    if (!result.allowed) {
+      throw new Error('Rate limit exceeded');
+    }
+
+    return result;
+  }
+
+  async resetUserLimit(userId: string) {
+    await this.rateLimitService.resetKey(userId);
+  }
+
+  async resetAllLimits() {
+    await this.rateLimitService.resetAll();
+  }
+}
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `windowMs` | number | `900000` (15 min) | Time window in milliseconds |
+| `max` | number | `100` | Maximum number of requests per window |
+| `message` | string | `'Too Many Requests'` | Error message when limit is exceeded |
+| `statusCode` | number | `429` | HTTP status code when limit is exceeded |
+| `skipSuccessfulRequests` | boolean | `false` | Skip successful requests in counting |
+| `keyGenerator` | function | IP-based | Function to generate rate limit key |
+| `skip` | function | `undefined` | Function to conditionally skip rate limiting |
+| `handler` | function | `undefined` | Custom handler for rate limit exceeded |
+| `clusterMode` | boolean | `false` | Enable Redis for cluster mode |
+| `redisOptions` | object | `{}` | Redis connection options |
+| `strategy` | string | `'fixed-window'` | Rate limiting strategy |
+| `burstCapacity` | number | `undefined` | Burst capacity for token-bucket |
+| `fillRate` | number | `undefined` | Fill rate for token-bucket |
+
+### Redis Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `host` | string | `'localhost'` | Redis host |
+| `port` | number | `6379` | Redis port |
+| `password` | string | `undefined` | Redis password |
+| `db` | number | `0` | Redis database number |
+| `keyPrefix` | string | `'rate-limit:'` | Key prefix for Redis |
+| `enableReadyCheck` | boolean | `true` | Enable ready check |
+
+## Response Headers
+
+When rate limiting is active, the following headers are set:
+
+- `X-RateLimit-Limit`: Maximum requests allowed
+- `X-RateLimit-Remaining`: Requests remaining in current window
+- `X-RateLimit-Reset`: Unix timestamp when the rate limit resets
+
+## Testing
+
+```typescript
+import { Test } from '@nestjs/testing';
+import { RateLimitModule, RateLimitService }

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "nestjs-cluster-throttle",
+  "version": "1.0.1",
+  "description": "Enterprise-grade rate limiting module for NestJS with Redis support, multiple strategies, and cluster mode",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prebuild": "rimraf dist",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "test:e2e": "jest --config ./test/jest-e2e.json",
+    "lint": "eslint \"{src,test}/**/*.ts\" --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "prepublishOnly": "npm run build",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "nestjs",
+    "rate-limiting",
+    "rate-limiter",
+    "throttle",
+    "throttling",
+    "cluster",
+    "redis",
+    "distributed",
+    "rate-limit",
+    "guard",
+    "middleware",
+    "api-protection",
+    "ddos-protection",
+    "request-limiting",
+    "token-bucket",
+    "sliding-window",
+    "fixed-window"
+  ],
+  "author": {
+    "name": "Roman Dobrynin",
+    "email": "roman.dobrynin@gmail.com"
+  },
+  "contributors": [
+    {
+      "name": "Roman Dobrynin",
+      "email": "roman.dobrynin@gmail.com"
+    }
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rdobrynin/nestjs-cluster-throttle.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rdobrynin/nestjs-cluster-throttle/issues"
+  },
+  "homepage": "https://github.com/rdobrynin/nestjs-cluster-throttle#readme",
+  "engines": {
+    "node": ">=14.0.0",
+    "npm": ">=6.0.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^9.0.0 || ^10.0.0",
+    "@nestjs/core": "^9.0.0 || ^10.0.0",
+    "reflect-metadata": "^0.1.13",
+    "rxjs": "^7.0.0"
+  },
+  "dependencies": {
+    "ioredis": "^5.3.2"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^10.0.0",
+    "@nestjs/core": "^10.0.0",
+    "@nestjs/platform-express": "^10.0.0",
+    "@nestjs/testing": "^10.0.0",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-prettier": "^5.0.0",
+    "jest": "^29.5.0",
+    "prettier": "^3.0.0",
+    "reflect-metadata": "^0.1.13",
+    "rimraf": "^5.0.0",
+    "rxjs": "^7.8.0",
+    "ts-jest": "^29.1.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "np": {
+    "yarn": false,
+    "contents": "dist"
+  }
+}