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 anR2ObjectBodywith a streamed body, ornull. A range is anoffset, alength, asuffix, or aRangeheader.head(key)returns the object record without the body.put(key, value, { httpMetadata, customMetadata, onlyIf })takes a string, anArrayBuffer, a typed array, aBlob, or aReadableStream. A refused condition returnsnull.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, andcomplete(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 thecello-r2user-metadata name (cello_r2on Azure Blob Storage, which refuses a hyphen in a metadata name). Objects a celld node wrote carrycelld-r2(celld_r2on 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 itshttpMetadata. Usecello r2 putto write the complete record. cello r2 get|head|put|delete|listreplaceswrangler r2 object. The command reads the fleet bucket directly, so it needs no running node. With--page,listprints one page — objects withhttpMetadataandcustomMetadata, plusdelimitedPrefixes,truncatedandcursor(absent when the listing is complete) — the fields of alist()page other thanversion,checksumsandstorageClass;--delimiterrolls keys up into prefixes. Continue a truncated listing with--cursor, as the resume line says;--afterbounds the first page past a key, and when both are given the cursor wins. Agetorheadof an absent key fails with exit code 1 andno object "<key>" in r2 bucket "<bucket>"on stderr; with--jsonit also prints{"error":"not_found","bucket":"<bucket>","key":"<key>"}on stdout first, so a caller matches theerrorfield instead of the English message.deleteof an absent key succeeds, as on R2.- An object
versionequals its content ETag, so identical content produces the same version. ssecKeyandjurisdictionare 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. `