proxy-buffering Enterprise

The proxy-buffering plugin dynamically disables the NGINX proxy_buffering directive.

You should disable buffering in scenarios when configuring APISIX with server-sent events (SSE) upstream services, or services that respond with chunked data, such as the etcd watch events.

Examples​

Configure With SSE Upstream​

The following example demonstrates how to disable proxy_buffering on a route with an SSE upstream service.

Start a sample upstream service for SSE:

docker run -d -p 8080:8080 jmalloc/echo-server

Create a route to the upstream and configure proxy-buffering:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "proxy-buffering-route",
    "uri": "/.sse",
    "plugins": {
      "proxy-buffering": {
        "disable_proxy_buffering": true
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "127.0.0.1:8080": 1
      }
    }
  }'

Send a request to the route:

curl "http://127.0.0.1:9080/.sse" -H "Accept: text/event-stream"

You should receive a HTTP/1.1 200 OK response and see continuous event stream similar to the following:

event: server
data: 162291b28f55
id: 1

event: request
data: GET /.sse HTTP/1.1
data: 
data: Host: 127.0.0.1:9080
data: Accept: text/event-stream
data: User-Agent: curl/7.74.0
data: X-Forwarded-For: 172.19.0.1
data: X-Forwarded-Host: 127.0.0.1
data: X-Forwarded-Port: 9080
data: X-Forwarded-Proto: http
data: X-Real-Ip: 172.19.0.1
data: 
id: 2

event: time
data: 2023-10-19T02:13:53Z
id: 3

event: time
data: 2023-10-19T02:13:54Z
id: 4

event: time
data: 2023-10-19T02:13:55Z
id: 5

...

(Optional) See Buffering in Effect​

You will see the proxy buffering effect on SSE when proxy_buffering is not turned off in this section. For demonstration, the proxy buffer size will be adjusted to a larger value.

Add the following snippet to the configuration file:

nginx_config:
  http_configuration_snippet: |
    server {
      listen 9080;

      location /sse {
        proxy_buffering on;
        proxy_buffers 4 2m;
      }
    }

❶ Though explicitly configured, proxy_buffering is on by default.

❷ Configure proxy_buffers to use 4 buffers, each with a size of 2 MB.

Reload APISIX for changes to take effect.

Recreate the route without proxy-buffering:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "proxy-buffering-route",
    "uri": "/.sse",
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "127.0.0.1:8080": 1
      }
    }
  }'

Send a request to the route:

curl "http://127.0.0.1:9080/.sse" -H "Accept: text/event-stream"

You should receive a HTTP/1.1 200 OK response and see the same event stream. However, note that events are not received at a regular interval due to the effect of the buffer, which is undesirable when working with an SSE upstream.