ai-token-ratelimit - API Gateway - Alibaba Cloud Documentation Center

The ai-token-ratelimit plug-in implements token rate limiting based on specific key values. The key values can be obtained from URL parameters, HTTP request headers, client IP addresses, consumer names, or key names in cookies.

Important

For this plug-in to take effect, you must enable the AI observability plug-in to count the number of tokens.

Running attributes

Plug-in execution stage: default stage. Plug-in execution priority: 600.

Configuration description

Parameter	Type	Required	Default value	Description
rule_name	string	Yes	-	The name of the rate limiting rule. You can concatenate the rate limiting rule name, rate limiting type, rate limiting key name, and actual value of the rate limiting key into a Redis key.
rule_items	array of object	Yes	-	The items that are used to match a rate limiting rule based on the specified item sequence. If a rate limiting rule is matched based on an item, subsequent rules are skipped.
rejected_code	int	No	429	The HTTP status code that is returned when requests are throttled.
rejected_msg	string	No	Too many requests	The body of the response that is returned when requests are throttled.
redis	object	Yes	-	The Redis-related configurations.

The following table describes the configuration fields in rule_items.

Parameter	Type	Required	Default value	Description
limit_by_header	string	No. You can configure only one of the `limit_by_*` fields.	-	The name of the HTTP request header that is used to obtain the key value for rate limiting.
limit_by_param	string	No. You can configure only one of the `limit_by_*` fields.	-	The name of the URL parameter that is used to obtain the key value for rate limiting.
limit_by_consumer	string	No. You can configure only one of the `limit_by_*` fields.	-	The name of the consumer that is used for rate limiting. You do not need to specify the actual value.
limit_by_cookie	string	No. You can configure only one of the `limit_by_*` fields.	-	The name of the cookie key that is used to obtain the key value for rate limiting.
limit_by_per_header	string	No. You can configure only one of the `limit_by_*` fields.	-	The names of the HTTP request headers that are used to obtain the key value for rate limiting. The system matches specific HTTP request headers based on rules and separately calculates the rate based on each request header. When you configure `limit_keys`, regular expressions or asterisks (`*`) are supported.
limit_by_per_param	string	No. You can configure only one of the `limit_by_*` fields.	-	The names of the URL parameters that are used to obtain the key value for rate limiting. The system matches specific URL parameters based on rules and separately calculates the rate based on each URL parameter. When you configure `limit_keys`, regular expressions or asterisks (`*`) are supported.
limit_by_per_consumer	string	No. You can configure only one of the `limit_by_*` fields.	-	The names of the consumers that are used to obtain the key value for rate limiting. The system matches specific consumers based on rules and separately calculates the rate based on each consumer. You do not need to specify the actual value. When you configure `limit_keys`, regular expressions or asterisks (`*`) are supported.
limit_by_per_cookie	string	No. You can configure only one of the `limit_by_*` fields.	-	The names of the cookie keys that are used to obtain the key value for rate limiting. The system matches specific cookie keys based on rules and separately calculates the rate based on each cookie key. When you configure `limit_keys`, regular expressions or asterisks (`*`) are supported.
limit_by_per_ip	string	No. You can configure only one of the `limit_by_*` fields.	-	The IP addresses that are used to obtain the key value for rate limiting. You can configure `from-header-Header name`, such as `from-header-x-forwarded-for`, to obtain IP addresses from request headers. You can also configure `from-remote-addr` to directly obtain the peer socket IP address. The system matches specific IP addresses based on rules and separately calculates the rate based on each IP address.
limit_keys	array of object	Yes	-	The number of times rate limiting is triggered after a specific key value is matched.

The following table describes the configuration fields in limit_keys.

Parameter	Type	Required	Default value	Description
key	string	Yes	-	The matched key value. Regular expressions or asterisks () are supported for `limit_by_per_header`, `limit_by_per_param`, `limit_by_per_consumer`, and `limit_by_per_cookie`. If you want to use a regular expression, you must place regexp: before the regular expression. If you use an asterisk (), all the key values are matched. Example of a regular expression: `regexp: ^d.*`. In this example, all strings that start with d can be matched. IP addresses or CIDR blocks are supported for `limit_by_per_ip`.
token_per_second	int	No. You can configure only one of the `token_per_second`, `token_per_minute`, `token_per_hour`, and `token_per_day` fields.	-	The number of tokens that are allowed to be requested per second.
token_per_minute	int	No. You can configure only one of the `token_per_second`, `token_per_minute`, `token_per_hour`, and `token_per_day` fields.	-	The number of tokens that are allowed to be requested per minute.
token_per_hour	int	No. You can configure only one of the `token_per_second`, `token_per_minute`, `token_per_hour`, and `token_per_day` fields.	-	The number of tokens that are allowed to be requested per hour.
token_per_day	int	No. You can configure only one of the `token_per_second`, `token_per_minute`, `token_per_hour`, and `token_per_day` fields.	-	The number of tokens that are allowed to be requested per day.

The following table describes the configuration fields in redis.

Parameter	Type	Required	Default value	Description
service_name	string	Yes	-	The Redis service name, which is a fully qualified domain name (FQDN) with a specific service type, such as my-redis.dns or redis.my-ns.svc.cluster.local.
service_port	int	No	If the service type is static service, the default value is 80. For other services, the default value is 6379.	The service port number of the Tair (Redis OSS-compatible) instance.
username	string	No	-	The username that is used to log on to the Tair (Redis OSS-compatible) instance.
password	string	No	-	The password that is used to log on to the Tair (Redis OSS-compatible) instance.
timeout	int	No	1000	The connection timeout period of the Tair (Redis OSS-compatible) instance. Unit: milliseconds.

Configuration examples

Identify requests based on the apikey parameter and perform different rate limiting operations for the requests.

rule_name: default_rule
rule_items:
  - limit_by_param: apikey
    limit_keys:
      - key: 9a342114-ba8a-11ec-b1bf-00163e1250b5
        token_per_minute: 10
      - key: a6a6d7f2-ba8a-11ec-bec2-00163e1250b5
        token_per_hour: 100
  - limit_by_per_param: apikey
    limit_keys:
      # A regular expression is used to match all strings that start with a. For each request that matches the apikey parameter, 10 QDS is allowed.
      - key: "regexp:^a.*"
         token_per_second: 10
      # A regular expression is used to match all strings that start with b. For each request that matches the apikey parameter, 100 QD is allowed.
      - key: "regexp:^b.*"
        token_per_minute: 100
      # All requests are matched. For each request, 1,000 QDH is allowed.
      - key: "*"
        token_per_hour: 1000
redis:
  service_name: redis.static

Identify requests based on the request header x-ca-key and perform different rate limiting operations for the requests.

rule_name: default_rule
rule_items:
  - limit_by_header: x-ca-key
    limit_keys:
      - key: 102234
        token_per_minute: 10
      - key: 308239
        token_per_hour: 10
  - limit_by_per_header: x-ca-key
    limit_keys:
      # A regular expression is used to match all strings that start with a. For each request that matches the apikey parameter, 10 QDS is allowed.
      - key: "regexp:^a.*"
        token_per_second: 10
      # A regular expression is used to match all strings that start with b. For each request that matches the apikey parameter, 100 QD is allowed.
      - key: "regexp:^b.*"
        token_per_minute: 100
      # All requests are matched. For each request, 1,000 QDH is allowed.
      - key: "*"
        token_per_hour: 1000
redis:
  service_name: redis.static

Obtain the peer IP addresses based on the request header x-forwarded-for and perform different rate limiting operations for requests.

rule_name: default_rule
rule_items:
  - limit_by_per_ip: from-header-x-forwarded-for
    limit_keys:
      # An exact IP address is used.
      - key: 1.1.1.1
        token_per_day: 10
      # A CIDR block is used. For each IP address in the CIDR block, 100 QPD is allowed.
      - key: 1.1.1.0/24
        token_per_day: 100
      # By default, 1,000 QPD is allowed for each IP address.
      - key: 0.0.0.0/0
        token_per_day: 1000
redis:
  service_name: redis.static

Identify requests based on consumers and perform different rate limiting operations for the requests.

rule_name: default_rule
rule_items:
  - limit_by_consumer: ''
    limit_keys:
      - key: consumer1
        token_per_second: 10
      - key: consumer2
        token_per_hour: 100
  - limit_by_per_consumer: ''
    limit_keys:
      # A regular expression is used to match all strings that start with a. For each consumer that matches the apikey parameter, 10 QDS is allowed.
      - key: "regexp:^a.*"
        token_per_second: 10
      # A regular expression is used to match all strings that start with b. For each consumer that matches the apikey parameter, 100 QD is allowed.
      - key: "regexp:^b.*"
        token_per_minute: 100
      # All requests are matched. For each consumer, 1,000 QDH is allowed.
      - key: "*"
        token_per_hour: 1000
redis:
  service_name: redis.static

Identify requests based on key-value pairs in cookies and perform different rate limiting operations for the requests.

rule_name: default_rule
rule_items:
  - limit_by_cookie: key1
    limit_keys:
      - key: value1
        token_per_minute: 10
      - key: value2
        token_per_hour: 100
  - limit_by_per_cookie: key1
    limit_keys:
      # A regular expression is used to match all strings that start with a. For each request that matches a specific cookie value, 10 QDS is allowed.
      - key: "regexp:^a.*"
        token_per_second: 10
      # A regular expression is used to match all strings that start with b. For each request that matches a specific cookie value, 100 QD is allowed.
      - key: "regexp:^b.*"
        token_per_minute: 100
      # All requests are matched. For each request, 1,000 QDH is allowed.
      - key: "*"
        token_per_hour: 1000
rejected_code: 200
rejected_msg: '{"code":-1,"msg":"Too many requests"}'
redis:
  service_name: redis.static