Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

odysseus-limit

0.0.5 • Public • Published

Odysseus Limiter

NPM Version Linux Build Test Coverage

Throttle limiting requests middleware for express apps. Can be backed by redis for maintainable and scalable apps.

Installation

$ npm install odysseus-limit

Examples

In the example below, after exceed 100 requests in 10 seconds, it will not proceed to next(). Each requests have time to live of 10 seconds. So, after 10 seconds from the first request, the limiter will proceed to next():

let OdysseusLimiter = require('odysseus-limit');
 
app.use(OdysseusLimiter.limit({amount: 100, ttl: 10000},
    (req, res, next) => {
        res.status(200).send('hello world');
    });

You can block requests by key. Meaning that if requests with same key where exceed the rate specified, all next requests form the same key will be blocked (until ttl of some request will expire). For example:

let OdysseusLimiter = require('odysseus-limit');
let options = {
    key: (req) => { // req = requet express object
        return req.body.username;
    },
    amount: 100,
    ttl: 10000
};
app.use(OdysseusLimiter.limit(options);

And here you can block by IP:

let OdysseusLimiter = require('odysseus-limit');
let options = {
    key: (req) => {
        return req.connection.remoteAddress;
    },
    amount: 100,
    ttl: 10000
};
app.use(OdysseusLimiter.limit(options);

Manage requets in redis for higher scalability:

let OdysseusLimiter = require('odysseus-limit');
let options = {
    store: new OdysseusLimiter.RedisStore({
        host: 'localhost',
        port: 6379
    });
    amount: 100,
    ttl: 10000
};
app.use(OdysseusLimiter.limit(options);

Classes

  • LocalStore - The requests save in memory.
  • RedisStore - implementation of Store. The requests are save in redis.
    • options:
      • host - host of redis
      • port - port of redis
      • client - predefined redis client
  • limit - An express middleware that limits requests.

limit middleware options:

Property Default Description
amount no default as noted above
ttl no default as noted above
store LocalStore where the requests are managed
key 'general' give each request a key and throttle by that key

More Complex Example

let OdysseusLimiter = require('odysseus-limit');
let store = new OdysseusLimiter.RedisStore({
    host: 'localhost',
    port: 6379
});
let options = {
    store: store,
    key: (req) => {
        return req.body.username;
    },
    amount: (req) => {
        return req.body.isAdmin ? 1000 : 50;
    },
    ttl: (req) => {
        return req.body.isAdmin ? 10 : 10000;
    }
};
app.use(OdysseusLimiter.limit(options),
    (req, res, next) => {
        res.status(200).send('Do\'h');
    });
app.listen(9638, () => {
    console.log('Start listening to port 9638');
});

Test

The tests are written with mocha, supertest and chai under the folder 'test'

Run tests with:

npm test

Features

  • Robust limiting.
  • Highly scalable.
  • Support limiting multiple routes and services.
  • Open for customisation (store, key, amount and ttl).

Install

npm i odysseus-limit

DownloadsWeekly Downloads

11

Version

0.0.5

License

MIT

Unpacked Size

12.6 kB

Total Files

10

Last publish

Collaborators

  • avatar