@perseidesjs/medusa-plugin-rate-limit

Website | Medusa

A simple rate-limitting utility for Medusa.

Purpose

This utility middleware was mainly built to protect your MedusaJS application from abuse. It allows you to easily manage request limits without stepping outside the familiar Medusa environment.

Why Rate Limiting Matters

1. Shield Against Attacks: Prevent Denial of Service (DoS) attempts by capping the number of requests from a single source.
2. Boost Security: Thwart brute force attacks and other automated threats by controlling request frequency.
3. Easy Setup: Seamlessly integrate rate limiting into your existing Medusa configuration files.

Installation

npm install @perseidesjs/medusa-plugin-rate-limit

Usage

This middleware uses the CacheModule available (InMemory, Redis, etc.) under the hood and exposes a simple middleware to limit the number of requests per IP address.

How to use

If you want to start restricting certain routes, you can import the defaultRateLimit middleware from the plugin and then use it as follows:

// src/api/middlewares.ts
import { defineMiddlewares } from "@medusajs/medusa"
import { defaultRateLimit } from '@perseidesjs/medusa-plugin-rate-limit'

export default defineMiddlewares({
  routes: [
    {
      matcher: "/store/custom*",
      middlewares: [defaultRateLimit()],
    },
  ],
})

You can also pass some custom options to have a complete control over the rate limiting mechanism as follows:

// src/api/middlewares.ts
import { defineMiddlewares } from "@medusajs/medusa"
import { defaultRateLimit } from '@perseidesjs/medusa-plugin-rate-limit'

export default defineMiddlewares({
  routes: [
    {
      matcher: "/store/custom*",
      middlewares: [defaultRateLimit({
				limit: 10,
				window: 60,
			})],
    },
  ],
})

In this example, the rate limiting mechanism will allow 10 requests per minute per IP address.

Granular control over rate limiting

The choice of having options directly inside the middleware instead of globally inside the global options (as on version 1.x of the project) was made to provide greater flexibility. This approach allows users to be more or less restrictive on certain specific routes. By specifying options directly within the middleware, you can tailor the rate limiting mechanism to suit the needs of individual routes, rather than applying a one-size-fits-all configuration globally. This ensures that you can have fine-grained control over the rate limiting behavior, making it possible to adjust the limits based on the specific requirements of each route.

Additionally, you can use a exported function called `configureDefaults` to update the default global values, such as the `limit`, `window` and `includeHeaders`. This allows you to set your own default values that will be applied across many routes, while still having the flexibility to specify more granular settings for specific routes. By configuring the middleware options, you can establish a baseline rate limiting policy that suits the majority of your application, and then override these defaults as needed for particular routes.

Default configuration

Option	Type	Default	Description
limit	Number	5	The number of requests allowed in the given time window
window	Number	60	The time window in seconds
includeHeaders	Boolean	false	Whether to include the headers (X-RateLimit-Limit, X-RateLimit-Remaining) in the response

Overriding default options

// 

import {
  defineMiddlewares
} from "@medusajs/framework/http"
import { defaultRateLimit, configureDefaults } from '@perseidesjs/medusa-plugin-rate-limit'

// This will override the global default options for all routes
// Here, we set the limit to 1 request per 30 seconds
configureDefaults({
  limit: 1,
  window: 30,
})

export default defineMiddlewares({
  routes: [
    {
      matcher: "/store/custom*",
      method: "POST",
      middlewares: [
        // Uses the global default options
        defaultRateLimit()
      ],
    },
        {
      matcher: "/store/custom*",
      method: "POST",
      middlewares: [
        // If the options are provided, they will ignore the global default options and use the provided ones
        defaultRateLimit({
          limit: 10,
          window: 60,
        })
      ],
    },
  ],
})

License

This project is licensed under the MIT License - see the LICENSE file for details