shrine 3.7.1 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29a02d25cd1180c4f0170434edd185b3b1ab0bd2be060fa53e58fcd32c50d4ae
-  data.tar.gz: 56e50d961ef88e0d3cae4d295b6996c52cd2021b923d9b453f401f10b04021b3
+  metadata.gz: fc3e1cb064bc4b1fc0132c5d97c244506b65014eac06b0e8181cf44b2319bf67
+  data.tar.gz: c289af323f41d3cd70dbe740439c9a08f595bba81150a396639cecd92b8b53af
 SHA512:
-  metadata.gz: cb06f261af63f09ba767556d65f8b99e5204c1162ce7d8e28e5355148539a02c486fa088819884cf38dee4bf0683e8167b6582c4a028271a5145bd8661f64765
-  data.tar.gz: ec5cd4f04fe90ada87cd594bf78e61c2de9fcbebe8d51cb9e49b0bec566614be5ea5826382a8f25608888c84a951f25ad80442a6af2d641a37bae0e8fe184d7e
+  metadata.gz: 128cb224b8199aba9b4a24a0b911c90bc88e404fc9746b440b3edafe19b28422506edf67f4c01474701a9d9a56d5bc4a874152741239a8ff05bc1fa6449a6fb4
+  data.tar.gz: 2582f06b0c087d56cea3e9056bd0763a8d50613dc86bc2707593a3322da0d4be018a507189ca96b63f70715309d8f469f3bc536fcf4c5b3ab859d54697e9910b

data/CHANGELOG.md

@@ -1,6 +1,34 @@
+## 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)
+
+* `derivatives` – Forward `Attacher#promote` options to `Attacher#upload_derivatives` (@milkcocoa)
+
+* `file_system` – Prevent path traversal outside of the storage directory (@janko)
+
 ## 3.7.1 (2026-06-03)
 
-* Update method signatures of some plugins to work around a Bootsnap bug causing a `wrong number of arguments` error.
+* Update method signatures of some plugins to work around a Bootsnap bug causing a `wrong number of arguments` error (@janko)
+
+* `derivation_endpoint` – Add `:format` argument to `UploadedFile#derivation_url` for path extension (@janko)
+
+* `rack_response` – Add `:etag` argument for setting a custom `ETag` (@camilohollanda)
 
 ## 3.7.0 (2026-05-27)
 

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.7.1.md

@@ -2,6 +2,24 @@
 title: Shrine 3.7.1
 ---
 
+## New features
+
+* The `derivation_endpoint` plugin now supports adding a file extension to the derivation URL path via the `:format` option on `UploadedFile#derivation_url`. Some HTTP clients and CDNs use the URL path extension to determine the content type of the response.
+
+  ```rb
+  uploaded_file.derivation_url(:thumbnail, format: "jpg")
+  #=> ".../thumbnail/eyJpZCI6ImZvbyIsInN.jpg?signature=..."
+  ```
+
+  The extension is included in the URL signature, so it cannot be tampered with.
+
+* The `rack_response` plugin now accepts an `:etag` option for setting a custom `ETag` header, overriding the default one Shrine generates.
+
+  ```rb
+  response = uploaded_file.to_rack_response(etag: "my-custom-etag")
+  response[1]["ETag"] #=> "my-custom-etag"
+  ```
+
 ## Bug fixes
 
 * When initializing Shrine with the `activerecord` plugin, under Bootsnap 1.24.5 and Ruby 3.4.5 this would raise an error:

data/doc/release_notes/3.8.0.md

@@ -0,0 +1,37 @@
+---
+title: Shrine 3.8.0
+---
+
+## Security
+
+* The `file_system` storage now prevents path traversal outside of the storage
+  directory. Previously, an id containing `../` sequences (e.g. coming from
+  attacker-controlled data) could resolve to a location outside of the
+  configured storage directory. Now `Shrine::Error` is raised whenever an id
+  would resolve outside of the storage directory:
+
+  ```rb
+  storage = Shrine::Storage::FileSystem.new("uploads")
+  storage.open("../../etc/passwd") #~> Shrine::Error
+  ```
+
+## New features
+
+* The `derivatives` plugin now forwards options passed to `Attacher#promote`
+  into `Attacher#upload_derivatives`. This means options such as upload options
+  reach the derivatives upload as well, not just the main file.
+
+  ```rb
+  attacher.promote(upload_options: { acl: "public-read" })
+  # the same options are now forwarded when uploading derivatives
+  ```
+
+## Other improvements
+
+* The `s3` storage again uses single-request uploads for smaller files, instead
+  of always using multipart uploads. In Shrine 3.7.0, when a `TransferManager`
+  was available, it was used for uploads of any size, but `TransferManager`
+  uploads via multipart unconditionally, which is inefficient for smaller files.
+  Now files at or below the multipart threshold (`:upload`, 15MB by default) are
+  uploaded in a single request, and only larger files use multipart upload via
+  the `TransferManager` (falling back to the older API when it's not available).

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

@@ -161,7 +161,7 @@ class Shrine
         #     attacher.stored?(attacher.derivatives[:thumb]) #=> true
         def promote(**options)
           super
-          promote_derivatives
+          promote_derivatives(**options)
           create_derivatives if create_derivatives_on_promote?
         end
 
@@ -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/storage/file_system.rb

@@ -113,9 +113,18 @@ class Shrine
         end
       end
 
-      # Returns the full path to the file.
+      # Returns the full path to the file. Raises Shrine::Error if the id would
+      # resolve to a location outside of the storage #directory (e.g. an id
+      # containing `../` path traversal sequences in attacker-controlled data).
       def path(id)
-        directory.join(id.gsub("/", File::SEPARATOR))
+        path = directory.join(id.gsub("/", File::SEPARATOR))
+        expanded = path.expand_path
+
+        unless expanded == directory || expanded.to_s.start_with?("#{directory}#{File::SEPARATOR}")
+          raise Shrine::Error, "path #{id.inspect} resolves outside of the storage directory"
+        end
+
+        path
       end
 
       protected

data/lib/shrine/storage/s3.rb

@@ -230,20 +230,15 @@ class Shrine
 
       private
 
-      # Upload the file to S3.
-      # Uses @transfer_manager, if defined, for any size upload.
-      # Falls back to the original code using the older, now depricated
-      # AWS APIs for users of older version of the AWS Gem.
-      # for multipart uploads of large files.
+      # Uploads the file to S3. Uses multipart upload for large files.
       def put(io, id, **)
-        if @transfer_manager
+        if io.respond_to?(:size) && io.size && io.size <= @multipart_threshold[:upload]
+          object(id).put(body: io, **)
+        elsif @transfer_manager # multipart upload - transfer manager
           @transfer_manager.upload_stream(bucket: bucket.name, key: object_key(id), part_size: part_size(io), **) do |write_stream|
             IO.copy_stream(io, write_stream)
           end
-        elsif io.respond_to?(:size) && io.size && io.size <= @multipart_threshold[:upload]
-          object(id).put(body: io, **)
-        else
-          # multipart upload old API
+        else # multipart upload - before transfer manager
           object(id).upload_stream(part_size: part_size(io), **) do |write_stream|
             IO.copy_stream(io, write_stream)
           end

data/lib/shrine/version.rb

@@ -7,8 +7,8 @@ class Shrine
 
   module VERSION
     MAJOR = 3
-    MINOR = 7
-    TINY  = 1
+    MINOR = 9
+    TINY  = 0
     PRE   = nil
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")

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"
@@ -67,10 +69,10 @@ direct uploads for fully asynchronous user experience.
 
   # for instrumentation plugin
   gem.add_development_dependency "dry-monitor"
-  gem.add_development_dependency "activesupport", RUBY_ENGINE == "jruby" ? "~> 7.2" : "~> 8.1"
+  gem.add_development_dependency "activesupport", RUBY_ENGINE == "jruby" ? "~> 8.0.0" : "~> 8.1"
 
   # for ORM plugins
   gem.add_development_dependency "sequel"
-  gem.add_development_dependency "activerecord", RUBY_ENGINE == "jruby" ? "~> 7.2" : "~> 8.1"
+  gem.add_development_dependency "activerecord", RUBY_ENGINE == "jruby" ? "~> 8.0.0" : "~> 8.1"
   gem.add_development_dependency "sqlite3", "~> 2.1" unless RUBY_ENGINE == "jruby"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shrine
 version: !ruby/object:Gem::Version
-  version: 3.7.1
+  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
@@ -483,6 +497,8 @@ files:
 - doc/release_notes/3.6.0.md
 - 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
@@ -576,7 +592,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.13
 specification_version: 4
 summary: Toolkit for file attachments in Ruby applications
 test_files: []