shrine 3.4.0 → 3.10.0

data/doc/multiple_files.md

@@ -3,6 +3,9 @@ id: multiple-files
 title: Multiple Files
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 There are times when you want to allow users to attach multiple files to a
 single resource, like an album having many photos or a playlist having many
 songs. Some file attachment libraries provide a special interface for multiple
@@ -67,8 +70,9 @@ files (or attachments) table will be the photos table.
 Let's create a table for the main resource and attachments, and add a foreign
 key in the attachment table for the main table:
 
-<!--DOCUSAURUS_CODE_TABS-->
-<!--Sequel-->
+<Tabs>
+<TabItem value="sequel" label="Sequel">
+
 ```rb
 Sequel.migration do
   change do
@@ -87,7 +91,10 @@ Sequel.migration do
   end
 end
 ```
-<!--ActiveRecord-->
+
+</TabItem>
+<TabItem value="activerecord" label="Active Record">
+
 ```rb
 class CreateAlbumsAndPhotos < ActiveRecord::Migration
   def change
@@ -104,25 +111,33 @@ class CreateAlbumsAndPhotos < ActiveRecord::Migration
   end
 end
 ```
-<!--END_DOCUSAURUS_CODE_TABS-->
+
+</TabItem>
+</Tabs>
 
 In the Photo model, create a Shrine attachment attribute named `image`
 (`:image` matches the `_data` column prefix above):
 
-<!--DOCUSAURUS_CODE_TABS-->
-<!--Sequel-->
+<Tabs>
+<TabItem value="sequel" label="Sequel">
+
 ```rb
 class Photo < Sequel::Model
   include ImageUploader::Attachment(:image)
 end
 ```
-<!--ActiveRecord-->
+
+</TabItem>
+<TabItem value="activerecord" label="Active Record">
+
 ```rb
 class Photo < ActiveRecord::Base
   include ImageUploader::Attachment(:image)
 end
 ```
-<!--END_DOCUSAURUS_CODE_TABS-->
+
+</TabItem>
+</Tabs>
 
 ### 2. Declare nested attributes
 
@@ -131,8 +146,9 @@ Using nested attributes is the easiest way to implement any dynamic
 relationship to the photos table, and allow it to directly accept attributes
 for the associated photo records by enabling nested attributes:
 
-<!--DOCUSAURUS_CODE_TABS-->
-<!--Sequel-->
+<Tabs>
+<TabItem value="sequel" label="Sequel">
+
 ```rb
 class Album < Sequel::Model
   one_to_many :photos
@@ -142,14 +158,20 @@ class Album < Sequel::Model
   nested_attributes :photos, destroy: true
 end
 ```
-<!--ActiveRecord-->
+
+</TabItem>
+<TabItem value="activerecord" label="Active Record">
+
 ```rb
 class Album < ActiveRecord::Base
   has_many :photos, dependent: :destroy
   accepts_nested_attributes_for :photos, allow_destroy: true
 end
 ```
-<!--Mongoid-->
+
+</TabItem>
+<TabItem value="mongoid" label="Mongoid">
+
 ```rb
 class Album
   include Mongoid::Document
@@ -157,7 +179,9 @@ class Album
   accepts_nested_attributes_for :photos
 end
 ```
-<!--END_DOCUSAURUS_CODE_TABS-->
+
+</TabItem>
+</Tabs>
 
 Documentation on nested attributes:
 
@@ -174,13 +198,14 @@ already created photos, so that the same form can be used for updating the
 album/photos as well (they will be submitted under the
 `album[photos_attributes]` parameter).
 
-<!--DOCUSAURUS_CODE_TABS-->
-<!--Rails form builder-->
+<Tabs>
+<TabItem value="rails" label="Rails form builder">
+
 ```rb
 form_for @album, html: { enctype: "multipart/form-data" } do |f|
   f.text_field :title
   f.fields_for :photos do |p| # adds new `album[photos_attributes]` parameter
-    p.hidden_field :image, value: p.object.cached_image_data
+    p.hidden_field :image, value: p.object.cached_image_data, id: nil
     p.file_field   :image
     p.check_box    :_destroy unless p.object.new_record?
   end
@@ -188,7 +213,10 @@ form_for @album, html: { enctype: "multipart/form-data" } do |f|
   f.submit "Create"
 end
 ```
-<!--Forme-->
+
+</TabItem>
+<TabItem value="forme" label="Forme">
+
 ```rb
 form @album, action: "/photos", enctype: "multipart/form-data" do |f|
   f.input :title
@@ -201,7 +229,9 @@ form @album, action: "/photos", enctype: "multipart/form-data" do |f|
   f.button "Create"
 end
 ```
-<!--END_DOCUSAURUS_CODE_TABS-->
+
+</TabItem>
+</Tabs>
 
 In your controller you should still be able to assign all the attributes to the
 album, just remember to whitelist the new parameter for the nested attributes,
@@ -286,21 +316,26 @@ class ImageUploader < Shrine
   end
 end
 ```
-<!--DOCUSAURUS_CODE_TABS-->
-<!--Sequel-->
+<Tabs>
+<TabItem value="sequel" label="Sequel">
+
 ```rb
 class Album < Sequel::Model
   # ... (nested_attributes already enables validating associated photos) ...
 end
 ```
-<!--ActiveRecord-->
+
+</TabItem>
+<TabItem value="activerecord" label="Active Record">
+
 ```rb
 class Album < ActiveRecord::Base
   # ...
   validates_associated :photos
 end
 ```
-<!--END_DOCUSAURUS_CODE_TABS-->
+</TabItem>
+</Tabs>
 
 Note that by default only metadata set on the client side will be available for
 validations. Shrine will not automatically run metadata extraction for directly

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

@@ -46,7 +46,7 @@ Then, in your initializer, you can configure all uploaders to use these jobs:
 
 ```rb
 Shrine::Attacher.promote_block do
-  PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
+  PromoteJob.perform_async(self.class.name, record.class.name, record.id, name.to_s, file_data)
 end
 Shrine::Attacher.destroy_block do
   DestroyJob.perform_async(self.class.name, data)
@@ -58,7 +58,7 @@ Alternatively, you can setup backgrounding only for specific uploaders:
 ```rb
 class MyUploader < Shrine
   Attacher.promote_block do
-    PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
+    PromoteJob.perform_async(self.class.name, record.class.name, record.id, name.to_s, file_data)
   end
   Attacher.destroy_block do
     DestroyJob.perform_async(self.class.name, data)
@@ -121,7 +121,7 @@ Shrine::Attacher.promote_block do |attacher|
     attacher.class.name,
     attacher.record.class.name,
     attacher.record.id,
-    attacher.name,
+    attacher.name.to_s,
     attacher.file_data,
   )
 end
@@ -143,7 +143,7 @@ photo.image_attacher.promote_block do |attacher|
     attacher.class.name,
     attacher.record.class.name,
     attacher.record.id,
-    attacher.name,
+    attacher.name.to_s,
     attacher.file_data,
     current_user.id, # pass arguments known at the controller level
   )
@@ -203,6 +203,32 @@ class MyUploader < Shrine
 end
 ```
 
+## Testing
+
+Since promotion happens in a background job, it won't have run yet
+immediately after you save the record, so asserting on the promoted file's
+data or location will fail unless the job has actually been executed. For
+example, with Active Job you'll need to run enqueued jobs inline:
+
+```rb
+require "active_job/test_helper"
+
+include ActiveJob::TestHelper
+
+perform_enqueued_jobs do
+  photo = Photo.create(image: file) # spawns promote job
+end
+
+photo.reload # fetch attachment data updated by the background job
+photo.image.storage_key #=> :store
+```
+
+Keep in mind that while the file is cached (i.e. before the promote job has
+run), the record may not have an `id` yet, so plugins like [`pretty_location`]
+that build the storage location from the record's identifier won't be able
+to include it until promotion happens.
+
 [backgrounding]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/backgrounding.rb
+[`pretty_location`]: https://shrinerb.com/docs/plugins/pretty_location
 [derivatives]: https://shrinerb.com/docs/plugins/derivatives
 [atomic_helpers]: https://shrinerb.com/docs/plugins/atomic_helpers

data/doc/plugins/data_uri.md

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

data/doc/plugins/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
@@ -331,6 +345,29 @@ uploaded_file.derivation_url(:thumbnail, expires_in: 90)
 #=> ".../thumbnail/eyJpZCI6ImZvbyIsInN?expires_at=1547843568&signature=..."
 ```
 
+## Custom signer
+
+The derivation URLs are signed by default, and the signature is checked when
+the URLs are requested, which prevents tampering. If you have URL expiration
+turned on, this may prevent your CDN from caching the response.
+
+In this case, you may need to do custom CDN-specific URL signing. You can
+bypass Shrine's default signing by passing a custom signer:
+
+```rb
+require "aws-sdk-cloudfront"
+signer = Aws::CloudFront::UrlSigner.new(key_pair_id: "...", private_key: "...")
+
+plugin :derivation_endpoint,
+  expires_in: 90,
+  signer: -> (url, expires_in:) do
+    signer.signed_url(url, expires: Time.now.to_i + expires_in)
+  end
+```
+
+When `:signer` option is used, the `:secret_key` option is not required, as
+that secret is only used for default signing.
+
 ## Response headers
 
 ### Content Type
@@ -796,6 +833,7 @@ derivation.option(:upload_location)
 | `:metadata`                    | List of metadata keys the source uploaded file should include in the derivation block                                                 | `[]`                                                 |
 | `:prefix`                      | Path prefix added to the URLs                                                                                                         | `nil`                                                |
 | `:secret_key`                  | Key used to sign derivation URLs in order to prevent tampering                                                                        | required                                             |
+| `:signer`                      | Proc accepting URL and query params used for custom signing of URLs.                                                                  | `nil`                                                |
 | `:type`                        | Media type returned in the `Content-Type` response header in the derivation response                                                  | determined from derivative's extension when possible |
 | `:upload`                      | Whether the generated derivatives will be cached on the storage                                                                       | `false`                                              |
 | `:upload_location`             | Location to which the derivatives will be uploaded on the storage                                                                     | `<source id>/<name>-<args>`                          |

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"
@@ -133,7 +134,7 @@ Attacher.default_url do |derivative: nil, **|
 end
 ```
 ```rb
-photo.image_url(:medium) #=> "https://example.com/fallbacks.com/medium.jpg"
+photo.image_url(:medium) #=> "https://example.com/fallbacks/medium.jpg"
 ```
 
 Any additional URL options passed to `#<name>_url` will be forwarded to the
@@ -778,6 +779,16 @@ derivatives #=>
 Like `Shrine.uploaded_file`, the `Shrine.derivatives` method accepts data as a
 hash (stringified or symbolized) or a JSON string.
 
+### Marshalling
+
+The `Attacher` instance uses a mutex to make `Attacher#merge_derivatives`
+thread-safe, which is not marshallable. If you want to be able to marshal the
+attacher instance, you can skip mutex usage:
+
+```rb
+plugin :derivatives, mutex: false
+```
+
 ## Instrumentation
 
 If the `instrumentation` plugin has been loaded, the `derivatives` plugin adds

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/dynamic_storage.md

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

data/doc/plugins/fallback_storage.md

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