shrine 3.0.0 → 3.2.2

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

@@ -130,16 +130,16 @@ end
 photo    = Photo.new(image_data: '{"id":"...","storage":"...","metadata":{...}}')
 attacher = ImageUploader::Attacher.from_entity(photo, :image)
 
-attacher.file #=> #<Shrine::UploadedFile @id="bc2e13.jpg" @storage_key=:store ...>
+attacher.file #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:store ...>
 
 attacher.attach(file)
-attacher.file          #=> #<Shrine::UploadedFile @id="397eca.jpg" @storage_key=:store ...>
+attacher.file          #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
 attacher.column_values #=> { image_data: '{"id":"397eca.jpg","storage":"store","metadata":{...}}' }
 
 photo    = Photo.new(attacher.column_values)
 attacher = ImageUploader::Attacher.from_entity(photo, :image)
 
-attacher.file #=> #<Shrine::UploadedFile @id="397eca.jpg" @storage_key=:store ...>
+attacher.file #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
 ```
 
 ### Loading entity

data/doc/plugins/form_assign.md

@@ -14,7 +14,7 @@ the attacher:
 
 ```rb
 attacher = photo.image_attacher
-attacher.form_assign("image" => file, "title" => "...", "description" => "...")
+attacher.form_assign({ "image" => file, "title" => "...", "description" => "..." })
 attacher.file #=> #<Shrine::UploadedFile>
 ```
 
@@ -22,17 +22,17 @@ It works with `remote_url`, `data_uri`, and `remove_attachment` plugins:
 
 ```rb
 # remote_url plugin
-attacher.form_assign("image_remote_url" => "https://example.com/...")
+attacher.form_assign({ "image_remote_url" => "https://example.com/..." })
 attacher.file #=> #<Shrine::UploadedFile>
 ```
 ```rb
 # data_uri plugin
-attacher.form_assign("image_data_uri" => "data:image/jpeg;base64,...")
+attacher.form_assign({ "image_data_uri" => "data:image/jpeg;base64,..." })
 attacher.file #=> #<Shrine::UploadedFile>
 ```
 ```rb
 # remove_attachment plugin
-attacher.form_assign("remove_image" => "1")
+attacher.form_assign({ "remove_image" => "1" })
 attacher.file #=> nil
 ```
 
@@ -40,7 +40,7 @@ The return value is a hash with form params, with file param replaced with
 cached file data, which can later be assigned again to the record.
 
 ```rb
-attacher.form_assign("image" => file, "title" => "...", "description" => "...")
+attacher.form_assign({ "image" => file, "title" => "...", "description" => "..." })
 #=> { :image => '{"id":"...","storage":"...","metadata":"..."}', "title" => "...", "description" => "..." }
 ```
 

data/doc/plugins/included.md

@@ -7,15 +7,35 @@ of the attachment module, and call additional methods on the model that
 includes it.
 
 ```rb
-plugin :included do |name|
-  # called when attachment module is included into a model
+class ImageUploader < Shrine
+  plugin :included do |name|
+    # called when attachment module is included into a model
 
-  self #=> #<Photo>
-  name #=> :image
+    self #=> Photo (the model class)
+    name #=> :image
+  end
 end
 ```
 ```rb
-Photo.include Shrine::Attachment(:image)
+class Photo
+  include ImageUploader::Attachment(:image) # triggers the included block
+end
+```
+
+For example, you can use it to define additional methods on the model:
+
+```rb
+class ImageUploader < Shrine
+  plugin :included do |name|
+    define_method(:"#{name}_width")  { send(name)&.width  }
+    define_method(:"#{name}_height") { send(name)&.height }
+  end
+end
+```
+```rb
+photo = Photo.new(image: file)
+photo.image_width  #=> 1200
+photo.image_height #=> 800
 ```
 
 [included]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/included.rb

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

@@ -26,12 +26,12 @@ photo = Photo.new
 
 photo.image = file
 
-photo.image      #=> #<Shrine::UploadedFile @id="bc2e13.jpg" @storage_key=:cache ...>
+photo.image      #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:cache ...>
 photo.image_data #=> '{"id":"bc2e13.jpg","storage":"cache","metadata":{...}}'
 
 photo.image_attacher.finalize
 
-photo.image      #=> #<Shrine::UploadedFile @id="397eca.jpg" @storage_key=:store ...>
+photo.image      #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
 photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
 ```
 
@@ -127,12 +127,12 @@ attacher = ImageUploader::Attacher.from_model(photo, :image)
 
 attacher.assign(file) # cache
 
-attacher.file    #=> #<Shrine::UploadedFile @id="bc2e13.jpg" @storage_key=:cache ...>
+attacher.file    #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:cache ...>
 photo.image_data #=> '{"id":"bc2e13.jpg","storage":"cache","metadata":{...}}'
 
 attacher.finalize # promote
 
-attacher.file    #=> #<Shrine::UploadedFile @id="397eca.jpg" @storage_key=:store ...>
+attacher.file    #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
 photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
 ```
 

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

@@ -40,7 +40,12 @@ around [open-uri].
 You can pass options to the downloader via the `:downloader` option:
 
 ```rb
-attacher.assign_remote_url(url, downloader: { 'Authorization' => 'Basic ...' })
+attacher.assign_remote_url url, downloader: {
+  headers: { "Authorization" => "Basic ..." },
+  read_timeout: 30, open_timeout: 30,
+  max_redirects: 5,
+  # ...
+}
 ```
 
 You can also change the downloader:
@@ -166,7 +171,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 +182,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/remove_invalid.md

@@ -11,9 +11,17 @@ plugin :remove_invalid
 ```
 
 ```rb
-photo.image = file # invalid file
+# without previous file
+photo.image        #=> nil
+photo.image = file # validation fails, assignment is reverted
 photo.valid?       #=> false
 photo.image        #=> nil
+
+# with previous file
+photo.image        #=> #<Shrine::UploadedFile id="foo" ...>
+photo.image = file # validation fails, assignment is reverted
+photo.valid?       #=> false
+photo.image        #=> #<Shrine::UploadedFile id="foo" ...>
 ```
 
 [remove_invalid]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/remove_invalid.rb

data/doc/plugins/sequel.md

@@ -27,12 +27,12 @@ photo = Photo.new
 
 photo.image = file # cache attachment
 
-photo.image      #=> #<Shrine::UploadedFile @id="bc2e13.jpg" @storage_key=:cache ...>
+photo.image      #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:cache ...>
 photo.image_data #=> '{"id":"bc2e13.jpg","storage":"cache","metadata":{...}}'
 
 photo.save # persist, promote attachment, then persist again
 
-photo.image      #=> #<Shrine::UploadedFile @id="397eca.jpg" @storage_key=:store ...>
+photo.image      #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
 photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
 
 photo.destroy # delete attachment
@@ -161,14 +161,14 @@ attacher = ImageUploader::Attacher.from_model(photo, :image)
 
 attacher.assign(file) # cache
 
-attacher.file    #=> #<Shrine::UploadedFile @id="bc2e13.jpg" @storage_key=:cache ...>
+attacher.file    #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:cache ...>
 photo.image_data #=> '{"id":"bc2e13.jpg","storage":"cache","metadata":{...}}'
 
 photo.save        # persist
 attacher.finalize # promote
 photo.save        # persist
 
-attacher.file    #=> #<Shrine::UploadedFile @id="397eca.jpg" @storage_key=:store ...>
+attacher.file    #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
 photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
 ```
 

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

@@ -0,0 +1,96 @@
+---
+title: Type Predicates
+---
+
+The [`type_predicates`][type_predicates] plugin adds predicate methods to
+`Shrine::UploadedFile` based on the MIME type. By default, it uses the
+[MiniMime] gem for looking up MIME types.
+
+```rb
+# Gemfile
+gem "mini_mime"
+```
+```rb
+Shrine.plugin :type_predicates
+```
+
+## General predicates
+
+The plugin adds four predicate methods based on the general type of the file:
+
+```rb
+file.image? # returns true for any "image/*" MIME type
+file.video? # returns true for any "video/*" MIME type
+file.audio? # returns true for any "audio/*" MIME type
+file.text?  # returns true for any "text/*" MIME type
+```
+
+If `mime_type` metadata value is nil, `Shrine::Error` will be raised.
+
+## Specific predicates
+
+The `UploadedFile#type?` method takes a file extension, and returns whether the
+`mime_type` metadata value of the uploaded file matches the MIME type
+associated to the given file extension.
+
+```rb
+file.type?(:jpg) # returns true if MIME type is "image/jpeg"
+file.type?(:svg) # returns true if MIME type is "image/svg+xml"
+file.type?(:mov) # returns true if MIME type is "video/quicktime"
+file.type?(:ppt) # returns true if MIME type is "application/vnd.ms-powerpoint"
+...
+```
+
+For convenience, you can create predicate methods for specific file types:
+
+```rb
+Shrine.plugin :type_predicates, methods: %i[jpg svg mov ppt]
+```
+```rb
+file.jpg? # returns true if MIME type is "image/jpeg"
+file.svg? # returns true if MIME type is "image/svg+xml"
+file.mov? # returns true if MIME type is "video/quicktime"
+file.ppt? # returns true if MIME type is "application/vnd.ms-powerpoint"
+```
+
+If `mime_type` metadata value is nil, or the underlying MIME type library
+doesn't recognize a given type, `Shrine::Error` will be raised.
+
+### MIME database
+
+The MIME type lookup by file extension is done by the underlying MIME type
+library ([MiniMime] by default). You can change the MIME type library via the
+`:mime` plugin option:
+
+```rb
+Shrine.plugin :type_predicates, mime: :marcel # requires adding "marcel" gem to the Gemfile
+```
+
+The following MIME type libraries are supported:
+
+| Name          | Description                                                           |
+| :----         | :---------                                                            |
+| `:mini_mime`  | (**Default**.) Uses [MiniMime] gem to look up MIME type by extension. |
+| `:mime_types` | Uses [mime-types] gem to look up MIME type by extension.              |
+| `:mimemagic`  | Uses [MimeMagic] gem to look up MIME type by extension.               |
+| `:marcel`     | Uses [Marcel] gem to look up MIME type by extension.                  |
+| `:rack_mime`  | Uses [Rack::Mime] to look up MIME type by extension.                  |
+
+You can also specify a custom block, which receives the extension and is
+expected to return the corresponding MIME type. Inside the block you can call
+into existing MIME type libraries:
+
+```rb
+Shrine.plugin :type_predicates, mime: -> (extension) do
+  mime_type   = Shrine.type_lookup(extension, :marcel)
+  mime_type ||= Shrine.type_lookup(extension, :mini_mime)
+  mime_type
+end
+```
+
+[type_predicates]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/type_predicates.rb
+[MiniMime]: https://github.com/discourse/mini_mime
+[mime-types]: https://github.com/mime-types/ruby-mime-types
+[MimeMagic]: https://github.com/minad/mimemagic
+[Marcel]: https://github.com/basecamp/marcel
+[Rack::Mime]: https://github.com/rack/rack/blob/master/lib/rack/mime.rb