shrine 2.19.3 → 3.6.0

data/doc/plugins/determine_mime_type.md

@@ -1,4 +1,6 @@
-# Determine MIME Type
+---
+title: Determine MIME Type
+---
 
 The [`determine_mime_type`][determine_mime_type] plugin allows you to determine
 and store the actual MIME type of the file analyzed from file content.
@@ -125,7 +127,7 @@ Or disable logging altogether:
 plugin :determine_mime_type, log_subscriber: nil
 ```
 
-[determine_mime_type]: /lib/shrine/plugins/determine_mime_type.rb
+[determine_mime_type]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/determine_mime_type.rb
 [file]: http://linux.die.net/man/1/file
 [Windows equivalent]: http://gnuwin32.sourceforge.net/packages/file.htm
 [ruby-filemagic]: https://github.com/blackwinter/ruby-filemagic

data/doc/plugins/download_endpoint.md

@@ -1,15 +1,19 @@
-# Download Endpoint
+---
+title: Download Endpoint
+---
 
 The [`download_endpoint`][download_endpoint] plugin provides a Rack app for
 downloading uploaded files from specified storages. This can be useful when
 files from your storage isn't accessible over URL (e.g. database storages) or
 if you want to authenticate your downloads.
 
+## Global Endpoint 
+
 You can configure the plugin with the path prefix which the endpoint will be
 mounted on.
 
 ```rb
-plugin :download_endpoint, prefix: "attachments"
+Shrine.plugin :download_endpoint, prefix: "attachments"
 ```
 
 The plugin adds a `Shrine.download_endpoint` method which returns a Rack
@@ -30,6 +34,62 @@ Links to the download endpoint are generated by calling
 ```rb
 uploaded_file.download_url #=> "/attachments/eyJpZCI6ImFkdzlyeTM..."
 ```
+## Endpoint via Uploader
+
+You can also configure the plugin in the uploader directly - just make sure to mount it via your Uploader-class.
+
+```rb
+class ImageUploader  < Shrine
+  plugin :download_endpoint, prefix: "images"
+end
+```
+
+```rb
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  # ...
+  mount ImageUploader.download_endpoint => "/images"
+end
+```
+
+*Hint: For shrine versions 2.x -> ensure that you don't include the plugin
+twice (globally and in your uploader class - see #408)*
+
+## Calling from a controller
+
+If you want to run additional code around the download (such as authentication),
+mounting the download endpoint in your router might be limiting. You can instead
+create a custom controller action and handle download requests there using
+`Shrine.download_response`:
+
+```rb
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  # ...
+  get "/attachments/*rest", to: "downloads#image"
+end
+```
+```rb
+# app/controllers/downloads_controller.rb (Rails)
+class DownloadsController < ApplicationController
+  def image
+    # ... we can perform authentication here ...
+    set_rack_response ImageUploader.download_response(request.env)
+  end
+
+  private
+
+  def set_rack_response((status, headers, body))
+    self.status = status
+    self.headers.merge!(headers)
+    self.response_body = body
+  end
+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
 
@@ -99,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  |
@@ -114,4 +169,5 @@ If you want to have more control on download requests, you can use the
 | `:prefix`           | Path prefix prepended to download URLs                                            | `nil`    |
 | `:redirect`         | Whether to redirect to uploaded files on the storage                              | `false`  |
 
-[download_endpoint]: /lib/shrine/plugins/download_endpoint.rb
+[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

@@ -1,4 +1,6 @@
-# Dynamic Storage
+---
+title: Dynamic Storage
+---
 
 The [`dynamic_storage`][dynamic_storage] plugin allows you to register a
 storage using a regex, and evaluate the storage class dynamically depending on
@@ -10,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
 ```
 
@@ -20,4 +22,4 @@ the bucket "foo". The block is yielded an instance of `MatchData`.
 
 This can be useful in combination with the `default_storage` plugin.
 
-[dynamic_storage]: /lib/shrine/plugins/dynamic_storage.rb
+[dynamic_storage]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/dynamic_storage.rb

data/doc/plugins/entity.md

@@ -0,0 +1,263 @@
+---
+title: Entity
+---
+
+The [`entity`][entity] plugin provides integration for handling attachments on
+immutable structs. It is built on top of the [`column`][column] plugin.
+
+```rb
+plugin :entity
+```
+
+## Attachment
+
+Including a `Shrine::Attachment` module into an entity class will add the
+following instance methods:
+
+* `#<name>` – returns the attached file
+* `#<name>_url` – returns the attached file URL
+* `#<name>_attacher` – returns a `Shrine::Attacher` instance
+
+These methods read attachment data from the `#<name>_data` attribute on the
+entity instance.
+
+```rb
+class Photo
+  attr_reader :image_data
+
+  include ImageUploader::Attachment(:image)
+end
+```
+```rb
+photo = Photo.new(image_data: '{"id":"...","storage":"...","metadata":{...}}')
+photo.image          #=> #<ImageUploader::UploadedFile>
+photo.image_url      #=> "https://example.com/image.jpg"
+photo.image_attacher #=> #<ImageUploader::Attacher>
+```
+
+#### `#<name>`
+
+Calls `Attacher#get`, which returns an `UploadedFile` object instantiated from
+attachment data.
+
+```rb
+photo = Photo.new(image_data: '{"id":"foo.jpg","storage":"store","metadata":{...}}')
+photo.image             #=> #<ImageUploader::UploadedFile>
+photo.image.id          #=> "foo.jpg"
+photo.image.storage_key #=> :store
+photo.image.metadata    #=> { ... }
+```
+
+If no file is attached, `nil` is returned.
+
+```rb
+photo = Photo.new(image_data: nil)
+photo.image #=> nil
+```
+
+#### `#<name>_url`
+
+Calls `Attacher#url`, which returns the URL to the attached file.
+
+```rb
+photo = Photo.new(image_data: {"id":"foo.jpg","storage":"...","metadata":{...}})
+photo.image_url #=> "https://example.com/foo.jpg"
+```
+
+If no file is attached, `nil` is returned.
+
+```rb
+photo = Photo.new(image_data: nil)
+photo.image_url #=> nil
+```
+
+#### `#<name>_attacher`
+
+Calls `Attacher.from_entity`, which returns an `Attacher` instance backed by
+the entity object.
+
+```rb
+photo = Photo.new
+photo.image_attacher           #=> #<ImageUploader::Attacher>
+photo.image_attacher.record    #=> #<Photo>
+photo.image_attacher.name      #=> :image
+photo.image_attacher.attribute #=> :image_data
+```
+
+Any additional options will be forwarded to `Attacher#initialize`.
+
+```rb
+photo    = Photo.new
+attacher = photo.image_attacher(cache: :other_cache)
+attacher.cache_key #=> :other_cache
+```
+
+You can also specify default attacher options when including
+`Shrine::Attachment`:
+
+```rb
+class Photo
+  attr_reader :image_data
+
+  include ImageUploader::Attachment(:image, store: :other_store)
+end
+```
+```rb
+photo    = Photo.new
+attacher = photo.image_attacher
+attacher.store_key #=> :other_store
+```
+
+You can retrieve an `Attacher` instance from the entity *class* as well. In
+this case it will not be initialized with any entity instance.
+
+```rb
+attacher = Photo.image_attacher
+attacher #=> #<ImageUploader::Attacher>
+attacher.record #=> nil
+attacher.name   #=> nil
+
+attacher = Photo.image_attacher(store: :other_store)
+attacher.store_key #=> :other_store
+```
+
+## Attacher
+
+You can also use `Shrine::Attacher` directly (with or without the
+`Shrine::Attachment` module):
+
+```rb
+class Photo
+  attr_reader :image_data
+end
+```
+```rb
+photo    = Photo.new(image_data: '{"id":"...","storage":"...","metadata":{...}}')
+attacher = ImageUploader::Attacher.from_entity(photo, :image)
+
+attacher.file #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:store ...>
+
+attacher.attach(file)
+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=:store ...>
+```
+
+### Loading entity
+
+The `Attacher.from_entity` method can be used for creating an `Attacher`
+instance backed by an entity object.
+
+```rb
+photo    = Photo.new(image_data: '{"id":"...","storage":"...","metadata":{...}}')
+attacher = ImageUploader::Attacher.from_entity(photo, :image)
+
+attacher.record    #=> #<Photo>
+attacher.name      #=> :image
+attacher.attribute #=> :image_data
+
+attacher.file #=> #<ImageUploader::UploadedFile>
+```
+
+Any additional options are forwarded to `Attacher#initialize`.
+
+```rb
+attacher = ImageUploader::Attacher.from_entity(photo, :image, cache: :other_cache)
+attacher.cache_key #=> :other_cache
+```
+
+You can also load an entity into an existing attacher with
+`Attacher#load_entity`.
+
+```rb
+photo = Photo.new(image_data: '{"id":"...","storage":"...","metadata":{...}}')
+
+attacher.load_entity(photo, :image)
+attacher.record #=> #<Photo>
+attacher.name   #=> :image
+attacher.file   #=> #<ImageUploader::UploadedFile>
+```
+
+Or just `Attacher#set_entity` if you don't want to load attachment data:
+
+```rb
+photo = Photo.new(image_data: '{"id":"...","storage":"...","metadata":{...}}')
+
+attacher.set_entity(photo, :image) # doesn't load attachment data
+attacher.record #=> #<Photo>
+attacher.name   #=> :image
+attacher.file   #=> nil
+```
+
+### Reloading
+
+The `Attacher#reload` method reloads attached file from the attachment data on
+the entity attribute and resets dirty tracking.
+
+```rb
+photo = Photo.new
+
+attacher = ImageUploader::Attacher.from_entity(photo, :image)
+attacher.file #=> nil
+
+photo.image_data = '{"id":"...","storage":"...","metadata":{...}}'
+
+attacher.file #=> nil
+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
+key and current attachment data as value.
+
+```rb
+attacher = ImageUploader::Attacher.from_entity(Photo.new, :image)
+attacher.attach(io)
+
+attacher.column_values #=> { :image_data => '{"id":"...","storage":"...","metadata":{...}}' }
+```
+
+The `Attacher#attribute` method returns just the entity attribute from which
+attached file data is read.
+
+```rb
+attacher = ImageUploader::Attacher.from_entity(Photo.new, :image)
+attacher.attribute #=> :image_data
+```
+
+### Entity data
+
+The `Attacher#record` method returns the entity instance from which the
+attacher was loaded.
+
+```rb
+attacher = ImageUploader::Attacher.from_entity(Photo.new, :image)
+attacher.record #=> #<Photo>
+```
+
+The `Attacher#name` method returns the name of the attachment from which the
+attacher was loaded.
+
+```rb
+attacher = ImageUploader::Attacher.from_entity(Photo.new, :image)
+attacher.name #=> :image
+```
+
+## Serialization
+
+By default, attachment data is serialized into JSON using the `JSON` standard
+library. If you want to change how data is serialized, see the
+[`column`][column serializer] plugin docs.
+
+[entity]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/entity.rb
+[column]: https://shrinerb.com/docs/plugins/column
+[column serializer]: https://shrinerb.com/docs/plugins/column#serializer

data/doc/plugins/form_assign.md

@@ -0,0 +1,55 @@
+---
+title: Form Assign
+---
+
+The [`form_assign`][form_assign] plugin allows attaching file from form params
+without a form object.
+
+```rb
+plugin :form_assign
+```
+
+The `Attacher#form_assign` method will detect the file param and assign it to
+the attacher:
+
+```rb
+attacher = photo.image_attacher
+attacher.form_assign({ "image" => file, "title" => "...", "description" => "..." })
+attacher.file #=> #<Shrine::UploadedFile>
+```
+
+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.file #=> #<Shrine::UploadedFile>
+```
+```rb
+# data_uri plugin
+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.file #=> nil
+```
+
+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" => "..." })
+#=> { :image => '{"id":"...","storage":"...","metadata":"..."}', "title" => "...", "description" => "..." }
+```
+
+You can also have attached file data returned as the `<name>_data` attribute,
+suitable for persisting.
+
+```rb
+attacher.form_assign({ "image" => image, ... }, result: :attributes)
+#=> { :image_data => '{"id":"...","storage":"...","metadata":"..."}', "title" => "...", "description" => "..." }
+```
+
+[form_assign]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/form_assign.rb

data/doc/plugins/included.md

@@ -1,18 +1,41 @@
-# Included
+---
+title: Included
+---
 
 The [`included`][included] plugin allows you to hook up to the `.included` hook
-of the attachment module, and call additional methods on the model which
+of the attachment module, and call additional methods on the model that
 includes it.
 
 ```rb
-plugin :included do |name|
-  before_save do
-    # ...
+class ImageUploader < Shrine
+  plugin :included do |name|
+    # called when attachment module is included into a model
+
+    self #=> Photo (the model class)
+    name #=> :image
   end
 end
 ```
+```rb
+class Photo
+  include ImageUploader::Attachment(:image) # triggers the included block
+end
+```
+
+For example, you can use it to define additional methods on the model:
 
-If you want to define additional methods on the model, it's recommended to use
-the `module_include` plugin instead.
+```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]: /lib/shrine/plugins/included.rb
+[included]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/included.rb

data/doc/plugins/infer_extension.md

@@ -1,4 +1,6 @@
-# Infer Extension
+---
+title: Infer Extension
+---
 
 The [`infer_extension`][infer_extension] plugin allows deducing the appropriate
 file extension for the upload location based on the MIME type of the file. This
@@ -9,21 +11,30 @@ 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 `MIME::Types` will be used for inferring the extension, but you can
-also choose a different inferrer:
+By default, the [mini_mime] gem will be used for inferring the extension, but
+you can also choose a different inferrer:
 
 ```rb
-plugin :infer_extension, inferrer: :mini_mime
+plugin :infer_extension, inferrer: :mime_types
 ```
 
 The following inferrers are accepted:
 
-| Name          | Description                                                                             |
-| :------------ | :-----------                                                                            |
-| `:mime_types` | (Default). Uses the [mime-types] gem to infer the appropriate extension from MIME type. |
-| `:mini_mime`  | Uses the [mini_mime] gem to infer the appropriate extension from MIME type.             |
+| Name          | Description                                                                            |
+| :------------ | :-----------                                                                           |
+| `:mini_mime`  | (Default). Uses the [mini_mime] gem to infer the appropriate extension from MIME type. |
+| `:mime_types` | Uses the [mime-types] gem to infer the appropriate extension from MIME type.           |
 
 You can also define your own inferrer, with the possibility to call the
 built-in inferrers:
@@ -31,7 +42,7 @@ built-in inferrers:
 ```rb
 plugin :infer_extension, inferrer: -> (mime_type, inferrers) do
   # don't add extension if the file is a text file
-  inferrers[:rack_mime].call(mime_type) unless mime_type == "text/plain"
+  inferrers[:mini_mime].call(mime_type) unless mime_type == "text/plain"
 end
 ```
 
@@ -89,6 +100,6 @@ Or disable logging altogether:
 plugin :infer_extension, log_subscriber: nil
 ```
 
-[infer_extension]: /lib/shrine/plugins/infer_extension.rb
+[infer_extension]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/infer_extension.rb
 [mime-types]: https://github.com/mime-types/ruby-mime-types
 [mini_mime]: https://github.com/discourse/mini_mime

data/doc/plugins/instrumentation.md

@@ -1,7 +1,9 @@
-# Instrumentation
+---
+title: Instrumentation
+---
 
-The [`instrumentation`][instrumentation] plugin sends events for various
-operations to a centralized notification component. In addition to that it
+The [`instrumentation`][instrumentation] plugin publishes events for various
+operations to a centralized notification component. In addition to that, it
 provides default logging for these events.
 
 ```rb
@@ -40,6 +42,13 @@ Download (1002ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1
 Delete (700ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}
 ```
 
+It uses `Shrine.logger` for logging, which allows you to change where and how
+are the logs going to be written:
+
+```rb
+Shrine.logger = Rails.logger # in Rails apps
+```
+
 You can choose to log only certain events, e.g. we can exclude metadata
 extraction:
 
@@ -79,6 +88,7 @@ The following events are instrumented by the `instrumentation` plugin:
 
 * [`upload.shrine`](#uploadshrine)
 * [`download.shrine`](#downloadshrine)
+* [`open.shrine`](#openshrine)
 * [`exists.shrine`](#existsshrine)
 * [`delete.shrine`](#deleteshrine)
 * [`metadata.shrine`](#metadatashrine)
@@ -94,21 +104,33 @@ following payload:
 | `:location`       | The location of the uploaded file      |
 | `:io`             | The uploaded IO object                 |
 | `:upload_options` | Any upload options that were specified |
-| `:options`        | Some additional context information    |
+| `:metadata`       | Metadata extracted during upload       |
+| `:options`        | Any additional uploader options        |
 | `:uploader`       | The uploader class that sent the event |
 
 ### download.shrine
 
-The `download.shrine` event is logged on `UploadedFile#open` (which includes
-`UploadedFile#download` and `UploadedFile#stream` methods as well), and
-contains the following payload:
+The `download.shrine` event is logged on `UploadedFile#stream` (which includes
+`UploadedFile#download`), and contains the following payload:
 
-| Key               | Description                            |
-| :--               | :----                                  |
-| `:storage`        | The storage identifier                 |
-| `:location`       | The location of the uploaded file      |
-| `:download_options` | Any upload options that were specified |
-| `:uploader`       | The uploader class that sent the event |
+| Key                 | Description                              |
+| :--                 | :----                                    |
+| `:storage`          | The storage identifier                   |
+| `:location`         | The location of the uploaded file        |
+| `:download_options` | Any download options that were specified |
+| `:uploader`         | The uploader class that sent the event   |
+
+### open.shrine
+
+The `download.shrine` event is logged on `UploadedFile#open` or when uploaded
+file is implicitly opened on calling an IO method.
+
+| Key                 | Description                              |
+| :--                 | :----                                    |
+| `:storage`          | The storage identifier                   |
+| `:location`         | The location of the uploaded file        |
+| `:download_options` | Any download options that were specified |
+| `:uploader`         | The uploader class that sent the event   |
 
 ### exists.shrine
 
@@ -141,7 +163,7 @@ following payload:
 | :--               | :----                                  |
 | `:storage`        | The storage identifier                 |
 | `:io`             | The uploaded IO object                 |
-| `:options`        | Some additional context information    |
+| `:options`        | Any options sent to the uploader       |
 | `:uploader`       | The uploader class that sent the event |
 
 ## API
@@ -151,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
 ```
@@ -165,6 +187,6 @@ Shrine.subscribe(:my_event) do |event|
 end
 ```
 
-[instrumentation]: /lib/shrine/plugins/instrumentation.rb
+[instrumentation]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/instrumentation.rb
 [ActiveSupport::Notifications]: https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html
 [dry-monitor]: https://github.com/dry-rb/dry-monitor