@cqrs-ddd/pipeline-rate-limit
Enforces throughput throttling and quota policies across distributed microservices. Works with any limiter exposing a consume() method, including rate-limiter-flexible (Redis, Memory, PostgreSQL, MySQL).
Over-quota requests are rejected before executing business logic, throwing RateLimitExceededError which translates to HTTP 429 Too Many Requests with a calculated Retry-After header.
Installation
Section titled “Installation”Compatible with all rate-limiter-flexible adapters (RateLimiterRedis, RateLimiterMemory, RateLimiterPostgres, RateLimiterCluster).
Usage Patterns
Section titled “Usage Patterns”1. Plain Node.js / Pipeline Engine
Section titled “1. Plain Node.js / Pipeline Engine”2. NestJS Integration (@cqrs-ddd/nestjs)
Section titled “2. NestJS Integration (@cqrs-ddd/nestjs)”Provide RateLimitBehavior in your rate-limiting or security module:
Decorate command or query handlers:
The global ErrorFilter automatically maps RateLimitExceededError to HTTP 429 Too Many Requests and sets the Retry-After: <seconds> response header.
Dynamic Points Consumption
Section titled “Dynamic Points Consumption”Requests can consume varying point costs based on execution weight (e.g. batch operations consume points proportional to array length):
Partitioned Key Construction
Section titled “Partitioned Key Construction”createPartitionedRateLimitKeyFactory(partitionFn, options) builds composite keys in the format <tenant>:<partition>:<requestName>:
| Option | Type | Default | Description |
|---|---|---|---|
onMissingPartition |
'throw' | 'request' |
'throw' |
When 'throw', requests lacking an identified caller fail closed with MissingRateLimitPartitionError. When 'request', unidentified callers share one bucket per request and tenant. |
includeTenant |
boolean |
true |
Prepends active tenant ID to prevent cross-tenant quota contention. |
requireTenant |
boolean |
includeTenant |
Throws MissingRateLimitPartitionError if tenant context is missing. |
Generated key examples:
- Authenticated user:
org_123:usr_456:searchCatalog - IP address:
org_123:ip_192.168.1.1:searchCatalog
Configuration Options
Section titled “Configuration Options”| Option | Type | Default | Description |
|---|---|---|---|
keyFactory |
RateLimitKeyFactory |
required | Key factory returning the partition string. |
points |
number | ((ctx) => number) |
1 |
Point cost consumed by this request, a non-negative safe integer. 0 charges nothing: the limiter is not called. |
keyPrefix |
string |
undefined |
Additional prefix prepended to the generated key. |
limiter |
RateLimiterLike |
Constructor limiter | Override the default limiter for this specific operation. |
failOpen |
boolean |
true |
When true, limiter backend errors (Redis offline) log a warning and let the request proceed. When false, backend failures reject. |
Observability & Pipeline Items
Section titled “Observability & Pipeline Items”RateLimitBehavior stamps limiter decisions onto context.items:
RATE_LIMIT_ITEM_TOKEN: the limiter’s result, with the remaining points and the milliseconds before the next point.buildRateLimitAttributes(context):{ 'rate_limit.remaining_points': n }, for span or metric attributes.
HTTP Error Translation
Section titled “HTTP Error Translation”When points are exhausted, RateLimitExceededError is thrown: