How to download partial content
This note documents the range request header and the server's implementation of the range protocol to get selected parts of a file.
range request header is an optimization technique that allows user-agents to request, and servers to send, a selected portion of a file. This optimization may be used by crawlers to obtain only the initial part of a document for the purpose of finding keywords; or it may be used by smart user-agents to get the tail-end of a PDF or zip file, where important metadata and internal indexing are held. Uses such as these benefit from the range optimization protocol because of its ability to reduce latency, shorten transfer times, and conserve network bandwidth.
The server implements the range protocol as specified in IETF RFC 7233 Hypertext Transfer Protocol (HTTP/1.1): Range Requests.
The range header is assembled by a user-agent with at least one range tuple comprising a
startByte and an
endByte separated by a HYPHEN. More than one range tuple may be specified in a single request by joining them into a comma-separated string.
Two types of open-ended tuples may also be specified. A begins-at tuple syntactically begins with a
startByte and terminates with a HYPHEN; it is interpreted as a request for the tail-end of a file's contents, starting at the specified position. An ends-with tuple syntactically begins with a HYPHEN and terminates with a
byteCount; it is also interpreted as a request for the tail-end of a file's contents, but one that starts
byteCount bytes from the end of the file.
A user-agent can include an
if-range header together with the range request. Its purpose is to instruct the server to send the requested range(s), but only if the condition in the
if-range header is met. There are two types of conditions that can be specified. An etag condition includes an Etag value obtained from a previous request for the file; if the file's current Etag is still the same as the condition, the range request is honored. A modification date condition includes a timestamp value obtained from a previous request for the file; if the file's modification timestamp is still the same as the condition, the range request is honored. If neither of these conditions are met, the server reverts to sending the entire file.
HEAD requests will include an
accept-ranges header, advertising to user-agents that the server supports the range protocol.
The server supports the range protocol on static files requested with the
GET method. Requests for dynamic files do not honor the range header and will always respond with the entire dynamic payload.
Responses that successfully include a single portion of the file return with a
206 status code, and a
content-range header indicating the
fileSize. Responses that successfully include more than one portion of the file also return with a
206 status code, but encode the payload using the multipart/byteranges encoding, and include a
content-type: multipart/byteranges header to inform the user-agent of that fact.
There is no server support for the range protocol with
PUT requests, nor is the range protocol meaningful for any of the other HTTP methods.
if-range conditional request cannot be fulfilled, a
rw-conditional-range-failed header is included in the response, together with a status code of 200 and the full file in the payload.
range header does not specify the units value to be
'bytes', the request fails with a status code of
416 and an information header of
range header improperly specifies a range which results in the
startByte value being greater than the
endByte value, or the
startByte value being less than zero, or the
endByte value being greater than the size of the file, the request fails with a status code of
416 and an information header of
Support for range requests does not require any server configuration. It is always enabled.
Key points to remember:
- There is no support for range requests via HTML.
- Range requests are an optimization used by crawlers and other automated user-agents.