Skip to content

Home > @opengovsg/rate-limit

rate-limit package ​

A framework-agnostic rate-limiting core built on rate-limiter-flexible.

Counters live in an injected Redis (ioredis) client so limits are shared across replicas, with an in-memory fallback that keeps enforcement alive through Redis outages or when no client is configured. A steady window can be composed with a short burst allowance to absorb legitimate spikes.

createGlobalRateLimiter() guards pre-authentication traffic by client IP.

createLocalRateLimiter() enforces per-actor, per-resource quotas for identified traffic.

createRateLimiter() exposes the underlying core for anything else.

Classes ​

ClassDescription
RateLimitExceededError

Thrown when a key has exhausted its rate-limit allowance.

Carries everything needed to build an HTTP 429 response. See RateLimitExceededError.toHttpHeaders() for deriving a Retry-After header value.

Functions ​

FunctionDescription
createGlobalRateLimiter(options)

Create a pre-authentication rate limiter keyed purely by client IP.

Mount this before authentication flows that rely on querying critical infrastructure.

Defaults to 100 points per second with no burst. Override via CreateRateLimiterOptions.overrides. Pass skipKeyNormalization: true to use each IP string verbatim as the store key.

createLocalRateLimiter(options)

Create a rate limiter enforcing per-actor, per-resource quotas for identified traffic.

Defaults to 50 points per 10 seconds with a burst of 20 per 30 seconds. Override via CreateRateLimiterOptions.overrides.

createRateLimiter(options)Create a rate limiter backed by the injected Redis client, or by in-memory counters when no client is configured.
normalizeIp(ip)

Derive the store key for a client IP, or null when the input is not a valid IP address so the caller can warn and fall back to the shared bucket.

IPv4 addresses, including IPv4-mapped IPv6 addresses, are keyed per address. IPv6 addresses are keyed by their /64 prefix, since a subscriber typically holds an entire /64 and could otherwise mint a fresh bucket per request by rotating within it.

Output keys have their colons replaced with |-| to avoid colliding with the common namespace:subkey Redis convention.

Interfaces ​

InterfaceDescription
BurstConfigA short-lived allowance layered on top of the steady window to absorb legitimate spikes, such as a page load firing several parallel API calls.
CreateGlobalRateLimiterOptionsOptions for creating a global rate limiter.
CreateRateLimiterOptionsOptions for creating a rate limiter.
FallbackConfigFallback allowance for the in-memory limiter used as insurance during a Redis outage, and as the sole limiter when no client is configured. Both fields are required when overriding the factory's built-in fallback.
GlobalRateLimiterA rate limiter keyed purely by client IP, for use before authentication. Obtain one via createGlobalRateLimiter().
LocalRateLimiterA rate limiter keyed by actor and resource, for identified traffic. Obtain one via createLocalRateLimiter().
Logger

The subset of a structured logger this package needs.

Any logger whose warn/error accept { message, context?, error? } satisfies it, including the logger from @opengovsg/logging.

RateLimitConfigConfiguration for a rate-limit window. Omitted fields inherit the limiter's defaults.
RateLimiterA rate limiter. Obtain one via createRateLimiter(), createGlobalRateLimiter() or createLocalRateLimiter().
RateLimitInfoA snapshot of a key's rate-limit state after a check.

Type Aliases ​

Type AliasDescription
CreateLocalRateLimiterOptionsOptions for creating a local rate limiter.
RedisClientThe ioredis client used to share rate-limit counters across instances.