shrine 3.1.0 → 3.2.0

data/doc/plugins/default_url.md

@@ -40,9 +40,12 @@ The default URL block is evaluated in the context of an instance of
 Attacher.default_url do |options|
   self    #=> #<Shrine::Attacher>
 
+  file    #=> #<Shrine::UploadedFile>
   name    #=> :avatar
   record  #=> #<User>
   context #=> { ... }
+
+  # ...
 end
 ```
 

data/doc/plugins/derivatives.md

@@ -44,43 +44,45 @@ end
 ```
 ```rb
 photo = Photo.new(image: file)
-photo.image_derivatives! # calls derivatives processor and uploads results
-photo.save
-```
-
-If you're allowing the attached file to be updated later on, in your update
-route make sure to create derivatives for new attachments:
 
-```rb
-photo.image_derivatives! if photo.image_changed?
+if photo.valid?
+  photo.image_derivatives! if photo.image_changed? # create derivatives
+  photo.save
+end
 ```
 
-You can then retrieve created derivatives as follows:
+You can then retrieve the URL of a processed derivative:
 
 ```rb
-photo.image(:large)           #=> #<Shrine::UploadedFile ...>
-photo.image(:large).url       #=> "https://s3.amazonaws.com/path/to/large.jpg"
-photo.image(:large).size      #=> 43843
-photo.image(:large).mime_type #=> "image/jpeg"
+photo.image_url(:large) #=> "https://s3.amazonaws.com/path/to/large.jpg"
 ```
 
-The derivatives data is stored in the `#<name>_data` record attribute, alongside
-the main file data:
+The derivatives data is stored in the `<attachment>_data` column alongside the
+main file:
 
 ```rb
 photo.image_data #=>
 # {
-#   "id": "original.jpg",
+#   "id": "path/to/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": { ... } },
+#     "small": { "id": "path/to/small.jpg", "storage": "store", "metadata": { ... } },
+#     "medium": { "id": "path/to/medium.jpg", "storage": "store", "metadata": { ... } },
+#     "large": { "id": "path/to/large.jpg", "storage": "store", "metadata": { ... } },
 #   }
 # }
 ```
 
+And they can be retrieved as `Shrine::UploadedFile` objects:
+
+```rb
+photo.image(:large)           #=> #<Shrine::UploadedFile id="path/to/large.jpg" storage=:store metadata={...}>
+photo.image(:large).url       #=> "https://s3.amazonaws.com/path/to/large.jpg"
+photo.image(:large).size      #=> 5825949
+photo.image(:large).mime_type #=> "image/jpeg"
+```
+
 ## Retrieving derivatives
 
 The list of stored derivatives can be retrieved with `#<name>_derivatives`:
@@ -135,7 +137,7 @@ You can use the [`default_url`][default_url] plugin to set up URL fallbacks:
 
 ```rb
 Attacher.default_url do |derivative: nil, **|
-  "https://my-app.com/fallbacks/#{derivative}.jpg" if derivative
+  "/fallbacks/#{derivative}.jpg" if derivative
 end
 ```
 ```rb
@@ -279,11 +281,14 @@ The storage block is evaluated in the context of a `Shrine::Attacher` instance:
 
 ```rb
 Attacher.derivatives_storage do |derivative|
-  self   #=> #<Shrine::Attacher>
+  self    #=> #<Shrine::Attacher>
 
+  file    #=> #<Shrine::UploadedFile>
   record  #=> #<Photo>
   name    #=> :image
   context #=> { ... }
+
+  # ...
 end
 ```
 
@@ -352,6 +357,7 @@ which allows you to change your processing logic based on the record data.
 Attacher.derivatives :my_processor do |original|
   self    #=> #<Shrine::Attacher>
 
+  file    #=> #<Shrine::UploadedFile>
   record  #=> #<Photo>
   name    #=> :image
   context #=> { ... }
@@ -756,11 +762,13 @@ 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 |
+| Key                  | Description                                |
+| :--                  | :----                                      |
+| `:processor`         | Name of the derivatives processor          |
+| `:processor_options` | Any options passed to the processor        |
+| `:io`                | The source file passed to the processor    |
+| `:attacher`          | The attacher instance doing the processing |
+| `:uploader`          | The uploader class that sent the event     |
 
 A default log subscriber is added as well which logs these events:
 
@@ -776,7 +784,7 @@ plugin :derivatives, log_subscriber: -> (event) {
 }
 ```
 ```
-{"name":"derivatives","duration":2133,"processor":"thumbnails","processor_options":{},"uploader":"ImageUploader"}
+{"name":"derivatives","duration":2133,"processor":"thumbnails","processor_options":{},"io":"#<File:...>","uploader":"ImageUploader"}
 ```
 
 Or disable logging altogether:

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

@@ -15,8 +15,8 @@ which will receive the UploadedFile object along with any options that were
 passed to `UploadedFile#url`.
 
 ```rb
-plugin :url_options, store: -> (io, options) do
-  { response_content_disposition: ContentDisposition.attachment(io.original_filename) }
+plugin :url_options, store: -> (file, options) do
+  { response_content_disposition: ContentDisposition.attachment(file.original_filename) }
 end
 ```
 

data/doc/plugins/validation.md

@@ -34,11 +34,12 @@ The validation block is executed in context of a `Shrine::Attacher` instance:
 ```rb
 class VideoUploader < Shrine
   Attacher.validate do
-    self #=> #<VideoUploader::Attacher>
+    self    #=> #<Shrine::Attacher>
 
-    record #=> #<Movie>
-    name   #=> :video
-    file   #=> #<Shrine::UploadedFile>
+    file    #=> #<Shrine::UploadedFile>
+    record  #=> #<Movie>
+    name    #=> :video
+    context #=> { ... }
   end
 end
 ```

data/doc/processing.md

@@ -2,16 +2,16 @@
 title: File Processing
 ---
 
-Shrine allows you to process attached files up front or on-the-fly. For
+Shrine allows you to process attached files eagerly or on-the-fly. For
 example, if your app is accepting image uploads, you can generate a predefined
 set of of thumbnails when the image is attached to a record, or you can have
 thumbnails generated dynamically as they're needed.
 
 How you're going to implement processing is entirely up to you. For images it's
 recommended to use the **[ImageProcessing]** gem, which provides wrappers for
-processing with [ImageMagick]/[GraphicsMagick] (using the [MiniMagick] gem) or
-[libvips] (using the [ruby-vips] gem; see the [libvips section](#libvips)).
-Here is an example of generating a thumbnail with ImageProcessing:
+processing with [MiniMagick][ImageProcessing::MiniMagick] and
+[libvips][ImageProcessing::Vips]. Here is an example of generating a thumbnail
+with ImageProcessing:
 
 ```
 $ brew install imagemagick
@@ -24,17 +24,21 @@ gem "image_processing", "~> 1.8"
 require "image_processing/mini_magick"
 
 thumbnail = ImageProcessing::MiniMagick
-  .source(image)
-  .resize_to_limit!(600, 400)
+  .source(image)              # input file
+  .resize_to_limit(600, 400)  # resize macro
+  .colorspace("grayscale")    # custom operation
+  .convert("jpeg")            # output type
+  .saver(quality: 90)         # output options
+  .call                       # run the pipeline
 
 thumbnail #=> #<Tempfile:...> (a 600x400 thumbnail of the source image)
 ```
 
-## Processing up front
+## Eager processing
 
 Let's say we're handling images, and want to generate a predefined set of
-thumbnails with various dimensions. We can use the `derivatives` plugin to
-upload and save the processed files:
+thumbnails with various dimensions. We can use the
+**[`derivatives`][derivatives]** plugin to upload and save the processed files:
 
 ```rb
 Shrine.plugin :derivatives
@@ -71,27 +75,55 @@ photo.image(:large).size       #=> 5825949
 photo.image(:large).mime_type  #=> "image/jpeg"
 ```
 
-### Automatic processing
+### Conditional derivatives
 
-If you would like derivatives to be automatically created with promotion, you
-can override `Attacher#promote` for call `Attacher#create_derivatives` before
-promotion:
+The `Attacher.derivatives` block is evaluated in context of a
+`Shrine::Attacher` instance:
 
 ```rb
-class Shrine::Attacher
-  def promote(*)
-    create_derivatives
-    super
+Attacher.derivatives do |original|
+  self    #=> #<Shrine::Attacher>
+
+  file    #=> #<Shrine::UploadedFile>
+  record  #=> #<Photo>
+  name    #=> :image
+  context #=> { ... }
+
+  # ...
+end
+```
+
+This gives you the ability to branch the processing logic based on the
+attachment information:
+
+```rb
+Attacher.derivatives do |original|
+  magick = ImageProcessing::MiniMagick.source(original)
+  result = {}
+
+  if record.is_a?(Photo)
+    result[:jpg]  = magick.convert!("jpeg")
+    result[:gray] = magick.colorspace!("grayscale")
   end
+
+  if file.mime_type == "image/svg+xml"
+    result[:png] = magick.loader(transparent: "white").convert!("png")
+  end
+
+  result
 end
 ```
 
+If you find yourself branching a lot based on MIME type, the
+[`type_predicates`][type_predicates] plugin provides convenient predicate
+methods for that.
+
 ### Backgrounding
 
 Since file processing can be time consuming, it's recommended to move it into a
 background job.
 
-#### With promotion
+#### A) Creating derivatives with promotion
 
 The simplest way is to use the [`backgrounding`][backgrounding] plugin to move
 promotion into a background job, and then create derivatives as part of
@@ -120,7 +152,7 @@ class PromoteJob
 end
 ```
 
-#### Separate from promotion
+#### B) Creating derivatives separately from promotion
 
 Derivatives don't need to be created as part of the attachment flow, you can
 create them at any point after promotion:
@@ -151,7 +183,7 @@ class DerivativesJob
 end
 ```
 
-#### Concurrent processing
+#### C) Creating derivatives concurrently
 
 You can also generate derivatives concurrently:
 
@@ -204,67 +236,97 @@ class DerivativeJob
 end
 ```
 
-### Processing other filetypes
+### URL fallbacks
 
-So far we've only been talking about processing images. However, there is
-nothing image-specific in Shrine's processing API, you can just as well process
-any other types of files. The processing tool doesn't need to have any special
-Shrine integration, the ImageProcessing gem that we saw earlier is a completely
-generic gem.
+If you're creating derivatives in a background job, you'll likely want to use
+some fallbacks for derivative URLs while the background job is still
+processing. You can do that with the [`default_url`][default_url] plugin.
 
-To demonstrate, here is an example of transcoding videos using
-[streamio-ffmpeg]:
+```rb
+Shrine.plugin :default_url
+```
+
+#### A) Fallback to original
+
+You can fall back to the original file URL when the derivative is missing:
 
 ```rb
-# Gemfile
-gem "streamio-ffmpeg"
+Attacher.default_url do |derivative: nil, **|
+  file&.url if derivative
+end
 ```
 ```rb
-require "streamio-ffmpeg"
+photo.image_url(:large) #=> "https://example.com/path/to/original.jpg"
+# ... background job finishes ...
+photo.image_url(:large) #=> "https://example.com/path/to/large.jpg"
+```
 
-class VideoUploader < Shrine
-  Attacher.derivatives do |original|
-    transcoded = Tempfile.new ["transcoded", ".mp4"]
-    screenshot = Tempfile.new ["screenshot", ".jpg"]
+#### B) Fallback to derivative
 
-    movie = FFMPEG::Movie.new(original.path)
-    movie.transcode(transcoded.path)
-    movie.screenshot(screenshot.path)
+You can fall back to another derivative URL when the derivative is missing:
 
-    { transcoded: transcoded, screenshot: screenshot }
-  end
+```rb
+Attacher.default_url do |derivative: nil, **|
+  derivatives[:optimized]&.url if derivative
+end
+```
+```rb
+photo.image_url(:large) #=> "https://example.com/path/to/optimized.jpg"
+# ... background job finishes ...
+photo.image_url(:large) #=> "https://example.com/path/to/large.jpg"
+```
+
+#### C) Fallback to on-the-fly
+
+You can also fall back to [on-the-fly processing](#on-the-fly-processing),
+which should generally provide the best user experience.
+
+```rb
+THUMBNAILS = {
+  small:  [300, 300],
+  medium: [500, 500],
+  large:  [800, 800],
+}
+
+Attacher.default_url do |derivative: nil, **|
+  file&.derivation_url(:thumbnail, *THUMBNAILS.fetch(derivative)) if derivative
 end
 ```
+```rb
+photo.image_url(:large) #=> "../derivations/thumbnail/800/800/..."
+# ... background job finishes ...
+photo.image_url(:large) #=> "https://example.com/path/to/large.jpg"
+```
 
 ## On-the-fly processing
 
-Generating image thumbnails on upload can be a pain to maintain, because
+Having eagerly created image thumbnails can be a pain to maintain, because
 whenever you need to add a new version or change an existing one, you need to
-retroactively apply it to all existing uploads (see the [Managing Derivatives]
-guide for more details).
+retroactively apply it to all existing attachments (see the [Managing
+Derivatives] guide for more details).
 
-As an alternative, it's very common to instead generate thumbnails dynamically
-as they're requested, and then cache them for future requests. This strategy is
-known as "on-the-fly processing", and it's suitable for short-running
-processing such as creating image thumbnails or document previews.
+Sometimes it makes more sense to generate thumbnails dynamically as they're
+requested, and then cache them for future requests. This strategy is known as
+processing "**on-the-fly**" or "**on-demand**", and it's suitable for
+short-running processing such as creating image thumbnails or document
+previews.
 
 Shrine provides on-the-fly processing functionality via the
-[`derivation_endpoint`][derivation_endpoint] plugin. The basic setup is the
-following:
-
-1. load the plugin with a secret key and a path prefix for the endpoint
-2. mount the endpoint into your main app's router
-3. define a processing block for the type files you want to generate
-
-Together it might look something like this:
+**[`derivation_endpoint`][derivation_endpoint]** plugin. You set it up by
+loading the plugin with a secret key and a path prefix, mount its Rack app in
+your routes on the configured path prefix, and define processing you want to
+perform:
 
+```rb
+# config/initializers/shrine.rb (Rails)
+# ...
+Shrine.plugin :derivation_endpoints, secret_key: "<YOUR_SECRET_KEY>"
+```
 ```rb
 require "image_processing/mini_magick"
 
 class ImageUploader < Shrine
-  plugin :derivation_endpoint,
-    secret_key: "<YOUR SECRET KEY>",
-    prefix:     "derivations/image"
+  plugin :derivation_endpoint, prefix: "derivations/image" # matches mount point
 
   derivation :thumbnail do |file, width, height|
     ImageProcessing::MiniMagick
@@ -273,11 +335,11 @@ class ImageUploader < Shrine
   end
 end
 ```
-
 ```rb
 # config/routes.rb (Rails)
 Rails.application.routes.draw do
-  mount ImageUploader.derivation_endpoint => "derivations/image"
+  # ...
+  mount ImageUploader.derivation_endpoint => "/derivations/image"
 end
 ```
 
@@ -293,8 +355,137 @@ The plugin is highly customizable, be sure to check out the
 [documentation][derivation_endpoint], especially the [performance
 section][derivation_endpoint performance].
 
+### Dynamic derivation
+
+If you have multiple types of transformations and don't want to have a
+derivation for each one, you can set up a single derivation that applies any
+series of transformations:
+
+```rb
+class ImageUploader < Shrine
+  derivation :transform do |original, transformations|
+    transformations = Shrine.urlsafe_deserialize(transformations)
+
+    vips = ImageProcessing::Vips.source(original)
+    vips.apply!(transformations)
+  end
+end
+```
+```rb
+photo.image.derivation_url :transform, Shrine.urlsafe_serialize(
+  crop:          [10, 10, 500, 500],
+  resize_to_fit: [300, 300],
+  gaussblur:     1,
+)
+```
+
+You can create a helper method for convenience:
+
+```rb
+def derivation_url(file, transformations)
+  file.derivation_url(:transform, Shrine.urlsafe_serialize(transformations))
+end
+```
+```rb
+derivation_url photo.image,
+  crop:          [10, 10, 500, 500],
+  resize_to_fit: [300, 300],
+  gaussblur:     1
+```
+
+## Processing other filetypes
+
+So far we've only been talking about processing images. However, there is
+nothing image-specific in Shrine's processing API, you can just as well process
+any other types of files. The processing tool doesn't need to have any special
+Shrine integration, the ImageProcessing gem that we saw earlier is a completely
+generic gem.
+
+To demonstrate, here is an example of transcoding videos using
+[streamio-ffmpeg]:
+
+```rb
+# Gemfile
+gem "streamio-ffmpeg"
+```
+```rb
+require "streamio-ffmpeg"
+
+class VideoUploader < Shrine
+  Attacher.derivatives do |original|
+    transcoded = Tempfile.new ["transcoded", ".mp4"]
+    screenshot = Tempfile.new ["screenshot", ".jpg"]
+
+    movie = FFMPEG::Movie.new(original.path)
+    movie.transcode(transcoded.path)
+    movie.screenshot(screenshot.path)
+
+    { transcoded: transcoded, screenshot: screenshot }
+  end
+end
+```
+
+### Polymorphic uploader
+
+Sometimes you might want an attachment attribute to accept multiple types of
+files, and apply different processing depending on the type. Since Shrine's
+processing blocks are evaluated dynamically, you can use conditional logic:
+
+```rb
+class PolymorphicUploader < Shrine
+  IMAGE_TYPES = %w[image/jpeg image/png image/webp]
+  VIDEO_TYPES = %w[video/mp4 video/quicktime]
+  PDF_TYPES   = %w[application/pdf]
+
+  Attacher.validate do
+    validate_mime_type IMAGE_TYPES + VIDEO_TYPES + PDF_TYPES
+    # ...
+  end
+
+  Attacher.derivatives do |original|
+    case file.mime_type
+    when *IMAGE_TYPES then process_derivatives(:image, original)
+    when *VIDEO_TYPES then process_derivatives(:video, original)
+    when *PDF_TYPES   then process_derivatives(:pdf,   original)
+    end
+  end
+
+  Attacher.derivatives :image do |original|
+    # ...
+  end
+
+  Attacher.derivatives :video do |original|
+    # ...
+  end
+
+  Attacher.derivatives :pdf do |original|
+    # ...
+  end
+end
+```
+
 ## Extras
 
+### Automatic derivatives
+
+If you would like derivatives to be automatically created with promotion, you
+can override `Attacher#promote` for call `Attacher#create_derivatives` before
+promotion:
+
+```rb
+class Shrine::Attacher
+  def promote(*)
+    create_derivatives
+    super
+  end
+end
+```
+
+This shouldn't be needed if you're processing in the
+[background](#backgrounding), as in that case you have a background worker that
+will be called for each attachment, so you can call
+`Attacher#create_derivatives` there.
+
 ### libvips
 
 As mentioned, ImageProcessing gem also has an alternative backend for
@@ -304,7 +495,7 @@ characteristics – it's often **multiple times faster** than ImageMagick and ha
 low memory usage (see [Why is libvips quick]).
 
 Using libvips is as easy as installing it and switching to the
-`ImageProcessing::Vips` backend:
+[`ImageProcessing::Vips`][ImageProcessing::Vips] backend:
 
 ```
 $ brew install vips
@@ -326,7 +517,7 @@ thumbnail = ImageProcessing::Vips
 thumbnail #=> #<Tempfile:...> (a 600x400 thumbnail of the source image)
 ```
 
-### Parallelize uploading
+### Parallelize uploads
 
 If you're generating derivatives, you can parallelize the uploads using the
 [concurrent-ruby] gem:
@@ -351,86 +542,60 @@ Concurrent::Promises.zip(*tasks).wait!
 
 ### External processing
 
-Since processing is so dynamic, you're not limited to using the ImageProcessing
-gem, you can also use a 3rd-party service to generate thumbnails for you. Here
-is an example of generating thumbnails on-the-fly using [ImageOptim.com] (not
-to be confused with the [image_optim] gem):
+You can also integrate Shrine with 3rd-party processing services such as
+[Cloudinary] and [Imgix]. In the most common case, you'd serve images directly
+from these services, see the corresponding plugin docs for more details
+([shrine-cloudinary], [shrine-imgix] and [others][external storages])
+
+You can also choose to use these services as an implementation detail of your
+application, by downloading the processed images and saving them to your
+storage. Here is how you might store files processed by Imgix as derivatives:
 
 ```rb
 # Gemfile
 gem "down", "~> 5.0"
 gem "http", "~> 4.0"
+gem "shrine-imgix", "~> 0.5"
+```
+```rb
+Shrine.plugin :derivatives
+Shrine.plugin :imgix, client: { host: "my-app.imgix.net", secure_url_token: "secret" }
 ```
-
 ```rb
 require "down/http"
 
 class ImageUploader < Shrine
-  plugin :derivation_endpoint,
-    secret_key: "secret",
-    prefix:     "derivations/image",
-    download:   false
-
-  derivation :thumbnail do |width, height|
-    # generate thumbnails using ImageOptim.com
-    down = Down::Http.new(method: :post)
-    down.download("https://im2.io/<USERNAME>/#{width}x#{height}/#{source.url}")
+  IMGIX_THUMBNAIL = -> (file, width, height) do
+    Down::Http.download(file.imgix_url(w: width, h: height))
   end
-end
-```
 
-### Cloudinary
-
-[Cloudinary] is a popular commercial service for on-the-fly image processing,
-so it's a good alternative to the `derivation_endpoint` plugin. The
-[shrine-cloudinary] gem provides a Shrine storage that we can set for our
-temporary and permanent storage:
-
-```rb
-# Gemfile
-gem "shrine-cloudinary"
-```
-
-```rb
-require "cloudinary"
-require "shrine/storage/cloudinary"
-
-Cloudinary.config(
-  cloud_name: "<YOUR_CLOUD_NAME>",
-  api_key:    "<YOUR_API_KEY>",
-  api_secret: "<YOUR_API_SECRET>",
-)
-
-Shrine.storages = {
-  cache: Shrine::Storage::Cloudinary.new(prefix: "cache"),
-  store: Shrine::Storage::Cloudinary.new,
-}
-```
-
-Now when we upload our images to Cloudinary, we can generate URLs with various
-processing parameters:
-
-```rb
-photo.image_url(width: 100, height: 100, crop: :fit)
-#=> "http://res.cloudinary.com/myapp/image/upload/w_100,h_100,c_fit/nature.jpg"
+  Attacher.derivatives do
+    {
+      large:  IMGIX_THUMBNAIL[file, 800, 800],
+      medium: IMGIX_THUMBNAIL[file, 500, 500],
+      small:  IMGIX_THUMBNAIL[file, 300, 300],
+    }
+  end
+end
 ```
 
 [`Shrine::UploadedFile`]: http://shrinerb.com/rdoc/classes/Shrine/UploadedFile/InstanceMethods.html
 [ImageProcessing]: https://github.com/janko/image_processing
-[ImageMagick]: https://www.imagemagick.org
-[GraphicsMagick]: http://www.graphicsmagick.org
-[libvips]: http://libvips.github.io/libvips/
-[Why is libvips quick]: https://github.com/libvips/libvips/wiki/Why-is-libvips-quick
-[ImageOptim.com]: https://imageoptim.com/api
+[ImageProcessing::MiniMagick]: https://github.com/janko/image_processing/blob/master/doc/minimagick.md#readme
+[ImageProcessing::Vips]: https://github.com/janko/image_processing/blob/master/doc/vips.md#readme
 [streamio-ffmpeg]: https://github.com/streamio/streamio-ffmpeg
 [Managing Derivatives]: https://shrinerb.com/docs/changing-derivatives
-[Cloudinary]: https://cloudinary.com
+[Cloudinary]: https://cloudinary.com/
+[Imgix]: https://www.imgix.com/
 [shrine-cloudinary]: https://github.com/shrinerb/shrine-cloudinary
+[shrine-imgix]: https://github.com/shrinerb/shrine-imgix
 [backgrounding]: https://shrinerb.com/docs/plugins/backgrounding
-[ruby-vips]: https://github.com/libvips/ruby-vips
-[MiniMagick]: https://github.com/minimagick/minimagick
 [derivation_endpoint]: https://shrinerb.com/docs/plugins/derivation_endpoint
 [derivation_endpoint performance]: https://shrinerb.com/docs/plugins/derivation_endpoint#performance
 [derivatives]: https://shrinerb.com/docs/plugins/derivatives
 [concurrent-ruby]: https://github.com/ruby-concurrency/concurrent-ruby
-[image_optim]: https://github.com/toy/image_optim
+[default_url]: https://shrinerb.com/docs/plugins/default_url
+[external storages]: https://shrinerb.com/docs/external/extensions#storages
+[libvips]: https://libvips.github.io/libvips/
+[Why is libvips quick]: https://github.com/libvips/libvips/wiki/Why-is-libvips-quick
+[type_predicates]: https://shrinerb.com/docs/plugins/type_predicates