docs: add doc for http3

docs/en/latest/config.json

@@ -391,6 +391,10 @@
     {
       "type": "doc",
       "id": "upgrade-guide-from-2.15.x-to-3.0.0"
+    },
+    {
+      "type": "doc",
+      "id": "http3"
     }
   ]
 }

docs/en/latest/http3.md

@@ -0,0 +1,128 @@
+---
+title: HTTP/3 protocol
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+[HTTP/3](https://en.wikipedia.org/wiki/HTTP/3) is the third major version of the Hypertext Transfer Protocol (HTTP). Unlike its predecessors which rely on TCP, HTTP/3 is based on [QUIC (Quick UDP Internet Connections) protocol](https://en.wikipedia.org/wiki/QUIC). It brings several benefits that collectively result in reduced latency and improved performance:
+
+ * enabling seamless transition between different network connections, such as switching from Wi-Fi to mobile data.
+ * eliminating head-of-line blocking, so that a lost packet does not block all streams.
+ * negotiate TLS versions at the same time as the TLS handshakes, allowing for faster connections.
+ * providing encryption by default, ensuring that all data transmitted over an HTTP/3 connection is protected and confidential.
+ * providing zero round-trip time (0-RTT) when communicating with servers that clients already established connections to.
+
+ APISIX currently supports HTTP/3 connections between downstream clients and APISIX. HTTP/3 connections with upstream services is not yet supported. Contributions are welcomed.
+
+ :::caution
+
+ This feature has not been tested at scale and therefore, is not recommended for production use.
+
+ :::
+
+## Usage example
+
+1. To allow for HTTP/3 connections on 9443 port, add the following configurations to the `config.yaml` file:
+
+```yaml
+apisix:
+  ssl:
+    listen:
+      - port: 9443
+        enable_http3: true   # enable HTTP/3
+    ssl_protocols: TLSv1.3 # enable TLSv1.3
+```
+
+**note** `enable_http3` requires `TLSv1.3`
+
+2. Create an SSL object for test.com.
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/ssls/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+     "cert" : "'"$(cat t/certs/apisix.crt)"'",
+     "key": "'"$(cat t/certs/apisix.key)"'",
+     "snis": ["test.com"]
+}'
+```
+
+3. Create route
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+{
+    "uri": "/get",
+    "hosts": ["test.com"],
+    "methods": ["GET"],
+    "upstream": {
+        "type": "roundrobin",
+        "nodes": {
+            "httpbin.org": 1
+        }
+    }
+}'
+```
+
+4. Access verification
+
+Access test.com using HTTP/3:
+
+- curl version 7.88.0+, requires [http-only](https://github.com/curl/curl/blob/master/docs/cmdline-opts/http3-only.md) option.
+
+```shell
+curl -k -vvv -H "Host: test.com" -H "content-length: 0" --http3-only --resolve "test.com:9443:127.0.0.1" https://test.com:9443/get
+
+* Added test.com:9443:127.0.0.1 to DNS cache
+* Hostname test.com was found in DNS cache
+*   Trying 127.0.0.1:9443...
+* QUIC cipher selection: TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256
+* Skipped certificate verification
+* Connected to test.com (127.0.0.1) port 9443
+* using HTTP/3
+* [HTTP/3] [0] OPENED stream for https://test.com:9443/get
+* [HTTP/3] [0] [:method: GET]
+* [HTTP/3] [0] [:scheme: https]
+* [HTTP/3] [0] [:authority: test.com]
+* [HTTP/3] [0] [:path: /get]
+* [HTTP/3] [0] [user-agent: curl/8.6.0]
+* [HTTP/3] [0] [accept: */*]
+* [HTTP/3] [0] [content-length: 0]
+> GET /get HTTP/3
+> Host: test.com
+> User-Agent: curl/8.6.0
+> Accept: */*
+> content-length: 0
+>
+< HTTP/3 200
+< content-type: text/plain; charset=utf-8
+< content-length: 28
+< date: Mon, 04 Mar 2024 04:38:42 GMT
+< server: APISIX/3.9.0
+<
+* Connection #0 to host test.com left intact
+```
+
+## Known Issues
+
+- For APISIX-3.9, test cases of Tongsuo will fail because the Tongsuo does not support QUIC TLS.
+- For HTTP/2 or HTTP/3 the request should send `content-length` header no matter what HTTP methods you use.
+- APISIX-3.9 is based on NGINX-1.25.3 with  vulnerabilities in HTTP/3 (CVE-2024-24989, CVE-2024-24990).

docs/zh/latest/config.json

@@ -335,6 +335,10 @@
     {
       "type": "doc",
       "id": "upgrade-guide-from-2.15.x-to-3.0.0"
+    },
+    {
+      "type": "doc",
+      "id": "http3"
     }
   ]
 }

docs/zh/latest/http3.md

@@ -0,0 +1,128 @@
+---
+title: HTTP3 协议
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+[HTTP/3](https://en.wikipedia.org/wiki/HTTP/3) 是 Hypertext Transfer Protocol(HTTP) 的第三个主要版本。 与依赖 TCP 的前辈不同，HTTP/3 基于 [QUIC (Quick UDP Internet Connections) protocol](https://en.wikipedia.org/wiki/QUIC)。 它带来了多项好处，减少了延迟并提高了性能：
+
+ * 实现不同网络连接之间的无缝过渡，例如从 Wi-Fi 切换到移动数据。
+ * 消除队头阻塞，以便丢失的数据包不会阻塞所有流。
+ * 在 TLS 握手的同时协商 TLS 版本，从而实现更快的连接。
+ * 默认提供加密，确保通过 HTTP/3 连接传输的所有数据都受到保护和保密。
+ * 在与客户端已建立连接的服务器通信时提供零往返时间(0-RTT)。
+
+ APISIX 目前支持下游客户端和 APISIX 之间的 HTTP/3 连接。 尚不支持与上游服务的 HTTP/3 连接。 欢迎贡献。
+
+ :::caution
+
+ 此功能尚未经过大规模测试，因此不建议用于生产使用。
+
+ :::
+
+## 使用示例
+
+1. config.yaml 配置。
+
+```yaml
+apisix:
+  ssl:
+    listen:
+      - port: 9443
+        enable_http3: true   # enable HTTP/3
+    ssl_protocols: TLSv1.3 # enable TLSv1.3
+```
+
+**注意** `enable_http3` 需要 `TLSv1.3`
+
+2. 为 test.com 创建 SSL 对象。
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/ssls/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+     "cert" : "'"$(cat t/certs/apisix.crt)"'",
+     "key": "'"$(cat t/certs/apisix.key)"'",
+     "snis": ["test.com"]
+}'
+```
+
+3. 创建 route
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+{
+    "uri": "/get",
+    "hosts": ["test.com"],
+    "methods": ["GET"],
+    "upstream": {
+        "type": "roundrobin",
+        "nodes": {
+            "httpbin.org": 1
+        }
+    }
+}'
+```
+
+4. 访问验证
+
+使用 HTTP/3 访问 test.com：
+
+- curl 版本 7.88.0+，需要支持 [http-only](https://github.com/curl/curl/blob/master/docs/cmdline-opts/http3-only.md) 选项。
+
+```shell
+curl -k -vvv -H "Host: test.com" -H "content-length: 0" --http3-only --resolve "test.com:9443:127.0.0.1" https://test.com:9443/get
+
+* Added test.com:9443:127.0.0.1 to DNS cache
+* Hostname test.com was found in DNS cache
+*   Trying 127.0.0.1:9443...
+* QUIC cipher selection: TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256
+* Skipped certificate verification
+* Connected to test.com (127.0.0.1) port 9443
+* using HTTP/3
+* [HTTP/3] [0] OPENED stream for https://test.com:9443/get
+* [HTTP/3] [0] [:method: GET]
+* [HTTP/3] [0] [:scheme: https]
+* [HTTP/3] [0] [:authority: test.com]
+* [HTTP/3] [0] [:path: /get]
+* [HTTP/3] [0] [user-agent: curl/8.6.0]
+* [HTTP/3] [0] [accept: */*]
+* [HTTP/3] [0] [content-length: 0]
+> GET /get HTTP/3
+> Host: test.com
+> User-Agent: curl/8.6.0
+> Accept: */*
+> content-length: 0
+>
+< HTTP/3 200
+< content-type: text/plain; charset=utf-8
+< content-length: 28
+< date: Mon, 04 Mar 2024 04:38:42 GMT
+< server: APISIX/3.9.0
+<
+* Connection #0 to host test.com left intact
+```
+
+## 已知问题
+
+- 对于 APISIX-3.9, Tongsuo 相关测试用例会失败，因为 Tongsuo 不支持 QUIC TLS。
+- 对于 HTTP/2 或 HTTP/3 请求，无论您使用哪种 HTTP 方法，请求都应发送 `Content-Length` 头部。
+- APISIX-3.9 基于 NGINX-1.25.3，存在 HTTP/3 漏洞（CVE-2024-24989、CVE-2024-24990）。