Limit Count Advanced Configuration

Parameters

See plugin common configurations for configuration options available to all plugins.

This plugin supports referencing sensitive parameter values from environment variables using the env:// prefix, or from a secret manager, such as HashiCorp Vault’s KV secrets engine, using the secret:// prefix. For more information, see environment variables in plugin and secrets.

• count — integer | string · required

  Valid values: greater than 0

  The maximum number of requests allowed within a given time interval.

  In API7 Enterprise (from 3.8.17), this parameter also supports the string data type and allows the use of built-in variables prefixed with a dollar sign ($).

• time_window — integer | string · required

  Valid values: greater than 0

  The time interval corresponding to the rate limiting count in seconds.

  In API7 Enterprise (from 3.8.17), this parameter also supports the string data type and allows the use of built-in variables prefixed with a dollar sign ($).

• window_type — string · optional · default: fixed

  Valid values: fixed or sliding

  Rate limiting algorithm, fixed window or sliding window.

• key_type — string · optional · default: var

  Valid values: var, var_combination, or constant

  The type of key.

  If the key_type is var, the key is interpreted as a variable.

  If the key_type is var_combination, the key is interpreted as a combination of variables.

  If the key_type is constant, the key is interpreted as a constant.

• key — string · optional · default: remote_addr

  The key to count requests by.

  If the key_type is var, the key is interpreted as a variable. The variable does not need to be prefixed by a dollar sign ($). See built-in variables for available variables.

  If the key_type is var_combination, the key is interpreted as a combination of variables. All variables should be prefixed by dollar signs ($). For example, to configure the key to use a combination of two request headers custom-a and custom-b, the key should be configured as $http_custom_a $http_custom_b.

  If the key_type is constant, the key is interpreted as a constant value.

• rejected_code — integer · optional · default: 503

  Valid values: between 200 and 599 inclusive

  The HTTP status code returned when a request is rejected for exceeding the threshold.

• rejected_msg — string · optional

  Valid values: any non-empty string

  The response body returned when a request is rejected for exceeding the threshold.

• policy — string · optional · default: local

  Valid values: local, redis, redis-cluster, or redis-sentinel

  The policy for rate limiting counter.

  Set to local to store the counter in memory locally.

  Set to redis to store the counter on a Redis instance.

  Set to redis-cluster to store the counter in a Redis cluster.

  Set to redis-sentinel to store the counter on the Redis primary node managed by Redis Sentinel, which ensures high availability by automatically promoting a replica to primary in case of failure. Redis Sentinel provides high availability for Redis when not using Redis Cluster.

• redis_sentinels — array[object] · optional

  An array of Redis Sentinel nodes (host and port). Required when policy is redis-sentinel.

• redis_master_name — string · optional

  The name of the Redis master group that Sentinels are monitoring. Required when policy is redis-sentinel.

• redis_role — string · optional · default: master

  Valid values: master or slave

  The Redis node role to connect to. Configurable when policy is redis-sentinel. Set to master to connect to the current Redis master, and set to slave to connect to a Redis replica.

• redis_connect_timeout — integer · optional · default: 1000

  Valid values: greater than or equal to 1

  Timeout in milliseconds for establishing a connection to a Redis node. Configurable when policy is redis-sentinel.

• redis_read_timeout — integer · optional · default: 1000

  Valid values: greater than or equal to 1

  Timeout in milliseconds for reading data from a Redis node. Configurable when policy is redis-sentinel.

• sentinel_username — string · optional

  Username used to authenticate with the Redis Sentinel instance. Configurable when policy is redis-sentinel.

• sentinel_password — string · optional

  Password used to authenticate with the Redis Sentinel instance. Configurable when policy is redis-sentinel.

• allow_degradation — boolean · optional · default: false

  If true, allow the gateway to continue handling requests without the plugin when the plugin or its dependencies become unavailable.

• rules — array[object] · optional

  An array of rate-limiting rules that are applied sequentially.

  Available in API7 Enterprise from 3.8.17.

  • count — integer | string · required

    Valid values: greater than 0

    The maximum number of requests allowed within a given time interval.

    This parameter also supports the string data type and allows the use of built-in variables prefixed with a dollar sign ($).

  • time_window — integer | string · required

    Valid values: greater than 0

    The time interval corresponding to the rate limiting count in seconds.

    This parameter also supports the string data type and allows the use of built-in variables prefixed with a dollar sign ($).

  • key — string · required

    The key to count requests by. If the configured key does not exist, the rule will not be executed.

    The key is interpreted as a combination of variables, for example, $http_custom_a $http_custom_b.

  • header_prefix — string · optional

    Prefix for all rate limiting response headers. Available in API7 Enterprise from version 3.8.19.

    When configured, the prefix is inserted after X- in the header name. For example, with header_prefix set to test, the headers become X-Test-RateLimit-Limit, X-Test-RateLimit-Remaining, and X-Test-RateLimit-Reset.

    When not configured, the index of the rule in the rules array is used as the prefix. For example, headers for the first rule will be X-1-RateLimit-Limit, X-1-RateLimit-Remaining, and X-1-RateLimit-Reset.

• show_limit_quota_header — boolean · optional · default: true

  If true, includes the rate limiting response headers. Specifically, if rules is not set, the headers are:

  • X-RateLimit-Limit shows the total quota.
  • X-RateLimit-Remaining shows the remaining quota.
  • X-RateLimit-Reset shows the number of seconds until the counter resets.
  
  

  When rules is set, a prefix (followed by a hyphen) is inserted after X-. See rules.header_prefix for details.

• group — string · optional

  Valid values: non-empty

  The group ID for the plugin, such that routes of the same group can share the same rate limiting counter.

• redis_host — string · optional

  The address of the Redis node. Required when policy is redis.

• redis_port — integer · optional · default: 6379

  Valid values: greater than or equal to 1

  The port of the Redis node when policy is redis.

• redis_username — string · optional

  The username for Redis if Redis ACL is used. If you use the legacy authentication method requirepass, configure only the redis_password. Used when policy is redis.

• redis_password — string · optional

  The password of the Redis node when policy is redis, or redis-cluster.

• redis_database — integer · optional · default: 0

  Valid values: greater than or equal to 0

  The database number in Redis when policy is redis or redis-sentinel.

• redis_ssl — boolean · optional · default: false

  If true, use SSL to connect to Redis when policy is redis.

• redis_ssl_verify — boolean · optional · default: false

  If true, verify the server SSL certificate when policy is redis.

• redis_timeout — integer · optional · default: 1000

  Valid values: greater than or equal to 1

  The Redis timeout value in milliseconds when policy is redis or redis-cluster.

• redis_keepalive_timeout — integer · optional

  Valid values: greater than or equal to 1000 for redis and redis-cluster; greater than or equal to 1 for redis-sentinel

  Time in milliseconds that an idle Redis connection is kept alive in the connection pool before being closed. When policy is redis or redis-cluster, the default is 10000. When policy is redis-sentinel, the default is 60000.

  For redis and redis-cluster, this parameter was introduced in API7 Enterprise 3.9.16 and 3.10.3.

• redis_keepalive_pool — integer · optional · default: 100

  Valid values: greater than or equal to 1

  Maximum number of idle Redis connections in the keepalive pool. Used when policy is redis or redis-cluster.

  Introduced in API7 Enterprise 3.9.16 and 3.10.3.

• redis_cluster_nodes — array[string] · optional

  The list of Redis cluster nodes with at least two addresses. Required when policy is redis-cluster.

• redis_cluster_name — string · optional

  The name of the Redis cluster. Required when policy is redis-cluster.

• redis_cluster_ssl — boolean · optional · default: false

  If true, use SSL to connect to Redis cluster when policy is redis-cluster.

• redis_cluster_ssl_verify — boolean · optional · default: false

  If true, verify the server SSL certificate when policy is redis-cluster.

• sync_interval — number · optional · default: -1

  Valid values: greater than or equal to 0.1, or the default -1

  The frequency of synchronizing counter data to Redis. Available only in Enterprise.

  The sync_interval value should be smaller than time_window. A value of 1 results in synchronizing counter data every second. A value of -1 yields no change in synchronizing behaviour, i.e. counter data will be synchronized for each request.