[apisix] branch master updated: docs(extern-plugin): the implementation of runner (#6336)

[sp...@apache.org]

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 42e84e4  docs(extern-plugin): the implementation of runner (#6336)
42e84e4 is described below

commit 42e84e437fa532f24523f5b38015436e1fcc013f
Author: 罗泽轩 <sp...@gmail.com>
AuthorDate: Mon Feb 21 09:54:33 2022 +0800

    docs(extern-plugin): the implementation of runner (#6336)
---
 docs/en/latest/config.json               |  1 +
 docs/en/latest/external-plugin.md        |  4 ++
 docs/en/latest/internal/plugin-runner.md | 78 ++++++++++++++++++++++++++++++++
 docs/zh/latest/external-plugin.md        |  5 ++
 4 files changed, 88 insertions(+)

diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index b93a9ed..2ffbf81 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -278,6 +278,7 @@
           "type": "category",
           "label": "internal",
           "items": [
+            "internal/plugin-runner",
             "internal/testing-framework"
           ]
         },
diff --git a/docs/en/latest/external-plugin.md b/docs/en/latest/external-plugin.md
index 4c620c4..8094f10 100644
--- a/docs/en/latest/external-plugin.md
+++ b/docs/en/latest/external-plugin.md
@@ -47,6 +47,10 @@ run external plugins and return the result back to APISIX.
 The target external plugins and the execution order are configured in the `ext-plugin-*`
 plugins. Like other plugins, they can be enabled and reconfigured on the fly.
 
+## How is it implemented
+
+If you are instested in the implementation of Plugin Runner, please refer to [The Implementation of Plugin Runner](./internal/plugin-runner.md).
+
 ## Supported plugin runners
 
 - Java: https://github.com/apache/apisix-java-plugin-runner
diff --git a/docs/en/latest/internal/plugin-runner.md b/docs/en/latest/internal/plugin-runner.md
new file mode 100644
index 0000000..4117187
--- /dev/null
+++ b/docs/en/latest/internal/plugin-runner.md
@@ -0,0 +1,78 @@
+---
+title: The Implementation of Plugin Runner
+---
+
+<!--
+#
+# 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.
+#
+-->
+
+## Prerequirement
+
+Each request which runs the extern plugin will trigger an RPC to Plugin Runner over a connection on Unix socket. The data of RPC are serialized with [Flatbuffers](https://github.com/google/flatbuffers).
+
+Therefore, the Plugin Runner needs to:
+
+1. handle a connection on Unix socket
+2. support Flatbuffers
+3. use the proto & generated code in https://github.com/api7/ext-plugin-proto/
+
+## Listening to the Path
+
+APISIX will pass the path of Unix socket as an environment variable `APISIX_LISTEN_ADDRESS` to the Plugin Runner. So the runner needs to read the value and listen to that address during starting.
+
+## Register Plugins
+
+The Plugin Runner should be able to load plugins written in the particular language.
+
+## Handle RPC
+
+There are two kinds of RPC: PrepareConf & HTTPReqCall
+
+### Handle PrepareConf
+
+As people can configure the extern plugin on the side of APISIX, we need a way to sync the plugin configuration to the Plugin Runner.
+
+When there is a configuration that needs to sync to the Plugin Runner, we will send it via the PrepareConf RPC call. The Plugin Runner should be able to handle the call and store the configuration in a cache, then returns a unique conf token that represents the configuration.
+
+In the previous design, an idempotent key is sent with the configuration. This field is deprecated and the Plugin Runner can safely ignore it.
+
+Requests run plugins with particular configuration will bear a particular conf token in the RPC call, and the Plugin Runner is expected to look up actual configuration via the token.
+
+When the configuration is modified, APISIX will send a new PrepareConf to the Plugin Runner. Currently, there is no way to notify the Plugin Runner that a configuration is removed. Therefore, we introduce another environment variable `APISIX_CONF_EXPIRE_TIME` as the conf cache expire time. The Plugin Runner should be able to cache the conf slightly longer than `APISIX_CONF_EXPIRE_TIME`, and APISIX will send another PrepareConf to refresh the cache if the configuration is still existing a [...]
+
+### Handle HTTPReqCall
+
+Each request which runs the extern plugin will trigger the HTTPReqCall. The HTTPReqCall is almost a serialized version of HTTP request, plus a conf token. The Plugin Runner is expected to tell APISIX what to update by the response of HTTPReqCall RPC call.
+
+Sometimes the plugin in the Plugin Runner needs to know some information that is not part of the HTTPReqCall request, such as the request start time and the route ID in APISIX. Hence the Plugin Runner needs to reply to an `ExtraInfo` message as the response on the connection which sends the HTTPReqCall request. APISIX will read the `ExtraInfo` message and return the asked information.
+
+Currently, the information below is passed by `ExtraInfo`:
+
+* variable value
+* request body
+
+The flow of HTTPReqCall procession is:
+
+```
+APISIX sends HTTPReqCall
+Plugin Runner looks up the plugin configuration by the token in HTTPReqCall
+(optional) loop:
+    Plugin Runner asks for ExtraInfo
+    APISIX replies the ExtraInfo
+Plugin Runner replies HTTPReqCall
+```
diff --git a/docs/zh/latest/external-plugin.md b/docs/zh/latest/external-plugin.md
index e02538e..3e8049f 100644
--- a/docs/zh/latest/external-plugin.md
+++ b/docs/zh/latest/external-plugin.md
@@ -41,6 +41,11 @@ APISIX 支持使用 Lua 语言编写插件，这种类型的插件在 APISIX 内
 
  External Plugin 及其执行顺序在这里 `ext-plugin-*` 配置。与其他插件一样， External Plugin 可以动态启用和重新配置。
 
+## 它是如何实现的
+
+如果你对 Plugin Runner 内部实现感兴趣，请参考这份文档：
+[The Implementation of Plugin Runner](../../en/latest/internal/plugin-runner.md)
+
 ## 支持的 Plugin Runner
 
 - Java: https://github.com/apache/apisix-java-plugin-runner