![\"npm\"](\"https://img.shields.io/npm/v/nest-ratelimiter\")
\n \n \n ![\"npm\"](\"https://img.shields.io/npm/dm/nest-ratelimiter\")
\n \n \n ![\"Code](\"https://qlty.sh/gh/iamolegga/projects/nestjs-ratelimiter/coverage.svg\")
\n \n \n ![\"Known](\"https://snyk.io/test/github/iamolegga/nestjs-ratelimiter/badge.svg\"){kind=icon}
\n \n \n ![\"Libraries.io\"](\"https://img.shields.io/librariesio/release/npm/nest-ratelimiter\")
\n \n ![\"Supported](\"https://img.shields.io/badge/platforms-Express%20%26%20Fastify-green\"){kind=icon}
\n\n \n \n \n \n
\n \n \n \n \n \n \n
The most flexible NestJS rate limiter based on Redis (rate limit against not only req path but req body to block distributed brute force attacks).
\n\n---\n\nThis is the documentation for v0.5. Compatibility with earlier versions:
\n\n| nest-ratelimiter | NestJS | Node.js |\n| ---------------- | ------------ | ------- |\n| v0.5 | 11, 12 | >=22.12 |\n| [v0.4](https://github.com/iamolegga/nestjs-ratelimiter/tree/0.4.0#readme) | 8, 9, 10, 11 | >=18 |\n\n---\n\n## Install\n\n```sh\nnpm i nest-ratelimiter ratelimiter @types/ratelimiter\n```\n\n**If you want to use the default response when reaching a limit (text: \"Rate limit exceeded, retry in _human readable time value_\") also install `ms`.**\n\n```sh\nnpm i nest-ratelimiter ratelimiter @types/ratelimiter ms\n```\n\n## Usage\n\n### Decorator\n\nLet's start with controllers.\nControllers are the places where you set parameters for the rate-limiter guard.\nYou can set parameters for an entire controller or handler.\nAlso, you can override the parameters of an entire controller by providing parameters for a specific handler.\nAnd finally, you can set several parameters for multi-checking.\n\n```ts\nimport { RateLimiter, LimiterInfo } from 'nest-ratelimiter';\n\n// Let's define several functions that returns the identifier\n// to limit against.\n\n// This is functions for limiting requests by IP\nfunction getRequestIP(ctx: ExecutionContext) {\n const request = ctx.switchToHttp().getRequest();\n return request.ip;\n}\n\n// Also you can limit every path separately\nfunction getRequestIPAndPath(ctx: ExecutionContext) {\n const request = ctx.switchToHttp().getRequest();\n return `${request.ip}:${request.path}`;\n}\n\n// For blocking brute force attacks on login\n// you can return `login` value as identifier\nfunction getRequestBodyLogin(ctx: ExecutionContext) {\n const request = ctx.switchToHttp().getRequest();\n return request.body.login;\n}\n\n// Now let's setup controller\n\n@Controller('/')\n// set params for entire controller\n@RateLimiter({ getId: getRequestIP })\nclass TestController {\n // without providing params for specific handler\n // it will inherit params of entire controller\n @Get('some-api')\n someApi() {\n // ...\n }\n\n @Get('some-other-api')\n // override params for specific handler\n @RateLimiter({\n getId: getRequestIPAndPath,\n max: 10,\n duration: 10000,\n })\n someOtherApi() {\n // ...\n }\n\n @Get('one-more-api')\n // turn off rate limiter for specific handler\n @RateLimiter(false)\n oneMoreApi() {\n // ...\n }\n\n @Get('login')\n // override params for specific handler\n // by providing several params\n @RateLimiter(\n {\n getId: getRequestIPAndPath,\n max: 3,\n duration: 60 * 60 * 1000,\n },\n {\n getId: getRequestBodyLogin,\n max: 3,\n duration: 60 * 60 * 1000,\n // this is default `createErrorBody` function\n // but you can set your own\n createErrorBody: (limit: LimiterInfo) => {\n const delta = limit.reset * 1000 - Date.now();\n // ms is imported from `ms` module\n const readable = ms(delta, { long: true });\n return 'Rate limit exceeded, retry in ' + readable;\n },\n },\n )\n login(creds: CredsDto) {\n // ...\n }\n}\n```\n\nPlease, check out the docs of [ratelimiter npm module](https://www.npmjs.com/package/ratelimiter#result-object) for a better understanding of `@RateLimiter` configuration.\n\n\n### Service\n\nAnother feature is using rate limiting in complex scenarios when `id` could not be retrieved from request context. For example when it's required to make a request for id in 3rd party systems:\n\n```ts\nimport {\n RATE_LIMITER_ASSERTER_TOKEN,\n RateLimiterAsserter,\n setHeaders,\n} from 'nest-ratelimiter'\n\n@Controller('/')\nclass TestController {\n constructor(\n @Inject(RATE_LIMITER_ASSERTER_TOKEN)\n private asserter: RateLimiterAsserter,\n private db: DB;\n ) {}\n\n @Get('some-api')\n someApi(\n @Res({ passthrough: true }) response: any\n ) {\n const id = await this.db.getId();\n\n // this potentially throws `RateLimiterError` which is handled by internal\n // filter and mapped to `TooManyRequestsException`. If that doesn't fit your\n // needs, semply use filters, interceptors, try/catch to handle those errors\n const limiterInfo = this.asserter.assert({\n id,\n max: 10,\n duration: 24 * 60 * 60 * 1000,\n });\n\n // In this simple example limiterInfo is retrieved in controller and\n // `X-RateLimit-...` headers could be easily set with `setHeaders` function.\n // In a real world scenario this is done on a services layer and in a such\n // case limiterInfo should be passed back to a controller where there is an\n // access to underlying framework's response object. But this is optional\n // and only required if there is a need for such headers in a positive case.\n setHeaders(response, limiterInfo);\n }\n}\n```\n\n## Setup\n\nLet's move to module registration.\nAs `nest-ratelimiter` is using Redis as a data storage you have to provide an instance of `Redis` client (`redis` or `ioredis`). As Redis client instantiation is out of the scope of this package, you can find something that fits your needs [on npm](https://www.npmjs.com/search?q=nestjs%20redis) or create your own module for NestJS. Here we will show two examples: with [redis](https://www.npmjs.com/package/redis) and [nestjs-redis](https://www.npmjs.com/package/nestjs-redis) modules:\n\n```ts\nimport { RedisModule } from 'nestjs-redis';\nimport { RateLimiterModule, LimiterInfo } from 'nest-ratelimiter';\n\n@Module({\n imports: [\n\n // redis example\n\n RateLimiterModule.forRoot({\n\n // The only required field is `db` (redis client), all the rest fields\n // will be used as defaults for `@RateLimiter(...)` and RateLimiterAsserter\n db: require(\"redis\").createClient()\n\n }),\n\n // nestjs-redis example\n\n RateLimiterModule.forRootAsync({\n\n // 1 Register third-party module that provides `redis` or `ioredis` client\n imports: [\n RedisModule.register({\n host: process.env.REDIS_HOST,\n port: parseInt(process.env.REDIS_PORT),\n db: parseInt(process.env.REDIS_DB),\n }),\n ],\n\n // 2 And then inject redis client provider\n inject: [RedisService],\n\n // 3. build and return `RateLimiterModuleParams` from factory\n useFactory: async (redisService: RedisService) => {\n\n // You can set default fields for every @RateLimiter and then you don't\n // have to copy-paste your params on entire codebase.\n\n // IF YOU SET `getId` HERE, THEN ALL CONTROLLERS (EVEN THOSE WITHOUT\n // @RateLimiter GUARD) WILL USE THIS FUNCTION BY DEFAULT. IF IN THAT\n // CASE YOU NEED TO TURN OFF RATE LIMITER ON SOME SPECIFIC HANDLER OR\n // CONTROLLER JUST USE `@RateLimiter(false)`\n\n return {\n db: redisService.getClient(),\n max: 10,\n duration: 10000,\n getId: getRequestIPAndPath;\n createErrorBody: (limit: LimiterInfo) => ({\n error: {\n code: 'MY-RATE-LIMIT-ERROR-CODE',\n params: limit,\n },\n }),\n };\n },\n\n }),\n ],\n controllers: [TestController],\n})\nclass TestModule {}\n```\n\n## Comparison with others\n\nThis `nest-ratelimiter` is using TJ's [ratelimiter](https://www.npmjs.com/package/ratelimiter) package underhood, so it allows the creation of a flexible strategy for limiting not only per request path but per **headers** or **body** values or even asynchronously computed values on a services layer. **It stores data only in `redis`**. If you need another store you can look at [nestjs-rate-limiter](https://www.npmjs.com/package/nestjs-rate-limiter), but it allows the use of strategies based on a request path only. Also, there is an example in [official docs](https://docs.nestjs.com/techniques/security#rate-limiting) with setting up [express-rate-limit](https://www.npmjs.com/package/express-rate-limit) middleware.\n\n## Migration\n\n### 0.5.0\n\n- dropped support of nestjs < 11.0.0\n- dropped support of node < 22.12.0\n- the package is now published from `dist/` with an `exports` map, so deep imports such as `nest-ratelimiter/utils/set-headers.fn` no longer resolve — import from the package root\n\n### 0.3.0\n\n- no need to use `app.useGlobalGuards` as now it's set automatically\n- dropped support of nestjs < 8.0.0\n- dropped support of node < 16.0.0\n\n### 0.2.0\n\n- `nestjs-redis` was moved from dependencies, now you are free to use any redis module that fit your needs, but you have to set new field `RateLimiterModuleParams.db` that should be `redis` or `ioredis` instance.\n- `ratelimiter` (with `@types/ratelimiter`) was moved to peer dependencies. If you are using `npm@7` it will install it automatically, either way you should install it manually.\n\n---\n\n