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.

Interface	Description
Redis:	You do not need to install the Redis library in your project. Simply obtain the Redis object through the import from express-rate-limiter-core.
CustomCache:	the interface provides a model for the implementation custom cache.
RateLimitCache:	interface provides a model for the response of the CustomCache.
Settings:	interface provides a model for the construction parameters of the library.

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

Parameter	Required	Description
`redis`	No	This property should be the instance of your Redis. If you wish, you can import the `Redis` library with `import { Redis } from "express-rate-limiter-core";`.
`cache`	No	Accepts a custom cache instance to store rate-limiting information. This property should be used in conjunction with `strategyCache` set to `CUSTOM`.
`policy`	Yes	A object with policy to service.
`strategyCache`	No	This property is used as a cache strategy, allowing you to set the values `IN_MEMORY`, `REDIS`, or `CUSTOM`.
`blockRequestRule`	No	Function optional to implement the rule of locking in your service. The function receives the property 'request' of the object express.

Policy to Request per Seconds

Object Specification policy:

Parameter	Type	Require	Description
`policy.type`	`REQUEST_PER_SECONDS`	true	type policy
`policy.periodWindow`	number	true	period window in seconds is utilized to calculate the time wait. Exemple: if defined `maxRequest: 100` and `periodWindow:60` the user needs to wait 60 seconds after 100 requets
`policy.maxRequests`	number	true	is the number request that the client 'ip' to can receive

Policy to Request per Minutes

Object Specification policy:

Parameter	Type	Require	Description
`policy.type`	`REQUEST_PER_MINUTES`	true	type policy
`policy.periodWindow`	number	true	period window in minutes is utilized to calculate the time wait. Exemple: if defined `maxRequest: 100` and `periodWindow:60` the user needs to wait 60 minutos after 100 requets
`policy.maxRequests`	number	true	is the number request that the client 'ip' to can receive

Policy to Request per Period

Object Specification policy:

Parameter	Type	Require	Description
`policy.type`	`REQUEST_PER_PERIOD`	true	type policy
`policy.maxRequests`	number	true	is the number request that the client 'ip' to can receive
`policy.periodWindowStart`	Date	true	date representing when rate-limit will be start
`policy.periodWindowEnd`	Date	true	date representing when rate-limit will be end

Response

Status code	message	description
429	Too many requests. You've exceeded the rate-limit for requests	This message is returned to all types of policies when the request limit is exceeded.
403	Unauthorized Request!	This message is returned only when the property `blockRequestRule` is passed in the instance of the library and returns `True`.
500	Other errors	This message is returned ever that a property doesn't is passed correctly in the instance of the library. Possible scenaries: `MISSING_PROPERTY`,`PROPERTY_IS_NOT_INSTANCE_DATE`,`PROPERTY_IS_NOT_NUMBER` and `PROPERTY_IS_NOT_STRING`,

Headers

Header	Always Returned	Description
`X-RateLimit-Limit`	Yes	used to identify max request limit
`X-RateLimit-Remaining`	No	used to identify the quantity remaining max request limit. This header is returned only if the quantity is less than max limit.
`X-RateLimit-Reset`	No	This header is used to identify when the limiter is reset and only is returned when the request limit hit. The value é represented in as ISO string. The header only is returned when the rate-limit was hit. When the policy is `REQUEST_PER_PERIOD` the header returns the value of property `periodWindowEnd` as ISO string
`Retry-After`	No	used to tells the client how long in seconds to wait before making another request. The header only is returned when the rate-limit was hit. When the policy is `REQUEST_PER_PERIOD` the header returns difference between timestamp now and `periodWindowEnd` in seconds.

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

JeffersonGibin/express-rate-limiter-core

Express Rate Limit Core

Install

Features

Cache

Note

TypeScript Support

Exemples

Docker

Importing

Request per Seconds or Minutes

Request per Period

Block Request Rule

How use ?

Constructor Parameters

Policy to Request per Seconds

Policy to Request per Minutes

Policy to Request per Period

Response

Headers

Issues and Contributing

License