shrine 3.3.0 → 3.5.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/paperclip.md

@@ -695,6 +695,7 @@ s3.upload(io, "object/destination/path")
 The Shrine storage has no replacement for the `:url` Paperclip option, and it
 isn't needed.
 
+[metadata_attributes]: https://shrinerb.com/docs/plugins/metadata_attributes
 [Managing Derivatives]: https://shrinerb.com/docs/changing-derivatives
 [direct uploads]: https://shrinerb.com/docs/getting-started#direct-uploads
 [S3]: https://shrinerb.com/docs/storage/s3

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
   )

data/doc/plugins/derivation_endpoint.md

@@ -331,6 +331,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 +819,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

@@ -133,7 +133,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 +778,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/entity.md

@@ -22,7 +22,9 @@ These methods read attachment data from the `#<name>_data` attribute on the
 entity instance.
 
 ```rb
-class Photo < Entity(:image_data) # has `image_data` reader
+class Photo
+  attr_reader :image_data
+
   include ImageUploader::Attachment(:image)
 end
 ```
@@ -94,7 +96,9 @@ You can also specify default attacher options when including
 `Shrine::Attachment`:
 
 ```rb
-class Photo < Entity(:image_data)
+class Photo
+  attr_reader :image_data
+
   include ImageUploader::Attachment(:image, store: :other_store)
 end
 ```
@@ -123,7 +127,8 @@ You can also use `Shrine::Attacher` directly (with or without the
 `Shrine::Attachment` module):
 
 ```rb
-class Photo < Entity(:image_data) # has `image_data` reader
+class Photo
+  attr_reader :image_data
 end
 ```
 ```rb
@@ -191,7 +196,7 @@ attacher.file   #=> nil
 ### Reloading
 
 The `Attacher#reload` method reloads attached file from the attachment data on
-the entity attribute.
+the entity attribute and resets dirty tracking.
 
 ```rb
 photo = Photo.new
@@ -206,6 +211,9 @@ attacher.reload
 attacher.file #=> #<ImageUploader::UploadedFile>
 ```
 
+If you want to reload attachment data while retaining dirty tracking state, use
+`Attacher#read` instead.
+
 ### Column values
 
 The `Attacher#column_values` method returns a hash with the entity attribute as

data/doc/plugins/instrumentation.md

@@ -173,7 +173,7 @@ methods:
 
 ```rb
 # sends a `my_event.shrine` event to the notifications component
-Shrine.instrument(:my_event, foo: "bar") do
+Shrine.instrument(:my_event, { foo: "bar" }) do
   # do work
 end
 ```

data/doc/plugins/keep_files.md

@@ -2,10 +2,11 @@
 title: Keep Files
 ---
 
-The [`keep_files`][keep_files] plugin prevents file deletion when the attacher
-is about to destroy currently attached or previously attached file. This
-functionality is useful when implementing soft deletes, versioning, or in
-general any scenario where you need to track history.
+The [`keep_files`][keep_files] plugin prevents the attached file (and any of
+its [derivatives]) from being deleted when the attachment would normally be
+destroyed, which happens when the attachment is removed/replaced, or when the
+record is deleted. This functionality is useful when implementing soft deletes,
+versioning, or in general any scenario where you need to keep history.
 
 ```rb
 plugin :keep_files
@@ -17,3 +18,4 @@ photo.image.exists? #=> true
 ```
 
 [keep_files]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/keep_files.rb
+[derivatives]: https://shrinerb.com/docs/plugins/derivatives

data/doc/plugins/model.md

@@ -17,7 +17,9 @@ Including a `Shrine::Attachment` module into a model class will:
 * add `#<name>=` and `#<name>_changed?` methods
 
 ```rb
-class Photo < Model(:image_data) # has `image_data` accessor
+class Photo
+  attr_accessor :image_data
+
   include ImageUploader::Attachment(:image)
 end
 ```
@@ -107,7 +109,9 @@ If you still want to include `Shrine::Attachment` modules to immutable
 entities, you can disable "model" behaviour by passing `model: false`:
 
 ```rb
-class Photo < Entity(:image_data)
+class Photo
+  attr_reader :image_data
+
   include ImageUploader::Attachment(:image, model: false)
 end
 ```
@@ -118,7 +122,8 @@ You can also use `Shrine::Attacher` directly (with or without the
 `Shrine::Attachment` module):
 
 ```rb
-class Photo < Model(:image_data) # has `image_data` accessor
+class Photo
+  attr_accessor :image_data
 end
 ```
 ```rb

data/doc/plugins/sequel.md

@@ -172,7 +172,7 @@ attacher.file    #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
 photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
 ```
 
-### Pesistence
+### Persistence
 
 The following persistence methods are added to `Shrine::Attacher`:
 

data/doc/plugins/validation_helpers.md

@@ -10,7 +10,7 @@ plugin :validation_helpers
 
 Attacher.validate do
   validate_mime_type %w[image/jpeg image/png image/webp]
-  validate_max_size 5*1024*1024
+  validate_max_size 5*1024*1024 # bytes
   # ...
 end
 ```

data/doc/processing.md

@@ -315,14 +315,15 @@ previews.
 
 Shrine provides on-the-fly processing functionality via the
 **[`derivation_endpoint`][derivation_endpoint]** plugin. You set it up by
-loading the plugin with a secret key and a path prefix, mount its Rack app in
+loading the plugin with a secret key (you generate this yourself, maybe via
+something like `SecureRandom.hex`) and a path prefix, mount its Rack app in
 your routes on the configured path prefix, and define processing you want to
 perform:
 
 ```rb
 # config/initializers/shrine.rb (Rails)
 # ...
-Shrine.plugin :derivation_endpoints, secret_key: "<YOUR_SECRET_KEY>"
+Shrine.plugin :derivation_endpoint, secret_key: "<SHRINE_SECRET_KEY>"
 ```
 ```rb
 require "image_processing/mini_magick"

data/doc/refile.md

@@ -458,7 +458,7 @@ Shrine.plugin :cached_attachment_data
 ```
 ```rb
 form_for @user do |form|
-  form.hidden_field :profile_image, value: @user.cached_profile_image_data
+  form.hidden_field :profile_image, value: @user.cached_profile_image_data, id: nil
   form.file_field :profile_image
 end
 ```
@@ -475,7 +475,7 @@ Shrine.plugin :remove_attachment
 ```
 ```rb
 form_for @user do |form|
-  form.hidden_field :profile_image, value: @user.cached_profile_image_data
+  form.hidden_field :profile_image, value: @user.cached_profile_image_data, id: nil
   form.file_field :profile_image
   form.check_box :remove_profile_image
 end
@@ -491,7 +491,7 @@ Shrine.plugin :remote_url
 ```
 ```rb
 form_for @user do |form|
-  form.hidden_field :profile_image, value: @user.cached_profile_image_data
+  form.hidden_field :profile_image, value: @user.cached_profile_image_data, id: nil
   form.file_field :profile_image
   form.text_field :profile_image_remote_url
 end

data/doc/release_notes/2.1.0.md

@@ -51,7 +51,7 @@ end
 
 ```rb
 form_for @photo do |f|
-  f.hidden_field :image, value: @photo.cached_image_data
+  f.hidden_field :image, value: @photo.cached_image_data, id: nil
   f.file_filed :image
 end
 ```

data/doc/release_notes/3.4.0.md

@@ -0,0 +1,35 @@
+---
+title: Shrine 3.4.0
+---
+
+* Passing attacher options to `Shrine.Attachment` method now works on Ruby 3.0.
+
+* Defining validation errors as an array of I18n key and options in
+  `activerecord` plugin now works on Ruby 3.0.
+
+* The `:fastimage` MIME type analyzer now correctly detects SVGs as
+  `image/svg+html` in the `determine_mime_type` plugin.
+
+* The `Shrine::Attacher#read` method provided by the `entity` plugin is now
+  public. This is consistent with `Shrine::Attacher#write` from `model` plugin
+  being public as well.
+
+* The `Shrine::Attacher#reload` method now resets attachment's dirty state.
+  This means that for a model whose `Attacher#changed?` returns `true`, calling
+  `#reload` on the model will make `Attacher#changed?` return `false`. This was
+  the behaviour before Shrine 3.3.0.
+
+  ```rb
+  # before
+  model.file_attacher.changed? #=> true
+  model.reload
+  model.file_attacher.changed? #=> true
+
+  # after
+  model.file_attacher.changed? #=> true
+  model.reload
+  model.file_attacher.changed? #=> false
+  ```
+
+* Calling `#reload` on the model will not initialize a `Shrine::Attacher`
+  instance anymore if one hasn't previously been initialized.

data/doc/release_notes/3.5.0.md

@@ -0,0 +1,63 @@
+---
+title: Shrine 3.5.0
+---
+
+## New features
+
+* The website has been migrated to Docusaurus v2. :sparkles:
+
+* The `:signer` option has been added to the `derivation_endpoint` plugin, for when you want to use custom URL signing. This is useful when using `:expires_in`, and wanting to have expiring URLs work with CDN caching.
+
+  ```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
+  ```
+
+* The S3 storage now supports `:max_multipart_parts` option for specifying the maximum number of concurrent parts in which a large file will get uploaded. This number defaults to `10_000`.
+
+  ```rb
+  Shrine::Storage::S3.new(max_multipart_parts: 1000, ...)
+  ```
+
+* The `:encoding` option can now be passed to `S3#open`, which is applied to downloaded chunks.
+
+  ```rb
+  io = uploaded_file.open(encoding: Encoding::UTF_8)
+  csv = CSV.new(io)
+  # ...
+  ```
+
+## Other improvements
+
+* Passing a boolean value to the `#remove_attachment=` setter now works on Ruby 3.2. Previously this would raise an error, because Shrine would try to call `=~` on it, but `Object#=~` method has been removed in Ruby 3.2.
+
+* When duplicating a model instance, the duplicated attacher now references the duplicated model instance instead of the original one.
+
+* The download endpoint now returns a `400 Bad Request` response when the serialized file component is invalid.
+
+* The `derivatives` plugin now supports passing `mutex: false` option to disable usage of a mutex. This makes the `Shrine::Attacher` object marshallable, which should enable using `Marshal.dump` and `Marshal.load` on model instances with attachments. This should be safe unless you're adding derivatives on the same attacher object concurrently.
+
+* When loading the `derivatives` plugin with `versions_compatibility: true`, this setting doesn't leak to other uploaders anymore. Previously if other uploaders would load `derivatives` plugin without this option, versions compatibility would still get enabled for them. This change also fixes behavior on JRuby.
+
+* When S3 storage copies files, the AWS tag are not inherited anymore. This allows passing the `:tagging` upload option when promoting from temporary to permanent storage, and have it take effect.
+
+* The `UploadedFile#url` method doesn't call the obsolete `URI.regexp` method anymore, which should avoid warnings.
+
+* The `infer_extension` plugin now defines `infer_extension` instance method (in addition to class method) on the uploader for convenience, so that it can be easily called at the uploader instance level.
+
+  ```rb
+  class MyUploader < Shrine
+    plugin :infer_extension
+
+    def generate_location(io, metadata:, **)
+      extension = infer_extension(metadata["mime_type"])
+      # ...
+    end
+  end
+  ```

data/doc/retrieving_uploads.md

@@ -124,7 +124,7 @@ end # underlying IO object is closed
 ```
 
 `Shrine::UploadedFile#open` will return the result of a given block.
-block. We can use that to safely retrieve the whole content of a file, without
+We can use that to safely retrieve the whole content of a file, without
 leaving any temporary files lying around.
 
 ```rb