Skip to main content
LeoNex News

Serving Large Files with Origin Range Requests

Illustration: Serving Large Files with Origin Range Requests
In this article

A range request is an HTTP request that asks for only part of a resource instead of the whole thing. Traditional caching for this kind of request can easily waste network bandwidth and disk operations when running a CDN at large scale. Cloudflare has rebuilt its cache mechanism for range requests and introduced Origin Range Requests, a feature that can be self-configured on every plan, with no need to adjust range sizes or contact support. This article describes the problems with the old approach, the new approach, the correctness checks, and the real-world results.

Range requests and the range size problem

The client sends an ordinary GET with a Range header. If the server supports it, it returns 206 Partial Content and uses Content-Range to indicate which bytes are being returned.

Range requests are common with large objects. A video player may request the bytes around a seek position instead of the whole file. A download tool may resume after an interruption. A package manager may fetch part of an artifact. A client may also look at the end of a file without downloading everything before it. The client decides whether to make a range request, and Cloudflare does not change that request; Origin Range Requests only changes how Cloudflare fulfills it.

The old implementation, through static per-zone configuration, resembled the cache-slicing described in an nginx blog post: each client request is mapped to fixed-size ranges, with the size and file extensions configured per zone. This size creates a trade-off. Small ranges lead to many small requests to the origin and put pressure on memory when requests are merged in memory. Large ranges make Cloudflare download much more data than the client needs. Changing the size also invalidates cache entries, because the size is part of the cache key.

  • Concurrent requests that fall into the same range can block each other, no matter how far apart the ranges the clients requested are.

  • A cache built on nginx could not combine range caching with concurrent streaming, the feature that lets multiple clients read a file from cache while it is still being written.

  • When both were enabled, responses were truncated, so each range had to be fully downloaded before anyone could read it, and a popular file needed a separate fetch to the origin for each range.

  • Extra bytes can pass through multiple parts of the distributed cache: from the origin to a data center, between cache tiers, and then to the client, so each hop multiplies the waste.

Using fixed-size chunks as the range unit

The solution came from the fact that Pingora already stores each cache file on disk as fixed-size chunks, to make it easier to resume interrupted downloads. If the cache already thinks in chunks, the range size no longer needs to be a setting: it is the chunk. For a range request, Cloudflare checks which bytes are already cached and serves them directly. For the missing bytes, the system fetches origin ranges aligned to chunk boundaries, stores the results in the same chunks used for regular cache storage, and returns only the bytes the client requested.

For example, a request for bytes 150-250 may cause Cloudflare to fetch the aligned chunk containing those bytes, but the response sent to the client still contains only 150-250. For requests smaller than the chunk size, fetching the whole chunk can still happen, and unaligned ranges also cost extra work. The difference is that this extra work is bounded and predictable, and no longer depends on a range size chosen by the customer, which used to have unpredictable effects on Cloudflare and the origin.

Coordinating cached and in-flight data

Parsing the Range header is fairly simple. The harder part is producing a correct response when the requested bytes are scattered across cached data, origin responses, and downloads in progress. At a high level, the edge performs the following steps.

  1. Look up the resource's headers and metadata about the ranges already available.

  2. Read the portion that can be read from disk or from in-memory streaming.

  3. Fetch the missing portion from the origin using aligned ranges.

  4. Write the new bytes and record the completed range in the metadata.

  5. Stitch the pieces together and set Content-Range and Content-Length for the response to the client.

This is a coordinator rather than a single cache lookup. One request may use an already-cached beginning, an in-progress download, and a newly fetched tail. The internal response from the origin may be larger than the response sent down to the client, but the client-facing status and headers describe only the requested range. If a running download already covers the bytes of another request, the second request can attach to that download instead of starting a new fetch to the origin, which shares work during traffic spikes on popular large files. The design reuses the existing cache data model: headers identify the resource version, the body is stored in bounded chunks, and metadata records which ranges were written successfully.

Verification before assembling the response

An assembled range response is valid only when every byte belongs to the same representation of the resource. The coordinator checks three things: each origin response matches the requested range, the total resource size is stable, and the entity tag is consistent across subrequests. The If-Range header lets a client request a range only if the representation still matches a known validator; if it does not match, Cloudflare returns the full representation instead of mixing bytes from different versions.

Cloudflare also avoids stitching ranges for representations that are about to be decompressed, because a range over the compressed byte stream differs from a range selected over the decompressed response. In that case, the system serves the entire transformed response instead of advertising a range it cannot fulfill correctly. The final behavior follows standard HTTP:

  • A satisfiable range receives 206 Partial Content with an accurate Content-Range.

  • An unsatisfiable range receives 416 Range Not Satisfiable.

  • A response that cannot be safely range-split is served as the full representation.

Real-world results and how to enable the feature

R2 is the largest internal user, with a configured range size of 64 MiB, so a small read straddling a range boundary could cost 128 MiB of transfer between data centers. After moving R2 to the new implementation, two improvements were recorded:

  • Faster responses: on R2's storage regions, p99 time to first byte dropped by roughly half, for both cache hits and cache misses.

  • Fewer bytes on the network: the coordinator was taught to combine bytes already on disk with bytes fetched from upstream in a single response, whereas before a request was served either entirely from cache or entirely from upstream. After enabling it for R2, tiered cache traffic for R2 and similar workloads dropped by about 6% week over week, meaning petabytes less data moving between data centers every day.

Origin Range Requests is meant for traffic where clients naturally request pieces of a large, cacheable object, such as:

  • Progressively loading, seekable video such as MP4.

  • Large resumable downloads.

  • Software distribution and package repositories.

  • Disk images, archives, and other multi-gigabyte objects.

  • AI training and inference workloads that stream large model files or fetch selected regions of model artifacts.

  • Clients that fetch only the metadata or a small region of a large file.

Key takeaways

More in Software Engineering

Illustration: Rust in CPython? Discussion at the Python Language Summit
SOFT-ENG Software Engineering

Rust in CPython? Discussion at the Python Language Summit

David Hewitt, representing the Rust for CPython project team, returned to the Python Language Summit to ask Python's core developers what they want from Rust. He presented a phased roadmap, success criteria and a proposal to start with an optional Rust backend for the zlib module. The long-term goal is to make Rust…

6 min read

Illustration: Notable V8 changes from Node.js 26 to 27
SOFT-ENG Software Engineering

Notable V8 changes from Node.js 26 to 27

The Node.js 27 Alpha upgrades V8 to version 15.6, up from 14.6 in Node.js 26. The upgrade brings several new JavaScript language features, a number of behavior changes, performance improvements and memory adjustments. Some changes may break code that relies on the old behavior, so developers should…

3 min read

Email newsletter

Receive a selection of new LeoNex News articles by email.

We only use this address to send the newsletter.

Receive a selection of new LeoNex News articles by email. You will receive a confirmation email; the subscription only takes effect after you confirm. Every email includes an unsubscribe link. Read the privacy policy