chore: update docs about sliding window

Signed-off-by: Sihyeon Jang <[email protected]>

Author: sihyeonn

docs/en/latest/plugins/limit-count.md

@@ -4,7 +4,7 @@ keywords:
   - Apache APISIX
   - API Gateway
   - Limit Count
-description: The limit-count plugin uses a fixed window algorithm to limit the rate of requests by the number of requests within a given time interval. Requests exceeding the configured quota will be rejected.
+description: The limit-count plugin limits the rate of requests by the number of requests within a given time interval. It supports both fixed window and sliding window behaviors. Requests exceeding the configured quota will be rejected.
 ---
 
 <!--
@@ -32,7 +32,12 @@ description: The limit-count plugin uses a fixed window algorithm to limit the r
 
 ## Description
 
-The `limit-count` plugin uses a fixed window algorithm to limit the rate of requests by the number of requests within a given time interval. Requests exceeding the configured quota will be rejected.
+The `limit-count` plugin limits the rate of requests by the number of requests within a given time interval. It supports both **fixed window** and **sliding window** behaviors.
+
+- When `window_type` is `fixed` (default), the plugin uses a fixed window algorithm.
+- When `window_type` is `sliding`, and the `policy` is `redis` or `redis-cluster`, the plugin enforces an exact **N requests per rolling time window** using a sliding window algorithm.
+
+Requests exceeding the configured quota will be rejected.
 
 You may see the following rate limiting headers in the response:
 
@@ -46,6 +51,7 @@ You may see the following rate limiting headers in the response:
 | ----------------------- | ------- | ----------------------------------------- | ------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | count                   | integer | True                                      |               | > 0                              | The maximum number of requests allowed within a given time interval.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | time_window             | integer | True                                      |               | > 0                        | The time interval corresponding to the rate limiting `count` in seconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| window_type             | string  | False                                     | fixed         | ["fixed","sliding"]          | The window behavior type. `fixed` uses a fixed window algorithm. `sliding` uses a sliding window algorithm to enforce an exact number of requests per rolling window. `sliding` is only supported when `policy` is `redis` or `redis-cluster`.                                                                                                                                                                                                                                               |
 | key_type                | string  | False                                     | var         | ["var","var_combination","constant"] | 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. If the `key_type` is `constant`, the `key` is interpreted as a constant.                  |
 | 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`. If the `key_type` is `constant`, the `key` is interpreted as a constant value. |
 | rejected_code           | integer | False                                     | 503           | [200,...,599]                          | The HTTP status code returned when a request is rejected for exceeding the threshold.                                                                                                                                                                                                                                                                                                                                                                                                                    |
@@ -401,6 +407,33 @@ You should see an `HTTP/1.1 200 OK` response with the corresponding response bod
 
 Send the same request to a different APISIX instance within the same 30-second time interval, you should receive an `HTTP/1.1 429 Too Many Requests` response, verifying routes configured in different APISIX nodes share the same quota.
 
+### Performance considerations (sliding window)
+
+When `window_type` is set to `sliding` and the `policy` is `redis` or `redis-cluster`, this Plugin uses a Redis ZSET to store timestamps for recent requests (a sliding log).
+
+Roughly, the memory usage for sliding window per Redis instance can be approximated as:
+
+\[
+\text{Memory} \approx K \times C \times B
+\]
+
+Where:
+
+- \(K\): number of active keys that receive traffic within a `time_window`
+- \(C\): `count` (maximum requests allowed per key within the window)
+- \(B\): bytes per ZSET entry (timestamp + member + metadata). A conservative estimate is around 100 bytes.
+
+For example:
+
+- \(K = 10{,}000\), \(C = 50\), \(B \approx 100\) → about 50 MB
+- \(K = 100{,}000\), \(C = 100\), \(B \approx 100\) → about 1 GB
+
+In practice, you should:
+
+- Monitor Redis memory and CPU when enabling sliding windows.
+- Prefer relatively small `count` values (tens to low hundreds) for keys with high QPS.
+- Consider using `window_type = "fixed"` (or `limit-req`) for very high throughput keys with large `count` or very high key cardinality.
+
 ### Rate Limit with Anonymous Consumer
 
 does not need to authenticate and has less quotas. While this example uses [`key-auth`](./key-auth.md) for authentication, the anonymous Consumer can also be configured with [`basic-auth`](./basic-auth.md), [`jwt-auth`](./jwt-auth.md), and [`hmac-auth`](./hmac-auth.md).

docs/zh/latest/plugins/limit-count.md

@@ -5,7 +5,7 @@ keywords:
   - API 网关
   - Limit Count
   - 速率限制
-description: limit-count 插件使用固定窗口算法，通过给定时间间隔内的请求数量来限制请求速率。超过配置配额的请求将被拒绝。
+description: limit-count 插件通过给定时间间隔内的请求数量来限制请求速率，支持固定窗口和滑动窗口两种行为。超过配置配额的请求将被拒绝。
 ---
 
 <!--
@@ -33,7 +33,12 @@ description: limit-count 插件使用固定窗口算法，通过给定时间间
 
 ## 描述
 
-`limit-count` 插件使用固定窗口算法，通过给定时间间隔内的请求数量来限制请求速率。超过配置配额的请求将被拒绝。
+`limit-count` 插件通过给定时间间隔内的请求数量来限制请求速率，支持 **固定窗口** 和 **滑动窗口** 两种行为。
+
+- 当 `window_type` 为 `fixed`（默认）时，插件使用固定窗口算法。
+- 当 `window_type` 为 `sliding` 且 `policy` 为 `redis` 或 `redis-cluster` 时，插件使用滑动窗口算法，在滚动时间窗口内精确限制请求次数。
+
+超过配置配额的请求将被拒绝。
 
 您可能会在响应中看到以下速率限制标头：
 
@@ -47,6 +52,7 @@ description: limit-count 插件使用固定窗口算法，通过给定时间间
 | ------------------- | ------- | ---------- | ------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | count | integer | 是 | | > 0 | 给定时间间隔内允许的最大请求数。 |
 | time_window | integer | 是 | | > 0 | 速率限制 `count` 对应的时间间隔（以秒为单位）。 |
+| window_type | string | 否 | fixed | ["fixed","sliding"] | 窗口行为类型。`fixed` 使用固定窗口算法；`sliding` 使用滑动窗口算法，在滚动时间窗口内精确限制请求次数。仅当 `policy` 为 `redis` 或 `redis-cluster` 时才支持 `sliding`。 |
 | key_type | string | 否 | var | ["var","var_combination","constant"] | key 的类型。如果`key_type` 为 `var`，则 `key` 将被解释为变量。如果 `key_type` 为 `var_combination`，则 `key` 将被解释为变量的组合。如果 `key_type` 为 `constant`，则 `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`。如果 `key_type` 为 `constant`，则 `key` 会被解释为常量值。|
 | rejection_code | integer | 否 | 503 | [200,...,599] | 请求因超出阈值而被拒绝时返回的 HTTP 状态代码。|
@@ -402,6 +408,33 @@ curl -i "http://127.0.0.1:9080/get"
 
 在相同的 30 秒时间间隔内向不同的 APISIX 实例发送相同的请求，您应该会收到一个 `HTTP/1.1 429 Too Many Requests` 响应，验证在不同 APISIX 节点中配置的路由是否共享相同的配额。
 
+### 性能注意事项（滑动窗口）
+
+当 `window_type` 配置为 `sliding` 且 `policy` 为 `redis` 或 `redis-cluster` 时，`limit-count` 会使用 Redis ZSET 作为滑动日志，按时间戳存储最近的请求记录。
+
+大致的内存占用可以近似为：
+
+\[
+\text{内存} \approx K \times C \times B
+\]
+
+其中：
+
+- \(K\)：在一个 `time_window` 内实际接收到流量的 key 数量
+- \(C\)：`count`（每个 key 在窗口内允许的最大请求数）
+- \(B\)：每个 ZSET 元素占用的字节数（时间戳 + member 字符串 + 元数据，保守估计约为 100 字节）
+
+例如：
+
+- \(K = 10{,}000\), \(C = 50\), \(B \approx 100\) → 内存约 50 MB
+- \(K = 100{,}000\), \(C = 100\), \(B \approx 100\) → 内存约 1 GB
+
+实际使用时建议：
+
+- 开启 `window_type = "sliding"` 时监控 Redis 的内存和 CPU 使用情况；
+- 对高 QPS 的 key，优先使用相对较小的 `count`（几十到一两百级别）；
+- 对于 `count` 很大、key 数量非常多或单 key 负载极高的场景，优先考虑 `window_type = "fixed"` 或使用 `limit-req` 插件来实现速率限制。
+
 ### 使用匿名消费者进行速率限制
 
 以下示例演示了如何为常规和匿名消费者配置不同的速率限制策略，其中匿名消费者不需要进行身份验证并且配额较少。虽然此示例使用 [`key-auth`](./key-auth.md) 进行身份验证，但匿名消费者也可以使用 [`basic-auth`](./basic-auth.md)、[`jwt-auth`](./jwt-auth.md) 和 [`hmac-auth`](./hmac-auth.md) 进行配置。