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-go-plugin-runner.git
The following commit(s) were added to refs/heads/master by this push:
new 413b903 docs: update README details (#80)
413b903 is described below
commit 413b90306370882b7d271e57b526fb501f819617
Author: Sylvia <[email protected]>
AuthorDate: Tue Apr 26 09:39:27 2022 +0800
docs: update README details (#80)
---
README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 77 insertions(+), 2 deletions(-)
diff --git a/README.md b/README.md
index c123294..43de32c 100644
--- a/README.md
+++ b/README.md
@@ -24,5 +24,80 @@
[](https://codecov.io/gh/apache/apisix-go-plugin-runner)
[](https://pkg.go.dev/github.com/apache/apisix-go-plugin-runner)
-The documentation can be found in this
[website](http://apisix.apache.org/docs/go-plugin-runner/getting-started),
-which is generated from the files under `docs/`.
+Runs [Apache APISIX](http://apisix.apache.org/) plugins written in Go.
Implemented as a sidecar that accompanies APISIX.
+
+## Status
+
+This project is currently considered experimental.
+
+## Why apisix-go-plugin-runner
+
+Apache APISIX offers many full-featured plugins covering areas such as
authentication, security, traffic control, serverless, analytics & monitoring,
transformations, logging.
+
+It also provides highly extensible API, allowing common phases to be mounted,
and users can use these API to develop their own plugins.
+
+This project is APISIX Go side implementation that supports writing plugins in
Go.
+
+Currently, Go Plugin Runner is provided as a library. This is because the
convention of Go is to compile all the code into an executable file.
+
+Although there is a mechanism for Go Plugin to compile the plugin code into a
dynamic link library and then load it into the binary. But as far as experience
is concerned, there are still some imperfections that are not so simple and
direct to use.
+
+The structure of the apache/apisix-go-plugin-runner repository on GitHub is as
follows:
+
+```
+.
+├── cmd
+├── internal
+├── pkg
+```
+
+`internal` is responsible for the internal implementation, `pkg` displays the
external interface, and `cmd` provides examples of the demonstration.
+There is a subdirectory of `go-runner` under the `cmd` directory. By reading
the code in this section, you can learn how to use Go Plugin Runner in
practical applications.
+
+## How it Works
+
+At present, the communication between Go Plugin Runner and Apache APISIX is an
RPC based on Unix socket. So Go Plugin Runner and Apache APISIX need to be
deployed on the same machine.
+
+### Enable Go Plugin Runner
+
+As mentioned earlier, Go Plugin Runner is managed by Apache APISIX, which runs
as a child process of APISIX. So we have to configure and run this Runner in
Apache APISIX.
+
+The following configuration process will take the code `cmd/go-runner` in the
`apisix-go-plugin-runner` project as an example.
+
+1. Compile the sample code. Executing `make build` generates the executable
file go-runner.
+2. Make the following configuration in the conf/config.yaml file of Apache
APISIX:
+
+```yaml
+ext-plugin:
+ cmd: ["/path/to/apisix-go-plugin-runner/go-runner", "run"]
+```
+
+With the above configuration, Apache APISIX pulls up `go-runner` when it
starts and closes `go-runner` when it stops.
+
+In view of the fact that `apisix-go-plugin-runner` is used in the form of a
library in the actual development process, you need to replace the above
example configuration with your own executable and startup instructions.
+
+Finally, after the startup of Apache APISIX, `go-runner` will be started along
with it.
+
+### Other configuration methods
+
+Of course, if you need to take these three steps every time you verify the
functionality in the development process, it is quite tedious. So we also
provide another configuration that allows apisix-go-plugin-runner to run
independently during development.
+
+1. The first thing to do is to compile the code.
+2. Configure the following in the conf/config.yaml file of Apache APISIX:
+
+```yaml
+ext-plugin:
+ path_for_test: /tmp/runner.sock
+```
+
+3. Start `go-runner` with the following code.
+
+```
+APISIX_LISTEN_ADDRESS=unix:/tmp/runner.sock ./go-runner run
+```
+
+Notice that we specify the socket address to be used for `go-runner`
communication through the environment variable `APISIX_LISTEN_ADDRESS`. This
address needs to be consistent with the configuration in Apache APISIX.
+
+## License
+
+Apache 2.0 LICENSE
