Ralphi Client

Client 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

Client Installation

$ npm install -s ralphi-client

Usage

const host = 'localhost';
const port = 8910;
const RalphiClient = require('ralphi-client');
const client = new RalphiClient({port, host});

async function handler (req, res) { //in your handler code
    const limit = await client.take('login', req.ip);
    if (limit.conformant) {
        //allow access
        return `Request was done. You have ${limit.remaining} more requests until ${new Date(limit.ttl * 1000)}`;
    } else {
        //reject access
        throw new Error(`You have made too many requests. You can send ${limit.size} requests after ${new Date(limit.ttl * 1000)}`);
    }
}

Config options

• host String (localhost) - host/ip where Ralphi server is running on
• port Integer (8910) - port Ralphi server listens on
• timeout Integer (5000) - timeout for requests in miliseconds
• keepAlive Boolean (false) - if true http keep alive will be enabled when connecting to ralphi server (should have performance benefit)

API

Ralphi Client is using a Promise API all methods return Promises

• take(bucket String, key String)` - remove one request token for key associated with bucket. Returns an object containing the following properties -
  • conformant Boolean - true if record had remaining request tokens and can be accepted. false if request did not have any tokens left and should not be accepted.
  • remaining Integer - the amount of requests that can still be made in the current time frame
  • ttl Integer - UNIX timestamp indicating when more requests will be available
  • size Integer - Total number of request tokens available in each time frame
• give(bucket String, key String)` - adds one request token for key associated with bucket. Returns an object containing the following properties -
  • conformant Boolean - true if after increase record has remaining request tokens. false if request still does not have any tokens left.
  • remaining Integer - the amount of requests that can still be made in the current time frame
  • ttl Integer - UNIX timestamp indicating when more requests will be available
  • size Integer - Total number of request tokens available in each time frame Please note that give is meant to be used to give back a token that wasn't suppose to be taken (like if login was successful). even after giving a token you can't be sure next request will be conformant cause other requests may have overdrawn the bucket if you want to manually force bucket to have more tokens you should use reset
• query(bucket String, key String)` - similar to take but will only query rate limit stats without removing any tokens. Returns an object containing the following properties -
  • conformant Boolean - true if record had remaining request tokens and can be accepted. false if request did not have any tokens left and should not be accepted.
  • remaining Integer - the amount of requests that can still be made in the current time frame
  • ttl Integer - UNIX timestamp indicating when more requests will be available
  • size Integer - Total number of request tokens available in each time frame
• reset(bucket String, key String) - remove a single record from the bucket. Removing a record means next request with the same key will get a fresh record with maximum available requests. returns true if record existed and false if it wasn't
• clean() - Remove all expired records from the bucket.