This is an automated email from the ASF dual-hosted git repository.
moonming pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 7769478b3f docs: correct real-ip and fault-injection behavior (#14060)
7769478b3f is described below
commit 7769478b3f55526a4292ed0c65758d810c58d6bd
Author: Traky Deng <[email protected]>
AuthorDate: Tue Nov 10 14:25:50 2026 +0800
docs: correct real-ip and fault-injection behavior (#14060)
Signed-off-by: kayx23 <[email protected]>
---
docs/en/latest/plugins/exit-transformer.md | 2 ++
docs/en/latest/plugins/fault-injection.md | 4 ++--
docs/en/latest/plugins/real-ip.md | 4 ++--
3 files changed, 6 insertions(+), 4 deletions(-)
diff --git a/docs/en/latest/plugins/exit-transformer.md
b/docs/en/latest/plugins/exit-transformer.md
index b36417ac1f..24911b0d2b 100644
--- a/docs/en/latest/plugins/exit-transformer.md
+++ b/docs/en/latest/plugins/exit-transformer.md
@@ -38,6 +38,8 @@ The `exit-transformer` Plugin intercepts responses generated
by APISIX itself
The Plugin registers callbacks that are invoked when `core.response.exit()` is
called, receiving the response `(status_code, body, headers)` as arguments and
returning the (possibly modified) values. Multiple functions can be chained,
and each function's output becomes the next function's input.
+Plugin priorities determine order only within the same phase and execution
pass. Rewrite handlers run before access handlers, and global-rule Plugins run
in a separate pass from Route or Service Plugins. `_meta.priority` can override
a Plugin's default priority. The `exit-transformer` rewrite handler defaults to
`22950`, below rewrite handlers such as `real-ip` at `23000`. A response
returned before `exit-transformer` registers its callbacks is not transformed.
Review the [Plugin executi [...]
+
:::note
This Plugin only transforms responses generated by APISIX's own
`core.response.exit()` mechanism. It does **not** transform responses that
originate from upstream services.
diff --git a/docs/en/latest/plugins/fault-injection.md
b/docs/en/latest/plugins/fault-injection.md
index ba6724c3d8..48ea730838 100644
--- a/docs/en/latest/plugins/fault-injection.md
+++ b/docs/en/latest/plugins/fault-injection.md
@@ -34,11 +34,11 @@ description: The fault-injection Plugin tests application
resiliency by simulati
## Description
-The `fault-injection` Plugin is designed to test your application's resiliency
by simulating controlled faults or delays. It executes before other configured
Plugins, ensuring that faults are applied consistently. This makes it ideal for
scenarios like chaos engineering, where the behavior of your system under
failure conditions is analyzed.
+The `fault-injection` Plugin tests your application's resiliency by simulating
controlled faults or delays. It runs in the rewrite phase. Within the same
rewrite execution pass, Plugins run in descending priority order, and
`_meta.priority` can override a Plugin's default priority. The
`fault-injection` default of `11000` places it before lower-priority rewrite
handlers and after higher-priority rewrite handlers in that pass. Global-rule
Plugins and Route or Service Plugins run in separa [...]
The Plugin supports two key actions:
-- `abort`: immediately terminates a request with a specified HTTP status code
(e.g., `503 Service Unavailable`), skipping all subsequent Plugins.
+- `abort`: immediately ends request processing with a specified HTTP status
code (e.g., `503 Service Unavailable`), so later rewrite and access handlers do
not run. Response-filter and log handlers can still run for the injected
response.
- `delay`: introduces a specified delay before processing the request further.
:::info
diff --git a/docs/en/latest/plugins/real-ip.md
b/docs/en/latest/plugins/real-ip.md
index 215cdeddf6..39a3a09464 100644
--- a/docs/en/latest/plugins/real-ip.md
+++ b/docs/en/latest/plugins/real-ip.md
@@ -45,8 +45,8 @@ The Plugin is functionally similar to NGINX's
[ngx_http_realip_module](https://n
| Name | Type | Required | Default | Valid values | Description |
|-----------|---------|----------|---------|----------------|---------------|
| source | string | True | | |A built-in [APISIX
variable](https://apisix.apache.org/docs/apisix/apisix-variable/) or [NGINX
variable](https://nginx.org/en/docs/varindex.html), such as
`http_x_forwarded_for` or `arg_realip`. The variable value should be a valid IP
address that represents the client's real IP address, with an optional port.|
-| trusted_addresses | array[string] | False | | array of IPv4 or IPv6
addresses (CIDR notation acceptable) | Trusted addresses that are known to
send correct replacement addresses. This configuration sets the
[`set_real_ip_from`](https://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from)
directive. |
-| recursive | boolean | False | False | | If false, replace the
original client address that matches one of the trusted addresses by the last
address sent in the configured `source`.<br />If true, replace the original
client address that matches one of the trusted addresses by the last
non-trusted address sent in the configured `source`. |
+| trusted_addresses | array[string] | False | | array of IPv4 or IPv6
addresses (CIDR notation acceptable) | Addresses of trusted proxies that can
supply a replacement address through `source`. When configured, the Plugin
changes the client address only if the current connection address matches this
list. When omitted, the Plugin accepts the value from `source` for connections
from any peer. Configure trusted addresses when untrusted clients can control
the source value. |
+| recursive | boolean | False | False | | Controls how the Plugin
selects an address when `source` is `http_x_forwarded_for` and
`trusted_addresses` is configured. If false, the Plugin selects the last
address in the header. If true, the Plugin scans the header from right to left,
skips trusted intermediary addresses, and selects the last non-trusted address.
If every address is trusted, it selects the leftmost address. This option has
no effect for other sources or when `trusted_ [...]
:::note
Only `X-Forwarded-*` headers sent from addresses in the
`apisix.trusted_addresses` configuration (supports IP and CIDR) will be trusted
and passed to plugins or upstream. If `apisix.trusted_addresses` is not
configured or the IP is not within the configured address range, the
`X-Forwarded-Proto`, `X-Forwarded-Host`, and `X-Forwarded-Port` headers are
overridden with trusted values and the `Forwarded` header is cleared. The
`X-Forwarded-For` header is reset to the APISIX-observed connecti [...]
