shrine 3.1.0 → 3.4.0

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/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/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

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

@@ -72,3 +72,4 @@ photo.original_filename #=> "nature.jpg"
 
 [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/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/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,4 +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/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:

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

@@ -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/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

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

data/doc/plugins/upload_endpoint.md

@@ -113,7 +113,7 @@ upload happens independently of a database record.
 You can also customize the upload itself via the `:upload` option:
 
 ```rb
-plugin :upload_endpoint, upload: -> (io, **options, request) do
+plugin :upload_endpoint, upload: -> (io, options, request) do
   Shrine.upload(io, :cache, **options)
 end
 ```