Yilialinn commented on code in PR #11850: URL: https://github.com/apache/apisix/pull/11850#discussion_r2000564590
########## docs/en/latest/plugins/response-rewrite.md: ########## @@ -80,175 +79,235 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Rewrite Header and Body + +The following example demonstrates how to add response body and headers, only to responses with `200` HTTP status codes. + +Create a Route with the `response-rewrite` plugin: + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "response-rewrite-route", "methods": ["GET"], - "uri": "/test/index.html", + "uri": "/headers", "plugins": { - "response-rewrite": { - "body": "{\"code\":\"ok\",\"message\":\"new json body\"}", - "headers": { - "set": { - "X-Server-id": 3, - "X-Server-status": "on", - "X-Server-balancer-addr": "$balancer_ip:$balancer_port" - } - }, - "vars":[ - [ "status","==",200 ] - ] - } + "response-rewrite": { + "body": "{\"code\":\"ok\",\"message\":\"new json body\"}", + "headers": { + "set": { + "X-Server-id": 3, + "X-Server-status": "on", + "X-Server-balancer-addr": "$balancer_ip:$balancer_port" + } + }, + "vars": [ + [ "status","==",200 ] + ] + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:80": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' ``` -Here, `vars` is configured to run the Plugin only on responses with a 200 status code. - -Besides `set` operation, you can also `add` or `remove` response header like: - -```json -"headers": { - "add": [ - "X-Server-balancer-addr: $balancer_ip:$balancer_port" - ], - "remove": [ - "X-TO-BE-REMOVED" - ] -} -``` - -The execution order among those operations are ["add", "set", "remove"]. - -If you are using the deprecated `headers` configuration which puts the headers directly under `headers`, -you need to move them to `headers.set`. - -## Example usage - -Once you have enabled the Plugin as shown above, you can make a request: +Send a request to verify: ```shell -curl -X GET -i http://127.0.0.1:9080/test/index.html +curl -i "http://127.0.0.1:9080/headers"; ``` -The response will be as shown below no matter what the response is from the Upstream: +You should receive a `HTTP/1.1 200 OK` response similar to the following: -``` -HTTP/1.1 200 OK -Date: Sat, 16 Nov 2019 09:15:12 GMT -Transfer-Encoding: chunked -Connection: keep-alive +```text +... X-Server-id: 3 X-Server-status: on -X-Server-balancer-addr: 127.0.0.1:80 +X-Server-balancer-addr: 50.237.103.220:80 {"code":"ok","message":"new json body"} ``` -:::info IMPORTANT +### Rewrite Header With RegEx Filter -[ngx.exit](https://openresty-reference.readthedocs.io/en/latest/Lua_Nginx_API/#ngxexit) will interrupt the execution of a request and returns its status code to Nginx. +The following example demonstrates how to use RegEx filter matching to replace `X-Amzn-Trace-Id` for responses. -However, if `ngx.exit` is executed during an access phase, it will only interrupt the request processing phase and the response phase will still continue to run. - -So, if you have configured the `response-rewrite` Plugin, it do a force overwrite of the response. - -| Phase | rewrite | access | header_filter | body_filter | -|---------------|----------|----------|---------------|-------------| -| rewrite | ngx.exit | √ | √ | √ | -| access | × | ngx.exit | √ | √ | -| header_filter | √ | √ | ngx.exit | √ | -| body_filter | √ | √ | × | ngx.exit | - -::: - -The example below shows how you can replace a key in the response body. Here, the key X-Amzn-Trace-Id is replaced with X-Amzn-Trace-Id-Replace by configuring the filters attribute using regex: +Create a Route with the `response-rewrite` plugin: ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "plugins":{ - "response-rewrite":{ - "headers":{ - "set": { - "X-Server-id":3, - "X-Server-status":"on", - "X-Server-balancer-addr":"$balancer_ip:$balancer_port" - } - }, - "filters":[ - { - "regex":"X-Amzn-Trace-Id", - "scope":"global", - "replace":"X-Amzn-Trace-Id-Replace" - } - ], - "vars":[ - [ - "status", - "==", - 200 +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "response-rewrite-route", + "methods": ["GET"], + "uri": "/headers", + "plugins":{ + "response-rewrite":{ + "filters":[ + { + "regex":"X-Amzn-Trace-Id", + "scope":"global", + "replace":"X-Amzn-Trace-Id-Replace" + } ] - ] - } - }, - "upstream":{ - "type":"roundrobin", - "scheme":"https", - "nodes":{ - "httpbin.org:443":1 + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } - }, - "uri":"/*" -}' + }' ``` +Send a request to verify: + ```shell -curl -X GET -i http://127.0.0.1:9080/get +curl -i "http://127.0.0.1:9080/headers"; ``` -```shell -HTTP/1.1 200 OK -Transfer-Encoding: chunked -X-Server-status: on -X-Server-balancer-addr: 34.206.80.189:443 -X-Server-id: 3 +You should see a response similar to the following: +```text { - "args": {}, "headers": { "Accept": "*/*", "Host": "127.0.0.1", - "User-Agent": "curl/7.29.0", - "X-Amzn-Trace-Id-Replace": "Root=1-629e0b89-1e274fdd7c23ca6e64145aa2", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id-Replace": "Root=1-6500095d-1041b05e2ba9c6b37232dbc7", "X-Forwarded-Host": "127.0.0.1" - }, - "origin": "127.0.0.1, 117.136.46.203", - "url": "https://127.0.0.1/get"; + } } - ``` -## Delete Plugin +### Decode Body from Base64 + +The following example demonstrates how to Decode Body from Base64 format. -To remove the `response-rewrite` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. +Create a Route with the `response-rewrite` plugin: ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "response-rewrite-route", "methods": ["GET"], - "uri": "/test/index.html", - "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:80": 1 + "uri": "/get", + "plugins":{ + "response-rewrite": { + "body": "SGVsbG8gV29ybGQ=", + "body_base64": true } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +Send a request to verify: + +```shell +curl "http://127.0.0.1:9080/get"; +``` + +You should see a response of the following: + +```text +Hello World +``` + +### Rewrite Response and Its Connection with Execution Phases + +The following example demonstrates the connection between the `response-rewrite` Plugin and [execution phases](/apisix/key-concepts/plugins#plugins-execution-lifecycle) by configuring the Plugin with the `key-auth` plugin, and see how the response is still rewritten to `200 OK` in the case of an unauthenticated request. + +Create a consumer `jack`: Review Comment: ```suggestion Create a Consumer `jack`: ``` ########## docs/en/latest/plugins/response-rewrite.md: ########## @@ -80,175 +79,235 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Rewrite Header and Body + +The following example demonstrates how to add response body and headers, only to responses with `200` HTTP status codes. + +Create a Route with the `response-rewrite` plugin: + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "response-rewrite-route", "methods": ["GET"], - "uri": "/test/index.html", + "uri": "/headers", "plugins": { - "response-rewrite": { - "body": "{\"code\":\"ok\",\"message\":\"new json body\"}", - "headers": { - "set": { - "X-Server-id": 3, - "X-Server-status": "on", - "X-Server-balancer-addr": "$balancer_ip:$balancer_port" - } - }, - "vars":[ - [ "status","==",200 ] - ] - } + "response-rewrite": { + "body": "{\"code\":\"ok\",\"message\":\"new json body\"}", + "headers": { + "set": { + "X-Server-id": 3, + "X-Server-status": "on", + "X-Server-balancer-addr": "$balancer_ip:$balancer_port" + } + }, + "vars": [ + [ "status","==",200 ] + ] + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:80": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' ``` -Here, `vars` is configured to run the Plugin only on responses with a 200 status code. - -Besides `set` operation, you can also `add` or `remove` response header like: - -```json -"headers": { - "add": [ - "X-Server-balancer-addr: $balancer_ip:$balancer_port" - ], - "remove": [ - "X-TO-BE-REMOVED" - ] -} -``` - -The execution order among those operations are ["add", "set", "remove"]. - -If you are using the deprecated `headers` configuration which puts the headers directly under `headers`, -you need to move them to `headers.set`. - -## Example usage - -Once you have enabled the Plugin as shown above, you can make a request: +Send a request to verify: ```shell -curl -X GET -i http://127.0.0.1:9080/test/index.html +curl -i "http://127.0.0.1:9080/headers"; ``` -The response will be as shown below no matter what the response is from the Upstream: +You should receive a `HTTP/1.1 200 OK` response similar to the following: -``` -HTTP/1.1 200 OK -Date: Sat, 16 Nov 2019 09:15:12 GMT -Transfer-Encoding: chunked -Connection: keep-alive +```text +... X-Server-id: 3 X-Server-status: on -X-Server-balancer-addr: 127.0.0.1:80 +X-Server-balancer-addr: 50.237.103.220:80 {"code":"ok","message":"new json body"} ``` -:::info IMPORTANT +### Rewrite Header With RegEx Filter -[ngx.exit](https://openresty-reference.readthedocs.io/en/latest/Lua_Nginx_API/#ngxexit) will interrupt the execution of a request and returns its status code to Nginx. +The following example demonstrates how to use RegEx filter matching to replace `X-Amzn-Trace-Id` for responses. -However, if `ngx.exit` is executed during an access phase, it will only interrupt the request processing phase and the response phase will still continue to run. - -So, if you have configured the `response-rewrite` Plugin, it do a force overwrite of the response. - -| Phase | rewrite | access | header_filter | body_filter | -|---------------|----------|----------|---------------|-------------| -| rewrite | ngx.exit | √ | √ | √ | -| access | × | ngx.exit | √ | √ | -| header_filter | √ | √ | ngx.exit | √ | -| body_filter | √ | √ | × | ngx.exit | - -::: - -The example below shows how you can replace a key in the response body. Here, the key X-Amzn-Trace-Id is replaced with X-Amzn-Trace-Id-Replace by configuring the filters attribute using regex: +Create a Route with the `response-rewrite` plugin: Review Comment: ```suggestion Create a Route with the `response-rewrite` Plugin: ``` ########## docs/en/latest/plugins/response-rewrite.md: ########## @@ -80,175 +79,235 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Rewrite Header and Body + +The following example demonstrates how to add response body and headers, only to responses with `200` HTTP status codes. + +Create a Route with the `response-rewrite` plugin: + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "response-rewrite-route", "methods": ["GET"], - "uri": "/test/index.html", + "uri": "/headers", "plugins": { - "response-rewrite": { - "body": "{\"code\":\"ok\",\"message\":\"new json body\"}", - "headers": { - "set": { - "X-Server-id": 3, - "X-Server-status": "on", - "X-Server-balancer-addr": "$balancer_ip:$balancer_port" - } - }, - "vars":[ - [ "status","==",200 ] - ] - } + "response-rewrite": { + "body": "{\"code\":\"ok\",\"message\":\"new json body\"}", + "headers": { + "set": { + "X-Server-id": 3, + "X-Server-status": "on", + "X-Server-balancer-addr": "$balancer_ip:$balancer_port" + } + }, + "vars": [ + [ "status","==",200 ] + ] + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:80": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' ``` -Here, `vars` is configured to run the Plugin only on responses with a 200 status code. - -Besides `set` operation, you can also `add` or `remove` response header like: - -```json -"headers": { - "add": [ - "X-Server-balancer-addr: $balancer_ip:$balancer_port" - ], - "remove": [ - "X-TO-BE-REMOVED" - ] -} -``` - -The execution order among those operations are ["add", "set", "remove"]. - -If you are using the deprecated `headers` configuration which puts the headers directly under `headers`, -you need to move them to `headers.set`. - -## Example usage - -Once you have enabled the Plugin as shown above, you can make a request: +Send a request to verify: ```shell -curl -X GET -i http://127.0.0.1:9080/test/index.html +curl -i "http://127.0.0.1:9080/headers"; ``` -The response will be as shown below no matter what the response is from the Upstream: +You should receive a `HTTP/1.1 200 OK` response similar to the following: -``` -HTTP/1.1 200 OK -Date: Sat, 16 Nov 2019 09:15:12 GMT -Transfer-Encoding: chunked -Connection: keep-alive +```text +... X-Server-id: 3 X-Server-status: on -X-Server-balancer-addr: 127.0.0.1:80 +X-Server-balancer-addr: 50.237.103.220:80 {"code":"ok","message":"new json body"} ``` -:::info IMPORTANT +### Rewrite Header With RegEx Filter -[ngx.exit](https://openresty-reference.readthedocs.io/en/latest/Lua_Nginx_API/#ngxexit) will interrupt the execution of a request and returns its status code to Nginx. +The following example demonstrates how to use RegEx filter matching to replace `X-Amzn-Trace-Id` for responses. -However, if `ngx.exit` is executed during an access phase, it will only interrupt the request processing phase and the response phase will still continue to run. - -So, if you have configured the `response-rewrite` Plugin, it do a force overwrite of the response. - -| Phase | rewrite | access | header_filter | body_filter | -|---------------|----------|----------|---------------|-------------| -| rewrite | ngx.exit | √ | √ | √ | -| access | × | ngx.exit | √ | √ | -| header_filter | √ | √ | ngx.exit | √ | -| body_filter | √ | √ | × | ngx.exit | - -::: - -The example below shows how you can replace a key in the response body. Here, the key X-Amzn-Trace-Id is replaced with X-Amzn-Trace-Id-Replace by configuring the filters attribute using regex: +Create a Route with the `response-rewrite` plugin: ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "plugins":{ - "response-rewrite":{ - "headers":{ - "set": { - "X-Server-id":3, - "X-Server-status":"on", - "X-Server-balancer-addr":"$balancer_ip:$balancer_port" - } - }, - "filters":[ - { - "regex":"X-Amzn-Trace-Id", - "scope":"global", - "replace":"X-Amzn-Trace-Id-Replace" - } - ], - "vars":[ - [ - "status", - "==", - 200 +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "response-rewrite-route", + "methods": ["GET"], + "uri": "/headers", + "plugins":{ + "response-rewrite":{ + "filters":[ + { + "regex":"X-Amzn-Trace-Id", + "scope":"global", + "replace":"X-Amzn-Trace-Id-Replace" + } ] - ] - } - }, - "upstream":{ - "type":"roundrobin", - "scheme":"https", - "nodes":{ - "httpbin.org:443":1 + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } - }, - "uri":"/*" -}' + }' ``` +Send a request to verify: + ```shell -curl -X GET -i http://127.0.0.1:9080/get +curl -i "http://127.0.0.1:9080/headers"; ``` -```shell -HTTP/1.1 200 OK -Transfer-Encoding: chunked -X-Server-status: on -X-Server-balancer-addr: 34.206.80.189:443 -X-Server-id: 3 +You should see a response similar to the following: +```text { - "args": {}, "headers": { "Accept": "*/*", "Host": "127.0.0.1", - "User-Agent": "curl/7.29.0", - "X-Amzn-Trace-Id-Replace": "Root=1-629e0b89-1e274fdd7c23ca6e64145aa2", + "User-Agent": "curl/8.2.1", + "X-Amzn-Trace-Id-Replace": "Root=1-6500095d-1041b05e2ba9c6b37232dbc7", "X-Forwarded-Host": "127.0.0.1" - }, - "origin": "127.0.0.1, 117.136.46.203", - "url": "https://127.0.0.1/get"; + } } - ``` -## Delete Plugin +### Decode Body from Base64 + +The following example demonstrates how to Decode Body from Base64 format. -To remove the `response-rewrite` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. +Create a Route with the `response-rewrite` plugin: Review Comment: ```suggestion Create a Route with the `response-rewrite` Plugin: ``` -- 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. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
