activestorage 7.2.2.1 → 8.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19f4fa25c348a39b38b18a049dd123c5a0c6f80d70e05cdfc4790c7e0dbf96d1
-  data.tar.gz: 48ba490e74129a1495ed0b3249730bfeba7b12f916e787849e7cfa4f81235bf9
+  metadata.gz: 2a42fb3f7bbc7e2032f582d6d934bfb06245afdd8fe2db1b07b35d6c8223a617
+  data.tar.gz: aefc082d3ed704bf9c675e40560d9eb3be6f2e315ea28d7313ceabb493a95b93
 SHA512:
-  metadata.gz: 6656a5f10b464e63d86f0e4fc60984735e522d56789f93ce4f0d6ec4684b0b7e6a449f14af01a92e5929b1a4854f283b0bf89b37fe67ecb5d8cc207430b81c71
-  data.tar.gz: a8fe146a25f52b241de32978f344a2303ad5221f05306a57776337194ba67aa2691c715790131056dec44dfe21cb26b7df1fe33fef5d09efba3ff5f226b83e58
+  metadata.gz: c5c63ac998f475f5b3b9fb11d6bd57f0697b1ece83903f4283b35eefe490a0b0a6edb4e9b8d6d2fc4673c67948296c66af79bc25821a16ed9ad3144d76bdef5e
+  data.tar.gz: 12412531395d736326f067fdb7cdbe23f4a99a3167d4921d1882191baf4d5c79d6260d9ef598b1bcc90c0ffc35a78a2b898bcad9d8d2332c5f5749378eceeaca

data/CHANGELOG.md

@@ -1,103 +1,174 @@
-## Rails 7.2.2.1 (December 10, 2024) ##
+## Rails 8.1.3 (March 24, 2026) ##
 
-*   No changes.
+*   Fix `ActiveStorage::Blob` content type predicate methods to handle `nil`.
 
+    *Daichi KUDO*
 
-## Rails 7.2.2 (October 30, 2024) ##
 
-*   No changes.
+## Rails 8.1.2.1 (March 23, 2026) ##
 
+*   Filter user supplied metadata in DirectUploadController
 
-## Rails 7.2.1.2 (October 23, 2024) ##
+    [CVE-2026-33173]
 
-*   No changes.
+    *Jean Boussier*
 
+*   Configurable maxmimum streaming chunk size
 
-## Rails 7.2.1.1 (October 15, 2024) ##
+    Makes sure that byte ranges for blobs don't exceed 100mb by default.
+    Content ranges that are too big can result in denial of service.
 
-*   No changes.
+    [CVE-2026-33174]
 
+    *Gannon McGibbon*
 
-## Rails 7.2.1 (August 22, 2024) ##
+*   Limit range requests to a single range
 
-*   No changes.
+    [CVE-2026-33658]
 
+    *Jean Boussier*
 
-## Rails 7.2.0 (August 09, 2024) ##
 
-*   Remove deprecated `config.active_storage.silence_invalid_content_types_warning`.
+*   Prevent path traversal in `DiskService`.
 
-    *Rafael Mendonça França*
+    `DiskService#path_for` now raises an `InvalidKeyError` when passed keys with dot segments (".",
+    ".."), or if the resolved path is outside the storage root directory.
 
-*   Remove deprecated `config.active_storage.replace_on_assign_to_many`.
+    `#path_for` also now consistently raises `InvalidKeyError` if the key is invalid in any way, for
+    example containing null bytes or having an incompatible encoding. Previously, the exception
+    raised may have been `ArgumentError` or `Encoding::CompatibilityError`.
 
-    *Rafael Mendonça França*
+    `DiskController` now explicitly rescues `InvalidKeyError` with appropriate HTTP status codes.
 
-*   Add support for custom `key` in `ActiveStorage::Blob#compose`.
+    [CVE-2026-33195]
 
-    *Elvin Efendiev*
+    *Mike Dalessio*
 
-*   Add `image/webp` to `config.active_storage.web_image_content_types` when `load_defaults "7.2"`
-    is set.
+*   Prevent glob injection in `DiskService#delete_prefixed`.
 
-    *Lewis Buckley*
+    Escape glob metacharacters in the resolved path before passing to `Dir.glob`.
 
-*   Fix JSON-encoding of `ActiveStorage::Filename` instances.
+    Note that this change breaks any existing code that is relying on `delete_prefixed` to expand
+    glob metacharacters. This change presumes that is unintended behavior (as other storage services
+    do not respect these metacharacters).
 
-    *Jonathan del Strother*
+    [CVE-2026-33202]
 
-*   Fix N+1 query when fetching preview images for non-image assets.
+    *Mike Dalessio*
 
-    *Aaron Patterson & Justin Searls*
 
-*   Fix all Active Storage database related models to respect
-    `ActiveRecord::Base.table_name_prefix` configuration.
+## Rails 8.1.2 (January 08, 2026) ##
 
-    *Chedli Bourguiba*
+*   Restore ADC when signing URLs with IAM for GCS
 
-*   Fix `ActiveStorage::Representations::ProxyController` not returning the proper
-    preview image variant for previewable files.
+    ADC was previously used for automatic authorization when signing URLs with IAM.
+    Now it is again, but the auth client is memoized so that new credentials are only
+    requested when the current ones expire. Other auth methods can now be used
+    instead by setting the authorization on `ActiveStorage::Service::GCSService#iam_client`.
+
+    ```ruby
+    ActiveStorage::Blob.service.iam_client.authorization = Google::Auth::ImpersonatedServiceAccountCredentials.new(options)
+    ```
+
+    This is safer than setting `Google::Apis::RequestOptions.default.authorization`
+    because it only applies to Active Storage and does not affect other Google API
+    clients.
+
+    *Justin Malčić*
+
+
+## Rails 8.1.1 (October 28, 2025) ##
+
+*   No changes.
 
-    *Chedli Bourguiba*
 
-*   Fix `ActiveStorage::Representations::ProxyController` to proxy untracked
-    variants.
+## Rails 8.1.0 (October 22, 2025) ##
+
+*   Add structured events for Active Storage:
+    - `active_storage.service_upload`
+    - `active_storage.service_download`
+    - `active_storage.service_streaming_download`
+    - `active_storage.preview`
+    - `active_storage.service_delete`
+    - `active_storage.service_delete_prefixed`
+    - `active_storage.service_exist`
+    - `active_storage.service_url`
+    - `active_storage.service_mirror`
+
+    *Gannon McGibbon*
+
+*   Allow analyzers and variant transformer to be fully configurable
+
+    ```ruby
+    # ActiveStorage.analyzers can be set to an empty array:
+    config.active_storage.analyzers = []
+    # => ActiveStorage.analyzers = []
+
+    # or use custom analyzer:
+    config.active_storage.analyzers = [ CustomAnalyzer ]
+    # => ActiveStorage.analyzers = [ CustomAnalyzer ]
+    ```
+
+    If no configuration is provided, it will use the default analyzers.
+
+    You can also disable variant processor to remove warnings on startup about missing gems.
+
+    ```ruby
+    config.active_storage.variant_processor = :disabled
+    ```
+
+    *zzak*, *Alexandre Ruban*
+
+*   Remove deprecated `:azure` storage service.
+
+    *Rafael Mendonça França*
+
+*   Remove unnecessary calls to the GCP metadata server.
 
-    *Chedli Bourguiba*
+    Calling Google::Auth.get_application_default triggers an explicit call to
+    the metadata server - given it was being called for significant number of
+    file operations, it can lead to considerable tail latencies and even metadata
+    server overloads. Instead, it's preferable (and significantly more efficient)
+    that applications use:
 
-*   When using the `preprocessed: true` option, avoid enqueuing transform jobs
-    for blobs that are not representable.
+    ```ruby
+    Google::Apis::RequestOptions.default.authorization = Google::Auth.get_application_default(...)
+    ```
 
-    *Chedli Bourguiba*
+    In the cases applications do not set that, the GCP libraries automatically determine credentials.
 
-*   Prevent `ActiveStorage::Blob#preview` to generate a variant if an empty variation is passed.
+    This also enables using credentials other than those of the associated GCP
+    service account like when using impersonation.
 
-    Calls to `#url`, `#key` or `#download` will now use the original preview
-    image instead of generating a variant with the exact same dimensions.
+    *Alex Coomans*
 
-    *Chedli Bourguiba*
+*   Direct upload progress accounts for server processing time.
 
-*   Process preview image variant when calling `ActiveStorage::Preview#processed`.
+    *Jeremy Daer*
 
-    For example, `attached_pdf.preview(:thumb).processed` will now immediately
-    generate the full-sized preview image and the `:thumb` variant of it.
-    Previously, the `:thumb` variant would not be generated until a further call
-    to e.g. `processed.url`.
+*   Delegate `ActiveStorage::Filename#to_str` to `#to_s`
 
-    *Chedli Bourguiba* and *Jonathan Hefner*
+    Supports checking String equality:
 
-*   Prevent `ActiveRecord::StrictLoadingViolationError` when strict loading is
-    enabled and the variant of an Active Storage preview has already been
-    processed (for example, by calling `ActiveStorage::Preview#url`).
+    ```ruby
+    filename = ActiveStorage::Filename.new("file.txt")
+    filename == "file.txt" # => true
+    filename in "file.txt" # => true
+    "file.txt" == filename # => true
+    ```
 
-    *Jonathan Hefner*
+    *Sean Doyle*
 
-*   Fix `preprocessed: true` option for named variants of previewable files.
+*   A Blob will no longer autosave associated Attachment.
 
-    *Nico Wenterodt*
+    This fixes an issue where a record with an attachment would have
+    its dirty attributes reset, preventing your `after commit` callbacks
+    on that record to behave as expected.
 
-*   Allow accepting `service` as a proc as well in `has_one_attached` and `has_many_attached`.
+    Note that this change doesn't require any changes on your application
+    and is supposed to be internal. Active Storage Attachment will continue
+    to be autosaved (through a different relation).
 
-    *Yogesh Khater*
+    *Edouard-chin*
 
-Please check [7-1-stable](https://github.com/rails/rails/blob/7-1-stable/activestorage/CHANGELOG.md) for previous changes.
+Please check [8-0-stable](https://github.com/rails/rails/blob/8-0-stable/activestorage/CHANGELOG.md) for previous changes.

data/README.md

@@ -1,6 +1,6 @@
 # Active Storage
 
-Active Storage makes it simple to upload and reference files in cloud services like [Amazon S3](https://aws.amazon.com/s3/), [Google Cloud Storage](https://cloud.google.com/storage/docs/), or [Microsoft Azure Storage](https://azure.microsoft.com/en-us/services/storage/), and attach those files to Active Records. Supports having one main service and mirrors in other services for redundancy. It also provides a disk service for testing or local deployments, but the focus is on cloud storage.
+Active Storage makes it simple to upload and reference files in cloud services like [Amazon S3](https://aws.amazon.com/s3/), or [Google Cloud Storage](https://cloud.google.com/storage/docs/), and attach those files to Active Records. Supports having one main service and mirrors in other services for redundancy. It also provides a disk service for testing or local deployments, but the focus is on cloud storage.
 
 Files can be uploaded from the server to the cloud or directly from the client to the cloud.
 
@@ -73,7 +73,7 @@ end
 ```erb
 <%= form_with model: @message, local: true do |form| %>
   <%= form.text_field :title, placeholder: "Title" %><br>
-  <%= form.text_area :content %><br><br>
+  <%= form.textarea :content %><br><br>
 
   <%= form.file_field :images, multiple: true %><br>
   <%= form.submit %>
@@ -88,7 +88,7 @@ class MessagesController < ApplicationController
   end
 
   def create
-    message = Message.create! params.require(:message).permit(:title, :content, images: [])
+    message = Message.create! params.expect(message: [ :title, :content, images: [] ])
     redirect_to message
   end
 
@@ -173,7 +173,10 @@ Active Storage, with its included JavaScript library, supports uploading directl
     ```erb
     <%= form.file_field :attachments, multiple: true, direct_upload: true %>
     ```
-3. That's it! Uploads begin upon form submission.
+
+3. Configure CORS on third-party storage services to allow direct upload requests.
+
+4. That's it! Uploads begin upon form submission.
 
 ### Direct upload JavaScript events
 
@@ -203,6 +206,6 @@ Bug reports for the Ruby on \Rails project can be filed here:
 
 * https://github.com/rails/rails/issues
 
-Feature requests should be discussed on the rails-core mailing list here:
+Feature requests should be discussed on the rubyonrails-core forum here:
 
 * https://discuss.rubyonrails.org/c/rubyonrails-core

data/app/assets/javascripts/activestorage.esm.js

@@ -672,7 +672,7 @@ class DirectUploadController {
     }));
   }
   uploadRequestDidProgress(event) {
-    const progress = event.loaded / event.total * 100;
+    const progress = event.loaded / event.total * 90;
     if (progress) {
       this.dispatch("progress", {
         progress: progress
@@ -707,6 +707,42 @@ class DirectUploadController {
       xhr: xhr
     });
     xhr.upload.addEventListener("progress", (event => this.uploadRequestDidProgress(event)));
+    xhr.upload.addEventListener("loadend", (() => {
+      this.simulateResponseProgress(xhr);
+    }));
+  }
+  simulateResponseProgress(xhr) {
+    let progress = 90;
+    const startTime = Date.now();
+    const updateProgress = () => {
+      const elapsed = Date.now() - startTime;
+      const estimatedResponseTime = this.estimateResponseTime();
+      const responseProgress = Math.min(elapsed / estimatedResponseTime, 1);
+      progress = 90 + responseProgress * 9;
+      this.dispatch("progress", {
+        progress: progress
+      });
+      if (xhr.readyState !== XMLHttpRequest.DONE && progress < 99) {
+        requestAnimationFrame(updateProgress);
+      }
+    };
+    xhr.addEventListener("loadend", (() => {
+      this.dispatch("progress", {
+        progress: 100
+      });
+    }));
+    requestAnimationFrame(updateProgress);
+  }
+  estimateResponseTime() {
+    const fileSize = this.file.size;
+    const MB = 1024 * 1024;
+    if (fileSize < MB) {
+      return 1e3;
+    } else if (fileSize < 10 * MB) {
+      return 2e3;
+    } else {
+      return 3e3 + fileSize / MB * 50;
+    }
   }
 }
 
@@ -845,4 +881,4 @@ function autostart() {
 
 setTimeout(autostart, 1);
 
-export { DirectUpload, DirectUploadController, DirectUploadsController, start };
+export { DirectUpload, DirectUploadController, DirectUploadsController, dispatchEvent, start };

data/app/assets/javascripts/activestorage.js

@@ -662,7 +662,7 @@
       }));
     }
     uploadRequestDidProgress(event) {
-      const progress = event.loaded / event.total * 100;
+      const progress = event.loaded / event.total * 90;
       if (progress) {
         this.dispatch("progress", {
           progress: progress
@@ -697,6 +697,42 @@
         xhr: xhr
       });
       xhr.upload.addEventListener("progress", (event => this.uploadRequestDidProgress(event)));
+      xhr.upload.addEventListener("loadend", (() => {
+        this.simulateResponseProgress(xhr);
+      }));
+    }
+    simulateResponseProgress(xhr) {
+      let progress = 90;
+      const startTime = Date.now();
+      const updateProgress = () => {
+        const elapsed = Date.now() - startTime;
+        const estimatedResponseTime = this.estimateResponseTime();
+        const responseProgress = Math.min(elapsed / estimatedResponseTime, 1);
+        progress = 90 + responseProgress * 9;
+        this.dispatch("progress", {
+          progress: progress
+        });
+        if (xhr.readyState !== XMLHttpRequest.DONE && progress < 99) {
+          requestAnimationFrame(updateProgress);
+        }
+      };
+      xhr.addEventListener("loadend", (() => {
+        this.dispatch("progress", {
+          progress: 100
+        });
+      }));
+      requestAnimationFrame(updateProgress);
+    }
+    estimateResponseTime() {
+      const fileSize = this.file.size;
+      const MB = 1024 * 1024;
+      if (fileSize < MB) {
+        return 1e3;
+      } else if (fileSize < 10 * MB) {
+        return 2e3;
+      } else {
+        return 3e3 + fileSize / MB * 50;
+      }
     }
   }
   const inputSelector = "input[type=file][data-direct-upload-url]:not([disabled])";
@@ -822,6 +858,7 @@
   exports.DirectUpload = DirectUpload;
   exports.DirectUploadController = DirectUploadController;
   exports.DirectUploadsController = DirectUploadsController;
+  exports.dispatchEvent = dispatchEvent;
   exports.start = start;
   Object.defineProperty(exports, "__esModule", {
     value: true

data/app/controllers/active_storage/direct_uploads_controller.rb

@@ -11,7 +11,7 @@ class ActiveStorage::DirectUploadsController < ActiveStorage::BaseController
 
   private
     def blob_args
-      params.require(:blob).permit(:filename, :byte_size, :checksum, :content_type, metadata: {}).to_h.symbolize_keys
+      params.expect(blob: [:filename, :byte_size, :checksum, :content_type, metadata: {}]).to_h.symbolize_keys
     end
 
     def direct_upload_json(blob)

data/app/controllers/active_storage/disk_controller.rb

@@ -17,6 +17,8 @@ class ActiveStorage::DiskController < ActiveStorage::BaseController
     end
   rescue Errno::ENOENT
     head :not_found
+  rescue ActiveStorage::InvalidKeyError
+    head :not_found
   end
 
   def update
@@ -25,13 +27,15 @@ class ActiveStorage::DiskController < ActiveStorage::BaseController
         named_disk_service(token[:service_name]).upload token[:key], request.body, checksum: token[:checksum]
         head :no_content
       else
-        head :unprocessable_entity
+        head ActionDispatch::Constants::UNPROCESSABLE_CONTENT
       end
     else
       head :not_found
     end
   rescue ActiveStorage::IntegrityError
-    head :unprocessable_entity
+    head ActionDispatch::Constants::UNPROCESSABLE_CONTENT
+  rescue ActiveStorage::InvalidKeyError
+    head ActionDispatch::Constants::UNPROCESSABLE_CONTENT
   end
 
   private

data/app/controllers/concerns/active_storage/streaming.rb

@@ -14,7 +14,8 @@ module ActiveStorage::Streaming
     def send_blob_byte_range_data(blob, range_header, disposition: nil)
       ranges = Rack::Utils.get_byte_ranges(range_header, blob.byte_size)
 
-      return head(:range_not_satisfiable) if ranges.blank? || ranges.all?(&:blank?)
+      return head(:range_not_satisfiable) unless ranges_valid?(ranges)
+      return head(:range_not_satisfiable) if ranges.length > ActiveStorage.streaming_max_ranges
 
       if ranges.length == 1
         range = ranges.first
@@ -51,6 +52,12 @@ module ActiveStorage::Streaming
       )
     end
 
+    def ranges_valid?(ranges)
+      return false if ranges.blank? || ranges.all?(&:blank?)
+
+      ranges.sum { |range| range.end - range.begin } < ActiveStorage.streaming_chunk_max_size
+    end
+
     # Stream the blob from storage directly to the response. The disposition can be controlled by setting +disposition+.
     # The content type and filename is set directly from the +blob+.
     def send_blob_stream(blob, disposition: nil) # :doc:
@@ -61,6 +68,15 @@ module ActiveStorage::Streaming
         blob.download do |chunk|
           stream.write chunk
         end
+      rescue ActiveStorage::FileNotFoundError
+        expires_now
+        head :not_found
+      rescue
+        # Status and caching headers are already set, but not committed.
+        # Change the status to 500 manually.
+        expires_now
+        head :internal_server_error
+        raise
       end
     end
 end

data/app/javascript/activestorage/direct_upload_controller.js

@@ -31,7 +31,8 @@ export class DirectUploadController {
   }
 
   uploadRequestDidProgress(event) {
-    const progress = event.loaded / event.total * 100
+    // Scale upload progress to 0-90% range
+    const progress = (event.loaded / event.total) * 90
     if (progress) {
       this.dispatch("progress", { progress })
     }
@@ -63,5 +64,51 @@ export class DirectUploadController {
   directUploadWillStoreFileWithXHR(xhr) {
     this.dispatch("before-storage-request", { xhr })
     xhr.upload.addEventListener("progress", event => this.uploadRequestDidProgress(event))
+
+    // Start simulating progress after upload completes
+    xhr.upload.addEventListener("loadend", () => {
+      this.simulateResponseProgress(xhr)
+    })
+  }
+
+  simulateResponseProgress(xhr) {
+    let progress = 90
+    const startTime = Date.now()
+
+    const updateProgress = () => {
+      // Simulate progress from 90% to 99% over estimated time
+      const elapsed = Date.now() - startTime
+      const estimatedResponseTime = this.estimateResponseTime()
+      const responseProgress = Math.min(elapsed / estimatedResponseTime, 1)
+      progress = 90 + (responseProgress * 9) // 90% to 99%
+
+      this.dispatch("progress", { progress })
+
+      // Continue until response arrives or we hit 99%
+      if (xhr.readyState !== XMLHttpRequest.DONE && progress < 99) {
+        requestAnimationFrame(updateProgress)
+      }
+    }
+
+    // Stop simulation when response arrives
+    xhr.addEventListener("loadend", () => {
+      this.dispatch("progress", { progress: 100 })
+    })
+
+    requestAnimationFrame(updateProgress)
+  }
+
+  estimateResponseTime() {
+    // Base estimate: 1 second for small files, scaling up for larger files
+    const fileSize = this.file.size
+    const MB = 1024 * 1024
+
+    if (fileSize < MB) {
+      return 1000 // 1 second for files under 1MB
+    } else if (fileSize < 10 * MB) {
+      return 2000 // 2 seconds for files 1-10MB
+    } else {
+      return 3000 + (fileSize / MB * 50) // 3+ seconds for larger files
+    }
   }
 }

data/app/javascript/activestorage/index.js

@@ -2,7 +2,8 @@ import { start } from "./ujs"
 import { DirectUpload } from "./direct_upload"
 import { DirectUploadController } from "./direct_upload_controller"
 import { DirectUploadsController } from "./direct_uploads_controller"
-export { start, DirectUpload, DirectUploadController, DirectUploadsController }
+import { dispatchEvent } from "./helpers"
+export { start, DirectUpload, DirectUploadController, DirectUploadsController, dispatchEvent }
 
 function autostart() {
   if (window.ActiveStorage) {

data/app/models/active_storage/blob/representable.rb

@@ -25,17 +25,83 @@ module ActiveStorage::Blob::Representable
   #
   #   <%= image_tag Current.user.avatar.variant(resize_to_limit: [100, 100]) %>
   #
-  # This will create a URL for that specific blob with that specific variant, which the ActiveStorage::RepresentationsController
-  # can then produce on-demand.
+  # This will create a URL for that specific blob with that specific variant, which the ActiveStorage::Representations::ProxyController
+  # or ActiveStorage::Representations::RedirectController can then produce on-demand.
   #
   # Raises ActiveStorage::InvariableError if the variant processor cannot
   # transform the blob. To determine whether a blob is variable, call
   # ActiveStorage::Blob#variable?.
+  #
+  # ==== Options
+  #
+  # Options are defined by the {image_processing gem}[https://github.com/janko/image_processing],
+  # and depend on which variant processor you are using:
+  # {Vips}[https://github.com/janko/image_processing/blob/master/doc/vips.md] or
+  # {MiniMagick}[https://github.com/janko/image_processing/blob/master/doc/minimagick.md].
+  # However, both variant processors support the following options:
+  #
+  # [+:resize_to_limit+]
+  #   Downsizes the image to fit within the specified dimensions while retaining
+  #   the original aspect ratio. Will only resize the image if it's larger than
+  #   the specified dimensions.
+  #
+  #       user.avatar.variant(resize_to_limit: [100, 100])
+  #
+  # [+:resize_to_fit+]
+  #   Resizes the image to fit within the specified dimensions while retaining
+  #   the original aspect ratio. Will downsize the image if it's larger than the
+  #   specified dimensions or upsize if it's smaller.
+  #
+  #       user.avatar.variant(resize_to_fit: [100, 100])
+  #
+  # [+:resize_to_fill+]
+  #   Resizes the image to fill the specified dimensions while retaining the
+  #   original aspect ratio. If necessary, will crop the image in the larger
+  #   dimension.
+  #
+  #       user.avatar.variant(resize_to_fill: [100, 100])
+  #
+  # [+:resize_and_pad+]
+  #   Resizes the image to fit within the specified dimensions while retaining
+  #   the original aspect ratio. If necessary, will pad the remaining area with
+  #   transparent color if source image has alpha channel, black otherwise.
+  #
+  #       user.avatar.variant(resize_and_pad: [100, 100])
+  #
+  # [+:crop+]
+  #   Extracts an area from an image. The first two arguments are the left and
+  #   top edges of area to extract, while the last two arguments are the width
+  #   and height of the area to extract.
+  #
+  #       user.avatar.variant(crop: [20, 50, 300, 300])
+  #
+  # [+:rotate+]
+  #   Rotates the image by the specified angle.
+  #
+  #       user.avatar.variant(rotate: 90)
+  #
+  # Some options, including those listed above, can accept additional
+  # processor-specific values which can be passed as a trailing hash:
+  #
+  #     <!-- Vips supports configuring `crop` for many of its transformations -->
+  #     <%= image_tag user.avatar.variant(resize_to_fill: [100, 100, { crop: :centre }]) %>
+  #
+  # If migrating an existing application between MiniMagick and Vips, you will
+  # need to update processor-specific options:
+  #
+  #     <!-- MiniMagick -->
+  #     <%= image_tag user.avatar.variant(resize_to_limit: [100, 100], format: :jpeg,
+  #           sampling_factor: "4:2:0", strip: true, interlace: "JPEG", colorspace: "sRGB", quality: 80) %>
+  #
+  #     <!-- Vips -->
+  #     <%= image_tag user.avatar.variant(resize_to_limit: [100, 100], format: :jpeg,
+  #           saver: { subsample_mode: "on", strip: true, interlace: true, quality: 80 }) %>
+  #
   def variant(transformations)
     if variable?
       variant_class.new(self, ActiveStorage::Variation.wrap(transformations).default_to(default_variant_transformations))
     else
-      raise ActiveStorage::InvariableError
+      raise ActiveStorage::InvariableError, "Can't transform blob with ID=#{id} and content_type=#{content_type}"
     end
   end
 
@@ -64,7 +130,7 @@ module ActiveStorage::Blob::Representable
     if previewable?
       ActiveStorage::Preview.new(self, transformations)
     else
-      raise ActiveStorage::UnpreviewableError
+      raise ActiveStorage::UnpreviewableError, "No previewer found for blob with ID=#{id} and content_type=#{content_type}"
     end
   end
 
@@ -89,7 +155,7 @@ module ActiveStorage::Blob::Representable
     when variable?
       variant transformations
     else
-      raise ActiveStorage::UnrepresentableError
+      raise ActiveStorage::UnrepresentableError, "No previewer found and can't transform blob with ID=#{id} and content_type=#{content_type}"
     end
   end