shrine 3.8.0 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55c3fc9bf7eb40700d2be0ee82900986c601b1b3449d5d5ee7b246546bfe5eb3
-  data.tar.gz: 11ffe3b196b79946c931f5a0e9538bda74cc4abd74711124509c76a13a5eaddc
+  metadata.gz: fc3e1cb064bc4b1fc0132c5d97c244506b65014eac06b0e8181cf44b2319bf67
+  data.tar.gz: c289af323f41d3cd70dbe740439c9a08f595bba81150a396639cecd92b8b53af
 SHA512:
-  metadata.gz: 19585a7a2c486d43fb9be2abc84123adced4d18beebf50919938a9c631d16c0c2ecb15e777397b5b8a1642911171d328c55bf86769b9a31a4a3957cf3d8256d9
-  data.tar.gz: 1dfbb667941b5f2bfa1b035230f0b1fb809c59855fc253f8365394624cffd4e3078a0aa41188eb27c8e57be8d4243e45d5dcf56a83b4d9ea1900bf02fa340dc6
+  metadata.gz: 128cb224b8199aba9b4a24a0b911c90bc88e404fc9746b440b3edafe19b28422506edf67f4c01474701a9d9a56d5bc4a874152741239a8ff05bc1fa6449a6fb4
+  data.tar.gz: 2582f06b0c087d56cea3e9056bd0763a8d50613dc86bc2707593a3322da0d4be018a507189ca96b63f70715309d8f469f3bc536fcf4c5b3ab859d54697e9910b

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 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/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`
 

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/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/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.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/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/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 = 9
     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.9.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
@@ -456,6 +498,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
@@ -549,7 +592,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: []