Copilot commented on code in PR #13215: URL: https://github.com/apache/apisix/pull/13215#discussion_r3090312466
########## docs/zh/latest/plugins/limit-conn.md: ########## @@ -264,40 +658,183 @@ docker run -d \ jmalloc/echo-server ``` -创建到服务器 WebSocket 端点的路由，并为路由启用 WebSocket。相应地调整 WebSocket 服务器地址。 +该服务器在 `/.ws` 路径上有一个 WebSocket 端点，会回显收到的任何消息。 + Review Comment: WebSocket 示例先通过 `docker run` 启动上游，但 “Ingress Controller” 标签页的 YAML 直接引用了 Kubernetes 中名为 `websocket-server` 的 Service（片段里也没有定义该 Service）。这会导致按文档操作时 Ingress 配置无法直接运行。建议在 Ingress 标签页补充 WebSocket 服务的 Deployment/Service（或 ExternalName Service），或明确说明需要预先创建 `websocket-server` Service。 ```suggestion :::note 上述 `docker run` 示例适用于直接将路由指向 Docker 网络中的上游容器。 如果使用下方的 **Ingress Controller** 标签页，请先在 Kubernetes 集群中创建名为 `websocket-server` 的 Service，并确保它可以将流量转发到实际的 WebSocket 服务后端（例如通过 Deployment/Service，或其他等价方式暴露该服务）。否则，Ingress 中对 `websocket-server` 的引用将无法生效。 ::: ``` ########## docs/en/latest/plugins/limit-conn.md: ########## @@ -264,34 +658,177 @@ docker run -d \ jmalloc/echo-server ``` -Create a Route to the server WebSocket endpoint and enable WebSocket for the route. Adjust the WebSocket server address accordingly. +The server has a WebSocket endpoint at `/.ws` that echoes back any message received. + Review Comment: In the WebSocket example, the section first starts an upstream via `docker run`, but the Ingress Controller tab YAML references a Kubernetes Service named `websocket-server` (and the snippet doesn’t define that Service). This makes the Ingress path non-runnable as written. Consider either adding a K8s Deployment/Service manifest for the WebSocket server (or an ExternalName Service) in the Ingress tab, or clarifying that `websocket-server` must already exist in the cluster. ```suggestion In the following examples, the Admin API configuration uses the Docker container hostname `websocket-server` on the `apisix-quickstart-net` network. If you use the Ingress Controller example, make sure a Kubernetes Service named `websocket-server` already exists in your cluster, or update the backend reference to match an existing Service. ``` ########## docs/zh/latest/plugins/limit-conn.md: ########## @@ -30,43 +30,46 @@ description: limit-conn 插件通过管理并发连接来限制请求速率。 <link rel="canonical" href="https://docs.api7.ai/hub/limit-conn"; /> </head> +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## 描述 `limit-conn` 插件通过并发连接数来限制请求速率。超过阈值的请求将根据配置被延迟或拒绝，从而确保可控的资源使用并防止过载。 ## 属性 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -|------------|---------|----------|-------|----------------------------|------------------| -| conn | integer | 否 | | > 0 | 允许的最大并发请求数。超过配置的限制且低于`conn + burst`的请求将被延迟。如果未配置 `rules`,则为必填项。| -| burst | integer | 否 | | >= 0 | 每秒允许延迟的过多并发请求数。超过限制的请求将被立即拒绝。如果未配置 `rules`,则为必填项。| -| default_conn_delay | number | 是 | | > 0 | 允许超过`conn + burst`的并发请求的处理延迟（秒），可根据`only_use_default_delay`设置动态调整。| -| only_use_default_delay | boolean | 否 | false | | 如果为 false，则根据请求超出`conn`限制的程度按比例延迟请求。拥塞越严重，延迟就越大。例如，当 `conn` 为 `5`、`burst` 为 `3` 且 `default_conn_delay` 为 `1` 时，6 个并发请求将导致 1 秒的延迟，7 个请求将导致 2 秒的延迟，8 个请求将导致 3 秒的延迟，依此类推，直到达到 `conn + burst` 的总限制，超过此限制的请求将被拒绝。如果为 true，则使用 `default_conn_delay` 延迟 `burst` 范围内的所有超额请求。超出 `conn + burst` 的请求将被立即拒绝。例如，当 `conn` 为 `5`、`burst` 为 `3` 且 `default_conn_delay` 为 `1` 时，6、7 或 8 个并发请求都将延迟 1 秒。| -| rules | array[object] | 否 | | | 连接限制规则列表。每个规则是一个包含 `conn`、`burst` 和 `key` 的对象。如果配置了此项，则优先于 `conn`、`burst` 和 `key`。 | -| rules.conn | integer 或 string | 是 | | > 0 或变量表达式 | 允许的最大并发请求数。可以是静态整数或变量表达式，如 `$http_custom_conn`。 | -| rules.burst | integer 或 string | 是 | | >= 0 或变量表达式 | 允许延迟的过多并发请求数。可以是静态整数或变量表达式。 | -| rules.key | string | 是 | | | 用于计数请求的键。如果配置的键不存在，则不会执行该规则。`key` 被解释为变量组合，例如：`$http_custom_a $http_custom_b`。 | -| key_type | string | 否 | var | ["var","var_combination"] | key 的类型。如果`key_type` 为 `var`，则 `key` 将被解释为变量。如果 `key_type` 为 `var_combination`，则 `key` 将被解释为变量的组合。 | -| key | string | 否 | remote_addr | | 用于计数请求的 key。如果 `key_type` 为 `var`，则 `key` 将被解释为变量。变量不需要以美元符号（`$`）为前缀。如果 `key_type` 为 `var_combination`，则 `key` 会被解释为变量的组合。所有变量都应该以美元符号 (`$`) 为前缀。例如，要配置 `key` 使用两个请求头 `custom-a` 和 `custom-b` 的组合，则 `key` 应该配置为 `$http_custom_a $http_custom_b`。如果未配置 `rules`，则为必填项。| -| key_ttl | integer | 否 | 3600 | | Redis 键的 TTL（以秒为单位）。当 `policy` 为 `redis` 或 `redis-cluster` 时使用。 | -| rejected_code | integer | 否 | 503 | [200,...,599] | 请求因超出阈值而被拒绝时返回的 HTTP 状态代码。| -| rejection_msg | string | 否 | | 非空 | 请求因超出阈值而被拒绝时返回的响应主体。| +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +|------|------|--------|--------|--------|------| +| conn | integer | 否 | | > 0 | 允许的最大并发请求数。超过配置的限制且低于 `conn + burst` 的请求将被延迟。如果未配置 `rules`，则为必填项。| +| burst | integer | 否 | | >= 0 | 允许延迟的过多并发请求数。超过 `conn + burst` 的请求将被立即拒绝。如果未配置 `rules`，则为必填项。| Review Comment: 属性表中 `conn` 和 `burst` 的类型标为 `integer`，但插件 schema 实际支持 `integer` 或 `string`（可用变量表达式，运行时通过 `core.utils.resolve_var` 解析）。这会导致用户误以为顶层不支持变量。建议将类型/有效值更新为 `integer 或 string` 并说明变量写法。 ```suggestion | conn | integer 或 string | 否 | | 整数时 > 0；或变量表达式 | 允许的最大并发请求数。超过配置的限制且低于 `conn + burst` 的请求将被延迟。如果未配置 `rules`，则为必填项。支持直接填写整数，或填写变量表达式（例如 `$arg_conn`），变量会在运行时解析。| | burst | integer 或 string | 否 | | 整数时 >= 0；或变量表达式 | 允许延迟的过多并发请求数。超过 `conn + burst` 的请求将被立即拒绝。如果未配置 `rules`，则为必填项。支持直接填写整数，或填写变量表达式（例如 `$arg_burst`），变量会在运行时解析。| ``` ########## docs/en/latest/plugins/limit-conn.md: ########## @@ -30,43 +30,46 @@ description: The limit-conn plugin restricts the rate of requests by managing co <link rel="canonical" href="https://docs.api7.ai/hub/limit-conn"; /> </head> +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## Description The `limit-conn` Plugin limits the rate of requests by the number of concurrent connections. Requests exceeding the threshold will be delayed or rejected based on the configuration, ensuring controlled resource usage and preventing overload. ## Attributes -| Name | Type | Required | Default | Valid values | Description | -|------------|---------|----------|-------------|-------------------|-----------------| -| conn | integer | False | | > 0 | The maximum number of concurrent requests allowed. Requests exceeding the configured limit and below `conn + burst` will be delayed. Required if `rules` is not configured. | -| burst | integer | False | | >= 0 | The number of excessive concurrent requests allowed to be delayed per second. Requests exceeding the limit will be rejected immediately. Required if `rules` is not configured. | -| default_conn_delay | number | True | | > 0 | Processing latency allowed in seconds for concurrent requests exceeding `conn + burst`, which can be dynamically adjusted based on `only_use_default_delay` setting. | -| only_use_default_delay | boolean | False | false | | If false, delay requests proportionally based on how much they exceed the `conn` limit. The delay grows larger as congestion increases. For instance, with `conn` being `5`, `burst` being `3`, and `default_conn_delay` being `1`, 6 concurrent requests would result in a 1-second delay, 7 requests a 2-second delay, 8 requests a 3-second delay, and so on, until the total limit of `conn + burst` is reached, beyond which requests are rejected. If true, use `default_conn_delay` to delay all excessive requests within the `burst` range. Requests beyond `conn + burst` are rejected immediately. For instance, with `conn` being `5`, `burst` being `3`, and `default_conn_delay` being `1`, 6, 7, or 8 concurrent requests are all delayed by exactly 1 second each. | -| rules | array[object] | False | | | A list of connection limiting rules. Each rule is an object containing `conn`, `burst`, and `key`. If configured, this takes precedence over `conn`, `burst`, and `key`. | -| rules.conn | integer or string | True | | > 0 or variable expression | The maximum number of concurrent requests allowed. Can be a static integer or a variable expression like `$http_custom_conn`. | -| rules.burst | integer or string | True | | >= 0 or variable expression | The number of excessive concurrent requests allowed to be delayed. Can be a static integer or a variable expression. | -| rules.key | string | True | | | 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`. | -| key_type | string | False | var | ["var","var_combination"] | The type of key. If the `key_type` is `var`, the `key` is interpreted a variable. If the `key_type` is `var_combination`, the `key` is interpreted as a combination of variables. | -| key | string | False | remote_addr | | The key to count requests by. If the `key_type` is `var`, the `key` is interpreted a variable. The variable does not need to be prefixed by a dollar sign (`$`). 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`. Required if `rules` is not configured. | -| key_ttl | integer | False | 3600 | | The TTL of the Redis key in seconds. Used when `policy` is `redis` or `redis-cluster`. | -| rejected_code | integer | False | 503 | [200,...,599] | The HTTP status code returned when a request is rejected for exceeding the threshold. | -| rejected_msg | string | False | | non-empty | The response body returned when a request is rejected for exceeding the threshold. | -| allow_degradation | boolean | False | false | | If true, allow APISIX to continue handling requests without the Plugin when the Plugin or its dependencies become unavailable. | -| policy | string | False | local | ["local","redis","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. | -| redis_host | string | False | | | The address of the Redis node. Required when `policy` is `redis`. | -| redis_port | integer | False | 6379 | [1,...] | The port of the Redis node when `policy` is `redis`. | -| redis_username | string | False | | | 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 | False | | | The password of the Redis node when `policy` is `redis` or `redis-cluster`. | -| redis_ssl | boolean | False | false | | If true, use SSL to connect to Redis cluster when `policy` is `redis`. | -| redis_ssl_verify | boolean | False | false | | If true, verify the server SSL certificate when `policy` is `redis`. | -| redis_database | integer | False | 0 | >= 0 | The database number in Redis when `policy` is `redis`. | -| redis_timeout | integer | False | 1000 | [1,...] | The Redis timeout value in milliseconds when `policy` is `redis` or `redis-cluster`. | -| redis_keepalive_timeout | integer | False | 10000 | ≥ 1000 | Keepalive timeout in milliseconds for redis when `policy` is `redis` or `redis-cluster`. | -| redis_keepalive_pool | integer | False | 100 | ≥ 1 | Keepalive pool size for redis when `policy` is `redis` or `redis-cluster`.| -| redis_cluster_nodes | array[string] | False | | | The list of the Redis cluster nodes with at least two addresses. Required when policy is redis-cluster. | -| redis_cluster_name | string | False | | | The name of the Redis cluster. Required when `policy` is `redis-cluster`. | -| redis_cluster_ssl | boolean | False | false | | If true, use SSL to connect to Redis cluster when `policy` is | -| redis_cluster_ssl_verify | boolean | False | false | | If true, verify the server SSL certificate when `policy` is `redis-cluster`. | +| Name | Type | Required | Default | Valid values | Description | +|------|------|----------|---------|--------------|-------------| +| conn | integer | False | | > 0 | The maximum number of concurrent requests allowed. Requests exceeding the configured limit and below `conn + burst` will be delayed. Required if `rules` is not configured. | +| burst | integer | False | | >= 0 | The number of excessive concurrent requests allowed to be delayed. Requests exceeding `conn + burst` will be rejected immediately. Required if `rules` is not configured. | Review Comment: `conn` and `burst` are documented as `integer` only, but the plugin schema allows both to be `integer` or `string` (variables resolved via `core.utils.resolve_var`). This mismatch can confuse users trying to use variable expressions at the top level (not only under `rules`). Update the type/valid-values columns accordingly. ```suggestion | conn | integer,string | False | | integer > 0, or a variable expression | The maximum number of concurrent requests allowed. Requests exceeding the configured limit and below `conn + burst` will be delayed. Required if `rules` is not configured. | | burst | integer,string | False | | integer >= 0, or a variable expression | The number of excessive concurrent requests allowed to be delayed. Requests exceeding `conn + burst` will be rejected immediately. Required if `rules` is not configured. | ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
