WebDyne::Cloudflare::R2

Future-returning buffered R2 facade. Construct with new(scope => $scope_hr, binding => 'OBJECTS'); the default binding is R2. binding() returns its name.

Interface

• get($key, range => $range_hr) returns an Object or undef.
• head($key) returns metadata without a body, or undef.
• put($key, $value, %options) accepts http_metadata, custom_metadata and storage_class and returns object metadata.
• delete($key) and delete_many(@keys) (1–1000 keys).
• list(%options) accepts prefix, cursor, delimiter, limit and include.

All operations return Futures. List results contain objects, truncated, optional cursor and delimited_prefixes. Include values are httpMetadata and customMetadata. Ranges use offset with optional length, or suffix. HTTP metadata keys use snake_case: content_type, content_language, content_disposition, content_encoding, cache_control and cache_expiry.

blob($bytes) accepts function, class or object invocation and one byte payload. Text is UTF-8; object bodies returned by get are byte strings. r2MaxObjectBytes defaults to 16 MiB. Oversized reads are rejected and unread bodies are cancelled. Streaming, multipart and conditional operations are not provided.

Errors fail with R2::Error. Invalid capabilities throw at construction. Internal validation and host-call helpers are not supported API.

Text inputs, including nested metadata keys and values, are normalized from unflagged UTF-8 without changing caller data. Invalid UTF-8, cyclic containers and duplicate normalized keys are rejected before calling the host. See the usage guide.