Byte ranges

A GET request with Range: bytes= returns part of a page or file instead of the whole thing. Use it to resume an interrupted download or to jump to a point in audio or video.

What you can range

Byte ranges work on a GET for a whole page or a stored file. A page that the server composes from includes or templates is cut from the bytes it would otherwise send, so the positions count into that composed output. The server cuts the range last, after any Processor has changed the response, so the positions count into the final bytes. Every byte-range request to a host with active decorations gets the whole 200, whether the answer comes from the cache or not. The server does not honour the Range. The body is decorated when it is an HTML page. A stored file comes back whole and as stored. A Processor aimed at 206 or 416 runs on a byte-range answer of that status, for a page and a stored file alike.

They do not apply to selector or entries requests, to 304 answers or to error responses. Range: selector= and Range: entries= work as they always did.

A HEAD request ignores Range. It returns 200 with the headers a GET would send, including Accept-Ranges.

Forms of the header

Range: bytes=0-499
Range: bytes=500-
Range: bytes=-500
Range: bytes=0-99, 200-299

A range that ends after the last byte is cut back to the last byte. A range that starts after the last byte is dropped.

One range

A single range that fits gets 206 Partial Content:

HTTP/1.1 206 Partial Content
Content-Range: bytes 0-499/1234
Content-Length: 500
ETag: "..."
Accept-Ranges: selector, bytes

Content-Range gives the span you received and the full length. The response keeps the ETag, Last-Modified, Vary and Cache-Control of the whole resource.

Several ranges

Two or more ranges that fit get 206 with Content-Type: multipart/byteranges; boundary=.... Each part has its own Content-Type (the type of the whole resource) and Content-Range.

When the server sends the whole resource

The server sends the whole body with 200 and ignores the Range header when:

Your client must be ready for a 200 in reply to any Range request.

When the range cannot be met

If every range starts after the last byte, the server answers 416 Range Not Satisfiable. The same happens when a range asks for the last 0 bytes. An empty body is different: the server ignores the range and sends the empty 200.

HTTP/1.1 416 Range Not Satisfiable
Content-Range: bytes */1234
Content-Type: text/html; charset=utf-8

Content-Range: bytes */1234 tells you the full length. The body is an error item with the type https://pagelove.org/Error/RangeNotSatisfiable, written as HTML microdata like every other Pagelove error.

Making a range conditional

Send If-Range with the ETag or Last-Modified value from an earlier response. The server applies the range only if the resource has not changed. If it has changed, you get the whole new resource with 200.

A composed page has a weak ETag, so a request with If-Range for a composed page always gets the whole page. A stored file and a plain stored page have strong ones.

Order of checks

The server checks If-None-Match and If-Modified-Since first. A request that earns a 304 gets a 304, whatever Range says. A GET does not check If-Match. The server considers Range and If-Range only when the answer would otherwise be 200.

Caches and the edge proxy

The edge proxy keeps whole responses. It cuts a range out of a cached page itself and sends the same answer you would get from the database. It never stores the 206 or 416 that answers a byte range. It still caches 206 answers to Range: selector= and entries=. A cached copy of the page serves every range request for it.

The WebDAV server answers byte ranges on GET in the same way, for pages and for files.

See also