<!-- Modified by Ryuz Corp (Cello): r2 list --delimiter/--page/--cursor; startAfter bounds the first page, cursor pages; r2 head/get --json answers an absent key with a not_found error object. -->
# R2

[R2](https://developers.cloudflare.com/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](https://developers.cloudflare.com/r2/api/workers/workers-api-reference/)
for the API.

## Example

The [R2 example](https://github.com/ryuzcorp/cello/tree/main/examples/r2) reads, writes, and deletes objects in an R2
bucket.

<!-- cello-example: r2 -->

## 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](https://developers.cloudflare.com/r2/objects/multipart-objects/)
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](/cloudflare-compat#services) page lists the
runtime APIs and the unsupported services.
`