Skip to content

Instantly share code, notes, and snippets.

Last active July 1, 2024 00:08
Show Gist options
  • Save CMCDragonkai/6bfade6431e9ffb7fe88 to your computer and use it in GitHub Desktop.
Save CMCDragonkai/6bfade6431e9ffb7fe88 to your computer and use it in GitHub Desktop.
HTTP Streaming (or Chunked vs Store & Forward)

HTTP Streaming (or Chunked vs Store & Forward)

The standard way of understanding the HTTP protocol is via the request reply pattern. Each HTTP transaction consists of a finitely bounded HTTP request and a finitely bounded HTTP response.

However it's also possible for both parts of an HTTP 1.1 transaction to stream their possibly infinitely bounded data. The advantages is that the sender can send data that is beyond the sender's memory limit, and the receiver can act on the data stream in chunks immediately instead of waiting for the entire data to arrive. Basically you're either saving space or you're saving time. The advantages of streaming is elaborated in Wikipedia's Online algorithm article.

Note that HTTP streaming is only involves the HTTP protocol and not websockets. Streaming is also the basis for HTML5 server sent events.

So we're going to look at HTTP streaming architecture, and how to achieve streaming in a few different languages.

The first thing to understand is that HTTP streaming involves streaming within a single HTTP transaction. In a larger context, each HTTP transaction itself represents an event as part of a larger event stream. This reveals to us that the concepts of "streaming" is a context-specific concept, it's relative to what we consider the "stream" to be.

Firstly we have to consider the HTTP headers that supports streaming. Open this up for reference:


The Content-Length header determines the byte length of the request/response body. If you neglect to specify the Content-Length header, HTTP servers will implicitly add a Transfer-Encoding: chunked header. The Content-Length and Transfer-Encoding header should not be used together. The receiver will have no idea what the length of the body is and cannot estimate the download completion time. If you do add a Content-Length header, make sure it matches the entire body in bytes, if it is incorrect, the behaviour of receivers is undefined.

The Content-Length header will not allow streaming, but it is useful for large binary files, where you want to support partial content serving. This basically means resumable downloads, paused downloads, partial downloads, and multi-homed downloads. This requires the use of an additional header called Range. This technique is called Byte serving.


The use of Transfer-Encoding: chunked is what allows streaming within a single request or response. This means that the data is transmitted in a chunked manner, and does not impact the representation of the content.

Officially an HTTP client is meant to send a request with a TE header field that specifies what kinds of transfer encodings the client is willing to accept. This is not always sent, however most servers assume that clients can process chunked encodings.

The chunked transfer encoding makes better use of persistent TCP connections, which HTTP 1.1 assumes to be true by default.

Chunked data is represented in this manner:


Each chunk starts with its byte length expressed as a hexadecimal number followed by optional parameters (chunk extension) and a terminating CRLF sequence, followed by the chunk data. The final chunk is terminated by a CRLF sequence.

Chunk extensions can be used to indicate a message digest or an estimated progress. They are just custom metadata that your layer 7 receiver needs to parse. There's no standardised format for it. Because of this, it's probably better to just add your metadata (if any) into the chunk itself for your layer 7.5 application to parse.

For your application to send out chunked data, you must first send out the Transfer-Encoding header, and then you must flush content in chunks according to the chunk format. If you don't have an appropriate HTTP server that handles this, then you need to implement the syntax generator yourself. Sometimes you can use a library to provide an abstract interface.

For example in PHP, there's the Symfony HTTP Foundation Stream Response and in NodeJS, it's native HTTP module chunks all responses.

Chunking is a 2 way street. The HTTP protocol allows the client to chunk HTTP requests. This allows the client to stream the HTTP request. Which is useful for uploading large files. However not many servers (except NGINX) support this feature, and most streaming upload implementations rely on Javascript libraries to cut up a binary file and send it by chunks to the server. Using Javascript gives you more control over the uploading experience, but the HTTP protocol would be the most simplest.

Browsers natively support chunked data. So if your server sends chunked data, they will start rendering data as soon as they receive it. However there's a buffer limit that browsers need to receive before it starts rendering them. This is different for each browser, but generally it's 1KB. You can see the limits for various browsers here:

If however you want to consume an API that supports streaming, you need to be aware of how your HTTP library handles chunked data. In most cases, you'll need to attach a callback handler that executes upon each chunk of data. This should mean that your API will need to frame each chunk in a useful manner. If the API is doing too many chunks, you may end up needing to buffer the data up into a "semantic protocol data unit" (PDU) before you can work on it. This of course defeats the purpose of chunking in the first place. For example in PHP, you can use the Guzzle library or curl.

In considering performance, you want to make sure that you're not producing way too chunky data. The more "chunking" you do, the more overhead that exists in both producing the chunks and parsing the chunks. Furthermore, it also results in more executions of buffering functions if the receiver can't make immediate use of the chunks. Chunking isn't always the right answer, it adds extra complexity on the recipient. So if you're sending small units of things that won't gain much from streaming, don't bother with it!

Do note that byte serving is compatible with chunked encoding, this would be applicable where you know the total content length, want to allow partial or resumable downloads, but you want to stream each partial response to the client.


It is also possible to compress chunked or non-chunked data. This is practically done via the Content-Encoding header.

Note that the Content-Length is equal to the length of the body after the Content-Encoding. This means if you have gzipped your response, then the length calculation happens after compression. You will need to be able to load the entire body in memory if you want to calculate the length (unless you have that information elsewhere).

When streaming using chunked encoding, the compression algorithm must also support online processing. Thankfully, gzip supports stream compression. I believe that the content gets compressed first, and then cut up in chunks. That way, the chunks are received, then decompressed to acquire the real content. If it were the other way around, you'll get the compressed stream, and then decompressing would give us chunks. Which doesn't make sense.

A typical compressed stream response may have these headers:

Content-Type: text/html
Content-Encoding: gzip
Transfer-Encoding: chunked

Semantically the usage of Content-Encoding indicates an "end to end" encoding scheme, which means only the final client or final server is supposed to decode the content. Proxies in the middle are not suppose to decode the content.

If you want to allow proxies in the middle to decode the content, the correct header to use is in fact the Transfer-Encoding header. If the HTTP request possessed a TE: gzip chunked header, then it is legal to respond with Transfer-Encoding: gzip chunked.

However this is very rarely supported. So you should only use Content-Encoding for your compression right now.

Buffering Problem

The biggest problem when implementing HTTP streaming is understanding the effect of buffering. Buffering is the practice of accumulating reads or writes into a temporary fixed memory space. The advantages of buffering include reducing read or write call overhead. For example instead of writing 1KB 4096 times, you can just write 4096KB at once. This means your program can create a write buffer holding 4096KB of temporary data (which can be aligned to the disk blocksize), and once the space limit is reached, the buffer is flushed to disk.

Typical HTTP architectures include these components:

Client <--> Proxy <--> HTTP Server <--> Application Server <--> Database Server

Each one of these components can possess adjustable and varied buffering styles and limits.

To correct perform streaming, you have to know and adjust the buffering limits at each component.

For example, let's invesigate the typical PHP stack such as:

Browser <--> Proxy <--> NGINX <--> PHP <--> MySQL

The Client

Firstly browsers have a rendering buffer limit. You must send as much data as the limit before the browsers will render the content. Having chunks smaller than the buffer will just make the browser hold the data until either the buffer is full or when the connection is closed (or after some time limit).

The Proxies

At the proxy level, this could be your ISP or some custom proxy. If the proxy buffers data this means, your streamed data from upstream will be stored up the proxy buffer before sending to the browser. Some mobile wireless ISP will buffer things and you won't be able to control this behaviour, this is a violation of the end to end principle, so there's nothing here you can do technically.

The Web Server

At the NGINX level, buffering is dependent upon the type of the upstream connection. There are 3 common connection types for HTTP: "proxy", "uwsgi", "fastcgi". If you want your NGINX server to respect streaming, you can either switch off buffering for your connection type, or match the buffer size with the upstream chunk size. Switching off buffering can be done using a buffering directive (proxy_buffering, uwsgi_buffering, fastcgi_buffering), or you can use a special header X-Accel-Buffering: no which tells NGINX to not buffer the response. The special header is more flexible, as this allows NGINX to buffer responses that don't need streaming. It also works for all 3 connection types.

If you instead try to match the buffer size with the chunk size, you have to make sure that the number of buffers multiplied by the buffer size (equal to a system memory page) is equal to a single chunk size. If it is greater than a single chunk from upstream, then this means your chunks will be accumulated before they are sent downstream. If it is less than the chunk size, this would result in NGINX buffering to disk, you want to avoid this as this results in extra overhead when streaming. For more information on buffer size see this gist.

Just a note on buffering optimisation: the larger the total buffer size, the greater likelihood of each connection using more memory. This is because if each buffer is large, there's a chance that you may not be efficiently using the buffer which can cause memory fragmentation. In the end, each buffer size should match the system memory page size. The number of buffers is what can be dynamically allocated. If your total buffer size across all connections exceeds your OS's memory limit, you're either going to meet an OOM error or starting paging to disk. To maintain your NGINX's availability, you have to consider the theoretical number of connections that a single NGINX server can handle, before it exhausts your server's memory limit.

Be aware of the real chunk size after compression. If your upstream is compressing the content, the resulting chunk size will be different. In most cases, NGINX should be doing the compression and it does support compressing for chunk that arrives from upstream. You just need gzip on. This means your application layer should not be compressing or chunking the content, it should just flush raw data. NGINX is smart enough to understand and will automatically compress each received upstream data, and then format it into chunks, which is then flushed to downstream.

There's an advantage in keeping buffers available or having a larger buffer size than the chunk size. It comes from dealing with slow clients. NGINX as a reverse proxy is very fast and can read the response from your upstream application server very quickly. NGINX itself can deal with any slow browsers that has a slower read rate than your upstream's write rate. Because NGINX is very light weight (asynchronous IO), the cost of holding a connection in NGINX is far smaller than holding open a process (that is waiting for the client to finish reading) in your application server. This is of course relative, as your application server might also be very light weight, and rely on either green threads or asynchronous IO. This problem does reveal an interesting property of streaming systems. Any stream will only be as quick as the slowest link (reader or writer) in the chain. This problem with streaming is related to network back pressure issue in distributed systems.

To take advantage of NGINX's ability of handling slow clients while still streaming data as fast as possible, there will need to be some tuning of both the buffer size and potentially the *_busy_buffer_size option. You cannot just increase the total buffer size, as that will just make NGINX wait until the buffer is full. What you need is some buffer size that is allocated only for slow clients. This has something to do with the *_busy_buffer_size, but this is poorly documented currently, so I do not know how make this work.

Here are 2 quotes about the *_busy_buffer_size:

When buffering of responses from the * server is enabled, limits the total size of buffers that can be busy sending a response to the client while the response is not yet fully read. In the meantime, the rest of the buffers can be used for reading the response and, if needed, buffering part of the response to a temporary file. By default, size is limited by the size of two buffers set by the *_buffer_size and *_buffers directives.

  • NGINX documentation

proxy_busy_buffers_size: This directive sets the maximum size of buffers that can be marked "client-ready" and thus busy. While a client can only read the data from one buffer at a time, buffers are placed in a queue to send to the client in bunches. This directive controls the size of the buffer space allowed to be in this state.

The Application Server

At the PHP level, global buffers can be set inside the php.ini configuration file. There are 3 options defined output_buffering, output_handler and implicit_flush. They are explained in the output control section of the PHP documentation. It is interesting to note that for CLI applications, the output buffering is off by default. This is so that your CLI application can show you results as its running. This buffer is controlled by the server application programming interface "SAPI". You can control inside your application by calling flush(), which will flush the entire SAPI buffer.

During runtime, custom buffers can also be created using ob_start(). Once you have added content to the buffer, you can then flush your custom buffer using ob_flush(). This only flushes the buffer that you created using ob_start(). Think of the ob_start() as a kind of PHP specific manual memory management. You're basically asking for some block of memory (fixed or variable), which you then can only use for your output statements and functions: echo and print.

If you have entered both levels of buffers, you need call the flush functions in this order: ob_flush(); flush();.

Both the global SAPI buffer and the custom application buffer have settings that enable automatic flushing. This can depend on hitting the buffer limit, or on some function call. Check the documentation for more.

The Upstream Data Source

Finally we reach the MySQL level. This can be replaced with any upstream data source that you are calling in order to prepare a response. By default all SQL queries are buffered. There are 2 options to achieve unbuffered queries (writes and reads). The first is the unbuffered query option. This allows one to work with reading large result sets, and to process each row as it arrives (including flushing to the client).The second option works with just one single column of data. This is useful where a single column contains a large binary or textual content, and you want to be able to work with a stream on this data specifically. This involves the usage of the large object option. You can also stream write a large binary or textual content into the database using large object option. The streaming of writing rows is just done by running multiple insert queries.

With regards to the second method, there are some peculiarities you have to keep in mind:

A Note About NodeJS

NodeJS has great support for streaming. In fact its entire native HTTP module does streaming by default for both incoming requests and outgoing responses. Everytime you call response.writeHead or response.write, it is just writing a chunk of data. However there may be a buffer size inside NodeJS which is probably the highWaterMark setting. However I have not looked into this further.

NodeJS has a native stream module: that serves as a base object for all other IO modules.

Copy link

This was extremely well written and very easy to follow. I now know what's actually going on with my application. Thanks!

Copy link

Very good. Thank you man

Copy link


Copy link

Nice handling! Thanks

Copy link

Bingnan commented Jul 1, 2019

thanks, mark

Copy link

mipac commented Jul 3, 2019

very useful!
thanks a lot

Copy link

hdw868 commented Nov 17, 2020

Thanks for the comprehensive explanation!

Copy link

Osuriel commented May 26, 2021

Thank you so much!!!!!!!!!!!!!!

Copy link

Nice article, thanks. 🤝

I've been working on this java project to chunk data (audio) to client, I used Firefox and vlc for testing.
It worked when I read the whole song file and buffer it out once, but didn't work when I implemented it in chunk Transfer-encoding using the your explanation.
Firefox is saying unknown file content and vlc just load the content and doesn't play at all.

Copy link

THX a lot for this.
Very well documented!

Copy link

Thank you so much for document this. It's so integrated.

Copy link

Could you please share your repo to me?

Thanks in advance.

Copy link

This is really helpful. Thanks ❤

Copy link

Good ⚡

Copy link

you save me bro

Copy link

you save me bro

Copy link

Thank you so much !

Copy link

kayws426 commented Dec 2, 2023

Thank you!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment