@heyhru/server-plugin-rate-limit 0.2.0

package/README.md

@@ -0,0 +1,60 @@
+# @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
+
+```bash
+pnpm add @heyhru/server-plugin-rate-limit
+```
+
+## Usage
+
+```ts
+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.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { rateLimitPlugin } from "./rate-limit.js";
+export type { RateLimitPluginOptions } from "./rate-limit.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,75 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  rateLimitPlugin: () => rateLimitPlugin
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/rate-limit.ts
+var import_fastify_plugin = __toESM(require("fastify-plugin"));
+var import_rate_limit = __toESM(require("@fastify/rate-limit"));
+function defaultKeyGenerator(req) {
+  const forwarded = req.headers["x-forwarded-for"];
+  const forwardedIp = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+  return forwardedIp?.split(",")[0]?.trim() || req.headers["x-real-ip"] || req.ip;
+}
+var plugin = async (fastify, opts) => {
+  await fastify.register(import_rate_limit.default, {
+    global: true,
+    max: opts.max ?? 100,
+    timeWindow: opts.timeWindow ?? 6e4,
+    redis: opts.redis ?? void 0,
+    allowList: opts.allowList ?? [],
+    keyGenerator: opts.keyGenerator ?? defaultKeyGenerator,
+    skipOnError: true,
+    enableDraftSpec: false,
+    errorResponseBuilder: () => ({
+      error: "Too many requests, please try again later"
+    }),
+    addHeadersOnExceeding: {
+      "x-ratelimit-limit": true,
+      "x-ratelimit-remaining": true,
+      "x-ratelimit-reset": true
+    },
+    addHeaders: {
+      "x-ratelimit-limit": true,
+      "x-ratelimit-remaining": true,
+      "x-ratelimit-reset": true,
+      "retry-after": true
+    }
+  });
+};
+var rateLimitPlugin = (0, import_fastify_plugin.default)(plugin, { name: "server-plugin-rate-limit" });
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  rateLimitPlugin
+});

package/dist/index.mjs

@@ -0,0 +1,38 @@
+// src/rate-limit.ts
+import fp from "fastify-plugin";
+import rateLimit from "@fastify/rate-limit";
+function defaultKeyGenerator(req) {
+  const forwarded = req.headers["x-forwarded-for"];
+  const forwardedIp = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+  return forwardedIp?.split(",")[0]?.trim() || req.headers["x-real-ip"] || req.ip;
+}
+var plugin = async (fastify, opts) => {
+  await fastify.register(rateLimit, {
+    global: true,
+    max: opts.max ?? 100,
+    timeWindow: opts.timeWindow ?? 6e4,
+    redis: opts.redis ?? void 0,
+    allowList: opts.allowList ?? [],
+    keyGenerator: opts.keyGenerator ?? defaultKeyGenerator,
+    skipOnError: true,
+    enableDraftSpec: false,
+    errorResponseBuilder: () => ({
+      error: "Too many requests, please try again later"
+    }),
+    addHeadersOnExceeding: {
+      "x-ratelimit-limit": true,
+      "x-ratelimit-remaining": true,
+      "x-ratelimit-reset": true
+    },
+    addHeaders: {
+      "x-ratelimit-limit": true,
+      "x-ratelimit-remaining": true,
+      "x-ratelimit-reset": true,
+      "retry-after": true
+    }
+  });
+};
+var rateLimitPlugin = fp(plugin, { name: "server-plugin-rate-limit" });
+export {
+  rateLimitPlugin
+};

package/dist/rate-limit.d.ts

@@ -0,0 +1,18 @@
+import type { FastifyPluginAsync } from "fastify";
+export interface RateLimitPluginOptions {
+    /** Max requests per time window (default: 100) */
+    max?: number;
+    /** Time window in ms or human-readable string (default: 60000) */
+    timeWindow?: number | string;
+    /** ioredis instance for shared store; null = in-memory fallback */
+    redis?: unknown | null;
+    /** IPs excluded from rate limiting */
+    allowList?: string[];
+    /** Custom key generator (default: IP-based with proxy header support) */
+    keyGenerator?: (req: {
+        headers: Record<string, string | string[] | undefined>;
+        ip: string;
+    }) => string;
+}
+export declare const rateLimitPlugin: FastifyPluginAsync<RateLimitPluginOptions>;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACvB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,yEAAyE;IACzE,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC;CACxG;AAqCD,eAAO,MAAM,eAAe,4CAAmD,CAAC"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@heyhru/server-plugin-rate-limit",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.2.0",
+  "description": "Rate limiting Fastify plugin powered by @fastify/rate-limit",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly",
+    "dev": "tsup --watch",
+    "lint": "eslint src",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@fastify/rate-limit": "^10.2.1",
+    "fastify-plugin": "5.1.0"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
+  },
+  "gitHead": "7c589bd1a37ed2def055d4619e914748fe66a15a"
+}