Skip to content
Cello
Esc
↑↓navigate↵open⌘Jpreview
On this page

R2

R2 is object storage. A Worker reaches a bucket through an r2_buckets binding. Cello stores the objects in the fleet bucket that the node opened with --bucket, so R2 has the durability of that object store. On a node without a fleet bucket, every R2 method fails. Read the Workers API reference for the API.

Example

The R2 example reads, writes, and deletes objects in an R2 bucket.

API

  • get(key, { range, onlyIf }) returns an R2ObjectBody with a streamed body, or null. A range is an offset, a length, a suffix, or a Range header.
  • head(key) returns the object record without the body.
  • put(key, value, { httpMetadata, customMetadata, onlyIf }) takes a string, an ArrayBuffer, a typed array, a Blob, or a ReadableStream. A refused condition returns null.
  • delete(keys) removes one key or a list of keys.
  • list({ prefix, delimiter, cursor, startAfter }) returns a page of objects.
  • createMultipartUpload(key) returns a handle. uploadPart(number, value) sends one part, and complete(parts) assembles the object.

Keys and storage

Each binding has its own bucket_name, and Cello stores key <key> as the object r2/<bucket_name>/<key>. A key is 1 to 1024 bytes. A streamed put() body that grows past 8 MiB becomes a multipart upload. delete() removes up to 1000 keys in one call. Cello has no public bucket URL, no presigned URL, and no S3 endpoint, so put a Worker in front of the bytes to publish them.

The object store keeps some keys in a percent-encoded form: a key with a non-ASCII character, a control character, or one of % \ { } ^ ` [ ] " < > ~ # | * ?. For example, přehled.html becomes r2/<bucket_name>/p%C5%99ehled.html. Each empty segment becomes %, so photos/ becomes r2/<bucket_name>/photos/%, and a/b, /a/b, a//b, and a/b/ are four different objects, as in Cloudflare R2. list() returns the decoded key but walks the objects in the encoded form’s order; Cloudflare R2 lists UTF-8 byte order throughout. Where the two orders disagree — a~ sorts after aa decoded, before it encoded — a page still opens with a~, while startAfter compares decoded keys in UTF-8 byte order, so a~ is returned after startAfter: "aa" even though its encoded form a%7E sorts before aa.

startAfter bounds the first page past a key; the cursor a listing answered with continues it past exactly what the page consumed. A continuation by startAfter silently drops keys where encoded and decoded orders disagree, so page every further listing with cursor. startAfter also scans the whole prefix to find its bound, once per page, while a cursor resumes as an offset — another reason cursor is the paging knob. With a delimiter, each folder answers once per walk.

A cursor is opaque: pass it back unchanged. An unseeded listing’s cursor is the key it consumed, so --cursor also takes a plain key; a seeded listing’s cursor carries its bound with it, so the continuation replays the first page’s filter.

list() fails when it reaches an object that another tool wrote with a percent-encoded key that is not UTF-8, such as a%FF.

cello 0.5.1 and earlier removed each empty segment from a key. An object that such a version wrote under photos/ stays under photos, and list() returns it as photos.

Multipart uploads

A multipart upload lives on the node that opened it. Read Multipart upload for the part rules. A part that arrives before its predecessor waits in memory, up to 256 MiB, and cello then refuses a further part. A waiting part can be replaced. A part that already went to the object store cannot, and cello refuses that write.

Differences from Cloudflare

  • An R2 binding uses the fleet bucket under r2/<bucket_name>/.
  • The five content headers are stored as headers. customMetadata, cacheExpiry, the checksums, and the storage class are stored together as one JSON value, under the cello-r2 user-metadata name (cello_r2 on Azure Blob Storage, which refuses a hyphen in a metadata name). Objects a celld node wrote carry celld-r2 (celld_r2 on Azure) and read the same way; new writes use the new spelling. Cursors work under both spellings.
  • An object another tool wrote still reads through the binding. Its user metadata becomes its customMetadata, and its headers become its httpMetadata. Use cello r2 put to write the complete record.
  • cello r2 get|head|put|delete|list replaces wrangler r2 object. The command reads the fleet bucket directly, so it needs no running node. With --page, list prints one page — objects with httpMetadata and customMetadata, plus delimitedPrefixes, truncated and cursor (absent when the listing is complete) — the fields of a list() page other than version, checksums and storageClass; --delimiter rolls keys up into prefixes. Continue a truncated listing with --cursor, as the resume line says; --after bounds the first page past a key, and when both are given the cursor wins. A get or head of an absent key fails with exit code 1 and no object "<key>" in r2 bucket "<bucket>" on stderr; with --json it also prints {"error":"not_found","bucket":"<bucket>","key":"<key>"} on stdout first, so a caller matches the error field instead of the English message. delete of an absent key succeeds, as on R2.
  • An object version equals its content ETag, so identical content produces the same version.
  • ssecKey and jurisdiction are unavailable.
  • A conditional write cannot use a streamed body larger than 8 MiB.
  • createMultipartUpload() does not accept a checksum.
  • A multipart upload cannot resume on another node or after a restart. cello also cannot replace a part that the object store already holds.
  • Out-of-order parts can use at most 256 MiB of memory, and completion cannot change the stored part order.

The Cloudflare compatibility page lists the runtime APIs and the unsupported services. `

Was this page helpful?