This is an automated email from the ASF dual-hosted git repository.
spacewander 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 c80a4959f docs(xRPC): add the main entry (#6956)
c80a4959f is described below
commit c80a4959f9bffee68d91ba9aee3e6899fd3d37a9
Author: 罗泽轩 <[email protected]>
AuthorDate: Fri Apr 29 14:12:46 2022 +0800
docs(xRPC): add the main entry (#6956)
Co-authored-by: 琚致远 <[email protected]>
Co-authored-by: tzssangglass <[email protected]>
---
docs/en/latest/config.json | 7 +++
docs/en/latest/xrpc.md | 145 +++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 152 insertions(+)
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index 6ea5784bd..6991ee3cb 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -212,6 +212,13 @@
"discovery/kubernetes"
]
},
+ {
+ "type": "category",
+ "label": "xRPC",
+ "items": [
+ "xrpc"
+ ]
+ },
{
"type": "doc",
"id": "health-check"
diff --git a/docs/en/latest/xrpc.md b/docs/en/latest/xrpc.md
new file mode 100644
index 000000000..1fb2a5159
--- /dev/null
+++ b/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
