Express-ralphi

Express middleware for ralphi pure Node.js rate limiting server

Ralphi is a simple rate limiting server intended to prevent bruteforce attacks on logins and other sensitive assets.

For more info about Ralphi other components see ralphi

Plugin Installation

$ npm install -s ralphi-client
$ npm install -s express-ralphi

Usage

Integrate rate limiting in express

const express   = require('express');
const app       = express();
const RateLimit = require('express-ralphi');
const client    = new require('ralphi-client')();

app.use('/login', RateLimit({bucket: 'login', client}));
app.get('/login', (rec, res) => res.send('Success'));

login root will be rate limited according to the bucket settings, and rate limiting headers will be sent with the response.

Configuration Options

• client RalphiClient required - Ralphi client, used to query Ralphi server.
• bucket String required - bucket to use for rate limiting (required when allRoutes is true)
• countSuccess Boolean default(true) - if true request are counted even if they are successful, when set to false only request that result in an error will be counted toward rate limiting.
• getKey Function(request) - A Function that will get the unique client key out of the request object. By default request.info.remoteAddress is used.
• addHeaders Boolean default(true) - Add the headers ‘X-RateLimit-Limit’, ‘X-RateLimit-Remaining’, ‘X-RateLimit-Reset’ for routes that enable rate liming
• headerLimit String default(‘X-RateLimit-Limit’) - name of the header that indicates the request quota
• headerRemaining String default(‘X-RateLimit-Remaining’) - name of the header that indicates the remaining request quota
• headerReset String default(‘X-RateLimit-Reset’) - name of the header that indicates how long until the request quota is reset
• ttlTransform Function(ttl) - A Function that allows transformation of the ttl passed down from the Ralphi server.
• message String default(‘you have exceeded your request limit’) - Error message in case limit has exceeded
• onError Function(error, rec, res, next) default(undefined) - if communication with Ralphi server results in an error, middleware will call this method and stop processing the request. By default request will be rate limited using errorSize and errorDelay settings errorSize Integer default(1) - default record size if Ralphi server is not available errorDelay Integer default(60) - default delay in seconds to send to the user if Ralphi server is not available
• errorLog Function(error) default(undefined) - if communication with Ralphi server results in an error, error will be passed to this method for logging. unlike onError the middleware will keep processing the request

For convince each configuration option has a method that will create a new instance extending the exiting configuration. so it is easy to have specific route configuration -

const express   = require('express');
const app       = express();
const RateLimit = require('express-ralphi');
const client    = new require('ralphi-client')();

const baseRateLimit = RateLimit({bucket: 'login', client, errorLog: e => console.log(e)});

app.use('/login', baseRateLimit);
app.get('/login', (rec, res) => res.send('Success'));

app.use('/recover', baseRateLimit.bucket('recover'));
app.get('/recover', (rec, res) => res.send('Success'));

app.use('/api', baseRateLimit.onError((e, req, res, next) => next()).bucket('api'));
app.get('/api', (rec, res) => res.send('Success'));