shrine 3.0.1 → 3.1.0

data/doc/plugins/determine_mime_type.md

@@ -106,7 +106,7 @@ payload:
 
 A default log subscriber is added as well which logs these events:
 
-```plaintext
+```
 MIME Type (33ms) – {:io=>StringIO, :uploader=>Shrine}
 ```
 
@@ -117,7 +117,7 @@ plugin :determine_mime_type, log_subscriber: -> (event) {
   Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
 }
 ```
-```plaintext
+```
 {"name":"mime_type","duration":24,"io":"#<StringIO:0x00007fb7c5b08b80>","uploader":"Shrine"}
 ```
 

data/doc/plugins/infer_extension.md

@@ -70,7 +70,7 @@ payload:
 
 A default log subscriber is added as well which logs these events:
 
-```plaintext
+```
 Extension (5ms) – {:mime_type=>"image/jpeg", :uploader=>Shrine}
 ```
 
@@ -81,7 +81,7 @@ plugin :infer_extension, log_subscriber: -> (event) {
   Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
 }
 ```
-```plaintext
+```
 {"name":"extension","duration":5,"mime_type":"image/jpeg","uploader":"Shrine"}
 ```
 

data/doc/plugins/instrumentation.md

@@ -34,7 +34,7 @@ uploaded_file.exists?
 uploaded_file.download
 uploaded_file.delete
 ```
-```plaintext
+```
 Metadata (32ms) – {:storage=>:store, :io=>StringIO, :uploader=>Shrine}
 Upload (1523ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :io=>StringIO, :upload_options=>{}, :uploader=>Shrine}
 Exists (755ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}

data/doc/plugins/metadata_attributes.md

@@ -2,21 +2,18 @@
 title: Metadata Attributes
 ---
 
-The [`metadata_attributes`][metadata_attributes] plugin allows you to sync
-attachment metadata to additional record attributes. You can provide a hash of
-mappings to the plugin call itself or the `Attacher.metadata_attributes`
-method:
+The [`metadata_attributes`][metadata_attributes] plugin allows you to write
+attachment metadata to additional record attributes. You can configure the
+plugin with a hash of mappings:
 
 ```rb
 plugin :metadata_attributes, :size => :size, :mime_type => :type
-
 # or
-
 plugin :metadata_attributes
 Attacher.metadata_attributes :size => :size, :mime_type => :type
 ```
 
-The above configuration will sync `size` metadata field to `<attachment>_size`
+The above configuration will write `size` metadata field to `<attachment>_size`
 record attribute, and `mime_type` metadata field to `<attachment>_type` record
 attribute.
 
@@ -32,6 +29,18 @@ user.avatar_size #=> nil
 user.avatar_type #=> nil
 ```
 
+## Model and Entity
+
+With the [`model`][model] plugin, any method that internally calls
+`Attacher#write` will trigger metadata attributes writing (`Attacher#assign`,
+`Attacher#attach`, `Attacher#change`, `Attacher#set`).
+
+```rb
+attacher.file.metadata["mime_type"] = "other/type"
+attacher.write
+attacher.record.avatar_type #=> "other/type"
+```
+
 If you're using the [`entity`][entity] plugin, metadata attributes will be
 added to `Attacher#column_values`:
 
@@ -45,6 +54,11 @@ attacher.column_values #=>
 # }
 ```
 
+Any metadata attributes that were declared but are missing on the record will
+be skipped.
+
+## Full attribute name
+
 If you want to specify the full record attribute name, pass the record
 attribute name as a string instead of a symbol.
 
@@ -56,8 +70,5 @@ photo.image = image
 photo.original_filename #=> "nature.jpg"
 ```
 
-Any metadata attributes that were declared but are missing on the record will
-be skipped.
-
 [metadata_attributes]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/metadata_attributes.rb
 [entity]: https://shrinerb.com/docs/plugins/entity

data/doc/plugins/persistence.md

@@ -89,3 +89,4 @@ attacher.persist # saves the underlying record
 
 [activerecord]: https://shrinerb.com/docs/plugins/activerecord
 [sequel]: https://shrinerb.com/docs/plugins/sequel
+[backgrounding]: https://shrinerb.com/docs/plugins/backgrounding

data/doc/plugins/refresh_metadata.md

@@ -12,17 +12,18 @@ plugin :refresh_metadata
 It provides `#refresh_metadata!` method, which triggers metadata extraction
 (calls `Shrine#extract_metadata`) with the uploaded file opened for reading,
 and updates the existing metadata hash with the results. This can be done
-on the attacher or the uploaded file level.
+on the `Shrine::Attacher` or the `Shrine::UploadedFile` level.
 
 ## Attacher
 
 Calling `#refresh_metadata!` on a `Shrine::Attacher` object will re-extract
-metadata of the attached file. When used with a [model], it will write new file
-data back into the attachment attribute.
+metadata of the attached file, and when used with a [model], it will write new
+file data back into the attachment attribute.
 
 ```rb
 attacher.refresh_metadata!
-attacher.file.metadata # re-extracted metadata
+attacher.file.metadata    # re-extracted metadata
+attacher.record.file_data #=> '{ ... data with updated metadata ... }'
 ```
 
 The `Attacher#context` hash will be forwarded to metadata extraction, as well

data/doc/plugins/remote_url.md

@@ -166,7 +166,7 @@ following payload:
 
 A default log subscriber is added as well which logs these events:
 
-```plaintext
+```
 Remote URL (1550ms) – {:remote_url=>"https://example.com/image.jpg",:download_options=>{},:uploader=>Shrine}
 ```
 
@@ -177,7 +177,7 @@ plugin :remote_url, log_subscriber: -> (event) {
   Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
 }
 ```
-```plaintext
+```
 {"name":"remote_url","duration":5,"remote_url":"https://example.com/image.jpg","download_options":{},"uploader":"Shrine"}
 ```
 

data/doc/plugins/signature.md

@@ -55,6 +55,15 @@ add_metadata :md5 do |io, action: nil, **|
 end
 ```
 
+## Rewinding
+
+If you want to calculate signature from a non-rewindable IO object, you can
+tell Shrine to skip rewinding:
+
+```rb
+Shrine.calculate_signature(io, :md5, rewind: false)
+```
+
 ## Instrumentation
 
 If the `instrumentation` plugin has been loaded, the `signature` plugin adds
@@ -76,7 +85,7 @@ following payload:
 
 A default log subscriber is added as well which logs these events:
 
-```plaintext
+```
 MIME Type (33ms) – {:io=>StringIO, :uploader=>Shrine}
 ```
 
@@ -87,7 +96,7 @@ plugin :signature, log_subscriber: -> (event) {
   Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
 }
 ```
-```plaintext
+```
 {"name":"signature","duration":24,"io":"#<StringIO:0x00007fb7c5b08b80>","uploader":"Shrine"}
 ```
 

data/doc/plugins/store_dimensions.md

@@ -110,7 +110,7 @@ following payload:
 
 A default log subscriber is added as well which logs these events:
 
-```plaintext
+```
 Image Dimensions (108ms) – {:io=>File, :uploader=>Shrine}
 ```
 
@@ -121,7 +121,7 @@ plugin :store_dimensions, log_subscriber: -> (event) {
   Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
 }
 ```
-```plaintext
+```
 {"name":"image_dimensions","duration":114,"io":"#<File:0x00007fc445371d90>","uploader":"Shrine"}
 ```
 

data/doc/plugins/upload_endpoint.md

@@ -95,16 +95,9 @@ plugin :upload_endpoint, max_size: 20*1024*1024 # 20 MB
 If the uploaded file is larger than the specified value, a `413 Payload Too
 Large` response will be returned.
 
-## Context
+## Uploader options
 
-The upload context will *not* contain `:record` and `:name` values, as the
-upload happens independently of a database record. The endpoint will send the
-following upload context:
-
-* `:action` – holds the value `:upload`
-* `:request` – holds an instance of `Rack::Request`
-
-You can update the upload context via `:upload_context`:
+You can pass additional uploader options via `:upload_context`:
 
 ```rb
 plugin :upload_endpoint, upload_context: -> (request) do
@@ -112,13 +105,16 @@ plugin :upload_endpoint, upload_context: -> (request) do
 end
 ```
 
+Note that the uploader will *not* receive `:record` and `:name` values, as the
+upload happens independently of a database record.
+
 ## Upload
 
 You can also customize the upload itself via the `:upload` option:
 
 ```rb
-plugin :upload_endpoint, upload: -> (io, context, request) do
-  Shrine.upload(io, :cache, context)
+plugin :upload_endpoint, upload: -> (io, **options, request) do
+  Shrine.upload(io, :cache, **options)
 end
 ```
 

data/doc/plugins/validation_helpers.md

@@ -150,11 +150,11 @@ the `:default_messages` option to the plugin:
 ```rb
 plugin :validation_helpers, default_messages: {
   max_size:            -> (max)  { I18n.t("errors.file.max_size", max: max) },
-  min_size:            -> (max)  { I18n.t("errors.file.min_size", min: min) },
+  min_size:            -> (min)  { I18n.t("errors.file.min_size", min: min) },
   max_width:           -> (max)  { I18n.t("errors.file.max_width", max: max) },
-  min_width:           -> (max)  { I18n.t("errors.file.min_width", min: min) },
+  min_width:           -> (min)  { I18n.t("errors.file.min_width", min: min) },
   max_height:          -> (max)  { I18n.t("errors.file.max_height", max: max) },
-  min_height:          -> (max)  { I18n.t("errors.file.min_height", min: min) },
+  min_height:          -> (min)  { I18n.t("errors.file.min_height", min: min) },
   max_dimensions:      -> (dims) { I18n.t("errors.file.max_dimensions", dims: dims) },
   min_dimensions:      -> (dims) { I18n.t("errors.file.min_dimensions", dims: dims) },
   mime_type_inclusion: -> (list) { I18n.t("errors.file.mime_type_inclusion", list: list) },

data/doc/processing.md

@@ -13,7 +13,7 @@ processing with [ImageMagick]/[GraphicsMagick] (using the [MiniMagick] gem) or
 [libvips] (using the [ruby-vips] gem; see the [libvips section](#libvips)).
 Here is an example of generating a thumbnail with ImageProcessing:
 
-```sh
+```
 $ brew install imagemagick
 ```
 ```rb
@@ -43,7 +43,7 @@ Shrine.plugin :derivatives
 require "image_processing/mini_magick"
 
 class ImageUploader < Shrine
-  Attacher.derivatives_processor do |original|
+  Attacher.derivatives do |original|
     magick = ImageProcessing::MiniMagick.source(original)
 
     {
@@ -163,7 +163,7 @@ class ImageUploader < Shrine
     small:  [300, 300],
   }
 
-  Attacher.derivatives_processor do |original, name:|
+  Attacher.derivatives do |original, name:|
     thumbnail = ImageProcessing::MiniMagick
       .source(original)
       .resize_to_limit!(*THUMBNAILS.fetch(name))
@@ -223,7 +223,7 @@ gem "streamio-ffmpeg"
 require "streamio-ffmpeg"
 
 class VideoUploader < Shrine
-  Attacher.derivatives_processor do |original|
+  Attacher.derivatives do |original|
     transcoded = Tempfile.new ["transcoded", ".mp4"]
     screenshot = Tempfile.new ["screenshot", ".jpg"]
 
@@ -306,7 +306,7 @@ low memory usage (see [Why is libvips quick]).
 Using libvips is as easy as installing it and switching to the
 `ImageProcessing::Vips` backend:
 
-```sh
+```
 $ brew install vips
 ```
 

data/doc/refile.md

@@ -6,7 +6,7 @@ This guide is aimed at helping Refile users transition to Shrine, and it consist
 of three parts:
 
 1. Explanation of the key differences in design between Refile and Shrine
-2. Instructions how to migrate and existing app that uses Refile to Shrine
+2. Instructions how to migrate an existing app that uses Refile to Shrine
 3. Extensive reference of Refile's interface with Shrine equivalents
 
 ## Overview
@@ -199,13 +199,18 @@ explains this setup in more detail.
 ## Migrating from Refile
 
 You have an existing app using Refile and you want to transfer it to
-Shrine. Let's assume we have a `Photo` model with the "image" attachment. First
-we need to create the `image_data` column for Shrine:
+Shrine. Let's assume we have a `Photo` model with the "image" attachment.
+
+### 1. Add Shrine column
+
+First we need to create the `image_data` column for Shrine:
 
 ```rb
 add_column :photos, :image_data, :text
 ```
 
+### 2. Dual write
+
 Afterwards we need to make new uploads write to the `image_data` column. This
 can be done by including the below module to all models that have Refile
 attachments:
@@ -219,8 +224,7 @@ Shrine.storages = {
 }
 
 Shrine.plugin :model
-```
-```rb
+
 module RefileShrineSynchronization
   def write_shrine_data(name)
     attacher = Shrine::Attacher.from_model(self, name)
@@ -257,8 +261,12 @@ end
 ```
 
 After you deploy this code, the `image_data` column should now be successfully
-synchronized with new attachments.  Next step is to run a script which writes
-all existing Refile attachments to `image_data`:
+synchronized with new attachments.
+
+### 3. Data migration
+
+Next step is to run a script which writes all existing Refile attachments to
+`image_data`:
 
 ```rb
 Photo.find_each do |photo|
@@ -267,9 +275,22 @@ Photo.find_each do |photo|
 end
 ```
 
+### 4. Rewrite code
+
 Now you should be able to rewrite your application so that it uses Shrine
-instead of Refile, using equivalent Shrine storages. For help with translating
-the code from Refile to Shrine, you can consult the reference below.
+instead of Refile (you can consult the reference in the next section). You can
+remove the `RefileShrineSynchronization` module as well.
+
+### 5. Remove Refile columns
+
+If everything is looking good, we can remove Refile columns:
+
+```rb
+remove_column :photos, :image_id
+remove_column :photos, :image_size
+remove_column :photos, :image_filename
+remove_column :photos, :image_content_type
+```
 
 ## Refile to Shrine direct mapping
 

data/doc/release_notes/2.19.0.md

@@ -16,7 +16,7 @@ title: Shrine 2.19.0
   uploaded_file.download
   uploaded_file.delete
   ```
-  ```plaintext
+  ```
   Metadata (32ms) – {:storage=>:store, :io=>StringIO, :uploader=>Shrine}
   Upload (1523ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :io=>StringIO, :upload_options=>{}, :uploader=>Shrine}
   Exists (755ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}

data/doc/release_notes/3.0.1.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 3.0.1
+---
+
 ## Regressions
 
 * Fixed `metadata_attributes` plugin raising an exception when the attachment

data/doc/release_notes/3.1.0.md

@@ -0,0 +1,73 @@
+---
+title: Shrine 3.1.0
+---
+
+## New features
+
+* The `Attacher#create_derivatives` method now accepts a `:storage` option for
+  specifying the storage to which derivatives should be uploaded.
+
+  ```rb
+  # with attachment module
+  photo.image_derivatives!(storage: :other_store)
+
+  # with attacher
+  attacher.create_derivatives(storage: :other_store)
+  ```
+
+* The `Shrine.calculate_signature` now accepts a `:rewind` boolean option for
+  choosing whether the IO object should be rewinded after reading. This is
+  useful if you want to calculate signature from non-rewindable IO objects,
+  such as `IO.pipe`, `Socket`, non-rewindable `Down::ChunkedIO` etc.
+
+  ```rb
+  Shrine.signature(io, rewind: false)
+  ```
+
+## Improvements
+
+* The derivatives processor can now be registered with `Attacher.derivatives`,
+  which is just an alias for `Attacher.derivatives_processor`.
+
+  ```rb
+  class ImageUploader < Shrine
+    Attacher.derivatives_processor do |original|
+      # ...
+    end
+  end
+
+  # can now be written as
+
+  class ImageUploader < Shrine
+    Attacher.derivatives do |original|
+      # ...
+    end
+  end
+  ```
+
+* The `Attacher#cached?` and `Attacher#stored?` methods now work correctly if
+  temporary/permanent storage identifiers were specified as strings.
+
+* The `store_dimensions` plugin now properly propagates exceptions when loading
+  the `ruby-vips` gem in `:vips` analyzer.
+
+* The `add_metadata` plugin now respects inheritance again when defining
+  metadata methods on the `Shrine::UploadedFile` class. In 2.19.0, the
+  `add_metadata` plugin was changed to define metadata methods on the internal
+  `FileMethods` plugin module, which is shared across all uploaders. This
+  change has now been reverted.
+
+## Backwards compatibility
+
+* The `Attacher#cache_key` and `Attacher#store_key` methods now always return
+  symbol keys, even if the storage key that was specified was a string key.
+
+  ```rb
+  attacher = Shrine::Attacher.new(cache: "cache", store: "store")
+  attacher.cache_key #=> :cache (previously "cache")
+  attacher.store_key #=> :store (previously "store")
+  ```
+
+* The `add_metadata` plugin now defines metadata methods directly on the
+  `UploadedFile` class, which means that if you happen to have been overriding
+  these metadata methods and calling `super`, this won't work anymore.