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-python-plugin-runner.git
The following commit(s) were added to refs/heads/master by this push:
new 9f5c373 docs: add getting started and developer guide document (#18)
9f5c373 is described below
commit 9f5c373b3d11544ac93ea7fe2525732ee849a4ce
Author: 帅进超 <[email protected]>
AuthorDate: Mon Aug 16 09:45:57 2021 +0800
docs: add getting started and developer guide document (#18)
---
README.md | 37 ++++++
.../images/apisix-plugin-runner-overview.png | Bin 0 -> 516068 bytes
docs/en/latest/developer-guide.md | 96 ++++++++++++++++
docs/en/latest/getting-started.md | 124 +++++++++++++++++++++
4 files changed, 257 insertions(+)
diff --git a/README.md b/README.md
index 0793576..014165a 100644
--- a/README.md
+++ b/README.md
@@ -19,3 +19,40 @@
# Python Plugin Runner for Apache APISIX
+[](https://github.com/apache/apisix-python-plugin-runner/actions)
+[](https://github.com/apache/apisix-python-plugin-runner/actions)
+
+Runs [Apache APISIX](http://apisix.apache.org/) plugins written in Python.
Implemented as a sidecar that accompanies
+APISIX.
+
+
+
+# Why apisix-python-plugin-runner
+
+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.
+
+APISIX supports writing plugins in multiple languages in
+version
[2.7.0](https://github.com/apache/apisix/blob/master/CHANGELOG.md#270), this
project is APISIX Python side
+implementation that supports writing plugins in Python.
+
+# Use apisix-python-plugin-runner
+
+For configuration and use, please refer to the [Getting
Started](./docs/en/latest/getting-started.md) document.
+
+# Get Involved in Development
+
+Welcome to make contributions, but before you start, please check out
+[Developer Guide](./docs/en/latest/developer-guide.md) to learn how to run and
debug `apisix-python-plugin-runner`
+in your own environment.
+
+# Status
+
+This project is currently in the experimental stage and it is not recommended
to be used in a production environment.
+
+# License
+
+[Apache 2.0 LICENSE](./LICENSE)
\ No newline at end of file
diff --git a/docs/assets/images/apisix-plugin-runner-overview.png
b/docs/assets/images/apisix-plugin-runner-overview.png
new file mode 100644
index 0000000..702a09d
Binary files /dev/null and
b/docs/assets/images/apisix-plugin-runner-overview.png differ
diff --git a/docs/en/latest/developer-guide.md
b/docs/en/latest/developer-guide.md
new file mode 100644
index 0000000..2d1efb8
--- /dev/null
+++ b/docs/en/latest/developer-guide.md
@@ -0,0 +1,96 @@
+---
+title: Developer Guide
+---
+
+<!--
+#
+# 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.
+#
+-->
+
+## Overview
+
+This documentation explains how to develop this project.
+
+
+## Prerequisites
+
+* Python 3.6+
+* APISIX 2.7.0
+
+
+## Debug
+
+- Run `make setup` Installation dependencies
+- Run `export PYTHONPATH=$PYTHONPATH:/path/to/apisix-python-plugin-runner`
loading project path
+- Run `APISIX_LISTEN_ADDRESS=unix:/tmp/runner.sock python3 apisix/main.py
start`
+to start it.
+
+
+## Plugin
+
+#### Plugin directory
+```
+/path/to/apisix-python-plugin-runner/apisix/plugin
+```
+the `.py` files in this directory autoload
+
+
+#### Plugin example
+```
+/path/to/apisix-python-plugin-runner/apisix/plugin/say.py
+```
+
+#### Plugin Format
+```python
+from apisix.runner.plugin.base import Base
+from apisix.runner.http.request import Request
+from apisix.runner.http.response import Response
+
+
+class Say(Base):
+ def __init__(self):
+ super(Say, self).__init__(self.__class__.__name__)
+
+ def filter(self, request: Request, response: Response):
+ headers = request.headers
+ headers["X-Resp-A6-Runner"] = "Python"
+ response.body = "Hello, Python Runner of APISIX"
+ response.headers = headers
+```
+- The plugin must inherit the `Base` class
+- The plugin must implement the `filter` function
+- `filter` function parameters can only contain `Request` and `Response`
classes as parameters
+- Request parameter can get request information
+- Response parameter can set response information
+- `self.config` can get plug-in configuration information
+
+
+## Test
+
+Run `make test`.
+
+
+## Data Format
+
+[FlatBuffers](https://github.com/google/flatbuffers)
+
+
+## Data Protocol
+
+```
+1 byte of type + 3 bytes of length + data
+```
diff --git a/docs/en/latest/getting-started.md
b/docs/en/latest/getting-started.md
new file mode 100644
index 0000000..1550e46
--- /dev/null
+++ b/docs/en/latest/getting-started.md
@@ -0,0 +1,124 @@
+---
+title: Getting started
+---
+
+<!--
+#
+# 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.
+#
+-->
+
+## Overview
+This document explains how to use Python Runner
+
+## Prerequisites
+
+* Python 3.6+
+* APISIX 2.7.0
+
+
+## Installation
+
+```bash
+$ git clone https://github.com/apache/apisix-python-plugin-runner.git
+$ cd apisix-python-plugin-runner
+$ make install
+```
+
+## Launch
+
+### Configuration Python Runner
+
+> Development Mode
+
+#### Run APISIX Python Runner
+```bash
+$ cd /path/to/apisix-python-plugin-runner
+$ APISIX_LISTEN_ADDRESS=unix:/tmp/runner.sock python3 apisix/main.py start
+```
+
+#### Modify APISIX configuration file
+```bash
+$ vim /path/to/apisix/conf/config.yaml
+apisix:
+ admin_key:
+ - name: "admin"
+ key: edd1c9f034335f136f87ad84b625c8f1
+ role: admin
+ext-plugin:
+ path_for_test: /tmp/runner.sock
+```
+
+> Production Mode
+
+#### Modify APISIX configuration file
+```bash
+$ vim /path/to/apisix/conf/config.yaml
+apisix:
+ admin_key:
+ - name: "admin"
+ key: edd1c9f034335f136f87ad84b625c8f1
+ role: admin
+ext-plugin:
+ cmd: [ "python3",
"/path/to/apache/apisix-python-plugin-runner/apisix/main.py", "start" ]
+```
+
+### Start or Restart APISIX
+```bash
+$ cd /path/to/apisix
+# Start or Restart
+$ ./bin/apisix [ start | restart ]
+```
+
+### Configure APISIX Routing Rule
+```bash
+$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/get",
+ "plugins": {
+ "ext-plugin-pre-req": {
+ "conf": [
+ { "name": "say", "value":"{\"body\":\"hello\"}"}
+ ]
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ }
+}
+'
+```
+
+
+# Testing
+```bash
+$ curl http://127.0.0.1:9080/get -i
+HTTP/1.1 200 OK
+Date: Fri, 13 Aug 2021 13:39:18 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+host: 127.0.0.1:9080
+accept: */*
+user-agent: curl/7.64.1
+X-Resp-A6-Runner: Python
+Server: APISIX/2.7
+
+Hello, Python Runner of APISIX
+```
