shrine 3.8.0 → 3.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55c3fc9bf7eb40700d2be0ee82900986c601b1b3449d5d5ee7b246546bfe5eb3
-  data.tar.gz: 11ffe3b196b79946c931f5a0e9538bda74cc4abd74711124509c76a13a5eaddc
+  metadata.gz: 5601661d53737bf3290ec5897dc9d33cfe5edac60a7468e67de7191649671a14
+  data.tar.gz: bf2a26e2162a0c1805f2e8d174128e8ee5008060fdbbb9b8e358d41bfdf680a2
 SHA512:
-  metadata.gz: 19585a7a2c486d43fb9be2abc84123adced4d18beebf50919938a9c631d16c0c2ecb15e777397b5b8a1642911171d328c55bf86769b9a31a4a3957cf3d8256d9
-  data.tar.gz: 1dfbb667941b5f2bfa1b035230f0b1fb809c59855fc253f8365394624cffd4e3078a0aa41188eb27c8e57be8d4243e45d5dcf56a83b4d9ea1900bf02fa340dc6
+  metadata.gz: 7eb43ca8a78d4dedec0d24422ca4bc9f62eb6e454aa61ac7871760c4c398973a9787591295c39799f6b3250d4b3af9e80f7082c659fb6ed67435d775846ca5e2
+  data.tar.gz: 636a7343486f6baaa3fa841abcef8439eb0df5d7183d6ac39a756a508de544dd356bca2562a9e01ac76b871a29455d2a40601f8086e8050dcc793bd57fc568e0

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+## 3.10.0 (2026-09-20)
+
+* Add `fallback_storage` plugin for reading files from a secondary storage when they're missing in the primary storage (@yegorov, @janko)
+
+* `data_uri` – Add `:max_size` option for limiting the size of the data URI content, checked before the content is decoded (@jalrax, @janko)
+
+* `data_uri` – Pass the error to the `:error_message` proc as an optional second argument (@jalrax, @janko)
+
+## 3.9.0 (2026-07-13)
+
+* `Shrine.find_storage` now raises `Shrine::MissingStorage` (subclass of `Shrine::Error`) when the storage isn't registered, so it can be rescued separately (@janko)
+
+* `url_options` – Allow regular expression storage keys for compatibility with `dynamic_storage` plugin (@janko)
+
+* `upload_options` – Allow regular expression storage keys for compatibility with `dynamic_storage` plugin (@janko)
+
+* `remove_invalid` – Fix model attribute not being cleared/reverted after deassigning invalid file (@janko)
+
+* `activerecord`/`sequel` – Skip deleting the previous attachment when the record being saved was just created, to avoid deleting the original attachment of a duplicated record (@janko)
+
+* `tempfile` – Allow `UploadedFile#tempfile` to be called without opening the uploaded file first (@janko)
+
+* `activerecord` – Add `:attribute_types` option for skipping serialization of JSON/JSONB attributes declared via the Attributes API, not just database columns (@vojtad, @janko)
+
 ## 3.8.0 (2026-06-24)
 
 * `s3` – Use single-request uploads for smaller files again instead of always using multipart uploads (@janko)

data/doc/advantages.md

@@ -412,7 +412,7 @@ on top of Rack, so that they can be used with any Ruby web framework.
 [Sequel]: http://sequel.jeremyevans.net
 [ROM]: http://rom-rb.org
 [Hanami::Model]: https://github.com/hanami/model
-[plugin system]: https://twin.github.io/the-plugin-system-of-sequel-and-roda/
+[plugin system]: https://janko.io/the-plugin-system-of-sequel-and-roda/
 [Down]: https://github.com/janko/down
 [ContentDisposition]: https://github.com/shrinerb/content_disposition
 [`file`]: http://linux.die.net/man/1/file

data/doc/attacher.md

@@ -189,7 +189,7 @@ attacher.upload(file, location: "path/to/file")           # setting upload locat
 
 ### Changes
 
-When a new file is attached, calling [`Attacher#finalize`](#finalization) will
+When a new file is attached, calling [`Attacher#finalize`](#finalizing) will
 perform additional actions such as promotion and deleting any previous file.
 It will also trigger [validation].
 

data/doc/design.md

@@ -9,8 +9,8 @@ There are five main types of classes that you deal with in Shrine:
 
 | Class | Description |
 | :---- | :---------- |
-| [`Shrine::Storage::*`](#Storage) | Manages files on a particular storage service |
-| [`Shrine`](#Shrine) | Wraps uploads and handles loading plugins |
+| [`Shrine::Storage::*`](#storage) | Manages files on a particular storage service |
+| [`Shrine`](#shrine) | Wraps uploads and handles loading plugins |
 | [`Shrine::UploadedFile`](#shrineuploadedfile) | Represents a file uploaded to a storage |
 | [`Shrine::Attacher`](#shrineattacher) | Handles file attachment logic |
 | [`Shrine::Attachment`](#shrineattachment) | Provides convenience model attachment interface |
@@ -60,7 +60,7 @@ end
 ```
 
 Storages are typically not used directly, but through [`Shrine`](#shrine) and
-[`Shrine::UploadedFile`](#shrine-uploadedfile) classes.
+[`Shrine::UploadedFile`](#shrineuploadedfile) classes.
 
 ## `Shrine`
 
@@ -264,7 +264,7 @@ When a persistence plugin is loaded ([`activerecord`][activerecord],
 [Using Attacher]: https://shrinerb.com/docs/attacher
 [Notes on study of shrine implementation]: https://bibwild.wordpress.com/2018/09/12/notes-on-study-of-shrine-implementation/
 [Creating a New Plugin]: https://shrinerb.com/docs/creating-plugins
-[Plugin system of Sequel and Roda]: https://twin.github.io/the-plugin-system-of-sequel-and-roda/
+[Plugin system of Sequel and Roda]: https://janko.io/the-plugin-system-of-sequel-and-roda/
 [entity]: https://shrinerb.com/docs/plugins/entity
 [model]: https://shrinerb.com/docs/plugins/model
 [activerecord]: https://shrinerb.com/docs/plugins/activerecord

data/doc/plugins/activerecord.md

@@ -80,6 +80,62 @@ Active Record currently has a [bug with transaction callbacks], so if you have
 any "after commit" callbacks, make sure to include Shrine's attachment module
 *after* they have all been defined.
 
+#### Duplicating records
+
+Since a record being created can't yet have a confirmed attachment of its own
+to safely replace, Shrine never deletes the previous file when the attachment
+changes as part of *creating* a record, only when *updating* one. This
+matters most when duplicating a record: `#dup` performs a shallow copy, so a
+duplicated record initially points to the *same* underlying file as the
+original (they'll have the same attached file data), and replacing the
+attachment on the duplicate before it's ever saved won't affect the original:
+
+```rb
+photo  = Photo.create(image: file)
+photo2 = photo.dup
+
+photo2.update!(image: new_file) # replaces the attachment on `photo2`
+photo.image.exists? #=> true (not affected)
+```
+
+Once `photo2` has been saved, replacing its attachment again behaves
+normally (the previously attached file is deleted):
+
+```rb
+previous_image = photo2.image
+photo2.update!(image: another_file)
+previous_image.exists? #=> false
+```
+
+Keep in mind this only protects against *replacing* the attachment on create.
+As long as `photo` and `photo2` continue to reference the same underlying
+file (i.e. `photo2` is saved without ever changing its attachment), destroying
+either record will still delete the file the other one references, since
+Shrine has no way of knowing the file is shared:
+
+```rb
+photo2.save! # still references the same file as `photo`
+
+photo2.destroy
+photo.image.exists? #=> false
+```
+
+If you want the duplicated record to have its own independent copy of the
+file from the start, so that destroying either record is also safe, upload a
+new copy explicitly after duplicating:
+
+```rb
+photo  = Photo.create(image: file)
+photo2 = photo.dup
+
+photo2.image_attacher.set(nil)
+photo2.image_attacher.attach(photo.image, storage: photo.image.storage_key)
+photo2.save!
+
+photo2.destroy # no longer affects `photo`
+photo.image.exists? #=> true
+```
+
 #### Overriding callbacks
 
 You can override any of the following attacher methods to modify callback
@@ -177,6 +233,39 @@ model errors, you can set `:validations` to `false`:
 plugin :activerecord, validations: false
 ```
 
+### JSON columns
+
+When the data attribute is backed by a `json` or `jsonb` database column,
+Active Record already serializes hashes into JSON, so Shrine skips its own
+serialization to avoid double encoding.
+
+```rb
+class Photo < ActiveRecord::Base # `image_data` is a jsonb column
+  include ImageUploader::Attachment(:image)
+end
+```
+```rb
+photo.image = file
+photo.image_data #=> { "id" => "bc2e13.jpg", "storage" => "cache", "metadata" => { ... } }
+```
+
+By default this detection only looks at real database columns. If you declare
+the data attribute type via the [Attributes API] (e.g. on top of a `text`
+column), enable the `:attribute_types` option so it's recognized as well:
+
+```rb
+plugin :activerecord, attribute_types: true
+```
+```rb
+class Photo < ActiveRecord::Base # `image_data` is a text column
+  include ImageUploader::Attachment(:image)
+
+  attribute :image_data, :json
+end
+```
+
+This option defaults to `false` for backwards compatibility.
+
 ## Attacher
 
 You can also use `Shrine::Attacher` directly (with or without the
@@ -217,8 +306,10 @@ See [persistence] docs for more details.
 
 [activerecord]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/activerecord.rb
 [Active Record]: https://guides.rubyonrails.org/active_record_basics.html
+[Attributes API]: https://api.rubyonrails.org/classes/ActiveRecord/Attributes/ClassMethods.html#method-i-attribute
 [model]: https://shrinerb.com/docs/plugins/model
 [callbacks]: https://guides.rubyonrails.org/active_record_callbacks.html
 [bug with transaction callbacks]: https://github.com/rails/rails/issues/14493
 [validation]: https://shrinerb.com/docs/plugins/validation
 [persistence]: https://shrinerb.com/docs/plugins/persistence
+[Replacing]: https://shrinerb.com/docs/attacher#replacing

data/doc/plugins/backgrounding.md

@@ -203,6 +203,32 @@ class MyUploader < Shrine
 end
 ```
 
+## Testing
+
+Since promotion happens in a background job, it won't have run yet
+immediately after you save the record, so asserting on the promoted file's
+data or location will fail unless the job has actually been executed. For
+example, with Active Job you'll need to run enqueued jobs inline:
+
+```rb
+require "active_job/test_helper"
+
+include ActiveJob::TestHelper
+
+perform_enqueued_jobs do
+  photo = Photo.create(image: file) # spawns promote job
+end
+
+photo.reload # fetch attachment data updated by the background job
+photo.image.storage_key #=> :store
+```
+
+Keep in mind that while the file is cached (i.e. before the promote job has
+run), the record may not have an `id` yet, so plugins like [`pretty_location`]
+that build the storage location from the record's identifier won't be able
+to include it until promotion happens.
+
 [backgrounding]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/backgrounding.rb
+[`pretty_location`]: https://shrinerb.com/docs/plugins/pretty_location
 [derivatives]: https://shrinerb.com/docs/plugins/derivatives
 [atomic_helpers]: https://shrinerb.com/docs/plugins/atomic_helpers

data/doc/plugins/data_uri.md

@@ -37,8 +37,23 @@ attachment column. You can change the default error message:
 ```rb
 plugin :data_uri, error_message: "data URI was invalid"
 plugin :data_uri, error_message: ->(uri) { I18n.t("errors.data_uri_invalid") }
+plugin :data_uri, error_message: ->(uri, error) { I18n.t("errors.data_uri.#{error.message}") }
 ```
 
+## Maximum size
+
+It's a good practice to limit the maximum size of the data URI content:
+
+```rb
+plugin :data_uri, max_size: 10*1024*1024 # 10 MB
+```
+
+Now if content bigger than 10MB is assigned, parsing will fail the same way as
+for an invalid data URI. The size is calculated from the data URI before the
+content is decoded, so oversized content never gets loaded into memory. It's
+exact for base64 content, while for percent-encoded content the encoded length
+is used, which can overestimate.
+
 ## Uploader options
 
 Any options passed to `Attacher#assign_data_uri` will be forwarded to

data/doc/plugins/dynamic_storage.md

@@ -22,4 +22,19 @@ the bucket "foo". The block is yielded an instance of `MatchData`.
 
 This can be useful in combination with the `default_storage` plugin.
 
+If the resolver block returns `nil` (e.g. it looks up a record that no longer
+exists), `Shrine.find_storage` raises `Shrine::MissingStorage`, which can be
+rescued separately from other `Shrine::Error` subclasses:
+
+```rb
+storage /store_(\w+)/ do |match|
+  Library.find_by(id: match[1])&.storage
+end
+```
+
+```rb
+attacher.file.storage
+# => raises Shrine::MissingStorage if the Library record was deleted
+```
+
 [dynamic_storage]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/dynamic_storage.rb

data/doc/plugins/fallback_storage.md

@@ -0,0 +1,90 @@
+---
+title: Fallback Storage
+---
+
+The [`fallback_storage`][fallback_storage] plugin allows you to specify a secondary (fallback) storage that
+Shrine will read from if a file is not found in the primary storage.
+
+This is especially useful when setting up a staging or development environment where you want to read files
+from production storage without replicating or copying large amounts of data locally.
+
+```rb
+Shrine.storages = {
+  cache:    Shrine::Storage::S3.new(endpoint: "https://stage.example.com", prefix: "cache"),
+  store:    Shrine::Storage::S3.new(endpoint: "https://stage.example.com"),
+  fallback: Shrine::Storage::S3.new(endpoint: "https://production.example.com"),
+}
+
+Shrine.plugin :fallback_storage
+```
+
+By default, the plugin looks for a storage named `:fallback`. You can override the fallback storage
+name by passing the `:store` option:
+
+```rb
+Shrine.plugin :fallback_storage, store: :production_store
+```
+
+## How It Works
+
+The plugin intercepts file existence checks, URL generation, and file reading methods on
+`Shrine::UploadedFile`.
+
+When performing read or check operations, Shrine will first attempt to query the main storage.
+If the file is missing in the primary storage, it seamlessly falls back to the configured fallback storage:
+
+* `UploadedFile#exists?` — Returns true if the file exists in the primary storage OR in the fallback storage.
+* `UploadedFile#url` — Returns the URL from the primary storage if the file exists there,
+otherwise generates the URL using the fallback storage.
+* `UploadedFile#open` (and methods relying on it like `read`, `download`, etc.) — Opens the file from the
+primary storage if present, otherwise opens it from the fallback storage.
+
+## Write and Delete Operations
+
+The plugin only affects read operations. Uploads, replacements, and deletions interact strictly with
+the primary storage:
+
+* Uploads: `Shrine.upload` writes files only to the main storage.
+* Deletes: `UploadedFile#delete` removes the file only from the primary storage. The fallback storage remains
+untouched.
+
+```ruby
+# File exists only in fallback storage
+file = Shrine.uploaded_file({ "id" => "some-id", "storage" => "store" })
+file.exists? # => true (found in fallback)
+
+# Deleting removes it from primary storage, but fallback remains intact
+file.delete
+file.exists? # => true (still found in fallback)
+```
+
+For additional security and reliability when pointing to a production environment, it is recommended
+to configure the credentials for the fallback storage (e.g., S3 access keys) with read-only permissions.
+
+## Rails example
+
+A common use case is a staging environment that should have access to production files without storing
+its own copies. You can configure Shrine differently per environment:
+
+```rb
+# config/initializers/shrine.rb
+if Rails.env.production?
+  Shrine.storages = {
+    cache: Shrine::Storage::S3.new(endpoint: "https://production.example.com", prefix: "cache"),
+    store: Shrine::Storage::S3.new(endpoint: "https://production.example.com"),
+  }
+else
+  Shrine.storages = {
+    cache: Shrine::Storage::S3.new(endpoint: "https://stage.example.com", prefix: "cache"),
+    store: Shrine::Storage::S3.new(endpoint: "https://stage.example.com"),
+    production: Shrine::Storage::S3.new(endpoint: "https://production.example.com"),
+  }
+
+  Shrine.plugin :fallback_storage, store: :production
+end
+```
+
+With this setup, staging uploads go to the staging endpoint, but any read for a missing file
+will automatically look in the production endpoint.
+
+[fallback_storage]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/fallback_storage.rb

data/doc/plugins/sequel.md

@@ -100,6 +100,63 @@ set `:hooks` to `false`:
 plugin :sequel, hooks: false
 ```
 
+#### Duplicating records
+
+Since a record being created can't yet have a confirmed attachment of its own
+to safely replace, Shrine never deletes the previous file when the attachment
+changes as part of *creating* a record, only when *updating* one.
+
+Note that Sequel's `#dup`/`#clone`, unlike Active Record's, don't reset the
+primary key or persistence state — a duplicated record still refers to the
+*same* row, so saving it just updates that row rather than inserting a new
+one. There's only ever one row here, so there's nothing to protect:
+
+```rb
+photo  = Photo.create(image: file)
+photo2 = photo.dup # `photo2` refers to the same row as `photo`
+
+photo2.update(image: new_file)
+photo.image.exists? #=> false (the row now has `new_file`, so this is expected)
+```
+
+The common way to duplicate a record in Sequel is instead to construct a new
+one from the original's values, which *does* produce a genuinely new,
+unpersisted row, and so *is* protected:
+
+```rb
+photo2 = Photo.new(photo.values.except(:id))
+
+photo2.update(image: new_file)
+photo.image.exists? #=> true (not affected)
+```
+
+Keep in mind this only protects against *replacing* the attachment on create.
+As long as `photo` and `photo2` continue to reference the same underlying
+file (i.e. `photo2` is saved without ever changing its attachment),
+destroying either record will still delete the file the other one
+references, since Shrine has no way of knowing the file is shared:
+
+```rb
+photo2.save # still references the same file as `photo`
+
+photo2.destroy
+photo.image.exists? #=> false
+```
+
+If you want `photo2` to have its own independent copy of the file from the
+start, so that destroying either record is also safe, upload a new copy
+explicitly:
+
+```rb
+photo2 = Photo.new(photo.values.reject { |k, _| k == :id })
+photo2.image_attacher.set(nil)
+photo2.image_attacher.attach(photo.image, storage: photo.image.storage_key)
+photo2.save
+
+photo2.destroy # no longer affects `photo`
+photo.image.exists? #=> true
+```
+
 ### Validations
 
 If you're using the [`validation`][validation] plugin, the attachment module

data/doc/plugins/tempfile.md

@@ -9,14 +9,22 @@ uploaded file on disk.
 Shrine.plugin :tempfile
 ```
 
-The plugin provides the `UploadedFile#tempfile` method, which when called on an
-open uploaded file will return a copy of its content on disk. The first time
-the method is called the file content will cached into a temporary file and
-returned. On any subsequent method calls the cached temporary file will be
-returned directly. The temporary file is deleted when the uploaded file is
-closed.
+The plugin provides the `UploadedFile#tempfile` method, which returns a copy
+of the uploaded file's content on disk. The first time the method is called
+the file content will be downloaded into a temporary file and returned. On
+any subsequent method calls the cached temporary file will be returned
+directly. If the uploaded file is currently open, its tempfile is deleted
+when the uploaded file is closed; otherwise it's deleted whenever it becomes
+unreachable and is garbage collected (so it's still recommended to close the
+uploaded file when you're done with it, to have the tempfile cleaned up
+deterministically).
 
 ```rb
+uploaded_file.tempfile #=> #<Tempfile:...> (file is downloaded and cached)
+uploaded_file.tempfile #=> #<Tempfile:...> (cache is returned)
+
+# OR
+
 uploaded_file.open do
   # ...
   uploaded_file.tempfile #=> #<Tempfile:...> (file is cached)

data/doc/plugins/upload_options.md

@@ -29,4 +29,16 @@ the uploader.
 uploader.upload(file, upload_options: { acl: "public-read" })
 ```
 
+If storage keys are generated dynamically (e.g. via the
+[`dynamic_storage`][dynamic_storage] plugin), it's not possible to list every
+storage key upfront. In that case you can use a `Regexp` instead, which will
+be matched against the storage key:
+
+```rb
+plugin :upload_options, /_store\z/ => { acl: "private" }
+```
+
+An exact storage key match always takes precedence over a `Regexp` match.
+
 [upload_options]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/upload_options.rb
+[dynamic_storage]: https://shrinerb.com/docs/plugins/dynamic_storage

data/doc/plugins/url_options.md

@@ -24,4 +24,16 @@ In both cases the default options are merged with options passed to
 `UploadedFile#url`, and the latter will always have precedence over default
 options.
 
+If storage keys are generated dynamically (e.g. via the
+[`dynamic_storage`][dynamic_storage] plugin), it's not possible to list every
+storage key upfront. In that case you can use a `Regexp` instead, which will
+be matched against the storage key:
+
+```rb
+plugin :url_options, /_store\z/ => { expires_in: 24*60*60 }
+```
+
+An exact storage key match always takes precedence over a `Regexp` match.
+
 [url_options]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/url_options.rb
+[dynamic_storage]: https://shrinerb.com/docs/plugins/dynamic_storage

data/doc/release_notes/3.10.0.md

@@ -0,0 +1,30 @@
+---
+title: Shrine 3.10.0
+---
+
+## New features
+
+* The new `fallback_storage` plugin makes Shrine read from a secondary (fallback) storage when a file is missing in the primary storage. This is useful for staging or development environments that should read files from production without copying them. `UploadedFile#exists?`, `#url` and `#open` (and methods relying on it) fall back to the secondary storage, while uploads and deletes only affect the primary storage.
+
+  ```rb
+  Shrine.storages = {
+    cache:    Shrine::Storage::S3.new(endpoint: "https://stage.example.com", prefix: "cache"),
+    store:    Shrine::Storage::S3.new(endpoint: "https://stage.example.com"),
+    fallback: Shrine::Storage::S3.new(endpoint: "https://production.example.com"),
+  }
+
+  Shrine.plugin :fallback_storage # looks for the `:fallback` storage by default
+  Shrine.plugin :fallback_storage, store: :production_store # custom storage name
+  ```
+
+* The `data_uri` plugin now accepts a `:max_size` option for limiting the size of the data URI content. The size is calculated from the data URI before the content is decoded, so oversized content never gets loaded into memory. It's exact for base64 content, while for percent-encoded content the encoded length is used, which can overestimate. Content over the limit fails parsing the same way as an invalid data URI.
+
+  ```rb
+  plugin :data_uri, max_size: 10*1024*1024 # 10 MB
+  ```
+
+* The `data_uri` plugin's `:error_message` proc can now optionally accept the error as a second argument, so the size limit can have its own message.
+
+  ```rb
+  plugin :data_uri, error_message: ->(uri, error) { I18n.t("errors.data_uri.#{error.message}") }
+  ```

data/doc/release_notes/3.9.0.md

@@ -0,0 +1,42 @@
+---
+title: Shrine 3.9.0
+---
+
+## New features
+
+* `Shrine.find_storage` now raises `Shrine::MissingStorage` (a subclass of `Shrine::Error`) when the storage isn't registered, instead of a generic `Shrine::Error`. This is useful with the `dynamic_storage` plugin, where the resolver might fail to find its dependencies (e.g. a deleted DB record), and lets you rescue that case separately from other errors.
+
+  ```rb
+  begin
+    Shrine.find_storage(:store)
+  rescue Shrine::MissingStorage
+    # handle missing storage specifically
+  end
+  ```
+
+* The `url_options` and `upload_options` plugins now accept a `Regexp` in place of a storage key. This is useful when storage keys are generated dynamically (e.g. via the `dynamic_storage` plugin), since it's not possible to list every storage key upfront. An exact storage key match always takes precedence over a `Regexp` match.
+
+  ```rb
+  plugin :url_options, /_store\z/ => { expires_in: 24*60*60 }
+  plugin :upload_options, /_store\z/ => { acl: "private" }
+  ```
+
+* The `activerecord` plugin now accepts an `:attribute_types` option. When enabled, it uses `type_for_attribute` (instead of just `columns_hash`) to detect whether the data attribute is JSON/JSONB, so Shrine also skips its own serialization for attributes declared via the Active Record Attributes API (not just real database columns). It defaults to `false` for backwards compatibility with apps that might be relying on the previous double-serialization behavior.
+
+  ```rb
+  class Photo < ActiveRecord::Base # `image_data` is a text column
+    include ImageUploader::Attachment(:image)
+
+    attribute :image_data, :json
+  end
+
+  plugin :activerecord, attribute_types: true
+  ```
+
+## Bug fixes
+
+* The `activerecord` and `sequel` plugins no longer delete the previous attachment when the record being saved was just created. Previously, duplicating a persisted record (e.g. via `#dup`) and immediately assigning a new attachment before saving the duplicate could end up deleting the *original* record's attachment, since both records shared the same underlying file.
+
+* The `remove_invalid` plugin now correctly clears/reverts the model attribute after an invalid file is deassigned. Previously the record's raw attribute could be left out of sync with the attacher after validation failed.
+
+* `UploadedFile#tempfile` (from the `tempfile` plugin) can now be called without opening the uploaded file first. Previously it raised `Shrine::Error` unless the file was already open; now it downloads and caches the file on demand. If the uploaded file is open, its tempfile is still cleaned up when the file is closed; otherwise it's cleaned up whenever it becomes unreachable and is garbage collected, so it's still recommended to close the uploaded file when you're done with it for deterministic cleanup.

data/lib/shrine/attacher.rb

@@ -20,7 +20,7 @@ class Shrine
 
       # Initializes the attacher from a data hash generated from `Attacher#data`.
       #
-      #     attacher = Attacher.from_data({ "id" => "...", "storage" => "...", "metadata" => { ... } })
+      #     attacher = Attacher.from_data({ "id" => "...", "storage" => "...", "metadata" => {} })
       #     attacher.file #=> #<Shrine::UploadedFile>
       def from_data(data, **)
         attacher = new(**)
@@ -60,8 +60,8 @@ class Shrine
       # useful when the uploaded file comes from form fields). Forwards any
       # additional options to #attach_cached.
       #
-      #     attacher.assign(File.open(...))
-      #     attacher.assign(File.open(...), metadata: { "foo" => "bar" })
+      #     attacher.assign(File.open(path))
+      #     attacher.assign(File.open(path), metadata: { "foo" => "bar" })
       #     attacher.assign('{"id":"...","storage":"cache","metadata":{...}}')
       #     attacher.assign({ "id" => "...", "storage" => "cache", "metadata" => {} })
       #
@@ -82,10 +82,10 @@ class Shrine
       # #attach.
       #
       #     # upload file to temporary storage and set the uploaded file.
-      #     attacher.attach_cached(File.open(...))
+      #     attacher.attach_cached(File.open(path))
       #
       #     # foward additional options to the uploader
-      #     attacher.attach_cached(File.open(...), metadata: { "foo" => "bar" })
+      #     attacher.attach_cached(File.open(path), metadata: { "foo" => "bar" })
       #
       #     # sets an existing cached file from JSON data
       #     attacher.attach_cached('{"id":"...","storage":"cache","metadata":{...}}')
@@ -189,7 +189,7 @@ class Shrine
       #     attacher.destroy_previous
       #     previous_file.exists? #=> false
       def destroy_previous
-        @previous.destroy_attached if changed?
+        @previous.destroy_attached if changed? && destroy_previous?
       end
 
       # Destroys the attached file if it exists and is uploaded to permanent
@@ -299,7 +299,7 @@ class Shrine
       # Loads the uploaded file from data generated by `Attacher#data`.
       #
       #     attacher.file #=> nil
-      #     attacher.load_data({ "id" => "...", "storage" => "...", "metadata" => { ... } })
+      #     attacher.load_data({ "id" => "...", "storage" => "...", "metadata" => {} })
       #     attacher.file #=> #<Shrine::UploadedFile>
       def load_data(data)
         @file = data && uploaded_file(data)
@@ -356,7 +356,7 @@ class Shrine
       #     #=> #<Shrine::UploadedFile>
       #
       #     # from Hash data
-      #     attacher.cached({ "id" => "...", "storage" => "cache", "metadata" => { ... } })
+      #     attacher.cached({ "id" => "...", "storage" => "cache", "metadata" => {} })
       #     #=> #<Shrine::UploadedFile>
       def cached(value, **)
         uploaded_file = uploaded_file(value)
@@ -380,6 +380,11 @@ class Shrine
         attached? && !cached?
       end
 
+      # Whether the previous attached file should be deleted.
+      def destroy_previous?
+        true
+      end
+
       # Whether assigning the given file is considered a change.
       def change?(file)
         @file != file

data/lib/shrine/plugins/activerecord.rb

@@ -12,7 +12,7 @@ class Shrine
       end
 
       def self.configure(uploader, **opts)
-        uploader.opts[:activerecord] ||= { callbacks: true, validations: true }
+        uploader.opts[:activerecord] ||= { callbacks: true, validations: true, attribute_types: false }
         uploader.opts[:activerecord].merge!(opts)
       end
 
@@ -108,12 +108,22 @@ class Shrine
           record.transaction { yield record.clone.reload(lock: true) }
         end
 
-        # Returns true if the data attribute represents a JSON or JSONB column.
+        # Returns true if the data attribute represents a JSON or JSONB type.
         # Used by the _persistence plugin to determine whether serialization
         # should be skipped.
+        #
+        # By default only real database columns are checked. When the
+        # `:attribute_types` plugin option is enabled, the check uses
+        # `type_for_attribute`, so attributes declared via the Attributes API
+        # are recognized as well.
         def activerecord_hash_attribute?
-          column = record.class.columns_hash[attribute.to_s]
-          column && [:json, :jsonb].include?(column.type)
+          if shrine_class.opts[:activerecord][:attribute_types]
+            attribute_type = record.class.type_for_attribute(attribute.to_s)
+            attribute_type && [:json, :jsonb].include?(attribute_type.type)
+          else
+            column = record.class.columns_hash[attribute.to_s]
+            column && [:json, :jsonb].include?(column.type)
+          end
         end
 
         # Returns whether the record is an ActiveRecord model. Used by the
@@ -121,6 +131,17 @@ class Shrine
         def activerecord?
           record.is_a?(::ActiveRecord::Base)
         end
+
+        # Prevents the previous file from being destroyed when this save
+        # created the record (as opposed to updating an existing one), since
+        # a record being created can't yet have its own confirmed attachment
+        # to safely replace (e.g. when it was duplicated via `#dup` from
+        # another, still-persisted record).
+        def destroy_previous?
+          return super unless activerecord?
+
+          super && !record.previously_new_record?
+        end
       end
     end
 

data/lib/shrine/plugins/backgrounding.rb

@@ -47,7 +47,7 @@ class Shrine
         #     attacher.promote_block do |attacher|
         #       Attachment::PromoteJob.perform_async(
         #         attacher.record,
-        #         attacher.name
+        #         attacher.name,
         #         attacher.file_data,
         #       )
         #     end

data/lib/shrine/plugins/column.rb

@@ -54,7 +54,7 @@ class Shrine
         # Converts the column data hash into a string (generates JSON by
         # default).
         #
-        #     Attacher.serialize_column({ "id" => "...", "storage" => "...", "metadata" => { ... } })
+        #     Attacher.serialize_column({ "id" => "...", "storage" => "...", "metadata" => {} })
         #     #=> '{"id":"...","storage":"...","metadata":{...}}'
         #
         #     Attacher.serialize_column(nil)

data/lib/shrine/plugins/data_uri.rb

@@ -17,6 +17,7 @@ class Shrine
       BASE64_REGEXP        = /;base64/
       CONTENT_SEPARATOR    = /,/
       DEFAULT_CONTENT_TYPE = "text/plain"
+      BASE64_ALPHABET      = "A-Za-z0-9+/"
 
       LOG_SUBSCRIBER = -> (event) do
         Shrine.logger.info "Data URI (#{event.duration}ms) – #{{
@@ -78,13 +79,37 @@ class Shrine
           data_file
         end
 
-        # Parses the data URI string and returns parts.
+        # Raises `ParseError` if the content exceeds the `:max_size` option.
+        def verify_data_size!(uri, offset, base64)
+          max_size = opts[:data_uri][:max_size]
+          return unless max_size
+
+          size = data_size(uri, offset, base64)
+
+          raise ParseError, "data URI is too large" if size > max_size
+        end
+
+        # Returns the size the content will have once decoded. It's exact for
+        # base64 and an upper bound for percent-encoded content.
+        def data_size(uri, offset, base64)
+          return uri.bytesize - offset unless base64
+
+          header_characters  = uri.byteslice(0, offset).count(BASE64_ALPHABET)
+          content_characters = uri.count(BASE64_ALPHABET) - header_characters
+
+          content_characters * 3 / 4 # 4 characters decode into 3 bytes
+        end
+
+        # Parses the data URI string, verifies content size, and returns parts.
         def parse_data_uri(uri)
           scanner = StringScanner.new(uri)
           scanner.scan(DATA_REGEXP) or raise ParseError, "data URI has invalid format"
           media_type = scanner.scan(MEDIA_TYPE_REGEXP)
           base64 = scanner.scan(BASE64_REGEXP)
           scanner.scan(CONTENT_SEPARATOR) or raise ParseError, "data URI has invalid format"
+
+          verify_data_size!(scanner.string, scanner.pos, base64)
+
           content = scanner.post_match
 
           { content_type: media_type, base64: !!base64, data: content }
@@ -129,7 +154,7 @@ class Shrine
         # Generates an error message for failed data URI parse.
         def data_uri_error_messsage(uri, error)
           message = shrine_class.opts[:data_uri][:error_message]
-          message = message.call(uri) if message.respond_to?(:call)
+          message = message.call(*[uri, error].take(message.arity.abs)) if message.respond_to?(:call)
           message || error.message
         end
       end

data/lib/shrine/plugins/derivatives.rb

@@ -431,12 +431,12 @@ class Shrine
         #     attacher.load_data({
         #       "id" => "...",
         #       "storage" => "store",
-        #       "metadata" => { ... },
+        #       "metadata" => {},
         #       "derivatives" => {
         #         "thumb" => {
         #           "id" => "...",
         #           "storage" => "store",
-        #           "metadata" => { ... },
+        #           "metadata" => {},
         #         }
         #       }
         #     })
@@ -471,7 +471,7 @@ class Shrine
 
         # Sets a hash of derivatives.
         #
-        #     attacher.derivatives = { thumb: Shrine.uploaded_file(...) }
+        #     attacher.derivatives = { thumb: Shrine.uploaded_file(data) }
         #     attacher.derivatives #=> { thumb: #<Shrine::UploadedFile ...> }
         def derivatives=(derivatives)
           unless derivatives.is_a?(Hash)
@@ -483,7 +483,9 @@ class Shrine
 
         # Iterates through nested derivatives and maps results.
         #
-        #     attacher.map_derivative(derivatives) { |path, file| ... }
+        #     attacher.map_derivative(derivatives) do |path, file|
+        #       # ...
+        #     end
         def map_derivative(derivatives, **options, &block)
           shrine_class.map_derivative(derivatives, **options, &block)
         end

data/lib/shrine/plugins/fallback_storage.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+class Shrine
+  module Plugins
+    # Documentation can be found on https://shrinerb.com/docs/plugins/fallback_storage
+    module FallbackStorage
+      def self.configure(uploader, **opts)
+        uploader.opts[:fallback_storage] ||= { store: :fallback }
+        uploader.opts[:fallback_storage].merge!(opts)
+
+        uploader.find_storage(uploader.opts.dig(:fallback_storage, :store))
+      end
+
+      module FileMethods
+        def self.included(base)
+          base.class_eval do
+            alias_method :storage_exists?, :exists?
+
+            def exists?
+              super || fallback_storage.exists?(id)
+            end
+          end
+        end
+
+        def url(**)
+          if storage_exists?
+            super
+          else
+            fallback_storage.url(id, **)
+          end
+        end
+
+        private
+
+        def _open(**)
+          if storage_exists?
+            super
+          else
+            fallback_storage.open(id, **)
+          end
+        end
+
+        def fallback_storage
+          shrine_class.find_storage(shrine_class.opts.dig(:fallback_storage, :store))
+        end
+      end
+    end
+
+    register_plugin(:fallback_storage, FallbackStorage)
+  end
+end

data/lib/shrine/plugins/remove_invalid.rb

@@ -26,6 +26,10 @@ class Shrine
           else
             load_data nil
           end
+
+          # `load_data` bypasses `Attacher#set`, so when the model plugin is
+          # loaded the record attribute needs to be synced manually.
+          write if respond_to?(:write)
         end
       end
     end

data/lib/shrine/plugins/sequel.rb

@@ -87,8 +87,11 @@ class Shrine
           end
         end
 
-        # Calls Attacher#save. Called before model save.
+        # Calls Attacher#save. Called before model save. Remembers whether
+        # the record is new, since by the time `#sequel_after_save` runs,
+        # Sequel has already flipped `#new?` to false.
         def sequel_before_save
+          @previously_new_record = record.new?
           save
         end
 
@@ -132,6 +135,17 @@ class Shrine
         def sequel?
           record.is_a?(::Sequel::Model)
         end
+
+        # Prevents the previous file from being destroyed when this save
+        # created the record (as opposed to updating an existing one), since
+        # a record being created can't yet have its own confirmed attachment
+        # to safely replace (e.g. when it was duplicated from another,
+        # still-persisted record).
+        def destroy_previous?
+          return super unless sequel?
+
+          super && !@previously_new_record
+        end
       end
     end
 

data/lib/shrine/plugins/tempfile.rb

@@ -19,8 +19,6 @@ class Shrine
 
       module FileMethods
         def tempfile
-          raise Error, "uploaded file must be opened" unless @io
-
           @tempfile ||= download
           @tempfile.rewind
           @tempfile

data/lib/shrine/plugins/upload_options.rb

@@ -4,9 +4,9 @@ class Shrine
   module Plugins
     # Documentation can be found on https://shrinerb.com/docs/plugins/upload_options
     module UploadOptions
-      def self.configure(uploader, **opts)
+      def self.configure(uploader, options = {})
         uploader.opts[:upload_options] ||= {}
-        uploader.opts[:upload_options].merge!(opts)
+        uploader.opts[:upload_options].merge!(options)
       end
 
       module InstanceMethods
@@ -19,11 +19,25 @@ class Shrine
         end
 
         def get_upload_options(io, options)
-          upload_options = opts[:upload_options][storage_key] || {}
+          upload_options = find_upload_options || {}
           upload_options = upload_options.call(io, options) if upload_options.respond_to?(:call)
           upload_options = upload_options.merge(options[:upload_options]) if options[:upload_options]
           upload_options
         end
+
+        # Matches the storage key exactly first, then falls back to any
+        # registered regex that matches the storage key. The regex form is
+        # useful when storage keys are generated dynamically (e.g. via the
+        # `dynamic_storage` plugin), since it's not possible to list every
+        # storage key upfront.
+        def find_upload_options
+          upload_options = opts[:upload_options]
+
+          return upload_options[storage_key] if upload_options.key?(storage_key)
+
+          _, options = upload_options.find { |key, _| key.is_a?(Regexp) && key.match?(storage_key.to_s) }
+          options
+        end
       end
     end
 

data/lib/shrine/plugins/url_options.rb

@@ -4,9 +4,9 @@ class Shrine
   module Plugins
     # Documentation can be found on https://shrinerb.com/docs/plugins/url_options
     module UrlOptions
-      def self.configure(uploader, **opts)
+      def self.configure(uploader, options = {})
         uploader.opts[:url_options] ||= {}
-        uploader.opts[:url_options].merge!(opts)
+        uploader.opts[:url_options].merge!(options)
       end
 
       module FileMethods
@@ -19,10 +19,24 @@ class Shrine
         private
 
         def url_options(options)
-          default_options = shrine_class.opts[:url_options][storage_key]
+          default_options = find_url_options
           default_options = default_options.call(self, options) if default_options.respond_to?(:call)
           default_options || {}
         end
+
+        # Matches the storage key exactly first, then falls back to any
+        # registered regex that matches the storage key. The regex form is
+        # useful when storage keys are generated dynamically (e.g. via the
+        # `dynamic_storage` plugin), since it's not possible to list every
+        # storage key upfront.
+        def find_url_options
+          url_options = shrine_class.opts[:url_options]
+
+          return url_options[storage_key] if url_options.key?(storage_key)
+
+          _, options = url_options.find { |key, _| key.is_a?(Regexp) && key.match?(storage_key.to_s) }
+          options
+        end
       end
     end
 

data/lib/shrine/version.rb

@@ -7,7 +7,7 @@ class Shrine
 
   module VERSION
     MAJOR = 3
-    MINOR = 8
+    MINOR = 10
     TINY  = 0
     PRE   = nil
 

data/lib/shrine.rb

@@ -28,6 +28,10 @@ class Shrine
   class FileNotFound < Error
   end
 
+  # Raised by Shrine.find_storage when the storage isn't registered.
+  class MissingStorage < Error
+  end
+
   @opts = {}
   @storages = {}
   @logger = Logger.new(STDOUT)
@@ -86,7 +90,7 @@ class Shrine
     # Retrieves the storage under the given identifier (can be a Symbol or
     # a String), raising Shrine::Error if the storage is missing.
     def find_storage(name)
-      storages[name.to_sym] || storages[name.to_s] or fail Error, "storage #{name.inspect} isn't registered on #{self}"
+      storages[name.to_sym] || storages[name.to_s] or fail MissingStorage, "storage #{name.inspect} isn't registered on #{self}"
     end
 
     # Generates an instance of Shrine::Attachment to be included in the

data/shrine.gemspec

@@ -36,6 +36,8 @@ direct uploads for fully asynchronous user experience.
   gem.add_dependency "down", "~> 5.1"
   gem.add_dependency "content_disposition", "~> 1.0"
 
+  gem.add_development_dependency "rdoc", "~> 8.0" unless RUBY_ENGINE == "jruby"
+
   # general testing helpers
   gem.add_development_dependency "rake", ">= 11.1"
   gem.add_development_dependency "minitest", "~> 6.0"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shrine
 version: !ruby/object:Gem::Version
-  version: 3.8.0
+  version: 3.10.0
 platform: ruby
 authors:
 - Janko Marohnić
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -155,6 +169,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby-filemagic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: mime-types
   requirement: !ruby/object:Gem::Requirement
@@ -287,14 +315,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 8.0.0
+        version: '8.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 8.0.0
+        version: '8.1'
 - !ruby/object:Gem::Dependency
   name: sequel
   requirement: !ruby/object:Gem::Requirement
@@ -315,14 +343,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 8.0.0
+        version: '8.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 8.0.0
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
 description: |
   Shrine is a toolkit for file attachments in Ruby applications. It supports
   uploading, downloading, processing and deleting IO objects, backed by various
@@ -375,6 +417,7 @@ files:
 - doc/plugins/download_endpoint.md
 - doc/plugins/dynamic_storage.md
 - doc/plugins/entity.md
+- doc/plugins/fallback_storage.md
 - doc/plugins/form_assign.md
 - doc/plugins/included.md
 - doc/plugins/infer_extension.md
@@ -446,6 +489,7 @@ files:
 - doc/release_notes/3.0.0.md
 - doc/release_notes/3.0.1.md
 - doc/release_notes/3.1.0.md
+- doc/release_notes/3.10.0.md
 - doc/release_notes/3.2.0.md
 - doc/release_notes/3.2.1.md
 - doc/release_notes/3.2.2.md
@@ -456,6 +500,7 @@ files:
 - doc/release_notes/3.7.0.md
 - doc/release_notes/3.7.1.md
 - doc/release_notes/3.8.0.md
+- doc/release_notes/3.9.0.md
 - doc/retrieving_uploads.md
 - doc/securing_uploads.md
 - doc/storage/file_system.md
@@ -487,6 +532,7 @@ files:
 - lib/shrine/plugins/download_endpoint.rb
 - lib/shrine/plugins/dynamic_storage.rb
 - lib/shrine/plugins/entity.rb
+- lib/shrine/plugins/fallback_storage.rb
 - lib/shrine/plugins/form_assign.rb
 - lib/shrine/plugins/included.rb
 - lib/shrine/plugins/infer_extension.rb
@@ -549,7 +595,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.13
 specification_version: 4
 summary: Toolkit for file attachments in Ruby applications
 test_files: []