Nodal Rate Limit Middleware

This is a middleware package for Nodal that performs basic rate-limiting on public endpoints. This is meant to be a functional example how how to write middleware for nodal and package as an npm module. Thus this is intentionally a very rudimentary and simplistic piece of middleware and my wish it others will build more advanced rate limiters.

DO NOT USE THIS YET

This module, while totally functional, has hardcoded options. Until PR #149 on the main Nodal repo is merged. The module currently allows 100 connections per minute per ip. Localhost (::1 in Nodal) is also intentionally not excluded to allow for testing.

Install

$ npm install --save nodal-middleware-ratelimit

Useage

In your app/app.js you first need to require the module

const RateLimitMiddleware = require('nodal-middleware-ratelimit');

Then simply use it

this.middleware.use(RateLimitMiddleware)

Whola your aapp is now being rate limited!.

Configuring

If you want to override the default rate limiting options, you can pass configuration options when you use() your middleware. For example if you wnat to limit requests to 50 per every 5 minutes and allow local requests to excluded from limiting, you would do the following.

this.middleware.use(RateLimitMiddleware, { max: 50, timeWindow: 300 * 100, exclude: ['::1'] })

Optiona	Description	Default
timeWindow	Time window for rate limiting in milliseconds	60000 (1 miniute)
max	Maximum number of requests in the rate limiting window	100 requests
message	Message to send back when rate limit exceeded	Too many requests, please try again later
includeHeaders	Set X-RateLimit-Limit, X-Rate-Limit-Reset & X-RateLimit-Remaining headers	true
exclude	Array of IPs that are excluded from rate limiting	[]
enforce	Array of route prefix's to limit the application of limiting to routes	[]

Apply Rate Limiting to specific routes

Nodal currently doesn't allow middleware/renderware to be scoped to a route, thus rate limiting is applied over all your routes by default. This mens that if your building a Nodal application with both API and UI routes, it will limit your UI endpoints as well. To control the behavior you can send an optional enforce option that is an array of route prefixes to limit the rate limiting to. For example to limit it to only routes starting with /v1

this.middleware.use(RateLimitMiddleware, { enforce: [ '/v1/' ] })

Headers

This middleware can optionally (and by default doest) set the following X- headers

Name	Description
X-RateLimit-Limit	Request limit per minute
X-RateLimit-Remaining	The number of requests left for the time window
X-Rate-Limit-Reset	Timestamp of when the limit will be reset

Error Messages

When the limit is reach, the middleware will return a HTTP Too Many Request (429) response and the body will be a JSON document. The error key in the document will look like the following

{
  "error":{
    "message": "Too many requests, please try again later.",
    "details": {
      "host": "::1",
      "maximum": 20,
      "requests": 22,
      "resets":" 2016-01-27T03:58:48.072Z"
    }
  }
}