Origin Range Requests: Serving Large Files Without Manual Range Tuning

Black and white speedometer at 0 – Origin Range Requests: Serving Large Files Without Manual Range Tuning

Delivering large files across a distributed Content Delivery Network (CDN) poses unique operational challenges. When clients request specific sections of a file using HTTP range requests—such as a video player seeking to a timestamp or a download manager resuming a broken transfer—naïve caching models can lead to severe network bandwidth waste and disk I/O bottlenecks. Cloudflare addressed this by replacing its legacy Nginx-based range caching system with an architecture built on Pingora, introducing a self-service feature called Origin Range Requests.

The Mechanics of HTTP Range Requests

An HTTP range request allows a client to request a specific subset of a resource rather than downloading the entire file. The client issues a standard GET request containing a Range header specifying the desired byte offsets:

GET /movie.mp4 HTTP/1.1
Host: example.com
Range: bytes=1048576-2097151

When the origin or edge server supports partial requests, it responds with an HTTP/1.1 206 Partial Content status code, accompanied by headers indicating the returned range and total asset size:

HTTP/1.1 206 Partial Content
Content-Range: bytes 1048576-2097151/524288000
Content-Length: 1048576

Range requests are standard practice across modern web applications. They allow video players to skip forward without downloading preceding video data, package managers to fetch specific artifact segments, download managers to resume interrupted transfers, and utilities to read file headers or trailing metadata without fetching full multi-gigabyte payloads.

Limitations of Legacy Nginx Cache-Slicing

Cloudflare previously managed range requests through a static, zone-level configuration modeled after Nginx cache-slicing. In that architecture, every client request was mapped to fixed-size byte ranges defined on a per-zone basis. This created severe operational trade-offs:

  • Small Range Sizes: Caused a high volume of small origin requests. Aggregating these requests in memory created substantial memory pressure on edge servers.
  • Large Range Sizes: Forced the CDN to fetch significantly more data from the origin than requested. For example, a single byte read could trigger a 128 MiB fetch across data centers, wasting bandwidth if the client disconnected early.
  • Cache Key Invalidation: Because the range size setting was incorporated into the cache key, modifying the range size configuration invalidated existing cached assets across the zone.
  • Request Blocking: Concurrent client requests falling within the same pre-defined range blocked each other, regardless of how far apart the actual requested bytes were.
  • Streaming Incompatibilities: The legacy Nginx setup could not combine range caching with concurrent streaming (a feature allowing multiple clients to read a file while it is written to cache). Combining both resulted in truncated responses, forcing the edge to download each range completely before serving clients and requiring separate origin fetches for popular ranges.

Architectural Shift: Chunk-Based Caching in Pingora

The transition from Nginx to Cloudflare’s Rust-based proxy framework, Pingora, provided the foundation to eliminate zone-level range tuning entirely. Pingora natively writes cached resources to disk in bounded, fixed-size chunks to simplify interrupted download recoveries.

Origin Range Requests leverages these internal disk chunks as the fundamental unit of range management. Instead of requiring administrators to define static range configurations, the system automatically uses Pingora’s native chunk boundaries:

  1. The edge evaluates incoming client range headers against local disk chunks.
  2. Bytes already stored locally in cache chunks are served directly to the downstream client.
  3. For uncached bytes, the edge fetches origin ranges aligned strictly to Pingora’s fixed-size chunk boundaries.
  4. The fetched bytes are written to disk in standard cache chunks, and only the exact range requested by the client is returned downstream.

For example, if a client requests bytes 150–250, the edge fetches the single aligned chunk containing those offsets from the origin, writes the chunk to cache storage, and delivers only bytes 150–250 in the 206 response to the client.

The Cache Coordinator: Merging Multi-Source Data

When a requested byte range spans across a mixture of cached disk data, active background downloads, and unmanaged origin regions, a central cache coordinator dynamically orchestrates the response. The coordinator performs the following steps:

  • Inspects the targeted asset’s response headers and range-coverage metadata.
  • Reads available cached bytes from local disk storage or active in-memory streams.
  • Issues upstream origin fetches for missing byte coverage, aligned to fixed chunk boundaries.
  • Writes newly fetched bytes to disk while updating range-coverage metadata.
  • Assembles the disjointed byte streams and calculates downstream Content-Range and Content-Length response headers.

To reduce duplicate origin load during high-concurrency traffic spikes, the coordinator supports download multiplexing: if an existing origin download is already fetching bytes needed by a secondary request, the second request attaches to the active in-flight stream rather than triggering another origin fetch.

Validation, Headers, and Protocol Correctness

To ensure content integrity when composing responses from multiple chunks, the coordinator enforces strict HTTP validation rules across subrequests:

  • Representation Consistency: The coordinator verifies that the asset’s total size and Entity Tag (ETag) remain identical across all partial origin fetches and cached chunks.
  • Conditional Requests (If-Range): If a client includes an If-Range header with an ETag or timestamp validator that fails match checks, the edge bypasses partial composition and serves the complete, updated asset representation instead.
  • Compression Handling: The coordinator skips range composition if an asset is scheduled for edge decompression. Because byte offsets over compressed files do not match offsets over uncompressed content, Cloudflare serves the complete transformed response rather than delivering invalid byte offsets.

Production Benchmark Results and Tiered Cache Impact

Cloudflare deployed Origin Range Requests internally across high-concurrency workloads before releasing the feature publicly. The primary internal benchmark was Cloudflare R2 object storage, which previously operated under a hardcoded 64 MiB range configuration where small boundary-crossing reads generated 128 MiB of inter-datacenter traffic.

Deploying the Pingora coordinator across R2 yielded concrete performance gains:

  • P99 Latency Reduction: Across all R2 storage regions, 99th-percentile Time to First Byte (p99 TTFB) dropped by approximately 50% for both cache hits and cache misses.
  • Tiered Cache Bandwidth Reduction: Enabling the coordinator to merge cached disk bytes with upstream bytes in a single unified response reduced week-over-week tiered cache traffic for R2 workloads by approximately 6%, eliminating petabytes of daily data transfers between data centers.

Implementation and Configuration

Origin Range Requests is available as a self-service feature across all plan levels. It relies on standard Cache Rules without requiring range size calculations or manual buffer sizing.

Prerequisites for activation:

  • The underlying origin server must support HTTP byte ranges (returning 206 Partial Content for range queries).
  • The target asset must meet existing cache eligibility rules (the feature does not make uncacheable responses cacheable).

To activate via the Cloudflare Dashboard, navigate to Caching > Cache Rules, define matching criteria for large-file endpoints, and set Origin Range Requests to On.

To activate via the Cloudflare API, include the origin_range_requests property within your Cache Rule payload:

{
  "expression": "(http.request.uri.path contains "/media/")",
  "action": "set_cache_settings",
  "action_parameters": {
    "origin_range_requests": {
      "mode": "on"
    }
  }
}

Suitable Workloads

Origin Range Requests provides immediate operational benefits for traffic patterns characterized by selective or non-sequential reads across large assets:

  • Media Streaming: Seekable MP4 or progressive video formats where players fetch localized frame buffers.
  • Resumable Downloads: Large software installers, OS ISO images, and archive files managed by multi-threaded or break-resumable download clients.
  • Package Repositories: Package managers fetching metadata indices or single binary blobs out of centralized archives.
  • AI Model Artifacts: Training and inference pipelines pulling specific layer weights or header metadata from multi-gigabyte model files.

Frequently asked questions

What is an HTTP range request?

An HTTP range request uses the Range header (e.g., Range: bytes=1048576-2097151) to ask an HTTP server for a specific portion of a file. The server responds with an HTTP 206 Partial Content status code and the requested byte subset.

Why did legacy Nginx range caching cause performance bottlenecks?

Nginx range caching relied on fixed, zone-level range sizes. Small ranges caused high origin request volume and memory overhead from coalescing requests, while large ranges forced data centers to download up to hundreds of megabytes from origin for small client reads.

How does Pingora store and handle range requests differently?

Pingora automatically saves cached files on disk in fixed-size chunks. Origin Range Requests uses these internal chunk boundaries to fetch missing data from origins, eliminating the need for user-configured range sizes.

Does enabling Origin Range Requests make uncacheable files cacheable?

No. Origin Range Requests alters how partial requests are handled and cached for assets that already qualify for caching. It does not bypass or override standard cacheability criteria.

How does the feature handle concurrent requests for the same file range?

The cache coordinator multiplexes concurrent requests. If multiple clients request bytes currently being fetched from an origin, subsequent requests attach to the existing in-flight download stream instead of creating extra origin load.

What configuration options are required to enable Origin Range Requests?

No size tuning is necessary. You turn it on via Cloudflare Cache Rules in the dashboard under Caching > Cache Rules, or via the API by setting origin_range_requests to { "mode": "on" }.

Primary reference: Review the original announcement for exact release details. This article is an independent explanation and does not reproduce the source text.