cloudflare-r2-cli 1.0.0 → 1.2.0

data/docs/FEATURES.md

@@ -7,7 +7,7 @@ Uploads a file to the configured Cloudflare R2 bucket.
 **Usage:**
 
 ```console
-$ r2 upload <file>
+$ r2 upload <file> [--key <key>]
 ```
 
 **Examples:**
@@ -15,6 +15,7 @@ $ r2 upload <file>
 ```console
 $ r2 upload image.jpg
 $ r2 upload ./images/photo.png
+$ r2 upload ./images/photo.png --key uploads/photo.png
 ```
 
 **Behavior:**
@@ -22,12 +23,39 @@ $ r2 upload ./images/photo.png
 * Validates that the given file exists.
 * Validates that the path is not a directory.
 * Opens the file in binary read mode.
+* Defines the `Content-Type` of the object from the extension of its key, falling back to `application/octet-stream` when the extension is not mapped.
 * Uploads the content to the configured Cloudflare R2 bucket.
-* Uses the file name as the object key in the bucket.
+* Uses the file name as the object key in the bucket, or the custom key given via `--key`.
 * Displays a success message after the upload.
 
 On error, the corresponding message is displayed and the CLI exits with a non-zero status code.
 
+## Download
+
+Downloads a file stored in the configured Cloudflare R2 bucket.
+
+**Usage:**
+
+```console
+$ r2 download <key> [--output <path>]
+```
+
+**Examples:**
+
+```console
+$ r2 download image.jpg
+$ r2 download image.jpg --output ./images/photo.png
+```
+
+**Behavior:**
+
+* Receives the object key to download.
+* Streams the content directly to the destination file, so large objects do not need to be fully loaded into memory.
+* Writes the content to a file named after the object key in the current directory, unless `--output` chooses a custom destination path.
+* Displays a success message after the download.
+
+On error, the corresponding message is displayed and the CLI exits with a non-zero status code.
+
 ## Delete
 
 Deletes a file stored in the configured Cloudflare R2 bucket.
@@ -35,23 +63,40 @@ Deletes a file stored in the configured Cloudflare R2 bucket.
 **Usage:**
 
 ```console
-$ r2 delete <file>
+$ r2 delete <file> [--force]
 ```
 
-**Example:**
+**Examples:**
 
 ```console
 $ r2 delete image.jpg
+$ r2 delete image.jpg --force
 ```
 
 **Behavior:**
 
 * Receives the name of the file to delete.
+* Asks for the confirmation of the deletion before sending the request, unless `--force` is given.
 * Uses the file name as the object key.
 * Requests the object deletion from Cloudflare R2.
 * Considers the operation successful when the storage completes the request without errors.
 * Displays a success message after the operation.
 
+**Confirmation:**
+
+The prompt is written to the standard output and the answer is read from the standard input:
+
+```console
+$ r2 delete image.jpg
+Delete "image.jpg" from the bucket? [y/N]
+```
+
+The deletion only proceeds with an affirmative answer (`y` or `yes`); any other answer, including an empty one, aborts the operation. In non-interactive executions, such as scripts and pipelines, the confirmation cannot be requested, so the CLI aborts with an explanatory message and status code `1`. Use `--force` to delete without confirmation:
+
+```console
+$ r2 delete image.jpg --force
+```
+
 The feature does not perform a follow-up query to check that the object no longer exists. The success confirmation is based on the result of the deletion operation provided by the storage layer.
 
 On error, the corresponding message is displayed and the CLI exits with a non-zero status code.
@@ -62,14 +107,85 @@ Lists the files stored in the configured Cloudflare R2 bucket.
 
 **Usage:**
 
+```console
+$ r2 list [--prefix <prefix>]
+```
+
+**Examples:**
+
 ```console
 $ r2 list
+$ r2 list --prefix uploads/
 ```
 
 **Behavior:**
 
 * Queries the objects stored in the configured bucket.
+* Follows the pagination of the bucket, requesting every page until the last one, so all objects are returned.
+* Lists only the objects whose keys start with the given prefix, when `--prefix` is used.
 * Displays the files found.
-* Returns all objects without pagination or control over the amount of returned objects.
 
 On error, the corresponding message is displayed and the CLI exits with a non-zero status code.
+
+## Exists
+
+Checks whether an object exists in the configured Cloudflare R2 bucket.
+
+**Usage:**
+
+```console
+$ r2 exists <key>
+```
+
+**Examples:**
+
+```console
+$ r2 exists image.jpg
+```
+
+**Behavior:**
+
+* Requests the metadata of the object, instead of its content, so the check does not depend on the object size.
+* Displays `Object exists: <key>` and exits with status code `0` when the object exists.
+* Displays `Object not found: <key>` and exits with status code `1` when the object does not exist, allowing the command to be used in scripts.
+
+On error, the corresponding message is displayed and the CLI exits with a non-zero status code.
+
+## Reliability
+
+### Automatic retries
+
+Transient failures while communicating with Cloudflare R2, such as brief network instabilities, are retried automatically with exponential backoff:
+
+| Attempt | Wait before the attempt |
+| ------- | ----------------------- |
+| 1       | —                       |
+| 2       | 0.5s                    |
+| 3       | 1s                      |
+
+The wait is capped at 5s, and the operation fails after the last attempt, reporting the mapped domain error. Failures that are not transient, such as missing credentials, an invalid bucket or a missing object, are reported immediately, without retries.
+
+The retries are applied to every storage operation and restart from the beginning of the data: the uploaded content is rewound and the downloaded content is written from the start again, so a retried request never sends an incomplete body or leaves a partially written file.
+
+### Diagnostics
+
+With `--verbose`, every retry is reported on the error output with the operation, the failure cause and the wait applied:
+
+```console
+$ r2 upload image.jpg --verbose
+Retrying upload of image.jpg in 0.5s (attempt 2 of 3) after a transient failure: Seahorse::Client::NetworkingError: ...
+```
+
+## 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
+```
+
+Without the flag, diagnostics are discarded by a null logger and only the standard output is produced.

data/docs/SECURITY.md

@@ -9,6 +9,10 @@ The project follows the following security practices:
 - **Isolated test environment** — E2E tests use a dedicated bucket
   (`R2_TEST_BUCKET`) separated from the default application bucket.
 
+- **Confirmation of destructive operations** — `r2 delete` asks for
+  confirmation before deleting and requires `--force` in non-interactive
+  executions, avoiding accidental deletions in scripts and pipelines.
+
 - **Ignored environment files** — `.env` files are excluded from version
   control. Only the `.env.example` template is versioned.
 

data/lib/r2/cli.rb

@@ -2,6 +2,7 @@
 
 require "thor"
 require_relative "errors"
+require_relative "logging"
 
 module R2
     # Command line interface of the project.
@@ -9,6 +10,11 @@ module R2
     # Acts as a minimal orchestrator: interprets the user's input, delegates
     # the execution to the responsible components and presents the results.
     class CLI < Thor
+        class_option :verbose,
+                     type: :boolean,
+                     default: false,
+                     desc: "Displays detailed information during execution"
+
         # Initializes the CLI with its dependencies.
         #
         # Dependencies are loaded lazily: they are only created when the first
@@ -17,14 +23,18 @@ module R2
         #
         # @param configuration [Configuration] application configuration
         # @param storage [Storage] storage used in object operations
+        # @param logger [#debug, nil] logger used for diagnostics
         def initialize(
             *,
             configuration: nil,
-            storage: nil
+            storage: nil,
+            logger: nil
         )
             super(*)
             @configuration = configuration
             @storage = storage
+            @injected_logger = logger
+            @logger = nil
         end
 
         # Ensures that Thor exits with a non-zero status code when an
@@ -46,28 +56,33 @@ module R2
             exit 1
         end
 
-        desc "upload FILE", "Uploads an image to R2"
+        desc "upload FILE", "Uploads a file to R2"
+        method_option :key,
+                      type: :string,
+                      desc: "Custom object key used in the bucket"
 
         long_desc <<~LONGDESC
-            Uploads an image to the configured Cloudflare R2 bucket.
-            The object key in the bucket will be the name of the given file.
+            Uploads a file to the configured Cloudflare R2 bucket.
+            By default, the object key is the name of the given file.
+            Use --key to store the object under a custom key.
 
             Examples:
 
               $ r2 upload image.jpg
 
-              $ r2 upload ./images/photo.png
+              $ r2 upload ./images/photo.png --key uploads/photo.png
         LONGDESC
 
-        # Uploads an image to the configured Cloudflare R2 bucket.
-        #
-        # The object key in the bucket will be the name of the given file.
+        # Uploads a file to the configured Cloudflare R2 bucket.
         #
         # @param file [String] path of the file to upload
         def upload(file)
+            key = options[:key] || File.basename(file)
+            logger.debug("Starting upload: #{file.inspect} as #{key.inspect}.")
             body = open_file(file)
-            storage.upload(key: File.basename(file), body: body)
-            puts "Image uploaded successfully: #{File.basename(file)}"
+            storage.upload(key: key, body: body)
+            puts "Uploaded successfully: #{key}"
+            logger.debug("Finished upload: #{key.inspect}.")
         rescue Errors::Error => e
             warn "Error: #{e.message}"
             exit 1
@@ -75,14 +90,57 @@ module R2
             body&.close
         end
 
+        desc "download KEY", "Downloads a file from R2"
+        method_option :output,
+                      type: :string,
+                      desc: "Local path where the content is written"
+
+        long_desc <<~LONGDESC
+            Downloads a file from the configured Cloudflare R2 bucket.
+            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.
+
+            Examples:
+
+              $ r2 download image.jpg
+
+              $ r2 download image.jpg --output ./images/photo.png
+        LONGDESC
+
+        # Downloads a file from the configured Cloudflare R2 bucket.
+        #
+        # @param key [String] object key in the bucket
+        def download(key)
+            destination = options[:output] || File.basename(key)
+            logger.debug("Starting download: #{key.inspect} to #{destination.inspect}.")
+            ensure_destination_writable(destination)
+            storage.download(key: key, destination: destination)
+            puts "Downloaded successfully: #{destination}"
+            logger.debug("Finished download: #{key.inspect}.")
+        rescue Errors::Error => e
+            warn "Error: #{e.message}"
+            exit 1
+        end
+
         desc "delete FILE", "Deletes a file from R2"
+        method_option :force,
+                      type: :boolean,
+                      default: false,
+                      desc: "Deletes without asking for confirmation"
 
         long_desc <<~LONGDESC
             Deletes a file from the configured Cloudflare R2 bucket.
 
+            The deletion is confirmed before the request is sent. Since a
+            non-interactive execution cannot ask the user, it requires the
+            --force option to proceed.
+
             Examples:
 
               $ r2 delete image.jpg
+
+              $ r2 delete image.jpg --force
         LONGDESC
 
         # Deletes a file from the configured Cloudflare R2 bucket.
@@ -92,30 +150,76 @@ module R2
         #
         # @param file [String] name of the file to delete
         def delete(file)
+            logger.debug("Starting delete: #{file.inspect}.")
+            confirm_deletion(file)
             storage.delete(key: file)
-            puts "File deleted successfully: #{file}"
+            puts "Deleted successfully: #{file}"
+            logger.debug("Finished delete: #{file.inspect}.")
         rescue Errors::Error => e
             warn "Error: #{e.message}"
             exit 1
         end
 
         desc "list", "Lists the files stored in R2"
+        method_option :prefix,
+                      type: :string,
+                      desc: "Lists only the objects whose keys start with the given prefix"
 
         long_desc <<~LONGDESC
             Lists the files stored in the configured Cloudflare R2 bucket.
 
+            Every object is listed, following the pagination of the bucket.
+            Use --prefix to list only the objects whose keys start with the
+            given prefix.
+
             Examples:
 
               $ r2 list
+
+              $ r2 list --prefix uploads/
         LONGDESC
 
         # Lists the files stored in the configured Cloudflare R2 bucket.
         def list
-            files = storage.list
+            logger.debug("Starting list: prefix=#{options[:prefix].inspect}.")
+            files = storage.list(prefix: options[:prefix])
 
             files.each do |file|
                 puts file
             end
+            logger.debug("Finished list: #{files.size} object(s).")
+        rescue Errors::Error => e
+            warn "Error: #{e.message}"
+            exit 1
+        end
+
+        desc "exists KEY", "Checks whether an object exists in R2"
+
+        long_desc <<~LONGDESC
+            Checks whether an object exists in the configured Cloudflare R2
+            bucket. The exit status is 0 when the object exists and 1 when it
+            does not, which allows the command to be used in scripts.
+
+            Examples:
+
+              $ r2 exists image.jpg
+        LONGDESC
+
+        # Checks whether an object exists in the configured Cloudflare R2
+        # bucket.
+        #
+        # @param key [String] object key in the bucket
+        def exists(key)
+            logger.debug("Starting existence check: #{key.inspect}.")
+
+            if storage.exists?(key: key)
+                puts "Object exists: #{key}"
+                logger.debug("Finished existence check: #{key.inspect} exists.")
+            else
+                puts "Object not found: #{key}"
+                logger.debug("Finished existence check: #{key.inspect} does not exist.")
+                exit 1
+            end
         rescue Errors::Error => e
             warn "Error: #{e.message}"
             exit 1
@@ -153,9 +257,126 @@ module R2
 
         # Returns the storage, creating it lazily on first use.
         #
+        # Shares the CLI logger with the storage so diagnostics follow
+        # the requested verbosity.
+        #
         # @return [Storage] storage used in object operations
         def storage
-            @storage ||= Storage.new(configuration)
+            @storage ||= Storage.new(configuration, logger: logger)
+        end
+
+        # Returns the logger used for diagnostics.
+        #
+        # An injected logger is always used as-is. Otherwise, a logger is
+        # built from the `--verbose` flag: verbose output goes to the
+        # error output, while the default is a null logger that silently
+        # ignores debug messages.
+        #
+        # @return [#debug] logger used for diagnostics
+        def logger
+            return @logger if logger_ready?
+
+            @logger_verbose = verbose?
+            @logger = build_logger
+        end
+
+        # Indicates whether verbose output was requested.
+        #
+        # @return [Boolean] true when `--verbose` was given
+        def verbose?
+            options[:verbose] == true
+        end
+
+        # Indicates whether the logger already matches the current verbosity.
+        #
+        # @return [Boolean] true when the logger is ready to use
+        def logger_ready?
+            !@logger.nil? && defined?(@logger_verbose) && @logger_verbose == verbose?
+        end
+
+        # Builds the logger for the current verbosity.
+        #
+        # @return [#debug] logger used for diagnostics
+        def build_logger
+            return @injected_logger unless @injected_logger.nil?
+
+            R2::Logging.build(verbose: verbose?)
+        end
+
+        # Ensures the download destination can be written.
+        #
+        # @param destination [String] local path where the content is written
+        # @raise [Errors::InvalidFileError] if the destination is a directory
+        # @raise [Errors::PermissionError] if the destination cannot be written
+        def ensure_destination_writable(destination)
+            if File.directory?(destination)
+                raise Errors::InvalidFileError, "The destination path is a directory: #{destination}"
+            end
+
+            parent = File.dirname(destination)
+
+            raise Errors::FileNotFoundError, "Destination directory not found: #{parent}" unless File.directory?(parent)
+
+            return if File.writable?(parent) && (!File.exist?(destination) || File.writable?(destination))
+
+            raise Errors::PermissionError, "Permission denied to write the file: #{destination}"
+        end
+
+        # Asks the user to confirm the deletion of an object.
+        #
+        # The confirmation is skipped when `--force` is given. Without it the
+        # deletion only happens after an affirmative answer, which requires an
+        # interactive input: scripts and pipelines cannot be asked, so they
+        # must opt out explicitly, avoiding accidental deletions.
+        #
+        # @param key [String] object key in the bucket
+        # @raise [Errors::ConfirmationRequiredError] when the input is not
+        #   interactive and `--force` was not given
+        # @raise [Errors::AbortedError] when the deletion is not confirmed
+        def confirm_deletion(key)
+            if options[:force]
+                logger.debug("Skipping the deletion confirmation: --force was given.")
+                return
+            end
+
+            raise Errors::ConfirmationRequiredError, confirmation_required_message(key) unless interactive_input?
+
+            return if affirmative?(ask_deletion_confirmation(key))
+
+            raise Errors::AbortedError, "Deletion aborted: #{key}"
+        end
+
+        # Writes the deletion confirmation prompt and reads the answer.
+        #
+        # @param key [String] object key in the bucket
+        # @return [String, nil] answer given by the user
+        def ask_deletion_confirmation(key)
+            $stdout.print("Delete #{key.inspect} from the bucket? [y/N] ")
+            $stdin.gets
+        end
+
+        # Indicates whether the standard input can be used to ask the user.
+        #
+        # @return [Boolean] true when the input is a terminal
+        def interactive_input?
+            $stdin.respond_to?(:tty?) && $stdin.tty?
+        end
+
+        # Indicates whether the given answer confirms the operation.
+        #
+        # @param answer [String, nil] answer given by the user
+        # @return [Boolean] true when the answer is affirmative
+        def affirmative?(answer)
+            answer.to_s.strip.match?(/\Ay(es)?\z/i)
+        end
+
+        # Builds the message shown when the confirmation cannot be requested.
+        #
+        # @param key [String] object key in the bucket
+        # @return [String] message explaining how to proceed
+        def confirmation_required_message(key)
+            "Deletion of #{key} requires confirmation. Run the command in an " \
+                "interactive terminal or use --force to delete it without confirmation."
         end
     end
 end

data/lib/r2/content_type.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module R2
+    # Determines the content type of an object from its key.
+    #
+    # The mapping covers the formats commonly handled by the CLI. Keys whose
+    # extension is not mapped fall back to the generic binary type, which is
+    # the same behavior offered by S3-compatible services.
+    #
+    # Reference: https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/MIME_types
+    module ContentType
+        # Content type used when the object extension is not mapped.
+        DEFAULT = "application/octet-stream"
+
+        # Content types by file extension.
+        TYPES = {
+            ".avif" => "image/avif",
+            ".bmp" => "image/bmp",
+            ".csv" => "text/csv",
+            ".doc" => "application/msword",
+            ".docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+            ".gif" => "image/gif",
+            ".gz" => "application/gzip",
+            ".htm" => "text/html",
+            ".html" => "text/html",
+            ".ico" => "image/vnd.microsoft.icon",
+            ".jpeg" => "image/jpeg",
+            ".jpg" => "image/jpeg",
+            ".js" => "text/javascript",
+            ".json" => "application/json",
+            ".md" => "text/markdown",
+            ".mp3" => "audio/mpeg",
+            ".mp4" => "video/mp4",
+            ".pdf" => "application/pdf",
+            ".png" => "image/png",
+            ".svg" => "image/svg+xml",
+            ".tar" => "application/x-tar",
+            ".tif" => "image/tiff",
+            ".tiff" => "image/tiff",
+            ".txt" => "text/plain",
+            ".wav" => "audio/wav",
+            ".webp" => "image/webp",
+            ".xls" => "application/vnd.ms-excel",
+            ".xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+            ".xml" => "application/xml",
+            ".yaml" => "application/yaml",
+            ".yml" => "application/yaml",
+            ".zip" => "application/zip"
+        }.freeze
+
+        # Determines the content type of the given object key.
+        #
+        # The extension is compared in lowercase, so keys stored with
+        # uppercase names are also recognized.
+        #
+        # @param key [String] object key in the bucket
+        # @return [String] content type corresponding to the key extension
+        def self.for(key)
+            TYPES.fetch(extension(key), DEFAULT)
+        end
+
+        # Extracts the extension of the given object key.
+        #
+        # @param key [String] object key in the bucket
+        # @return [String] lowercase extension, including the leading dot
+        def self.extension(key)
+            File.extname(key.to_s).downcase
+        end
+    end
+end

data/lib/r2/errors.rb

@@ -31,6 +31,10 @@ module R2
         class BucketNotFoundError < Error
         end
 
+        # The requested object does not exist in the bucket.
+        class ObjectNotFoundError < Error
+        end
+
         # Network failure while communicating with Cloudflare R2.
         class NetworkError < Error
         end
@@ -38,5 +42,14 @@ module R2
         # Unclassified failure in the storage layer.
         class StorageError < Error
         end
+
+        # The confirmation required before a destructive operation could not
+        # be requested, because the execution is not interactive.
+        class ConfirmationRequiredError < Error
+        end
+
+        # The user did not confirm a destructive operation.
+        class AbortedError < Error
+        end
     end
 end

data/lib/r2/logging.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module R2
+    # Builds and configures loggers used for diagnostics.
+    module Logging
+        # Discards all diagnostic messages.
+        #
+        # Used as the default when no logger is provided, keeping
+        # collaborators free from nil checks.
+        class NullLogger
+            # Ignores a debug message.
+            #
+            # @param _message [String] message to ignore
+            # @return [nil]
+            def debug(_message); end
+        end
+
+        # Builds a logger according to the requested verbosity.
+        #
+        # @param verbose [Boolean] whether detailed output is enabled
+        # @param output [IO] destination of the diagnostic messages
+        # @return [Logger, NullLogger] configured logger
+        def self.build(verbose: false, output: $stderr)
+            return NullLogger.new unless verbose
+
+            Logger.new(output).tap do |log|
+                log.level = Logger::DEBUG
+                log.formatter = proc { |_severity, _datetime, _progname, message| "#{message}\n" }
+            end
+        end
+    end
+end