# @npm/spife-ratelimit

> Middleware that adds [Token Bucket]-style ratelimiting to [Spife].

Latest version **2.0.1** (published 2018-03-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install @npm/spife-ratelimit
pnpm add @npm/spife-ratelimit
yarn add @npm/spife-ratelimit
bun add @npm/spife-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 | 2.0.1 |
| Published | 2018-03-12 |
| First published | 2018-01-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 26.4 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | Chris Dickinson |
| Maintainers | adam_baldwin, aearly, ag_dubs, amzod, arobson, bcoe, buzuli, carolynwriter, ceejbot, chrisdickinson, ehsalazar, elizposadas, gabra, iarna, isaacs, jec, jlembeck, katiefenn, kmanion, labond, lisayu, ljon, mmalecki, nlf, npm, npmci, rockbot, seldo, soldair, zkat |

## Links

- npm: https://www.npmjs.com/package/@npm/spife-ratelimit
- Repository: https://github.com/npm/spife-ratelimit
- Homepage: https://github.com/npm/spife-ratelimit#readme
- Issues: https://github.com/npm/spife-ratelimit/issues
- npm.io page: https://npm.io/package/@npm/spife-ratelimit

## Dependencies (1)

- [redis](https://npm.io/package/redis.md) ^2.8.0

## Recent versions

- 2.0.1 (latest) — 2018-03-12
- 2.0.0 — 2018-01-11

## README

# spife-ratelimiter

Middleware that adds [Token Bucket]-style ratelimiting to [Spife].

```javascript
// settings.js:
module.exports.MIDDLEWARE = {
  ['@npm/spife-ratelimiting', {
    redisUrl: 'redis://localhost:6379', // let it connect to redis
    redisClient,                        // (or give it a client)

    costHeader: 'npm-cost',             // the "cost" header to use
                                        // for determining how many
                                        // tokens a request took

    clock: Date.now,                    // if you would like time to
                                        // move to the beat of a
                                        // different drum

    getBucket (spifeRequest) {          // given a request, return
                                        // an object describing its
                                        // token bucket
      return {
        capacity: 100,                  // how many tokens does
                                        // the bucket hold?

        interval: 60,                   // in minutes, how long
                                        // does the bucket take to
                                        // fill up?

        key: String                     // what should the bucket be
                                        // named?
      }
    }
  }]
}

// views.js:
const reply = require('@npm/spife/reply')
const cost = require('@npm/spife-ratelimiter/decorator')

module.exports = {
  // a view can declare how much it costs up-front:
  index: cost(index, 5),
  other
}

function index (req, context) {
  return 'I cost five tokens!'
}

function other (req, context) {
  return reply.header(
    'I cost a hundred tokens sometimes',
    'npm-cost',
    Math.random() > 0.5 ? 100 : 0
  )
}
```

This is implemented in redis by keeping two keys per bucket: one that
tracks the current number of tokens, and one that tracks the last update
time. Both keys are expired at `interval`, and updated atomically using a
Lua script.

[Token Bucket]: https://en.wikipedia.org/wiki/Token_bucket
[Spife]: https://github.com/npm/spife

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