Connect Rate Limit Middleware

0.0.7 verified Thu Apr 23 auth: no javascript abandoned

connect-ratelimit is a Connect middleware designed to limit the number of requests per client IP address or hostname to a Node.js server. As of its last known update, it is at version 0.0.7, indicating a very early stage of development and a likely abandoned status, with no new releases since August 2014. It distinguishes clients using `req.headers['x-forwarded-for']` or `req.connection.remoteAddress` and supports flexible rate limiting rules through configurable 'normal', 'whitelist', and 'blacklist' categories. Uniquely, it offers an `end` option to either prematurely terminate the middleware chain with a 'Rate limit exceeded' message or allow the chain to continue, augmenting the `response` object with rate limit details for custom handling. This package is built for the `connect` framework, which is less commonly used directly in modern Node.js web applications, often replaced by frameworks like Express. Its core differentiation lies in its direct integration with `connect`'s simple middleware pattern and its customizable category-based limiting, though newer, more robust alternatives exist for current Node.js ecosystems.

Common errors

error ReferenceError: require is not defined ↓

cause Attempting to import `connect-ratelimit` using ES module syntax (`import`) in a JavaScript file configured as an ES module.

fix

This package is CommonJS-only. Either convert your consuming file to CommonJS (.js without "type": "module" in package.json) and use const limiter = require('connect-ratelimit');, or use a modern rate-limiting library compatible with ESM.

error TypeError: app.use is not a function ↓

cause Using the `connect-ratelimit` middleware directly with an `express` application instance without the `connect` compatibility layer.

fix

Ensure you are either using the connect framework directly (const app = connect();) or, if using Express, consider express-rate-limit which is designed for Express. If you must use this middleware with Express, you'd typically wrap it: app.use(connect().use(limiter(...))); which is generally not recommended.

error Client is not being rate limited, or is being rate limited incorrectly. ↓

cause The client identification mechanism (`x-forwarded-for` or `remoteAddress`) is not accurately reflecting the true client IP, often due to improper proxy configuration or IP spoofing.

fix

Verify that your proxy (e.g., Nginx, cloud load balancer) is correctly forwarding client IP addresses via the X-Forwarded-For header and that your Node.js application is trusting these headers. Also consider using a more modern rate-limiting solution that supports various client identification strategies.

Warnings

breaking This package is explicitly designed for the 'connect' framework, which is an older middleware system. Direct usage with modern Express.js applications without an explicit 'connect' compatibility layer may lead to unexpected behavior or errors. ↓

fix For Express.js, consider 'express-rate-limit' or 'rate-limiter-flexible'. If using 'connect', ensure your application correctly integrates 'connect' middleware.

breaking The package is version 0.0.7 and has not been updated since August 2014. It is considered abandoned and will not receive security patches, bug fixes, or compatibility updates for newer Node.js versions or evolving web standards. Using it in production is strongly discouraged. ↓

fix Migrate to a actively maintained rate-limiting solution like 'express-rate-limit' (for Express) or 'rate-limiter-flexible' (for more general Node.js use cases).

gotcha Client identification relies on `req.headers['x-forwarded-for']` or `req.connection.remoteAddress`. In environments behind a proxy (like Nginx, AWS ELB, etc.), `remoteAddress` will be the proxy's IP, and `x-forwarded-for` can be spoofed if the proxy isn't configured to set it correctly and securely. This can lead to incorrect rate limiting or bypasses. ↓

fix Ensure your proxy infrastructure correctly sets and forwards client IP headers. For more robust identification, consider rate limiters that integrate with other client attributes (e.g., authenticated user IDs, API keys) or use a trusted proxy solution.

breaking This package is a CommonJS module, requiring `require()` for inclusion. It is not directly compatible with native ES Modules (ESM) without a transpilation step or a CommonJS wrapper. ↓

fix If your project uses native ESM, you will need to use a compatible modern rate-limiting library. If you must use this package, ensure your project is configured for CommonJS or use dynamic `import()` within an async context (though this is not recommended for an abandoned package).

Install

npm install connect-ratelimit

yarn add connect-ratelimit

pnpm add connect-ratelimit

Imports

limiter
wrong
```
import limiter from 'connect-ratelimit';
```
correct
```
const limiter = require('connect-ratelimit');
```
This package is CommonJS-only and does not support ES module `import` syntax.

Quickstart

Demonstrates basic rate limiting with whitelisting and custom categories using the 'connect' framework, running a simple HTTP server.

const connect = require('connect');
const http = require('http');
const limiter = require('connect-ratelimit');

const app = connect();

// Basic rate limiting: 500 requests/hour for 'normal' clients
// 4000 requests/hour for 'whitelist', 0 for 'blacklist'
app.use(limiter({
  whitelist: ['127.0.0.1'], // Whitelist local IP
  blacklist: ['example.com'], // Blacklist a domain
  categories: {
    normal: {
      totalRequests: 5, // For demonstration, set a low limit
      every: 60 * 1000 // 5 requests per minute
    }
  },
  end: true // Terminate middleware chain if limit exceeded (default)
}));

app.use(function (req, res) {
  res.end('Hello world! Your IP is: ' + (req.headers['x-forwarded-for'] || req.connection.remoteAddress));
});

http.createServer(app).listen(4000, () => {
  console.log('Connect server running on http://localhost:4000');
  console.log('Try refreshing the page to hit rate limits for 127.0.0.1');
});