@heyhru/server-plugin-rate-limit

Rate limiting Fastify plugin powered by @fastify/rate-limit. Supports Redis (shared across instances) and in-memory (single-process fallback) stores.

Install

pnpm add @heyhru/server-plugin-rate-limit

Usage

import Fastify from "fastify";
import { rateLimitPlugin } from "@heyhru/server-plugin-rate-limit";

const app = Fastify();

// Global rate limit — 100 req/min per IP
await app.register(rateLimitPlugin, {
  max: 100,
  timeWindow: 60_000,
  redis: app.redis, // optional, falls back to in-memory
});

// Per-route override
app.post("/auth/login", {
  config: {
    rateLimit: {
      max: 5,
      timeWindow: 60_000,
    },
  },
}, handler);

API

rateLimitPlugin

Fastify plugin (wrapped with fastify-plugin).

Options:

| Option | Type | Default | Description | | --------------- | ----------------- | ---------------- | ---------------------------------------------------- | | max | number | 100 | Max requests per time window | | timeWindow | number \| string | 60000 | Time window in ms or human-readable (e.g. "1 minute") | | redis | Redis \| null | null | ioredis instance for shared store; null = in-memory | | allowList | string[] | [] | IPs excluded from rate limiting | | keyGenerator | (req) => string | IP-based | Custom key generator function |

Headers added to responses:

• x-ratelimit-limit — max requests allowed
• x-ratelimit-remaining — remaining requests in window
• x-ratelimit-reset — seconds until window resets
• retry-after — seconds to wait (only on 429)

Degradation: When redis is null or unavailable, the plugin uses an in-memory LRU store automatically. skipOnError: true ensures Redis failures never block requests.