shrine 3.6.0 → 3.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5fadb4e660b7638e1d17b81ecb1761e8dd5faa675f15a3b30de0c549bafd653
-  data.tar.gz: a9ee826b483ab474f55ac66bc35e95a4cb8496cada12ce7595091210670f1f38
+  metadata.gz: 29a02d25cd1180c4f0170434edd185b3b1ab0bd2be060fa53e58fcd32c50d4ae
+  data.tar.gz: 56e50d961ef88e0d3cae4d295b6996c52cd2021b923d9b453f401f10b04021b3
 SHA512:
-  metadata.gz: 2c0f867b7215189135563524f9e7d8cf28d8be1a5b298bc173bbe1af9fb3ced15f98dd198c8cb13bfa87abdf3eb29566083c6ebc1de0955713da6c165562c41d
-  data.tar.gz: 47c2f75d9a831fdc1d731086fbeeb5a6885a1845eac375a5ba2ce9b5354654f49931e6b26f2732d98edfa39cbfcf3e587be63f01490910a06a7bad64cea8219e
+  metadata.gz: cb06f261af63f09ba767556d65f8b99e5204c1162ce7d8e28e5355148539a02c486fa088819884cf38dee4bf0683e8167b6582c4a028271a5145bd8661f64765
+  data.tar.gz: ec5cd4f04fe90ada87cd594bf78e61c2de9fcbebe8d51cb9e49b0bec566614be5ea5826382a8f25608888c84a951f25ad80442a6af2d641a37bae0e8fe184d7e

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+## 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.
+
+## 3.7.0 (2026-05-27)
+
+* `rack_response` - Add `:etag` option for setting a custom `ETag` header (@janko)
+
+* `download_endpoint` - Add support for expiring URLs (@davidwessman)
+
+* `s3` - Use `TransferManager` where available instead of deprecated `upload_steam` (@danieldevlewis)
+
+* `column` - Don't attempt to deserialize empty string as JSON (@adam12)
+
+* `derivatives` - Add `:keep_derivatives` plugin option to keep existing derivatives when a new file is attached (@fnordfish)
+
+* `refresh_metadata` - Add `replace:` keyword argument to `refresh_metadata!` for replacing instead of merging existing metadata (@JacobGalati)
+
+* `backgrounding` - Fix options not being forwarded from `promote_cached` to `promote_block` (@4ndypanda)
+
+* Fix URI default parser warnings in `UploadedFile` (@adam12)
+
+* Drop support for Ruby < 3.2
+
 ## 3.6.0 (2024-04-29)
 
 * Add Rack 3 support (@tomasc, @janko)

data/doc/changing_derivatives.md

@@ -36,7 +36,8 @@ derivatives generated). Let's assume you're generating image thumbnails:
 
 ```rb
 # Gemfile
-gem "image_processing", "~> 1.8"
+gem "image_processing", "~> 2.0"
+gem "mini_magick", "~> 5.0"
 ```
 ```rb
 require "image_processing/mini_magick"

data/doc/changing_location.md

@@ -3,7 +3,7 @@ id: changing-location
 title: Migrating File Locations
 ---
 
-This guide shows how to migrate the location of uploaded files on the same 
+This guide shows how to migrate the location of uploaded files on the same
 storage in production, with zero downtime.
 
 Let's assume we have a `Photo` model with an `image` file attachment:
@@ -31,20 +31,32 @@ to work with the previously stored urls because the files have not been migrated
 ```rb
 class ImageUploader < Shrine
   def generate_location(io, **options)
-    # change location generation
+    # change location generation, eg....
+    [
+      options[:record] && options[:record].class.name.underscore,
+      option[:record] && options[:record].id,
+      super
+    ].compact.join("/")
   end
 end
 ```
 
-We can now deploy this change to production so new file uploads will be stored in 
+We can now deploy this change to production so new file uploads will be stored in
 the new location.
 
+As seen above, we can call `super` to get the include the default location, which uses ruby
+`SecureRandom.hex` to have a unique immutable storage location. While it isn't
+strictly required to have a unique immutable storage location, it makes many
+things work smoother when different content will get a different storage location,
+and is recommended. One approach is using fixed directory/prefix as above.
+
+
 ## 2. Move existing files
 
 To move existing files to new location, run the following script. It fetches
 the photos in batches, downloads the image, and re-uploads it to the new location.
-We only need to migrate the files in `:store` storage need to be migrated as the files
-in `:cache` storage will be uploaded to the new location on promotion.
+Only the files in `:store` storage need to be migrated as the files in `:cache`
+storage will be uploaded to the new location on promotion.
 
 ```rb
 Photo.find_each do |photo|

data/doc/getting_started.md

@@ -602,7 +602,8 @@ creation:
 
 ```rb
 # Gemfile
-gem "image_processing", "~> 1.8"
+gem "image_processing", "~> 2.0"
+gem "mini_magick", "~> 5.0"
 ```
 ```rb
 Shrine.plugin :derivatives, create_on_promote: true
@@ -656,7 +657,8 @@ processing we want to perform:
 
 ```rb
 # Gemfile
-gem "image_processing", "~> 1.8"
+gem "image_processing", "~> 2.0"
+gem "mini_magick", "~> 5.0"
 ```
 ```rb
 # config/initializers/rails.rb (Rails)

data/doc/plugins/derivation_endpoint.md

@@ -35,7 +35,8 @@ apply to an attached file. For example, we can generate image thumbnails using
 the [ImageProcessing] gem:
 
 ```rb
-gem "image_processing", "~> 1.8"
+gem "image_processing", "~> 2.0"
+gem "mini_magick", "~> 5.0"
 ```
 ```rb
 require "image_processing/mini_magick"
@@ -308,6 +309,19 @@ uploaded_file.derivation_url(:thumbnail, prefix: "transformations/image")
 #=> ".../transformations/image/thumbnail/eyJpZCI6ImZvbyIsInN?signature=..."
 ```
 
+## Format
+
+Some HTTP clients and CDNs use the URL path extension to determine the content
+type of the response. You can append a file extension to the derivation URL
+path with the `:format` option:
+
+```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.
+
 ## Expiration
 
 By default derivation URLs are valid indefinitely. If you want URLs to expire

data/doc/plugins/derivatives.md

@@ -20,7 +20,8 @@ Here is an example of generating image thumbnails:
 
 ```rb
 # Gemfile
-gem "image_processing", "~> 1.8"
+gem "image_processing", "~> 2.0"
+gem "mini_magick", "~> 5.0"
 ```
 ```rb
 require "image_processing/mini_magick"

data/doc/plugins/download_endpoint.md

@@ -7,7 +7,7 @@ downloading uploaded files from specified storages. This can be useful when
 files from your storage isn't accessible over URL (e.g. database storages) or
 if you want to authenticate your downloads.
 
-## Global Endpoint 
+## Global Endpoint
 
 You can configure the plugin with the path prefix which the endpoint will be
 mounted on.
@@ -34,6 +34,7 @@ Links to the download endpoint are generated by calling
 ```rb
 uploaded_file.download_url #=> "/attachments/eyJpZCI6ImFkdzlyeTM..."
 ```
+
 ## Endpoint via Uploader
 
 You can also configure the plugin in the uploader directly - just make sure to mount it via your Uploader-class.
@@ -52,8 +53,8 @@ Rails.application.routes.draw do
 end
 ```
 
-*Hint: For shrine versions 2.x -> ensure that you don't include the plugin
-twice (globally and in your uploader class - see #408)*
+_Hint: For shrine versions 2.x -> ensure that you don't include the plugin
+twice (globally and in your uploader class - see #408)_
 
 ## Calling from a controller
 
@@ -69,6 +70,7 @@ Rails.application.routes.draw do
   get "/attachments/*rest", to: "downloads#image"
 end
 ```
+
 ```rb
 # app/controllers/downloads_controller.rb (Rails)
 class DownloadsController < ApplicationController
@@ -131,6 +133,16 @@ plugin :download_endpoint, download_options: -> (uploaded_file, request) {
 }
 ```
 
+## Expiring download urls
+
+If you want to have URLs that expire after a certain time, you can use the `:expires_in` and `secret_key` options:
+
+```rb
+plugin :download_endpoint, expires_in: 5 * 60, secret_key: "secret"
+```
+
+this will generate URLs that are signed with a signature valid for 5 minutes.
+
 ## Performance considerations
 
 Streaming files through the app might impact the request throughput, depending
@@ -162,7 +174,7 @@ Shrine.download_endpoint(disposition: "attachment")
 ## Plugin options
 
 | Name                | Description                                                                       | Default  |
-| :--------           | :----------                                                                       | :------  |
+| :------------------ | :-------------------------------------------------------------------------------- | :------- |
 | `:disposition`      | Whether browser should render the file `inline` or download it as an `attachment` | `inline` |
 | `:download_options` | Hash of storage-specific options passed to `Storage#open`                         | `{}`     |
 | `:host`             | URL host that will be added to download URLs                                      | `nil`    |

data/doc/plugins/rack_response.md

@@ -95,6 +95,15 @@ headers["Content-Range"]  #=> "bytes 100-200/1000"
 body                      # partial content
 ```
 
+## ETag
+
+A custom ETag value can be provided via the `:etag` option:
+
+```rb
+response = uploaded_file.to_rack_response(etag: "my-custom-etag")
+response[1]["ETag"] #=> "my-custom-etag"
+```
+
 ## Download options
 
 The `#to_rack_response` method will automatically open the `UploadedFile` if it

data/doc/plugins/refresh_metadata.md

@@ -69,5 +69,25 @@ Any options passed in will be forwarded to metadata extraction:
 uploaded_file.refresh_metadata!(foo: "bar") # passes `{ foo: "bar" }` options to metadata extraction
 ```
 
+## Replacing Metadata
+
+By default the `#refresh_metadata!` method will merge the results into any existing metadata.
+
+```rb
+  uploaded_file.metadata["custom"] = "custom value"
+  uploaded_file.refresh_metadata!
+  uploaded_file.metadata
+  # returns {"filename"=>"example.jpg", "size"=>1024, "mime_type"=>"image/jpeg", "custom"=>"custom value"}
+```
+
+Passing `replace: true` will instead fully overwrite the existing metadata with the new metadata.
+
+```rb
+  uploaded_file.metadata["custom"] = "custom value"
+  uploaded_file.refresh_metadata!(replace: true)
+  uploaded_file.metadata
+  # returns {"filename"=>"example.jpg", "size"=>1024, "mime_type"=>"image/jpeg"}
+```
+
 [refresh_metadata]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/refresh_metadata.rb
 [model]: https://shrinerb.com/docs/plugins/model

data/doc/plugins/signature.md

@@ -78,15 +78,17 @@ plugin :signature
 Calculating signature will trigger a `signature.shrine` event with the
 following payload:
 
-| Key         | Description                            |
-| :--         | :----                                  |
-| `:io`       | The IO object                          |
-| `:uploader` | The uploader class that sent the event |
+| Key          | Description                            |
+| :--          | :----                                  |
+| `:algorithm` | The hashing algorithm used             |
+| `:format`    | The encoding format                    |
+| `:io`        | The IO object                          |
+| `:uploader`  | The uploader class that sent the event |
 
 A default log subscriber is added as well which logs these events:
 
 ```
-MIME Type (33ms) – {:io=>StringIO, :uploader=>Shrine}
+Signature (1ms) – {io: StringIO, algorithm: :md5, format: :hex, uploader: Shrine}
 ```
 
 You can also use your own log subscriber:
@@ -97,7 +99,7 @@ plugin :signature, log_subscriber: -> (event) {
 }
 ```
 ```
-{"name":"signature","duration":24,"io":"#<StringIO:0x00007fb7c5b08b80>","uploader":"Shrine"}
+{"name":"signature","duration":24,"io":"#<StringIO:0x00007fb7c5b08b80>","algorithm":"sha512","format":"hex","uploader":"Shrine"}
 ```
 
 Or disable logging altogether:

data/doc/processing.md

@@ -18,7 +18,8 @@ $ brew install imagemagick
 ```
 ```rb
 # Gemfile
-gem "image_processing", "~> 1.8"
+gem "image_processing", "~> 2.0"
+gem "mini_magick", "~> 5.0"
 ```
 ```rb
 require "image_processing/mini_magick"
@@ -405,7 +406,7 @@ Shrine integration, the ImageProcessing gem that we saw earlier is a completely
 generic gem.
 
 To demonstrate, here is an example of transcoding videos using
-[streamio-ffmpeg]:
+[streamio-ffmpeg][streamio-ffmpeg]:
 
 ```rb
 # Gemfile
@@ -502,7 +503,8 @@ $ brew install vips
 
 ```rb
 # Gemfile
-gem "image_processing", "~> 1.8"
+gem "image_processing", "~> 2.0"
+gem "ruby-vips", "~> 2.3"
 ```
 
 ```rb

data/doc/release_notes/3.7.0.md

@@ -0,0 +1,75 @@
+---
+title: Shrine 3.7.0
+---
+
+## New features
+
+* The `download_endpoint` plugin now supports expiring URLs. Configure a `secret_key` and optionally a default `expires_in` on the plugin, then pass `expires_in:` when generating a URL. The URL is signed with HMAC-SHA256, and the endpoint will reject requests with an expired or tampered signature.
+
+  ```rb
+  plugin :download_endpoint,
+    prefix: "downloads",
+    secret_key: "<your-secret-key>",
+    expires_in: 5 * 60 # optional default; can be overridden per URL
+  ```
+
+  ```rb
+  uploaded_file.download_url                      # uses the default expires_in
+  uploaded_file.download_url(expires_in: 10 * 60) # override per URL
+  # => "https://example.com/downloads/<token>?signature=...&expires_at=..."
+  ```
+
+* The `derivatives` plugin now accepts a `:keep_derivatives` option. When set to `true`, existing derivatives are kept when a new file is attached via `Attacher#change`, instead of being cleared.
+
+  ```rb
+  plugin :derivatives, keep_derivatives: true
+  ```
+
+  ```rb
+  attacher.derivatives #=> { thumb: #<Shrine::UploadedFile> }
+  attacher.change(new_file)
+  attacher.derivatives #=> { thumb: #<Shrine::UploadedFile> } # preserved
+  ```
+
+* The `refresh_metadata` plugin now accepts a `replace:` keyword argument on `refresh_metadata!`. Passing `replace: true` replaces the file's metadata entirely with the freshly extracted values, instead of merging them. This is useful when you want to remove stale custom metadata keys.
+
+  ```rb
+  uploaded_file.metadata["custom"] = "stale value"
+
+  uploaded_file.refresh_metadata!              # merge (default)
+  uploaded_file.metadata["custom"]             #=> "stale value" (preserved)
+
+  uploaded_file.refresh_metadata!(replace: true)  # replace
+  uploaded_file.metadata["custom"]             #=> nil (removed)
+  ```
+
+## Other improvements
+
+* The `s3` storage now prefers using `TransferManager#upload_stream` over the deprecated `#upload_stream` method on the S3 object, when `TransferManager` is available. This avoids deprecation warnings from newer versions of the AWS SDK.
+
+* The `column` plugin no longer attempts to deserialize an empty string as JSON. Previously this would raise a parse error; now the attachment is treated as blank.
+
+* The `backgrounding` plugin now correctly forwards keyword arguments passed to `Attacher#promote_cached` into the `promote_block` callback.
+
+  ```rb
+  Shrine::Attacher.promote_block do |attacher:, my_option:, **|
+    # my_option was previously not forwarded here
+    SomePromoteJob.perform_async(attacher.dump, my_option: my_option)
+  end
+
+  attacher.promote_cached(my_option: "value") # now forwarded correctly
+  ```
+
+* `UploadedFile` no longer produces URI default parser warnings (`URI::RFC3986_PARSER.make_regexp is obsolete`) when verbose warnings are enabled.
+
+## Backwards compatibility
+
+* Support for Ruby versions below 3.2 has been dropped. Ruby >= 3.2 is now required.
+
+* ImageProcessing 2.0 made `mini_magick` and `ruby-vips` soft dependencies that are no longer loaded automatically. If you use either gem for image processing, you will need to add it explicitly to your `Gemfile`:
+
+  ```rb
+  gem "mini_magick"
+  # or
+  gem "ruby-vips"
+  ```

data/doc/release_notes/3.7.1.md

@@ -0,0 +1,13 @@
+---
+title: Shrine 3.7.1
+---
+
+## Bug fixes
+
+* When initializing Shrine with the `activerecord` plugin, under Bootsnap 1.24.5 and Ruby 3.4.5 this would raise an error:
+
+  ```
+  ArgumentError: wrong number of arguments (given 2, expected 1; required keyword: plugin)
+  ```
+
+  The seems to be triggered by a special combination of method signatures, where keyword arguments get converted into positional arguments under Bootsnap. To work around this issue, method signatures of some plugin methods have been updated.

data/lib/shrine/attacher.rb

@@ -22,8 +22,8 @@ class Shrine
       #
       #     attacher = Attacher.from_data({ "id" => "...", "storage" => "...", "metadata" => { ... } })
       #     attacher.file #=> #<Shrine::UploadedFile>
-      def from_data(data, **options)
-        attacher = new(**options)
+      def from_data(data, **)
+        attacher = new(**)
         attacher.load_data(data)
         attacher
       end
@@ -47,14 +47,14 @@ class Shrine
       end
 
       # Returns the temporary storage identifier.
-      def cache_key; @cache.to_sym; end
+      def cache_key = @cache.to_sym
       # Returns the permanent storage identifier.
-      def store_key; @store.to_sym; end
+      def store_key = @store.to_sym
 
       # Returns the uploader that is used for the temporary storage.
-      def cache; shrine_class.new(cache_key); end
+      def cache = shrine_class.new(cache_key)
       # Returns the uploader that is used for the permanent storage.
-      def store; shrine_class.new(store_key); end
+      def store = shrine_class.new(store_key)
 
       # Calls #attach_cached, but skips if value is an empty string (this is
       # useful when the uploaded file comes from form fields). Forwards any
@@ -67,14 +67,14 @@ class Shrine
       #
       #     # ignores the assignment when a blank string is given
       #     attacher.assign("")
-      def assign(value, **options)
+      def assign(value, **)
         return if value == "" # skip empty hidden field
 
         if value.is_a?(Hash) || value.is_a?(String)
           return if uploaded_file(value) == file # skip assignment for current file
         end
 
-        attach_cached(value, **options)
+        attach_cached(value, **)
       end
 
       # Sets an existing cached file, or uploads an IO object to temporary
@@ -92,11 +92,11 @@ class Shrine
       #
       #     # sets an existing cached file from Hash data
       #     attacher.attach_cached({ "id" => "...", "storage" => "cache", "metadata" => {} })
-      def attach_cached(value, **options)
+      def attach_cached(value, **)
         if value.is_a?(String) || value.is_a?(Hash)
-          change(cached(value, **options))
+          change(cached(value, **))
         else
-          attach(value, storage: cache_key, action: :cache, **options)
+          attach(value, storage: cache_key, action: :cache, **)
         end
       end
 
@@ -113,8 +113,8 @@ class Shrine
       #
       #     # removes the attachment
       #     attacher.attach(nil)
-      def attach(io, storage: store_key, **options)
-        file = upload(io, storage, **options) if io
+      def attach(io, storage: store_key, **)
+        file = upload(io, storage, **) if io
 
         change(file)
       end
@@ -158,8 +158,8 @@ class Shrine
       #     attacher.cached? #=> true
       #     attacher.promote_cached
       #     attacher.stored? #=> true
-      def promote_cached(**options)
-        promote(**options) if promote?
+      def promote_cached(**)
+        promote(**) if promote?
       end
 
       # Uploads current file to permanent storage and sets the stored file.
@@ -167,8 +167,8 @@ class Shrine
       #     attacher.cached? #=> true
       #     attacher.promote
       #     attacher.stored? #=> true
-      def promote(storage: store_key, **options)
-        set upload(file, storage, action: :store, **options)
+      def promote(storage: store_key, **)
+        set upload(file, storage, action: :store, **)
       end
 
       # Delegates to `Shrine.upload`, passing the #context.
@@ -178,8 +178,8 @@ class Shrine
       #
       #     # pass additional options for the uploader
       #     attacher.upload(io, :store, metadata: { "foo" => "bar" })
-      def upload(io, storage = store_key, **options)
-        shrine_class.upload(io, storage, **context, **options)
+      def upload(io, storage = store_key, **)
+        shrine_class.upload(io, storage, **context, **)
       end
 
       # If a new file was attached, deletes previously attached file if any.
@@ -249,8 +249,8 @@ class Shrine
       #
       #     attacher.file = nil
       #     attacher.url #=> nil
-      def url(**options)
-        file&.url(**options)
+      def url(**)
+        file&.url(**)
       end
 
       # Returns whether the attachment has changed.

data/lib/shrine/attachment.rb

@@ -22,8 +22,8 @@ class Shrine
       # Shorthand for `Attachment.new`.
       #
       #   Shrine::Attachment[:image]
-      def [](*args, **options)
-        new(*args, **options)
+      def [](*, **)
+        new(*, **)
       end
     end
 

data/lib/shrine/plugins/_persistence.rb

@@ -7,7 +7,7 @@ class Shrine
     #
     #     plugin :_persistence, plugin: MyPlugin
     module Persistence
-      def self.load_dependencies(uploader, *)
+      def self.load_dependencies(uploader, **)
         uploader.plugin :atomic_helpers
         uploader.plugin :entity
       end

data/lib/shrine/plugins/_urlsafe_serialization.rb

@@ -23,8 +23,8 @@ class Shrine
       end
 
       module FileMethods
-        def urlsafe_dump(**options)
-          self.class.urlsafe_dump(self, **options)
+        def urlsafe_dump(**)
+          self.class.urlsafe_dump(self, **)
         end
 
         def urlsafe_data(metadata: [])
@@ -45,8 +45,8 @@ class Shrine
       end
 
       module FileClassMethods
-        def urlsafe_dump(file, **options)
-          data = file.urlsafe_data(**options)
+        def urlsafe_dump(file, **)
+          data = file.urlsafe_data(**)
 
           shrine_class.urlsafe_serialize(data)
         end

data/lib/shrine/plugins/add_metadata.rb

@@ -29,11 +29,9 @@ class Shrine
       end
 
       module InstanceMethods
-        def extract_metadata(io, **options)
+        def extract_metadata(io, **)
           metadata = super
-
-          extract_custom_metadata(io, **options, metadata: metadata)
-
+          extract_custom_metadata(io, **, metadata:)
           metadata
         end
 

data/lib/shrine/plugins/atomic_helpers.rb

@@ -14,14 +14,14 @@ class Shrine
         #
         #     Shrine::Attacher.retrieve(model: photo, name: :image, file: file_data)
         #     #=> #<ImageUploader::Attacher>
-        def retrieve(model: nil, entity: nil, name:, file:, **options)
+        def retrieve(model: nil, entity: nil, name:, file:, **)
           fail ArgumentError, "either :model or :entity is required" unless model || entity
 
           record = model || entity
 
-          attacher   = record.send(:"#{name}_attacher", **options) if record.respond_to?(:"#{name}_attacher")
-          attacher ||= from_model(record, name, **options) if model
-          attacher ||= from_entity(record, name, **options) if entity
+          attacher   = record.send(:"#{name}_attacher", **) if record.respond_to?(:"#{name}_attacher")
+          attacher ||= from_model(record, name, **) if model
+          attacher ||= from_entity(record, name, **) if entity
 
           if attacher.file != attacher.uploaded_file(file)
             fail Shrine::AttachmentChanged, "attachment has changed"
@@ -43,13 +43,13 @@ class Shrine
         #
         # This more convenient to use with concrete persistence plugins, which
         # provide defaults for reloading and persistence.
-        def abstract_atomic_promote(reload:, persist:, **options, &block)
+        def abstract_atomic_promote(reload:, persist:, **, &block)
           original_file = file
 
-          result = promote(**options)
+          result = promote(**)
 
           begin
-            abstract_atomic_persist(original_file, reload: reload, persist: persist, &block)
+            abstract_atomic_persist(original_file, reload:, persist:, &block)
             result
           rescue Shrine::AttachmentChanged
             destroy_attached