express-rate-limiter-core v2.0.2

Express Rate Limit Core

A library to that disponibility is an easy middleware to limit request rate in the server express.

Install

To install express-rate-limiter-core, just run the following command:

npm install express-rate-limiter-core

Features

• Rate-limit per second
• Rate-limit per minutes
• Rate-limit per period
• Block system to requets
• Storage in Memory or Redis
• Support for Storage Customization

Cache

• Redis Cache: Use Redis to manage your cache. Ideal for environments that require scalability.
• Cache in Memory: it does not have support to scale this is only a simple cache that will be in your server.
• Custom Cache: the library available an interface CustomCache with this interface you can implement your owner cache manager.

Note

• If your storage needs are in a different location, then you need to implement a class with the Custom interface and pass the instance of this class to the cache attribute. When doing this, the strategyCache property must be set to CUSTOM.

TypeScript Support

This library provides interfaces that can be used with TypeScript.

Exemples

Docker

Start an example with Docker by viewing the readme in the example directory.

Importing

import { RateLimitExpress, Redis } from "express-rate-limiter-core";

Request per Seconds or Minutes

// Exemple RateLimitExpress with cache in Memory
const app = express();

const rateLimit = RateLimitExpress({
  // This field is optional; when not defined, it defaults to IN_MEMORY.
  strategyCache: 'IN_MEMORY',

  policy: {
    type: "REQUEST_PER_SECONDS", // REQUEST_PER_SECONDS, REQUEST_PER_MINUTES

    periodWindow: 10,

    maxRequests: 10,
  },
});

// Exemple RateLimitExpress with cache in Redis
const redisClient = Redis.createClient({
    url: 'redis://localhost:6379'
});

const rateLimit = RateLimitExpress({
  // This field is optional and support IN_MEMORY, REDIS and CUSTOM
  strategyCache: 'REDIS',
  
  redis: redisClient,

  policy: {
    type: "REQUEST_PER_SECONDS", // REQUEST_PER_SECONDS, REQUEST_PER_MINUTES

    periodWindow: 10,

    maxRequests: 10,
  },
});

// The implementation can be done in any storage you need. The only requirement is to respect the interface contracts; if you wish, you can draw inspiration from already implemented repositories.

class CustomCacheExemple implements CustomCache {}

// Exemple RateLimitExpress with custom cache
const rateLimit = RateLimitExpress({
  // This field is optional and support IN_MEMORY, REDIS and CUSTOM
  strategyCache: 'CUSTOM',

  cache: new CustomCacheExemple(),

  policy: {
    type: "REQUEST_PER_SECONDS", // REQUEST_PER_SECONDS, REQUEST_PER_MINUTES

    periodWindow: 10,

    maxRequests: 10,
  },
});

Request per Period

// Exemple RateLimitExpress with cache in Memory
const rateLimit = RateLimitExpress({

  policy: {
    type: "REQUEST_PER_PERIOD",

    // date representing when rate-limit will be start
    periodWindowStart: new Date("2023-02-22T19:02:57.087Z"),

    //date representing when rate-limit will be end
    periodWindowEnd: new Date("2023-02-22T19:06:57.087Z"),

    // max requests allowed in the interval start and end
    maxRequests: 10,
  },
});

Block Request Rule

// exemple cache in memory

import express from "express";
import { RateLimitExpress } from "express-rate-limiter-core";

const app = express();

const rateLimit = RateLimitExpress({
  policy: {
    type: "REQUEST_PER_PERIOD",

    // date representing when rate-limit will be start
    periodWindowStart: new Date("2023-02-22T19:02:57.087Z"),

    //date representing when rate-limit will be end
    periodWindowEnd: new Date("2023-02-22T19:06:57.087Z"),

    // max requests allowed in the interval start and end
    maxRequests: 10,
  },

  /**
   * In this  Method, you can implement block request rules.
   * The method to have request express object available to use
   */
  blockRequestRule: (requestExpress) => {
    // this is only an example. You can implement of more forms
    const blackList = ["192.168.1.10", "192.168.1.11", "192.168.1.12"];
    if (blackList.includes(requestExpress.ip)) {
      return true;
    }

    return false;
  },
});

How use ?

/**
 * Apply rate-limit in the express.
 */
app.use(rateLimit.apply);

Constructor Parameters

Policy to Request per Seconds

Object Specification policy:

Policy to Request per Minutes

Object Specification policy:

Policy to Request per Period

Object Specification policy:

Response

Headers

Issues and Contributing

• Issues: If you encounter a bug or wish to see something added/changed, please open an issue!

• Discussion: If you need assistance with anything related to the project, whether it's understanding how to use a particular feature, troubleshooting an issue, or anything start a discussion here!

• Contributing: To contributing please read the guide.

License

MIT