feat: support lua proxy upstream #12086

LiteSun · 2025-03-26T07:06:29Z

Description

Currently, APISIX cannot support making HTTP requests during the body_filter phase.

This PR adds a lua_body_filter phase, which uses Lua to make HTTP requests to upstream services, bypassing Nginx's default upstream request behavior.

This allows for more flexible request operations in the lua_body_filter phase.

The lua_body_filter phase executes before header_filter and body_filter phases.

Checklist

I have explained the need for this PR and the problem it solves
I have explained the changes or the new features added to this PR
I have added tests corresponding to this change
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 first)

AlinsRan · 2025-04-01T01:13:43Z

apisix/plugins/example-plugin.lua

@@ -85,6 +90,10 @@ function _M.access(conf, ctx)
    core.log.warn("plugin access phase, conf: ", core.json.encode(conf))
    -- return 200, {message = "hit example plugin"}

+    if conf.lua_proxy_upstream then


This is a feature PR that has added plugin configuration and requires updating schema.

AlinsRan · 2025-04-01T01:34:10Z

apisix/init.lua

+        common_phase("before_proxy")
+        return
+    end
+
    -- run the before_proxy method in access phase first to avoid always reinit request
    common_phase("before_proxy")


common_phase("before_proxy") if api_ctx.lua_proxy_upstream then return end

nic-6443 · 2025-04-01T02:41:20Z

apisix/init.lua

@@ -550,6 +550,12 @@ function _M.handle_upstream(api_ctx, route, enable_websocket)

    set_upstream_headers(api_ctx, server)

+    -- lua proxy the request to upstream
+    if api_ctx.lua_proxy_upstream then


I thought about the naming of the existing variables bypass_nginx_upstream and lua_proxy_upstream, and felt that their meanings are unclear. I think we can design them as two:

bypass_nginx_upstream to indicate bypassing nginx's upstream module

bypass_balancer to indicate bypassing the existing balancer logic
cc @membphis What do you think?

I agree with this

nic-6443 · 2025-04-01T02:48:00Z

apisix/lua_proxy.lua

+    end
+
+    local headers = core.request.headers(ctx)
+    -- When content-length is cleared, the HTTP server will automatically calculate and


Suggested change

-- When content-length is cleared, the HTTP server will automatically calculate and

-- When content-length is cleared, the HTTP client will automatically calculate and

nic-6443 · 2025-04-01T02:53:30Z

apisix/lua_proxy.lua

+    -- TODO: support event stream
+    if content_type and core.string.find(content_type, "text/event-stream") then
+        core.log.error("event stream is not supported")
+       return HTTP_INTERNAL_SERVER_ERROR
+    end


This already has example code in ai-proxy.

nic-6443 · 2025-04-01T03:01:02Z

t/plugin/example.t

+                        "example-plugin": {
+                            "i": 0,
+                            "lua_proxy_upstream": true,
+                            "request_uri": "http://httpbin.org/get",


rename this request_uri to indicate it's used to change the rseponse body, it make me confused with upstream.nodes

nic-6443 · 2025-04-01T03:02:21Z

apisix/plugins/example-plugin.lua

+    core.log.warn("plugin lua_body_filter phase, conf: ", core.json.encode(conf))
+    core.log.warn("plugin lua_body_filter phase, body: ", core.json.encode(body))


you can assert those log in test cases to confirm the body come from upstream is passed to lua_body_filter as expect.

nic-6443 · 2025-04-01T03:06:59Z

t/plugin/example.t

+
+
+
+=== TEST 14: lua body filter


We need to add more test cases that combine example-plugin with other plugins like proxy-rewrite, which modify downstream requests. This will help verify that the new Lua HTTP client way works with existing plugins in the rewrite/access phase.

AlinsRan · 2025-04-01T05:49:48Z

apisix/lua_proxy.lua

+        headers = headers,
+        ssl_verify = conf.ssl_verify,
+        keepalive = conf.keepalive,
+        keepalive_timeout = conf.timeout,


This timeout is unclear.
The meanings of connection timeout and idle connection timeout are different.
I suggest using keepalive_timeout

AlinsRan · 2025-04-01T05:51:05Z

apisix/lua_proxy.lua

+    -- Get request body
+    local body, err = core.request.get_body()
+    if err then
+        core.log.error("failed to get request body: ", err)


Why isn't there a return for this error?

AlinsRan · 2025-04-01T06:03:30Z

apisix/plugins/example-plugin.lua

@@ -107,6 +116,49 @@ function _M.access(conf, ctx)
    return
 end

+
+function _M.before_proxy(conf, ctx)
+    core.log.warn("plugin before_proxy phase, conf: ", core.json.encode(conf))


This is not a warm level log, please use core.json.delay_encode

AlinsRan · 2025-04-01T06:20:15Z

apisix/lua_proxy.lua

+    local code, body = read_response(ctx, res)
+
+    -- Set keepalive for connection reuse
+    if opts.keepalive then


Do I not need to close the connection when the keepalive is false?

bzp2010

What is the mean of another complex mechanism introduced by this PR? It's introducing a new plugin phase again, and continuing to introduce new learning costs, and I can't accept it without significant justification.

Now, even a professional APISIX developer would be hard pressed to say what APISIX phases are and how they correspond to NGINX phases.

How does it differ from performing HTTP requests at rewrite/access using lua-resty-http?
Has the solution been properly evaluated for performance differences with access phase + subrequests? This would also allow you to implement running external requests in the header_filter and body_filter phases, and there would be no need to introduce new request phases, just a new core API is enough.

LiteSun added 7 commits March 26, 2025 15:05

feat: add proxy_nginx_upstream param

e593091

u

d59dbb7

u

e708e62

u

8a289ed

u

981a7a8

u

6c40320

update name

6ed4f52

LiteSun changed the title ~~feat: add proxy_nginx_upstream param~~ feat: add lua_proxy_upstream param Mar 27, 2025

LiteSun added 11 commits March 27, 2025 17:51

rm

0f83314

u

7de4631

u

54bf2de

f

90e0620

u

e43eeb3

refactor

89ff772

f

5f92bc7

add test

48ec69e

u

00e1d09

u

052fc8f

f

1294721

LiteSun marked this pull request as ready for review March 31, 2025 03:57

dosubot bot added size:L This PR changes 100-499 lines, ignoring generated files. enhancement New feature or request labels Mar 31, 2025

update log

2f3bfc9

LiteSun changed the title ~~feat: add lua_proxy_upstream param~~ feat: support lua proxy upstream Mar 31, 2025

LiteSun requested review from nic-6443, Revolyssup and AlinsRan April 1, 2025 00:57

AlinsRan reviewed Apr 1, 2025

View reviewed changes

nic-6443 reviewed Apr 1, 2025

View reviewed changes

AlinsRan reviewed Apr 1, 2025

View reviewed changes

bzp2010 requested changes Apr 1, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: support lua proxy upstream #12086

feat: support lua proxy upstream #12086

LiteSun commented Mar 26, 2025 •

edited

Loading

AlinsRan Apr 1, 2025 •

edited

Loading

AlinsRan Apr 1, 2025

nic-6443 Apr 1, 2025 •

edited

Loading

shreemaan-abhishek Apr 5, 2025

nic-6443 Apr 1, 2025

nic-6443 Apr 1, 2025

nic-6443 Apr 1, 2025

nic-6443 Apr 1, 2025

AlinsRan Apr 1, 2025

nic-6443 Apr 1, 2025

AlinsRan Apr 1, 2025

AlinsRan Apr 1, 2025

AlinsRan Apr 1, 2025

AlinsRan Apr 1, 2025

bzp2010 left a comment •

edited

Loading

	-- When content-length is cleared, the HTTP server will automatically calculate and
	-- When content-length is cleared, the HTTP client will automatically calculate and

		core.log.warn("plugin lua_body_filter phase, conf: ", core.json.encode(conf))
		core.log.warn("plugin lua_body_filter phase, body: ", core.json.encode(body))

feat: support lua proxy upstream #12086

Are you sure you want to change the base?

feat: support lua proxy upstream #12086

Conversation

LiteSun commented Mar 26, 2025 • edited Loading

Description

Checklist

AlinsRan Apr 1, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nic-6443 Apr 1, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bzp2010 left a comment • edited Loading

Choose a reason for hiding this comment

LiteSun commented Mar 26, 2025 •

edited

Loading

AlinsRan Apr 1, 2025 •

edited

Loading

nic-6443 Apr 1, 2025 •

edited

Loading

bzp2010 left a comment •

edited

Loading