shrine 3.0.1 → 3.3.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/download_endpoint.md

@@ -87,6 +87,10 @@ class DownloadsController < ApplicationController
 end
 ```
 
+If you want to create an endpoint with a custom path, you can use the
+[`rack_response`][rack_response] plugin directly, which this plugin uses
+internally.
+
 ## Host
 
 You can specify download URL host via the `:host` plugin option:
@@ -155,11 +159,6 @@ You can override any of the options above when creating the endpoint:
 Shrine.download_endpoint(disposition: "attachment")
 ```
 
-## Custom endpoint
-
-If you want to have more control on download requests, you can use the
-`rack_response` plugin which this plugin uses internally.
-
 ## Plugin options
 
 | Name                | Description                                                                       | Default  |
@@ -171,3 +170,4 @@ If you want to have more control on download requests, you can use the
 | `:redirect`         | Whether to redirect to uploaded files on the storage                              | `false`  |
 
 [download_endpoint]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/download_endpoint.rb
+[rack_response]: https://shrinerb.com/docs/plugins/rack_response

data/doc/plugins/dynamic_storage.md

@@ -12,7 +12,7 @@ Example:
 plugin :dynamic_storage
 
 storage /store_(\w+)/ do |match|
-  Shrine::Storages::S3.new(bucket: match[1])
+  Shrine::Storage::S3.new(bucket: match[1])
 end
 ```
 

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

@@ -11,6 +11,15 @@ extension might not be known.
 plugin :infer_extension
 ```
 
+By default an extension will only be inferred if needed to supply an otherwise
+missing extension. But option `force: true` will normalize even an already
+present extension to the extension inferred from MIME type. This could be used
+to fix incorrect or malicious extensions on user-submitted files.
+
+```rb
+plugin :infer_extension, force: true
+```
+
 ## Inferrers
 
 By default, the [mini_mime] gem will be used for inferring the extension, but
@@ -70,7 +79,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 +90,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,6 @@ 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
+[model]: https://shrinerb.com/docs/plugins/model

data/doc/plugins/mirroring.md

@@ -50,7 +50,7 @@ Shrine.plugin :mirroring, mirror: { ... }, delete: false
 You can have mirroring performed in a background job:
 
 ```rb
-Shrine.mirror_upload_block do |file|
+Shrine.mirror_upload_block do |file, **options|
   MirrorUploadJob.perform_async(file.shrine_class.name, file.data)
 end
 

data/doc/plugins/persistence.md

@@ -6,6 +6,10 @@ This is an internal plugin that provides uniform persistence interface across
 different persistence plugins (e.g. [`activerecord`][activerecord],
 [`sequel`][sequel]).
 
+For these activerecord and sequel, atomic persistence is implemented in terms
+of database locks, eg "SELECT... FOR UPDATE". For more discussion of concurrency
+challenges, see the [atomic_helpers] documentation.
+
 ## Atomic promotion
 
 If you're promoting cached file to permanent storage
@@ -65,11 +69,15 @@ changed, and if it hasn't the attachment is persisted. If the attachment has
 changed, `Shrine::AttachmentChanged` exception is raised.
 
 If you want to execute code after the attachment change check but before
-persistence, you can pass a block:
+persistence, you can pass a block. For instance, one way to allow concurrent
+changes to metadata, perhaps in different background workers,  without
+overwriting each other might be:
 
 ```rb
 attacher.atomic_persist do |reloaded_attacher|
   # run code after attachment change check but before persistence
+  attacher.file.metadata.merge!(reloaded_attacher.file.metadata)
+  attacher.file.metadata["some_key"] = "changed_value"
 end
 ```
 
@@ -89,3 +97,5 @@ attacher.persist # saves the underlying record
 
 [activerecord]: https://shrinerb.com/docs/plugins/activerecord
 [sequel]: https://shrinerb.com/docs/plugins/sequel
+[atomic_helpers]: https://shrinerb.com/docs/plugins/atomic_helpers
+[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/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

@@ -72,6 +72,16 @@ Shrine.dimensions(io) #=> [300, 400] (calls the defined analyzer)
 Shrine.dimensions_analyzers[:fastimage].call(io) #=> [300, 400] (calls a built-in analyzer)
 ```
 
+### Disabling auto-extraction
+
+If you want to use the dimensions extraction methods but not automatically
+extract dimensions on upload, you can setup this plugin with the
+`auto_extraction: false` option.
+
+```rb
+plugin :store_dimensions, auto_extraction: false
+```
+
 ## Errors
 
 By default, any exceptions that the analyzer raises while extracting dimensions
@@ -110,7 +120,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 +131,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