rate-limiting-with-penalty.mdx

title	description	meta_tags	namespace	permalink
How to install Upstash Rate Limiting integration through Azion Marketplace	This integration allows you to control incoming traffic right at the edge and protect your applications.	marketplace, edge computing, rate limiting	docs_guides_rate_limiting_integration	/documentation/products/guides/upstash-rate-limiting-integration/

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:

• Create an Upstash account.
• Create a Global Database for the best available edge latency in the Upstash Console.

---

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, at the bottom-right corner of the page.

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 + Rule Set 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, select the Functions Instances tab and follow these steps:

1. Click the Add Function button.
2. Give an easy-to-remember name to your instance.
3. 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.

4. 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:

Variable	Description
upstash_redis_rest_url	The URL of your Upstash database that will store the rate limit and penalty data
upstash_redis_rest_token	Your Upstash API access token
rate_limit_prefix	It 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_metadata	It defines which metadata variables will be used to generate the rate limit key in Azion's platform
rate_limit_key_header	It defines which headers will be used to generate the rate limit key in Azion's platform
rate_limit_key_hostname	If true, the URL will be used to generate the Rate Limit "key"
rate_limit_repenalize	If true, the penalty time is recalculated every time a penalized user makes a request
rate_limits	It defines the rate limit windows as an object. You must add at least one object
algorithm	It defines the rate limit algorithm to be applied. Possible values: fixed_window, sliding_window, token_bucket. Read more
requests	Maximum number of requests until reaching the rate limit
interval	Rate 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 end	These variables define the time window. It uses the 24-hour format and the UTC time zone. Read more
penalty_in_seconds	Penalty time (blocking that returns 403 status code) that users will be subjected to after violating the rate limit Read more

:::note 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. :::

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 Edge Firewall page:

1. Select the Rules Engine tab.
2. Click the New Rule 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.