How to install Upstash Rate Limiting integration through Azion Marketplace

Upstash Rate Limiting allows you to control incoming traffic right at the edge of the network, avoiding bottlenecks, managing traffic spikes, and protecting your applications from potential threats such as DDoS, fuzzing, or brute force attacks.

With this integration, based on an edge function, you can define:

  • Limiting requests and window limit, including specific rate limit windows for different periods of the day.
  • A penalty configuration that analyzes the validity of each request.
    • If the request isn’t valid, it blocks the request and returns the user a 403 Forbidden status code.
    • If the request is valid, it counts the request and, in case it reaches the defined rate limit, it interrupts the request and returns a 429 Too Many Requests status code.

Upstash Rate Limiting is integrated with the upstash/ratelimit library and provides a global accounting of the rate limit, summing up all the requests received across the entire network, instead of counting separately for each edge location.

Requirements

To start using this integration, you need to:

Getting the integration

To install this integration:

  1. Access Azion Console > Marketplace.
  2. On the Marketplace homepage, select the integration’s card.
  3. On the integration page, click the Install button.

You’ll see a message indicating that your integration was successfully installed.

Then, you’ll need to complete the steps explained below to instantiate the function and configure an edge firewall.

Configuring the integration

Setting up an edge firewall

To instantiate the Upstash Rate Limiting integration, follow the steps:

  1. Open the Products menu and select Edge Firewall in the Secure section.
  2. Click the + Edge Firewall button.
  3. Give an easy-to-remember name to your edge firewall.
  4. Select the domains you want to protect with the function.
  5. Enable the Edge Functions switch in the Modules section.
    • This action gives access to edge functions on your edge firewall.
  6. Click the Save button.

Done. Now you’ve instantiated the edge firewall for your function.

Setting up the Edge Firewall function

While still on the Edge Firewall page:

  1. Select the Functions tab.
  2. Click the Add Function button.
  3. Give an easy-to-remember name to your instance.
  4. On the dropdown menu, select the Upstash Rate Limiting function.

This action will load the function, showing a form with the function’s source-code and, just above it, two tabs: Code and Arguments. By clicking on the Code tab, you’ll be able to navigate through the source-code, but won’t be able to change it.

  1. In the Arguments tab, you’ll pass your Upstash credentials and your variables:
Terminal window
{
  "upstash_redis_rest_url": "https://your-database.upstash.io",
  "upstash_redis_rest_token": "Your upstash token",
 "rate_limit_prefix": "my_rate_limit",
  "rate_limit_key_metadata": [
  "remote_addr"
  ],
  "rate_limit_key_header": [
  "x-a-custom-header"
  ],
  "rate_limit_key_hostname": true,
  "rate_limit_repenalize": true,
  "rate_limits": [
  {
          "algorithm": "sliding_window",
          "requests": 2,
          "interval": "20 s",
          "start": "00:00",
          "end": "12:00",
          "penalty_in_seconds": 45
  },
  {
          "algorithm": "fixed_window",
          "requests": 3,
          "interval": "120 s",
          "start": "12:01",
          "end": "23:00",


  },
       {
        "algorithm": "token_bucket",
        "refil_rate": 5,
        "max_tokens": 5,
        "interval": "10 s",
           "start": "23:01",
            "penalty_in_seconds": 55
  }
  ]
}

Where:

VariableDescription
upstash_redis_rest_urlThe URL of your Upstash database that will store the rate limit and penalty data
upstash_redis_rest_tokenYour Upstash API access token
rate_limit_prefixIt defines a prefix to be used in all the rate limit keys. This variable is crucial to avoid overlaps between different instances of the function
rate_limit_key_metadataIt defines which metadata variables will be used to generate the rate limit key in Azion’s platform
rate_limit_key_headerIt defines which headers will be used to generate the rate limit key in Azion’s platform
rate_limit_key_hostnameIf true, the URL will be used to generate the Rate Limit “key”
rate_limit_repenalizeIf true, the penalty time is recalculated every time a penalized user makes a request
rate_limitsIt defines the rate limit windows as an object. You must add at least one object
algorithmIt defines the rate limit algorithm to be applied. Possible values: fixed_window, sliding_window, token_bucket. Read more
requestsMaximum number of requests until reaching the rate limit
intervalRate limit window time interval. This variable follows the Upstash standard: XXXX y, where the X are the numeral and y is the unit of measurement, which can be s for seconds or m for minutes. Example: 120 s
start and endThese variables define the time window. It uses the 24-hour format and the UTC time zone. Read more
penalty_in_secondsPenalty time (blocking that returns 403 status code) that users will be subjected to after violating the rate limit Read more
  1. Click the Save button.

Important

  • This integration allows you to define different rate limit windows for different periods of the day, according to your needs. Example: you can define a limit of 10 requests/minute from 00:00 to 12:00, and 15 requests/minute from 12:01 to 23:59.

  • This integration supports three possible values for algorithm:

    • fixed_window divides time into fixed durations/windows.
    • sliding_window builds on top of fixed window but uses a rolling window. Example: you want to define a rate limit of 10 requests per 1 minute, then, you divide the time into 1 minute slices, as in the fixed window algorithm.
    • token_bucket defines the maximum number of tokens to fill a bucket and the interval which the bucket will be cleaned. Every request removes one token and if there’s no token to take, the request is rejected.

  • The token_bucket includes different values, where:

    • max_tokens defines the number of tokens (or keys) that this rate limit will allow.
    • refil_rate defines the number of buckets that will be “cleaned” at each time interval.
Terminal window
"algorithm": "token_bucket",
        "refil_rate": 5,
        "max_tokens": 5,
        "interval": "10 s",
           "start": "23:01",
            "penalty_in_seconds": 55

In this example, every 10 seconds, 5 buckets are cleaned, out of a maximum of 5 "busy" buckets.

  • If start isn’t defined, the default value will be 00:00. If end isn’t defined, the default value of 23:59” will be assumed. In case of overlaps between rate limits, the rate limit that is first in the JSON Args will be considered.

  • When the penalty_in_seconds variable isn’t filled in, the rate limit won’t apply a penalty, behaving like a simple rate limit.

Setting up the Rules Engine

To finish, you have to set up a rule in Rules Engine to configure the criteria and the behavior to run the function.

Still in the Edge Firewall page:

  1. Select the Rules Engine tab.
  2. Click the + Rule Engine button.
  3. Give an easy-to-remember name to the rule.
  4. Select a criteria to run and catch the domains that you want to run the integration on. Example: if Hostname is equal xxxxxxxxxxxx.map.azionedge.net.
  5. Below, select the Run Function behavior to the criteria.
  6. Select the Upstash Rate Limiting function according to the name you gave it before.
  7. Click the Save button.

Done. Now Upstash Rate Limiting is running and protecting your domains.

Discover how to enhance your web application’s performance with this tutorial on Rate Limit with Penalty on Azion + Upstash DB. Watch now on Azion’s YouTube channel.

Contributors