[GitHub] [apisix-java-plugin-runner] tzssangglass commented on a change in pull request #19: docs: add the-internal-of-apisix-java-plugin-runner.md, development.md and how-it-works.md

[GitBox <gi...@apache.org>]

tzssangglass commented on a change in pull request #19:
URL: https://github.com/apache/apisix-java-plugin-runner/pull/19#discussion_r642181375



##########
File path: docs/how-it-works.md
##########
@@ -0,0 +1,86 @@
+# How It Works
+
+This article explains how apisix-java-plugin-runner collaborate with [Apache APISIX](https://apisix.apache.org) to run plugins written in java.
+
+## Run Mode
+
+apisix-java-plugin-runner can be run alone or bundled with Apache APISIX.
+It depends on whether you need to debug it or run it.
+
+### Debug
+
+If you are developing a new plugin and need to debug the code, then you can run the main class
+[PluginRunnerApplication](https://github.com/apache/apisix-java-plugin-runner/blob/main/runner-starter/src/main/java/org/apache/apisix/plugin/runner/PluginRunnerApplication.java),
+and before start, you need to set the following two environment variables:
+
+- APISIX_LISTEN_ADDRESS: apisix-java-plugin-runner and APISIX for inter-process communication (Unix Domain Socket) socket type file address.
+  And do not need to actively create this file, apisix-java-plugin-runner will automatically create this file when it starts.
+- APISIX_CONF_EXPIRE_TIME: the time that APISIX's configuration is cached in the apisix-java-plugin-runner process.
+
+For example, if you start apisix-java-plugin-runner as a jar package, pass the environment variables as follows
+
+```shell
+java -jar -DAPISIX_LISTEN_ADDRESS=/tmp/runner.sock -DAPISIX_CONF_EXPIRE_TIME=3600 /path/to/apisix-java-plugin-runner.jar
+```
+
+and add the following configure in the `config.yaml` file of APISIX
+
+```yaml
+ext-plugin:
+  path_for_test: /tmp/runner.sock
+  cmd: ['echo', 'call runner']
+```
+
+The `/tmp/runner.sock` is the address of the file where apisix-java-plugin-runner  
+and APISIX communicate between processes and must be consistent.
+
+Note: If you see some error logs like
+
+```
+phase_func(): failed to connect to the unix socket unix:/tmp/runner.sock: permission denied

Review comment:
       runner has permission to the sock file, but APISIX does not, the permission denied log will appear in the APISIX error.log




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org