Documentation

Documentation / zerotal / index / ThrottleMiddleware

Class: ThrottleMiddleware

Defined in: packages/core/src/middleware/ThrottleMiddleware.ts:68

Rate-limiting middleware using an in-memory sliding window counter.

Returns 429 Too Many Requests with Retry-After and X-RateLimit-* headers when a client exceeds the configured threshold within the time window.

Example

// Global: 120 req / min
app.use([ThrottleMiddleware.with({ maxAttempts: 120, windowSeconds: 60 })]);

// Per-route: 5 login attempts / min
Router.post('/login', AuthController, 'login', [
  ThrottleMiddleware.with({ maxAttempts: 5, windowSeconds: 60 }),
]);

// By authenticated user ID
ThrottleMiddleware.with({
  maxAttempts: 1000,
  windowSeconds: 3600,
  keyResolver: (ctx) => String(ctx.user?.id ?? _clientIp(ctx.request)),
})

Extends

• BaseMiddleware<ThrottleOptions>

Constructors

Constructor

new ThrottleMiddleware(options?): ThrottleMiddleware

Defined in: packages/core/src/middleware/ThrottleMiddleware.ts:74

Parameters

options?

Partial<ThrottleOptions> = {}

Returns

ThrottleMiddleware

Overrides

BaseMiddleware.constructor

Properties

options

protected options: ThrottleOptions

Defined in: packages/core/src/middleware/ThrottleMiddleware.ts:69

Subclasses must declare this with their default option values. TypeScript enforces this at compile time — forgetting it is a type error.

Overrides

BaseMiddleware.options

Methods

with()

static with<T, Opts>(this, options): () => InstanceType<T>

Defined in: packages/core/src/middleware/BaseMiddleware.ts:48

Returns a zero-arg subclass with the given options deep-merged on top of the subclass defaults, usable directly in app.use([...]).

Type Parameters

T

T extends (...args) => BaseMiddleware<any>

Opts

Opts = T extends (...args) => BaseMiddleware<U> ? U : object

Parameters

this

T

options

Partial<Opts>

Returns

() => InstanceType<T>

Inherited from

BaseMiddleware.with

afterResponse()?

optional afterResponse(ctx): Promise<void>

Defined in: packages/core/src/middleware/BaseMiddleware.ts:70

Parameters

ctx

HttpContext

Returns

Promise<void>

Inherited from

BaseMiddleware.afterResponse

onError()?

optional onError(ctx, error): Promise<void>

Defined in: packages/core/src/middleware/BaseMiddleware.ts:71

Parameters

ctx

HttpContext

error

Error

Returns

Promise<void>

Inherited from

BaseMiddleware.onError

handle()

handle(http, next): Promise<void | Response>

Defined in: packages/core/src/middleware/ThrottleMiddleware.ts:102

Parameters

http

HttpContext

next

NextFn

Returns

Promise<void | Response>

Overrides

BaseMiddleware.handle

reset()

reset(): void

Defined in: packages/core/src/middleware/ThrottleMiddleware.ts:170

Reset all counters — useful in tests.

Returns

void

resetKey()

resetKey(ctx): void

Defined in: packages/core/src/middleware/ThrottleMiddleware.ts:179

Reset the counter for a single key derived from the given context. Used by RateLimiter.resetFor() to clear a specific actor's bucket (e.g. after a successful login clears failed-attempt counters).

Parameters

ctx

HttpContext

Returns

void