nic-6443 commented on code in PR #14156: URL: https://github.com/apache/apisix/pull/14156#discussion_r4476328799
########## docs/en/latest/terminology/plugin.md: ########## @@ -311,6 +312,70 @@ curl -v /dev/null http://127.0.0.1:9080/get?version=v2 -H"host:httpbin.org" } ``` +### Evaluate the filter in a later phase + +By default, `filter` is evaluated once per request, at the first function the plugin has for that request, and that decision applies to all the plugin's later functions. For a plugin with an `access` function, such as the logger plugins, the decision is therefore made before the request is proxied, when `status` and `upstream_status` have no value yet. + +`filter_phase` names the phase at which the decision is made: + +- A plugin function in a phase earlier than `filter_phase` always runs, whatever the filter would say. +- At `filter_phase` or at the first later phase in which the plugin has a function, the filter is evaluated. The decision is kept for the rest of the request, like a decision made without `filter_phase`. +- If the request does not reach that phase, the decision is made at the next phase that runs. For example, a `HEAD` request has no `body_filter`, so `filter_phase` set to `body_filter` decides at `log`. +- On a stream route, which runs `preread`, `before_proxy` and `log`, a `filter_phase` of `rewrite` or `access` decides at `preread`, and `header_filter` or `body_filter` decides at `log`. + +The configuration is rejected if the plugin has no function at or after `filter_phase`, as the filter would never be evaluated, or if `filter` is missing. Without `filter_phase`, nothing changes. + +The following configuration logs every response except a 404 generated by APISIX or one of its plugins, and keeps a 404 returned by the upstream: + +```json +{ + "file-logger": { + "path": "logs/file.log", + "include_resp_body": true, + "_meta": { + "filter": ["OR", ["status", "~=", 404], ["upstream_status", "==", 404]], Review Comment: Right, a retried request has `upstream_status` as a list such as `502, 404`, so `== 404` would drop it. The doc example now uses `["upstream_status", "~~", "404$"]` in both languages and explains why, and TEST 16 in `t/plugin/meta-filter-phase.t` covers the retry case. -- 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]
