Detailed description of the two key parameters rate and burst of Nginx's request rate limiting module and related code statements.

01-Reference article

This article is written with reference to the following two articles (it is recommended to read the following two articles before reading):
NGINX rate limiting principle and source code analysis
A preliminary study on Nginx speed limit module

02-Detailed explanation of parameters rate and burst

The unit of rate is r/s, and the literal translation of the unit is times/second, which is the maximum number of requests allowed per second.
Common misunderstandings:For example, if the value of rate is 5, does this mean that the maximum number of requests allowed per second is 5?
The answer is: not exactly. The maximum number of requests allowed per second is 5.

If you do not set the burst parameter and you initiate 5 consecutive requests within 200ms, only the first request will be executed, and the next 4 requests will be discarded. For specific examples, please refer to the article:A preliminary study on Nginx speed limit module. This article has specific examples.
Why is this? Because Nginx executes requests at the millisecond level, because 1 second = 1000 milliseconds, so the true meaning of 5 r/s is 1 time/200 milliseconds, that is, every 200 A request is executed every millisecond.
So in fact, 5 r/s defines a time window. The width of a time window can execute one request. In this example, the width of the time window is 200 milliseconds, that is, it is executed every 200 milliseconds. One request.

But the actual situation is that more than one request often occurs within 200 milliseconds. What should we do at this time? The burst parameter comes into play. Burst represents the maximum number of requests that Nginx can receive at one time. If the number of requests is within the range of burst, then these requests can be arranged into the queue by Nginx even if they exceed 1 or exceed the rate value.
Burst has two working modes, one is the working mode with delay (the default working mode of burst), and the other is the working mode without delay, which is the nodelay working mode.
Take rate = 5 r/s = 1 time/200 milliseconds, burst = 10 as an example to illustrate this problem.
When in delay working mode:
This is the default working mode of burst. Assume that the client initiates 11 requests in a short period of time (for example, within 200 milliseconds). At this time, Nginx will add the first 10 requests to the burst queue slot, discard the last one, and then execute one every 200 milliseconds. request, and at the same time, a queue slot is released every 200 milliseconds during processing. This released queue slot can be filled with a subsequent request, and then the subsequent requests are executed in sequence.
When in nodelay working mode:
Also assume that the client initiates 11 requests in a short period of time (for example, within 200 milliseconds). At this time, Nginx also The first 10 requests will be added to the queue slot, the last one will be discarded, and then all 10 requests will be executed within a time window unit (that is, within 200 milliseconds). Please note that although all 10 requests have been executed, the occupied queue slot has not been released. Instead, the occupied queue slot is released every 200 milliseconds, that is, the unit of a time window. This released queue The slot can be newly filled with a subsequent request, and then the subsequent requests are executed in sequence.

03-Practical examples and detailed code explanations

Corresponding to the detailed explanation of the above two parameters, the corresponding code of the example is as follows:

# 限速配置，限速配置需放在server块之外
limit_req_zone $binary_remote_addr zone=ip_limit_01s:10m rate=5r/s;
......
server {
    
    
		location / {
    
    
			# 限速配置
			limit_req zone=ip_limit_01s burst=10 nodelay;
		}
}

Detailed code explanation:

limit_req_zone $binary_remote_addr zone=ip_limit_01s:10m rate=5r/s;

In the above Nginx configuration statement, limit_req_zone is a directive used to configure request rate limit based on the client IP address.

Specifically, this directive is used todefine a request zone that will be used to store information about the client End request rate information. This information includes the client's IP address, request count, etc. This way, Nginx is able to track each client's request frequency and limit it based on a predefined rate.

Let's break down this specific example:

• $binary_remote_addr: This is an Nginx variable that represents the client’s IP address in binary format. This is used as a basis for restrictions so that restrictions can be made for different clients. In addition to $binary_remote_addr, Nginx also provides some other variables that can be used as the basis for request rate limiting. Here are some of the common variables:

1. $binary_remote_addr: The client’s IP address in binary format.

2. $remote_addr: The IP address of the client.

3. $http_user_agent: The client's User-Agent header, indicating the client's browser, operating system and other information.

4. $server_name: The server name of the current request.

5. $host: Host header of the current request, used to identify the target host of the request.

6. $request_uri: Complete request URI, including parameters.

7. $scheme: Requested protocol (http or https).

8. $http_referer: Represents the URI that guides the user agent to the current page.

   You can choose appropriate variables as the basis for restrictions based on specific needs. For example, if you want to rate limit requests based on different User-Agents, you can use $http_user_agent. When configuring the limit_req_zone directive, simply replace the appropriate variable with the $binary_remote_addr position.
   Question: What is the difference between $binary_remote_addr and $remote_addr?
   $binary_remote_addr and $remote_addr are both used to represent the client’s IP address, but there are some differences between them:

   1. Number dative expression:
      • $binary_remote_addr: Represents the binary format of the client IP address.
      • $remote_addr: A text format representing the client IP address.
   2. 用途:
      • $binary_remote_addr: Mainly used as the basis for restricting areas in limit_req_zone. Because it is a binary format, it is more efficient to store in memory and is suitable for large-scale request limits.
      • $remote_addr: Typically used to record the client's IP address in logs, or when a textual representation of the IP address is needed elsewhere.

• zone=ip_limit_01s:10m: This section defines the name of the request limit zone (ip_limit_01s) and its maximum size (10m, or 10 megabytes). The name will be used later when configuring the limit number of requests for a specific server block. The size of the limit area is used to store the status information of the request.

• rate=5r/s: I have made this very clear and specific earlier in this article, so I won’t explain it too much here.

limit_req zone=ip_limit_01s burst=10 nodelay;

There is nothing much to say about this code. This code calls the request limit area "ip_limit_01s" defined in the previous code, then sets the burst queue slot value to 10, and runs in nodelay mode. I have already said it clearly before, so there is nothing more to say.

04-Can the rate value be a decimal?

Question: Can the rate value in Nginx’s request rate limiting module be set to a decimal? For example, can rate be 0.5?
Answer: No. Should be set to an integer.

05-What will Nginx prompt if the request exceeds the allowed rate?

Ask: What happens if the request allowed rate is exceeded?
Answer, a 503 error will be prompted, as shown below: