feat: add proxy-buffering plugin

[AlinsRan]

Summary

The proxy-buffering plugin controls nginx proxy buffering behavior per route. When proxy buffering is disabled, nginx streams responses directly to clients without buffering, which is essential for Server-Sent Events (SSE), streaming APIs, and real-time data delivery.

This plugin runs at a very high priority (21991) so it takes effect before authentication plugins, ensuring the streaming behavior is established early in the request lifecycle.

Changes

• New plugin apisix/plugins/proxy-buffering.lua (priority: 21991)
• Extends apisix/init.lua with a disable_proxy_buffering_access_phase() handler and routing check
• Extends apisix/cli/ngx_tpl.lua with a @disable_proxy_buffering nginx location block (similar to @grpc_pass)

Example

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

# Configure a route with proxy buffering disabled for SSE
curl http://127.0.0.1:9180/apisix/admin/routes/1 -X PUT   -H "X-API-KEY: ${admin_key}"   -d '{
    "uri": "/events",
    "plugins": {
      "proxy-buffering": {
        "disable_proxy_buffering": true
      }
    },
    "upstream": { "type": "roundrobin", "nodes": { "127.0.0.1:1980": 1 } }
  }'

Requests to /events will be proxied with proxy_buffering off, allowing SSE or chunked streaming responses to be delivered immediately to the client.

[shreemaan-abhishek]

license check failing

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a new proxy-buffering plugin to disable Nginx proxy buffering on a per-route basis (primarily to support SSE/streaming), wiring it into APISIX request handling and the Nginx template, plus adding docs and tests.

Changes:

• Introduces proxy-buffering plugin (priority 21991) that flags requests to be proxied with proxy_buffering off.
• Routes flagged requests to a dedicated named Nginx location (@disable_proxy_buffering) via apisix/init.lua + apisix/cli/ngx_tpl.lua.
• Adds docs (EN/ZH) and adds tests/scripts for schema validation and SSE verification.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
t/test_sse.py	Adds a Python SSE upstream + client used for manual/integration validation.
t/plugin/test_proxy_buffering.sh	Adds a shell-based flow configuring routes/SSLs and running SSE checks.
t/plugin/proxy-buffering.t	Adds schema validation tests for the new plugin.
t/certs/sse_server.key	Adds TLS private key for the SSE upstream used in tests.
t/certs/sse_server.crt	Adds TLS certificate for the SSE upstream used in tests.
t/admin/plugins.t	Registers proxy-buffering in admin plugin listing tests.
t/APISIX.pm	Adds a named Nginx location for disabling proxy buffering in test harness template.
docs/zh/latest/plugins/proxy-buffering.md	Adds Chinese documentation for proxy-buffering.
docs/zh/latest/config.json	Adds doc nav entry for plugin (ZH).
docs/en/latest/plugins/proxy-buffering.md	Adds English documentation for proxy-buffering.
docs/en/latest/config.json	Adds doc nav entry for plugin (EN).
conf/config.yaml.example	Adds plugin to default plugin list with priority comment.
apisix/plugins/proxy-buffering.lua	Implements the proxy-buffering plugin and schema.
apisix/init.lua	Adds upstream routing to @disable_proxy_buffering and a ctx-restoring access handler.
apisix/cli/ngx_tpl.lua	Adds @disable_proxy_buffering named location when plugin enabled.
apisix/cli/config.lua	Adds plugin to default enabled plugins list.
.ignore_words	Adds an ignored word entry.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.