# connect-ratelimit

> connect middleware for ratelimiting clients

Latest version **0.0.7** (published 2014-08-26) · BSD license · 0 weekly downloads

## Install

```sh
npm install connect-ratelimit
pnpm add connect-ratelimit
yarn add connect-ratelimit
bun add connect-ratelimit
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.7 |
| Published | 2014-08-26 |
| First published | 2012-11-21 |
| Weekly downloads | 0 |
| License | BSD |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 57 |
| Maintainers | dharmafly |
| Keywords | connect, middleware, ip, limit, throttle, bandwidth |

## Links

- npm: https://www.npmjs.com/package/connect-ratelimit
- Repository: https://github.com/dharmafly/connect-ratelimit
- Issues: https://github.com/dharmafly/connect-ratelimit/issues
- npm.io page: https://npm.io/package/connect-ratelimit

## Alternatives

- [lodash.startswith](https://npm.io/package/lodash.startswith.md) — 769.7K weekly downloads
- [@tarojs/service](https://npm.io/package/@tarojs/service.md) — 33.9K weekly downloads
- [io.extendreality.tilia.indicators.spatialtargets.unity](https://npm.io/package/io.extendreality.tilia.indicators.spatialtargets.unity.md) — 131 weekly downloads
- [@rtarojs/taro](https://npm.io/package/@rtarojs/taro.md) — 90 weekly downloads
- [node-branch-io](https://npm.io/package/node-branch-io.md) — 50 weekly downloads

## Recent versions

- 0.0.7 (latest) — 2014-08-26
- 0.0.6 — 2014-01-09
- 0.0.5 — 2013-01-08
- 0.0.4-b — 2012-12-21
- 0.0.4 — 2012-12-19
- 0.0.3 — 2012-12-19
- 0.0.2 — 2012-11-21
- 0.0.1 — 2012-11-21
- 0.0.0 — 2012-11-21

## README

connect-ratelimit
=================

```JavaScript
var limiter = require('connect-ratelimit');

app = connect()
      .use(limiter({
        whitelist: ['127.0.0.1'],
        blacklist: ['example.com']
      }))
      .use(function (req, res) {
        res.end('Hello world!');
      });
```

connect-ratelimit is connect middleware for limiting the number of requests per 
client ip/hostname to your node server.

When a limit is reached the middleware will cancel the middleware chain early 
with `res.end('Rate limit exceeded.')` or you can optionally check for a limit 
exceeding yourself elsewhere down the chain.

About
-----

### Categories

Categories serve as templates to manage different types of connecting clients.
By default all clients are categorized as 'normal' but `whitelist` and `blacklist` 
categories also exist. 

#### normal

By default anyone uncategorized will be subject to 500 requests per hour.

#### whitelist

By default client names in the whitelist will be subject to 4000 requests per 
hour.

#### blacklist

By default client names in the blacklist will be subject to 0 requests per 0 
time. In other words they will always be exceding the rate limit.

### Client identification

connect-ratelimit uses the following code to identify clients:

```JavaScript
req.headers['x-forwarded-for'] || req.connection.remoteAddress
```


Usage
-----

```JavaScript
var limiter = require('connect-ratelimit');
```

The middleware takes an options object with the following parameters:

- `whitelist`: An array of strings representing clients you wish to apply to 
the whitelist category. eg. `['127.0.0.1']` for local development.
- `blacklist`: An array of strings representing clients you wish to apply to 
the blacklist category.
- `end`: A boolean when set to false (default true) the connect chain will 
continue even if a client has exceeded the ratelimit. The `response` object is 
augmented with the `ratelimit` namespace. `response.ratelimit` exposes an object 
which contains the various details about the client including if they have past 
their limit as well as all other recorded clients. This is useful if you wish 
to supply your own error response to the client or any other logic.
- `categories`: An object representing the various *total requests* per *time* 
for each category type. See below.

### Configuring the different categories

The `categories` property of the options object for the connect-limiter allows 
you to specify different `totalRequests` and `every` for specific categories.

A fully configured value of the `categories` property could like this:

```JavaScript
{
  whitelist: {
    totalRequests: 5000,
    every:         60 * 60 * 1000
  },
  blacklist: {
    totalRequests: 0,
    every:         0 
  },
  normal: {
    totalRequests: 5,
    every:         60 * 60 * 1000
  }
}
```

Set `totalRequests` to `0` is how to block requests from under category 
entirely.

Below is how you can switch from an hourly rate to a half-hourly rate for all 
categories but blacklist.

```JavaScript
.use(limiter({
  whitelist: ['dharmafly.com'],
  categories: {
    normal: {
      every: (60 * 60 * 1000) / 2
    },
    whitelist: {
      every: (60 * 60 * 1000) / 2
    }
  }
}))
```

You don't need to set every category, just the properties you want to change.

Example
-------

connect is required for the example to run.

```bash
npm install connect
```

To play with the example app run the command below and navigate to 
[localhost:4000](http://localhost:4000)

```bash
node example.js
```

---
_Source: https://npm.io/package/connect-ratelimit · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._