# uploads-on-r2: serve WordPress uploads from R2

uploads-on-r2 is a Cloudflare Worker for WordPress operators who want media served from an R2 bucket without changing any URL. It answers /wp-content/uploads/ requests from the bucket and falls back to the origin when a file is not there yet. The code is at [https://github.com/IndianOpinion/uploads-on-r2](https://github.com/IndianOpinion/uploads-on-r2), under the MIT licence. Version v0.1.0 was released on 14 November 2026.

## The problem

A WordPress site keeps uploads on the origin's disk. Every cache miss for a media file costs the origin a request, the disk is the only copy that serves, and when the origin is slow or down every image breaks with it. Moving files to an object store fixes storage, but themes, feeds and years of published HTML all point at the same URLs. Rewriting them is slow, risky and never complete.

The Worker sits on the uploads path of the zone and serves those same URLs from the bucket. The worst case, a missing object or a Worker error, is the site you had before.

The main lesson shaped the design. A Worker in front of the origin bypasses the web server's own deny rules. A naive version that serves anything in the bucket will serve private upload folders, such as WordPress personal-data exports and plugin logs, to the public. This version denies private folders on the decoded key and reads only media extensions.

## What it does

- Serves GET and HEAD for media extensions from R2 on unchanged URLs, with content type, ETag, Last-Modified, conditional requests (304, 412) and single byte ranges (206, 416).

- Falls back to the origin on a miss, an R2 error, a non-media request or a non-GET method.

- Refuses private folders for every method, whatever the bucket holds.

- Sets long browser caching, with a per-family override (image, video, audio, document, other), and optionally caches in the Workers Cache API.

- Marks each response with an x-uploads-source header: r2, edge-cache, origin, origin-error, deny or negative-cache.

- Ships scripts/sync-uploads.sh, a copy-only rclone wrapper that fills the bucket.

## How it works

The code is strict TypeScript with no runtime dependencies. src/handler.ts holds the request pipeline and takes its origin fetch and cache as injected dependencies. The pure parts live apart: key.ts (path to key, deny list), http.ts (dates, ETags, preconditions, ranges), content-type.ts, stream.ts and config.ts.

Every request goes through fixed steps:

- A path outside the public prefix goes to the origin untouched.

- The rest of the path is percent-decoded once. Bad escapes, control characters, backslashes and empty, . or .. segments give 404.

- A decoded, lower-cased key that starts with a deny prefix gives a no-store 404. R2, the cache and the origin are never asked.

- A request with the hop header goes straight to the origin, which stops loops.

- Only GET and HEAD of a media extension go further.

- The edge cache answers if it can, including conditionals and ranges. Otherwise R2 is read and a full 200 is copied to the cache in the background.

- A miss or an R2 error falls back to the origin. If the origin is unreachable, the Worker returns 502.

A short negative cache holds repeated origin 404s for 60 seconds by default. R2 is still read first, so a file synced a second later is served at once. Ranges on an edge-cache hit are cut locally with a stream slicer, not by relying on the Cache API.

The sync script copies and never deletes:

scripts/sync-uploads.sh \
--source /var/www/example.com/wp-content/uploads \
--remote r2:your-bucket \
--rclone /usr/local/bin/rclone \
--max-age 30m

Check which path answered:

curl -sI https://example.com/wp-content/uploads/2026/01/photo.jpg | grep -i x-uploads-source

## Guard rails

- The built-in deny prefixes cannot be removed: wp-personal-data-exports/, wc-logs/, woocommerce_uploads/ and wpcf7_uploads/. They also apply under a multisite sites/<n>/ folder. EXTRA_DENY_PREFIXES adds more.

- Only media extensions are read from R2, and only the last extension counts. A .php.jpg goes out with an image content type and nosniff.

- A stored content type that a browser could run as a document (HTML, XML, JavaScript, SVG on a non-SVG extension) is replaced by the type for the extension.

- The Worker never writes to or deletes from R2, and it has no secrets. The R2 binding is native.

- Unexpected errors fail open to the origin. Deny and an unreachable origin fail closed.

- Invalid config values are replaced by defaults and logged once. EDGE_CACHE_MAX_BYTES is clamped to 64 MiB.

- Rolling back means removing the route. The origin serves uploads again at once.

## What review changed

- On a zone route the Cache API shares keys with the zone cache, so the zone's copy of a fallback response could be served as if the Worker had written it. Worker-written entries now carry an internal marker, and an unmarked or non-200 entry is treated as a miss.

- The stored content type rule was tightened. A stored type is trusted only if it is one well-formed type/subtype with no comma list, of the same kind as the extension.

- EDGE_CACHE_MAX_BYTES became a ceiling, not just a default, because the cache write can buffer a whole object for a slow client.

- In the sync script, a relative --source starting with a hyphen is now prefixed so rclone never reads it as a flag.

## Limits and what is next

- No image resizing or format conversion. Sizes WordPress makes on demand come from the origin by fallback until synced.

- Single byte ranges only. Multi-range requests get a full 200.

- The edge cache is per data centre, and the Cache API does nothing on the default Workers subdomain.

- No Unicode normalisation: keys must match file names byte for byte.

- Purging the edge cache was not tested against a live zone. The procedure follows the documentation.

- One open issue: issue 4 asks whether an origin redirect should pass its Location header through unchanged. With ORIGIN_OVERRIDE set, a redirect would name the override host. That variable is for testing only.

Test status: this is v0.1.0, tested on stubs and an in-memory bucket. 100 Vitest tests run inside the Workers runtime with an in-memory R2 bucket, and 8 bats tests cover the sync script. TypeScript, eslint and prettier are clean, and wrangler deploy --dry-run passes. CI has not yet run on GitHub, and the Worker has not been deployed to a live zone from this repo.

## Install

You need a Cloudflare account that holds both the zone and an R2 bucket, Node 22.12 or later, and Wrangler (a dev dependency). The package is not published to npm.

git clone https://github.com/IndianOpinion/uploads-on-r2.git
cd uploads-on-r2
npm ci
npm run build
npx wrangler deploy

Before deploying, copy your uploads into the bucket, and edit wrangler.toml to replace your-worker, example.com and your-bucket. Keep the route on the uploads path, not the whole zone.

[All 47 utilities](https://indianopinion.org/blog/open-source/) · [uploads-on-r2 on GitHub](https://github.com/IndianOpinion/uploads-on-r2)

Canonical: https://indianopinion.org/blog/open-source/uploads-on-r2/

AI disclosure: Every summary and comment here is written by AI and published automatically, without a person reviewing each article. We do no original reporting. How this works: https://indianopinion.org/ai-use-policy/
