feat(plugin): add graphql-limit-count plugin

[AlinsRan]

What does this PR do?

Add a new graphql-limit-count plugin that limits GraphQL request rates based on the depth of the query Abstract Syntax Tree (AST) within a given time window.

Why is this change needed?

Standard rate limiting counts every request equally, regardless of its computational cost. This is insufficient for GraphQL endpoints where the cost of execution scales with query complexity. A single deeply nested query can be far more expensive than dozens of simple ones:

# Shallow query: depth 1, cheap to execute
query { users }

# Deep query: depth 5, potentially expensive (N+1 queries, large result sets)
query { users { orders { items { product { category { name } } } } } }

Without depth-aware limiting, a client could exhaust server resources with a single request while staying well within a request-count limit.

The graphql-limit-count plugin solves this by using the GraphQL query AST depth as the cost for each request, powered by the existing limit-count infrastructure. This lets operators configure a single depth budget per time window and have it consumed proportionally by query complexity.

How does it work?

1. The plugin intercepts POST requests with application/json (containing a query field) or application/graphql content type.
2. It parses the request body to extract the GraphQL query string.
3. It calls graphql.parse() to build the AST and recursively counts the selections depth.
4. It calls limit_count.rate_limit(conf, ctx, plugin_name, depth), passing the depth as the cost.
5. If the accumulated cost within the time window exceeds count, the request is rejected with the configured rejected_code.

Example

Configure a route to allow a cumulative query depth of 10 per minute per client IP:

curl http://127.0.0.1:9180/apisix/admin/routes -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "graphql-rate-limited",
    "uri": "/graphql",
    "plugins": {
      "graphql-limit-count": {
        "count": 10,
        "time_window": 60,
        "rejected_code": 429,
        "key": "remote_addr"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": { "127.0.0.1:1980": 1 }
    }
  }'

A depth-4 query consumes 4 out of 10. After the budget is exhausted:

curl -i http://127.0.0.1:9080/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query": "query { foo { bar { baz { id } } } }"}'

# HTTP/1.1 200 OK
# X-RateLimit-Limit: 10
# X-RateLimit-Remaining: 6

# (after quota exhaustion)
# HTTP/1.1 429 Too Many Requests

Changes

File	Change
apisix/plugins/graphql-limit-count.lua	New plugin (priority 1004)
t/plugin/graphql-limit-count.t	14 test cases covering normal flow, error handling, and Redis/Redis-cluster policies
apisix/cli/config.lua	Register plugin; add plugin-graphql-limit-count and plugin-graphql-limit-count-reset-header shared dict defaults
apisix/cli/ngx_tpl.lua	Conditional shared dict declarations for the plugin
conf/config.yaml.example	Register plugin and shared dicts
docs/en/latest/plugins/graphql-limit-count.md	English documentation with examples
docs/zh/latest/plugins/graphql-limit-count.md	Chinese documentation with examples
docs/en/latest/config.json	Add to Traffic sidebar
docs/zh/latest/config.json	Add to 流量控制 sidebar
t/admin/plugins.t	Register plugin in admin test list

[Copilot]

Pull request overview

Adds a new graphql-limit-count traffic control plugin that reuses limit-count infrastructure to charge requests by parsed GraphQL query depth.

Changes:

• Adds the new plugin implementation and registers it in default plugin/admin configuration.
• Adds NGINX shared dict configuration for the plugin.
• Adds tests, documentation, and sidebar entries for English and Chinese docs.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
apisix/plugins/graphql-limit-count.lua	Implements GraphQL parsing, depth calculation, and limit-count integration.
apisix/cli/config.lua	Adds plugin and shared dict defaults.
apisix/cli/ngx_tpl.lua	Adds conditional shared dict declarations.
conf/config.yaml.example	Registers plugin and shared dicts in example config.
t/plugin/graphql-limit-count.t	Adds plugin functional tests.
t/admin/plugins.t	Adds plugin to admin plugin list expectations.
docs/en/latest/plugins/graphql-limit-count.md	Adds English plugin documentation.
docs/zh/latest/plugins/graphql-limit-count.md	Adds Chinese plugin documentation.
docs/en/latest/config.json	Adds English sidebar entry.
docs/zh/latest/config.json	Adds Chinese sidebar entry.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.