@6thbridge/utils 1.10.3 → 1.10.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@6thbridge/utils",
-  "version": "1.10.3",
+  "version": "1.10.5",
   "description": "simple interface for the our commonly used functions",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -31,6 +31,7 @@
     "bignumber.js": "^11.1.5",
     "csv-parse": "^7.0.2",
     "dayjs": "^1.11.23",
+    "express-rate-limit": "8.7.1",
     "ioredis": "^6.0.0",
     "joi": "^18.3.1",
     "libphonenumber-js": "^1.13.13",
@@ -39,6 +40,7 @@
     "mongoose-paginate-v2": "^1.9.5",
     "path-to-regexp": "^8.4.2",
     "randomstring": "^1.3.1",
+    "rate-limit-redis": "6.0.1",
     "redlock": "^5.0.0-beta.2",
     "rollbar": "^3.1.0",
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",

package/readme.md

@@ -90,6 +90,56 @@ Express.js middlewares for common functionality.
 - **Authentication**: JWT and API key validation
 - **Validation**: Request/response validation
 - **Error Handling**: Centralized error processing
+- **Rate Limiting**: Redis-backed request limits with a service-owned ioredis connection
+
+#### Shared rate limiter
+
+```typescript
+import Redis from 'ioredis';
+import { Ratelimiter } from '@6thbridge/utils';
+
+const redisClient = new Redis(process.env.REDIS_URL);
+Ratelimiter.configure({
+  redisClient,
+  serviceName: 'my-service',
+});
+
+const loginLimiter = Ratelimiter.limit({
+  keyPrefix: 'login',
+  numberOfTries: 5,
+  skipSuccessfulRequests: true,
+});
+
+// Use loginLimiter as Express middleware on your login route.
+```
+
+The default limit is five attempts per IP in a 30-minute window. Exceeding it
+returns HTTP 429 with `errorCode: 'RateLimitExceeded'`. Set `skipSuccessfulRequests`
+to exclude successful responses from the count; it defaults to `false`.
+
+Call `Ratelimiter.configure({ redisClient, serviceName })` during startup before
+creating limiters. It accepts an existing standard ioredis `Redis` connection;
+the calling service owns connection setup and shutdown. Calling `limit` before
+configuration throws an error. Individual `limit` calls no longer take a client.
+
+`serviceName` is optional and defaults to `process.env.APP_NAME`, so
+`Ratelimiter.configure({ redisClient })` is enough when `APP_NAME` is set.
+An explicit `serviceName` takes precedence. Configuration throws if neither
+provides a service name.
+
+Every Redis key starts with `rl:<serviceName>:`. Set a route-specific `keyPrefix`
+to isolate counters within a service; its default is `rate-limit-key`. For example,
+the login limiter above uses `rl:my-service:login:<normalized-ip>`. Services with
+different names can safely share Redis. Existing limiters retain the configuration
+they were created with if `configure` is called again.
+
+An optional synchronous `keyGenerator(req, res)` replaces the default key,
+including `keyPrefix`, while preserving the service prefix. Without it, the
+limiter uses `res.locals.ip`, then
+`cf-connecting-ip`, `x-forwarded-for`, the `ip` header, or `req.ip`, in that order,
+and normalizes IPv6 addresses. Configure trusted proxies to supply these values.
+
+The class is also available as `middlewares.Ratelimiter` from the package root.
 
 ### 📊 [Monitoring](./src/monitoring/README.md)
 Application monitoring and observability tools.