Storage
R2
Run R2 buckets on OpenOrange, stored in a Rivet Actor or in your own S3-compatible store.
Runs on Actor SQLite by default, or any S3-compatible store per bucket
- Works
- Objects, metadata, checksums, conditional and range reads, listing, and multipart uploads, on a Rivet Actor or on your S3-compatible store
- Differs
- On the default backend, one Rivet Actor holds the whole bucket, and large objects are slow.
put()takes a stream of any length. - Missing
ssecKey(customer-provided encryption keys) and anorange r2command- Migration
- Not supported
orange migratedoes not copy buckets. To keep the data on Cloudflare, point the binding at the R2 bucket through its S3 API.
- Configure
r2_buckets- Scales by
- S3 or bucket
- Checks
- 1 pass
An R2 bucket on OpenOrange is a Rivet Actor that stores your objects, or a
bucket in your own S3-compatible store. Your R2 code and wrangler.jsonc run
unchanged.
Quickstart
This builds a small file service. The full examples/r2
adds metadata, checksums, conditional requests, listing, and multipart uploads.
-
Bind the bucket
Add an
r2_bucketsentry towrangler.jsonc. Orange creates the bucket on first use.{ "name": "r2", "main": "src/index.ts", "compatibility_date": "2026-09-03", "r2_buckets": [{ "binding": "FILES", "bucket_name": "files" }] } -
Store and serve files
Call the bucket from
env, as on Cloudflare.writeHttpMetadata()copies the storedContent-Typeand the other HTTP headers to the response.interface Env { FILES: R2Bucket; } export default { async fetch(request, env): Promise<Response> { const key = /^\/files\/(.+)$/.exec(new URL(request.url).pathname)?.[1]; if (key === undefined) return new Response("Try /files/<key>", { status: 404 }); if (request.method === "PUT") { await env.FILES.put(key, request.body, { httpMetadata: request.headers }); return new Response(null, { status: 201 }); } const object = await env.FILES.get(key); if (object === null) return new Response(`No file named ${key}`, { status: 404 }); const headers = new Headers(); object.writeHttpMetadata(headers); headers.set("etag", object.httpEtag); return new Response(object.body, { headers }); }, } satisfies ExportedHandler<Env>; -
Run it
orange devlists the bucket as a Rivet Actor.orange dev Binding Resource Runs on env.FILES R2 Bucket Rivet Actor · filesUpload a file and read it back. It survives a restart of
orange dev.curl -X PUT localhost:8787/files/notes/a.txt -H 'content-type: text/plain' --data-binary 'hello world' curl localhost:8787/files/notes/a.txt hello world
How it works
- Each bucket is one Rivet Actor that keeps your objects in its SQLite
database. It runs on your machine under
orange dev, and on your Rivet cluster afterorange deploy. - For production, keep each bucket in your own S3-compatible store, such as Amazon S3 or Cloudflare R2. Set its endpoint and keys, and your code stays the same. See Store a bucket in S3 instead.
AI context Compatibility, limits and details
Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.
Compatibility
| Feature | Status | Notes |
|---|---|---|
head(), get(), and put() | Supported | |
delete() with one key or an array | Supported | |
list() with prefix, delimiter, cursor, startAfter, limit, and include | Supported | include is always honored, as with the r2_list_honor_include compatibility flag. |
onlyIf and range, as objects or as Headers | Supported | A failed condition makes get() return the object without a body, and put() return null. |
httpMetadata and customMetadata | Supported | |
A checksum on put(): md5, sha1, sha256, sha384, or sha512 | Supported | A mismatch fails the put and keeps the stored object. |
A ReadableStream body on put() | Supported | Any length. Cloudflare requires a known length. |
Multipart uploads: createMultipartUpload(), resumeMultipartUpload(), uploadPart(), abort(), and complete() | Supported | |
writeHttpMetadata(), and arrayBuffer(), bytes(), text(), json(), and blob() on a body | Supported | |
storageClass | Partial | Stored as given, and not checked. |
ssecKey | Not supported | Rejects with a NotSupportedError. |
wrangler r2 commands | Not supported | orange r2 prints that the command is not implemented. |
Two differences reach most projects:
- On the default backend, one Rivet Actor holds the whole bucket. Rivet’s storage limit for one actor bounds the bucket, and large objects are slow. Cloudflare buckets have no size limit. Use S3 for large buckets.
- The S3 backend changes a few object details, such as the case of custom
metadata keys and the precision of
uploaded. See S3 backend.
Limits
| What | Limit | What happens over it |
|---|---|---|
| A key | 1,024 bytes | The call rejects with The specified object name is not valid. (10020). |
| Custom metadata | 2,048 bytes, counted as R2 counts them | The call rejects with Your metadata headers exceed the maximum allowed metadata size. (10012). |
One put() or one part | 5 GiB minus 5 MiB | The call rejects with Your proposed upload exceeds the maximum allowed object size. (100100). |
Keys in one list() | 1 to 1,000 | The call rejects with MaxKeys params must be positive integer <= 1000. (10022). |
| Multipart parts | 5 MiB or more and all one size, except the last part. Part numbers 1 to 10,000. | complete() rejects. A part number out of range throws a TypeError. |
| One bucket on the default backend | Rivet’s storage limit for one actor | Use the S3 backend. |
| A read on the default backend | 5 minutes | The read can fail if the object is overwritten or deleted during it. |
What Orange reads
In wrangler.jsonc | On Orange |
|---|---|
bucket_name | Names the bucket. Under orange dev, a preview_bucket_name wins, as in wrangler dev. orange serve and a deployed Worker skip preview_bucket_name, as wrangler deploy does. |
| The same bucket name on two bindings | One bucket, also for every Worker of one orange dev session. See Multiple Workers. |
jurisdiction | Ignored. |
Store a bucket in S3 instead
Set these variables to keep a bucket in an S3-compatible store. The Worker
code does not change. <BUCKET> is the bucket_name in uppercase, with each
character other than A-Z and 0-9 changed to _, so files becomes
FILES.
| Variable | Required | Value |
|---|---|---|
ORANGE_R2_<BUCKET>_S3_ENDPOINT | Yes | The S3 endpoint URL. Setting it moves this bucket to S3. |
ORANGE_R2_<BUCKET>_S3_ACCESS_KEY_ID | Yes | The access key. Falls back to AWS_ACCESS_KEY_ID. |
ORANGE_R2_<BUCKET>_S3_SECRET_ACCESS_KEY | Yes | The secret key. Falls back to AWS_SECRET_ACCESS_KEY. |
ORANGE_R2_<BUCKET>_S3_BUCKET | No | The S3 bucket name. Defaults to bucket_name. |
ORANGE_R2_<BUCKET>_S3_REGION | No | The S3 region. Falls back to AWS_REGION, then auto. |
# .dev.vars
ORANGE_R2_FILES_S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
ORANGE_R2_FILES_S3_REGION=us-east-1
ORANGE_R2_FILES_S3_ACCESS_KEY_ID=<access key ID>
ORANGE_R2_FILES_S3_SECRET_ACCESS_KEY=<secret access key>Orange reads them from the shell environment, .dev.vars, or .env, and a
value from the shell wins. On a cluster, set them on the runner pool as
secrets, with orange deploy --secrets-file.
The S3 bucket must already exist. orange doctor shows the store that each
bucket uses.
| Provider | ..._S3_ENDPOINT | ..._S3_REGION | Keys |
|---|---|---|---|
| Amazon S3 | https://s3.<region>.amazonaws.com | The bucket’s region, such as us-east-1 | An IAM access key ID and secret access key |
| Cloudflare R2 | https://<account ID>.r2.cloudflarestorage.com | auto (the default) | The access key ID and secret access key of an R2 API token |
| Google Cloud Storage | https://storage.googleapis.com | auto (the default) | An HMAC key: the access ID, which starts with GOOG, and the secret |
| Backblaze B2 | https://s3.<region>.backblazeb2.com | The region in the endpoint, such as us-west-004 | An application key ID and application key |
| MinIO that you run | http://127.0.0.1:9000 | auto (the default) | The MinIO user and password. See Run MinIO locally. |
Orange sends path-style requests, such as <endpoint>/<bucket>/<key>, so a
store that accepts only virtual-hosted requests does not work. For example,
Tigris buckets created
after February 19, 2025 accept only virtual-hosted requests.
Run MinIO locally
Start MinIO and create the bucket, then point the bucket at it:
docker run -p 9000:9000 minio/minio server /data # then create the "files" bucket
export ORANGE_R2_FILES_S3_ENDPOINT=http://127.0.0.1:9000
export ORANGE_R2_FILES_S3_ACCESS_KEY_ID=minioadmin
export ORANGE_R2_FILES_S3_SECRET_ACCESS_KEY=minioadmin
orange devS3 settings
- For
ORANGE_R2_*variables, the shell wins over.dev.vars,.env, andvars. For theAWS_*fallbacks, the Worker’s variables win over the shell. - An empty
ORANGE_R2_<BUCKET>_S3_ENDPOINTleaves the bucket on the default backend. An empty value in the shell also wins over the one in.dev.vars. - With the endpoint set and a key missing, the Worker does not start. The
error is
R2 bucket "<bucket>" sets ORANGE_R2_<BUCKET>_S3_ENDPOINT, so it also needs ORANGE_R2_<BUCKET>_S3_ACCESS_KEY_ID and ORANGE_R2_<BUCKET>_S3_SECRET_ACCESS_KEY (or AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY).orange doctorfails its R2 Bucket check with the same text. orange doctorshowsenv.<BINDING> · <endpoint>for a bucket on S3, andenv.<BINDING> · Rivet Actorfor one on the default backend.- When the store is down, calls fail with an R2 internal error that names the
bucket and the endpoint:
put: We encountered an internal error. Please try again. (S3 bucket "<bucket>" at <endpoint>: <cause>) (10001).
Errors
- A storage error is an
Errorwith the message<action>: <message> (<code>), such asput: The specified object name is not valid. (10020), as workerd reports it. The codes and messages are Miniflare’s. - A checksum mismatch fails with code 10037 and names the algorithm, the
provided value, and the actual value. A put may carry only one checksum:
You cannot specify multiple hashing algorithms. - An unsatisfiable range fails with
The requested range is not satisfiable (10039). list()takes onlyhttpMetadataandcustomMetadataininclude. Another value throws aRangeError.- On the default backend,
complete()fails with code 10011 when a part other than the last is under 5 MiB, with 10048 when those parts differ in size or the last part is larger, and with 10025 when a part or its ETag is unknown. ssecKeyonget(),put(),createMultipartUpload(), oruploadPart()rejects with aNotSupportedError:<action>: ssecKey (customer-provided encryption keys) is not supported by OpenOrange yet.- Custom metadata counts each name and value by its length, or twice its length when it has a character above U+00FF, as Miniflare counts it.
Backends
Each bucket uses one of two backends, picked by the ORANGE_R2_<BUCKET>_S3_*
variables. Both apply the same argument checks, limits, and error text, from
workerd and the local R2 backend of wrangler dev.
Default backend
- One actor per bucket keeps the metadata and the bodies in its SQLite
database. Under
orange dev, it lives in the project’s.open-orangedirectory. - The bucket is the actor
openorange:r2-bucket, shown asR2 buckets (Orange), with the bucket name as its key. Itsobjectstable lists the objects. - A put cuts the body into 512 KiB chunks and writes each chunk with its own request, so each SQLite commit stays far below Rivet’s limit. A final request commits the object, so a reader never sees a partial object.
- If the upload stops, for example because
orange devrestarts, the previous object stays visible. - A read streams the chunks over one WebSocket for each body.
- An alarm deletes the chunks of overwritten, deleted, and abandoned objects 5 minutes later.
S3 backend
- Each call becomes one or more S3 requests. Orange evaluates
onlyIfand ranges itself, with the same rules as the default backend. - A conditional put reads the current object first, then writes with
If-MatchorIf-None-Match, so a concurrent write makes the put returnnull. - A put from a stream first writes the body to a temporary file, because S3 needs the length before the upload starts.
list()withincludereads each listed object’s metadata with one more request.delete()sends oneDeleteObjectrequest for each key, 16 at a time.
Deviations
These add to the differences under Compatibility.
Both backends:
delete()with an array has no 1,000-key limit.
The default backend:
- Large objects are slow. On a development machine, a 30 MiB object takes about 1.5 seconds to write and 4.5 seconds to read.
- Incomplete multipart uploads are kept until they are completed or aborted. Cloudflare aborts them after 7 days.
The S3 backend:
versionis the S3 version ID when bucket versioning is on. Otherwise, it is the ETag.uploadedhas one-second precision.- S3 returns custom metadata keys in lowercase. Orange keeps the original case
of keys that have capital letters in one extra metadata entry,
orange-r2-key-case, and restores it on reads. The entry counts toward the S3 2 KB metadata limit, and other S3 clients see it. Two keys that differ only in case cannot both be stored. - S3 stores a default content type when the put has none.
checksumsreturns MD5 for single-part objects, plus SHA-1 or SHA-256 when the put gave one. A SHA-384 or SHA-512 checksum is verified but not stored.- Completing a multipart upload with no parts fails. Aborting an unknown upload succeeds.
- Part ETags are the MD5 of the part.
- A conditional put is atomic only if the store supports
If-MatchandIf-None-Matchon writes. AWS S3, MinIO, and R2 support them.
Conformance
tests/bindings/r2.test.ts runs the same cases through orange dev against both
backends. The S3 run uses a real MinIO server. The cases cover:
- Byte-equal round trips for 0 B, 1 B, 512 KiB ± 1 B, and 30 MiB, with MD5 ETags.
- Failed
onlyIfonget()andput(), as an object and asHeaders. - Ranges that cross a chunk boundary, and an unsatisfiable range.
- Two concurrent puts on one key while reads run.
- Checksum mismatches, metadata with the case of each key, listing, and multipart uploads.
- Invalid keys and
ssecKey.
The default backend also has a test that restarts orange dev during a put.
The S3 backend also has a test for an S3 endpoint that is down.
tests/cli/orange-settings.test.ts checks that an ORANGE_R2_<BUCKET>_S3_* value
in .dev.vars moves a bucket to S3. tests/examples/runnable-examples.test.ts runs
examples/r2. workerd’s upstream r2-test passes 0 of 1,
because it needs a mock R2 server that the conformance runner does not
configure.
Recorded results from the conformance run of 2026-11-10 (Orange ea40348), 1,670 of 1,851 tests passing across every area. Each check is works when every result passed and partial when some did. The full feature matrix is on the compatibility page.
R2
| Check | Status | Results |
|---|---|---|
| R2 | Works |
|