rate-limit

Enforces per-client request rate limits using a sliding-window counter. On allowed requests, injects X-RateLimit-* response headers. On limited requests, returns 429 Too Many Requests with a Retry-After value.

The store is pluggable — any object implementing hit(key, windowMs) → { count, resetMs } can replace the built-in MemoryStore for Redis-backed or distributed rate limiting.

Pipeline stage: Negotiation

Import

import { rateLimit } from "@centralping/ergo";

Options

Option	Type	Default	Description
max	number	100	Maximum requests per window
windowMs	number	60000 (1 min)	Window duration in milliseconds
store	object	MemoryStore	Pluggable store with hit(key, windowMs) interface
keyGenerator	function	defaultKeyGenerator	(req) => string — client identifier (default: req.socket.remoteAddress)

Return Value

Allowed Request

{
  response: {
    headers: [
      ["X-RateLimit-Limit", "100"],
      ["X-RateLimit-Remaining", "99"],
      ["X-RateLimit-Reset", "1717041600"]
    ]
  }
}

Limited Request

{
  response: {
    statusCode: 429,
    retryAfter: 30
  }
}

send() automatically sets the Retry-After header and formats the RFC 9457 error body.

Error Responses

Status	Condition
429 Too Many Requests	Request count exceeds max within windowMs

Usage

Standalone

import { compose, rateLimit } from "@centralping/ergo";

const pipeline = compose(
  rateLimit({ max: 100, windowMs: 60_000 }),
  (req, res, acc) => ({
    response: { statusCode: 200, body: { ok: true } },
  }),
);

ergo-router

const router = createRouter({
  defaults: {
    rateLimit: { max: 100, windowMs: 60_000 },
  },
});

RFC References

• RFC 6585 §4 — 429 Too Many Requests

API Reference

See the auto-generated rateLimit API docs.