docs(xRPC): add the main entry (#6956)

Co-authored-by: 琚致远 <juzhiyuan@apache.org>
Co-authored-by: tzssangglass <tzssangglass@gmail.com>

docs/en/latest/config.json

@@ -212,6 +212,13 @@
             "discovery/kubernetes"
           ]
         },
+        {
+          "type": "category",
+          "label": "xRPC",
+          "items": [
+            "xrpc"
+          ]
+        },
         {
           "type": "doc",
           "id": "health-check"

docs/en/latest/xrpc.md

@@ -0,0 +1,145 @@
+---
+title: xRPC
+---
+
+<!--
+#
+# 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.
+#
+-->
+
+## What is xRPC
+
+APISIX supports proxy TCP protocols, but there are times when a pure TCP protocol proxy is not enough. It would help if you had an application-specific proxy, such as Redis Proxy, Kafka Proxy, etc. In addition, some features must be coded and decoded for that protocol before they can be implemented.
+
+Therefore, Apache APISIX implements an L4 protocol extension framework called xRPC that allows developers to customize application-specific protocols. Based on xRPC, developers can codec requests and responses through Lua code and then implement fault injection, log reporting, dynamic routing, and other functions based on understanding the protocol content.
+
+Based on the xRPC framework, APISIX can provide a proxy implementation of several major application protocols. In addition, users can also support their own private TCP-based application protocols based on this framework, giving them precise granularity and higher-level 7-layer control similar to HTTP protocol proxies.
+
+## How to use
+
+Currently, the steps for users to use xRPC are relatively simple and can be handled quickly in just two steps.
+
+1. First, enable the corresponding protocol in `conf/config.yaml`.
+
+```yaml
+xrpc:
+  protocols:
+    - name: redis
+```
+
+2. Then specify the protocol in the relevant `stream_routes`.
+
+```json
+{
+    ...
+    "protocol": {
+        "name": "redis",
+        "conf": {
+            "faults": [
+                { "delay": 5, "key": "bogus_key", "commands":["GET", "MGET"]}
+            ]
+        }
+    }
+}
+```
+
+The TCP connection that hits that `stream_route` is then handled according to that protocol.
+
+## Configuration
+
+| Name        | Type   | Required | Default | Description                                     |
+|-------------|--------|----------|---------|-------------------------------------------------|
+| name        | string | True     |         | the protocol name                               |
+| conf        |        | False    |         | the application-specific protocol configuration |
+| superior_id | ID     | False    |         | the ID of the superior stream route             |
+
+## Scenarios
+
+### Fault injection
+
+Taking Redis protocol as an example, after decoding the RESP protocol of Redis, we can know the command and parameters of the current request and then get the corresponding content according to the configuration, encode it using RESP protocol, and return it to the client.
+
+Suppose the user uses the following routing configuration.
+
+```json
+{
+    ...
+    "protocol": {
+        "name": "redis",
+        "conf": {
+            "faults": [
+                { "delay": 5, "key": "bogus_key", "commands":["GET", "MGET"]}
+            ]
+        }
+    }
+}
+```
+
+Then when the command is "GET" or "MGET", and the operation key contains "bogus_key", it will get "delay" according to the configuration: "5" parameter, and the corresponding operation will be performed with a delay of 5 seconds.
+
+Since xRPC requires developers to codec the protocol when customizing it, the same operation can be applied to other protocols.
+
+### Dynamic Routing
+
+In the process of proxy RPC protocol, there are often different RPC calls that need to be forwarded to different upstream requirements. Therefore, the xRPC framework has built-in support for dynamic routing.
+
+To solve this problem, the concept of superior and subordinate is used in xRPC routing, as shown in the following two examples.
+
+```json
+# /stream_routes/1
+{
+    "sni": "a.test.com",
+    "protocol": {
+        "name": "xx",
+        "conf": {
+            ...
+        }
+    },
+    "upstream_id": "1"
+}
+```
+
+```json
+# /stream_routes/2
+{
+    "protocol": {
+        "name": "xx",
+        "superior_id": "1",
+        "conf": {
+            ...
+        }
+    },
+    "upstream_id": "2"
+}
+```
+
+One specifies the `superior_id`, whose corresponding value is the ID of another route; the other specifies that the route with the `superior_id` is a subordinate route, subordinate to the one with the `superior_id`. Only the superior route is involved in matching at the entry point. The subordinate route is then matched by the specific protocol when the request is decoded.
+
+For example, for the Dubbo RPC protocol, the subordinate route is matched based on the service_name and other parameters configured in the route and the actual service_name brought in the request. If the match is successful, the configuration above the subordinate route is used, otherwise the configuration of the superior route is still used. In the above example, if the match for route 2 is successful, it will be forwarded to upstream 2; otherwise, it will still be forwarded to upstream 1.
+
+## How to write your own protocol
+
+Assuming that your protocol is named `my_proto`, you need to create a directory that can be introduced by `require "apisix.stream.xrpc.protocols.my_proto"`.
+Inside this directory you need to have two files, `init.lua`, which implements the methods required by the xRPC framework, and `schema.lua`, which implements the schema checks for the protocol configuration.
+
+For a concrete implementation, you can refer to the existing protocols at:
+
+* https://github.com/apache/apisix/tree/master/apisix/stream/xrpc/protocols
+* https://github.com/apache/apisix/tree/master/t/xrpc/apisix/stream/xrpc/protocols
+
+To know what methods are required to be implemented and how the xRPC framework works, please refer to:
+https://github.com/apache/apisix/tree/master/apisix/stream/xrpc/runner.lua