Skip to main content

Proxy Control

The proxy-control plugin controls whether NGINX buffers a request body before sending it to an upstream service. Disabling request buffering lets the upstream receive the body as the client sends it, which is useful for streaming uploads and services that need to process large request bodies incrementally.

Request Handling​

By default, request buffering is enabled and NGINX reads the complete request body before proxying it upstream. Disable request buffering to stream the body to the upstream as it arrives.

After NGINX starts sending a request body without buffering, it cannot retry the request on another upstream node. Disable request buffering only when this tradeoff is acceptable.

In Apache APISIX, do not combine this plugin with ext-plugin-post-resp. That plugin sends upstream requests through lua-resty-http, which bypasses request-buffering control.

Example​

The example compares buffered and streaming request-body delivery through two routes that share one controlled upstream.

Compare Buffered and Streaming Uploads​

The Docker-based setup requires a running APISIX or API7 Gateway container that can join a Docker network. During each rate-limited upload, a separate request checks whether the test upstream is receiving the body.

Create and enter a working directory for the example:

mkdir proxy-control-example
cd proxy-control-example

Create the following Python script for the test upstream:

request-observer.py
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer


active_paths = set()


class Handler(BaseHTTPRequestHandler):
protocol_version = "HTTP/1.1"

def do_POST(self):
active_paths.add(self.path)

try:
remaining = int(self.headers.get("Content-Length", "0"))
while remaining:
chunk = self.rfile.read(min(remaining, 8192))
if not chunk:
break
remaining -= len(chunk)
finally:
active_paths.discard(self.path)

body = b"upload complete\n"

self.send_response(200)
self.send_header("Content-Type", "text/plain")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)

def do_GET(self):
state = "receiving" if self.path in active_paths else "waiting"
body = f"{state}\n".encode()

self.send_response(200)
self.send_header("Content-Type", "text/plain")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)

def log_message(self, *_):
pass


ThreadingHTTPServer(("0.0.0.0", 8000), Handler).serve_forever()

Set GATEWAY_CONTAINER to the running APISIX or API7 Gateway container. Create a dedicated network and connect the gateway to it:

export GATEWAY_CONTAINER=replace-with-gateway-container-name

docker network create gateway-request-buffering-net
docker network connect gateway-request-buffering-net "$GATEWAY_CONTAINER"

Start the test upstream from the directory containing request-observer.py:

docker run -d \
--name request-observer \
--network gateway-request-buffering-net \
-v "$PWD/request-observer.py:/request-observer.py:ro" \
python:3.13.15-alpine3.24 \
python -u /request-observer.py

Create two routes to the same upstream. One route enables request buffering, and the other streams the request body:

If Admin API authentication is enabled, export an admin-role key as ADMIN_API_KEY before using the Admin API tab.

Create the route that buffers the request body:

curl "http://127.0.0.1:9180/apisix/admin/routes/proxy-control-buffered" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"uri": "/buffered-upload",
"plugins": {
"proxy-control": {
"request_buffering": true
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"request-observer:8000": 1
}
}
}'

Create the route that streams the request body:

curl "http://127.0.0.1:9180/apisix/admin/routes/proxy-control-streaming" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"uri": "/streaming-upload",
"plugins": {
"proxy-control": {
"request_buffering": false
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"request-observer:8000": 1
}
}
}'

Create a 100 KiB request body:

dd if=/dev/zero of=upload.bin bs=1024 count=100

Start sending the body at 10 KiB per second to the buffered route, then check whether the upstream has received the request:

curl "http://127.0.0.1:9080/buffered-upload" \
--limit-rate 10k \
--data-binary @upload.bin \
--output /dev/null \
--silent \
--show-error &

buffered_pid=$!
sleep 1
curl "http://127.0.0.1:9080/buffered-upload"
wait "$buffered_pid"

The status request should return waiting because the gateway is still buffering the upload and has not started the upstream request:

waiting

Start the same upload to the streaming route, then check its status:

curl "http://127.0.0.1:9080/streaming-upload" \
--limit-rate 10k \
--data-binary @upload.bin \
--output /dev/null \
--silent \
--show-error &

streaming_pid=$!
sleep 1
curl "http://127.0.0.1:9080/streaming-upload"
wait "$streaming_pid"

The status request should return receiving because the gateway started forwarding the body before the client finished sending it:

receiving

This difference confirms that disabling request buffering starts forwarding the body before the client finishes sending it.