How do proxy_module response buffering options work?

[Maxim Dounin]

Hello!

On Sun, Apr 24, 2011 at 04:49:23PM +0200, Hongli Lai wrote:

> I'm trying to understand how the different proxy_module response
> buffering options work. The current documentation is a little bit vague.
> Here's how I currently think buffering works:
> 
> Nginx allocates a number of separate buffers for buffering the response.
> They are probably used as a ring for efficiency reasons.
> 
> The first buffer is used to store the response header, and must be large
> enough to store the header. I'm guessing this is because the proxy
> module's response header parser can only operate on a contiguous block
> of memory. The size of this first buffer can be customized through
> proxy_buffer_size, but it has no effect on all the other buffers.
> 
> If proxy_buffering is turned on then Nginx will fill all proxy buffers
> with data, either until the upstream sends EOF or until the buffers are
> full. When one of those conditions occur Nginx will flush the data to
> the client. If the client does not read data quickly enough Nginx will
> write the unflushed buffer data to disk and will flush them when the
> client can read more data. This is repeated until the upstream sends
> EOF.

Yes.

Additionally, there is proxy_max_temp_file_size, which controls how 
much data may be written to disk.  Once temp file size becomes 
bigger - nginx pauses reading data from upstream until data from 
temporary file is sent to client.

> If proxy_buffering is turned off then Nginx will also fill all proxy
> buffers. However it tries to immediately flush the data to the client.
> If the upstream sends data faster than the client can read then the
> proxy buffers will eventually be full and upstream will be throttled
> until the client can read more data.

Yes.  But only main buffer (proxy_buffer_size) will be used to 
read response.

> Is this correct? There's also proxy_busy_buffers_size but I have no idea
> what that is.

Busy buffers are buffers which are already passed downstream but 
not yet completely send (and hence can't be reused).  The 
proxy_busy_buffers_size directive limits maximum total size of 
such buffers and thus allows remaining buffers to be used to read 
upstream response (and spool it to disk if needed).

Maxim Dounin