Rate limiting
@getsoda/core/throttler limits how many requests each client sends to each route, as @nestjs/throttler does.
import { ThrottlerGuard, ThrottlerModule } from '@getsoda/core/throttler'
@Module({ imports: [ThrottlerModule.forRoot({ throttlers: [{ ttl: 60_000, limit: 100 }] })] })export class AppModule {}
const app = await createApp(AppModule, { guards: [ThrottlerGuard] })Every client may now send 100 requests a minute to each route. Past that, it gets 429 Too Many Requests with Retry-After in seconds, until the window ends.
ThrottlerModule is global. ThrottlerGuard may also protect a few controllers with @UseGuards(ThrottlerGuard) instead of all of them.
Several limits
Every limit applies; name them to change them apart:
ThrottlerModule.forRoot({ throttlers: [ { name: 'burst', ttl: 1000, limit: 5 }, // 5 per second { ttl: 60_000, limit: 100 }, // and 100 per minute, named `default` ],})blockDuration (milliseconds) refuses a client past the limit for that long instead of the rest of the window: { ttl: 60_000, limit: 5, blockDuration: 15 * 60_000 }.
Per route
@Post('login')@Throttle({ default: { limit: 5, ttl: 60_000 } }) // stricter for loginslogin() {}
@Controller('health')@SkipThrottle() // not counted at allexport class HealthController {}
@Get('report')@SkipThrottle({ burst: true }) // only the `default` limit appliesreport() {}On a method, they win over the class: @SkipThrottle({ default: false }) counts a route of a skipped controller.
Each route is counted apart: login and register each have their own 5 a minute.
Headers
Successful responses tell clients where they are:
| Header | |
|---|---|
X-RateLimit-Limit |
requests allowed per window |
X-RateLimit-Remaining |
requests left in this window |
X-RateLimit-Reset |
seconds until the window ends |
Retry-After |
on a 429: seconds until the client is let in again |
For a limit named burst, the headers are X-RateLimit-Limit-burst and so on. headers: false sends none but Retry-After.
Who is a client
By default, ctx.ip: the address of the peer. Behind a reverse proxy or a load balancer that is the proxy, and every client would share one limit. Read the client from the header the proxy sets:
ThrottlerModule.forRoot({ throttlers: [{ ttl: 60_000, limit: 100 }], // The last address is the one your proxy appended: clients can write the ones before it. tracker: (ctx) => ctx.header('x-forwarded-for')?.split(',').at(-1)?.trim() ?? ctx.ip,})Trust that header only behind a proxy that sets it. A tracker may also count users instead of addresses: (ctx) => ctx.has(USER) ? ctx.get(USER).id : ctx.ip, with the guard that sets USER before ThrottlerGuard. A tracker returning undefined lets the request through uncounted.
skip: (ctx) => boolean lets requests through uncounted, such as those of your own monitoring.
Configuration from providers
ThrottlerModule.forRootAsync({ inject: [AppConfig], useFactory: (config) => ({ throttlers: [{ ttl: 60_000, limit: config.RATE_LIMIT }] }),})Several instances
Counts live in the memory of the process: right for one instance. With several (behind a load balancer, in a cluster), each counts on its own, so a client may send the limit to each. Share the counts with a ThrottlerStorage, such as one on Redis:
import { RedisClient } from 'bun'import type { ThrottlerRecord, ThrottlerStorage } from '@getsoda/core/throttler'
export class RedisThrottlerStorage implements ThrottlerStorage { readonly #redis = new RedisClient(process.env.REDIS_URL)
async increment(key: string, ttl: number, limit: number, blockDuration: number): Promise<ThrottlerRecord> { const blocked = Number(await this.#redis.send('PTTL', [`${key}:blocked`]))
if (blocked > 0) { return { totalHits: limit + 1, timeToExpire: blocked, isBlocked: true, timeToBlockExpire: blocked } }
const hits = Number(await this.#redis.send('INCR', [key]))
if (hits === 1) { await this.#redis.send('PEXPIRE', [key, String(ttl)]) }
const timeToExpire = Math.max(0, Number(await this.#redis.send('PTTL', [key])))
if (hits > limit) { await this.#redis.send('SET', [`${key}:blocked`, '1', 'PX', String(blockDuration)])
return { totalHits: hits, timeToExpire, isBlocked: true, timeToBlockExpire: blockDuration } }
return { totalHits: hits, timeToExpire, isBlocked: false, timeToBlockExpire: 0 } }}
ThrottlerModule.forRoot({ throttlers, storage: new RedisThrottlerStorage() })The memory storage drops expired keys every minute, so its memory follows the clients that are active, not every client ever seen.
WebSockets
On a gateway, ThrottlerGuard among the class guards limits handshakes: how often a client may connect.