My biggest gripe with nginx is the documentation. I ran into an issue with proxy_buffering being off yet I was still getting 502 errors because the upstream was passing too large headers for the default 4k buffers. I naively assumed that with proxy buffering off that it would send data to the client immediately and, y'know, not buffer it, as [0] suggests. Turns out that turning proxy_buffering off doesn't turn proxy buffering completely off.
While working on that issue, I also needed to set the proxy buffer size. Quick, what's the difference between proxy_buffer_size [1] and the size argument of proxy_buffers [2]? I still don't know, because the docs for each directive sound to me like they're restating the same exact thing.
Looking at that documentation has me even more confused.
The article says "Proxy buffering means that NGINX stores the response from a server in internal buffers as it comes in, and doesn’t start sending data to the client until the entire response is buffered."
But those parameters say nothing about waiting to send data to the client, and in fact some of them like proxy_busy_buffers_size imply the exact opposite.
Logically the purpose of proxy buffering is to prevent server death from clients holding connections open by reading the data very slowly (slowloris attack). But this doesn't require waiting for the entire upstream response before sending bytes to the client; merely that reading from upstream doesn't stop when the client is reading slowly. It looks like nginx does this while still preventing slowloris.
The parameters mentioned look like they're about tuning the relative memory costs of sending down the first bit of data in a response, which may contain enough information on the client side to do something interesting. proxy_buffer_size looks like it's just the first buffer, while the size argument to proxy_buffers applies to all the buffers.
But it seems it's about response buffering, not incoming (request) buffering. (Or to be more precise slowloris can be done on either/both leg(s) of the request-response process.)
While working on that issue, I also needed to set the proxy buffer size. Quick, what's the difference between proxy_buffer_size [1] and the size argument of proxy_buffers [2]? I still don't know, because the docs for each directive sound to me like they're restating the same exact thing.
[0] https://nginx.org/en/docs/http/ngx_http_proxy_module.html#pr... [1] https://nginx.org/en/docs/http/ngx_http_proxy_module.html#pr... [2] https://nginx.org/en/docs/http/ngx_http_proxy_module.html#pr...