GraphQL Limit Count Configuration

Parameters

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

• count — integer | string · optional

  Valid values: greater than 0

  The maximum accumulated GraphQL query cost allowed within a given time interval. Query cost is depth under the default strategy. Required when rules is not configured. The value can use built-in variables when configured as a string.

• time_window — integer | string · optional

  Valid values: greater than 0

  The time interval corresponding to the rate limiting count in seconds. Required when rules is not configured. The value can use built-in variables when configured as a string.

• rules — array[object] · optional

  An array of rate-limiting rules that are applied sequentially. Configure either rules or the top-level count and time_window, but not both.

  • count — integer | string · required

    Valid values: greater than 0

    The maximum accumulated GraphQL query cost allowed within the rule's time_window. Query cost is depth under the default strategy. The value can use built-in variables when configured as a string.

  • time_window — integer | string · required

    Valid values: greater than 0

    The time interval corresponding to the rule's count in seconds. The value can use built-in variables when configured as a string.

  • key — string · required

    The key to count requests by. Supports combinations of built-in variables, with each variable prefixed by a dollar sign ($). If the key cannot be resolved, the rule is not applied.

  • header_prefix — string · optional

    Prefix inserted into the rate limiting response headers for this rule. For example, foo produces X-foo-RateLimit-Limit, X-foo-RateLimit-Remaining, and X-foo-RateLimit-Reset.

• cost_strategy — string · optional · default: depth

  Valid values: depth, complexity, or node_quantifier

  How the raw cost of a GraphQL document is computed. depth counts the selection nesting depth, which is what this plugin has always done. complexity scores the nodes the query resolves. node_quantifier scores only nodes whose matching cost decoration resolves an argument listed in mul_arguments. If no node has both a matching decoration and a usable quantifier, the document's raw score is 0. For complexity and node_quantifier, the plugin adds 0.01, applies score_factor, and rounds up before charging the quota. The default factor produces a charged cost of 1 from a zero raw score; a factor greater than 100 increases it. Introduced in API7 Enterprise 3.10.6.

• max_cost — number · optional · default: 0

  Valid values: greater than or equal to 0

  Reject a document whose charged cost exceeds this value with 403 Forbidden before it reaches the upstream. The request consumes quota before this check. 0 disables the check and lets the quota alone decide. Introduced in API7 Enterprise 3.10.6.

• score_factor — number · optional · default: 1

  Valid values: greater than 0

  Scaling applied before the cost is rounded up, charged against the quota, and compared with max_cost. Introduced in API7 Enterprise 3.10.6.

• resolve_variables — boolean · optional · default: true

  If true, resolve supplied GraphQL variables, variable defaults declared by the operation, and argument defaults from the upstream schema when computing cost. The default ensures variable-based quantifiers contribute their resolved value. Introduced in API7 Enterprise 3.10.6.

• introspection_endpoint — string · optional

  Valid values: starts with http:// or https://

  Endpoint used to introspect the upstream GraphQL schema, which the complexity and node_quantifier strategies need in order to match cost decorations. Derived from the upstream when unset. The result is cached per worker and Service. Introduced in API7 Enterprise 3.10.6.

• introspection_headers — object · optional

  Headers sent on the schema introspection request for an upstream whose introspection endpoint requires credentials. The headers come from the configuration rather than from the request because the introspected schema is cached per worker and Service. When Data Plane data encryption is enabled, this field is encrypted at rest. Introduced in API7 Enterprise 3.10.6.

• 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, or redis-cluster

  The policy for rate limiting counter. If it is local, the counter is stored in memory locally. If it is redis, the counter is stored on a Redis instance. If it is redis-cluster, the counter is stored in a Redis cluster.

• 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.

• show_limit_quota_header — boolean · optional · default: true

  If true, includes the rate limiting response headers. Specifically:

  • 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.

• 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.

• 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 · default: 10000

  Valid values: greater than or equal to 1000

  Keepalive timeout in milliseconds for Redis when policy is redis or redis-cluster.

  This parameter is available in API7 Enterprise from version 3.9.16 on the 3.9 line and from version 3.10.3 on the 3.10 line, and in APISIX from version 3.17.0.

• redis_keepalive_pool — integer · optional · default: 100

  Valid values: greater than or equal to 1

  Keepalive pool size for Redis when policy is redis or redis-cluster.

  This parameter is available in API7 Enterprise from version 3.9.16 on the 3.9 line and from version 3.10.3 on the 3.10 line, and in APISIX from version 3.17.0.

• 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.

Plugin Metadata

• limit_header — string · optional · default: X-RateLimit-Limit

  Default response header name for the total rate limit quota. Available in API7 Enterprise from version 3.10.6.

• remaining_header — string · optional · default: X-RateLimit-Remaining

  Default response header name for the remaining rate limit quota. Available in API7 Enterprise from version 3.10.6.

• reset_header — string · optional · default: X-RateLimit-Reset

  Default response header name for the number of seconds until the rate limit counter resets. Available in API7 Enterprise from version 3.10.6.