[apisix-go-plugin-runner] branch master updated: docs: add response filter for doc (#93)

[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-go-plugin-runner.git


The following commit(s) were added to refs/heads/master by this push:
     new 7b748eb  docs: add response filter for doc (#93)
7b748eb is described below

commit 7b748eb9e5f485400dd077a529ee28bb9c5866de
Author: soulbird <zh...@outlook.com>
AuthorDate: Wed Jun 22 17:51:36 2022 +0800

    docs: add response filter for doc (#93)
---
 docs/assets/images/runner-overview.png | Bin 524459 -> 229694 bytes
 docs/en/latest/getting-started.md      |  44 ++++++++++++++++++++++++++++++---
 2 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/docs/assets/images/runner-overview.png b/docs/assets/images/runner-overview.png
index 3f6f391..11981a0 100644
Binary files a/docs/assets/images/runner-overview.png and b/docs/assets/images/runner-overview.png differ
diff --git a/docs/en/latest/getting-started.md b/docs/en/latest/getting-started.md
index e06fc5a..7bf8c7e 100644
--- a/docs/en/latest/getting-started.md
+++ b/docs/en/latest/getting-started.md
@@ -132,8 +132,43 @@ We can see that the RequestFilter takes the value of the body set in the configu
 (respond directly in the plugin), it will response directly in the APISIX without touching the upstream. We can also set response headers in the plugin and touch the upstream
 at the same time by set RespHeader in `pkgHTTP.Request`.
 
-For the `pkgHTTP.Request`, you can refer to the API documentation provided by the Go Runner SDK:
-https://pkg.go.dev/github.com/apache/apisix-go-plugin-runner
+`ResponseFilter` supports rewriting the response during the response phase, we can see an example of its use in the ResponseRewrite plugin:
+
+```go
+type ResponseRewriteConf struct {
+    Status  int               `json:"status"`
+    Headers map[string]string `json:"headers"`
+    Body    string            `json:"body"`
+}
+
+func (p *ResponseRewrite) ResponseFilter(conf interface{}, w pkgHTTP.Response) {
+	cfg := conf.(ResponseRewriteConf)
+	if cfg.Status > 0 {
+		w.WriteHeader(200)
+	}
+
+	w.Header().Set("X-Resp-A6-Runner", "Go")
+	if len(cfg.Headers) > 0 {
+		for k, v := range cfg.Headers {
+			w.Header().Set(k, v)
+		}
+	}
+
+	if len(cfg.Body) == 0 {
+		return
+	}
+	_, err := w.Write([]byte(cfg.Body))
+	if err != nil {
+		log.Errorf("failed to write: %s", err)
+	}
+}
+```
+
+We can see that `ResponseFilter` will rewrite the status, header, and response body of the response phase according to the configuration.
+
+In addition, we can also get the status and headers in the original response through `pkgHTTP.Response`.
+
+For the `pkgHTTP.Request` and `pkgHTTP.Response`, you can refer to the [API documentation](https://pkg.go.dev/github.com/apache/apisix-go-plugin-runner) provided by the Go Runner SDK.
 
 After building the application (`make build` in the example), we need to set some environment variables at runtime:
 
@@ -159,8 +194,9 @@ When you configure a plugin runner in APISIX, APISIX will treat the plugin runne
 
 If you configure the ext-plugin-* plugin for a given route, a request to hit that route will trigger APISIX to make an RPC call to the plugin runner via a unix socket. The call is broken down into two phases.
 
-- ext-plugin-pre-req: before executing most of the APISIX built-in plugins (Lua language plugins)
-- ext-plugin-post-req: after the execution of the APISIX built-in plugins (Lua language plugins)
+- ext-plugin-pre-req: executed during handling the request, before most of the APISIX built-in plugins (Lua language plugins)
+- ext-plugin-post-req: executed during handling the request, after most of the APISIX built-in plugins (Lua language plugins)
+- ext-plugin-post-resp: executed during handling the response, after most of the APISIX built-in plugins (Lua language plugins)
 
 Configure the timing of plugin runner execution as needed.