# koa-auto-ratelimit

> Rate limiter middleware for koa.

Latest version **1.0.5** (published 2023-09-15) · ISC license · 0 weekly downloads

## Install

```sh
npm install koa-auto-ratelimit
pnpm add koa-auto-ratelimit
yarn add koa-auto-ratelimit
bun add koa-auto-ratelimit
```

## Health

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

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.5 |
| Published | 2023-09-15 |
| First published | 2023-09-15 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 10.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | luohongweb |

## Links

- npm: https://www.npmjs.com/package/koa-auto-ratelimit
- Repository: https://github.com/luoHongFSD/koa-token-bucket
- Homepage: https://github.com/luoHongFSD/koa-token-bucket#readme
- Issues: https://github.com/luoHongFSD/koa-token-bucket/issues
- npm.io page: https://npm.io/package/koa-auto-ratelimit

## Dependencies (4)

- [debug](https://npm.io/package/debug.md) ^4.3.4
- [redis](https://npm.io/package/redis.md) ^4.6.8
- [assert](https://npm.io/package/assert.md) ^2.0.0
- [ioredis](https://npm.io/package/ioredis.md) ^5.3.2

## Recent versions

- 1.0.5 (latest) — 2023-09-15

## README

# koa-auto-ratelimit

Rate limiter middleware for koa.

## Installation

```bash
# npm
$ npm install koa-auto-ratelimit
# yarn
$ yarn add koa-auto-ratelimit
```

## Example

### With a Redis driver

```js
const Koa = require("koa");
const Redis = require("ioredis");
const app = new Koa();

const ratelimit = require("koa-auto-ratelimit").default;
//import ratelimit from "koa-auto-ratelimit";
// apply rate limit
app.use(
  ratelimit({
    driver: "redis",
    redis: new Redis(),
    capacity: 100, //总令牌桶数
    rate: 10, //1秒生成多少个令牌
    hitCounts:10 //被拒绝十次后，就永远被拒绝。如果hitCounts 等于0 ,默认无判断拒绝次数。
    errorMessage: "Sometimes You Just Have to Slow Down.",
    id: (ctx) => ctx.ip,
    headers: {
      rate: "X-RateLimit-Rate",
      tokens: "X-RateLimit-Tokens",
      capacity: "X-RateLimit-Capacity",
    },
    disableHeader: false,
    whitelist: (ctx) => {
      // some logic that returns a boolean
    },
    blacklist: (ctx) => {
      // some logic that returns a boolean
    },
  })
);

// response middleware
app.use(async (ctx) => {
  ctx.body = "Stuff!";
});

// run server
app.listen(3000, () => console.log("listening on port 3000"));
```

### With a Memory driver

```js
const Koa = require("koa");
const Redis = require("ioredis");
const app = new Koa();
const ratelimit = require("koa-auto-ratelimit").default;
//import tokenBucket from "koa-token-bucket";
// apply rate limit
app.use(
  ratelimit({
    driver: "memory",
    capacity: 100, //总令牌桶数
    rate: 10, //1秒生成多少个令牌
    hitCounts:10 //被拒绝十次后，就永远被拒绝。如果hitCounts 等于0 ,默认无判断拒绝次数。
    errorMessage: "Sometimes You Just Have to Slow Down.",
    id: (ctx) => ctx.ip,
    headers: {
      rate: "X-RateLimit-Rate",
      tokens: "X-RateLimit-Tokens",
      capacity: "X-RateLimit-Capacity",
    },
    disableHeader: false,
    whitelist: (ctx) => {
      // some logic that returns a boolean
    },
    blacklist: (ctx) => {
      // some logic that returns a boolean
    },
  })
);

// response middleware
app.use(async (ctx) => {
  ctx.body = "Stuff!";
});

// run server
app.listen(3000, () => console.log("listening on port 3000"));
```

## Options

- `capacity` capacity number of requests ['X-RateLimit-Capacity']
- `rate` rate timestamp ['X-RateLimit-Rate']
- `tokens` tokens number of requests ['X-RateLimit-Tokens']
- `errorMessage` custom error message
- `id` id to compare requests [ip]
- `headers` custom header names
- `disableHeader` set whether send the `capacity, rate, tokens` headers [false]
- `whitelist` if function returns true, middleware exits before limiting
- `blacklist` if function returns true, `403` error is thrown
- `throw` call ctx.throw if true

## Responses

Example 200 with header fields:

```
HTTP/1.1 200 OK
X-Powered-By: koa
X-RateLimit-Rate: 10
X-RateLimit-Tokens: 99
X-RateLimit-Capacity: 100
Content-Type: text/plain; charset=utf-8
Content-Length: 6
Date: Wed, 13 Nov 2013 21:22:13 GMT
Connection: keep-alive

Stuff!
```

Example 429 response:

```
HTTP/1.1 429 Too Many Requests
X-Powered-By: koa
X-RateLimit-Rate: 10
X-RateLimit-Tokens: 0
X-RateLimit-Capacity: 100
Content-Type: text/plain; charset=utf-8
Content-Length: 39
Retry-After: 7
Date: Wed, 13 Nov 2013 21:21:48 GMT
Connection: keep-alive

Rate limit exceeded
```

## License

[MIT](LICENSE)

##

Please introduce me to a job

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