activestorage-validator 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb2851d4b64cc39176ceaba155c80ac8989930899110e55f471c67df9d78a1bc
-  data.tar.gz: ea620cd996d2b50cf53e058fb43acc89652c5edaaa754de8f333855bab4f177e
+  metadata.gz: acc9fae7338e419736df276e25e94e198cdc8a0ca9a2b80210c3175d684f5f22
+  data.tar.gz: 6b9be22b0d25c70bcf08cc51a05f9443982963d7e42e3817b90c60a596e5e071
 SHA512:
-  metadata.gz: 9288e28946a1e1fb38691329eae86807c4d781116b2f64b389a6bc4e8b3c8e87c0cff3342c1bf716693126d84d64d553a0abddd2ae7a99e4fd28855f9940f0db
-  data.tar.gz: 6098588122be931263ae237cd6e486c1a975e446578502179f6b2064ed54ef1397431e3a23ce9aa1c086ecddc3fc49e42a2d402ed725472b57587ca8cc42d975
+  metadata.gz: 57e1e9cd4353cfcb2aaeee8a2eef4bbedfe49b3382a3cacc7281fa1e5ec5ca1aa10158465a42e6eff8c2dbfd375b16f9ddb26c3027d1b337ca8fd0b41824c94b
+  data.tar.gz: 597d5cd7f32091fcf00a196fa4bd9d7404e5f129db45d0235c70768a01167d47ae9ec361b635b2732add9ba8be45c2bb2fef6db5a4b67e676130dfe7cf9fd13a

data/.github/workflows/rspec.yml

@@ -44,7 +44,7 @@ jobs:
           sudo apt update -y
           sudo apt install -y libsqlite3-dev
 
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1

data/README.md

@@ -3,43 +3,143 @@
 
 # ActiveStorage Validator
 
-ActiveStorage blob validator.
+A Rails gem that makes it easy to add validations such as `content_type` and file size to ActiveStorage attachments.
+
+- Supports both `has_one_attached` and `has_many_attached` of ActiveStorage
+- Flexible validations for content type and file size
 
 ## Installation
 
+### Using Bundler
+
 Add this line to your application's Gemfile:
 
 ```ruby
 gem 'activestorage-validator'
 ```
 
-And then execute:
+Then execute:
 
-    $ bundle
+    $ bundle install
 
-Or install it yourself as:
+### Install with gem command
 
     $ gem install activestorage-validator
 
 ## Usage
 
+You can add validations to models with ActiveStorage attachments using the `blob` validator.
+
 ```ruby
 class User < ApplicationRecord
   has_one_attached :avatar
   has_many_attached :photos
 
-  validates :avatar, presence: true, blob: { content_type: :web_image } # supported options: :web_image, :image, :audio, :video, :text
-  validates :photos, presence: true, blob: { content_type: ['image/png', 'image/jpg', 'image/jpeg'], size_range: 1..(5.megabytes) }
-  # validates :photos, presence: true, blob: { content_type: %r{^image/}, size_range: 1..(5.megabytes) }
+  # Allow only web image files
+  validates :avatar, presence: true, blob: { content_type: :web_image }
+
+  # Allow only JPEG/PNG, up to 5MB per file
+  validates :photos, presence: true, blob: { content_type: ["image/png", "image/jpg", "image/jpeg"], size_range: 1..(5.megabytes) }
+
+  # You can also use a regular expression for content_type
+  # validates :photos, blob: { content_type: %r{^image/}, size_range: 1..(5.megabytes) }
+
+  # Require the filename to have one of the allowed extensions
+  # validates :audio, blob: { content_type: "audio/mpeg", extension: %w[mp3] }
 end
 ```
 
-Note: For `has_many_attached`, size is validated on each file individually. In the code above, `:photos` validation allows any number of photos to be upload, each one being 5 MB or less in size.
+> **Note:** For `has_many_attached`, the size validation is applied to each file individually.
+
+## Validation Options
+
+| Option        | Description                                                                                 |
+|--------------|---------------------------------------------------------------------------------------------|
+| content_type | Allowed MIME types. Accepts a symbol (`:web_image`, `:image`, `:audio`, `:video`, `:text`), an array of MIME types, a regular expression, or a string (single MIME type). |
+| size_range   | Allowed file size range (e.g. `1..5.megabytes`)                                             |
+| extension    | Allowed file extensions. Accepts a String or an Array of Strings. Case-insensitive, leading dot optional. Files without an extension are rejected. |
+
+### content_type Examples
+
+- **Symbol**
+  - `:web_image` ... PNG, JPEG, GIF, WebP (special handling)
+  - `:image`, `:audio`, `:video`, `:text` ... Calls `blob.image?`, `blob.audio?`, etc. (ActiveStorage built-in predicate)
+- **Array**
+  - `["image/png", "image/jpg", "image/jpeg"]` ... Only allow these MIME types
+- **Regexp**
+  - `%r{^image/}` ... Allow any image type (MIME type starts with `image/`)
+- **String**
+  - `"application/pdf"` ... Only allow PDF files
+
+### extension Examples
+
+- **String**
+  - `extension: "mp3"` ... Only allow `.mp3` files
+- **Array**
+  - `extension: %w[mp3 m4a]` ... Allow either `.mp3` or `.m4a`
+- **Combined with content_type (AND)**
+  - `blob: { content_type: "audio/mpeg", extension: %w[mp3] }` ... Reject both `my_podcast` (no extension) and `my_podcast.wav` (wrong extension), even when their MIME types match.
+
+The leading dot is optional (`"mp3"` and `".mp3"` behave the same), and matching is case-insensitive (`PHOTO.JPG` matches `extension: "jpg"`).
+
+## I18n Error Message Options
+
+Validation error messages are I18n compatible. The following interpolation keys are available in your translation files, according to the validator's implementation:
+
+| Key            | Description                                 |
+|----------------|---------------------------------------------|
+| filename       | The uploaded file's name                    |
+| min_size       | The minimum allowed file size (humanized)   |
+| max_size       | The maximum allowed file size (humanized)   |
+| extension      | The list of allowed extensions, joined by `, ` |
+
+The following error types are used:
+
+- `content_type` (invalid content type)
+- `min_size_error` (file is too small)
+- `max_size_error` (file is too large)
+- `extension` (invalid file extension)
+
+Example (config/locales/en.yml):
+
+```yaml
+en:
+  errors:
+    messages:
+      content_type: "%{filename} has an invalid content type"
+      min_size_error: "%{filename} is too small (minimum is %{min_size})"
+      max_size_error: "%{filename} is too large (maximum is %{max_size})"
+      extension: "%{filename} has an invalid file extension (allowed: %{extension})"
+```
+
+## Notes
+
+- Some features may not work depending on your ActiveStorage or Rails version.
+- Validation error messages are I18n compatible and support interpolation keys as described above.
+
+## Agent skill
+
+This repo ships an [agent skill](skills/activestorage-validator/) (`SKILL.md`,
+plus a Japanese `SKILL-ja.md`) that teaches coding agents when and how to apply
+`activestorage-validator`. Install it into your project with the GitHub CLI:
+
+```sh
+gh skill install aki77/activestorage-validator
+```
+
+> `gh skill` is currently a GitHub CLI preview feature.
+
+Alternatively, if your project already pulls `activestorage-validator` in via
+Bundler, the [bundler-skills](https://github.com/aki77/bundler-skills) plugin
+auto-syncs this skill on `bundle install` — keeping the skill version locked to
+the gem version.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/aki77/activestorage-validator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub via [issues](https://github.com/aki77/activestorage-validator/issues) or [pull requests](https://github.com/aki77/activestorage-validator/pulls).
+
+This project adheres to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+This gem is released under the MIT License. See [LICENSE.txt](LICENSE.txt) for details.

data/activestorage-validator.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) || f.match(%r{^skills/.*-ja\.md$}) }
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }

data/config/locales/de.yml

@@ -5,3 +5,4 @@ de:
         content_type: "ist kein gültiges Dateiformat"
         min_size_error: "Dateigröße sollte weniger als %{min_size} betragen"
         max_size_error: "Dateigröße sollte weniger als %{max_size} betragen"
+        extension: "hat eine ungültige Dateierweiterung (erlaubt: %{extension})"

data/config/locales/en.yml

@@ -5,3 +5,4 @@ en:
         content_type: "is not a valid file format"
         min_size_error: "File size should be greater than %{min_size}"
         max_size_error: "File size should be less than %{max_size}"
+        extension: "has an invalid file extension (allowed: %{extension})"

data/config/locales/es.yml

@@ -5,3 +5,4 @@ es:
         content_type: "no es un formato válido"
         min_size_error: "tamaño de archivo debe ser mayor a %{min_size}"
         max_size_error: "tamaño de archivo debe ser menor a %{max_size}"
+        extension: "tiene una extensión de archivo no válida (permitidas: %{extension})"

data/config/locales/fr.yml

@@ -5,3 +5,4 @@ fr:
         content_type: "n'est pas un format de fichier valide"
         min_size_error: "La taille du fichier doit être supérieure à %{min_size}"
         max_size_error: "La taille du fichier doit être inférieure à %{max_size}"
+        extension: "a une extension de fichier non valide (autorisées : %{extension})"

data/config/locales/ja.yml

@@ -5,3 +5,4 @@ ja:
         content_type: "のファイル形式が不正です。"
         min_size_error: "を%{min_size}以上のサイズにしてください。"
         max_size_error: "を%{max_size}以下のサイズにしてください。"
+        extension: "のファイル拡張子が不正です（許可: %{extension}）。"

data/config/locales/pl.yml

@@ -5,3 +5,4 @@ pl:
         content_type: "ma nieprawidłowy format"
         min_size_error: "Rozmiar pliku nie może być większy niż %{min_size}"
         max_size_error: "Rozmiar pliku nie może być mniejszy niż %{max_size}"
+        extension: "ma nieprawidłowe rozszerzenie pliku (dozwolone: %{extension})"

data/config/locales/pt-br.yml

@@ -5,3 +5,4 @@ pt-br:
         content_type: "não é um formato válido"
         min_size_error: "tamanho do arquivo deve ser maior que %{min_size}"
         max_size_error: "tamanho do arquivo deve ser menor que %{max_size}"
+        extension: "tem uma extensão de arquivo inválida (permitidas: %{extension})"

data/lib/activestorage/validator/blob.rb

@@ -16,6 +16,15 @@ module ActiveRecord
           unless valid_content_type?(value.blob)
             record.errors.add(attribute, :content_type, filename: value.blob.filename.to_s)
           end
+
+          unless valid_extension?(value.blob)
+            record.errors.add(
+              attribute,
+              :extension,
+              filename: value.blob.filename.to_s,
+              extension: Array(options[:extension]).map { |e| normalize_extension(e) }.join(', ')
+            )
+          end
         end
       end
 
@@ -37,6 +46,20 @@ module ActiveRecord
             options[:content_type] == blob.content_type
           end
         end
+
+        def valid_extension?(blob)
+          return true if options[:extension].nil?
+
+          allowed = Array(options[:extension]).map { |e| normalize_extension(e) }
+          actual = normalize_extension(blob.filename.extension)
+          return false if actual.empty?
+
+          allowed.include?(actual)
+        end
+
+        def normalize_extension(value)
+          value.to_s.downcase.delete_prefix('.')
+        end
     end
   end
 end

data/lib/activestorage/validator/version.rb

@@ -1,5 +1,5 @@
 module ActiveStorage
   module Validator
-    VERSION = '0.5.0'
+    VERSION = '0.7.0'
   end
 end

data/skills/activestorage-validator/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: activestorage-validator
+description: "Validate ActiveStorage attachments (content type, file size, file extension) with the activestorage-validator gem's `blob` validator. Use when adding validations to has_one_attached / has_many_attached attributes."
+---
+
+# activestorage-validator
+
+A Rails gem that adds a `blob` validator for ActiveStorage attachments. It
+validates content type, file size, and file extension on both
+`has_one_attached` and `has_many_attached` attributes.
+
+## First: determine applicability
+
+Use this gem **only** for validating ActiveStorage attachments. For ordinary
+(non-attachment) attributes, use the standard Rails validators (`presence`,
+`length`, `numericality`, etc.).
+
+| What you validate | Tool |
+| --- | --- |
+| ActiveStorage attachment (content type / size / extension) | **`blob:` validator (this gem)** |
+| Plain string/number/boolean columns | Standard Rails validators |
+| Presence of the attachment itself | `presence: true` (works alongside `blob:`) |
+
+There is no special read path — declare `validates ..., blob: { ... }` and the
+attachment is validated like any other Rails validation on `save`/`valid?`.
+
+## Usage
+
+Declare validations on the model with the `blob:` validator.
+
+```ruby
+class User < ApplicationRecord
+  has_one_attached :avatar
+  has_many_attached :photos
+
+  # Allow only web image files (PNG, JPEG, GIF, WebP)
+  validates :avatar, presence: true, blob: { content_type: :web_image }
+
+  # Allow only JPEG/PNG, up to 5MB per file
+  validates :photos, presence: true, blob: {
+    content_type: ["image/png", "image/jpg", "image/jpeg"],
+    size_range: 1..(5.megabytes)
+  }
+
+  # Regexp content_type + required extension (AND condition)
+  validates :audio, blob: { content_type: "audio/mpeg", extension: %w[mp3] }
+end
+```
+
+> For `has_many_attached`, every option (including `size_range`) is applied to
+> **each file individually**.
+
+## Options (all optional, combine freely)
+
+| Option | Accepts | Notes |
+| --- | --- | --- |
+| `content_type` | Symbol / Array / Regexp / String | Allowed MIME type(s). See matching below. |
+| `size_range` | Range | Allowed byte size, e.g. `1..(5.megabytes)`. |
+| `extension` | String / Array | Allowed filename extension(s). |
+
+### `content_type` matching
+
+- **`:web_image`** — special-cased to `ActiveStorage.web_image_content_types`
+  (PNG, JPEG, GIF, WebP). Use this instead of `:image` when you want only
+  browser-safe images.
+- **Other Symbol** (`:image`, `:audio`, `:video`, `:text`) — calls the
+  ActiveStorage built-in predicate `blob.image?` / `blob.audio?` / etc.
+- **Array** — `["image/png", "image/jpeg"]`: exact membership of the blob's
+  content type in the list.
+- **Regexp** — `%r{^image/}`: matched against the blob's content type.
+- **String** — `"application/pdf"`: exact equality.
+
+### `extension` matching
+
+- Accepts a String (`"mp3"`) or Array (`%w[mp3 m4a]`).
+- Leading dot is optional (`"mp3"` == `".mp3"`).
+- Case-insensitive (`PHOTO.JPG` matches `extension: "jpg"`).
+- **A file with no extension is always rejected** when `extension` is set.
+- When combined with `content_type`, both must pass (AND). E.g.
+  `{ content_type: "audio/mpeg", extension: %w[mp3] }` rejects a `.wav` file
+  even if its MIME type happens to be `audio/mpeg`.
+
+## I18n error messages
+
+Errors are I18n-compatible. Error types and their interpolation keys:
+
+| Error type | Interpolation keys | When |
+| --- | --- | --- |
+| `content_type` | `filename` | content type not allowed |
+| `min_size_error` | `filename`, `min_size` | smaller than `size_range.min` |
+| `max_size_error` | `filename`, `max_size` | larger than `size_range.max` |
+| `extension` | `filename`, `extension` | extension not allowed (or missing) |
+
+`min_size` / `max_size` are humanized (`ActiveSupport::NumberHelper.number_to_human_size`).
+`extension` is the allowed list joined by `, `.
+
+```yaml
+# config/locales/en.yml
+en:
+  errors:
+    messages:
+      content_type: "%{filename} has an invalid content type"
+      min_size_error: "%{filename} is too small (minimum is %{min_size})"
+      max_size_error: "%{filename} is too large (maximum is %{max_size})"
+      extension: "%{filename} has an invalid file extension (allowed: %{extension})"
+```
+
+The gem ships default messages for 7 locales: `en`, `ja`, `de`, `es`, `fr`,
+`pl`, `pt-br`. Override them in your app's locale files using the keys above.
+
+## Behavior details
+
+- **Unattached values are skipped.** Validation returns early unless the
+  attachment is attached, so `blob:` does not enforce presence — add
+  `presence: true` separately if the attachment is required.
+- **Size boundaries are inclusive.** A blob is valid when
+  `size_range.min <= byte_size <= size_range.max`. Below min → `min_size_error`;
+  above max → `max_size_error`.
+- **Extension normalization** is `downcase` + strip a single leading dot; an
+  empty resulting extension (no extension on the file) fails.
+- Options are independent — omit any you don't need; only the present ones run.
+
+## Pitfalls
+
+- A file **without an extension** is rejected whenever `extension:` is set —
+  even if its content type is allowed. Don't set `extension:` if you accept
+  extension-less uploads.
+- For `has_many_attached`, `size_range` applies **per file**, not to the total.
+- `blob:` alone does **not** require an attachment; pair it with `presence: true`
+  when the upload is mandatory.
+- No special read/preload path exists — this is a plain `EachValidator`; it runs
+  on standard `valid?` / `save`.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: activestorage-validator
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - aki
 bindir: exe
 cert_chain: []
-date: 2025-06-15 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -115,6 +115,7 @@ files:
 - lib/activestorage/validator.rb
 - lib/activestorage/validator/blob.rb
 - lib/activestorage/validator/version.rb
+- skills/activestorage-validator/SKILL.md
 homepage: https://github.com/aki77/activestorage-validator
 licenses:
 - MIT
@@ -133,7 +134,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.10
 specification_version: 4
 summary: ActiveStorage blob validator.
 test_files: []