Range

Preliminaries

This note documents the range request header and the server's implementation of the range protocol to get selected parts of a file.

The HTTP 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.

Conditional requests

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.

Methods

Responses to 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 startByte, endByte and 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.

Information headers

When an 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.

When the 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 rw-range-units-not-supported.

When the 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 rw-bad-range.

Support for range requests does not require any server configuration. It is always enabled.

Review

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.