feat: add proxy-buffering plugin

.ignore_words

@@ -9,3 +9,4 @@ nulll
 smove
 aks
 nin
+bre

apisix/cli/config.lua

@@ -194,6 +194,7 @@ local _M = {
     "real-ip",
     "ai",
     "client-control",
+    "proxy-buffering",
     "proxy-control",
     "request-id",
     "zipkin",

apisix/cli/ngx_tpl.lua

@@ -947,6 +947,46 @@ http {
         }
         {% end %}
 
+        {% if enabled_plugins["proxy-buffering"] then %}
+        location @disable_proxy_buffering {
+            access_by_lua_block {
+                apisix.disable_proxy_buffering_access_phase()
+            }
+
+            proxy_http_version 1.1;
+            proxy_set_header   Host              $upstream_host;
+            proxy_set_header   Upgrade           $upstream_upgrade;
+            proxy_set_header   Connection        $upstream_connection;
+            proxy_set_header   X-Real-IP         $remote_addr;
+            proxy_pass_header  Date;
+
+            proxy_set_header   X-Forwarded-For      $proxy_add_x_forwarded_for;
+            proxy_set_header   X-Forwarded-Proto    $var_x_forwarded_proto;
+            proxy_set_header   X-Forwarded-Host     $var_x_forwarded_host;
+            proxy_set_header   X-Forwarded-Port     $var_x_forwarded_port;
+
+            proxy_pass      $upstream_scheme://apisix_backend$upstream_uri;
+
+            {% if enabled_plugins["proxy-mirror"] then %}
+            mirror          /proxy_mirror;
+            {% end %}
+
+            header_filter_by_lua_block {
+                apisix.http_header_filter_phase()
+            }
+
+            body_filter_by_lua_block {
+                apisix.http_body_filter_phase()
+            }
+
+            log_by_lua_block {
+                apisix.http_log_phase()
+            }
+
+            proxy_buffering off;
+        }
+        {% end %}
+
         {% if enabled_plugins["proxy-mirror"] then %}
         location = /proxy_mirror {
             internal;

apisix/init.lua

@@ -610,6 +610,11 @@ function _M.handle_upstream(api_ctx, route, enable_websocket)
         stash_ngx_ctx()
         return ngx.exec("@dubbo_pass")
     end
+
+    if ngx.ctx.disable_proxy_buffering then
+        stash_ngx_ctx()
+        return ngx.exec("@disable_proxy_buffering")
+    end
 end
 
 
@@ -865,6 +870,11 @@ function _M.dubbo_access_phase()
 end
 
 
+function _M.disable_proxy_buffering_access_phase()
+    ngx.ctx = fetch_ctx()
+end
+
+
 function _M.grpc_access_phase()
     ngx.ctx = fetch_ctx()
 

apisix/plugins/proxy-buffering.lua

@@ -0,0 +1,53 @@
+--
+-- Licensed to the Apache Software Foundation (ASF) under one or more
+-- contributor license agreements.  See the NOTICE file distributed with
+-- this work for additional information regarding copyright ownership.
+-- The ASF licenses this file to You under the Apache License, Version 2.0
+-- (the "License"); you may not use this file except in compliance with
+-- the License.  You may obtain a copy of the License at
+--
+--     http://www.apache.org/licenses/LICENSE-2.0
+--
+-- Unless required by applicable law or agreed to in writing, software
+-- distributed under the License is distributed on an "AS IS" BASIS,
+-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+-- See the License for the specific language governing permissions and
+-- limitations under the License.
+--
+local require = require
+local ngx     = ngx
+local core = require("apisix.core")
+
+
+local schema = {
+    type = "object",
+    properties = {
+        disable_proxy_buffering = {
+            type = "boolean",
+            default = false,
+        },
+    },
+}
+
+
+local plugin_name = "proxy-buffering"
+local _M = {
+    version = 0.1,
+    priority = 21991,
+    name = plugin_name,
+    schema = schema,
+}
+
+
+function _M.check_schema(conf)
+    return core.schema.check(schema, conf)
+end
+
+
+-- we want to control proxy behavior before auth, so put the code under rewrite method
+function _M.rewrite(conf, ctx)
+    ngx.ctx.disable_proxy_buffering = conf.disable_proxy_buffering
+end
+
+
+return _M

conf/config.yaml.example

@@ -473,6 +473,7 @@ plugins:                           # plugin list (sorted by priority)
   - real-ip                        # priority: 23000
   - ai                             # priority: 22900
   - client-control                 # priority: 22000
+  - proxy-buffering                # priority: 21991
   - proxy-control                  # priority: 21990
   - request-id                     # priority: 12015
   - zipkin                         # priority: 12011

docs/en/latest/config.json

@@ -167,6 +167,7 @@
             "plugins/traffic-split",
             "plugins/request-id",
             "plugins/proxy-control",
+            "plugins/proxy-buffering",
             "plugins/client-control",
             "plugins/workflow"
           ]

docs/en/latest/plugins/proxy-buffering.md

@@ -0,0 +1,109 @@
+---
+title: proxy-buffering
+keywords:
+  - Apache APISIX
+  - API Gateway
+  - Proxy Buffering
+description: The proxy-buffering Plugin disables nginx proxy buffering per route to enable streaming responses such as Server-Sent Events (SSE).
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+<head>
+  <link rel="canonical" href="https://docs.api7.ai/hub/proxy-buffering" />
+</head>
+
+## Description
+
+The `proxy-buffering` Plugin disables nginx proxy buffering for the configured route. When proxy buffering is disabled, nginx streams the upstream response directly to the client without accumulating it in memory or on disk first.
+
+This is particularly useful for:
+
+- **Server-Sent Events (SSE)**: Clients must receive events in real time; buffering would delay or break the stream.
+- **Streaming APIs**: Large or indefinite response bodies must flow continuously without waiting for the full body.
+- **Real-time data delivery**: Any use case requiring low-latency delivery of partial responses.
+
+## Attributes
+
+| Name                      | Type    | Required | Default | Description                                                                                   |
+| ------------------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------- |
+| disable_proxy_buffering   | boolean | False    | false   | When set to `true`, disables [`proxy_buffering`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) for this route, enabling streaming responses. |
+
+## Examples
+
+The examples below demonstrate how you can configure the `proxy-buffering` Plugin for different scenarios.
+
+:::note
+You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:
+
+```bash
+admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
+```
+
+:::
+
+### Disable Proxy Buffering for Streaming Responses
+
+The following example disables proxy buffering for a route that serves Server-Sent Events (SSE):
+
+```shell
+curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \
+  -H "X-API-KEY: $admin_key" -X PUT -d '
+{
+    "uri": "/sse",
+    "plugins": {
+        "proxy-buffering": {
+            "disable_proxy_buffering": true
+        }
+    },
+    "upstream": {
+        "type": "roundrobin",
+        "nodes": {
+            "127.0.0.1:1980": 1
+        }
+    }
+}'
+```
+
+Send a request to the route:
+
+```shell
+curl -i -N -H "Accept: text/event-stream" http://127.0.0.1:9080/sse
+```
+
+Because `disable_proxy_buffering` is `true`, nginx streams each SSE event from the upstream to the client as it arrives, without buffering.
+
+## Delete Plugin
+
+To remove the `proxy-buffering` Plugin, delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
+
+```shell
+curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \
+  -H "X-API-KEY: $admin_key" -X PUT -d '
+{
+    "uri": "/sse",
+    "upstream": {
+        "type": "roundrobin",
+        "nodes": {
+            "127.0.0.1:1980": 1
+        }
+    }
+}'
+```

docs/zh/latest/config.json

@@ -156,6 +156,7 @@
             "plugins/traffic-split",
             "plugins/request-id",
             "plugins/proxy-control",
+            "plugins/proxy-buffering",
             "plugins/client-control",
             "plugins/workflow"
           ]

docs/zh/latest/plugins/proxy-buffering.md

@@ -0,0 +1,117 @@
+---
+title: proxy-buffering
+keywords:
+  - APISIX
+  - API 网关
+  - Proxy Buffering
+description: 本文介绍了 Apache APISIX proxy-buffering 插件的相关操作，你可以使用此插件按路由禁用 nginx 代理缓冲，这对于流式响应（如 Server-Sent Events）至关重要。
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+<head>
+  <link rel="canonical" href="https://docs.api7.ai/hub/proxy-buffering" />
+</head>
+
+## 描述
+
+`proxy-buffering` 插件用于按路由控制 nginx 代理缓冲行为。禁用代理缓冲后，nginx 会将上游响应直接流式传输给客户端，而不会在内存或磁盘中积累完整响应体。该功能对以下场景至关重要：
+
+- **Server-Sent Events（SSE）**：客户端需要实时接收事件，缓冲会延迟或中断数据流。
+- **流式 API**：响应体较大或无限长，需要持续流式传输而无需等待完整响应。
+- **实时数据推送**：任何需要低延迟传输部分响应的场景。
+
+该插件工作在 `rewrite` 阶段，优先级为 **21991**，早于鉴权插件执行，可以影响 APISIX 流水线中代理 location 的选择。
+
+## 属性
+
+| 名称                    | 类型    | 必选项 | 默认值 | 描述                                                                                                                                              |
+| ----------------------- | ------- | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| disable_proxy_buffering | boolean | 否     | false  | 设置为 `true` 时，将为该路由禁用 [`proxy_buffering`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering)，从而支持流式响应。 |
+
+## 启用插件
+
+以下示例展示了如何在指定路由上启用 `proxy-buffering` 插件以支持流式响应：
+
+:::note
+
+您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
+
+```bash
+admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
+```
+
+:::
+
+```shell
+curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \
+  -H "X-API-KEY: $admin_key" -X PUT -d '
+{
+    "uri": "/sse",
+    "plugins": {
+        "proxy-buffering": {
+            "disable_proxy_buffering": true
+        }
+    },
+    "upstream": {
+        "type": "roundrobin",
+        "nodes": {
+            "127.0.0.1:1980": 1
+        }
+    }
+}'
+```
+
+## 测试插件
+
+启用插件后，向该路由发送请求：
+
+```shell
+curl -i http://127.0.0.1:9080/sse
+```
+
+由于 `disable_proxy_buffering` 设置为 `true`，nginx 会将响应直接流式传输给客户端，对调用方透明，但消除了 nginx 引入的缓冲延迟。
+
+要验证配置是否已正确保存：
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+  -H "X-API-KEY: $admin_key"
+```
+
+响应中将包含路由对象中的 `proxy-buffering` 插件配置。
+
+## 删除插件
+
+当你需要删除该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+
+```shell
+curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \
+  -H "X-API-KEY: $admin_key" -X PUT -d '
+{
+    "uri": "/sse",
+    "upstream": {
+        "type": "roundrobin",
+        "nodes": {
+            "127.0.0.1:1980": 1
+        }
+    }
+}'
+```