shrine 2.19.4 → 3.0.0.alpha

data/doc/plugins/column.md

@@ -0,0 +1,90 @@
+# Column
+
+The [`column`][column] plugin provides interface for serializing and
+deserializing attachment data in format suitable for persisting in a database
+column (JSON by default).
+
+```rb
+plugin :column
+```
+
+## Serializing
+
+The `Attacher#column_data` method returns attached file data in serialized
+format, ready to be persisted into a database column.
+
+```rb
+attacher.attach(io)
+attacher.column_data #=> '{"id":"...","storage":"...","metadata":{...}}'
+```
+
+If there is no attached file, `nil` is returned.
+
+```rb
+attacher.column_data #=> nil
+```
+
+If you want to retrieve this data as a Hash, use `Attacher#data` instead.
+
+## Deserializing
+
+The `Attacher.from_column` method instantiates the attacher from serialized
+attached file data.
+
+```rb
+attacher = Shrine::Attacher.from_column('{"id":"...","storage":"...","metadata":{...}}')
+attacher.file #=> #<Shrine::UploadedFile>
+```
+
+If `nil` is given, it means no attached file.
+
+```rb
+attacher = Shrine::Attacher.from_column(nil)
+attacher.file #=> nil
+```
+
+Any additional options are forwarded to `Attacher#initialize`.
+
+```rb
+attacher = Shrine::Attacher.from_column('{...}', store: :other_store)
+attacher.store_key #=> :other_store
+```
+
+If you want to load attachment data into an existing attacher, use
+`Attacher#load_column`.
+
+```rb
+attacher.file #=> nil
+attacher.load_column('{"id":"...","storage":"...","metadata":{...}}')
+attacher.file #=> #<Shrine::UploadedFile>
+```
+
+If you want to load attachment from a Hash, use `Attacher.from_data` or
+`Attacher#load_data` instead.
+
+## Serializer
+
+By default the `JSON` standard library is used as the serializer, but you can
+use your own serializer. The serializer object needs to implement `#dump` and
+`#load` methods.
+
+```rb
+require "oj"
+
+plugin :column, serializer: Oj # use custom serializer
+```
+
+If you want to disable serialization, you can set serializer to `nil`.
+
+```rb
+plugin :column, serializer: nil # disable serialization
+```
+
+You can also change the serializer on the attacher level:
+
+```rb
+Shrine::Attacher.new(column_serializer: Oj)  # use custom serializer
+Shrine::Attacher.new(column_serializer: nil) # disable serialization
+```
+
+[column]: /lib/shrine/plugins/column.rb

data/doc/plugins/derivation_endpoint.md

@@ -76,7 +76,7 @@ Now we can generate "derivation" URLs from attached files, which on request
 will call the derivation block we defined.
 
 ```rb
-photo.image.derivation_url(:thumbnail, "600", "400")
+photo.image.derivation_url(:thumbnail, 600, 400)
 #=> "/derivations/image/thumbnail/600/400/eyJpZCI6ImZvbyIsInN0b3JhZ2UiOiJzdG9yZSJ9?signature=..."
 ```
 
@@ -102,10 +102,14 @@ derivation URLs, preventing potential DoS attacks.
 
 The derivation endpoint then extracts the source file data, derivation name and
 arguments from the request URL, and calls the corresponding derivation block,
-passing the downloaded source file and derivation arguments.
+passing the downloaded source file and derivation arguments. The derivation
+block is evaluated within the context of a
+[`Shrine::Derivation`](#derivation-api) instance.
 
 ```rb
 derivation :thumbnail do |file, arg1, arg2, ...|
+  self #=> #<Shrine::Derivation>
+
   file #=> #<Tempfile:...> (source file downloaded to disk)
   arg1 #=> "600" (first derivation argument in #derivation_url)
   arg2 #=> "400" (second derivation argument in #derivation_url)
@@ -494,11 +498,9 @@ sense.
 
 ### Deleting derivatives
 
-When you use the `:upload` options and upload the derivatives to storage, there
-will come a time when you need to delete the derivatives because the original
-file is being replaced, deleted, or some other reason. In this case, you can
-delete the derivatives before deleting the record or updating the record with
-the new original file.
+When the original attachment is deleted, its uploaded derivatives will not be
+automatically deleted, you will need to do the deletion manually. You can do
+that by calling `Shrine::Derivation#delete` for each derivation you're using:
 
 ```rb
 # photo is the model and image is the file attachment
@@ -538,50 +540,38 @@ uploaded_file.derivation_url(:thumbnail, version: 1)
 
 ## Accessing source file
 
-If you want to access the source `UploadedFile` object when deriving, you can
-set `:include_uploaded_file` to `true`.
+Inside the derivation block we can access the source `UploadedFile` object via
+`Shrine::Derivation#source`:
 
 ```rb
-plugin :derivation_endpoint, include_uploaded_file: true
-```
-
-Now the source `UploadedFile` will be passed as the second argument of the
-derivation block:
-
-```rb
-derivation :thumbnail do |file, uploaded_file, width, height|
-  uploaded_file             #=> #<Shrine::UploadedFile>
-  uploaded_file.id          #=> "9a7d1bfdad24a76f9cfaff137fe1b5c7.jpg"
-  uploaded_file.storage_key #=> "store"
-  uploaded_file.metadata    #=> {}
+derivation :thumbnail do |file, width, height|
+  source             #=> #<Shrine::UploadedFile>
+  source.id          #=> "9a7d1bfdad24a76f9cfaff137fe1b5c7.jpg"
+  source.storage_key #=> :store
+  source.metadata    #=> {}
 
   # ...
 end
 ```
 
-By default original metadata that were extracted on attachment won't be
-available in the derivation block. This is because metadata we want to have
-available would need to be serialized into the derivation URL, which would make
-it longer. However, you can opt in for the metadata you need with the
-`:metadata` option:
+By default, when using the derivation endpoint, original metadata of the source
+file won't be available in the derivation block. This is because any metadata
+we would want to have available would need to be serialized into the derivation
+URL, which would make it longer. Instead, you can opt in for the metadata you
+want to have available:
 
 ```rb
 plugin :derivation_endpoint, metadata: ["filename", "mime_type"]
-```
-
-Now `filename` and `mime_type` metadata values will be available in the
-derivation block:
 
-```rb
-derivation :thumbnail do |file, uploaded_file, width, height|
-  uploaded_file.metadata #=>
+derivation :thumbnail do |file, width, height|
+  source.metadata #=>
   # {
   #  "filename" => "nature.jpg",
   #  "mime_type" => "image/jpeg"
   # }
 
-  uploaded_file.original_filename #=> "nature.jpg"
-  uploaded_file.mime_type         #=> "image/jpeg"
+  source.original_filename #=> "nature.jpg"
+  source.mime_type         #=> "image/jpeg"
 
   # ...
 end
@@ -602,17 +592,9 @@ plugin :derivation_endpoint, download_options: {
 }
 ```
 
-If the source file has been deleted, the error the storage raises when
-attempting to download it will be propagated by default. For
-`Shrine.derivation_endpoint` and `Shrine.derivation_response` you can have
-these errors converted to 404 responses by adding them to `:download_errors`:
-
-```rb
-plugin :derivation_endpoint, download_errors: [
-  Errno::ENOENT,             # raised by Shrine::Storage::FileSystem
-  Aws::S3::Errors::NotFound, # raised by Shrine::Storage::S3
-]
-```
+If the source file was not found, `Shrine::Derivation::SourceNotFound`
+exception is raised. In a derivation response this is converted into a `404 Not
+Found` response.
 
 ### Skipping download
 
@@ -621,15 +603,8 @@ disk for you, you can set `:download` to `false`.
 
 ```rb
 plugin :derivation_endpoint, download: false
-```
-
-In this case the `UploadedFile` object is yielded to the derivation block
-instead of the raw file:
-
-```rb
-derivation :thumbnail do |uploaded_file, width, height|
-  uploaded_file #=> #<Shrine::UploadedFile>
 
+derivation :thumbnail do |width, height| # source file is not downloaded
   # ...
 end
 ```
@@ -639,10 +614,10 @@ One use case for this is delegating processing to a 3rd-party service:
 ```rb
 require "down/http"
 
-derivation :thumbnail do |uploaded_file, width, height|
+derivation :thumbnail do |width, height|
   # generate the thumbnail using ImageOptim.com
   down = Down::Http.new(method: :post)
-  down.download("https://im2.io/<USERNAME>/#{width}x#{height}/#{uploaded_file.url}")
+  down.download("https://im2.io/<USERNAME>/#{width}x#{height}/#{source.url}")
 end
 ```
 
@@ -735,13 +710,20 @@ uploaded_file    #=> #<Shrine::UploadedFile>
 uploaded_file.id #=> "bcfd0d67e4a8ec2dc9a6d7ddcf3825a1/thumbnail-500-500"
 ```
 
-If not given any arguments, it generates the derivative before uploading it.
+It can also be called without arguments, in which case it will generate a new
+derivative and upload it.
+
+```rb
+derivation.upload # generates derivative and uploads it
+```
+
+Any additional options will be passed to the uploader.
 
 ### `#retrieve`
 
-`Derivation#retrieve` method returns the uploaded derivative file. If the file
-exists on the storage, it returns an `UploadedFile` object, otherwise `nil` is
-returned.
+`Derivation#retrieve` method returns `Shrine::UploadedFile` object pointing to
+the uploaded derivative if it exists. If the uploaded derivative does not
+exist, `nil` is returned.
 
 ```rb
 uploaded_file = derivation.retrieve
@@ -749,6 +731,18 @@ uploaded_file    #=> #<Shrine::UploadedFile>
 uploaded_file.id #=> "bcfd0d67e4a8ec2dc9a6d7ddcf3825a1/thumbnail-500-500"
 ```
 
+### `#opened`
+
+`Derivation#opened` method returns opened `Shrine::UploadedFile` object pointing
+to the uploaded derivative if it exists. If the uploaded derivative does not
+exist, `nil` is returned.
+
+```rb
+uploaded_file = derivation.opened
+uploaded_file    #=> #<Shrine::UploadedFile>
+uploaded_file.id #=> "bcfd0d67e4a8ec2dc9a6d7ddcf3825a1/thumbnail-500-500"
+```
+
 ### `#delete`
 
 `Derivation#delete` method deletes the uploaded derivative file from the
@@ -774,12 +768,10 @@ derivation.option(:upload_location)
 | `:cache_control`               | Hash of directives for the `Cache-Control` response header                                                                            | `{ public: true, max_age: 365*24*60*60 }`            |
 | `:disposition`                 | Whether the browser should attempt to render the derivative (`inline`) or prompt the user to download the file to disk (`attachment`) | `inline`                                             |
 | `:download`                    | Whether the source uploaded file should be downloaded to disk when the derivation block is called                                     | `true`                                               |
-| `:download_errors`             | List of error classes that will be converted to a `404 Not Found` response by the derivation endpoint                                 | `[]`                                                 |
 | `:download_options`            | Additional options to pass when downloading the source uploaded file                                                                  | `{}`                                                 |
 | `:expires_in`                  | Number of seconds after which the URL will not be available anymore                                                                   | `nil`                                                |
 | `:filename`                    | Filename the browser will assume when the derivative is downloaded to disk                                                            | `<name>-<args>-<source id basename>`                 |
 | `:host`                        | URL host to use when generated URLs                                                                                                   | `nil`                                                |
-| `:include_uploaded_file`       | Whether to include the source uploaded file in the derivation block arguments                                                         | `false`                                              |
 | `:metadata`                    | List of metadata keys the source uploaded file should include in the derivation block                                                 | `[]`                                                 |
 | `:prefix`                      | Path prefix added to the URLs                                                                                                         | `nil`                                                |
 | `:secret_key`                  | Key used to sign derivation URLs in order to prevent tampering                                                                        | required                                             |

data/doc/plugins/derivatives.md

@@ -0,0 +1,752 @@
+# Derivatives
+
+The derivatives plugin allows storing processed files ("derivatives") alongside
+the main attached file. The processed file data will be saved together with the
+main attachment data in the same record attribute.
+
+```rb
+plugin :derivatives
+```
+
+## Contents
+
+* [API overview](#api-overview)
+* [Creating derivatives](#creating-derivatives)
+  - [Nesting derivatives](#nesting-derivatives)
+* [Retrieving derivatives](#retrieving-derivatives)
+* [Derivative URL](#derivative-url)
+* [Processing derivatives](#processing-derivatives)
+  - [Dynamic processing](#dynamic-processing)
+  - [Source file](#source-file)
+* [Adding derivatives](#adding-derivatives)
+* [Uploading derivatives](#uploading-derivatives)
+  - [Derivatives storage](#derivatives-storage)
+  - [Uploader options](#uploader-options)
+  - [File deletion](#file-deletion)
+* [Merging derivatives](#merging-derivatives)
+  - [Setting derivatives](#setting-derivatives)
+* [Promoting derivatives](#promoting-derivatives)
+* [Removing derivatives](#removing-derivatives)
+  * [Deleting derivatives](#deleting-derivatives)
+* [Miscellaneous](#miscellaneous)
+  * [Without original](#without-original)
+  * [Iterating derivatives](#iterating-derivatives)
+  * [Parsing derivatives](#parsing-derivatives)
+* [Instrumentation](#instrumentation)
+
+## API overview
+
+The interface for managing derivatives is implemented on the `Shrine::Attacher`
+class, and it's layered in the following way:
+
+* [`Attacher#create_derivatives`](#creating-derivatives) – processes, uploads and merges derivatives
+  * [`Attacher#process_derivatives`](#processing-derivatives) – processes derivatives
+  * [`Attacher#add_derivatives`](#adding-derivatives) – uploads and merges derivatives
+    * [`Attacher#upload_derivatives`](#uploading-derivatives) – uploads derivatives
+    * [`Attacher#merge_derivatives`](#merging-derivatives) – merges derivatives
+      * [`Attacher#set_derivatives`](#setting-derivatives) – overrides derivatives
+
+## Creating derivatives
+
+When you have a file attached, you can generate derivatives from it and save
+them alongside the attached file. The simplest way to do this is to define a
+processor which returns the processed files, and then trigger it with
+`Attacher#create_derivatives` when you want to generate the derivatives.
+
+Here is an example of generating image thumbnails:
+
+```rb
+# Gemfile
+gem "image_processing", "~> 1.2"
+```
+```rb
+require "image_processing/mini_magick"
+
+class ImageUploader < Shrine
+  plugin :derivatives
+
+  Attacher.derivatives_processor :thumbnails do |original|
+    processor = ImageProcessing::MiniMagick.source(original)
+
+    {
+      small:  processor.resize_to_limit!(300, 300),
+      medium: processor.resize_to_limit!(500, 500),
+      large:  processor.resize_to_limit!(800, 800),
+    }
+  end
+end
+```
+```rb
+class Photo < Model(:image_data)
+  include ImageUploader::Attachment(:image)
+end
+```
+```rb
+photo.image #=> #<Shrine::UploadedFile @id="original.jpg" @storage_key=:store ...>
+photo.image_derivatives #=> {}
+
+photo.image_attacher.create_derivatives(:thumbnails) # calls processor and uploads results
+photo.image_derivatives #=>
+# {
+#   small:  #<Shrine::UploadedFile @id="small.jpg" @storage_key=:store ...>,
+#   medium: #<Shrine::UploadedFile @id="medium.jpg" @storage_key=:store ...>,
+#   large:  #<Shrine::UploadedFile @id="large.jpg" @storage_key=:store ...>,
+# }
+```
+
+The derivatives data is stored in the `#<name>_data` record attribute alongside
+the main file data:
+
+```rb
+photo.image_data #=>
+# {
+#   "id": "original.jpg",
+#   "store": "store",
+#   "metadata": { ... },
+#   "derivatives": {
+#     "small": { "id": "small.jpg", "storage": "store", "metadata": { ... } },
+#     "medium": { "id": "medium.jpg", "storage": "store", "metadata": { ... } },
+#     "large": { "id": "large.jpg", "storage": "store", "metadata": { ... } },
+#   }
+# }
+```
+
+Any additional options passed to `Attacher#create_derivatives` are forwarded to
+[`Attacher#upload_derivatives`](#uploading-derivatives).
+
+```rb
+attacher.create_derivatives(:thumbnails, storage: :other_store)                  # specify destination storage
+attacher.create_derivatives(:thumbnails, upload_options: { acl: "public-read" }) # pass uploader options
+```
+
+### Nesting derivatives
+
+Derivatives can be nested to any level, using both hashes and arrays, but the
+top-level object must be a hash.
+
+```rb
+Attacher.derivatives_processor :tiff do |original|
+  {
+    thumbnail: {
+      small:  small,
+      medium: medium,
+      large:  large,
+    },
+    layers: [
+      layer_1,
+      layer_2,
+      # ...
+    ]
+  }
+end
+```
+
+## Retrieving derivatives
+
+If you're using the `Shrine::Attachment` module, you can retrieve stored
+derivatives by calling `#<name>_derivatives` on your model/entity.
+
+```rb
+class Photo < Model(:image_data)
+  include ImageUploader::Attachment(:image)
+end
+```
+```rb
+photo.image_derivatives #=>
+# {
+#   small:  #<Shrine::UploadedFile>,
+#   medium: #<Shrine::UploadedFile>,
+#   large:  #<Shrine::UploadedFile>,
+# }
+```
+
+A specific derivative can be retrieved in any of the following ways:
+
+```rb
+photo.image_derivatives[:small] #=> #<Shrine::UploadedFile>
+photo.image_derivatives(:small) #=> #<Shrine::UploadedFile>
+photo.image(:small)             #=> #<Shrine::UploadedFile>
+```
+
+And with nested derivatives:
+
+```rb
+photo.image_derivatives #=> { thumbnail: { small: ..., medium: ..., large: ... } }
+
+photo.image_derivatives.dig(:thumbnail, :small) #=> #<Shrine::UploadedFile>
+photo.image_derivatives(:thumbnail, :small)     #=> #<Shrine::UploadedFile>
+photo.image(:thumbnails :small)                 #=> #<Shrine::UploadedFile>
+```
+
+When using `Shrine::Attacher` directly, you can retrieve derivatives using
+`Attacher#derivatives`:
+
+```rb
+attacher.derivatives #=>
+# {
+#   small:  #<Shrine::UploadedFile>,
+#   medium: #<Shrine::UploadedFile>,
+#   large:  #<Shrine::UploadedFile>,
+# }
+```
+
+## Derivative URL
+
+If you're using the `Shrine::Attachment` module, you can use the `#<name>_url`
+method to retrieve the URL of a derivative.
+
+```rb
+class Photo < Model(:image_data)
+  include ImageUploader::Attachment(:image)
+end
+```
+```rb
+photo.image_url(:small)  #=> "https://example.com/small.jpg"
+photo.image_url(:medium) #=> "https://example.com/medium.jpg"
+photo.image_url(:large)  #=> "https://example.com/large.jpg"
+```
+
+For nested derivatives you can pass multiple keys:
+
+```rb
+photo.image_derivatives #=> { thumbnail: { small: ..., medium: ..., large: ... } }
+
+photo.image_url(:thumbnail, :medium) #=> "https://example.com/medium.jpg"
+```
+
+By default, `#<name>_url` method will return `nil` if derivative is not found.
+You can use the [`default_url`][default_url] plugin to set up URL fallbacks:
+
+```rb
+Attacher.default_url do |derivative: nil, **|
+  "https://fallbacks.com/#{derivative}.jpg" if derivative
+end
+```
+```rb
+photo.image_url(:medium) #=> "https://example.com/fallbacks.com/medium.jpg"
+```
+
+Any additional URL options passed to `#<name>_url` will be forwarded to the
+storage:
+
+```rb
+photo.image_url(:small, response_content_disposition: "attachment")
+```
+
+You can also retrieve the derivative URL via `UploadedFile#url`:
+
+```rb
+photo.image_derivatives[:large].url
+# or
+attacher.derivatives[:large].url
+```
+
+## Processing derivatives
+
+A derivatives processor block takes the original file, and is expected to
+return a hash of processed files (it can be [nested](#nesting-derivatives)).
+
+```rb
+Attacher.derivatives_processor :my_processor do |original|
+  # return a hash of processed files
+end
+```
+
+The [`Attacher#create_derivatives`](#creating-derivatives) method will call
+the processor and upload results.
+
+```rb
+attacher.create_derivatives(:my_processor)
+```
+
+Internally this calls `Attacher#process_derivatives`, which calls the
+processor and returns processed files:
+
+```rb
+files = attacher.process_derivatives(:my_processor)
+attacher.add_derivatives(files)
+```
+
+### Dynamic processing
+
+The processor block is evaluated in context of the `Shrine::Attacher` instance,
+which allows you to change your processing logic based on the record data.
+
+```rb
+Attacher.derivatives_processor :my_processor do |original|
+  self    #=> #<Shrine::Attacher>
+
+  record  #=> #<Photo>
+  name    #=> :image
+  context #=> { ... }
+
+  # ...
+end
+```
+
+Moreover, any options passed to `Attacher#process_derivatives` will be
+forwarded to the processor:
+
+```rb
+attacher.process_derivatives(:my_processor, foo: "bar")
+```
+```rb
+Attacher.derivatives_processor :my_processor do |original, **options|
+  options #=> { :foo => "bar" }
+  # ...
+end
+```
+
+### Source file
+
+The `Attacher#process_derivatives` method will automatically download the
+attached file and pass it to the processor:
+
+```rb
+Attacher.derivatives_processor :my_processor do |original|
+  original #=> #<File:...>
+  # ...
+end
+```
+```rb
+attacher.process_derivatives(:my_processor) # downloads attached file and passes it to the processor
+```
+
+If you already have the source file locally, or if you're calling multiple
+processors in a row and want to avoid downloading the same source file each
+time, you can pass the source file as the second argument to
+`Attacher#process_derivatives`:
+
+```rb
+# this way the source file is downloaded only once
+attacher.file.download do |original|
+  attacher.process_derivatives(:thumbnails, original)
+  attacher.process_derivatives(:colors,     original)
+end
+```
+
+## Adding derivatives
+
+If you already have processed files that you want to save, you can do that with
+`Attacher#add_derivatives`:
+
+```rb
+attacher.add_derivatives(
+  one: file_1,
+  two: file_2,
+  # ...
+)
+
+attacher.derivatives #=>
+# {
+#   one: #<Shrine::UploadedFile>,
+#   two: #<Shrine::UploadedFile>,
+#   ...
+# }
+```
+
+New derivatives will be merged with existing ones:
+
+```rb
+attacher.derivatives #=> { one: #<Shrine::UploadedFile> }
+attacher.add_derivatives(two: two_file)
+attacher.derivatives #=> { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile> }
+```
+
+The merging is deep, so the following will work as well:
+
+```rb
+attacher.derivatives #=> { nested: { one: #<Shrine::UploadedFile> } }
+attacher.add_derivatives(nested: { two: two_file })
+attacher.derivatives #=> { nested: { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile> } }
+```
+
+For adding a single derivative, you can also use the singular
+`Attacher#add_derivative`:
+
+```rb
+attacher.add_derivative(:thumb, thumbnail_file)
+```
+
+Any options passed to `Attacher#add_derivative(s)` will be forwarded to
+[`Attacher#upload_derivatives`](#uploading-derivatives).
+
+```rb
+attacher.add_derivative(:thumb, thumbnail_file, storage: :thumbnails_store)             # specify destination storage
+attacher.add_derivative(:thumb, thumbnail_file, upload_options: { acl: "public-read" }) # pass uploader options
+```
+
+The `Attacher#add_derivative(s)` methods are thread-safe.
+
+## Uploading derivatives
+
+If you want to upload processed files without setting them, you can use
+`Attacher#upload_derivatives`:
+
+```rb
+derivatives = attacher.upload_derivatives(
+  one: file_1,
+  two: file_2,
+  # ...
+)
+
+derivatives #=>
+# {
+#   one: #<Shrine::UploadedFile>,
+#   two: #<Shrine::UploadedFile>,
+#   ...
+# }
+```
+
+For uploading a single derivative, you can also use the singular
+`Attacher#upload_derivative`:
+
+```rb
+attacher.upload_derivative(:thumb, thumbnail_file)
+#=> #<Shrine::UploadedFile>
+```
+
+### Derivatives storage
+
+By default, derivatives are uploaded to the permanent storage of the attacher
+(`:store` by default). You can specify a different destination storage for
+`Attacher#upload_derivative(s)` with the `:storage` option:
+
+```rb
+attacher.upload_derivatives(derivatives, storage: :other_store)
+```
+
+You can also set a default derivatives storage on the plugin level:
+
+```rb
+plugin :derivatives, storage: :other_store
+```
+
+The storage can be dynamic based on the derivative name:
+
+```rb
+plugin :derivatives, storage: -> (derivative) do
+  if derivative == :thumb
+    :thumbnail_store
+  else
+    :store
+  end
+end
+```
+
+You can also set this option with `Attacher.derivatives_storage`:
+
+```rb
+Attacher.derivatives_storage :other_store
+# or
+Attacher.derivatives_storage do |derivative|
+  if derivative == :thumb
+    :thumbnail_store
+  else
+    :store
+  end
+end
+```
+
+The storage block is evaluated in the context of a `Shrine::Attacher` instance:
+
+```rb
+Attacher.derivatives_storage do |derivative|
+  self   #=> #<Shrine::Attacher>
+
+  record  #=> #<Photo>
+  name    #=> :image
+  context #=> { ... }
+end
+```
+
+### Uploader options
+
+Any options other than `:storage` will be forwarded to the uploader:
+
+```rb
+attacher.upload_derivative :thumb, thumbnail_file,
+  upload_options: { acl: "public-read" },
+  metadata: { "foo" => "bar" }),
+  location: "path/to/derivative"
+```
+
+A `:derivative` option is automatically passed to the uploader and holds the
+name of the derivative, which you can use when extracting metadata, generating
+location or generating upload options:
+
+```rb
+class MyUploader < Shrine
+  plugin :add_metadata
+
+  add_metadata :md5 do |io, derivative: nil, **|
+    calculate_signature(io, :md5) unless derivative
+  end
+
+  def generate_location(io, derivative: nil, **)
+    "location/for/#{derivative}"
+  end
+
+  plugin :upload_options, store: -> (io, derivative: nil, **) {
+    { acl: "public-read" } if derivative
+  }
+end
+```
+
+### File deletion
+
+Files given to `Attacher#upload_derivative(s)` are assumed to be temporary, so
+for convenience they're automatically closed and unlinked after upload.
+
+If you want to disable this behaviour, pass `delete: false`:
+
+```rb
+attacher.upload_derivative(:thumb, thumbnail_file, delete: false)
+
+File.exist?(thumbnail_file.path) #=> true
+```
+
+## Merging derivatives
+
+If you want to save already uploaded derivatives, you can use
+`Attacher#merge_derivatives`:
+
+```rb
+attacher.derivatives #=> { one: #<Shrine::UploadedFile> }
+attacher.merge_derivatives attacher.upload_derivatives(two: two_file)
+attacher.derivatives #=> { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile> }
+```
+
+This does a deep merge, so the following will work as well:
+
+```rb
+attacher.derivatives #=> { nested: { one: #<Shrine::UploadedFile> } }
+attacher.merge_derivatives attacher.upload_derivatives(nested: { two: two_file })
+attacher.derivatives #=> { nested: { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile> } }
+```
+
+The `Attacher#merge_derivatives` method is thread-safe.
+
+### Setting derivatives
+
+If instead of adding you want to *override* existing derivatives, you can use
+`Attacher#set_derivatives`:
+
+```rb
+attacher.derivatives #=> { one: #<Shrine::UploadedFile> }
+attacher.set_derivatives attacher.upload_derivatives(two: two_file)
+attacher.derivatives #=> { two: #<Shrine::UploadedFile> }
+```
+
+If you're using the [`model`][model] plugin, this method will trigger writing
+derivatives data into the column attribute.
+
+## Promoting derivatives
+
+Any assigned derivatives that are uploaded to temporary storage will be
+automatically uploaded to permanent storage on `Attacher#promote`.
+
+```rb
+attacher.derivatives[:one].storage_key #=> :cache
+attacher.promote
+attacher.derivatives[:one].storage_key #=> :store
+```
+
+If you want more control over derivatives promotion, you can use
+`Attacher#promote_derivatives`. Any additional options passed to it are
+forwarded to the uploader.
+
+```rb
+attacher.derivatives[:one].storage_key #=> :cache
+attacher.promote_derivatives(upload_options: { acl: "public-read" })
+attacher.derivatives[:one].storage_key #=> :store
+```
+
+## Removing derivatives
+
+If you want to manually remove certain derivatives, you can do that with
+`Attacher#remove_derivative`.
+
+```rb
+attacher.derivatives #=> { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile> }
+attacher.remove_derivative(:two) #=> #<Shrine::UploadedFile> (removed derivative)
+attacher.derivatives #=> { one: #<Shrine::UploadedFile> }
+```
+
+You can also use the plural `Attacher#remove_derivatives` for removing multiple
+derivatives:
+
+```rb
+attacher.derivatives #=> { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile>, three: #<Shrine::UploadedFile> }
+attacher.remove_derivative(:two, :three) #=> [#<Shrine::UploadedFile>, #<Shrine::UploadedFile>] (removed derivatives)
+attacher.derivatives #=> { one: #<Shrine::UploadedFile> }
+```
+
+It's possible to remove nested derivatives as well:
+
+```rb
+attacher.derivatives #=> { nested: { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile> } }
+attacher.remove_derivative([:nested, :one]) #=> #<Shrine::UploadedFile> (removed derivative)
+attacher.derivatives #=> { nested: { one: #<Shrine::UploadedFile> } }
+```
+
+The removed derivatives are not automatically deleted, because it's safer to
+first persist the removal change, and only then perform the deletion.
+
+```rb
+derivative = attacher.remove_derivative(:two)
+# ... persist removal change ...
+derivative.delete
+```
+
+If you still want to delete the derivative at the time of removal, you can
+pass `delete: true`:
+
+```rb
+derivative = attacher.remove_derivative(:two, delete: true)
+derivative.exists? #=> false
+```
+
+### Deleting derivatives
+
+If you want to delete a collection of derivatives, you can use
+`Attacher#delete_derivatives`:
+
+```rb
+derivatives #=> { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile> }
+
+attacher.delete_derivatives(derivatives)
+
+derivatives[:one].exists? #=> false
+derivatives[:two].exists? #=> false
+```
+
+Without arguments `Attacher#delete_derivatives` deletes current derivatives:
+
+```rb
+attacher.derivatives #=> { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile> }
+
+attacher.delete_derivatives
+
+attacher.derivatives[:one].exists? #=> false
+attacher.derivatives[:two].exists? #=> false
+```
+
+Derivatives are automatically deleted on `Attacher#destroy`.
+
+## Without original
+
+You can store derivatives even if there is no main attached file:
+
+```rb
+attacher.file #=> nil
+attacher.add_derivatives(one: one_file, two: two_file)
+attacher.data #=>
+# {
+#   "derivatives" => {
+#     "one" => { "id" => "...", "storage" => "...", "metadata": { ... } },
+#     "two" => { "id" => "...", "storage" => "...", "metadata": { ... } },
+#   }
+# }
+```
+
+However, note that in this case operations such as promotion and deletion will
+not be automatically triggered in the attachment flow, you'd need to trigger
+them manually as needed.
+
+## Iterating derivatives
+
+If you want to iterate over a nested hash of derivatives (which can be
+`Shrine::UploadedFile` objects or raw files), you can use
+`Attacher#map_derivative` or `Shrine.map_derivative`:
+
+```rb
+derivatives #=>
+# {
+#   one: #<Shrine::UploadedFile>,
+#   two: { three: #<Shrine::UploadedFile> },
+#   four: [#<Shrine::UploadedFile>],
+# }
+
+# or Shrine.map_derivative
+attacher.map_derivative(derivatives) do |name, file|
+  puts "#{name}, #{file}"
+end
+
+# output:
+#
+#   :one, #<Shrine::UploadedFile>
+#   [:two, :three], #<Shrine::UploadedFile>
+#   [:four, 0], #<Shrine::UploadedFile>
+```
+
+## Parsing derivatives
+
+If you want to directly parse derivatives data written to a record attribute,
+you can use `Shrine.derivatives` (counterpart to `Shrine.uploaded_file`):
+
+```rb
+# or MyUploader.derivatives
+derivatives = Shrine.derivatives({
+  "one" => { "id" => "...", "storage" => "...", "metadata" => { ... } },
+  "two" => { "three" => { "id" => "...", "storage" => "...", "metadata" => { ... } } }
+  "four" => [{ "id" => "...", "storage" => "...", "metadata" => { ... } }]
+})
+
+derivatives #=>
+# {
+#   one: #<Shrine::UploadedFile>,
+#   two: { three: #<Shrine::UploadedFile> },
+#   four: [#<Shrine::UploadedFile>],
+# }
+```
+
+Like `Shrine.uploaded_file`, the `Shrine.derivatives` method accepts data as a
+hash (stringified or symbolized) or a JSON string.
+
+## Instrumentation
+
+If the `instrumentation` plugin has been loaded, the `derivatives` plugin adds
+instrumentation around derivatives processing.
+
+```rb
+# instrumentation plugin needs to be loaded *before* derivatives
+plugin :instrumentation
+plugin :derivatives
+```
+
+Processing derivatives will trigger a `derivatives.shrine` event with the
+following payload:
+
+| Key                  | Description                            |
+| :--                  | :----                                  |
+| `:processor`         | Name of the derivatives processor      |
+| `:processor_options` | Any options passed to the processor    |
+| `:uploader`          | The uploader class that sent the event |
+
+A default log subscriber is added as well which logs these events:
+
+```
+Derivatives (2133ms) – {:processor=>:thumbnails, :processor_options=>{}, :uploader=>ImageUploader}
+```
+
+You can also use your own log subscriber:
+
+```rb
+plugin :derivatives, log_subscriber: -> (event) {
+  Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
+}
+```
+```
+{"name":"derivatives","duration":2133,"processor":"thumbnails","processor_options":{},"uploader":"ImageUploader"}
+```
+
+Or disable logging altogether:
+
+```rb
+plugin :derivatives, log_subscriber: nil
+```
+
+[default_url]: /doc/plugins/default_url.md#readme
+[entity]: /doc/plugins/entity.md#readme
+[model]: /doc/plugins/model.md#readme