Mirror Request

The mirror request feature allows generating subrequests to access additional servers, enabling various business scenarios. For example:

• Send requests to authentication servers for verification before allowing service access
• Send requests to WAF servers for security checks before permitting access

# Configuration Parameters

• Type: Processing method for mirror requests
  • RAW: Directly mirror the original request
  • CUSTOM: Perform customized processing through a custom Lua module
• Module Name: When type is CUSTOM, specify the name of the Lua module that handles the request (see examples below for module format requirements)
• Upstream: Select the target upstream server for mirror requests
• Algorithm: Load balancing algorithm, supports Hash, Chash, Roundrobin
• Retry Count: Number of retries when requests fail
• Send Timeout: Timeout for sending data to the mirror server (in seconds)
• Read Timeout: Timeout for receiving data from the mirror server (in seconds)
• Connect Timeout: Timeout for connecting to the mirror server (in seconds)
• Async: Whether to enable asynchronous mirror requests (main request doesn’t wait for subrequest to return) (Added in v25.12.1-1)
• Forward Request Body: Whether to forward the original request body (Added in v25.12.1-1)

Note: When upstream servers have health checks enabled, the mirror request feature will enable fast-fail by default. This means when health checks show no available upstream servers, the system will skip mirror request operations.

# Configuration Examples

# 1. Add Global Lua Module

Lua Module Example:

local _M = {}

function _M.before_mirror(ctx)
    local content_length = tonumber(ngx.var.content_length)
    if content_length and ctx.max_body_size > 4096 then
        return ngx.DONE  -- Skip mirror operation
    end
    return ngx.OK
end

function _M.mirror_rewrite(ctx)
    ngx.req.set_header('X-Real-IP', tostring(ngx.var.remote_addr))
end

function _M.mirror_header_filter(ctx)
    ngx.log(ngx.ERR, "in mirror_header_filter")
end

function _M.mirror_body_filter(ctx)
    ngx.log(ngx.ERR, "in mirror_body_filter")
end

function _M.after_mirror(ctx, resp)
    ngx.header['mirror-response-body'] = resp.body
end

function _M.header_filter()
    ngx.log(ngx.ERR, "in main request header filter")
end

function _M.body_filter()
    ngx.log(ngx.ERR, "in main request body filter")
end

return _M

Callback Function Descriptions:

• before_mirror: Called before subrequest creation, returning ngx.DONE skips the mirror operation
• mirror_rewrite: Called during the subrequest rewrite phase, can modify subrequest information
• mirror_header_filter: Called during the subrequest header_filter phase, can modify subrequest response headers
• mirror_body_filter: Called during the subrequest body_filter phase, can modify subrequest response body (not called in async mode)
• after_mirror: Called after subrequest completion (not called in async mode)
• header_filter: Called during the main request header_filter phase
• body_filter: Called during the main request body_filter phase

# 2. Add Mirror Server

# 3. Configure Page Rules

# 4. Test Request

$ curl http://test.com -v
* Rebuilt URL to: test.com/
*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to test.com (127.0.0.1) port 80 (#0)
> GET / HTTP/1.1
> Host: test.com
> User-Agent: curl/7.61.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Thu, 13 Oct 2022 08:25:22 GMT
< Content-Type: text/plain
< Transfer-Encoding: chunked
< Connection: keep-alive
< mirror-response-body: i am mirror server
< Server: openresty+
< Req-ID: 00000080000447f28b90004c
< Cache-Status: BYPASS
<
i am upstream
* Connection #0 to host test.com left intact

From the response results, we can see that the response headers include mirror-response-body: i am mirror server, indicating that the mirror request feature is working properly and successfully retrieved the response content from the mirror server.