Configure Upstash Ratelimit Strapi Plugin

After setting up the plugin, it’s possible to customize the ratelimiter algorithm and rates. You can also define different rate limits and rate limit algorithms for different routes.

General Configurations

enabled · boolean · default: "true"

Enable or disable the plugin.

Database Configurations

token · string · required

The token to authenticate with the Upstash Redis REST API. You can find this credential on Upstash Console with the name UPSTASH_REDIS_REST_TOKEN

url · string · required

The URL for the Upstash Redis REST API. You can find this credential on Upstash Console with the name UPSTASH_REDIS_REST_URL

prefix · string · default: "@strapi"

The prefix for the rate limit keys. The plugin uses this prefix to store the rate limit data in Redis.
For example, if the prefix is @strapi, the key will be @strapi:<method>:<route>:<identifier>.

analytics · boolean · default: "false"

Enable analytics for the rate limit. When enabled, the plugin extra insights related to your ratelimits. You can use this data to analyze the rate limit usage on Upstash Console.

Strategy

The plugin uses a strategy array to define the rate limits per route. Each strategy object has the following properties:

methods · ('GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH' |'ALL')[] · required

An array of HTTP methods to apply the rate limit.
For example, ["GET", "POST"]

path · string · required

The path to apply the rate limit. You can use wildcards to match multiple routes. For example, * matches all routes.
Some examples:

• path: "/api/restaurants/:id"
  
• path: "/api/restaurants"
  

identifierSource · string · required

The source to identifiy the user. Requests with the same identifier will be rate limited under the same limit.
Available sources are:

• ip: The IP address of the user.
  
• header: The value of a header key. You should pass the source in the header.<HEADER_KEY> format.
  For example, header.Authorization will use the value of the Authorization

debug · string

Enable debug mode for the route. When enabled, the plugin logs the remaining limits and the block status for each request.

limiter · object · required

The limiter configuration for the route. The limiter object has the following properties:

algorithm · 'fixed-window' | 'sliding-window' | 'token-bucket' · required

The rate limit algorithm to use. For more information related to algorithms, see docs here.

• fixed-window: The fixed-window algorithm divides time into fixed intervals. Each interval has a set limit of allowed requests. When a new interval starts, the count resets.
  
• sliding-window: The sliding-window algorithm uses a rolling time frame. It considers requests from the past X time units, continuously moving forward. This provides a smoother distribution of requests over time.
  
• token-bucket: The token-bucket algorithm uses a bucket that fills with tokens at a steady rate. Each request consumes a token. If the bucket is empty, requests are denied. This allows for bursts of traffic while maintaining a long-term rate limit.
  

tokens · number · required

The number of tokens allowed in the time window.

window · string · required

The time window for the rate limit. Available units are "ms" | "s" | "m" | "h" | "d"
For example, 20s means 20 seconds.

refillRate · number

The rate at which the bucket refills. This property is only used for the token-bucket algorithm.

Examples

Apply rate limit for all routes

{
   "strapi-plugin-upstash-ratelimit":{
      "enabled":true,
      "resolve":"./src/plugins/strapi-plugin-upstash-ratelimit",
      "config":{
         "enabled":true,
         "token":"process.env.UPSTASH_REDIS_REST_TOKEN",
         "url":"process.env.UPSTASH_REDIS_REST_URL",
         "strategy":[
            {
               "methods":[
                  "GET",
                  "POST"
               ],
               "path":"*",
               "identifierSource":"header.Authorization",
               "limiter":{
                  "algorithm":"fixed-window",
                  "tokens":10,
                  "window":"20s"
               }
            }
         ],
         "prefix":"@strapi"
      }
   }
}

{
  "strapi-plugin-upstash-ratelimit": {
    "enabled": true,
    "resolve": "./src/plugins/strapi-plugin-upstash-ratelimit",
    "config": {
      "enabled": true,
      "token": "process.env.UPSTASH_REDIS_REST_TOKEN",
      "url": "process.env.UPSTASH_REDIS_REST_URL",
      "strategy": [
        {
          "methods": ["GET", "POST"],
          "path": "*",
          "identifierSource": "ip",
          "limiter": {
            "algorithm": "fixed-window",
            "tokens": 10,
            "window": "20s"
          }
        }
      ],
      "prefix": "@strapi"
    }
  }
}

{
  "strapi-plugin-upstash-ratelimit": {
    "enabled": true,
    "resolve": "./src/plugins/strapi-plugin-upstash-ratelimit",
    "config": {
      "enabled": true,
      "token": "process.env.UPSTASH_REDIS_REST_TOKEN",
      "url": "process.env.UPSTASH_REDIS_REST_URL",
      "strategy": [
        {
          "methods": ["GET", "POST"],
          "path": "/api/restaurants/:id",
          "identifierSource": "header.x-author",
          "limiter": {
            "algorithm": "fixed-window",
            "tokens": 10,
            "window": "20s"
          }
        },
        {
          "methods": ["GET"],
          "path": "/api/restaurants",
          "identifierSource": "header.x-author",
          "limiter": {
            "algorithm": "tokenBucket",
            "tokens": 10,
            "window": "20s",
            "refillRate": 1
          }
        }
      ],
      "prefix": "@strapi"
    }
  }
}