Skip to content
Storage / R2

Storage

R2

Run R2 buckets on OpenOrange, stored in a Rivet Actor or in your own S3-compatible store.

Pluggable

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 an orange r2 command
Migration
Not supported orange migrate does 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.

  1. Bind the bucket

    Add an r2_buckets entry to wrangler.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" }]
    }
  2. Store and serve files

    Call the bucket from env, as on Cloudflare. writeHttpMetadata() copies the stored Content-Type and 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>;
  3. Run it

    orange dev lists the bucket as a Rivet Actor.

    orange dev
      Binding     Resource    Runs on
      env.FILES   R2 Bucket   Rivet Actor · files

    Upload 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 after orange 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

FeatureStatusNotes
head(), get(), and put()Supported
delete() with one key or an arraySupported
list() with prefix, delimiter, cursor, startAfter, limit, and includeSupportedinclude is always honored, as with the r2_list_honor_include compatibility flag.
onlyIf and range, as objects or as HeadersSupportedA failed condition makes get() return the object without a body, and put() return null.
httpMetadata and customMetadataSupported
A checksum on put(): md5, sha1, sha256, sha384, or sha512SupportedA mismatch fails the put and keeps the stored object.
A ReadableStream body on put()SupportedAny 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 bodySupported
storageClassPartialStored as given, and not checked.
ssecKeyNot supportedRejects with a NotSupportedError.
wrangler r2 commandsNot supportedorange 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

WhatLimitWhat happens over it
A key1,024 bytesThe call rejects with The specified object name is not valid. (10020).
Custom metadata2,048 bytes, counted as R2 counts themThe call rejects with Your metadata headers exceed the maximum allowed metadata size. (10012).
One put() or one part5 GiB minus 5 MiBThe call rejects with Your proposed upload exceeds the maximum allowed object size. (100100).
Keys in one list()1 to 1,000The call rejects with MaxKeys params must be positive integer <= 1000. (10022).
Multipart parts5 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 backendRivet’s storage limit for one actorUse the S3 backend.
A read on the default backend5 minutesThe read can fail if the object is overwritten or deleted during it.

What Orange reads

In wrangler.jsoncOn Orange
bucket_nameNames 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 bindingsOne bucket, also for every Worker of one orange dev session. See Multiple Workers.
jurisdictionIgnored.

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.

VariableRequiredValue
ORANGE_R2_<BUCKET>_S3_ENDPOINTYesThe S3 endpoint URL. Setting it moves this bucket to S3.
ORANGE_R2_<BUCKET>_S3_ACCESS_KEY_IDYesThe access key. Falls back to AWS_ACCESS_KEY_ID.
ORANGE_R2_<BUCKET>_S3_SECRET_ACCESS_KEYYesThe secret key. Falls back to AWS_SECRET_ACCESS_KEY.
ORANGE_R2_<BUCKET>_S3_BUCKETNoThe S3 bucket name. Defaults to bucket_name.
ORANGE_R2_<BUCKET>_S3_REGIONNoThe 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_REGIONKeys
Amazon S3https://s3.<region>.amazonaws.comThe bucket’s region, such as us-east-1An IAM access key ID and secret access key
Cloudflare R2https://<account ID>.r2.cloudflarestorage.comauto (the default)The access key ID and secret access key of an R2 API token
Google Cloud Storagehttps://storage.googleapis.comauto (the default)An HMAC key: the access ID, which starts with GOOG, and the secret
Backblaze B2https://s3.<region>.backblazeb2.comThe region in the endpoint, such as us-west-004An application key ID and application key
MinIO that you runhttp://127.0.0.1:9000auto (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 dev

S3 settings

  • For ORANGE_R2_* variables, the shell wins over .dev.vars, .env, and vars. For the AWS_* fallbacks, the Worker’s variables win over the shell.
  • An empty ORANGE_R2_<BUCKET>_S3_ENDPOINT leaves 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 doctor fails its R2 Bucket check with the same text.
  • orange doctor shows env.<BINDING> · <endpoint> for a bucket on S3, and env.<BINDING> · Rivet Actor for 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 Error with the message <action>: <message> (<code>), such as put: 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 only httpMetadata and customMetadata in include. Another value throws a RangeError.
  • 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.
  • ssecKey on get(), put(), createMultipartUpload(), or uploadPart() rejects with a NotSupportedError: <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-orange directory.
  • The bucket is the actor openorange:r2-bucket, shown as R2 buckets (Orange), with the bucket name as its key. Its objects table 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 dev restarts, 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 onlyIf and ranges itself, with the same rules as the default backend.
  • A conditional put reads the current object first, then writes with If-Match or If-None-Match, so a concurrent write makes the put return null.
  • A put from a stream first writes the body to a temporary file, because S3 needs the length before the upload starts.
  • list() with include reads each listed object’s metadata with one more request.
  • delete() sends one DeleteObject request 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:

  • version is the S3 version ID when bucket versioning is on. Otherwise, it is the ETag.
  • uploaded has 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.
  • checksums returns 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-Match and If-None-Match on 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 onlyIf on get() and put(), as an object and as Headers.
  • 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
  • Pass: example: r2