Socket
Socket
Sign inDemoInstall

@nestjs/throttler

Package Overview
Dependencies
Maintainers
2
Versions
25
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@nestjs/throttler - npm Package Compare versions

Comparing version 4.2.1 to 5.0.0

dist/throttler.guard.interface.d.ts
dist/throttler.guard.interface.js
dist/throttler.guard.interface.js.map
dist/utilities.d.ts
dist/utilities.js
dist/utilities.js.map

1

dist/index.d.ts

@@ -9,1 +9,2 @@ export * from './throttler-module-options.interface';

export * from './throttler.service';
export * from './utilities';

1

dist/index.js

@@ -28,2 +28,3 @@ "use strict";

__exportStar(require("./throttler.service"), exports);
__exportStar(require("./utilities"), exports);
//# sourceMappingURL=index.js.map

16

dist/throttler-module-options.interface.d.ts
import { ExecutionContext, ModuleMetadata, Type } from '@nestjs/common/interfaces';
export interface ThrottlerModuleOptions {
limit?: number;
ttl?: number;
import { ThrottlerStorage } from './throttler-storage.interface';
export type Resolvable<T extends number | string | boolean> = T | ((context: ExecutionContext) => T | Promise<T>);
export interface ThrottlerOptions {
name?: string;
limit: Resolvable<number>;
ttl: Resolvable<number>;
ignoreUserAgents?: RegExp[];
storage?: any;
skipIf?: (context: ExecutionContext) => boolean;
}
export type ThrottlerModuleOptions = Array<ThrottlerOptions> | {
skipIf?: (context: ExecutionContext) => boolean;
ignoreUserAgents?: RegExp[];
storage?: ThrottlerStorage;
throttlers: Array<ThrottlerOptions>;
};
export interface ThrottlerOptionsFactory {

@@ -10,0 +18,0 @@ createThrottlerOptions(): Promise<ThrottlerModuleOptions> | ThrottlerModuleOptions;

2

dist/throttler-storage.interface.d.ts

@@ -1,7 +0,5 @@

import { ThrottlerStorageOptions } from './throttler-storage-options.interface';
import { ThrottlerStorageRecord } from './throttler-storage-record.interface';
export interface ThrottlerStorage {
storage: Record<string, ThrottlerStorageOptions>;
increment(key: string, ttl: number): Promise<ThrottlerStorageRecord>;
}
export declare const ThrottlerStorage: unique symbol;

10

dist/throttler.decorator.d.ts

@@ -1,4 +0,10 @@

export declare const Throttle: (limit?: number, ttl?: number) => MethodDecorator & ClassDecorator;
export declare const SkipThrottle: (skip?: boolean) => MethodDecorator & ClassDecorator;
import { Resolvable } from './throttler-module-options.interface';
interface ThrottlerMethodOrControllerOptions {
limit?: Resolvable<number>;
ttl?: Resolvable<number>;
}
export declare const Throttle: (options: Record<string, ThrottlerMethodOrControllerOptions>) => MethodDecorator & ClassDecorator;
export declare const SkipThrottle: (skip?: Record<string, boolean>) => MethodDecorator & ClassDecorator;
export declare const InjectThrottlerOptions: () => PropertyDecorator & ParameterDecorator;
export declare const InjectThrottlerStorage: () => PropertyDecorator & ParameterDecorator;
export {};

28

dist/throttler.decorator.js

@@ -7,13 +7,15 @@ "use strict";

const throttler_providers_1 = require("./throttler.providers");
function setThrottlerMetadata(target, limit, ttl) {
Reflect.defineMetadata(throttler_constants_1.THROTTLER_TTL, ttl, target);
Reflect.defineMetadata(throttler_constants_1.THROTTLER_LIMIT, limit, target);
function setThrottlerMetadata(target, options) {
for (const name in options) {
Reflect.defineMetadata(throttler_constants_1.THROTTLER_TTL + name, options[name].ttl, target);
Reflect.defineMetadata(throttler_constants_1.THROTTLER_LIMIT + name, options[name].limit, target);
}
}
const Throttle = (limit = 20, ttl = 60) => {
const Throttle = (options) => {
return (target, propertyKey, descriptor) => {
if (descriptor) {
setThrottlerMetadata(descriptor.value, limit, ttl);
setThrottlerMetadata(descriptor.value, options);
return descriptor;
}
setThrottlerMetadata(target, limit, ttl);
setThrottlerMetadata(target, options);
return target;

@@ -23,10 +25,12 @@ };

exports.Throttle = Throttle;
const SkipThrottle = (skip = true) => {
const SkipThrottle = (skip = { default: true }) => {
return (target, propertyKey, descriptor) => {
if (descriptor) {
Reflect.defineMetadata(throttler_constants_1.THROTTLER_SKIP, skip, descriptor.value);
return descriptor;
for (const key in skip) {
if (descriptor) {
Reflect.defineMetadata(throttler_constants_1.THROTTLER_SKIP + key, skip[key], descriptor.value);
return descriptor;
}
Reflect.defineMetadata(throttler_constants_1.THROTTLER_SKIP + key, skip[key], target);
return target;
}
Reflect.defineMetadata(throttler_constants_1.THROTTLER_SKIP, skip, target);
return target;
};

@@ -33,0 +37,0 @@ };

17

dist/throttler.guard.d.ts
import { CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { ThrottlerModuleOptions } from './throttler-module-options.interface';
import { ThrottlerModuleOptions, ThrottlerOptions } from './throttler-module-options.interface';
import { ThrottlerStorage } from './throttler-storage.interface';
import { ThrottlerLimitDetail } from './throttler.guard.interface';
export declare class ThrottlerGuard implements CanActivate {

@@ -11,6 +12,10 @@ protected readonly options: ThrottlerModuleOptions;

protected errorMessage: string;
protected throttlers: Array<ThrottlerOptions>;
protected commonOptions: Pick<ThrottlerOptions, 'skipIf' | 'ignoreUserAgents'>;
constructor(options: ThrottlerModuleOptions, storageService: ThrottlerStorage, reflector: Reflector);
onModuleInit(): Promise<void>;
canActivate(context: ExecutionContext): Promise<boolean>;
protected handleRequest(context: ExecutionContext, limit: number, ttl: number): Promise<boolean>;
protected getTracker(req: Record<string, any>): string;
protected shouldSkip(_context: ExecutionContext): Promise<boolean>;
protected handleRequest(context: ExecutionContext, limit: number, ttl: number, throttler: ThrottlerOptions): Promise<boolean>;
protected getTracker(req: Record<string, any>): Promise<string>;
protected getRequestResponse(context: ExecutionContext): {

@@ -20,4 +25,6 @@ req: Record<string, any>;

};
protected generateKey(context: ExecutionContext, suffix: string): string;
protected throwThrottlingException(context: ExecutionContext): void;
protected generateKey(context: ExecutionContext, suffix: string, name: string): string;
protected throwThrottlingException(context: ExecutionContext, throttlerLimitDetail: ThrottlerLimitDetail): Promise<void>;
protected getErrorMessage(_context: ExecutionContext, _throttlerLimitDetail: ThrottlerLimitDetail): Promise<string>;
private resolveValue;
}

107

dist/throttler.guard.js

@@ -23,3 +23,3 @@ "use strict";

const throttler_exception_1 = require("./throttler.exception");
let ThrottlerGuard = exports.ThrottlerGuard = class ThrottlerGuard {
let ThrottlerGuard = class ThrottlerGuard {
constructor(options, storageService, reflector) {

@@ -32,26 +32,58 @@ this.options = options;

}
async onModuleInit() {
this.throttlers = (Array.isArray(this.options) ? this.options : this.options.throttlers)
.sort((first, second) => {
if (typeof first.ttl === 'function') {
return 1;
}
if (typeof second.ttl === 'function') {
return 0;
}
return first.ttl - second.ttl;
})
.map((opt) => { var _a; return (Object.assign(Object.assign({}, opt), { name: (_a = opt.name) !== null && _a !== void 0 ? _a : 'default' })); });
if (Array.isArray(this.options)) {
this.commonOptions = {};
}
else {
this.commonOptions = {
skipIf: this.options.skipIf,
ignoreUserAgents: this.options.ignoreUserAgents,
};
}
}
async canActivate(context) {
var _a, _b;
const handler = context.getHandler();
const classRef = context.getClass();
if (this.reflector.getAllAndOverride(throttler_constants_1.THROTTLER_SKIP, [handler, classRef]) ||
((_b = (_a = this.options).skipIf) === null || _b === void 0 ? void 0 : _b.call(_a, context))) {
if (await this.shouldSkip(context)) {
return true;
}
const routeOrClassLimit = this.reflector.getAllAndOverride(throttler_constants_1.THROTTLER_LIMIT, [
handler,
classRef,
]);
const routeOrClassTtl = this.reflector.getAllAndOverride(throttler_constants_1.THROTTLER_TTL, [
handler,
classRef,
]);
const limit = routeOrClassLimit || this.options.limit;
const ttl = routeOrClassTtl || this.options.ttl;
return this.handleRequest(context, limit, ttl);
const continues = [];
for (const namedThrottler of this.throttlers) {
const skip = this.reflector.getAllAndOverride(throttler_constants_1.THROTTLER_SKIP + namedThrottler.name, [
handler,
classRef,
]);
const skipIf = namedThrottler.skipIf || this.commonOptions.skipIf;
if (skip || (skipIf === null || skipIf === void 0 ? void 0 : skipIf(context))) {
continues.push(true);
continue;
}
const routeOrClassLimit = this.reflector.getAllAndOverride(throttler_constants_1.THROTTLER_LIMIT + namedThrottler.name, [handler, classRef]);
const routeOrClassTtl = this.reflector.getAllAndOverride(throttler_constants_1.THROTTLER_TTL + namedThrottler.name, [handler, classRef]);
const limit = await this.resolveValue(context, routeOrClassLimit || namedThrottler.limit);
const ttl = await this.resolveValue(context, routeOrClassTtl || namedThrottler.ttl);
continues.push(await this.handleRequest(context, limit, ttl, namedThrottler));
}
return continues.every((cont) => cont);
}
async handleRequest(context, limit, ttl) {
async shouldSkip(_context) {
return false;
}
async handleRequest(context, limit, ttl, throttler) {
var _a;
const { req, res } = this.getRequestResponse(context);
if (Array.isArray(this.options.ignoreUserAgents)) {
for (const pattern of this.options.ignoreUserAgents) {
const ignoreUserAgents = (_a = throttler.ignoreUserAgents) !== null && _a !== void 0 ? _a : this.commonOptions.ignoreUserAgents;
if (Array.isArray(ignoreUserAgents)) {
for (const pattern of ignoreUserAgents) {
if (pattern.test(req.headers['user-agent'])) {

@@ -62,15 +94,23 @@ return true;

}
const tracker = this.getTracker(req);
const key = this.generateKey(context, tracker);
const tracker = await this.getTracker(req);
const key = this.generateKey(context, tracker, throttler.name);
const { totalHits, timeToExpire } = await this.storageService.increment(key, ttl);
const getThrottlerSuffix = (name) => (name === 'default' ? '' : `-${name}`);
if (totalHits > limit) {
res.header('Retry-After', timeToExpire);
this.throwThrottlingException(context);
res.header(`Retry-After${getThrottlerSuffix(throttler.name)}`, timeToExpire);
await this.throwThrottlingException(context, {
limit,
ttl,
key,
tracker,
totalHits,
timeToExpire,
});
}
res.header(`${this.headerPrefix}-Limit`, limit);
res.header(`${this.headerPrefix}-Remaining`, Math.max(0, limit - totalHits));
res.header(`${this.headerPrefix}-Reset`, timeToExpire);
res.header(`${this.headerPrefix}-Limit${getThrottlerSuffix(throttler.name)}`, limit);
res.header(`${this.headerPrefix}-Remaining${getThrottlerSuffix(throttler.name)}`, Math.max(0, limit - totalHits));
res.header(`${this.headerPrefix}-Reset${getThrottlerSuffix(throttler.name)}`, timeToExpire);
return true;
}
getTracker(req) {
async getTracker(req) {
return req.ip;

@@ -82,10 +122,17 @@ }

}
generateKey(context, suffix) {
const prefix = `${context.getClass().name}-${context.getHandler().name}`;
generateKey(context, suffix, name) {
const prefix = `${context.getClass().name}-${context.getHandler().name}-${name}`;
return md5(`${prefix}-${suffix}`);
}
throwThrottlingException(context) {
throw new throttler_exception_1.ThrottlerException(this.errorMessage);
async throwThrottlingException(context, throttlerLimitDetail) {
throw new throttler_exception_1.ThrottlerException(await this.getErrorMessage(context, throttlerLimitDetail));
}
async getErrorMessage(_context, _throttlerLimitDetail) {
return this.errorMessage;
}
async resolveValue(context, resolvableValue) {
return typeof resolvableValue === 'function' ? resolvableValue(context) : resolvableValue;
}
};
exports.ThrottlerGuard = ThrottlerGuard;
exports.ThrottlerGuard = ThrottlerGuard = __decorate([

@@ -92,0 +139,0 @@ (0, common_1.Injectable)(),

5

dist/throttler.module.js

@@ -14,4 +14,4 @@ "use strict";

const throttler_providers_1 = require("./throttler.providers");
let ThrottlerModule = exports.ThrottlerModule = ThrottlerModule_1 = class ThrottlerModule {
static forRoot(options = {}) {
let ThrottlerModule = ThrottlerModule_1 = class ThrottlerModule {
static forRoot(options = []) {
const providers = [...(0, throttler_providers_1.createThrottlerProviders)(options), throttler_providers_1.ThrottlerStorageProvider];

@@ -60,2 +60,3 @@ return {

};
exports.ThrottlerModule = ThrottlerModule;
exports.ThrottlerModule = ThrottlerModule = ThrottlerModule_1 = __decorate([

@@ -62,0 +63,0 @@ (0, common_1.Global)(),

3

dist/throttler.providers.d.ts
import { Provider } from '@nestjs/common';
import { ThrottlerModuleOptions } from './throttler-module-options.interface';
import { ThrottlerStorage } from './throttler-storage.interface';
export declare function createThrottlerProviders(options: ThrottlerModuleOptions): Provider[];
export declare const ThrottlerStorageProvider: {
provide: symbol;
useFactory: (options: ThrottlerModuleOptions) => any;
useFactory: (options: ThrottlerModuleOptions) => ThrottlerStorage;
inject: string[];

@@ -8,0 +9,0 @@ };

4

dist/throttler.providers.js

@@ -19,3 +19,5 @@ "use strict";

useFactory: (options) => {
return options.storage ? options.storage : new throttler_service_1.ThrottlerStorageService();
return !Array.isArray(options) && options.storage
? options.storage
: new throttler_service_1.ThrottlerStorageService();
},

@@ -22,0 +24,0 @@ inject: [throttler_constants_1.THROTTLER_OPTIONS],

5

dist/throttler.service.js

@@ -11,3 +11,3 @@ "use strict";

const common_1 = require("@nestjs/common");
let ThrottlerStorageService = exports.ThrottlerStorageService = class ThrottlerStorageService {
let ThrottlerStorageService = class ThrottlerStorageService {
constructor() {

@@ -32,3 +32,3 @@ this._storage = {};

async increment(key, ttl) {
const ttlMilliseconds = ttl * 1000;
const ttlMilliseconds = ttl;
if (!this.storage[key]) {

@@ -53,2 +53,3 @@ this.storage[key] = { totalHits: 0, expiresAt: Date.now() + ttlMilliseconds };

};
exports.ThrottlerStorageService = ThrottlerStorageService;
exports.ThrottlerStorageService = ThrottlerStorageService = __decorate([

@@ -55,0 +56,0 @@ (0, common_1.Injectable)()

65

package.json
{
"name": "@nestjs/throttler",
"version": "4.2.1",
"version": "5.0.0",
"description": "A Rate-Limiting module for NestJS to work on Express, Fastify, Websockets, Socket.IO, and GraphQL, all rolled up into a simple package.",

@@ -31,44 +31,45 @@ "author": "Jay McDoniel <me@jaymcdoniel.dev>",

"devDependencies": {
"@apollo/server": "4.9.3",
"@changesets/cli": "2.26.2",
"@commitlint/cli": "17.6.6",
"@commitlint/config-angular": "17.6.6",
"@nestjs/cli": "10.1.7",
"@nestjs/common": "10.0.5",
"@nestjs/core": "10.0.5",
"@nestjs/graphql": "12.0.7",
"@nestjs/platform-express": "10.0.5",
"@nestjs/platform-fastify": "10.0.5",
"@nestjs/platform-socket.io": "10.0.5",
"@nestjs/platform-ws": "10.0.5",
"@nestjs/schematics": "10.0.1",
"@nestjs/testing": "10.0.5",
"@nestjs/websockets": "10.0.5",
"@commitlint/cli": "17.7.1",
"@commitlint/config-angular": "17.7.0",
"@nestjs/cli": "10.1.17",
"@nestjs/common": "10.2.4",
"@nestjs/core": "10.2.4",
"@nestjs/graphql": "12.0.8",
"@nestjs/platform-express": "10.2.4",
"@nestjs/platform-fastify": "10.2.4",
"@nestjs/platform-socket.io": "10.2.4",
"@nestjs/platform-ws": "10.2.4",
"@nestjs/schematics": "10.0.2",
"@nestjs/testing": "10.2.4",
"@nestjs/websockets": "10.2.4",
"@semantic-release/git": "10.0.1",
"@types/express": "4.17.17",
"@types/express-serve-static-core": "4.17.35",
"@types/jest": "29.5.2",
"@types/express-serve-static-core": "4.17.36",
"@types/jest": "29.5.4",
"@types/md5": "2.3.2",
"@types/node": "18.16.19",
"@types/node": "18.17.14",
"@types/supertest": "2.0.12",
"@typescript-eslint/eslint-plugin": "5.61.0",
"@typescript-eslint/parser": "5.61.0",
"@apollo/server": "4.7.5",
"apollo-server-fastify": "3.12.0",
"conventional-changelog-cli": "3.0.0",
"@typescript-eslint/eslint-plugin": "6.6.0",
"@typescript-eslint/parser": "6.6.0",
"apollo-server-fastify": "3.12.1",
"conventional-changelog-cli": "4.0.0",
"cz-conventional-changelog": "3.3.0",
"eslint": "8.44.0",
"eslint-config-prettier": "8.8.0",
"eslint-plugin-import": "2.27.5",
"graphql": "16.7.1",
"eslint": "8.48.0",
"eslint-config-prettier": "9.0.0",
"eslint-plugin-import": "2.28.1",
"graphql": "16.8.0",
"graphql-tools": "9.0.0",
"husky": "8.0.3",
"jest": "29.6.1",
"lint-staged": "13.2.3",
"nodemon": "2.0.22",
"jest": "29.6.4",
"lint-staged": "14.0.1",
"nodemon": "3.0.1",
"pactum": "^3.4.1",
"pinst": "3.0.0",
"prettier": "3.0.0",
"prettier": "3.0.3",
"reflect-metadata": "0.1.13",
"rimraf": "5.0.1",
"rxjs": "7.8.1",
"socket.io": "4.7.1",
"socket.io": "4.7.2",
"supertest": "6.3.3",

@@ -79,3 +80,3 @@ "ts-jest": "29.1.1",

"tsconfig-paths": "4.2.0",
"typescript": "5.1.6",
"typescript": "5.2.2",
"ws": "8.13.0"

@@ -82,0 +83,0 @@ },

363

README.md

@@ -23,4 +23,2 @@ <p align="center">

</p>
<!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
[![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->

@@ -54,10 +52,7 @@ ## Description

- [ThrottlerModule](#throttlermodule)
- [Decorators](#decorators)
- [@Throttle()](#throttle)
- [@SkipThrottle()](#skipthrottle)
- [Ignoring specific user agents](#ignoring-specific-user-agents)
- [ThrottlerStorage](#throttlerstorage)
- [Customization](#customization)
- [ThrottlerStorage](#storages)
- [Proxies](#proxies)
- [Working with Websockets](#working-with-websockets)
- [Working with GraphQL](#working-with-graphql)
- [Working with Websockets](#websockets)
- [Working with GraphQL](#graphql)
- [Community Storage Providers](#community-storage-providers)

@@ -69,24 +64,13 @@

The `ThrottleModule` is the main entry point for this package, and can be used
in a synchronous or asynchronous manner. All the needs to be passed is the
`ttl`, the time to live in seconds for the request tracker, and the `limit`, or
how many times an endpoint can be hit before returning a 429.
Once the installation is complete, the `ThrottlerModule` can be configured as any other Nest package with `forRoot` or `forRootAsync` methods.
```ts
import { APP_GUARD } from '@nestjs/core';
import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
```typescript
@@filename(app.module)
@Module({
imports: [
ThrottlerModule.forRoot({
ttl: 60,
ThrottlerModule.forRoot([{
ttl: 60000,
limit: 10,
}),
}]),
],
providers: [
{
provide: APP_GUARD,
useClass: ThrottlerGuard,
},
],
})

@@ -96,141 +80,87 @@ export class AppModule {}

The above would mean that 10 requests from the same IP can be made to a single endpoint in 1 minute.
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.
```ts
@Module({
imports: [
ThrottlerModule.forRootAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (config: ConfigService) => ({
ttl: config.get('THROTTLE_TTL'),
limit: config.get('THROTTLE_LIMIT'),
}),
}),
],
providers: [
{
provide: APP_GUARD,
useClass: ThrottlerGuard,
},
],
})
export class AppModule {}
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](https://docs.nestjs.com/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:
```typescript
{
provide: APP_GUARD,
useClass: ThrottlerGuard
}
```
The above is also a valid configuration for asynchronous registration of the module.
#### Multiple Throttler Definitions
**NOTE:** If you add the `ThrottlerGuard` to your `AppModule` as a global guard
then all the incoming requests will be throttled by default. This can also be
omitted in favor of `@UseGuards(ThrottlerGuard)`. The global guard check can be
skipped using the `@SkipThrottle()` decorator mentioned later.
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.
Example with `@UseGuards(ThrottlerGuard)`:
```ts
// app.module.ts
```typescript
@@filename(app.module)
@Module({
imports: [
ThrottlerModule.forRoot({
ttl: 60,
limit: 10,
}),
ThrottlerModule.forRoot([
{
name: 'short'
ttl: 1000,
limit: 3,
},
{
name: 'medium',
ttl: 10000,
limit: 20
},
{
long: 'long',
ttl: 60000,
limit: 100
}
]),
],
})
export class AppModule {}
// app.controller.ts
@Controller()
export class AppController {
@UseGuards(ThrottlerGuard)
@Throttle(5, 30)
normal() {}
}
```
### Decorators
#### Customization
#### @Throttle()
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 {{ '}' }}`
```ts
@Throttle(limit: number = 30, ttl: number = 60)
```typescript
@SkipThrottle()
@Controller('users')
export class UsersController {}
```
This decorator will set `THROTTLER_LIMIT` and `THROTTLER_TTL` metadatas on the
route, for retrieval from the `Reflector` class. Can be applied to controllers
and routes.
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()
```ts
@SkipThrottle(skip = true)
```
This 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.
```ts
```typescript
@SkipThrottle()
@Controller()
export class AppController {
@SkipThrottle(false)
dontSkip() {}
doSkip() {}
@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.';
}
}
```
In the above controller, `dontSkip` would be counted against and rate-limited
while `doSkip` would not be limited in any way.
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:
### Ignoring specific user agents
You can use the `ignoreUserAgents` key to ignore specific user agents.
```ts
@Module({
imports: [
ThrottlerModule.forRoot({
ttl: 60,
limit: 10,
ignoreUserAgents: [
// Don't throttle request that have 'googlebot' defined in them.
// Example user agent: Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)
/googlebot/gi,
// Don't throttle request that have 'bingbot' defined in them.
// Example user agent: Mozilla/5.0 (compatible; Bingbot/2.0; +http://www.bing.com/bingbot.htm)
new RegExp('bingbot', 'gi'),
],
}),
],
})
export class AppModule {}
```
### ThrottlerStorage
Interface to define the methods to handle the details when it comes to keeping track of the requests.
Currently the key is seen as an `MD5` hash of the `IP` the `ClassName` and the
`MethodName`, to ensure that no unsafe characters are used and to ensure that
the package works for contexts that don't have explicit routes (like Websockets
and GraphQL).
The interface looks like this:
```ts
export interface ThrottlerStorage {
storage: Record<string, ThrottlerStorageOptions>;
increment(key: string, ttl: number): Promise<ThrottlerStorageRecord>;
```typescript
// Override default configuration for Rate limiting and duration.
@Throttle({ default: { limit: 3, ttl: 60000 } })
@Get()
findAll() {
return "List users works with custom rate limiting.";
}
```
So long as the Storage service implements this interface, it should be usable by the `ThrottlerGuard`.
#### Proxies
### Proxies
If your application runs behind a proxy server, check the specific HTTP adapter options ([express](http://expressjs.com/en/guide/behind-proxies.html) and [fastify](https://www.fastify.io/docs/latest/Reference/Server/#trustproxy)) 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:
If you are working behind a proxy, check the specific HTTP adapter options ([express](http://expressjs.com/en/guide/behind-proxies.html) and [fastify](https://www.fastify.io/docs/latest/Server/#trustproxy)) for the `trust proxy` option and enable it. Doing so will allow you to get the original IP address from the `X-Forward-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:
```ts
```typescript
// throttler-behind-proxy.guard.ts

@@ -249,10 +179,13 @@ import { ThrottlerGuard } from '@nestjs/throttler';

import { ThrottlerBehindProxyGuard } from './throttler-behind-proxy.guard';
@UseGuards(ThrottlerBehindProxyGuard)
```
### Working with Websockets
> info **Hint** You can find the API of the `req` Request object for express [here](https://expressjs.com/en/api.html#req.ips) and for fastify [here](https://www.fastify.io/docs/latest/Reference/Request/).
To work with Websockets you can extend the `ThrottlerGuard` and override the `handleRequest` method with something like the following method
#### Websockets
```ts
This module can work with websockets, but it requires some class extension. You can extend the `ThrottlerGuard` and override the `handleRequest` method like so:
```typescript
@Injectable()

@@ -262,7 +195,3 @@ export class WsThrottlerGuard extends ThrottlerGuard {

const client = context.switchToWs().getClient();
// this is a generic method to switch between `ws` and `socket.io`. You can choose what is appropriate for you
const ip = ['conn', '_socket']
.map((key) => client[key])
.filter((obj) => obj)
.shift().remoteAddress;
const ip = client._socket.remoteAddress;
const key = this.generateKey(context, ip);

@@ -280,19 +209,16 @@ const { totalHits } = await this.storageService.increment(key, ttl);

There are some things to take keep in mind when working with websockets:
> info **Hint** If you are using ws, it is necessary to replace the `_socket` with `conn`
- You cannot bind the guard with `APP_GUARD` or `app.useGlobalGuards()` due to how Nest binds global guards.
- When a limit is reached, Nest will emit an `exception` event, so make sure there is a listener ready for this.
There's a few things to keep in mind when working with WebSockets:
### Working with GraphQL
- Guard cannot be registered with the `APP_GUARD` or `app.useGlobalGuards()`
- When a limit is reached, Nest will emit an `exception` event, so make sure there is a listener ready for this
To get the `ThrottlerModule` to work with the GraphQL context, a couple of things must happen.
> info **Hint** If you are using the `@nestjs/platform-ws` package you can use `client._socket.remoteAddress` instead.
- You must use `Express` and `apollo-server-express` as your GraphQL server engine. This is
the default for Nest, but the [`apollo-server-fastify`](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-server-fastify) package does not currently support passing `res` to the `context`, meaning headers cannot be properly set.
- When configuring your `GraphQLModule`, you need to pass an option for `context` in the form
of `({ req, res}) => ({ req, res })`. This will allow access to the Express Request and Response
objects, allowing for the reading and writing of headers.
- You must add in some additional context switching to get the `ExecutionContext` to pass back values correctly (or you can override the method entirely)
#### GraphQL
```ts
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
```typescript
@Injectable()

@@ -303,3 +229,3 @@ export class GqlThrottlerGuard extends ThrottlerGuard {

const ctx = gqlCtx.getContext();
return { req: ctx.req, res: ctx.res }; // ctx.request and ctx.reply for fastify
return { req: ctx.req, res: ctx.res };
}

@@ -309,2 +235,121 @@ }

#### Configuration
The following options are valid for the object passed to the array of the `ThrottlerModule`'s options:
<table>
<tr>
<td><code>name</code></td>
<td>the name for internal tracking of which throttler set is being used. Defaults to `default` if not passed</td>
</tr>
<tr>
<td><code>ttl</code></td>
<td>the number of milliseconds that each request will last in storage</td>
</tr>
<tr>
<td><code>limit</code></td>
<td>the maximum number of requests within the TTL limit</td>
</tr>
<tr>
<td><code>ignoreUserAgents</code></td>
<td>an array of regular expressions of user-agents to ignore when it comes to throttling requests</td>
</tr>
<tr>
<td><code>skipIf</code></td>
<td>a function that takes in the <code>ExecutionContext</code> and returns a <code>boolean</code> to short circuit the throttler logic. Like <code>@SkipThrottler()</code>, but based on the request</td>
</tr>
</table>
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
<table>
<tr>
<td><code>storage</code></td>
<td>a custom storage service for where the throttling should be kept track. <a href="/security/rate-limiting#storages">See here.</a></td>
</tr>
<tr>
<td><code>ignoreUserAgents</code></td>
<td>an array of regular expressions of user-agents to ignore when it comes to throttling requests</td>
</tr>
<tr>
<td><code>skipIf</code></td>
<td>a function that takes in the <code>ExecutionContext</code> and returns a <code>boolean</code> to short circuit the throttler logic. Like <code>@SkipThrottler()</code>, but based on the request</td>
</tr>
<tr>
<td><code>throttlers</code></td>
<td>an array of throttler sets, defined using the table above</td>
</tr>
</table>
#### Async Configuration
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:
```typescript
@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:
```typescript
@Module({
imports: [
ThrottlerModule.forRootAsync({
imports: [ConfigModule],
useClass: ThrottlerConfigService,
}),
],
})
export class AppModule {}
```
This is doable, as long as `ThrottlerConfigService` implements the interface `ThrottlerOptionsFactory`.
#### Storages
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** `ThrottlerStorage` can be imported from `@nestjs/throttler`.
#### Time Helpers
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.
#### Migration Guide
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 `ttl` is now in **milliseconds**. If you want to keep your ttl
> in seconds for readability, use the `seconds` helper from this package. It just
> multiplies the ttl by 1000 to make it in milliseconds.
For more info, see the [Changelog](https://github.com/nestjs/throttler/blob/master/CHANGELOG.md#500)
## Community Storage Providers

@@ -311,0 +356,0 @@ 

dist/index.js.map

Sorry, the diff of this file is not supported yet

dist/throttler-storage.interface.js.map

Sorry, the diff of this file is not supported yet

dist/throttler.decorator.js.map

Sorry, the diff of this file is not supported yet

dist/throttler.guard.js.map

Sorry, the diff of this file is not supported yet

dist/throttler.module.js.map

Sorry, the diff of this file is not supported yet

dist/throttler.providers.js.map

Sorry, the diff of this file is not supported yet

dist/throttler.service.js.map

Sorry, the diff of this file is not supported yet

dist/tsconfig.build.tsbuildinfo

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc