# 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[​](#request-handling "Direct link to 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[​](#example "Direct link to Example")

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

### Compare Buffered and Streaming Uploads[​](#compare-buffered-and-streaming-uploads "Direct link to 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.

* Admin API
* ADC

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

      }

    }

  }'
```

Configure ADC to connect to the target backend. The remaining ADC commands read the connection settings from these environment variables:

* APISIX
* API7 Gateway

If Admin API authentication is enabled, export an admin-role key as `ADMIN_API_KEY` before configuring ADC.

```
export ADC_BACKEND=apisix

export ADC_SERVER="http://127.0.0.1:9180"

export ADC_TOKEN="${ADMIN_API_KEY}"
```

```
export ADC_BACKEND=api7ee

export ADC_SERVER="https://{DASHBOARD_ADDR}"

export ADC_TOKEN="{DASHBOARD_TOKEN}"

export ADC_GATEWAY_GROUP="{GATEWAY_GROUP}"
```

Create one service with a buffered route and a streaming route:

adc.yaml

```
services:

  - name: proxy-control-service

    labels:

      docs-example: proxy-control

    routes:

      - name: proxy-control-buffered

        uris:

          - /buffered-upload

        plugins:

          proxy-control:

            request_buffering: true

      - name: proxy-control-streaming

        uris:

          - /streaming-upload

        plugins:

          proxy-control:

            request_buffering: false

    upstream:

      type: roundrobin

      nodes:

        - host: request-observer

          port: 8000

          weight: 1
```

Preview the changes for this example:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-control
```

Review the diff, then synchronize only the labeled service:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=proxy-control
```

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.
