# @ladjs/koa-simple-ratelimit

> Fork of koa-simple-ratelimit with better tests and options. Simple Rate limiter middleware for koa v2

Latest version **4.1.1** (published 2022-11-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install @ladjs/koa-simple-ratelimit
pnpm add @ladjs/koa-simple-ratelimit
yarn add @ladjs/koa-simple-ratelimit
bun add @ladjs/koa-simple-ratelimit
```

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.1.1 |
| Published | 2022-11-22 |
| First published | 2022-05-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=14 |
| Dependencies | 2 |
| Unpacked size | 9.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Scott Cooper |
| Maintainers | titanism, shadowgate15, niftylettuce, shaunwarman, spence-s |
| Keywords | abuse, api, ddos, http, koa, limit, limiter, middleware, protection, rate, ratelimit, ratelimiter, request, spam |

## Links

- npm: https://www.npmjs.com/package/@ladjs/koa-simple-ratelimit
- Repository: https://github.com/ladjs/koa-simple-ratelimit
- Issues: https://github.com/ladjs/koa-simple-ratelimit/issues
- npm.io page: https://npm.io/package/@ladjs/koa-simple-ratelimit

## Dependencies (2)

- [ms](https://npm.io/package/ms.md) ^2.1.3
- [multimatch](https://npm.io/package/multimatch.md) 5

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 4.1.1 (latest) — 2022-11-22
- 4.1.0 — 2022-11-22
- 4.0.2 — 2022-11-10
- 4.0.1 — 2022-07-02
- 4.0.0 — 2022-07-02
- 3.0.0 — 2022-05-27

## README

# [**@ladjs/koa-simple-ratelimit**](https://github.com/ladjs/koa-simple-ratelimit)

[![build status](https://github.com/ladjs/koa-simple-ratelimit/actions/workflows/ci.yml/badge.svg)](https://github.com/ladjs/koa-simple-ratelimit/actions/workflows/ci.yml)
[![code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)
[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
[![made with lass](https://img.shields.io/badge/made_with-lass-95CC28.svg)](https://lass.js.org)
[![license](https://img.shields.io/github/license/ladjs/koa-simple-ratelimit.svg)](LICENSE)

> **Fork of koa-simple-ratelimit with better tests and options.** Rate limiter middleware for koa v2. Differs from [koa-ratelimit](https://github.com/koajs/ratelimit) by not depending on [ratelimiter](https://github.com/tj/node-ratelimiter) and using redis ttl (time to live) to handle expiration time remaining. This creates only one entry in redis instead of the three that node-ratelimiter does.


## Table of Contents

* [Install](#install)
* [Example](#example)
* [Options](#options)
* [Responses](#responses)
* [License](#license)


## Install

```sh
npm install @ladjs/koa-simple-ratelimit
```


## Example

```js
const Koa = require('koa');
const Redis = require('ioredis-mock');

const ratelimit = require('.');

const app = new Koa();

app.use(
  ratelimit({
    db: new Redis(),
    duration: 60_000,
    max: 100
  })
);

app.use((ctx) => {
  ctx.body = 'Stuff!';
});

app.listen(4000);

console.log('listening on port http://localhost:4000');

module.exports = app;
```


## Options

* `db` (Object) Redis connection instance **required**
* `max` (Number) number of max requests within `duration` (defaults to `2500`)
* `duration` (Number) duration of limit in milliseconds (defaults to `3600000`)
* `throw` (Boolean) whether or not to throw an error with `ctx.throw` (defaults to `false`)
* `prefix` (String) redis key prefix (defaults to `limit`)
* `id` (Function) function accepting an argument `ctx` that returns an id to compare requests with (defaults to `ip` via `ctx.ip`)
* `allowlist` (Array) an array of ids to allowlist (defaults to `[]`)
* `blocklist` (Array) an array of ids to blocklist (defaults to `[]`)
* `logger` (Function) a logger to log database errors with (to prevent app middleware requests from failing due to database connection issues) - set this value to `false` to disable the logger output
* `headers` (Object) containing keys `remaining`, `reset`, and `total` which set the headers on the HTTP request to `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and `X-RateLimit-Limit` by default respectively
* `errorMessage` (Function) a function accepting an argument `exp` which is the number of milliseconds until limitation expiry (see code for default) – it also accepts a second argument of `ctx`
* `ignoredPathGlobs` (Array) defaults to an empty Array, but you can pass an Array of glob paths to ignore


## Responses

Example 200 with header fields:

```sh
HTTP/1.1 200 OK
X-Powered-By: koa
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1384377793
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:

```sh
HTTP/1.1 429 Too Many Requests
X-Powered-By: koa
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1384377716
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, retry in 8 seconds
```


## License

[MIT](LICENSE) © Scott Cooper

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