cloudflare-r2-cli 1.0.0 → 1.2.0

data/lib/r2/retry.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module R2
+    # Automatic retries with exponential backoff.
+    #
+    # Transient failures, such as brief network instabilities, are retried a
+    # limited number of times. The wait between the attempts grows
+    # exponentially and is capped, so the remote service has time to recover
+    # without making the user wait indefinitely.
+    #
+    # Only the error classes informed as transient are retried; every other
+    # failure is raised immediately, preserving the domain error mapping.
+    module Retry
+        # Total number of attempts: the first execution plus the retries.
+        DEFAULT_MAX_ATTEMPTS = 3
+
+        # Wait applied after the first failed attempt, in seconds.
+        DEFAULT_BASE_DELAY = 0.5
+
+        # Upper limit of the wait between attempts, in seconds.
+        DEFAULT_MAX_DELAY = 5.0
+
+        # Waiting strategy used when nothing else is provided.
+        DEFAULT_SLEEPER = ->(seconds) { sleep(seconds) }
+
+        # Description used in the diagnostics when the caller gives none.
+        DEFAULT_DESCRIPTION = "operation"
+
+        # Retry settings shared by the operations of a client.
+        class Policy
+            attr_reader :max_attempts, :base_delay, :max_delay
+
+            # @param max_attempts [Integer] total number of attempts
+            # @param base_delay [Float] wait after the first failure, in seconds
+            # @param max_delay [Float] upper limit of the wait, in seconds
+            def initialize(
+                max_attempts: DEFAULT_MAX_ATTEMPTS,
+                base_delay: DEFAULT_BASE_DELAY,
+                max_delay: DEFAULT_MAX_DELAY
+            )
+                @max_attempts = max_attempts
+                @base_delay = base_delay
+                @max_delay = max_delay
+            end
+
+            # Wait applied after the given failed attempt.
+            #
+            # @param attempt [Integer] number of the attempt that just failed
+            # @return [Float] seconds to wait before the next attempt
+            def delay_for(attempt)
+                [@base_delay * (2**(attempt - 1)), @max_delay].min
+            end
+        end
+
+        # Runs the block, retrying the transient failures it raises.
+        #
+        # @param policy [Policy] retry settings
+        # @param retry_on [Array<Class>] error classes considered transient
+        # @param logger [#debug, nil] logger used for diagnostics
+        # @param sleeper [#call, nil] waiting strategy used between attempts
+        # @param description [String, nil] operation description used in the diagnostics
+        # @yield the operation to run
+        # @return [Object] result of the block
+        # @raise [StandardError] error of the last attempt when the retries are exhausted
+        def self.call(policy: Policy.new, retry_on: [], logger: nil, sleeper: nil, description: nil)
+            attempt = 0
+            description ||= DEFAULT_DESCRIPTION
+
+            begin
+                attempt += 1
+                yield
+            rescue StandardError => e
+                raise unless transient?(e, retry_on) && attempt < policy.max_attempts
+
+                delay = policy.delay_for(attempt)
+                logger&.debug(retry_message(attempt, policy, description, e, delay))
+                (sleeper || DEFAULT_SLEEPER).call(delay)
+                retry
+            end
+        end
+
+        # Indicates whether an error is considered transient.
+        #
+        # @param error [StandardError] error raised by the operation
+        # @param retry_on [Array<Class>] error classes considered transient
+        # @return [Boolean] true when the failure may be retried
+        def self.transient?(error, retry_on)
+            retry_on.any? { |error_class| error.is_a?(error_class) }
+        end
+
+        # Builds the diagnostic message of a retry.
+        #
+        # @param attempt [Integer] number of the attempt that just failed
+        # @param policy [Policy] retry settings
+        # @param description [String] description of the operation
+        # @param error [StandardError] error raised by the attempt
+        # @param delay [Float] seconds to wait before the next attempt
+        # @return [String] message describing the retry
+        def self.retry_message(attempt, policy, description, error, delay)
+            "Retrying #{description} in #{delay}s (attempt #{attempt + 1} of " \
+                "#{policy.max_attempts}) after a transient failure: " \
+                "#{error.class}: #{error.message}"
+        end
+    end
+end

data/lib/r2/storage.rb

@@ -1,19 +1,34 @@
 # frozen_string_literal: true
 
 require "aws-sdk-s3"
+require_relative "content_type"
 require_relative "errors"
+require_relative "logging"
+require_relative "retry"
 
 module R2
     # Storage layer responsible for communicating with Cloudflare R2.
     #
     # Uses the `aws-sdk-s3` gem with the S3-compatible endpoint provided by
     # the application configuration.
+    #
+    # Transient network failures are retried with exponential backoff
+    # (see `R2::Retry`), so brief instabilities do not fail the operation.
     class Storage
+        # Error classes considered transient and therefore retried.
+        RETRYABLE_ERRORS = [Seahorse::Client::NetworkingError].freeze
+
         # Initializes the storage with the configured credentials and bucket.
         #
         # @param config [Configuration] application configuration
-        def initialize(config)
+        # @param logger [#debug, nil] logger used for diagnostics
+        # @param retry_policy [Retry::Policy, nil] retry settings, defaults to the project policy
+        # @param sleeper [#call, nil] waiting strategy used between attempts
+        def initialize(config, logger: nil, retry_policy: nil, sleeper: nil)
             @bucket = config.bucket
+            @logger = logger || R2::Logging::NullLogger.new
+            @retry_policy = retry_policy || Retry::Policy.new
+            @sleeper = sleeper
             @s3 = Aws::S3::Client.new(
                 region: config.region,
                 access_key_id: config.access_key_id,
@@ -28,17 +43,33 @@ module R2
         # Receives content already prepared by the layer that uses the storage
         # and delivers it to Cloudflare R2.
         #
+        # The content type is determined from the object key, unless an
+        # explicit value is given, so the stored object is served with the
+        # correct type instead of the generic binary type.
+        #
+        # When the content comes from a stream, it is rewound before every
+        # attempt, since a retry must read the content from the beginning.
+        #
         # @param key [String] object key in the bucket
         # @param body [IO, String] content of the object to upload
+        # @param content_type [String, nil] content type stored in the object metadata
         # @raise [Errors::Error] if the operation fails
-        def upload(key:, body:)
-            @s3.put_object(
-                bucket: @bucket,
-                key: key,
-                body: body
-            )
+        def upload(key:, body:, content_type: nil)
+            type = content_type || ContentType.for(key)
+            @logger.debug("Uploading object #{key.inspect} as #{type.inspect} to bucket #{@bucket.inspect}.")
+            with_retries(operation: "upload", key: key) do
+                body.rewind if body.respond_to?(:rewind)
+                @s3.put_object(
+                    bucket: @bucket,
+                    key: key,
+                    body: body,
+                    content_type: type
+                )
+            end
+            @logger.debug("Upload of object #{key.inspect} completed.")
+            nil
         rescue StandardError => e
-            raise_storage_error(e)
+            raise_storage_error(e, operation: "upload", key: key)
         end
 
         # Deletes an object from the configured bucket.
@@ -49,45 +80,173 @@ module R2
         # @param key [String] object key in the bucket
         # @raise [Errors::Error] if the operation fails
         def delete(key:)
-            @s3.delete_object(
-                bucket: @bucket,
-                key: key
-            )
+            @logger.debug("Deleting object #{key.inspect} from bucket #{@bucket.inspect}.")
+            with_retries(operation: "delete", key: key) do
+                @s3.delete_object(
+                    bucket: @bucket,
+                    key: key
+                )
+            end
+            @logger.debug("Deletion of object #{key.inspect} completed.")
+            nil
         rescue StandardError => e
-            raise_storage_error(e)
+            raise_storage_error(e, operation: "delete", key: key)
         end
 
         # Lists the objects stored in the configured bucket.
         #
+        # Every page of the listing is requested, so all the stored objects
+        # are returned regardless of the amount of keys in the bucket.
+        #
+        # @param prefix [String, nil] lists only the objects whose keys start with the prefix
         # @return [Array<String>] keys of the stored objects
         # @raise [Errors::Error] if the operation fails
-        def list
-            response = @s3.list_objects_v2(bucket: @bucket)
-            response.contents.map(&:key)
+        def list(prefix: nil)
+            @logger.debug("Listing objects in bucket #{@bucket.inspect} with prefix #{prefix.inspect}.")
+            keys = []
+            token = nil
+
+            loop do
+                response = list_page(token, prefix)
+                keys.concat(response.contents.map(&:key))
+                token = response.next_continuation_token
+                break if token.nil? || token.empty?
+            end
+
+            @logger.debug("Found #{keys.size} object(s) in bucket #{@bucket.inspect}.")
+            keys
+        rescue StandardError => e
+            raise_storage_error(e, operation: "list")
+        end
+
+        # Downloads an object from the configured bucket.
+        #
+        # The content is streamed directly to the destination file, so large
+        # objects do not need to be fully loaded into memory. Every attempt
+        # writes the file from the beginning, avoiding a partially written
+        # content when a retry is needed.
+        #
+        # @param key [String] object key in the bucket
+        # @param destination [String] local path where the content is written
+        # @return [String] destination path
+        # @raise [Errors::Error] if the operation fails
+        def download(key:, destination:)
+            @logger.debug("Downloading object #{key.inspect} to #{destination.inspect}.")
+            with_retries(operation: "download", key: key) do
+                File.open(destination, "wb") do |file|
+                    @s3.get_object(bucket: @bucket, key: key, response_target: file)
+                end
+            end
+            @logger.debug("Download of object #{key.inspect} completed.")
+            destination
         rescue StandardError => e
-            raise_storage_error(e)
+            raise_storage_error(e, operation: "download", key: key, destination: destination)
+        end
+
+        # Checks whether an object exists in the configured bucket.
+        #
+        # The object metadata is requested instead of the content, so the
+        # check is cheap regardless of the object size.
+        #
+        # @param key [String] object key in the bucket
+        # @return [Boolean] true when the object exists
+        # @raise [Errors::Error] if the operation fails
+        def exists?(key:)
+            @logger.debug("Checking whether object #{key.inspect} exists in bucket #{@bucket.inspect}.")
+            with_retries(operation: "exists", key: key) do
+                @s3.head_object(bucket: @bucket, key: key)
+            end
+            @logger.debug("Object #{key.inspect} was found in bucket #{@bucket.inspect}.")
+            true
+        rescue Aws::S3::Errors::NoSuchKey, Aws::S3::Errors::NotFound
+            @logger.debug("Object #{key.inspect} was not found in bucket #{@bucket.inspect}.")
+            false
+        rescue StandardError => e
+            raise_storage_error(e, operation: "exists", key: key)
         end
 
         private
 
+        # Requests a single page of the object listing.
+        #
+        # @param token [String, nil] continuation token of the page
+        # @param prefix [String, nil] lists only the objects whose keys start with the prefix
+        # @return [Object] response of the listing operation
+        def list_page(token, prefix)
+            params = { bucket: @bucket }
+            params[:prefix] = prefix unless prefix.nil?
+            params[:continuation_token] = token unless token.nil?
+
+            with_retries(operation: "list") { @s3.list_objects_v2(**params) }
+        end
+
+        # Runs the given block retrying transient network failures.
+        #
+        # @param operation [String] operation being performed
+        # @param key [String, nil] object key involved in the operation
+        # @yield the request to run against the storage
+        # @return [Object] result of the block
+        def with_retries(operation:, key: nil, &)
+            R2::Retry.call(
+                policy: @retry_policy,
+                retry_on: RETRYABLE_ERRORS,
+                logger: @logger,
+                sleeper: @sleeper,
+                description: describe_operation(operation, key),
+                &
+            )
+        end
+
+        # Builds the description of an operation used in the diagnostics.
+        #
+        # @param operation [String] operation being performed
+        # @param key [String, nil] object key involved in the operation
+        # @return [String] operation description
+        def describe_operation(operation, key)
+            return "#{operation} on bucket #{@bucket}" if key.nil?
+
+            "#{operation} of #{key}"
+        end
+
         # Converts storage layer errors into project domain errors, avoiding
         # exposing internal details of the implementations.
         #
         # The original message is preserved when useful.
         #
         # @param error [StandardError] original error
+        # @param operation [String] operation being performed
+        # @param key [String, nil] object key involved in the operation
+        # @param destination [String, nil] destination path involved
         # @raise [Errors::Error] subclass matching the cause of the error
-        def raise_storage_error(error)
+        def raise_storage_error(error, operation:, key: nil, destination: nil)
+            raise error if error.is_a?(Errors::Error)
+
+            @logger.debug("Operation #{operation} failed: #{error.class}: #{error.message}")
+
+            mapped = map_storage_error(error, key: key, destination: destination)
+            raise mapped unless mapped.nil?
+
+            raise Errors::StorageError, error.message
+        end
+
+        # Maps known storage failures to domain errors.
+        #
+        # @param error [StandardError] original error
+        # @param key [String, nil] object key involved in the operation
+        # @param destination [String, nil] destination path involved
+        # @return [Errors::Error, nil] mapped domain error, if recognized
+        def map_storage_error(error, key:, destination:)
             case error
             when Aws::Errors::MissingCredentialsError
-                raise Errors::ConfigurationError,
-                      "Missing or invalid credential environment variables."
+                Errors::ConfigurationError.new("Missing or invalid credential environment variables.")
             when Aws::S3::Errors::NoSuchBucket
-                raise Errors::BucketNotFoundError, "Bucket not found: #{@bucket}"
+                Errors::BucketNotFoundError.new("Bucket not found: #{@bucket}")
+            when Aws::S3::Errors::NoSuchKey, Aws::S3::Errors::NotFound
+                Errors::ObjectNotFoundError.new("Object not found: #{key}")
             when Seahorse::Client::NetworkingError
-                raise Errors::NetworkError, error.message
-            else
-                raise Errors::StorageError, error.message
+                Errors::NetworkError.new(error.message)
+            when Errno::EACCES, Errno::EPERM
+                Errors::PermissionError.new("Permission denied to write the file: #{destination || key}")
             end
         end
     end

data/lib/r2/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module R2
-    VERSION = "1.0.0"
+    VERSION = "1.2.0"
 end

data/lib/r2.rb

@@ -2,6 +2,9 @@
 
 require "r2/cli"
 require "r2/configuration"
+require "r2/content_type"
 require "r2/errors"
+require "r2/logging"
+require "r2/retry"
 require "r2/storage"
 require "r2/version"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cloudflare-r2-cli
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - rpzerosixcode
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-30 00:00:00.000000000 Z
+date: 2026-09-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-s3
@@ -117,25 +117,20 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- LICENCE
+- LICENSE
 - README.md
 - Rakefile
 - bin/r2
 - docs/ARCHITECTURE.md
-- docs/DECISIONS.md
-- docs/DEVELOPMENT.md
 - docs/FEATURES.md
-- docs/ROADMAP.md
 - docs/SECURITY.md
-- docs/architecture/cli.md
-- docs/architecture/configuration.md
-- docs/architecture/errors.md
-- docs/architecture/storage.md
-- docs/architecture/testing.md
 - lib/r2.rb
 - lib/r2/cli.rb
 - lib/r2/configuration.rb
+- lib/r2/content_type.rb
 - lib/r2/errors.rb
+- lib/r2/logging.rb
+- lib/r2/retry.rb
 - lib/r2/storage.rb
 - lib/r2/version.rb
 homepage: https://github.com/rpzerosixcode/cloudflare-r2-cli

data/docs/DECISIONS.md

@@ -1,30 +0,0 @@
-# Decisions
-
-This document records the main architectural and project-level decisions.
-
-## Name
-
-The publication name of the project is **`cloudflare-r2-cli`**.
-
-For command usage, **`r2`** is used.
-
-## Content
-
-The project's public content is maintained in **English**.
-
-## Changelog
-
-Formal changelog maintenance starts with version **`1.0.0`** in
-[CHANGELOG.md](../CHANGELOG.md).
-
-## Versioning
-
-The project follows **Semantic Versioning**, starting with version **`1.0.0`**.
-
-## Dependency Injection
-
-Dependencies should preferably be provided through **dependency injection**,
-avoiding unnecessary coupling to concrete implementations.
-
-The project does not use a dependency injection container. Dependencies are
-provided directly by the components that require them.

data/docs/DEVELOPMENT.md

@@ -1,65 +0,0 @@
-# Development
-
-## Branches
-
-The project uses two main branches:
-
-* `develop`: development.
-* `main`: stable version.
-
-## Pull Requests
-
-Changes between branches must be made through Pull Requests.
-
-Pull Requests must be clear, objective and pass the required checks before merging.
-
-## Commits
-
-Commits must follow the **Conventional Commits** convention, using types such as:
-
-* `feat`: new feature.
-* `fix`: bug fix.
-* `docs`: documentation change.
-* `refactor`: refactoring without behavior change.
-* `test`: creation or change of tests.
-* `chore`: maintenance tasks.
-
-## Continuous Integration
-
-The project uses **GitHub Actions** to automatically validate changes on every
-push to the `develop` and `main` branches and on Pull Requests.
-
-The workflow defined in `.github/workflows/ci.yml` runs:
-
-* **Lint** — RuboCop.
-* **Tests** — unit, integration and E2E suites. The E2E scenarios are marked
-  as pending when the test credentials are not configured in the repository
-  secrets (`R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_ENDPOINT`,
-  `R2_REGION` and `R2_TEST_BUCKET`).
-* **Packaging** — gem build (`rake build`).
-
-## Releases
-
-Releases are published from tags in the `v*` format (for example, `v1.0.0`).
-
-The workflow defined in `.github/workflows/release.yml`:
-
-* validates the project (lint, tests and packaging);
-* publishes the gem to RubyGems using the `RUBYGEMS_API_KEY` repository secret;
-* creates a GitHub Release with the packed gem attached.
-
-To release a new version:
-
-1. Update the version in `lib/r2/version.rb` and the changelog in `CHANGELOG.md`.
-2. Merge the changes into `main`.
-3. Create and push the version tag:
-   ```console
-   $ git tag v1.0.0
-   $ git push origin v1.0.0
-   ```
-
-## Principles
-
-Development must prioritize simplicity, organization and code maintenance.
-
-Changes must remain aligned with the current scope of the project and its documentation.

data/docs/ROADMAP.md

@@ -1,69 +0,0 @@
-# Roadmap
-
-The roadmap tracks the planned evolution of the project.
-
-## MVP
-
-The MVP was completed through the phases below.
-
-### Phase 1 — Initial Preparation
-
-Initial structure and fundamental project definitions.
-
-### Phase 2 — Features
-
-Implementation of the essential MVP features.
-
-#### Phase 2.1 — Upload
-
-Implementation of the upload feature.
-
-#### Phase 2.2 — Delete
-
-Implementation of the delete feature.
-
-#### Phase 2.3 — List
-
-Implementation of the list feature.
-
-### Phase 3 — Test Coverage
-
-Implementation and expansion of the project's test coverage.
-
-### Phase 4 — Refinement and Stabilization
-
-Review, refinement and stabilization of the project.
-
-- **Portability** — ensure the CLI works in different environments and operating systems.
-- **Consistency** — review and standardize code, tests, messages and behaviors.
-- **Error handling** — review exception handling and ensure clear, safe messages.
-- **Security** — review settings and ensure sensitive information is not exposed.
-- **Documentation** — review and update the public documentation according to the current state of the project.
-- **Development context** — remove or isolate documentation exclusively related to the development process.
-- **Packaging** — validate the build, installation and execution of the distributed package.
-- **Continuous integration** — integrate the CI flow into the development process, ensuring automated execution of tests and checks.
-- **Final validation** — run the full test suite and validate the project in a clean environment.
-
-### Phase 5 — Release
-
-Preparation and publication of the first stable version of the project.
-
-- **Versioning** — adopt semantic versioning from `1.0.0`.
-- **Changelog** — start formal changelog maintenance from `1.0.0`.
-- **Documentation** — normalize the public documentation according to the stable version.
-- **Development context** — remove or isolate development-specific documentation that is no longer relevant.
-- **MVP context** — remove or update MVP-specific notes and references that no longer apply to the stable version.
-- **Translation** — translate and standardize the project content to English.
-- **Release validation** — validate the version, build and release artifacts before publication.
-- **Publication** — publish the `cloudflare-r2-cli` package on RubyGems.
-- **Post-release validation** — install the published package in a clean environment and confirm it works.
-
-## Future Evolution
-
-Possible next steps for the project:
-
-- **Pagination and control of the number of returned objects** in the `list` command.
-- **Additional configuration sources** such as files and command-line flags.
-- **Multipart uploads** for large files.
-
-> **Note:** The focus will remain a **minimally scalable base** and **essential features**, not optimizations.

data/docs/architecture/cli.md

@@ -1,24 +0,0 @@
-# CLI
-
-The CLI is responsible for interpreting the user's input, executing the
-corresponding actions and presenting the results.
-
-The `thor` gem is used to define and execute the commands.
-
-## Responsibility
-
-The CLI acts as a **minimal orchestrator**, coordinating the operations at a
-high level.
-
-## Boundaries
-
-The CLI must not implement business rules, directly handle files or know
-details of the implementations and services used.
-
-The execution of the operations must be delegated to the responsible
-components.
-
-## Commands
-
-The available commands and their behaviors are documented in
-[FEATURES.md](../FEATURES.md).

data/docs/architecture/configuration.md

@@ -1,24 +0,0 @@
-# Configuration
-
-The `Configuration` centralizes the application settings.
-
-## Source
-
-The settings are obtained directly from **environment variables**. The other
-components must not access `ENV` directly.
-
-## Variables
-
-The required variables are `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`,
-`R2_ENDPOINT` and `R2_BUCKET`.
-
-The `R2_REGION` variable is optional and, when absent, uses the default value
-`auto`, recommended for Cloudflare R2.
-
-When a required variable is absent, the `Configuration` raises
-`R2::Errors::ConfigurationError` with a message indicating the variable.
-
-## Evolution
-
-The source of the settings may be diversified in the future if a real need
-arises.

data/docs/architecture/errors.md

@@ -1,25 +0,0 @@
-# Errors
-
-Errors are centralized to standardize their handling and keep the application
-behavior consistent.
-
-## Hierarchy
-
-All domain errors inherit from `R2::Errors::Error`:
-
-* `ConfigurationError` — required configuration missing or invalid.
-* `FileNotFoundError` — the given file does not exist.
-* `InvalidFileError` — the given path is not a file.
-* `PermissionError` — no permission to read the given file.
-* `BucketNotFoundError` — the configured bucket does not exist.
-* `NetworkError` — network failure while communicating with Cloudflare R2.
-* `StorageError` — unclassified failure in the storage layer.
-
-## Handling
-
-The specific exceptions of the implementations are converted to the
-`R2::Errors` hierarchy, avoiding exposing internal details of the libraries
-and allowing consumers to catch the generic error or a specific error.
-
-The CLI catches `R2::Errors::Error`, presents the message on the error output
-and exits with a non-zero status code.