kotx / render

Cloudflare Worker to proxy and cache requests to R2

Render

Proxies readonly requests to Cloudflare R2 via Cloudflare Workers.

If you want an uploader, try Aster!

If you see a bug or something missing, please open an issue or pull request!

Features

• File listings (with optional hidden files)!

• Handles HEAD, GET, and OPTIONS requests
• Forwards caching headers (etag, cache-control, expires, last-modified)
• Forwards content headers (content-type, content-encoding, content-language, content-disposition)
• Caches served files using the Cache API
• Ranged requests (range, if-range, returns content-range)
• Handles precondition headers (if-modified-since, if-unmodified-since, if-match, if-none-match)
• Can serve an appended path if the requested url ends with / - Defaults to index.html in 0.5.0
• Can serve custom 404 responses if a file is not found

Setup

Configuration

Create your R2 bucket(s) if you haven't already (replace bucket_name and preview_bucket_name appropriately):

pnpm install
pnpm wrangler r2 bucket create bucket_name # required
pnpm wrangler r2 bucket create preview_bucket_name # optional

You can also do this from the Cloudflare dashboard.

Edit wrangler.toml to have the correct bucket_name and optionally, preview_bucket_name (you can set it to bucket_name) if you're going to run this locally. You can do this from a fork, if using the GitHub Actions method.

You may edit CACHE_CONTROL to the default cache-control header or remove it entirely to fall back to nothing. If you set CACHE_CONTROL to "no-store" then Cloudflare caching will not be used.

Deploying

Note: Due to how custom domains for workers work, you MUST use a route to take advantage of caching. Cloudflare may fix this soon. Also note that *.workers.dev domains do not cache responses. You MUST use a route to your own (sub)domain.

If you want to deploy render with multiple domains for one worker, check out multi-render! It uses render as a package to serve multiple buckets to multiple domains with custom configurations.

Method 1 (Local)

pnpm wrangler publish # or `pnpm run deploy`

Method 2 (GitHub Actions)

1. Fork this repository
2. Set the secrets CF_API_TOKEN (with the Edit Cloudflare Workers template) and CF_ACCOUNT_ID in the repo settings
3. Enable workflows in the Actions tab
4. Update wrangler.toml as needed (this will trigger the workflow)
5. (Optionally) set the worker route in the Cloudflare dashboard to use the Cache API

Using as a package

You may use this worker's functionality as a package by installing and importing render2:

npm install render2

Usage:

import render from "render2";
render.fetch(req, env, ctx);

You can see an awesome example with Erisa's multi-render!

Development

Install deps:

pnpm install

To launch the development server:

pnpm run dev

Notable Related Projects

• auravoid's fork adds Plausible support.
• Erisa's project multi-render add support for domain-specific configurations.

render's Issues

Add Edge-Side-Includes

Please consider adding support for Edge-Side-Includes

Remove `range-parser` dependency

R2 API can process range requests now, it seems. We can remove the range-parser dependency and directly pass the header instead.

File Not Found

It will always display that the file cannot be found, and the deployment of GitHub Action has been completed. After opening the Workers page, it will display File Not Found

0-byte files cause issues

maybe this is a Cloudflare issue or something but I'll mention it here

you can definitely create 0-byte files in R2 buckets

but trying to access them through your script results in odd behavior

using a HEAD request it returns a HTTP 204 (No Content) which is sensible

however using a GET request, the browser gets a HTTP 500 (Internal Server Error) along with some HTML claiming there was an error 1101

if I test it in the worker dashboard this is what I see:

Not all files listed

In the case where I have around 17,000 files in a directory, only the first 600-900 are shown in the directory listing.

Any ideas?

Etag needs to be quoted?

Hey!

In src/index.ts, it is said that the R2 API requires etag to not be quoted. I don't find this information in the API documentation. Moreover, with Miniflare, etag should be left quoted, otherwise, there is no match.

Remove type from <style> tag -- causes WC3 validation warning

As per recent changes to the WC3 validator, <style type="text/css"> now generates a warning as the type="text/css" is deprecated and not recommended to include

can this be changed to just <style>

Turn off cache?

If an object in R2 is deleted then the cache still serves the old file. Even if I upload a new file at the same path then the old file is still served.

I suggest a way to either (a) opt-out of the cache completely, or (b) provide some way to manually invalidate the cache. Any ideas? Particularly ideas for (b)?

Configuring CORS (Access-Control-Allow-Origin)

I would like to know how I could apply an Access-Control-Allow-Origin to a certain domain from R2, could it be done with this worker? Currently the content of my bucket is not shown because of this.

"wrangler publish" fails, "Error: missing field `type`"

I'm very new at this and having a bad time

The wrangler.toml does not have a "type" entry so "wrangler publish" fails like this:

$ wrangler r2 bucket list
Error: missing field `type`

I tried putting type = "javascript" in the file but it did not work

$ wrangler publish
✨  Basic JavaScript project found. Skipping unnecessary build!
Error: The entrypoint of your Worker (dist/index.js) could not be found.

I tried type = "typescript" but also did not work

$ wrangler publish
Error: enum TargetType does not have variant constructor typescript

I tried some other random guesses but nothing that worked

cache.put always fired

Hi,
thanks for sharing this great tool.
I've a question:
is there a specific reason for having cache.put fired also when the response is already in cache (previous cache.match)?

Thanks!

how to upload

hy there can u help me I'm new in this stuff I don't understand how to upload file larger then 300mb I checked the guide but If try to upload with guide then I have to change code every single time I upload file in r2 through Wrangler CLI if u have any suggestion to to upload file larger then 300mb then please let mr know..

site showing errors always in the first requests to a file

I installed the code in a worker so that I could display mainly images, unfortunately the script always presents errors in the first requests of some files, after a few attempts the photo is displayed to the user

first try:

after I reload the page a few times:

after I reload the page a few times, the first image is displayed but the others keep showing error:

the workers panel:

this error seems to be occasional, there are photos that load without problems, others that don't load on the first try and some load only after I reload the pages many times, at first I thought it could be a problem with Cloudflare R2 but I didn't find any problem in the status page.

Way to invalidate cache when object at R2 path changes?

Hey there, this is a super well done library. Thank you!

I'm not sure if I'm missing something in your documentation or if it's just not possible, but how can I invalidate a url when the object at a R2 path changes? For example, when I'm updating the contents of my static website.

add variable for HTML language declaration?

the <html> without a language specified causes a WC3 validation warning

this should probably default to English (<html lang="en">) since the UI elements are in English, however, a person might want to change it if their filenames are in another language

could this potentially be added as a variable in wrangler.toml

List items in bucket

A handy feature would be the ability to list objects. I was thinking maybe if on a get request a file isn't found, try list objects with the the path as the prefix.

I can do a PR if you think this is a good idea.

Chinese characters may display as garbled text

The possible reason is that the Chinese characters encoded in UTF-8 were read in GBK format.

An example:
搴斿鐗规畩鏃舵湡鐨勫簲鎬ョ墿璧勬竻鍗晇1.2.pdf
Actually should be:
应对特殊时期的应急物资清单v1.2.pdf

Cache hit ignored for 304 response

Hi, just noticed that you are checking for response.ok() to see if cache was hit. This will fail if cache returned a 304 response to a correct etag.

Music playing CORS/Cache/worker error

Whenever I try playing music on my website, I get either Failed to load resource: net::ERR_CACHE_OPERATION_NOT_SUPPORTED

or CORS error like
.
Googling returned 0 results, what can I do? I've been fighting with CORS since I thought that's the issue, but this made me think CORS might not be the issue. could it be the worker?
inside the wrangler.toml file, I set my origins to:

ALLOWED_ORIGINS = "https://djkato.net/"

All other files load just fine(eg videos, images). Just audio seems messed up, regardless if crossorigin="anonymous" is set via html property on the audio element, or before initializing the web Audio API context through HTMLMediaElement.crossOrigin = "anonymous", or even not set anywhere. if I don't set it anywhere, I get "audio source set to none due to cors issues" or something along those lines.
Any tips on solving this? Thanks!