This is an automated email from the ASF dual-hosted git repository.
sylviasu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new b60913bcb docs: add websocket rate limit example (#7581)
b60913bcb is described below
commit b60913bcb1d23352278db9726ecfaf336a2cd702
Author: soulbird <[email protected]>
AuthorDate: Wed Aug 3 16:39:15 2022 +0800
docs: add websocket rate limit example (#7581)
* docs: add websocket rate limit example
---
docs/en/latest/plugins/limit-conn.md | 73 ++++++++++++++++++++++++++++++++
docs/zh/latest/plugins/limit-conn.md | 81 ++++++++++++++++++++++++++++++++++--
2 files changed, 150 insertions(+), 4 deletions(-)
diff --git a/docs/en/latest/plugins/limit-conn.md
b/docs/en/latest/plugins/limit-conn.md
index 508ed1c58..e004be950 100644
--- a/docs/en/latest/plugins/limit-conn.md
+++ b/docs/en/latest/plugins/limit-conn.md
@@ -141,3 +141,76 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}
}'
```
+
+## Limit the number of concurrent WebSocket connections
+
+Apache APISIX supports WebSocket proxy, we can use `limit-conn` plugin to
limit the number of concurrent WebSocket connections.
+
+1. Create a Route, enable the WebSocket proxy and the `limit-conn` plugin.
+
+````shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/ws",
+ "enable_websocket": true,
+ "plugins": {
+ "limit-conn": {
+ "conn": 1,
+ "burst": 0,
+ "default_conn_delay": 0.1,
+ "rejected_code": 503,
+ "key_type": "var",
+ "key": "remote_addr"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ }
+}'
+````
+
+The above route enables the WebSocket proxy on `/ws`, and limits the number of
concurrent WebSocket connections to 1. More than 1 concurrent WebSocket
connection will return `503` to reject the request.
+
+2. Initiate a WebSocket request, and the connection is established successfully
+
+````shell
+curl --include \
+ --no-buffer \
+ --header "Connection: Upgrade" \
+ --header "Upgrade: websocket" \
+ --header "Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==" \
+ --header "Sec-WebSocket-Version: 13" \
+ --http1.1 \
+ http://127.0.0.1:9080/ws
+```
+
+```shell
+HTTP/1.1 101 Switching Protocols
+Connection: upgrade
+Upgrade: websocket
+Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
+Server: APISIX/2.15.0
+...
+````
+
+3. Initiate the WebSocket request again in another terminal, the request will
be rejected
+
+````shell
+HTTP/1.1 503 Service Temporarily Unavailable
+Date: Mon, 01 Aug 2022 03:49:17 GMT
+Content-Type: text/html; charset=utf-8
+Content-Length: 194
+Connection: keep-alive
+Server: APISIX/2.15.0
+
+<html>
+<head><title>503 Service Temporarily Unavailable</title></head>
+<body>
+<center><h1>503 Service Temporarily Unavailable</h1></center>
+<hr><center>openresty</center>
+</body>
+</html>
+````
diff --git a/docs/zh/latest/plugins/limit-conn.md
b/docs/zh/latest/plugins/limit-conn.md
index 9e3173547..631f23ba4 100644
--- a/docs/zh/latest/plugins/limit-conn.md
+++ b/docs/zh/latest/plugins/limit-conn.md
@@ -39,7 +39,7 @@ title: limit-conn
| rejected_msg | string | 否 |
| 非空 | 当请求超过 `conn` + `burst`
这个阈值时，返回的响应体。
|
| allow_degradation | boolean | 否
| false |
| 当插件功能临时不可用时是否允许请求继续。当值设置为 true 时则自动允许请求继续，默认值是 false。
|
-### 如何启用
+## 开启插件
下面是一个示例，在指定的 route 上开启了 limit-conn 插件，并设置 `key_type` 为 `var`:
@@ -68,7 +68,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-下面是一个示例，在指定的 route 上开启了 limit-conn 插件，并设置 `key_type` 为 `var_combination`:
+下面是一个示例，在指定的路由上开启了 `limit-conn` 插件，并设置 `key_type` 为 `var_combination`:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -98,7 +98,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
你也可以通过 web 界面来完成上面的操作，先增加一个 route，然后在插件页面中添加 limit-conn 插件：
-### 测试插件
+## 测试插件
上面启用的插件的参数表示只允许一个并发请求。 当收到多个并发请求时，将直接返回 503 拒绝请求。
@@ -117,7 +117,7 @@ curl -i http://127.0.0.1:9080/index.html?sleep=20
这就表示 limit-conn 插件生效了。
-### 移除插件
+## 移除插件
当你想去掉 limit-conn 插件的时候，很简单，在插件的配置中把对应的 json 配置删除即可，无须重启服务，即刻生效：
@@ -136,3 +136,76 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
```
现在就已经移除了 limit-conn 插件了。其他插件的开启和移除也是同样的方法。
+
+## 限制 WebSocket 连接的并发数
+
+Apache APISIX 支持 WebSocket 代理，我们可以使用 `limit-conn` 插件限制 WebSocket 连接的并发数。
+
+1、创建路由并启用 WebSocket 代理和 `limit-conn` 插件
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/ws",
+ "enable_websocket": true,
+ "plugins": {
+ "limit-conn": {
+ "conn": 1,
+ "burst": 0,
+ "default_conn_delay": 0.1,
+ "rejected_code": 503,
+ "key_type": "var",
+ "key": "remote_addr"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ }
+}'
+```
+
+上述路由在 `/ws` 上开启了 WebSocket 代理，并限制了 WebSocket 连接并发数为 1，超过 1 个并发的 WebSocket
连接将返回 `503` 拒绝请求。
+
+2、发起 WebSocket 请求，连接建立成功
+
+```shell
+curl --include \
+ --no-buffer \
+ --header "Connection: Upgrade" \
+ --header "Upgrade: websocket" \
+ --header "Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==" \
+ --header "Sec-WebSocket-Version: 13" \
+ --http1.1 \
+ http://127.0.0.1:9080/ws
+```
+
+```shell
+HTTP/1.1 101 Switching Protocols
+Connection: upgrade
+Upgrade: websocket
+Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
+Server: APISIX/2.15.0
+...
+```
+
+3、在另一个终端中再次发起 WebSocket 请求，请求将被拒绝
+
+```shell
+HTTP/1.1 503 Service Temporarily Unavailable
+Date: Mon, 01 Aug 2022 03:49:17 GMT
+Content-Type: text/html; charset=utf-8
+Content-Length: 194
+Connection: keep-alive
+Server: APISIX/2.15.0
+
+<html>
+<head><title>503 Service Temporarily Unavailable</title></head>
+<body>
+<center><h1>503 Service Temporarily Unavailable</h1></center>
+<hr><center>openresty</center>
+</body>
+</html>
+```
