OpenResty Edge now offers Mirror Request functionality, simplifying complex business logic and security policies for enhanced efficiency.

At its core, the Mirror Request functionality allows you to send a copy of a request to other servers for additional processing. In synchronous mode, the primary request will wait for the mirrored request to complete before responding. Conversely, in asynchronous mode, the primary request can respond immediately, unaffected by the mirrored request’s processing. This capability is particularly valuable in scenarios requiring security auditing, data analysis, or business validation. By leveraging this feature, the flexibility and security of your systems can be significantly improved. This guide will walk you through the steps to effectively utilize the mirror request feature within OpenResty Edge.

The continuous optimization of the Mirror Request feature is a testament to the hard work of the engineers on the OpenResty Edge team. We are grateful for their contributions in continually refining this crucial functionality.

Request to try out OpenResty Edge

Triple Enhancement in Stability, Experience, and Cost

OpenResty Edge’s mirror request feature is akin to equipping the main request with a “clone” ability. It can generate one or more sub-requests (mirror requests) while processing the main request. These “clones” carry a copy of the original request and are sent to pre-configured backend servers to perform various background tasks. In asynchronous mode, the main request can respond quickly without any hindrance, ensuring a seamless user experience.

  • Enhanced Security and Compliance: The mirror request feature, by asynchronously handling Web Application Firewall (WAF) scans and identity authentication, ensures low latency for the main request. This allows us to meet the stringent security and compliance requirements of industries like finance and e-commerce without impacting user experience, significantly boosting user trust and business efficiency.
  • Flexible Business Process Orchestration: The mirror request feature enables you to efficiently apply real-time data to diverse scenarios such as monitoring, analytics, A/B testing, and canary releases, all without affecting core business operations. This provides robust support for building highly available edge applications.
  • Ultimate Performance and User Experience: By introducing asynchronous mirror mode, your main requests no longer need to wait for auxiliary background tasks like logging and data statistics to complete, enabling immediate responses to clients. This mechanism significantly reduces the latency of the main request, ensuring your users enjoy a faster and more seamless application experience.

Core Mechanism Breakdown

The power of mirrored requests stems from the exceptional request processing capabilities of OpenResty Edge. It ingeniously creates and spawns sub-requests at critical stages of the request lifecycle, enabling precise replication and efficient forwarding of the original request.

To meet your diverse and evolving business needs, we offer an extremely rich set of configuration options:

  • Type (RAW/CUSTOM): You can choose to mirror the original request directly (RAW), or perform deep customization through custom Lua modules (CUSTOM) to implement advanced logic such as modifying request content or conditional judgments.
  • Asynchronous Mirroring Mode (New in v25.12.1-1): When this option is enabled, the main request does not need to wait for the mirrored request to complete. This completely decouples the execution of the main request and the mirrored request, significantly improving response speed, which is key to achieving high-performance edge computing.
  • Forward Request Body (New in v25.12.1-1): This allows the original request’s body to be forwarded along with the mirrored request to the target server. This is crucial for WAFs or logging systems that require the complete request content, greatly expanding the application depth of mirrored requests in scenarios like security auditing and data analysis.
  • Flexible Upstream Selection & Load Balancing: You can specify the target upstream servers for mirrored requests and choose from various load balancing algorithms such as Hash, Chash, Roundrobin, and more.
  • Comprehensive Fault Tolerance: Supports configuring retry counts, send/read/connect timeouts, and defaults to enabling a fast-fail mechanism (linked with health checks) to ensure system stability during high loads or backend service anomalies.

The upcoming v25.12.1-1 version of OpenResty Edge will introduce key enhancements with Asynchronous Mirroring Mode and Request Body Forwarding capabilities. We recommend keeping an eye on this release to experience the latest features.

Callback Functions

OpenResty Edge offers powerful customization capabilities, allowing you to write your own Lua modules.

Through a series of thoughtfully designed callback functions such as before_mirror, mirror_rewrite, and mirror_header_filter, you can deeply intervene at every critical stage of the mirroring process. This means you can intelligently decide whether to skip mirroring based on the request content, flexibly modify the header information of mirrored requests, and even execute your custom specific operations after the mirroring is complete.

This comprehensive flexibility is designed to empower developers, helping you precisely tailor mirroring behavior to meet a wide range of complex business needs.

Configuration Steps Example

Configuring the mirroring feature is very intuitive. Here are the main steps:

  1. Add Global Lua Module (Optional, for CUSTOM type):
local _M = {}

function _M.before_mirror(ctx)
    local content_length = tonumber(ngx.var.content_length)
    if content_length and content_length > 4096 then
        return ngx.DONE  -- Skip mirroring 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 Description:

  • before_mirror: Called before a sub-request is created. Returning ngx.DONE will skip the mirroring operation.
  • mirror_rewrite: Called during the rewrite phase of a sub-request. It allows modification of sub-request information.
  • mirror_header_filter: Called during the header_filter phase of a sub-request. It allows modification of the sub-request’s response headers.
  • mirror_body_filter: Called during the body_filter phase of a sub-request. It allows modification of the sub-request’s response body (this will not be called in asynchronous mode).
  • after_mirror: Called after the sub-request is completed (this will not be called in asynchronous mode).
  • header_filter: Called during the header_filter phase of the main request.
  • body_filter: Called during the body_filter phase of the main request.

  1. Add Mirror Server: Configure your target mirror upstream server within the OpenResty Edge management interface. You can access this at OpenResty Edge.

  2. Configure Page Rules: Enable the mirror request action within your page rules. Here, you’ll select the appropriate configuration parameters. If you’re using the CUSTOM type, you’ll also specify the relevant Lua module.

  3. Test Your Request:

    $ curl http://test.com -v
# The response will include content from your mirror server, for example:
# mirror-response-body: i am mirror server

For those interested in the deeper technical details or advanced use cases of the mirror request functionality, we encourage you to explore the comprehensive documentation on Mirror Request in the OpenResty Edge documentation.

What is OpenResty Edge

OpenResty Edge is our all-in-one gateway software for microservices and distributed traffic architectures. It combines traffic management, private CDN construction, API gateway, security, and more to help you easily build, manage, and protect modern applications. OpenResty Edge delivers industry-leading performance and scalability to meet the demanding needs of high concurrency, high load scenarios. It supports scheduling containerized application traffic such as K8s and manages massive domains, making it easy to meet the needs of large websites and complex applications.

Request to try out OpenResty Edge

About The Author

Yichun Zhang (Github handle: agentzh), is the original creator of the OpenResty® open-source project and the CEO of OpenResty Inc..

Yichun is one of the earliest advocates and leaders of “open-source technology”. He worked at many internationally renowned tech companies, such as Cloudflare, Yahoo!. He is a pioneer of “edge computing”, “dynamic tracing” and “machine coding”, with over 22 years of programming and 16 years of open source experience. Yichun is well-known in the open-source space as the project leader of OpenResty®, adopted by more than 40 million global website domains.

OpenResty Inc., the enterprise software start-up founded by Yichun in 2017, has customers from some of the biggest companies in the world. Its flagship product, OpenResty XRay, is a non-invasive profiling and troubleshooting tool that significantly enhances and utilizes dynamic tracing technology. And its OpenResty Edge product is a powerful distributed traffic management and private CDN software product.

As an avid open-source contributor, Yichun has contributed more than a million lines of code to numerous open-source projects, including Linux kernel, Nginx, LuaJIT, GDB, SystemTap, LLVM, Perl, etc. He has also authored more than 60 open-source software libraries.