How to Install Upstash Rate Limiting

This integration allows you to control incoming traffic right at the edge and protect your applications.

View as Markdown

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 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 a firewall.

Configuring the integration

Setting up a firewall

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

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

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

Setting up the Firewall function

While still on the Firewall page:

  1. Select the Functions Instances tab.
  2. Click the + Function Instance 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 Arguments tab.
  5. In the Arguments tab, you’ll pass your Upstash credentials and your variables:
{
"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

The key to a rate limit is made up of the combination of all these variables. In this code sample, the final key would be: my_rate_limit + User IP + X-a-custom-reader Value + Hostname used in the request.

Example: my_rate_limit_127.0.0.1_Value_azion.com.

  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.
"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 Firewall page:

  1. Select the Rules Engine tab.
  2. Click the + Rule Engine button.
  3. Give a name to the rule.
  4. Select a criteria to run and catch the domains that you want to run the integration on.
  • Example: if Host matches yourdomain.com.
  1. Below, select a behavior to the criteria. In this case, it’ll be Run Function.
    • Select the adequate function according to the name you gave it during the instantiation step.
  2. Click the Save button.

On the Console, you must now configure your domain so your firewall protects it.

  1. On the Products menu, select Workloads.
  2. Click on the domain you want to protect with your Upstash Rate Limiting function.
  3. In the Settings section, click on the Firewall selector and choose the firewall you created.
  4. 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.