active_storage_validations 3.0.6 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb09e2b76b2325f8dab17bd4774b91bb1f041766e3705e563f338951d04e191a
-  data.tar.gz: 56ed87a99def7941a8d17e4433980c947c8771c3dd42141d0f1f13702c8556c2
+  metadata.gz: 24d8643d1f970252124d4429ca9bc15b222ef203cdcae93427a0860c7190c370
+  data.tar.gz: 62a74e517b40b32dba39c0529f0d4e4529d615a11decdebf8ec338505c082435
 SHA512:
-  metadata.gz: 84fb802a4958ef5b3e00e088383768540849a883b3f2bd757b19ed24c0516d1fd8a498aaaac93ef0e02d6105dca0c6058e5a85ac3a4d1a1b0d79cd1e682dfb45
-  data.tar.gz: de96e6b525ca4ff0e9e3342b9bd1719c199e956b807467c62d6f063e649f80348e9b323525b1c99f203b025e08a995bc8534b1fd01c434579eca5526ee2ced61
+  metadata.gz: c8fa701638b13eea05351e5a76847d144e93ec83b4e14a8d5b5e23ae71944eabd092704c723fcb81e9c44a3fb909ab6431be680390ee414f13002af671792ca1
+  data.tar.gz: 82af6984104d830cd7eda7ffdb557f3bb997d8bb59fbef6edc85e0830c3a4397209d4ab31f6427f5945fe392935fefe7c49dc6cabd87c840a34592e8b827f300

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2018-2025 Igor Kasyanchuk
+Copyright 2018-2026 Igor Kasyanchuk
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -3,7 +3,7 @@
 
 # Active Storage Validations
 
-[![MiniTest](https://github.com/igorkasyanchuk/active_storage_validations/workflows/MiniTest/badge.svg)](https://github.com/igorkasyanchuk/active_storage_validations/actions)
+[![CI](https://github.com/igorkasyanchuk/active_storage_validations/actions/workflows/main.yml/badge.svg)](https://github.com/igorkasyanchuk/active_storage_validations/actions/workflows/main.yml)
 [![RailsJazz](https://github.com/igorkasyanchuk/rails_time_travel/blob/main/docs/my_other.svg?raw=true)](https://www.railsjazz.com)
 [![https://www.patreon.com/igorkasyanchuk](https://github.com/igorkasyanchuk/rails_time_travel/blob/main/docs/patron.svg?raw=true)](https://www.patreon.com/igorkasyanchuk)
 
@@ -11,7 +11,7 @@
 
 Active Storage Validations is a gem that allows you to add validations for Active Storage attributes.
 
-This gems is doing it right for you! Just use `validates :avatar, attached: true, content_type: 'image/png'` and that's it!
+This gem is doing it right for you! Just use `validates :avatar, attached: true, content_type: 'image/png'` and that's it!
 
 ## Table of Contents
 
@@ -22,6 +22,7 @@ This gems is doing it right for you! Just use `validates :avatar, attached: true
   - [Using video and audio metadata validators](#using-video-and-audio-metadata-validators)
   - [Using pdf metadata validators](#using-pdf-metadata-validators)
   - [Using content type spoofing protection validator option](#using-content-type-spoofing-protection-validator-option)
+  - [Configuration](#configuration)
 - [Validators](#validators)
   - [Attached](#attached)
   - [Limit](#limit)
@@ -30,11 +31,11 @@ This gems is doing it right for you! Just use `validates :avatar, attached: true
   - [Total size](#total-size)
   - [Dimension](#dimension)
   - [Duration](#duration)
+  - [With audio](#with-audio)
   - [Aspect ratio](#aspect-ratio)
   - [Processable file](#processable-file)
   - [Pages](#pages)
-- [Upgrading from 1.x to 2.x](#upgrading-from-1x-to-2x)
-- [Upgrading from 2.x to 3.x](#upgrading-from-2x-to-3x)
+- [Upgrading](#upgrading)
 - [Internationalization (I18n)](#internationalization-i18n)
 - [Test matchers](#test-matchers)
 - [Contributing](#contributing)
@@ -44,7 +45,7 @@ This gems is doing it right for you! Just use `validates :avatar, attached: true
 
 ### Installation
 
-Active Storage Validations work with Rails 6.1.4 onwards. Add this line to your application's Gemfile:
+Active Storage Validations work with Rails 7.0.1 onwards and Ruby 3.3 onwards. Add this line to your application's Gemfile:
 
 ```ruby
 gem 'active_storage_validations'
@@ -65,16 +66,18 @@ Once you have installed the gem, I18n error messages will be added automatically
 Optionally, to use the image metadata validators (`dimension`, `aspect_ratio` and `processable_file`), you will have to add one of the corresponding gems:
 
 ```ruby
-gem 'mini_magick', '>= 4.9.5'
-# Or
 gem 'ruby-vips', '>= 2.1.0'
+# Or
+gem 'mini_magick', '>= 4.9.5'
 ```
 
-Plus, you have to be sure to have the corresponding command-line tool installed on your system. For example, to use `mini_magick` gem, you need to have `imagemagick` installed on your system (both on your local and in your CI / production environments).
+Plus, you have to be sure to have the corresponding command-line tool installed on your system (`libvips` for `ruby-vips`, or ImageMagick for `mini_magick` — both locally and in CI / production).
+
+We recommend **libvips** (`ruby-vips` + `config.active_storage.variant_processor = :vips`) for these validators. Rails already defaults Active Storage variants to libvips ([`ActiveStorage::Variant`](https://api.rubyonrails.org/classes/ActiveStorage/Variant.html)), and our [image processor benchmarks](benchmark/BASELINE.md#image-processors--vips-vs-mini_magick) show cold metadata analysis is about **8× faster** than MiniMagick/ImageMagick on the same machine and fixtures. Warm validations (cached `asv_*` metadata) are similar for both.
 
 ### Using video and audio metadata validators
 
-To use the video and audio metadata validators (`dimension`, `aspect_ratio`, `processable_file` and `duration`), you will not need to add any gems. However you will need to have the `ffmpeg` command-line tool installed on your system (once again, be sure to have it installed both on your local and in your CI / production environments).
+To use the video and audio metadata validators (`dimension`, `aspect_ratio`, `processable_file`, `duration` and `with_audio`), you will not need to add any gems. However you will need to have the `ffmpeg` command-line tool installed on your system (once again, be sure to have it installed both on your local and in your CI / production environments).
 
 ### Using pdf metadata validators
 
@@ -82,9 +85,51 @@ To use the pdf metadata validators (`dimension`, `aspect_ratio`, `processable_fi
 
 ### Using content type spoofing protection validator option
 
-To use the `spoofing_protection` option with the `content_type` validator, you only need to have the UNIX `file` command on your system.
+To use the `spoofing_protection` option with the `content_type` validator:
+
+- Default backend (`true` / `:file`): the UNIX [`file`](https://en.wikipedia.org/wiki/File_(command)) command (usually preinstalled on UNIX systems)
+- Magika backend (`:magika`): the [Google Magika](https://github.com/google/magika) CLI — install via `brew install magika`, their [install script](https://securityresearch.google/magika/getting-started/installation/), `cargo install --locked magika-cli`, or `pipx install magika`
+
+Both backends are optional system tools (not Ruby gems). Prefer `:magika` when you can install the CLI — it is generally more accurate than `file`, especially on textual / ambiguous formats. Be sure to install Magika in CI / production if you enable `:magika`.
+
+If you want some inspiration about how to add `imagemagick`, `libvips`, `ffmpeg`, `poppler` or `magika` to your docker image, you can check how we do it for the gem CI (https://github.com/igorkasyanchuk/active_storage_validations/blob/master/.github/workflows/main.yml)
+
+### Configuration
+
+Optional global settings can go in an initializer. Example template:
+
+```ruby
+# config/initializers/active_storage_validations.rb
+ActiveStorageValidations.configure do |config|
+  # Infer HTML accept= on file_field from content_type validators (default: true)
+  # config.infer_file_field_accept = false
+
+  # Max time for external analyzer commands: ffprobe, pdfinfo, file, magika, ImageMagick identify, libvips
+  # (default: 10.seconds; set to nil to disable)
+  # config.command_timeout = 10.seconds
+end
+
+# Optional: monitor analyzer timeouts
+# ActiveSupport::Notifications.subscribe("timeout.active_storage_validations") do |*args|
+#   event = ActiveSupport::Notifications::Event.new(*args)
+#   Rails.logger.warn("[ASV] command timeout: #{event.payload}")
+# end
+```
+
+`command_timeout` bounds metadata analysis used by `dimension`, `aspect_ratio`, `duration`, `with_audio`, `pages`, `processable_file`, and `content_type` (with `spoofing_protection`). When a command times out, analysis fails closed and the validator adds its usual error (`file_not_processable` / `media_metadata_missing` / `audio_missing` / content-type errors) — there is no separate timeout error message.
+
+The 10s default is enough for typical uploads. Raise it (or set `nil`) if you analyze very large videos/PDFs, especially on slow or network storage — otherwise those files can start failing validation after upgrade. See [upgrade to 4.x](docs/upgrade_to_4.md#analyzer-command-timeout).
+
+Per-validator override (applies to the analysis triggered by that validator; the first analysis for a blob is cached):
+
+```ruby
+validates :video, duration: { less_than: 5.minutes, timeout: 30.seconds }
+```
 
-If you want some inspiration about how to add `imagemagick`, `libvips`, `ffmpeg` or `poppler` to your docker image, you can check how we do it for the gem CI (https://github.com/igorkasyanchuk/active_storage_validations/blob/master/.github/workflows/main.yml)
+Notes:
+- Setting `command_timeout` (or per-validator `timeout:`) to `nil` disables the deadline
+- ImageMagick analysis runs `identify` through the same killable command runner (MiniMagick is only used to build the argv)
+- For libvips, a timeout may not immediately free the Ruby thread stuck in FFI/C; the validation still fails closed and emits `timeout.active_storage_validations`
 
 ## Validators
 
@@ -96,6 +141,7 @@ If you want some inspiration about how to add `imagemagick`, `libvips`, `ffmpeg`
 - [Total size](#total-size): validates total file size for several files
 - [Dimension](#dimension): validates image / video dimensions
 - [Duration](#duration): validates video / audio duration
+- [With audio](#with-audio): validates whether a video contains an audio track
 - [Aspect ratio](#aspect-ratio): validates image / video aspect ratio
 - [Processable file](#processable-file): validates if a file can be processed
 - [Pages](#pages): validates pdf number of pages
@@ -205,10 +251,11 @@ Validates if the attachment has an allowed content type.
 
 #### Options
 
-The `content_type` validator has 3 possible options:
+The `content_type` validator has several possible options:
 - `with`: defines the allowed content type (string, symbol or regex)
 - `in`: defines the allowed content types (array of strings or symbols)
-- `spoofing_protection`: enables content type spoofing protection (boolean, defaults to `false`)
+- `spoofing_protection`: enables content type spoofing protection (`false` by default). Allowed values: `true` / `:file` (UNIX `file` CLI), `:magika` (Google Magika CLI)
+- `timeout`: overrides the global analyzer [command timeout](#configuration) when spoofing protection runs `file` or `magika`
 
 As mentioned above, this validator can define content types in several ways:
 - String: `image/png` or `png`
@@ -226,32 +273,55 @@ class User < ApplicationRecord
   validates :avatar, content_type: :png # only allows PNG images, same as { with: :png }
   validates :avatar, content_type: /\Avideo\/.*\z/ # only allows video files
   validates :avatar, content_type: ['image/png', 'image/jpeg'] # only allows PNG and JPEG images
-  validates :avatar, content_type: { in: [:png, :jpeg], spoofing_protection: true } # only allows PNG, JPEG and their variants, with spoofing protection enabled
+  validates :avatar, content_type: { in: [:png, :jpeg], spoofing_protection: true } # UNIX `file` backend (same as :file)
+  validates :avatar, content_type: { in: [:png, :jpeg], spoofing_protection: :magika } # Google Magika CLI backend
+  # Stronger protection for media/PDF: sniff + parse
+  validates :avatar, content_type: { in: [:png, :jpeg], spoofing_protection: true }, processable_file: true
 end
 ```
 
-#### Best practices
+#### HTML `accept` attribute (FormBuilder)
 
-When using the `content_type` validator, it is recommended to reflect the allowed content types in the html [`accept`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept) attribute in the corresponding file field in your views. This will prevent users from trying to upload files with not allowed content types (however it is only an UX improvement, a malicious user can still try to upload files with not allowed content types therefore the backend validation).
+When using Rails' `FormBuilder#file_field`, the gem automatically sets the HTML [`accept`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept) attribute from your `content_type` validators. This improves UX by filtering selectable files in the browser dialog. It is only a frontend hint: a malicious user can still submit disallowed types, so keep the backend validation.
 
-For example, if you want to allow PNG and JPEG images only, you can do this:
 ```ruby
 class User < ApplicationRecord
-  ACCEPTED_CONTENT_TYPES = ['image/png', 'image/jpeg'].freeze
-
   has_one_attached :avatar
 
-  validates :avatar, content_type: ACCEPTED_CONTENT_TYPES
+  validates :avatar, content_type: ['image/png', 'image/jpeg']
 end
 ```
 
 ```erb
 <%= form_with model: @user do |f| %>
-  <%= f.file_field :avatar,
-                   accept: ACCEPTED_CONTENT_TYPES.join(',') %>
+  <%= f.file_field :avatar %>
+  <%# => <input type="file" accept="image/png,image/jpeg" ...> %>
 <% end %>
 ```
 
+Explicit `accept` values are never overridden. You can also disable inference:
+
+```erb
+<%# Per field %>
+<%= f.file_field :avatar, infer_accept: false %>
+
+<%# Or set a custom accept value %>
+<%= f.file_field :avatar, accept: "image/*" %>
+```
+
+```ruby
+# Globally — see [Configuration](#configuration) for a full initializer template
+ActiveStorageValidations.infer_file_field_accept = false
+
+# Equivalent:
+ActiveStorageValidations.configure { |config| config.infer_file_field_accept = false }
+```
+
+Notes:
+- Only broad MIME-type regexes of the form `/\Aimage\/.*\z/` (or `video` / `audio` / etc.) are inferred, as `image/*`
+- Other regexes (e.g. `/\Aimage\/(png|gif)\z/`) and Proc / dynamic `content_type` options are skipped, since they cannot be reliably represented in `accept`
+- Conditional validators (`if:` / `unless:`) are not evaluated: their content types are always included in `accept`, even when the condition would skip the validator for that record. Backend validation is unchanged; use `infer_accept: false` (or a custom `accept:`) if the picker must match the active conditions
+
 #### Content type shorthands
 
 If you choose to use a content_type 'shorthand' (like `png`), note that it will be converted to a full content type using `Marcel::MimeType.for` under the hood. Therefore, you should check if the content_type is registered by [`Marcel::EXTENSIONS`](https://github.com/rails/marcel/blob/main/lib/marcel/tables.rb). If it's not, you can register it by adding the following code to your `config/initializers/mime_types.rb` file:
@@ -264,7 +334,15 @@ Be sure to at least include one the `extensions`, `parents` or `magic` option, o
 
 #### Content type spoofing protection
 
-By default, the gem does not prevent content type spoofing. You can enable it by setting the `spoofing_protection` option to `true` in your validator options.
+By default, the gem does not prevent content type spoofing. Enable it with `spoofing_protection`:
+
+```ruby
+validates :avatar, content_type: { in: [:png, :jpeg], spoofing_protection: true }     # => :file (UNIX file CLI)
+validates :avatar, content_type: { in: [:png, :jpeg], spoofing_protection: :file }    # explicit
+validates :avatar, content_type: { in: [:png, :jpeg], spoofing_protection: :magika }  # Google Magika CLI
+```
+
+Override binary paths with `ActiveStorage.paths[:file]` / `ActiveStorage.paths[:magika]` if needed.
 
 <details>
 <summary>
@@ -279,9 +357,22 @@ File content type spoofing happens when an ill-intentioned user uploads a file w
 How do we prevent it?
 </summary>
 
-The spoofing protection relies on both the UNIX `file` command and `Marcel` gem. Be careful, since it needs to load the whole file io to perform the analysis, it will use a lot of RAM for very large files. Therefore it could be a wise decision not to enable it in this case.
+Spoofing protection compares the declared Active Storage content type to a type detected by a sniffer CLI, then uses `Marcel` parent types so near-matches still pass:
+
+- `:file` (default) — UNIX `file` / libmagic, mostly magic bytes / headers. Zero extra install on most UNIX systems.
+- `:magika` — [Google Magika](https://github.com/google/magika) CLI (ML sniffer; samples begin/middle/end of the file). Generally more accurate than `file`, especially on textual / ambiguous formats (Google reports ~99% F1 vs ~88% for `file --mime` on overlapping types). Prefer `:magika` when you can install the CLI.
+
+Neither backend fully parses the file. They do **not** load the whole file into RAM. For already-persisted blobs (e.g. remote storage), the analyzer still downloads the blob to a local tempfile before sniffing. That download is streamed in chunks to disk, but it can still be costly for very large files. Local path uploads are analyzed in place.
+
+Detected types are cached on the blob as `asv_content_type` + `asv_content_type_backend`. Switching backend re-analyzes. Legacy blobs that only have `asv_content_type` (no backend key) are treated as `:file` and keep using the cache — they are not re-analyzed.
 
-Take note that the `file` analyzer will not find the exactly same content type as the ActiveStorage blob (ActiveStorage content type detection relies on a different logic using first 4kb of content + filename + extension). To handle this issue, we consider a close parent content type to be a match. For example, for an ActiveStorage blob which content type is `video/x-ms-wmv`, the `file` analyzer will probably detect a `video/x-ms-asf` content type, this will be considered as a valid match because these 2 content types are closely related. The correlation mapping is based on `Marcel::TYPE_PARENTS` table.
+Sniffers will not always return the exact same MIME as Active Storage (AS uses first ~4kb + filename + extension). Close parent types are accepted via `Marcel::TYPE_PARENTS` (e.g. `video/x-ms-wmv` vs `video/x-ms-asf`).
+
+For stronger protection on images / video / audio / PDF, combine sniffing with parse validation:
+
+```ruby
+validates :avatar, content_type: { in: [:png, :jpeg], spoofing_protection: true }, processable_file: true
+```
 </details>
 
 <details>
@@ -289,9 +380,11 @@ Take note that the `file` analyzer will not find the exactly same content type a
 Edge cases
 </summary>
 
-The difficulty to accurately predict a mime type may generate false positives, if so there are two solutions available:
-- If the ActiveStorage blob content type is closely related to the detected content type using the `file` analyzer, you can enhance `Marcel::TYPE_PARENTS` mapping using `Marcel::MimeType.extend "application/x-rar-compressed", parents: %(application/x-rar)` in the `config/initializers/mime_types.rb` file. (Please drop an issue so we can add it to the gem for everyone!)
-- If the ActiveStorage blob content type is not closely related, you still can disable the content type spoofing protection in the validator, if so, please drop us an issue so we can fix it for everyone!
+The difficulty to accurately predict a mime type may generate false positives, if so there are several solutions available:
+- Try the other sniffer backend (`:file` vs `:magika`)
+- For media/PDF that sniffers misidentify but that open correctly, add `processable_file: true`
+- If the ActiveStorage blob content type is closely related to the detected content type, enhance `Marcel::TYPE_PARENTS` mapping using `Marcel::MimeType.extend "application/x-rar-compressed", parents: %(application/x-rar)` in the `config/initializers/mime_types.rb` file. (Please drop an issue so we can add it to the gem for everyone!)
+- If needed, disable spoofing protection in the validator, and please drop us an issue so we can fix it for everyone!
 </details>
 
 
@@ -326,7 +419,7 @@ Validates each attached file size.
 
 #### Options
 
-The `size` validator has 5 possible options:
+The `size` validator has 6 possible options:
 - `less_than`: defines the strict maximum allowed file size
 - `less_than_or_equal_to`: defines the maximum allowed file size
 - `greater_than`: defines the strict minimum allowed file size
@@ -384,7 +477,7 @@ Validates the total file size for several files.
 
 #### Options
 
-The `total_size` validator has 5 possible options:
+The `total_size` validator has 6 possible options:
 - `less_than`: defines the strict maximum allowed total file size
 - `less_than_or_equal_to`: defines the maximum allowed total file size
 - `greater_than`: defines the strict minimum allowed total file size
@@ -434,7 +527,7 @@ The `total_size` validator error messages expose 4 values that you can use:
 
 Validates the dimension of the attached image / video files.
 It can also be used for pdf files, but it will only analyze the pdf first page, and will assume a DPI of 72.
-(be sure to have the right dependencies installed as mentioned in [installation](#installation))
+(be sure to have the right dependencies installed as mentioned in [Getting started](#getting-started))
 
 #### Options
 
@@ -449,6 +542,7 @@ The `dimension` validator has several possible options:
   - `in`: defines the allowed height range (range)
 - `min`: defines the minimum allowed width and height (range)
 - `max`: defines the maximum allowed width and height (range)
+- `timeout`: overrides the global analyzer [command timeout](#configuration) for this validation
 
 #### Examples
 
@@ -499,17 +593,18 @@ The `dimension` validator error messages expose 6 values that you can use:
 ### Duration
 
 Validates the duration of the attached audio / video files.
-(be sure to have the right dependencies installed as mentioned in [installation](#installation))
+(be sure to have the right dependencies installed as mentioned in [Using video and audio metadata validators](#using-video-and-audio-metadata-validators))
 
 #### Options
 
-The `duration` validator has 5 possible options:
+The `duration` validator has several possible options:
 - `less_than`: defines the strict maximum allowed file duration
 - `less_than_or_equal_to`: defines the maximum allowed file duration
 - `greater_than`: defines the strict minimum allowed file duration
 - `greater_than_or_equal_to`: defines the minimum allowed file duration
 - `between`: defines the allowed file duration range
 - `equal_to`: defines the allowed duration
+- `timeout`: overrides the global analyzer [command timeout](#configuration) for this validation
 
 #### Examples
 
@@ -524,6 +619,7 @@ class User < ApplicationRecord
   validates :intro_song, duration: { greater_than_or_equal_to: 1.second } # restricts the file duration to >= 1 second
   validates :intro_song, duration: { between: 1.second..2.minutes } # restricts the file duration to between 1 second and 2 minutes
   validates :intro_song, duration: { equal_to: 1.minute } # restricts the duration to exactly 1 minute
+  validates :intro_song, duration: { less_than: 5.minutes, timeout: 5.seconds } # custom analyzer timeout
 end
 ```
 
@@ -550,17 +646,59 @@ The `duration` validator error messages expose 4 values that you can use:
 
 ---
 
+### With audio
+
+Validates whether attached video files contain an audio track.
+(be sure to have the right dependencies installed as mentioned in [Using video and audio metadata validators](#using-video-and-audio-metadata-validators))
+
+#### Options
+
+The `with_audio` validator supports:
+- `with`: `true` requires an audio track and `false` rejects one
+- `timeout`: overrides the global analyzer [command timeout](#configuration) for this validation
+
+#### Examples
+
+Use it like this:
+```ruby
+class User < ApplicationRecord
+  has_one_attached :video
+  has_one_attached :silent_video
+
+  validates :video, with_audio: true
+  validates :silent_video, with_audio: { with: false }
+  validates :video, with_audio: { timeout: 5.seconds }
+end
+```
+
+Rails treats a bare `with_audio: false` as a disabled validator. Use the hash form `with_audio: { with: false }` to reject videos that contain audio.
+
+#### Error messages (I18n)
+
+```yml
+en:
+  errors:
+    messages:
+      audio_missing: "must have an audio track"
+      audio_present: "must not have an audio track"
+```
+
+The `with_audio` validator error message exposes the `filename` value containing the current file name.
+
+---
+
 ### Aspect ratio
 
 Validates the aspect ratio of the attached image / video files.
 It can also be used for pdf files, but it will only analyze the pdf first page.
-(be sure to have the right dependencies installed as mentioned in [installation](#installation))
+(be sure to have the right dependencies installed as mentioned in [Getting started](#getting-started))
 
 #### Options
 
 The `aspect_ratio` validator has several options:
 - `with`: defines the allowed aspect ratio (e.g. `:is_16/9`)
 - `in`: defines the allowed aspect ratios (e.g. `%i[square landscape]`)
+- `timeout`: overrides the global analyzer [command timeout](#configuration) for this validation
 
 This validator can define aspect ratios in several ways:
 - Symbols:
@@ -607,11 +745,12 @@ The `aspect_ratio` validator error messages expose 4 values that you can use:
 ### Processable file
 
 Validates if the attached files can be processed by MiniMagick or Vips (image), ffmpeg (video/audio) or poppler (pdf).
-(be sure to have the right dependencies installed as mentioned in [installation](#installation))
+(be sure to have the right dependencies installed as mentioned in [Getting started](#getting-started))
 
 #### Options
 
-The `processable_file` validator has no options.
+The `processable_file` validator supports:
+- `timeout`: overrides the global analyzer [command timeout](#configuration) for this validation
 
 #### Examples
 
@@ -621,9 +760,14 @@ class User < ApplicationRecord
   has_one_attached :avatar
 
   validates :avatar, processable_file: true # ensures that the file is processable by MiniMagick or Vips (image) or ffmpeg (video/audio)
+  validates :avatar, processable_file: { timeout: 5.seconds }
 end
 ```
 
+#### Notes
+
+Rails 7.2.3.2+ / 8.0.5.1+ / 8.1.3.1+ call `Vips.block_untrusted(true)`, so libvips refuses to load formats marked untrusted (e.g. SVG, BMP). Analysis then returns empty metadata by design. `processable_file` does **not** treat that as failure for those content types. `dimension` / `aspect_ratio` still need width/height — use MiniMagick for those formats, or skip those validators for them.
+
 #### Error messages (I18n)
 
 ```yml
@@ -641,17 +785,18 @@ The `processable_file` validator error messages expose 1 value that you can use:
 ### Pages
 
 Validates each attached pdf file number of pages.
-(be sure to have the right dependencies installed as mentioned in [installation](#installation))
+(be sure to have the right dependencies installed as mentioned in [Using pdf metadata validators](#using-pdf-metadata-validators))
 
 #### Options
 
-The `pages` validator has 6 possible options:
+The `pages` validator has several possible options:
 - `less_than`: defines the strict maximum allowed number of pages
 - `less_than_or_equal_to`: defines the maximum allowed number of pages
 - `greater_than`: defines the strict minimum allowed number of pages
 - `greater_than_or_equal_to`: defines the minimum allowed number of pages
 - `between`: defines the allowed number of pages range
 - `equal_to`: defines the allowed number of pages
+- `timeout`: overrides the global analyzer [command timeout](#configuration) for this validation
 
 #### Examples
 
@@ -692,64 +837,11 @@ The `pages` validator error messages expose 5 values that you can use:
 
 ---
 
-## Upgrading from 1.x to 2.x
-
-If you are upgrading from 1.x to 2.x, you will be pleased to note that a lot of things have been added and improved!
-
-Added features:
-- `duration` validator has been added for audio / video files
-- `dimension` validator now supports videos
-- `aspect_ratio` validator now supports videos
-- `processable_image` validator is now `processable_file` validator and supports image/video/audio
-- Major performance improvement have been added: we now only perform the expensive io analysis operation on the newly attached files. For previously attached files, we validate them using Rails `ActiveStorage::Blob#metadata` internal mecanism ([more here](https://github.com/rails/rails/blob/main/activestorage/app/models/active_storage/blob/analyzable.rb)).
-- All error messages have been given an upgrade and new variables that you can use
-
-But this major version bump also comes with some breaking changes. Below are the main breaking changes you need to be aware of:
-- Error messages
-  - We advise you to replace all the v1 translations by the new v2 rather than changing them one by one. A majority of messages have been completely rewritten to be more consistent and easier to understand.
-  - If you wish to change them one by one, here is the list of changes to make:
-    - Some validator errors have been totally changed:
-      - `limit` validator keys have been totally reworked
-      - `dimension` validator keys have been totally reworked
-      - `content_type` validator keys have been totally reworked
-      - `processable_image` validator keys have been totally reworked
-    - Some keys have been changed:
-      - `image_metadata_missing` has been replaced by `media_metadata_missing`
-      - `aspect_ratio_is_not` has been replaced by `aspect_ratio_not_x_y`
-    - Some error messages variables names have been changed to improve readability:
-      - `aspect_ratio` validator:
-        - `aspect_ratio` has been replaced by `authorized_aspect_ratios`
-      - `content_type` validator:
-        - `authorized_types` has been replaced by `authorized_human_content_types`
-      - `size` validator:
-        - `min_size` has been replaced by `min`
-        - `max_size` has been replaced by `max`
-      - `total_size` validator:
-        - `min_size` has been replaced by `min`
-        - `max_size` has been replaced by `max`
-
-- `content_type` validator
-  - The `:in` option now only accepts 'valid' content types (ie content types deemed by Marcel as valid).
-    - The check was mistakenly only performed on the `:with` option previously. Therefore, invalid content types were accepted in the `:in` option, which is not the expected behavior.
-    - This might break some cases when you had for example `content_type: ['image/png', 'image/jpg']`, because `image/jpg` is not a valid content type, it should be replaced by `image/jpeg`.
-  - An `ArgumentError` is now raised if `image/jpg` is used to make it easier to fix. You should now only use `image/jpeg`.
-
-- `processable_image` validator
-  - The validator has been replaced by `processable_file` validator, be sure to replace `processable_image: true` to `processable_file: true`
-  - The associated matcher has also been updated accordingly, be sure to replace `validate_processable_image_of` to `validate_processable_file_of`
-
-## Upgrading from 2.x to 3.x
-
-Version 3 comes with the ability to support single page pdf `dimension` / `aspect_ratio` analysis, we had to make a breaking change:
-- To analyze PDFs, you must install the `poppler` PDF processing dependency
-  - It's a  Rails-supported PDF processing dependency (https://guides.rubyonrails.org/active_storage_overview.html#requirements)
-  - To install it, check their documentation at this [link](https://pdf2image.readthedocs.io/en/latest/installation.html).
-  - To check if it's installed, execute `pdftoppm -h`.
-  - To install this tool in your CI / production environments, you can check how we do it in our own CI (https://github.com/igorkasyanchuk/active_storage_validations/blob/master/.github/workflows/main.yml)
-
-We also added the `pages` validator to validate pdf number of pages, and the `equal_to` option to `duration`, `size` and `total_size` validators.
-
-Note that, if you do not perform these metadata validations on pdfs, the gem will work the same as in version 2.
+## Upgrading
+
+- [Upgrading to 2.x](docs/upgrade_to_2.md)
+- [Upgrading to 3.x](docs/upgrade_to_3.md)
+- [Upgrading to 4.x](docs/upgrade_to_4.md)
 
 ## Internationalization (I18n)
 
@@ -802,9 +894,11 @@ describe User do
   it { is_expected.to validate_limits_of(:avatar).max(5) }
 
   # content_type:
-  # #allowing, #rejecting
+  # #allowing, #rejecting, #spoofing_protection
   it { is_expected.to validate_content_type_of(:avatar).allowing('image/png', 'image/gif') } # possible to use an Array or *splatted array
   it { is_expected.to validate_content_type_of(:avatar).rejecting('text/plain', 'text/xml') } # possible to use an Array or *splatted array
+  it { is_expected.to validate_content_type_of(:avatar).allowing('image/png').spoofing_protection } # true / :file
+  it { is_expected.to validate_content_type_of(:avatar).allowing('image/png').spoofing_protection(:magika) }
 
   # dimension:
   # #width, #height, #width_min, #height_min, #width_max, #height_max, #width_between, #height_between
@@ -844,6 +938,10 @@ describe User do
   it { is_expected.to validate_duration_of(:introduction).between(100..500.seconds) }
   it { is_expected.to validate_duration_of(:avatar).equal_to(5.minutes) }
 
+  # with_audio
+  it { is_expected.to validate_with_audio_of(:video) }
+  it { is_expected.to validate_with_audio_of(:silent_video).without_audio }
+
   # pages:
   # #less_than, #less_than_or_equal_to, #greater_than, #greater_than_or_equal_to, #between, #equal_to
   it { is_expected.to validate_pages_of(:contract).less_than(50) }
@@ -856,7 +954,7 @@ end
 ```
 (Note that matcher methods are chainable)
 
-All matchers can currently be customized with Rails validation options:
+All matchers can currently be customized with these options:
 
 ```ruby
 describe User do
@@ -867,8 +965,17 @@ describe User do
   it { is_expected.to validate_attached_of(:avatar).on(:update) }
   it { is_expected.to validate_attached_of(:avatar).on(%i[update custom]) }
 
+  # :except_on (Rails >= 8.0)
+  it { is_expected.to validate_attached_of(:avatar).except_on(:update) }
+  it { is_expected.to validate_attached_of(:avatar).except_on(%i[update custom]) }
+
   # :message
   it { is_expected.to validate_dimensions_of(:avatar).width(250).with_message('Invalid dimensions.') }
+
+  # :timeout (analyzer command timeout — metadata validators + content_type with spoofing)
+  it { is_expected.to validate_duration_of(:video).less_than(5.minutes).timeout(30.seconds) }
+  it { is_expected.to validate_with_audio_of(:video).timeout(5.seconds) }
+  it { is_expected.to validate_processable_file_of(:avatar).timeout(5.seconds) }
 end
 ```
 
@@ -899,40 +1006,44 @@ Then you can use the matchers with the syntax specified in the RSpec section, ju
 
 If you want to contribute to the project, you will have to fork the repository and create a new branch from the `master` branch. Then build your feature, or fix the issue, and create a pull request. Be sure to add tests for your changes.
 
+AI coding agents: see [AGENTS.md](AGENTS.md) for architecture, test commands, and contribution patterns. Commit and PR titles follow [Conventional Commits](.cursor/rules/git.mdc).
+
 Before submitting your pull request, run the tests to make sure everything works as expected.
 
 To run the gem tests, launch the following commands in the root folder of gem repository:
 
-* `BUNDLE_GEMFILE=gemfiles/rails_6_1_4.gemfile bundle exec rake test` to run for Rails 6.1.4
-* `BUNDLE_GEMFILE=gemfiles/rails_7_0.gemfile bundle exec rake test` to run for Rails 7.0
-* `BUNDLE_GEMFILE=gemfiles/rails_7_1.gemfile bundle exec rake test` to run for Rails 7.1
-* `BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle exec rake test` to run for Rails 7.2
-* `BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle exec rake test` to run for Rails 8.0
-* `BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile bundle exec rake test` to run for Rails 8.1
-* `BUNDLE_GEMFILE=gemfiles/rails_next.gemfile bundle exec rake test` to run for Rails main
+* `BUNDLE_GEMFILE=gemfiles/rails_7_0_1.gemfile bundle exec rake spec` to run for Rails 7.0.1
+* `BUNDLE_GEMFILE=gemfiles/rails_7_1.gemfile bundle exec rake spec` to run for Rails 7.1
+* `BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle exec rake spec` to run for Rails 7.2
+* `BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle exec rake spec` to run for Rails 8.0
+* `BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile bundle exec rake spec` to run for Rails 8.1
+* `BUNDLE_GEMFILE=gemfiles/rails_next.gemfile bundle exec rake spec` to run for Rails main
 
 Snippet to run in console:
 
 ```bash
-BUNDLE_GEMFILE=gemfiles/rails_6_1_4.gemfile bundle
-BUNDLE_GEMFILE=gemfiles/rails_7_0.gemfile bundle
+BUNDLE_GEMFILE=gemfiles/rails_7_0_1.gemfile bundle
 BUNDLE_GEMFILE=gemfiles/rails_7_1.gemfile bundle
 BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle
 BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle
 BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile bundle
 BUNDLE_GEMFILE=gemfiles/rails_next.gemfile bundle
-BUNDLE_GEMFILE=gemfiles/rails_6_1_4.gemfile bundle exec rake test
-BUNDLE_GEMFILE=gemfiles/rails_7_0.gemfile bundle exec rake test
-BUNDLE_GEMFILE=gemfiles/rails_7_1.gemfile bundle exec rake test
-BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle exec rake test
-BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle exec rake test
-BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile bundle exec rake test
-BUNDLE_GEMFILE=gemfiles/rails_next.gemfile bundle exec rake test
+BUNDLE_GEMFILE=gemfiles/rails_7_0_1.gemfile bundle exec rake spec
+BUNDLE_GEMFILE=gemfiles/rails_7_1.gemfile bundle exec rake spec
+BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle exec rake spec
+BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle exec rake spec
+BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile bundle exec rake spec
+BUNDLE_GEMFILE=gemfiles/rails_next.gemfile bundle exec rake spec
 ```
 
 Tips:
-- To focus a specific test, use the `focus` class method provided by [minitest-focus](https://github.com/minitest/minitest-focus)
-- To focus a specific file, use the TEST option provided by minitest, e.g. to only run `size_validator_test.rb` file you will launch the following command: `bundle exec rake test TEST=test/validators/size_validator_test.rb`
+- To focus examples, tag them with `:focus` (or use `fit` / `fdescribe`); RSpec is configured with `filter_run_when_matching :focus`
+- To run a specific file: `bundle exec rspec spec/validators/size_validator_spec.rb`
+- Image processor: CI runs both via `IMAGE_PROCESSOR=vips` / `IMAGE_PROCESSOR=mini_magick`. Locally, unset means validators use MiniMagick (ASV default) and both analyzer unit specs run; setting the env selects that processor for validators and excludes the other processor’s tagged examples (so they do not show as pending)
+
+### Benchmarks
+
+Optional wall-clock / ips suite for metadata validators (cold analysis vs cached `asv_*` hits) lives under [`benchmark/`](benchmark/). See [`benchmark/README.md`](benchmark/README.md) for setup, how to run, and how to refresh [`benchmark/BASELINE.md`](benchmark/BASELINE.md). CI runs the suite informationally (no fail-on-regression).
 
 
 ## Additional information