@nestjs/throttler
Advanced tools
A Rate-Limiting module for NestJS to work on Express, Fastify, Websockets, Socket.IO, and GraphQL, all rolled up into a simple package.
@nestjs/throttler is a rate-limiting module for NestJS applications. It helps to control the rate of incoming requests to prevent abuse and ensure fair usage of resources. This package is particularly useful for APIs to avoid being overwhelmed by too many requests in a short period.
Basic Rate Limiting
This feature allows you to set up basic rate limiting for your entire application. In this example, a maximum of 10 requests per minute is allowed.
```typescript
import { ThrottlerModule } from '@nestjs/throttler';
@Module({
imports: [
ThrottlerModule.forRoot({
ttl: 60,
limit: 10,
}),
],
})
export class AppModule {}
```Rate Limiting for Specific Routes
This feature allows you to apply rate limiting to specific routes. In this example, the 'limited' route is restricted to 5 requests per minute.
```typescript
import { Controller, Get, UseGuards } from '@nestjs/common';
import { ThrottlerGuard, Throttle } from '@nestjs/throttler';
@Controller('api')
@UseGuards(ThrottlerGuard)
export class ApiController {
@Get('limited')
@Throttle(5, 60)
getLimited() {
return 'This route is rate limited to 5 requests per minute';
}
}
```Customizing Rate Limiting
This feature allows you to customize the rate limiting storage mechanism. In this example, Redis is used as the storage backend for rate limiting.
```typescript
import { ThrottlerModule, ThrottlerGuard, ThrottlerStorageRedisService } from '@nestjs/throttler';
import { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';
@Module({
imports: [
ThrottlerModule.forRoot({
ttl: 60,
limit: 10,
storage: new ThrottlerStorageRedisService(),
}),
],
providers: [
{
provide: APP_GUARD,
useClass: ThrottlerGuard,
},
],
})
export class AppModule {}
```express-rate-limit is a basic rate-limiting middleware for Express applications. It is simpler and more lightweight compared to @nestjs/throttler, but it lacks the deep integration with NestJS and some advanced features like custom storage backends.
rate-limiter-flexible is a highly flexible rate-limiting library that supports various backends like Redis, MongoDB, and in-memory storage. It offers more customization options compared to @nestjs/throttler but requires more setup and integration effort.
koa-ratelimit is a rate-limiting middleware for Koa applications. It provides similar functionalities to @nestjs/throttler but is designed specifically for Koa, making it less suitable for NestJS applications.
A progressive Node.js framework for building efficient and scalable server-side applications.
A Rate-Limiter for NestJS, regardless of the context.
For an overview of the community storage providers, see Community Storage Providers.
This package comes with a couple of goodies that should be mentioned, first is the ThrottlerModule.
$ npm i --save @nestjs/throttler
@nestjs/throttler@^1 is compatible with Nest v7 while @nestjs/throttler@^2 is compatible with Nest v7 and Nest v8, but it is suggested to be used with only v8 in case of breaking changes against v7 that are unseen.
For NestJS v10, please use version 4.1.0 or above
Once the installation is complete, the ThrottlerModule can be configured as any other Nest package with forRoot or forRootAsync methods.
@@filename(app.module)
@Module({
imports: [
ThrottlerModule.forRoot([{
ttl: 60000,
limit: 10,
}]),
],
})
export class AppModule {}
The above will set the global options for the ttl, the time to live in milliseconds, and the limit, the maximum number of requests within the ttl, for the routes of your application that are guarded.
Once the module has been imported, you can then choose how you would like to bind the ThrottlerGuard. Any kind of binding as mentioned in the guards section is fine. If you wanted to bind the guard globally, for example, you could do so by adding this provider to any module:
{
provide: APP_GUARD,
useClass: ThrottlerGuard
}
There may come upon times where you want to set up multiple throttling definitions, like no more than 3 calls in a second, 20 calls in 10 seconds, and 100 calls in a minute. To do so, you can set up your definitions in the array with named options, that can later be referenced in the @SkipThrottle() and @Throttle() decorators to change the options again.
@@filename(app.module)
@Module({
imports: [
ThrottlerModule.forRoot([
{
name: 'short',
ttl: 1000,
limit: 3,
},
{
name: 'medium',
ttl: 10000,
limit: 20
},
{
name: 'long',
ttl: 60000,
limit: 100
}
]),
],
})
export class AppModule {}
There may be a time where you want to bind the guard to a controller or globally, but want to disable rate limiting for one or more of your endpoints. For that, you can use the @SkipThrottle() decorator, to negate the throttler for an entire class or a single route. The @SkipThrottle() decorator can also take in an object of string keys with boolean values for if there is a case where you want to exclude most of a controller, but not every route, and configure it per throttler set if you have more than one. If you do not pass an object, the default is to use {{ '{' }} default: true {{ '}' }}
@SkipThrottle()
@Controller('users')
export class UsersController {}
This @SkipThrottle() decorator can be used to skip a route or a class or to negate the skipping of a route in a class that is skipped.
@SkipThrottle()
@Controller('users')
export class UsersController {
// Rate limiting is applied to this route.
@SkipThrottle({ default: false })
dontSkip() {
return 'List users work with Rate limiting.';
}
// This route will skip rate limiting.
doSkip() {
return 'List users work without Rate limiting.';
}
}
There is also the @Throttle() decorator which can be used to override the limit and ttl set in the global module, to give tighter or looser security options. This decorator can be used on a class or a function as well. With version 5 and onwards, the decorator takes in an object with the string relating to the name of the throttler set, and an object with the limit and ttl keys and integer values, similar to the options passed to the root module. If you do not have a name set in your original options, use the string default You have to configure it like this:
// Override default configuration for Rate limiting and duration.
@Throttle({ default: { limit: 3, ttl: 60000 } })
@Get()
findAll() {
return "List users works with custom rate limiting.";
}
If your application runs behind a proxy server, check the specific HTTP adapter options (express and fastify) for the trust proxy option and enable it. Doing so will allow you to get the original IP address from the X-Forwarded-For header, and you can override the getTracker() method to pull the value from the header rather than from req.ip. The following example works with both express and fastify:
// throttler-behind-proxy.guard.ts
import { ThrottlerGuard } from '@nestjs/throttler';
import { Injectable } from '@nestjs/common';
@Injectable()
export class ThrottlerBehindProxyGuard extends ThrottlerGuard {
protected getTracker(req: Record<string, any>): Promise<string> {
return new Promise<string>((resolve, reject) => {
const tracker = req.ips.length > 0 ? req.ips[0] : req.ip; // individualize IP extraction to meet your own needs
resolve(tracker);
});
}
}
// app.controller.ts
import { ThrottlerBehindProxyGuard } from './throttler-behind-proxy.guard';
@UseGuards(ThrottlerBehindProxyGuard)
info Hint You can find the API of the
reqRequest object for express here and for fastify here.
This module can work with websockets, but it requires some class extension. You can extend the ThrottlerGuard and override the handleRequest method like so:
@Injectable()
export class WsThrottlerGuard extends ThrottlerGuard {
async handleRequest(requestProps: ThrottlerRequest): Promise<boolean> {
const { context, limit, ttl, throttler, blockDuration, getTracker, generateKey } = requestProps;
const client = context.switchToWs().getClient();
const tracker = client._socket.remoteAddress;
const key = generateKey(context, tracker, throttler.name);
const { totalHits, timeToExpire, isBlocked, timeToBlockExpire } =
await this.storageService.increment(key, ttl, limit, blockDuration, throttler.name);
const getThrottlerSuffix = (name: string) => (name === 'default' ? '' : `-${name}`);
// Throw an error when the user reached their limit.
if (isBlocked) {
await this.throwThrottlingException(context, {
limit,
ttl,
key,
tracker,
totalHits,
timeToExpire,
isBlocked,
timeToBlockExpire,
});
}
return true;
}
}
info Hint If you are using ws, it is necessary to replace the
_socketwithconn
There's a few things to keep in mind when working with WebSockets:
APP_GUARD or app.useGlobalGuards()exception event, so make sure there is a listener ready for thisinfo Hint If you are using the
@nestjs/platform-wspackage you can useclient._socket.remoteAddressinstead.
The ThrottlerGuard can also be used to work with GraphQL requests. Again, the guard can be extended, but this time the getRequestResponse method will be overridden
@Injectable()
export class GqlThrottlerGuard extends ThrottlerGuard {
getRequestResponse(context: ExecutionContext) {
const gqlCtx = GqlExecutionContext.create(context);
const ctx = gqlCtx.getContext();
return { req: ctx.req, res: ctx.res };
}
}
However, when using Apollo Express/Fastify or Mercurius, it's important to configure the context correctly in the GraphQLModule to avoid any problems.
For Apollo Server running on Express, you can set up the context in your GraphQLModule configuration as follows:
GraphQLModule.forRoot({
// ... other GraphQL module options
context: ({ req, res }) => ({ req, res }),
});
When using Apollo Server with Fastify or Mercurius, you need to configure the context differently. You should use request and reply objects. Here's an example:
GraphQLModule.forRoot({
// ... other GraphQL module options
context: (request, reply) => ({ request, reply }),
});
The following options are valid for the object passed to the array of the ThrottlerModule's options:
name | the name for internal tracking of which throttler set is being used. Defaults to `default` if not passed |
ttl | the number of milliseconds that each request will last in storage |
limit | the maximum number of requests within the TTL limit |
blockDuration | the number of milliseconds that request will be blocked for that time |
ignoreUserAgents | an array of regular expressions of user-agents to ignore when it comes to throttling requests |
skipIf | a function that takes in the ExecutionContext and returns a boolean to short circuit the throttler logic. Like @SkipThrottler(), but based on the request |
getTracker | a function that takes in the Request and returns a string to override the default logic of the getTracker method |
generateKey | a function that takes in the ExecutionContext, the tacker string and the throttler name as a string and returns a string to override the final key which will be used to store the rate limit value. This overrides the default logic of the generateKey method |
If you need to set up storages instead, or want to use a some of the above options in a more global sense, applying to each throttler set, you can pass the options above via the throttlers option key and use the below table
storage | a custom storage service for where the throttling should be kept track. See here. |
ignoreUserAgents | an array of regular expressions of user-agents to ignore when it comes to throttling requests |
skipIf | a function that takes in the ExecutionContext and returns a boolean to short circuit the throttler logic. Like @SkipThrottler(), but based on the request |
throttlers | an array of throttler sets, defined using the table above |
errorMessage | a string OR a function that takes in the ExecutionContext and the ThrottlerLimitDetail and returns a string which overrides the default throttler error message |
getTracker | a function that takes in the Request and returns a string to override the default logic of the getTracker method |
generateKey | a function that takes in the ExecutionContext, the tacker string and the throttler name as a string and returns a string to override the final key which will be used to store the rate limit value. This overrides the default logic of the generateKey method |
You may want to get your rate-limiting configuration asynchronously instead of synchronously. You can use the forRootAsync() method, which allows for dependency injection and async methods.
One approach would be to use a factory function:
@Module({
imports: [
ThrottlerModule.forRootAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (config: ConfigService) => [
{
ttl: config.get('THROTTLE_TTL'),
limit: config.get('THROTTLE_LIMIT'),
},
],
}),
],
})
export class AppModule {}
You can also use the useClass syntax:
@Module({
imports: [
ThrottlerModule.forRootAsync({
imports: [ConfigModule],
useClass: ThrottlerConfigService,
}),
],
})
export class AppModule {}
This is doable, as long as ThrottlerConfigService implements the interface ThrottlerOptionsFactory.
The built in storage is an in memory cache that keeps track of the requests made until they have passed the TTL set by the global options. You can drop in your own storage option to the storage option of the ThrottlerModule so long as the class implements the ThrottlerStorage interface.
info Note
ThrottlerStoragecan be imported from@nestjs/throttler.
There are a couple of helper methods to make the timings more readable if you prefer to use them over the direct definition. @nestjs/throttler exports five different helpers, seconds, minutes, hours, days, and weeks. To use them, simply call seconds(5) or any of the other helpers, and the correct number of milliseconds will be returned.
For most people, wrapping your options in an array will be enough.
If you are using a custom storage, you should wrap you ttl and limit in an
array and assign it to the throttlers property of the options object.
Any @ThrottleSkip() should now take in an object with string: boolean props.
The strings are the names of the throttlers. If you do not have a name, pass the
string 'default', as this is what will be used under the hood otherwise.
Any @Throttle() decorators should also now take in an object with string keys,
relating to the names of the throttler contexts (again, 'default' if no name)
and values of objects that have limit and ttl keys.
Warning Important The
ttlis now in milliseconds. If you want to keep your ttl in seconds for readability, use thesecondshelper from this package. It just multiplies the ttl by 1000 to make it in milliseconds.
For more info, see the Changelog
Feel free to submit a PR with your custom storage provider being added to this list.
Nest is MIT licensed.
6.3.0
FAQs
A Rate-Limiting module for NestJS to work on Express, Fastify, Websockets, Socket.IO, and GraphQL, all rolled up into a simple package.
The npm package @nestjs/throttler receives a total of 286,990 weekly downloads. As such, @nestjs/throttler popularity was classified as popular.
We found that @nestjs/throttler demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.