alibaba · kai2321 · Feb 12, 2025 · Feb 24, 2025
@@ -0,0 +1,73 @@
+<p>
+   <a href="README_EN.md"> English </a> | 中文
+</p>
+
+# 功能说明
+`key-rate-limit`插件实现了基于特定键值实现限流，键值来源可以是 URL 参数、HTTP 请求头
+
+# 配置字段
+
+| 名称 | 数据类型 | 填写要求 |  默认值 | 描述 |
+| -------- | -------- | -------- | -------- | -------- |
+|  limit_by_header     |  string     | 选填，`limit_by_header`,`limit_by_param` 中选填一项     |   -  |  配置获取限流键值的来源 http 请求头名称   |
+|  limit_by_param     |  string     | 选填，`limit_by_header`,`limit_by_param` 中选填一项     |   -  |  配置获取限流键值的来源 URL 参数名称   |
+|  limit_keys     |  array of object     | 必填     |   -  |  配置匹配键值后的限流次数   |
+
+`limit_keys`中每一项的配置字段说明
+
+| 名称 | 数据类型 | 填写要求 |  默认值 | 描述 |
+| -------- | -------- | -------- | -------- | -------- |
+|  key     |  string     | 必填     |   -  |  匹配的键值 |
+|  query_per_second     |  number     | 选填，`query_per_second`,`query_per_minute`,`query_per_hour`,`query_per_day` 中选填一项     |   -  |  允许每秒请求次数 |
+|  query_per_minute     |  number     | 选填，`query_per_second`,`query_per_minute`,`query_per_hour`,`query_per_day` 中选填一项     |   -  |  允许每分钟请求次数 |
+|  query_per_hour     |  number     | 选填，`query_per_second`,`query_per_minute`,`query_per_hour`,`query_per_day` 中选填一项     |   -  |  允许每小时请求次数 |
+|  query_per_day     |  number     | 选填，`query_per_second`,`query_per_minute`,`query_per_hour`,`query_per_day` 中选填一项     |   -  |  允许每天请求次数 |
+
+# 配置示例
+
+## 识别请求参数 apikey，进行区别限流
+```yaml
+limit_by_param: apikey
+limit_keys:
+- key: 9a342114-ba8a-11ec-b1bf-00163e1250b5
+  query_per_second: 10
+- key: a6a6d7f2-ba8a-11ec-bec2-00163e1250b5
+  query_per_minute: 100
+```
+
+## 识别请求头 x-ca-key，进行区别限流
+```yaml
+limit_by_header: x-ca-key
+limit_keys:
+- key: 102234
+  query_per_second: 10
+- key: 308239
+  query_per_hour: 10
+
+```
+
+## 对特定路由或域名开启
+```yaml
+# 使用 _rules_ 字段进行细粒度规则配置
+_rules_:
+# 规则一：按路由名称匹配生效
+- _match_route_:
+  - route-a
+  - route-b
+  limit_by_header: x-ca-key
+  limit_keys:
+  - key: 102234
+    query_per_second: 10
+# 规则二：按域名匹配生效
+- _match_domain_:
+  - "*.example.com"
+  - test.com
+  limit_by_header: x-ca-key
+  limit_keys:
+  - key: 102234
+    query_per_second: 100
+
+```
+此例 `_match_route_` 中指定的 `route-a` 和 `route-b` 即在创建网关路由时填写的路由名称，当匹配到这两个路由时，将使用此段配置；
+此例 `_match_domain_` 中指定的 `*.example.com` 和 `test.com` 用于匹配请求的域名，当发现域名匹配时，将使用此段配置；
+配置的匹配生效顺序，将按照 `_rules_` 下规则的排列顺序，匹配第一个规则后生效对应配置，后续规则将被忽略。
@@ -0,0 +1,71 @@
+<p>
+   English | <a href="README.md">中文</a>
+</p>
+
+# Description
+`key-rate-limit` plugin implements a rate-limiting function based on specific key-values. The key-values may come from URL parameters or HTTP headers.
+
+# Configuration Fields
+
+| Name | Type | Requirement |  Default Value | Description |
+| -------- | -------- | -------- | -------- | -------- |
+|  limit_by_header     |  string     | Optional. Choose one from following: `limit_by_header`, `limit_by_param`. |   -  |  The name of HTTP header used to obtain key-value used in rate-limiting. |
+|  limit_by_param     |  string     | Optional. Choose one from following: `limit_by_header`, `limit_by_param`. |   -  |  The name of URL parameter used to obtain key-value used in rate-limiting.   |
+|  limit_keys     |  array of object     | Required     |   -  |  Rate-limiting thresholds when matching specific key-values |
+
+Field descriptions of `limit_keys` items:
+
+| Name | Type | Requirement |  Default Value | Description |
+| -------- | -------- | -------- | -------- | -------- |
+|  key     |  string     | Required     |   -  |  Value to match of the specific key |
+|  query_per_second     |  number     | Optional. Choose one from following: `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day`. |   -  |  Number of requests allowed per second |
+|  query_per_minute     |  number     | Optional. Choose one from following: `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day`. |   -  |  Number of requests allowed per minute |
+|  query_per_hour     |  number     | Optional. Choose one from following: `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day`. |   -  |  Number of requests allowed per hour |
+|  query_per_day     |  number     | Optional. Choose one from following: `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day`. |   -  |  Number of requests allowed per day |
+
+# Configuration Samples
+
+## Use query parameter `apikey` for rate-limiting
+```yaml
+limit_by_param: apikey
+limit_keys:
+- key: 9a342114-ba8a-11ec-b1bf-00163e1250b5
+  query_per_second: 10
+- key: a6a6d7f2-ba8a-11ec-bec2-00163e1250b5
+  query_per_minute: 100
+```
+
+## Use HTTP header parameter `x-ca-key` for rate-limiting
+```yaml
+limit_by_header: x-ca-key
+limit_keys:
+- key: 102234
+  query_per_second: 10
+- key: 308239
+  query_per_hour: 10
+```
+
+## Enable rate-limiting for specific routes or domains
+```yaml
+# Use _rules_ field for fine-grained rule configurations
+_rules_:
+# Rule 1: Match by route name
+- _match_route_:
+  - route-a
+  - route-b
+  limit_by_header: x-ca-key
+  limit_keys:
+  - key: 102234
+    query_per_second: 10
+# Rule 2: Match by domain
+- _match_domain_:
+  - "*.example.com"
+  - test.com
+  limit_by_header: x-ca-key
+  limit_keys:
+  - key: 102234
+    query_per_second: 100
+```
+In the rule sample of `_match_route_`, `route-a` and `route-b` are the route names provided when creating a new gateway route. When the current route names matches the configuration, the rule following shall be applied.
+In the rule sample of `_match_domain_`, `*.example.com` and `test.com` are the domain names used for request matching. When the current domain name matches the configuration, the rule following shall be applied.
+All rules shall be checked following the order of items in the `_rules_` field, The first matched rule will be applied. All remained will be ignored.
@@ -0,0 +1,20 @@
+module key-rate-limit
+
+go 1.19
+
+replace github.com/alibaba/higress/plugins/wasm-go => ../..
+
+require (
+	github.com/alibaba/higress/plugins/wasm-go v1.4.4-0.20250208094229-512385d22551
+	github.com/higress-group/proxy-wasm-go-sdk v1.0.0
+	github.com/tidwall/gjson v1.18.0
+)
+
+require (
+	github.com/google/uuid v1.3.0 // indirect
+	github.com/higress-group/nottinygc v0.0.0-20231101025119-e93c4c2f8520 // indirect
+	github.com/magefile/mage v1.14.0 // indirect
+	github.com/tidwall/match v1.1.1 // indirect
+	github.com/tidwall/pretty v1.2.0 // indirect
+	github.com/tidwall/resp v0.1.1 // indirect
+)
@@ -0,0 +1,18 @@
+github.com/alibaba/higress/plugins/wasm-go v1.4.4-0.20250208094229-512385d22551 h1:okADrHK5ZXhlI1fGF06pNsLib45olF3BKMYtrH2JK00=
+github.com/alibaba/higress/plugins/wasm-go v1.4.4-0.20250208094229-512385d22551/go.mod h1:vB63GaXsCNfsVshhoO9zs92Uv9TWgs5bkMpRyaGd9nI=
+github.com/google/uuid v1.3.0 h1:t6JiXgmwXMjEs8VusXIJk2BXHsn+wx8BZdTaoZ5fu7I=
+github.com/google/uuid v1.3.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/higress-group/nottinygc v0.0.0-20231101025119-e93c4c2f8520 h1:IHDghbGQ2DTIXHBHxWfqCYQW1fKjyJ/I7W1pMyUDeEA=
+github.com/higress-group/nottinygc v0.0.0-20231101025119-e93c4c2f8520/go.mod h1:Nz8ORLaFiLWotg6GeKlJMhv8cci8mM43uEnLA5t8iew=
+github.com/higress-group/proxy-wasm-go-sdk v1.0.0 h1:BZRNf4R7jr9hwRivg/E29nkVaKEak5MWjBDhWjuHijU=
+github.com/higress-group/proxy-wasm-go-sdk v1.0.0/go.mod h1:iiSyFbo+rAtbtGt/bsefv8GU57h9CCLYGJA74/tF5/0=
+github.com/magefile/mage v1.14.0 h1:6QDX3g6z1YvJ4olPhT1wksUcSa/V0a1B+pJb73fBjyo=
+github.com/magefile/mage v1.14.0/go.mod h1:z5UZb/iS3GoOSn0JgWuiw7dxlurVYTu+/jHXqQg881A=
+github.com/tidwall/gjson v1.18.0 h1:FIDeeyB800efLX89e5a8Y0BNH+LOngJyGrIWxG2FKQY=
+github.com/tidwall/gjson v1.18.0/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
+github.com/tidwall/match v1.1.1 h1:+Ho715JplO36QYgwN9PGYNhgZvoUSc9X2c80KVTi+GA=
+github.com/tidwall/match v1.1.1/go.mod h1:eRSPERbgtNPcGhD8UCthc6PmLEQXEWd3PRB5JTxsfmM=
+github.com/tidwall/pretty v1.2.0 h1:RWIZEg2iJ8/g6fDDYzMpobmaoGh5OLl4AXtGUGPcqCs=
+github.com/tidwall/pretty v1.2.0/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
+github.com/tidwall/resp v0.1.1 h1:Ly20wkhqKTmDUPlyM1S7pWo5kk0tDu8OoC/vFArXmwE=
+github.com/tidwall/resp v0.1.1/go.mod h1:3/FrruOBAxPTPtundW0VXgmsQ4ZBA0Aw714lVYgwFa0=