cloudflare-r2-cli 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ceadf052d3952605f7b5c2d6adf2bb1baae97a8bcb00683713434916a7dc068
-  data.tar.gz: 9e53105d7191fa1385f20eae36e936da2c3f1bb0700204c32b65591424ef0fd8
+  metadata.gz: 3195ca7161952b3ef9a5e7cc6e6d1afb4af82c631364a6786f4b1d4aeaace272
+  data.tar.gz: ca9017f232ee7a6a8a15048dfc6dd895e490f9ac18eb442dfb7e518deb89830d
 SHA512:
-  metadata.gz: bfcd9ae92ac95ae4184f55099d0d324c40cc41d86698f6fd238aca320e436df6d22b71c3f21a8748a985fc2be14335b618493bbec1fd67c886442492b7efecd9
-  data.tar.gz: f39eeffa35d7b63bf58cb7010654c17c5154d28f1fa31069f6b13274c2ca8a9ac2469b368191b9c7fc1b3995e7e8076d279e56d011cf022f40256d7870896348
+  metadata.gz: 7166d020132b6cabf2835a41a8cca93531eb58e4b65102ca8f9d8b9a16b9055eb460578f346a4b38cf15e757d3f5581e14da22eaf2b3b893497deabfb4de53d8
+  data.tar.gz: 331b10be069ca8262aceb8ebffebddaedc99c4cf806a4ff35eae5679eeed7304ef7b64079f7d4e66d4c4370767d6859f8e9cce72b776cf1f745bc38c6c88ff78

data/CHANGELOG.md

@@ -3,7 +3,89 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.2.0] - 2026-09-21
+
+### Added
+
+* `r2 exists` — checks whether an object exists in the configured bucket,
+  exiting with status code `1` when it does not.
+* `r2 list --prefix` — lists only the objects whose keys start with the given
+  prefix.
+* `r2 delete --force` — deletes an object without asking for confirmation.
+* Automatic `Content-Type` definition on upload, based on the object key.
+* Automatic retries with exponential backoff for transient network failures
+  in every storage operation.
+* `R2::ContentType` — maps the object key extension to a content type.
+* `R2::Retry` — retry policy with exponential backoff shared by the storage
+  operations.
+* `R2::Errors::ConfirmationRequiredError` and `R2::Errors::AbortedError`.
+
+### Changed
+
+* `r2 delete` now asks for confirmation before deleting. In non-interactive
+  executions (scripts and pipelines) the deletion requires `--force`.
+* `r2 list` now follows the pagination of the bucket, listing every object
+  instead of only the first page.
+* `Storage#list` accepts a `prefix` and lists every page of the bucket.
+* `Storage#upload` accepts an explicit `content_type` and rewinds the streamed
+  content before every attempt.
+* `Storage#exists?` — checks the existence of an object using its metadata.
+* Restructured the documentation to cover the new commands, options and
+  reliability behavior.
+
+## [1.2.0] - 2026-09-21
+
+### Added
+
+* `r2 exists` — checks whether an object exists in the configured bucket,
+  exiting with status code `1` when it does not.
+* `r2 list --prefix` — lists only the objects whose keys start with the given
+  prefix.
+* `r2 delete --force` — deletes an object without asking for confirmation.
+* Automatic `Content-Type` definition on upload, based on the object key.
+* Automatic retries with exponential backoff for transient network failures
+  in every storage operation.
+* `R2::ContentType` — maps the object key extension to a content type.
+* `R2::Retry` — retry policy with exponential backoff shared by the storage
+  operations.
+* `R2::Errors::ConfirmationRequiredError` and `R2::Errors::AbortedError`.
+
+### Changed
+
+* `r2 delete` now asks for confirmation before deleting. In non-interactive
+  executions (scripts and pipelines) the deletion requires `--force`.
+* `r2 list` now follows the pagination of the bucket, listing every object
+  instead of only the first page.
+* `Storage#list` accepts a `prefix` and lists every page of the bucket.
+* `Storage#upload` accepts an explicit `content_type` and rewinds the streamed
+  content before every attempt.
+* `Storage#exists?` — checks the existence of an object using its metadata.
+* Restructured the documentation to cover the new commands, options and
+  reliability behavior.
+
+## [1.1.0] - 2026-09-09
+
+### Added
+
+* `r2 download` — downloads an object from the configured bucket, with
+  `--output` to choose a custom destination path.
+* `r2 upload --key` — stores the uploaded file under a custom object key.
+* Global `--verbose` flag — writes detailed diagnostic information to the
+  error output during execution.
+* Internal logging support in the CLI and storage layers.
+* `R2::Errors::ObjectNotFoundError` for missing objects.
+
+### Changed
+
+* Standardized success messages across commands:
+  * `Uploaded successfully: <key>`
+  * `Downloaded successfully: <destination>`
+  * `Deleted successfully: <key>`
+* Restructured the `README` with a table of contents and documentation for
+  the new command, options and global flag.
+* Integrated the documentation into the repository: architecture, features
+  and security guides now live in `docs/`, replacing the dedicated docs
+  branch.
 
 ## [1.0.0] - 2026-08-30
 
@@ -21,5 +103,7 @@ First stable release of `cloudflare-r2-cli`.
 * Unit, integration and E2E test suites.
 * Continuous integration via GitHub Actions.
 
-[Unreleased]: https://github.com/rpzerosixcode/cloudflare-r2-cli/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/rpzerosixcode/cloudflare-r2-cli/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/rpzerosixcode/cloudflare-r2-cli/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/rpzerosixcode/cloudflare-r2-cli/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/rpzerosixcode/cloudflare-r2-cli/releases/tag/v1.0.0

data/README.md

@@ -2,6 +2,24 @@
 
 Ruby CLI to manage objects on Cloudflare R2 from the terminal.
 
+## Table of Contents
+
+* [Requirements](#requirements)
+* [Installation](#installation)
+* [Configuration](#configuration)
+* [Usage](#usage)
+  * [Upload](#upload)
+  * [Download](#download)
+  * [Delete](#delete)
+  * [List](#list)
+  * [Exists](#exists)
+  * [Global Options](#global-options)
+* [Reliability](#reliability)
+* [Testing](#testing)
+* [Changelog](#changelog)
+* [License](#license)
+* [Documentation](#documentation)
+
 ## Requirements
 
 * Ruby **3.3** or higher.
@@ -21,40 +39,49 @@ $ git clone https://github.com/rpzerosixcode/cloudflare-r2-cli.git
 $ cd cloudflare-r2-cli
 $ bundle install
 $ bundle exec rake build
-$ gem install pkg/cloudflare-r2-cli-1.0.0.gem
+$ gem install pkg/cloudflare-r2-cli-1.2.0.gem
 ```
 
-## Usage
-
-### Configuration
+## Configuration
 
 Before using the CLI, define the required environment variables:
 
-| Variable               | Description                                        |
-| ---------------------- | -------------------------------------------------- |
-| `R2_ACCESS_KEY_ID`     | Cloudflare R2 S3 access key ID.                    |
-| `R2_SECRET_ACCESS_KEY` | Cloudflare R2 S3 secret access key.                |
-| `R2_ENDPOINT`          | Cloudflare R2 S3-compatible endpoint.              |
+| Variable               | Description                                                        |
+| ---------------------- | ------------------------------------------------------------------ |
+| `R2_ACCESS_KEY_ID`     | Cloudflare R2 S3 access key ID.                                    |
+| `R2_SECRET_ACCESS_KEY` | Cloudflare R2 S3 secret access key.                                |
+| `R2_ENDPOINT`          | Cloudflare R2 S3-compatible endpoint.                              |
 | `R2_REGION`            | Region of the S3-compatible endpoint. *(optional, default `auto`)* |
-| `R2_BUCKET`            | Default bucket used by the CLI.                    |
+| `R2_BUCKET`            | Default bucket used by the CLI.                                    |
 
-A fillable template is available in [`.env.example`](.env.example).
+A fillable template is available in `.env.example`.
 
-Credentials are read only from environment variables and must never be
-inserted into code or versioned files. See
-[`docs/SECURITY.md`](docs/SECURITY.md) for more details.
+Credentials are read only from environment variables and must never be inserted into code or versioned files. If an access key is accidentally exposed, revoke it immediately through the Cloudflare dashboard and generate a new one.
+
+## Usage
 
 ### Upload
 
-Uploads an image to the configured bucket:
+Uploads a file to the configured bucket:
 
 ```console
 $ r2 upload image.jpg
 $ r2 upload ./images/photo.png
+$ r2 upload ./images/photo.png --key uploads/photo.png
+```
+
+By default, the object key in the bucket is the name of the given file. Use `--key` to store the object under a custom key. The `Content-Type` of the object is defined automatically from its key extension (`application/octet-stream` when the extension is unknown). On success, a confirmation message is displayed.
+
+### Download
+
+Downloads a file stored in the configured bucket:
+
+```console
+$ r2 download image.jpg
+$ r2 download image.jpg --output ./images/photo.png
 ```
 
-The object key in the bucket will be the name of the given file. On success,
-a confirmation message is displayed.
+By default, the content is written to a file with the object key base name in the current directory. Use `--output` to choose a custom destination path. On success, a confirmation message is displayed.
 
 ### Delete
 
@@ -62,9 +89,17 @@ Deletes a file stored in the configured bucket:
 
 ```console
 $ r2 delete image.jpg
+$ r2 delete image.jpg --force
+```
+
+The deletion is confirmed before the request is sent:
+
+```console
+$ r2 delete image.jpg
+Delete "image.jpg" from the bucket? [y/N]
 ```
 
-The operation is confirmed by the result of the deletion returned by the service.
+The operation only proceeds with an affirmative answer (`y` or `yes`). Use `--force` to delete without confirmation, which is required in non-interactive executions, such as scripts and pipelines, where the confirmation cannot be requested. On success, a confirmation message is displayed.
 
 ### List
 
@@ -72,17 +107,55 @@ Lists the files stored in the configured bucket:
 
 ```console
 $ r2 list
+$ r2 list --prefix uploads/
+```
+
+Every object is listed, following the pagination of the bucket. Use `--prefix` to list only the objects whose keys start with the given prefix.
+
+### Exists
+
+Checks whether an object exists in the configured bucket:
+
+```console
+$ r2 exists image.jpg
+```
+
+The exit status is `0` when the object exists and `1` when it does not, which allows the command to be used in scripts:
+
+```console
+$ r2 exists image.jpg
+Object exists: image.jpg
+$ r2 exists missing.jpg
+Object not found: missing.jpg
+```
+
+### Global Options
+
+Every command accepts the global `--verbose` flag, which writes detailed diagnostic information to the error output without changing the standard output:
+
+```console
+$ r2 list --verbose
+$ r2 upload image.jpg --verbose
+$ r2 download image.jpg --verbose
+$ r2 delete image.jpg --force --verbose
+$ r2 exists image.jpg --verbose
 ```
 
-On any error, the CLI displays the corresponding message on the error output
-and exits with status code `1`.
+On any error, the CLI displays the corresponding message on the error output and exits with status code `1`.
+
+## Reliability
+
+### Automatic retries
+
+Requests that fail due to transient network failures are retried automatically with exponential backoff: 3 attempts in total, waiting 0.5s and then 1s between them, capped at 5s. Failures that are not transient, such as missing credentials or an invalid bucket, are reported immediately.
+
+The retries are applied to every storage operation and restart from the beginning of the data: uploaded content is rewound and downloaded content is written from the start again, so a retried request never uploads an empty body or leaves a partially written file.
 
-## Development
+### Pagination
 
-The development guidelines, branches and commits are described in
-[`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md).
+`r2 list` follows the pagination of the bucket, requesting every page until the last one, so all objects are listed regardless of the amount of keys in the bucket.
 
-### Tests
+## Testing
 
 Run the full suite (unit, integration and E2E):
 
@@ -98,20 +171,20 @@ $ bundle exec rake integration
 $ bundle exec rake e2e
 ```
 
-The E2E tests require real Cloudflare R2 credentials, provided by the `.env`
-file or by the environment. Without them, the scenarios are marked as
-pending and do not fail.
+The E2E tests require real Cloudflare R2 credentials, provided by the `.env` file or by the environment. Without them, the scenarios are marked as pending and do not fail.
 
-## Documentation
+## Changelog
 
-* [Architecture](docs/ARCHITECTURE.md) — Overview of the project architecture.
-* [Changelog](CHANGELOG.md) — Version history of the project.
-* [Decisions](docs/DECISIONS.md) — Architecture and project decisions.
-* [Features](docs/FEATURES.md) — Planned and implemented features.
-* [Roadmap](docs/ROADMAP.md) — Planned evolution of the project.
-* [Security](docs/SECURITY.md) — General security guidelines of the project.
-* [Development](docs/DEVELOPMENT.md) — Development guidelines of the project.
+See [`CHANGELOG.md`](CHANGELOG.md) for the version history of the project.
 
 ## License
 
-[MIT License](./LICENCE) — Terms of use and distribution of the project.
+[MIT License](./LICENSE) — Terms of use and distribution of the project.
+
+## Documentation
+
+Additional guides are versioned with the code in the `docs/` directory:
+
+* [Features](docs/FEATURES.md) — commands, options and behaviors.
+* [Architecture](docs/ARCHITECTURE.md) — layers, data flow, testing and design decisions.
+* [Security](docs/SECURITY.md) — security practices adopted by the project.

data/docs/ARCHITECTURE.md

@@ -1,92 +1,187 @@
 # Architecture
 
-## Test Strategy
+## Layers
 
-* [Testing](architecture/testing.md) — Test strategy and organization.
+### CLI
 
-## Documentation
+`lib/r2/cli.rb`
 
-### Architecture
+Built with `thor`. Acts as a minimal orchestrator:
 
-* [CLI](architecture/cli.md) — Structure and operation of the command line interface.
-* [Configuration](architecture/configuration.md) — Organization and management of the application settings.
-* [Errors](architecture/errors.md) — Strategy and organization of error handling.
-* [Storage](architecture/storage.md) — Organization of the storage and persistence layer.
-* [Testing](architecture/testing.md) — Test strategy and organization.
+* Parses command-line input.
+* Delegates operations to `Storage` and `Configuration`.
+* Prints results to the user.
+* Handles domain errors.
 
-## Project Structure
+The CLI contains no business rules and does not access files or `ENV` directly.
+
+Commands that delete data ask for confirmation before delegating the operation. The confirmation is requested only when the standard input is a terminal, and `--force` skips it, so non-interactive executions must opt out explicitly.
+
+### Configuration
+
+`lib/r2/configuration.rb`
+
+Responsible exclusively for application configuration:
+
+* Reads settings from environment variables.
+* Requires `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_ENDPOINT`, and `R2_BUCKET`.
+* Defaults `R2_REGION` to `auto`.
+* Raises `Errors::ConfigurationError` when a required variable is missing.
+
+No other component reads `ENV` directly.
+
+### Storage
+
+`lib/r2/storage.rb`
+
+Wraps `aws-sdk-s3` to communicate with the S3-compatible Cloudflare R2 endpoint.
+
+Responsible only for:
+
+* Uploading objects, defining the content type from the object key.
+* Downloading objects.
+* Deleting objects.
+* Listing objects, following the pagination of the bucket and filtering by prefix.
+* Checking whether an object exists.
+
+`Storage` does not:
+
+* Read local files.
+* Transform content.
+* Determine object keys.
+* Read configuration directly from `ENV`.
+
+The bucket is provided by `Configuration` rather than passed to individual operations.
+
+Every request is wrapped in the retry support (see `Retry`), so transient network failures are retried before the failure reaches the caller.
+
+### Content Type
+
+`lib/r2/content_type.rb`
+
+Defines the content type of an object from the extension of its key:
+
+* `ContentType.for(key)` returns the mapped type, or `application/octet-stream` when the extension is not mapped.
+* The comparison is case insensitive, and keys inside directories are supported.
+
+`Storage#upload` uses this value automatically and accepts an explicit `content_type` when the caller needs to override it.
+
+### Retry
+
+`lib/r2/retry.rb`
+
+Concentrates the automatic retries of the application:
+
+* `Policy` holds the retry settings: total attempts, base delay and maximum delay.
+* `Retry.call` runs the block and retries only the error classes informed as transient, waiting between the attempts with exponential backoff.
+* The waiting strategy and the logger are injected, keeping the behavior testable without real waiting.
+
+`Storage` uses a shared policy for every operation and passes `Seahorse::Client::NetworkingError` as the transient error, which is also the error mapped to `NetworkError`.
+
+### Errors
+
+`lib/r2/errors.rb`
+
+Defines the application's domain-level errors.
+
+All errors inherit from `R2::Errors::Error`. Exceptions raised by `aws-sdk-s3` are mapped to specific application errors:
+
+* `ConfigurationError`
+* `BucketNotFoundError`
+* `ObjectNotFoundError`
+* `NetworkError`
+* `StorageError`
+
+Errors of the CLI are also part of the domain:
+
+* `ConfirmationRequiredError` when a destructive operation cannot be confirmed in a non-interactive execution.
+* `AbortedError` when the user does not confirm a destructive operation.
+
+This prevents callers from depending on AWS SDK-specific exceptions.
+
+The CLI rescues the base `Error`, prints the message to `stderr`, and exits with a non-zero status.
+
+### Logging
+
+`lib/r2/logging.rb`
+
+`R2::Logging` builds the loggers used for diagnostics:
+
+* `R2::Logging.build` returns a standard `Logger` writing to the error output when the `--verbose` flag is present, and a `NullLogger` otherwise.
+* `NullLogger` silently discards debug messages, keeping collaborators free from nil checks.
+
+The CLI builds the logger from the `--verbose` flag and shares it with `Storage` so diagnostics follow the requested verbosity.
+
+## Data Flow
 
 ```text
-C:.
-|   CHANGELOG.md
-|   LICENCE
-|   README.md
-|   Rakefile
-|   r2.gemspec
-|   Gemfile
-|   Gemfile.lock
-|   .env.example
-|   .gitattributes
-|   .gitignore
-|   .rspec
-|   .rubocop.yml
-|
-+---.github
-|   \---workflows
-|           ci.yml
-|           release.yml
-|
-+---bin
-|       r2
-|
-+---docs
-|   |   ARCHITECTURE.md
-|   |   DECISIONS.md
-|   |   DEVELOPMENT.md
-|   |   FEATURES.md
-|   |   ROADMAP.md
-|   |   SECURITY.md
-|   |
-|   \---architecture
-|           cli.md
-|           configuration.md
-|           errors.md
-|           storage.md
-|           testing.md
-|
-+---lib
-|   |   r2.rb
-|   |
-|   \---r2
-|           cli.rb
-|           configuration.rb
-|           errors.rb
-|           storage.rb
-|           version.rb
-|
-\---spec
-    |   spec_helper.rb
-    |
-    +---e2e
-    |       e2e_spec.rb
-    |
-    +---integration
-    |       cli_storage_spec.rb
-    |
-    +---support
-    |       cleanup.rb
-    |       cli_expectations.rb
-    |       cli_runner.rb
-    |       e2e_helper.rb
-    |       env_helper.rb
-    |       fake_s3_client.rb
-    |       output_capture.rb
-    |       temp_file_helper.rb
-    |
-    \---unit
-            cli_spec.rb
-            configuration_spec.rb
-            errors_spec.rb
-            storage_spec.rb
-            version_spec.rb
+CLI
+ │
+ ├── Configuration ──→ ENV
+ │
+ ├── Logging ←── --verbose
+ │
+ ├── $stdin ←── confirmation of destructive commands
+ │
+ └── Storage
+      │
+      ├── ContentType ──→ Content-Type of the object
+      │
+      └── Retry ──→ aws-sdk-s3 ──→ Cloudflare R2
+                       │
+                       └── failure → R2::Errors::*
+                                       │
+                                       └── CLI → stderr + exit 1
 ```
+
+Transient network failures are retried by `Retry` before the error mapping, so a brief instability does not interrupt the operation.
+
+## Testing
+
+### Unit Tests
+
+`spec/unit/`
+
+Tests individual components in isolation: CLI, configuration, content type, errors, logging, retry and storage.
+
+### Integration Tests
+
+`spec/integration/`
+
+Tests the interaction between the CLI and `Storage` using a fake S3 client, which reproduces the bucket behavior, including the pagination of the listing and the metadata requests.
+
+The confirmation prompts are validated with a controlled standard input, so the suite never waits for a real user and the result does not depend on whether the runner has a terminal attached.
+
+### End-to-End Tests
+
+`spec/e2e/`
+
+Tests the application against a real Cloudflare R2 bucket using `R2_TEST_BUCKET`.
+
+These tests are skipped when the required credentials are unavailable.
+
+## Design Decisions
+
+### Direct Constructor Injection
+
+No dependency-injection container is used. Dependencies are passed directly through constructors, keeping the architecture simple and explicit. `Storage`, for instance, receives its logger, retry policy and waiting strategy, which makes the retries testable without real waiting.
+
+### Deletion Confirmation
+
+Destructive commands confirm the operation before sending it, since a deletion cannot be undone. The confirmation depends on an interactive input, so scripts and pipelines must use `--force`: the alternative, deleting silently when no terminal is attached, would make accidental deletions possible in automated executions.
+
+### Retries with Backoff
+
+Transient network failures are retried with exponential backoff by the application, on top of the retries already performed by `aws-sdk-s3`. Keeping the behavior in the project makes it explicit, configurable and covered by the tests, instead of being an undocumented side effect of the SDK.
+
+### Automatic Content Type
+
+The content type is derived from the object key instead of the local file, because the key is what defines the object in the bucket and can differ from the name of the uploaded file (`--key`). Unmapped extensions fall back to `application/octet-stream`, the default of S3-compatible services.
+
+### R2 Region
+
+`R2_REGION` defaults to `auto`, which is the recommended region value for Cloudflare R2.
+
+### Runtime XML Dependency
+
+`rexml` is included as a required runtime dependency because it is used for XML parsing by `aws-sdk-s3`.