You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by "kayx23 (via GitHub)" <gi...@apache.org> on 2024/12/23 09:52:56 UTC
[PR] docs: improve `response-rewrite` plugin docs [apisix]
kayx23 opened a new pull request, #11850:
URL: https://github.com/apache/apisix/pull/11850
### Description
Improve `response-rewrite` plugin docs.
### Checklist
- [x] I have explained the need for this PR and the problem it solves
- [x] I have explained the changes or the new features added to this PR
- [ ] I have added tests corresponding to this change
- [x] I have updated the documentation to reflect this change
- [ ] I have verified that this change is backward compatible (If not, please discuss on the [APISIX mailing list](https://github.com/apache/apisix/tree/master#community) first)
<!--
Note
1. Mark the PR as draft until it's ready to be reviewed.
2. Always add/update tests for any changes unless you have a good reason.
3. Always update the documentation to reflect the changes made in the PR.
4. Make a new commit to resolve conversations instead of `push -f`.
5. To resolve merge conflicts, merge master instead of rebasing.
6. Use "request review" to notify the reviewer after making changes.
7. Only a reviewer can mark a conversation as resolved.
-->
--
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: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: improve `response-rewrite` plugin docs [apisix]
Posted by "kayx23 (via GitHub)" <gi...@apache.org>.
kayx23 merged PR #11850:
URL: https://github.com/apache/apisix/pull/11850
--
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: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: improve `response-rewrite` plugin docs [apisix]
Posted by "Yilialinn (via GitHub)" <gi...@apache.org>.
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: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org