shrine 2.17.1 → 2.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7732350278c5d815ab0b52cbedf453707d77fae3dd4bb65b809d804dc79264bd
-  data.tar.gz: 1c7d2767978fdc0a97be12fb3732e8cf3ff8fa440aa3fc88118fba4538b858b2
+  metadata.gz: e805d8626c94174d171e7bbddbcad967caf1d3278065d2177fa513c840bb2728
+  data.tar.gz: e00dca26185799041130da5d51cca0188eac2737ad0d9c8ccc23176e589c6d09
 SHA512:
-  metadata.gz: 916e5df12daae5c50b1493a92593d6e030fbdabde239726edafb11eb7a8992a0d03479cd59ddab5ea720152281c4a042fd69812f8fb8b487a98943d0841cbd00
-  data.tar.gz: 8f1b8eb9abf796b86696c27f1a2614ae98724b1b0a5a4a00506b35cacac75dcd9ae9d193d2f5c5d8aaeab6f3cbd2a2934aeb88ab51de368b14738e18e3e33735
+  metadata.gz: f504716d480883fe8b4d4b11c4c98dd68de9b0f0da6cb43be6f8b2ff46489b9f61b4598fc3f41ae50096fe822c94e74362a455e08270b54ce1f340a150f21f35
+  data.tar.gz: 9f25fd5c79c08badbdd5d9ba1c76a3e503fe8fcecd93a51626d12f2841cdeffc7aa8bcb4bf02f944c1dec89ecaf3e2981c18342c312ceaa330e54fb1bb8aa1fb

data/CHANGELOG.md

@@ -1,4 +1,22 @@
-## 2.17.1 (2019-05-15)
+## 2.18.0 (2019-06-24)
+
+* `core` – Add `Shrine.upload` method as a shorthand for `Shrine.new(...).upload(...)` (@janko)
+
+* `upload_endpoint` – Accept file uploads from Uppy's default `files[]` array (@janko)
+
+* `core` – Add `Shrine::Attachment()` shorthand for `Shrine::Attachment.new` (@janko)
+
+* `upload_endpoint` – Add `:url` option for adding uploaded file URL to response body (@janko)
+
+* `s3` – Deprecate `:download` URL option over `:response_content_disposition` (@janko)
+
+* `s3` – Remove backfilling `size` metadata when uploading IO objects of unknown size (@janko)
+
+* `s3` – Deprecate `aws-sdk-s3` version less than 1.14.0 (@janko)
+
+* `presign_endpoint` – Add `Shrine.presign_response` for handling presigns inside a custom controller (@janko)
+
+* `upload_endpoint` – Add `Shrine.upload_response` for handling uploads inside a custom controller (@janko)
 
 * `rack_file` – Fix overriden `Attacher#assign` not accepting second argument (@janko)
 

data/README.md

@@ -2,22 +2,22 @@
 
 Shrine is a toolkit for file attachments in Ruby applications. Some highlights:
 
-* **Modular design** – the [plugin system][plugin system] allows you to load only the functionality you need
-* **Memory friendly** – streaming uploads and downloads make it work great with large files
-* **Cloud storage** – store files on [disk][FileSystem], [AWS S3][S3], [Google Cloud][GCS], [Cloudinary] and others
+* **Modular design** – the [plugin system] allows you to load only the functionality you need
+* **Memory friendly** – streaming uploads and [downloads][Retrieving Uploads] make it work great with large files
+* **Cloud storage** – store files on [disk][FileSystem], [AWS S3][S3], [Google Cloud][GCS], [Cloudinary] and [others][external]
 * **ORM integrations** – works with [Sequel][sequel plugin], [ActiveRecord][activerecord plugin], [Hanami::Model][hanami plugin] and [Mongoid][mongoid plugin]
 * **Flexible processing** – generate thumbnails [on upload] or [on-the-fly] using [ImageMagick][ImageProcessing::MiniMagick] or [libvips][ImageProcessing::Vips]
-* **Metadata validation** – [validate files][validation_helpers plugin] based on [extracted metadata][Extracting Metadata]
-* **Direct uploads** – upload asynchronously [to your app][upload_endpoint plugin] or [to the cloud][presign_endpoint plugin] using [Uppy]
-* **Resumable uploads** – make large file uploads [resumable][tus] by pointing [Uppy][uppy tus] to a [resumable endpoint][tus-ruby-server]
-* **Background jobs** – built-in support for [background processing][backgrounding plugin] that supports [any backgrounding library][backgrounding libraries]
+* **Metadata validation** – [validate files][validation] based on [extracted metadata][metadata]
+* **Direct uploads** – upload asynchronously [to your app][simple upload] or [to the cloud][presigned upload] using [Uppy]
+* **Resumable uploads** – make large file uploads [resumable][resumable upload] on [S3][uppy-s3_multipart] or [tus][tus-ruby-server]
+* **Background jobs** – built-in support for [background processing][backgrounding] that supports [any backgrounding library][Backgrounding Libraries]
 
 If you're curious how it compares to other file attachment libraries, see the [Advantages of Shrine].
 
 ## Resources
 
 | Resource          | URL                                                                                        |
-| :-------          | :---                                                                                       |
+| :---------------- | :----------------------------------------------------------------------------------------- |
 | Website           | [shrinerb.com](https://shrinerb.com)                                                       |
 | Demo code         | [Roda][roda demo] / [Rails][rails demo]                                                    |
 | Source            | [github.com/shrinerb/shrine](https://github.com/shrinerb/shrine)                           |
@@ -25,6 +25,33 @@ If you're curious how it compares to other file attachment libraries, see the [A
 | Bugs              | [github.com/shrinerb/shrine/issues](https://github.com/shrinerb/shrine/issues)             |
 | Help & Discussion | [groups.google.com/group/ruby-shrine](https://groups.google.com/forum/#!forum/ruby-shrine) |
 
+## Contents
+
+* [Quick start](#quick-start)
+* [Storage](#storage)
+* [Uploader](#uploader)
+  - [Uploading](#uploading)
+  - [IO abstraction](#io-abstraction)
+* [Uploaded file](#uploaded-file)
+* [Attachment](#attachment)
+* [Attacher](#attacher)
+* [Plugin system](#plugin-system)
+* [Metadata](#metadata)
+  * [MIME type](#mime-type)
+  * [Other metadata](#other-metadata)
+* [Processing](#processing)
+  * [Processing on upload](#processing-on-upload)
+  * [Processing on-the-fly](#processing-on-the-fly)
+* [Validation](#validation)
+* [Location](#location)
+* [Direct uploads](#direct-uploads)
+  - [Simple direct upload](#simple-direct-upload)
+  - [Presigned direct upload](#presigned-direct-upload)
+  - [Resumable direct upload](#resumable-direct-upload)
+* [Backgrounding](#backgrounding)
+* [Clearing cache](#clearing-cache)
+* [Settings](#settings)
+
 ## Quick start
 
 Add Shrine to the Gemfile and write an initializer which sets up the storage and
@@ -55,16 +82,30 @@ migration that adds an `<attachment>_data` text or JSON column, which Shrine
 will use to store all information about the attachment:
 
 ```rb
-Sequel.migration do                           # class AddImageDataToPhotos < ActiveRecord::Migration
-  change do                                   #   def change
-    add_column :photos, :image_data, :text    #     add_column :photos, :image_data, :text
-  end                                         #   end
-end                                           # end
+Sequel.migration do
+  change do
+    add_column :photos, :image_data, :text
+  end
+end
+```
+
+In Rails with Active Record the migration would look similar:
+
+```sh
+$ rails generate migration add_image_data_to_photos image_data:text
+```
+```rb
+class AddImageDataToPhotos < ActiveRecord::Migration
+  def change
+    add_column :photos, :image_data, :text
+  end
+end
 ```
 
 Now you can create an uploader class for the type of files you want to upload,
 and add a virtual attribute for handling attachments using this uploader to
-your model:
+your model. If you do not care about adding plugins or additional processing,
+you can use `Shrine::Attachment`.
 
 ```rb
 class ImageUploader < Shrine
@@ -80,24 +121,17 @@ end
 
 Let's now add the form fields which will use this virtual attribute. We need
 (1) a file field for choosing files, and (2) a hidden field for retaining the
-uploaded file in case of validation errors and for potential [direct
-uploads][direct S3 uploads guide].
+uploaded file in case of validation errors and for potential [direct uploads].
 
 ```rb
-# with Forme:
-form @photo, action: "/photos", enctype: "multipart/form-data" do |f|
-  f.input :image, type: :hidden, value: @photo.cached_image_data
-  f.input :image, type: :file
-  f.button "Create"
-end
-
 # with Rails form builder:
 form_for @photo do |f|
   f.hidden_field :image, value: @photo.cached_image_data
   f.file_field :image
   f.submit
 end
-
+```
+```rb
 # with Simple Form:
 simple_form_for @photo do |f|
   f.input :image, as: :hidden, input_html: { value: @photo.cached_image_data }
@@ -105,17 +139,41 @@ simple_form_for @photo do |f|
   f.button :submit
 end
 ```
+```rb
+# with Forme:
+form @photo, action: "/photos", enctype: "multipart/form-data" do |f|
+  f.input :image, type: :hidden, value: @photo.cached_image_data
+  f.input :image, type: :file
+  f.button "Create"
+end
+```
 
 Note that the file field needs to go *after* the hidden field, so that
 selecting a new file can always override the cached file in the hidden field.
 Also notice the `enctype="multipart/form-data"` HTML attribute, which is
-required for submitting files through the form; the Rails form builder
-will automatically generate this for you.
+required for submitting files through the form (the Rails form builder
+will automatically generate this for you).
+
+When the form is submitted, in your router/controller you can assign the file
+from request params to the attachment attribute on the model.
+
+```rb
+# In Rails:
+class PhotosController < ApplicationController
+  def create
+    Photo.create(photo_params)
+    # ...
+  end
 
-Now in your router/controller the attachment request parameter can be assigned
-to the model like any other attribute:
+  private
 
+  def photo_params
+    params.require(:photo).permit(:image)
+  end
+end
+```
 ```rb
+# In Sinatra:
 post "/photos" do
   Photo.create(params[:photo])
   # ...
@@ -125,29 +183,38 @@ end
 Once a file is uploaded and attached to the record, you can retrieve a URL to
 the uploaded file with `#<attachment>_url` and display it on the page:
 
-```rb
-image_tag @photo.image_url
+```erb
+<!-- In Rails: -->
+<%= image_tag @photo.image_url %>
+```
+```erb
+<!-- In HTML: -->
+<img src="<%= @photo.image_url %>" />
 ```
 
 ## Storage
 
-A "storage" in Shrine is an object responsible for managing files on a specific
-storage service (disk, AWS S3, Google Cloud etc), which implements a generic
-method interface. Storages are configured directly and registered under a name
-in `Shrine.storages`, so that they can later be used by uploaders.
+A "storage" in Shrine is an object that encapsulates communication with a
+specific storage service, by implementing a common public interface. Storage
+instances are registered under an identifier in `Shrine.storages`, so that they
+can later by used by [uploaders][uploader].
+
+Previously we've shown the [FileSystem] storage which saves files to disk, but
+Shrine also ships with [S3] storage which stores files on [AWS S3] (or any
+S3-compatible service such as [DigitalOcean Spaces] or [MinIO]).
 
 ```rb
 # Gemfile
-gem "aws-sdk-s3", "~> 1.2" # for AWS S3 storage
+gem "aws-sdk-s3", "~> 1.14" # for AWS S3 storage
 ```
 ```rb
 require "shrine/storage/s3"
 
 s3_options = {
-  bucket:            "my-bucket", # required
-  access_key_id:     "abc",
-  secret_access_key: "xyz",
-  region:            "my-region",
+  bucket:            "<YOUR BUCKET>", # required
+  access_key_id:     "<YOUR ACCESS KEY ID>",
+  secret_access_key: "<YOUR SECRET ACCESS KEY>",
+  region:            "<YOUR REGION>",
 }
 
 Shrine.storages = {
@@ -156,129 +223,125 @@ Shrine.storages = {
 }
 ```
 
-The above example sets up AWS S3 storage both for temporary and permanent
-storage, which is suitable for [direct uploads][direct S3 uploads guide]. The
-`:cache` and `:store` names are special only in terms that the attacher will
-automatically pick them up, but you can also register more storages under
-different names.
+The above example sets up S3 for both temporary and permanent storage, which is
+suitable for [direct uploads][Direct Uploads to S3]. The `:cache` and
+`:store` names are special only in terms that the [attacher] will automatically
+pick them up, you can also register more storage objects under different names.
 
-Shrine ships with [FileSystem] and [S3] storage, take a look at their
-documentation for more details on various features they support. There are
-[many more Shrine storages][external storages] provided by external gems, and
-you can also [create your own storage][creating storage].
+See the [FileSystem] and [S3] storage docs for more details. There are [many
+more Shrine storages][external] provided by external gems, and you can also
+[create your own storage][Creating Storages].
 
 ## Uploader
 
-Uploaders are subclasses of `Shrine`, and are essentially wrappers around
-storages. They perform common tasks around upload that aren't related to a
+Uploaders are subclasses of `Shrine`, and they wrap the actual upload to the
+storage. They perform common tasks around upload that aren't related to a
 particular storage.
 
 ```rb
-class ImageUploader < Shrine
+class MyUploader < Shrine
   # image attachent logic
 end
 ```
-```rb
-uploader = ImageUploader.new(:store)
-uploader #=> uploader for storage registered under `:store`
-```
 
 It's common to create an uploader for each type of file that you want to handle
-(image, video, audio, document etc), but really you can organize them in any way
-you like.
+(`ImageUploader`, `VideoUploader`, `AudioUploader` etc), but really you can
+organize them in any way you like.
 
 ### Uploading
 
-The main method of the uploader is `#upload`, which takes an IO-like object on
-the input, and returns a representation of the uploaded file on the output.
+The main method of the uploader is `#upload`, which takes an [IO-like
+object][io abstraction] and a storage identifier on the input, and returns a
+representation of the [uploaded file] on the output.
 
 ```rb
-uploaded_file = uploader.upload(file)
-uploaded_file #=> #<Shrine::UploadedFile>
+MyUploader.upload(file, :store) #=> #<Shrine::UploadedFile>
+```
+
+Internally this instantiates the uploader with the storage and calls `#upload`
+on it:
+
+```rb
+uploader = MyUploader.new(:store)
+uploader.upload(file) #=> #<Shrine::UploadedFile>
 ```
 
 Some of the tasks performed by `#upload` include:
 
-* file processing (if defined)
-* extracting metadata
-* generating location
-* uploading (this is where the storage is called)
+* any defined [file processing][on upload]
+* extracting [metadata]
+* generating [location]
+* uploading (this is where the [storage] is called)
 * closing the uploaded file
 
-Additional upload options can be passed via `:upload_options`, and they will be
-forwarded directly to `Storage#upload` (see the documentation of your storage
-for the list of available options):
+The second argument is a `context` hash which is forwarded to places like
+metadata extraction and location generation, but it has a few special options:
 
 ```rb
-uploader.upload(file, upload_options: { acl: "public-read" })
+uploader.upload(io, metadata: { "foo" => "bar" })           # add metadata
+uploader.upload(io, location: "path/to/file")               # specify custom location
+uploader.upload(io, upload_options: { acl: "public-read" }) # add options to Storage#upload
 ```
 
 ### IO abstraction
 
-Shrine is able to upload any IO-like object that responds to `#read`,
-`#rewind`, `#eof?` and `#close`. This includes built-in IO and IO-like objects
-like File, Tempfile and StringIO.
+Shrine is able to upload any IO-like object that implement methods [`#read`],
+[`#rewind`], [`#eof?`] and [`#close`] whose behaviour matches the [`IO`] class.
+This includes built-in IO and IO-like objects like File, Tempfile and StringIO.
 
-When a file is uploaded to a Rails app, it will be represented by an
-ActionDispatch::Http::UploadedFile object in the params. This is also an
+When a file is uploaded to a Rails app, in request params it will be
+represented by an `ActionDispatch::Http::UploadedFile` object, which is also an
 IO-like object accepted by Shrine. In other Rack applications the uploaded file
-will be represented as a Hash, but it can still be attached when `rack_file`
-plugin is loaded.
+will be represented as a Hash, but it can be converted into an IO-like object
+with the [`rack_file`][rack_file plugin] plugin.
 
-Here are some examples of IO objects that can be uploaded:
+Here are some examples of various IO-like objects that can be uploaded:
 
 ```rb
-uploader.upload File.open("/path/to/file", binmode: true) # upload from disk
-uploader.upload StringIO.new("file content")              # upload from memory
-uploader.upload ActionDispatch::Http::UploadedFile.new    # upload from Rails controller
-uploader.upload Shrine.rack_file({ tempfile: tempfile })  # upload from Rack controller
-uploader.upload Rack::Test::UploadedFile.new              # upload from rack-test
-uploader.upload Down.open("https://example.org/file")     # upload from internet
+uploader.upload File.open("/path/to/file", binmode: true)   # upload from disk
+uploader.upload StringIO.new("file content")                # upload from memory
+uploader.upload ActionDispatch::Http::UploadedFile.new(...) # upload from Rails controller
+uploader.upload Shrine.rack_file({ tempfile: tempfile })    # upload from Rack controller
+uploader.upload Rack::Test::UploadedFile.new(...)           # upload from rack-test
+uploader.upload Down.open("https://example.org/file")       # upload from internet
+uploader.upload Shrine::UploadedFile.new(...)               # upload from Shrine storage
 ```
 
-`Shrine::UploadedFile`, the object returned after upload, is itself an IO-like
-object as well. This makes it trivial to reupload a file from one storage to
-another, and this is used by the attacher to reupload a file stored on
-temporary storage to permanent storage.
-
 ## Uploaded file
 
-The `Shrine::UploadedFile` object represents the file that was uploaded to the
+The `Shrine::UploadedFile` object represents the file that was uploaded to a
 storage, and it's what's returned from `Shrine#upload` or when retrieving a
-record attachment. It contains the following information:
+record [attachment]. It contains the following information:
 
-* `storage` – identifier of the storage the file was uploaded to
-* `id` – location of the file on the storage
-* `metadata` – file metadata that was extracted before upload
+| Key        | Description                                        |
+| :-------   | :----------                                        |
+| `id`       | location of the file on the storage                |
+| `storage`  | identifier of the storage the file was uploaded to |
+| `metadata` | file [metadata] that was extracted before upload   |
 
 ```rb
 uploaded_file = uploader.upload(file)
+uploaded_file.data #=> {"id"=>"949sdjg834.jpg","storage"=>"store","metadata"=>{...}}
 
 uploaded_file.id       #=> "949sdjg834.jpg"
 uploaded_file.storage  #=> #<Shrine::Storage::FileSystem>
 uploaded_file.metadata #=> {...}
-
-# It can be serialized into JSON and saved to a database column
-uploaded_file.to_json  #=> '{"id":"949sdjg834.jpg","storage":"store","metadata":{...}}'
 ```
 
 It comes with many convenient methods that delegate to the storage:
 
 ```rb
-uploaded_file.url                 #=> "https://my-bucket.s3.amazonaws.com/949sdjg834.jpg"
-uploaded_file.open                # opens the uploaded file
-uploaded_file.download            #=> #<File:/var/folders/.../20180302-33119-1h1vjbq.jpg>
-uploaded_file.stream(destination) # streams uploaded content into a writable destination
-uploaded_file.exists?             #=> true
-uploaded_file.delete              # deletes the file from the storage
-
-# open/download the uploaded file for the duration of the block
-uploaded_file.open     { |io| io.read }
-uploaded_file.download { |tempfile| tempfile.read }
+uploaded_file.url                     #=> "https://my-bucket.s3.amazonaws.com/949sdjg834.jpg"
+uploaded_file.open { |io| ... }       # opens the uploaded file stream
+uploaded_file.download { |file| ... } # downloads the uploaded file to disk
+uploaded_file.stream(destination)     # streams uploaded content into a writable destination
+uploaded_file.exists?                 #=> true
+uploaded_file.delete                  # deletes the uploaded file from the storage
 ```
 
-It also implements the IO-like interface that conforms to Shrine's IO
-abstraction, which allows it to be uploaded again to other storages.
+It also implements the IO-like interface that conforms to Shrine's [IO
+abstraction][io abstraction], which allows it to be uploaded again to other
+storages.
 
 ```rb
 uploaded_file.read   # returns content of the uploaded file
@@ -287,19 +350,20 @@ uploaded_file.rewind # rewinds the IO
 uploaded_file.close  # closes the IO
 ```
 
-For more details on these `Shrine::UploadedFile` methods, see the [Retrieving
-Uploads] guide.
+For more details, see the [Retrieving Uploads] guide and
+[`Shrine::UploadedFile`] API docs.
 
 ## Attachment
 
-Storages, uploaders, and uploaded file objects are the main components for
-managing files. Since most often you also want to *attach* the uploaded files
-to database records, Shrine comes with a high-level attachment interface, which
-uses these components internally.
+Storages, uploaders, and uploaded file objects are Shrine's foundational
+components. To help you actually attach uploaded files to database records in
+your application, Shrine comes with a high-level attachment interface built on
+top of these components.
 
-Usually you're using an ORM for saving database records, in which case you can
-load an additional plugin to automatically tie the attached files to record
-lifecycle. But you can also use Shrine just with plain models.
+There are plugins for hooking into most database libraries, and in case of
+ActiveRecord and Sequel the plugin will automatically tie the attached files to
+records' lifecycles. But you can also use Shrine just with plain old Ruby
+objects.
 
 ```rb
 Shrine.plugin :sequel # :activerecord
@@ -308,23 +372,25 @@ Shrine.plugin :sequel # :activerecord
 ```rb
 class Photo < Sequel::Model # ActiveRecord::Base
   include ImageUploader::Attachment.new(:image) #
-  include ImageUploader.attachment(:image)      # these are all equivalent
+  include ImageUploader::Attachment(:image)     # these are all equivalent
   include ImageUploader[:image]                 #
 end
 ```
 
-You can choose whichever of these three syntaxes you prefer. Either of these
+You can choose whichever of these syntaxes you prefer. Either of these
 will create a `Shrine::Attachment` module with attachment methods for the
 specified attribute, which then get added to your model when you include it:
 
-* `#image=` – uploads the file to temporary storage and serializes the result into `image_data`
-* `#image` – returns `Shrine::UploadedFile` instantiated from `image_data`
-* `#image_url` – calls `url` on the attachment if it's present, otherwise returns nil
-* `#image_attacher` – returns instance of `Shrine::Attacher` which handles the attaching
+| Method            | Description                                                                       |
+| :-----            | :----------                                                                       |
+| `#image=`         | uploads the file to temporary storage and serializes the result into `image_data` |
+| `#image`          | returns [`Shrine::UploadedFile`][uploaded file] instantiated from `image_data`    |
+| `#image_url`      | calls `url` on the attachment if it's present, otherwise returns nil              |
+| `#image_attacher` | returns instance of [`Shrine::Attacher`][attacher] which handles the attaching    |
 
-The ORM plugin that we loaded adds appropriate callbacks, so when record is
-saved the attachment is uploaded to permanent storage, and when record is
-deleted the attachment is deleted as well.
+The ORM plugin that we loaded adds appropriate callbacks. For example, saving
+the record uploads the attachment to permanent storage, while deleting the
+record deletes the attachment.
 
 ```rb
 # no file is attached
@@ -352,23 +418,13 @@ attachment will get deleted when the record gets saved.
 
 ```rb
 photo.update(image: new_file) # changes the attachment and deletes previous
-# or
 photo.update(image: nil)      # removes the attachment and deletes previous
 ```
 
-In addition to assigning raw files, you can also assign a JSON representation
-of files that are already uploaded to the temporary storage. This allows Shrine
-to retain cached files in case of validation errors and handle [direct uploads]
-via the hidden form field.
-
-```rb
-photo.image = '{"id":"9260ea09d8effd.jpg","storage":"cache","metadata":{...}}'
-```
-
 ## Attacher
 
-The model attachment attributes and callbacks just delegate the behaviour
-to their underlying `Shrine::Attacher` object.
+The model attachment attributes and callbacks added by `Shrine::Attachment`
+just delegate the behaviour to their underlying `Shrine::Attacher` object.
 
 ```rb
 photo.image_attacher #=> #<Shrine::Attacher>
@@ -384,40 +440,13 @@ attacher.get          # equivalent to `photo.image`
 attacher.url          # equivalent to `photo.image_url`
 ```
 
-The attacher is what drives attaching files to model instances, and it functions
-independently from models' attachment interface. This means that you can use it
-as an alternative, in case you prefer not to add additional attributes to the
-model, or prefer explicitness over callbacks. It's also useful when you need
-something more advanced which isn't available through the attachment
-attributes.
-
-The `Shrine::Attacher` by default uses `:cache` for temporary and `:store` for
-permanent storage, but you can specify a different storage:
-
-```rb
-ImageUploader::Attacher.new(photo, :image, cache: :other_cache, store: :other_store)
-
-# OR
-
-photo.image_attacher(cache: :other_cache, store: :other_store)
-photo.image = file # uploads to :other_cache storage
-photo.save         # promotes to :other_store storage
-```
-
-You can also skip the temporary storage altogether and upload files directly to
-the primary storage:
-
-```rb
-uploaded_file = attacher.store!(file) # upload file directly to permanent storage
-attacher.set(uploaded_file)           # attach the uploaded file
-```
-
-Whenever the attacher uploads or deletes files, it sends a `context` hash
-which includes `:record`, `:name`, and `:action` keys, so that you can perform
-processing or generate location differently depending on this information. See
-"Context" section for more details.
+The attacher is what drives attaching files to model instances; you can use it
+as a more explicit alternative to models' attachment interface, or simply when
+you need something that's not available through the attachment methods.
 
-For more information about `Shrine::Attacher`, see the [Using Attacher] guide.
+You can do things such as change the temporary and permanent storage the
+attacher uses, or upload files directly to permanent storage. See the [Using
+Attacher] guide for more details.
 
 ## Plugin system
 
@@ -441,7 +470,7 @@ end
 ```
 
 If you want to extend Shrine functionality with custom behaviour, you can also
-[create your own plugin][creating plugin].
+[create your own plugin][Creating Plugins].
 
 ## Metadata
 
@@ -463,23 +492,12 @@ uploaded_file.mime_type         #=> "video/mp4"
 uploaded_file.size              #=> 345993
 ```
 
-By default these values are determined from the following attributes on the IO
-object:
-
-* `filename` – `io.original_filename` or `io.path`
-* `mime_type` – `io.content_type`
-* `size` – `io.size`
-
 ### MIME type
 
-By default `mime_type` will be inherited from `#content_type` attribute of the
-uploaded file, which is set from the `Content-Type` request header. However,
-this header is determined by the browser solely based on the file extension.
-This means that by default Shrine's `mime_type` is *not guaranteed* to hold
-the actual MIME type of the file.
-
-To remedy that, you can load the `determine_mime_type` plugin, which will make
-Shrine extract the MIME type from *file content*.
+By default, `mime_type` metadata will be inherited from the `#content_type`
+attribute of the uploaded file, which is generally not secure and will trigger
+a warning. You can load the [`determine_mime_type`][determine_mime_type plugin]
+plugin to have MIME type extracted from file *content* instead.
 
 ```rb
 Shrine.plugin :determine_mime_type
@@ -490,66 +508,42 @@ photo.image.mime_type #=> "text/x-php"
 ```
 
 By the default the UNIX [`file`] utility is used to determine the MIME type,
-but you can also choose a different analyzer – see the plugin documentation for
-more details.
+but you can also choose a different analyzer, see the
+[`determine_mime_type`][determine_mime_type plugin] docs for more details.
 
 ### Other metadata
 
-In addition to `size`, `filename`, and `mime_type`, you can also extract image
-dimensions using the `store_dimensions` plugin, as well as any custom metadata
-using the `add_metadata` plugin. Check out the [Extracting Metadata] guide for
-more details.
-
-Note that you can also manually override extracted metadata by passing the
-`:metadata` option to `Shrine#upload`:
-
-```rb
-uploaded_file = uploader.upload(file, metadata: { "filename" => "Matrix[1999].mp4", "foo" => "bar" })
-uploaded_file.original_filename #=> "Matrix[1999].mp4"
-uploaded_file.metadata["foo"]   #=> "bar"
-```
+In addition to basic metadata, you can also extract [image
+dimensions][store_dimensions plugin], calculate [signatures][signature plugin],
+and in general extract any [custom metadata][add_metadata plugin]. Check out
+the [Extracting Metadata] guide for more details.
 
 ## Processing
 
-Shrine allows you to processing attached files either "on upload" or
+Shrine allows you to process attached files either "on upload" or
 "on-the-fly". For example, if your app is accepting image uploads, you can
 generate a pre-defined set of of thumbnails as soon as the image is attached to
 a record ("on upload"), or you can generate necessary thumbnails dynamically as
 they're needed ("on-the-fly").
 
-In both cases, for image processing you can use the **[ImageProcessing]** gem.
-It provides a convenient unified API for processing with [ImageMagick] or
-[libvips]. Here is an example of generating a thumbnail with ImageProcessing:
+For image processing it's recommended to use the **[ImageProcessing]** gem,
+which is a high-level wrapper for processing with [ImageMagick] (via
+[MiniMagick]) or [libvips] (via [ruby-vips]).
+
+### Processing on upload
+
+For processing "on upload", you can intercept when a cached file is being
+uploaded to permanent storage, and perform any file processing you might want.
+The [`processing`][processing plugin] plugin provides the promotion hook, while
+the [`versions`][versions plugin] plugin enables handling a hash of versions.
 
 ```sh
 $ brew install imagemagick
 ```
 ```rb
 # Gemfile
-gem "image_processing", "~> 1.0"
+gem "image_processing", "~> 1.2"
 ```
-```rb
-require "image/mini_magick"
-
-thumbnail = ImageProcessing::MiniMagick
-  .source(original_image)
-  .resize_to_limit!(600, 400)
-
-thumbnail #=> #<Tempfile:...> (thumbnail limited to 600x400)
-```
-
-### On upload
-
-Shrine allows you intercept when a cached file is being uploaded to permanent
-storage, and perform any file processing you might want. The result of
-processing can also be multiple files, such as thumbnails of various
-dimensions. This processing can additionaly be delayed into a [background
-job](#backgrounding).
-
-The promotion hook is provided by the `processing` plugin, while the ability
-to save multiple files is provided by the `versions` plugin. Let's set up our
-uploader to generate some thumbnails from the attached image:
-
 ```rb
 require "image_processing/mini_magick"
 
@@ -574,21 +568,12 @@ class ImageUploader < Shrine
 end
 ```
 
-After these files have been uploaded, their data will all be saved to the
-`<attachment>_data` column. The attachment getter will then read them as a Hash
-of `Shrine::UploadedFile` objects.
+After the files are uploaded, their data is saved into the `<attachment>_data`
+column, and the attachment getter will read them as a Hash of
+[`Shrine::UploadedFile`][uploaded file] objects.
 
 ```rb
-photo = Photo.create(image: image)
-
-photo.image_data #=>
-# '{
-#   "original": {"id":"9sd84.jpg", "storage":"store", "metadata":{...}},
-#   "large": {"id":"lg043.jpg", "storage":"store", "metadata":{...}},
-#   "medium": {"id":"kd9fk.jpg", "storage":"store", "metadata":{...}},
-#   "small": {"id":"932fl.jpg", "storage":"store", "metadata":{...}}
-# }'
-
+photo = Photo.create(image: file) # processing is triggered
 photo.image #=>
 # {
 #   :original => #<Shrine::UploadedFile @data={"id"=>"9sd84.jpg", ...}>,
@@ -601,32 +586,46 @@ photo.image[:medium]           #=> #<Shrine::UploadedFile>
 photo.image[:medium].url       #=> "/uploads/store/lg043.jpg"
 photo.image[:medium].size      #=> 5825949
 photo.image[:medium].mime_type #=> "image/jpeg"
-```
-
-The `versions` plugin also expands `#<attachment>_url` to accept version names:
 
-```rb
-photo.image_url(:large) #=> "https://..."
+photo.image_url(:large) # returns version URL with fallbacks in case version is missing
 ```
 
-For more details see the [File Processing] guide.
+By default processing is executed synchronously, but you can choose to delay it
+into a [background job][backgrounding]. You can also do any other type of file
+processing you want, see the [File Processing] guide for more details.
 
-### On-the-fly
+### Processing on-the-fly
 
 On-the-fly processing is provided by the
-[`derivation_endpoint`][derivation_endpoint plugin] plugin. It provides a
-mountable Rack app, which on request will call the processing we defined.
+[`derivation_endpoint`][derivation_endpoint plugin] plugin. It comes with a
+[mountable][Mounting Endpoints] Rack app which applies processing on request
+and returns processed files.
 
-We start by loading the plugin with a secret key and a path prefix to where
-we'll mount the Rack app, and defining a "derivation" we want the app to call:
+To set it up, we mount the Rack app in our router on a chosen path prefix,
+configure the plugin with a secret key and that path prefix, and define
+processing we want to perform:
 
+```sh
+$ brew install imagemagick
+```
+```rb
+# Gemfile
+gem "image_processing", "~> 1.2"
+```
+```rb
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  # ...
+  mount ImageUploader.derivation_endpoint => "/derivations/image"
+end
+```
 ```rb
 require "image_processing/mini_magick"
 
 class ImageUploader < Shrine
   plugin :derivation_endpoint,
     secret_key: "<YOUR SECRET KEY>",
-    prefix:     "derivations/image"
+    prefix:     "derivations/image" # needs to match the mount point in routes
 
   derivation :thumbnail do |file, width, height|
     ImageProcessing::MiniMagick
@@ -636,62 +635,23 @@ class ImageUploader < Shrine
 end
 ```
 
-Then we can mount the Rack app into our router (for web frameworks other than
-Rails see [Mounting Endpoints] wiki):
-
-```rb
-# config/routes.rb (Rails)
-Rails.application.routes.draw do
-  mount ImageUploader.derivation_endpoint => "derivations/image"
-end
-```
-
-Now we can generate URLs from attached files that on request will call the
-processing we defined:
+Now we can generate URLs from attached files that will perform the desired
+processing:
 
 ```rb
 photo.image.derivation_url(:thumbnail, "600", "400")
 #=> "/derivations/image/thumbnail/600/400/eyJpZCI6ImZvbyIsInN0b3JhZ2UiOiJzdG9yZSJ9?signature=..."
 ```
 
-The `derivation_endpoint` plugin is highly customizable, for more details see
-its [documentation][derivation_endpoint plugin].
-
-## Context
-
-The `#upload` (and `#delete`) methods accept a hash of options as the second
-argument, which is forwarded down the chain and be available for processing,
-extracting metadata and generating location.
-
-```rb
-uploader.upload(file, { foo: "bar" }) # context hash is forwarded to all tasks around upload
-```
-
-Some options are actually recognized by Shrine (such as `:location`,
-`:upload_options`, and `:metadata`), some are added by plugins, and the rest are
-there just to provide additional context, for more flexibility in performing
-tasks and more descriptive logging.
-
-The attacher automatically includes additional `context` information for each
-upload and delete operation:
-
-* `context[:record]` – model instance where the file is attached
-* `context[:name]` – name of the attachment attribute on the model
-* `context[:action]` – identifier for the action being performed (`:cache`, `:store`, `:recache`, `:backup`, ...)
-
-```rb
-class VideoUploader < Shrine
-  process(:store) do |io, context|
-    trim_video(io, 300) if context[:record].user.free_plan?
-  end
-end
-```
+The on-the-fly processing feature is highly customizable, see the
+[`derivation_endpoint`][derivation_endpoint plugin] plugin documentation for
+more details.
 
 ## Validation
 
-Shrine can perform file validations for files assigned to the model. The
-validations are defined inside the `Attacher.validate` block, and you can load
-the `validation_helpers` plugin to get convenient file validation methods:
+Shrine can perform file validations for files assigned to the model, with
+[`validation_helpers`][validation_helpers plugin] plugin providing some common
+validation methods:
 
 ```rb
 class DocumentUploader < Shrine
@@ -706,20 +666,21 @@ end
 
 ```rb
 user = User.new
-user.cv = File.open("cv.pdf")
+user.cv = File.open("cv.pdf", "rb")
 user.valid? #=> false
 user.errors.to_hash #=> {:cv=>["is too large (max is 5 MB)"]}
 ```
 
-See the [File Validation] guide and [`validation_helpers`][validation_helpers
-plugin] plugin documentation for more details.
+For more details, see the [File Validation] guide and
+[`validation_helpers`][validation_helpers plugin] plugin docs.
 
 ## Location
 
-Before Shrine uploads a file, it generates a random location for it. By default
-the hierarchy is flat; all files are stored in the root directory of the
-storage. The `pretty_location` plugin provides a nice default hierarchy, but
-you can also override `#generate_location` with a custom implementation:
+Shrine automatically generated random locations before uploading files. By
+default the hierarchy is flat, meaning all files are stored in the root
+directory of the storage. The [`pretty_location`][pretty_location plugin]
+plugin provides a good default hierarchy, but you can also override
+`#generate_location` with a custom implementation:
 
 ```rb
 class ImageUploader < Shrine
@@ -746,46 +707,23 @@ Note that there should always be a random component in the location, so that
 the ORM dirty tracking is detected properly. Inside `#generate_location` you
 can also access the extracted metadata through `context[:metadata]`.
 
-When uploading single files, it's possible to bypass `#generate_location` via
-the uploader, by specifying `:location`:
-
-```rb
-uploader.upload(file, location: "some/specific/location.mp4")
-```
-
 ## Direct uploads
 
-To really improve the user experience, it's recommended to start uploading the
-files asynchronously as soon they're selected. This way the UI is still
-responsive during upload, so the user can fill in other fields while the files
-are being uploaded, and if you display a progress bar they can see when the
-upload will finish.
-
-These asynchronous uploads will have to go to an endpoint separate from the one
-where the form is submitted. This can be an endpoint in your app, or an
-endpoint of a cloud service. In either case, the uploads should go to
-*temporary* storage (`:cache`), to ensure there won't be any orphan files in
-the primary storage (`:store`).
-
-Once files are uploaded on the client side, their data can be submitted to the
-server and attached to a record, just like with raw files. The only difference
-is that they won't be additionally uploaded to temporary storage on assignment,
-as they were already uploaded on the client side. Note that by default **Shrine
-won't extract metadata from directly uploaded files**, instead it will just copy
-metadata that was extacted on the client side; see [this section][metadata
-direct uploads] for the rationale and instructions on how to opt in.
-
-For handling client side uploads it's recommended to use **[Uppy]**. Uppy is a
-very flexible modern JavaScript file upload library, which happens to integrate
-nicely with Shrine.
+To improve the user experience, it's recommended to upload files asynchronously
+as soon as the user selects them. The direct uploads would go to temporary
+storage, just like in the synchronous flow.
+
+On the client side it's highly recommended to use **[Uppy]**, a very flexible
+modern JavaScript file upload library that happens to integrate nicely with
+Shrine.
 
 ### Simple direct upload
 
 The simplest approach is creating an upload endpoint in your app that will
-receive uploads and forward them to the specified storage. You can use the
-`upload_endpoint` Shrine plugin to create a Rack app that handles uploads,
-and mount it inside your application (for web frameworks other than Rails
-see [Mounting Endpoints] wiki).
+forward uploads to the specified storage. The
+[`upload_endpoint`][upload_endpoint plugin] Shrine plugin provides a
+[mountable][Mounting Endpoints] Rack application that does that, and you can
+combine it with Uppy's [XHR Upload][uppy xhr-upload] plugin:
 
 ```rb
 Shrine.plugin :upload_endpoint
@@ -793,45 +731,47 @@ Shrine.plugin :upload_endpoint
 ```rb
 # config/routes.rb (Rails)
 Rails.application.routes.draw do
-  mount ImageUploader.upload_endpoint(:cache) => "images/upload"
+  # ...
+  mount ImageUploader.upload_endpoint(:cache) => "/images/upload" # POST /images/upload
 end
 ```
+```js
+// upload.js
+// ...
+uppy.use(Uppy.XHRUpload, {
+  endpoint: '/images/upload'
+})
 
-The above will add a `POST /images/upload` route to your app. You can now use
-Uppy's [XHR Upload][uppy xhr upload] plugin to upload selected files to this
-endpoint, and have the uploaded file data submitted to your app. The client
-side code for this will depend on your application, see [this
-walkthrough][direct uploads walkthrough] for an example of adding simple direct
-uploads from scratch.
-
-If you wanted to implement this enpdoint yourself, this is how it could roughly
-look like in Sinatra:
-
-```rb
-Shrine.plugin :rack_file # only if not using Rails
+uppy.on('upload-success', (file, response) => {
+  const uploadedFileData = JSON.stringify(response.body)
+  // ... add this data to your form or submit it to your app ...
+})
 ```
-```rb
-post "/images/upload" do
-  uploader = ImageUploader.new(:cache)
-  file     = Shrine.rack_file(params["file"]) # only `params[:file]` in Rails
-
-  uploaded_file = uploader.upload(file)
 
-  json uploaded_file.data
-end
-```
+For adding simple direct uploads from scratch, see [this walkthrough][Adding
+Direct App Uploads] (there is also the [Roda][roda demo] / [Rails][rails demo]
+demo app).
 
 ### Presigned direct upload
 
-If you want to free your app from receiving file uploads, you can also upload
-files directly to the cloud (AWS S3, Google Cloud etc). In this flow the client
-is required to first fetch upload parameters from the server, and then use these
-parameters to make the upload.
+For better performance, you can also upload files directly to your cloud
+storage service (AWS S3, Google Cloud Storage etc). For this, your temporary
+storage needs to be your cloud service:
 
-You can use the `presign_endpoint` Shrine plugin to create a Rack app that
-generates these upload parameters (provided that the underlying storage
-implements `#presign`), and mount it inside your application (for web
-frameworks other than Rails see [Mounting Endpoints] wiki):
+```rb
+require "shrine/storage/s3"
+
+Shrine.storages = {
+  cache: Shrine::Storage::S3.new(prefix: "cache", **s3_options),
+  store: Shrine::Storage::S3.new(**s3_options)
+}
+```
+
+In this flow, the client needs to first fetch upload parameters from the
+server, and then use these parameters for the upload to the cloud service. The
+[`presign_endpoint`][presign_endpoint plugin] Shrine plugin provides a
+[mountable][Mounting Endpoints] Rack application that generates upload
+parameters, and you can combine it with Uppy's [AWS S3][uppy aws-s3] plugin:
 
 ```rb
 Shrine.plugin :presign_endpoint
@@ -839,62 +779,144 @@ Shrine.plugin :presign_endpoint
 ```rb
 # config/routes.rb (Rails)
 Rails.application.routes.draw do
-  mount Shrine.presign_endpoint(:cache) => "s3/params"
+  # ...
+  mount Shrine.presign_endpoint(:cache) => "/s3/params" # GET /s3/params
 end
 ```
+```js
+// upload.js
+// ...
+uppy.use(Uppy.AwsS3, {
+  companionUrl: '/' // uses '/s3/params'
+})
+
+uppy.on('upload-success', (file, response) => {
+  const uploadedFileData = JSON.stringify({
+    id: file.meta['key'].match(/^cache\/(.+)/)[1], // object key without prefix
+    storage: 'cache',
+    metadata: {
+      size:      file.size,
+      filename:  file.name,
+      mime_type: file.type,
+    }
+  })
+  // ... add this data to your form or submit it to your app ...
+})
+```
+
+For adding direct S3 uploads from scratch, see [this walkthrough][Adding Direct
+S3 Uploads] (there is also the [Roda][roda demo] / [Rails][rails demo] demo).
+See also the [Direct Uploads to S3] guide for more details.
 
-The above will add a `GET /s3/params` route to your app. You can now hook Uppy's
-[AWS S3][uppy aws s3] plugin to this endpoint and have it upload directly to
-S3. See [this walkthrough][direct S3 uploads walkthrough] that shows adding
-direct S3 uploads from scratch, as well as the [Direct Uploads to S3][direct S3
-uploads guide] guide that provides some useful tips. Also check out the
-[Roda][roda demo] / [Rails][rails demo] demo app which implements multiple
-uploads directly to S3.
+### Resumable direct upload
 
-If you wanted to implement this enpdoint yourself, this is how it could roughly
-look like for S3 storage in Sinatra:
+If your app is accepting large uploads, you can make the uploads **resumable**.
+This can significantly improve experience for users on slow and flaky internet
+connections.
 
-```rb
-get "/s3/params" do
-  storage  = Shrine.storages[:cache]
-  location = SecureRandom.hex + File.extname(params["filename"].to_s)
+#### Uppy S3 Multipart
 
-  presign_data = storage.presign(location, content_type: params["type"])
+You can achieve resumable uploads directly to S3 with the [AWS S3
+Multipart][uppy aws-s3-multipart] Uppy plugin, accompanied with the Shrine
+plugin provided by the [uppy-s3_multipart] gem (assuming your temporary storage
+is `Shrine::Storage::S3`):
 
-  json presign_data
+```rb
+# Gemfile
+gem "uppy-s3_multipart", "~> 0.3"
+```
+```rb
+Shrine.plugin :uppy_s3_multipart
+```
+```rb
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  # ...
+  mount Shrine.uppy_s3_multipart(:cache) => "/s3/multipart"
 end
 ```
+```js
+// upload.js
+// ...
+uppy.use(Uppy.AwsS3Multipart, {
+  companionUrl: '/' // uses '/s3/multipart/*' routes
+})
 
-### Resumable direct upload
+uppy.on('upload-success', (file, response) => {
+  const uploadedFileData = JSON.stringify({
+    id: response.uploadURL.match(/\/cache\/([^\?]+)/)[1], // object key without prefix
+    storage: 'cache',
+    metadata: {
+      size:      file.size,
+      filename:  file.name,
+      mime_type: file.type,
+    }
+  })
+  // ... add this data to your form or submit it to your app ...
+})
+```
 
-If your app is dealing with large uploads (e.g. videos), keep in mind that it
-can be challening for your users to upload these large files to your app. Many
-users might not have a great internet connection, and if it happens to break at
-any point during uploading, they need to retry the upload from the beginning.
+See the [uppy-s3_multipart] docs for more details.
 
-This problem has been solved by **[tus]**. tus is an open protocol for
-resumable file uploads, which enables the client and the server to achieve
-reliable file uploads even on unstable connections, by enabling the upload to
-be resumed in case of interruptions, even after the browser was closed or the
-device was shut down.
+#### Tus protocol
 
-[tus-ruby-server] provides a Ruby server implemenation of the tus protocol.
-Uppy's [Tus][uppy tus] plugin can then be configured to do resumable uploads to
-a tus-ruby-server instance, and then the uploaded files can be attached to the
-record with the help of [shrine-tus]. See [this walkthrough][resumable uploads
-walkthrough] that adds resumable uploads from scratch, as well as the
-[demo][resumable demo] for a complete example.
+If you want a more generic approach, you can build your resumable uploads on
+**[tus]**, an open resumable upload protocol. On the server side you can use
+the [tus-ruby-server] gem, on the client side Uppy's [Tus][uppy tus] plugin,
+and the [shrine-tus] gem for the glue:
 
-Alternatively, you can have resumable uploads directly to S3 using Uppy's [AWS
-S3 Multipart][uppy aws s3 multipart] plugin, accompanied with the
-[uppy-s3_multipart] gem.
+```rb
+# Gemfile
+gem "tus-server", "~> 2.0"
+gem "shrine-tus", "~> 1.2"
+```
+```rb
+require "shrine/storage/tus"
+
+Shrine.storages = {
+  cache: Shrine::Storage::Tus.new, # tus server acts as temporary storage
+  store: ...,                      # your permanent storage
+}
+```
+```rb
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  # ...
+  mount Tus::Server => "/files"
+end
+```
+```js
+// upload.js
+// ...
+uppy.use(Uppy.Tus, {
+  endpoint:  '/files',
+  chunkSize: 5*1024*1024,
+})
+
+uppy.on('upload-success', (file, response) => {
+  const uploadedFileData = JSON.stringify({
+    id: response.uploadURL,
+    storage: "cache",
+    metadata: {
+      filename:  file.name,
+      size:      file.size,
+      mime_type: file.type,
+    }
+  })
+  // ... add this data to your form or submit it to your app ...
+})
+```
+
+For adding tus-powered resumable uploads from scratch, see [this
+walkthrough][Adding Resumable Uploads] (there is also a [demo app][resumable
+demo]). See also [shrine-tus] and [tus-ruby-server] docs for more details.
 
 ## Backgrounding
 
-Shrine is the first file attachment library designed for backgrounding support.
-Moving phases of managing file attachments to background jobs is essential for
-scaling and good user experience, and Shrine provides a `backgrounding` plugin
-which makes it easy to plug in your favourite backgrounding library:
+Shrine allows you to put file deletion and promotion of cached files to
+permanent storage into a background job. The [`backgrounding`][backgrounding
+plugin] plugin provides hooks for plugging in your [favourite backgrounding
+library][Backgrounding Libraries].
 
 ```rb
 Shrine.plugin :backgrounding
@@ -918,11 +940,6 @@ class DeleteJob
 end
 ```
 
-The above puts promoting (uploading cached file to permanent storage) and
-deleting of files for all uploaders into background jobs using Sidekiq.
-Obviously instead of Sidekiq you can use [any other backgrounding
-library][backgrounding libraries].
-
 ## Clearing cache
 
 Shrine doesn't automatically delete files uploaded to temporary storage, instead
@@ -943,47 +960,6 @@ s3 = Shrine.storages[:cache]
 s3.clear! { |object| object.last_modified < Time.now - 7*24*60*60 } # delete files older than 1 week
 ```
 
-Note that for AWS S3 you can also configure bucket lifecycle rules to do this
-for you. This can be done either from the [AWS Console][S3 lifecycle console]
-or via an [API call][S3 lifecycle API]:
-
-```rb
-require "aws-sdk-s3"
-
-client = Aws::S3::Client.new(
-  access_key_id:     "<YOUR KEY>",
-  secret_access_key: "<YOUR SECRET>",
-  region:            "<REGION>",
-)
-
-client.put_bucket_lifecycle_configuration(
-  bucket: "<YOUR BUCKET>",
-  lifecycle_configuration: {
-    rules: [{
-      expiration: { days: 7 },
-      filter: { prefix: "cache/" },
-      id: "cache-clear",
-      status: "Enabled"
-    }]
-  }
-)
-```
-
-## Logging
-
-Shrine ships with the `logging` which automatically logs processing, uploading,
-and deleting of files. This can be very helpful for debugging and performance
-monitoring.
-
-```rb
-Shrine.plugin :logging
-```
-```
-2015-10-09T20:06:06.676Z #25602: STORE[cache] ImageUploader[:avatar] User[29543] 1 file (0.1s)
-2015-10-09T20:06:06.854Z #25602: PROCESS[store]: ImageUploader[:avatar] User[29543] 1-3 files (0.22s)
-2015-10-09T20:06:07.133Z #25602: DELETE[destroyed]: ImageUploader[:avatar] User[29543] 3 files (0.07s)
-```
-
 ## Settings
 
 Each uploader can store generic settings in the `opts` hash, which can be
@@ -1030,62 +1006,111 @@ mailing lists is expected to follow the [Shrine code of conduct][CoC].
 
 The gem is available as open source under the terms of the [MIT License].
 
-[Shrine]: https://shrinerb.com
-[plugin system]: https://twin.github.io/the-plugin-system-of-sequel-and-roda/
+<!-- Guides & RDocs -->
+[Advantages of Shrine]: /doc/advantages.md#readme
+[Creating Plugins]: /doc/creating_plugins.md#readme
+[Creating Storages]: /doc/creating_storages.md#readme
+[Direct Uploads to S3]: /doc/direct_s3.md#readme
+[Extracting Metadata]: /doc/metadata.md#readme
+[File Processing]: /doc/processing.md#readme
+[File Validation]: /doc/validation.md#readme
+[Retrieving Uploads]: /doc/retrieving_uploads.md#readme
+[Using Attacher]: /doc/attacher.md#readme
 [FileSystem]: /doc/storage/file_system.md#readme
 [S3]: /doc/storage/s3.md#readme
-[GCS]: https://github.com/renchap/shrine-google_cloud_storage
+[`Shrine::UploadedFile`]: https://shrinerb.com/rdoc/classes/Shrine/UploadedFile/InstanceMethods.html
+
+<!-- Sections -->
+[attacher]: #attacher
+[attachment]: #attachment
+[backgrounding]: #backgrounding
+[direct uploads]: #direct-uploads
+[io abstraction]: #io-abstraction
+[location]: #location
+[metadata]: #metadata
+[on upload]: #processing-on-upload
+[on-the-fly]: #processing-on-the-fly
+[plugin system]: #plugin-system
+[simple upload]: #simple-direct-upload
+[presigned upload]: #presigned-direct-upload
+[resumable upload]: #resumable-direct-upload
+[storage]: #storage
+[uploaded file]: #uploaded-file
+[uploading]: #uploading
+[uploader]: #uploader
+[validation]: #validation
+
+<!-- Wikis -->
+[Adding Direct App Uploads]: https://github.com/shrinerb/shrine/wiki/Adding-Direct-App-Uploads
+[Adding Resumable Uploads]: https://github.com/shrinerb/shrine/wiki/Adding-Resumable-Uploads
+[Adding Direct S3 Uploads]: https://github.com/shrinerb/shrine/wiki/Adding-Direct-S3-Uploads
+[Backgrounding Libraries]: https://github.com/shrinerb/shrine/wiki/Backgrounding-Libraries
+[Mounting Endpoints]: https://github.com/shrinerb/shrine/wiki/Mounting-Endpoints
+
+<!-- Storage & Destinations -->
+[AWS S3]: https://aws.amazon.com/s3/
+[MinIO]: https://min.io/
+[DigitalOcean Spaces]: https://www.digitalocean.com/products/spaces/
 [Cloudinary]: https://github.com/shrinerb/shrine-cloudinary
-[Transloadit]: https://github.com/shrinerb/shrine-transloadit
-[activerecord plugin]: /doc/plugins/activerecord.md#readme
-[sequel plugin]: /doc/plugins/sequel.md#readme
-[hanami plugin]: https://github.com/katafrakt/hanami-shrine
-[mongoid plugin]: https://github.com/shrinerb/shrine-mongoid
+[GCS]: https://github.com/renchap/shrine-google_cloud_storage
+[uppy-s3_multipart]: https://github.com/janko/uppy-s3_multipart
+[tus-ruby-server]: https://github.com/janko/tus-ruby-server
+
+<!-- Direct Uploads -->
+[Uppy]: https://uppy.io
+[shrine-tus]: https://github.com/shrinerb/shrine-tus
+[tus]: https://tus.io
+[uppy aws-s3-multipart]: https://uppy.io/docs/aws-s3-multipart/
+[uppy aws-s3]: https://uppy.io/docs/aws-s3/
+[uppy tus]: https://uppy.io/docs/tus/
+[uppy xhr-upload]: https://uppy.io/docs/xhr-upload/
+
+<!-- Processing -->
+[ImageMagick]: https://imagemagick.org/
+[MiniMagick]: https://github.com/minimagick/minimagick
+[ruby-vips]: https://github.com/libvips/ruby-vips
 [ImageProcessing]: https://github.com/janko/image_processing
-[on upload]: #on-upload
-[on-the-fly]: #on-the-fly
 [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
-[ImageMagick]: https://imagemagick.org/
 [libvips]: http://libvips.github.io/libvips/
+[`file`]: http://linux.die.net/man/1/file
+
+<!-- Plugins -->
+[activerecord plugin]: /doc/plugins/activerecord.md#readme
+[add_metadata plugin]: /doc/plugins/add_metadata.md#readme
+[backgrounding plugin]: /doc/plugins/backgrounding.md#readme
 [derivation_endpoint plugin]: /doc/plugins/derivation_endpoint.md#readme
-[validation_helpers plugin]: /doc/plugins/validation_helpers.md#readme
-[upload_endpoint plugin]: /doc/plugins/upload_endpoint.md#readme
+[determine_mime_type plugin]: /doc/plugins/determine_mime_type.md#readme
+[hanami plugin]: https://github.com/katafrakt/hanami-shrine
+[mongoid plugin]: https://github.com/shrinerb/shrine-mongoid
 [presign_endpoint plugin]: /doc/plugins/presign_endpoint.md#readme
-[Uppy]: https://uppy.io
-[tus]: https://tus.io
-[uppy tus]: https://uppy.io/docs/tus/
-[tus-ruby-server]: https://github.com/janko/tus-ruby-server
-[backgrounding plugin]: /doc/plugins/backgrounding.md#readme
-[Advantages of Shrine]: /doc/advantages.md#readme
-[external storages]: https://shrinerb.com/#external
-[creating storage]: /doc/creating_storages.md#readme
-[creating plugin]: /doc/creating_plugins.md#readme
-[Retrieving Uploads]: /doc/retrieving_uploads.md#readme
-[Using Attacher]: /doc/attacher.md#readme
-[plugins]: https://shrinerb.com/#plugins
-[`file`]: http://linux.die.net/man/1/file
-[Extracting Metadata]: /doc/metadata.md#readme
-[File Processing]: /doc/processing.md#readme
-[File Validation]: /doc/validation.md#readme
-[metadata direct uploads]: /doc/metadata.md#direct-uploads
-[uppy xhr upload]: https://uppy.io/docs/xhr-upload/
-[direct uploads walkthrough]: https://github.com/shrinerb/shrine/wiki/Adding-Direct-App-Uploads
-[uppy aws s3]: https://uppy.io/docs/aws-s3/
-[direct S3 uploads walkthrough]: https://github.com/shrinerb/shrine/wiki/Adding-Direct-S3-Uploads<Paste>
-[direct S3 uploads guide]: /doc/direct_s3.md#readme
-[roda demo]: https://github.com/shrinerb/shrine/tree/master/demo
+[pretty_location plugin]: /doc/plugins/pretty_location.md#readme
+[processing plugin]: /doc/plugins/processing.md#readme
+[rack_file plugin]: /doc/plugins/rack_file.md#readme
+[sequel plugin]: /doc/plugins/sequel.md#readme
+[signature plugin]: /doc/plugins/signature.md#readme
+[store_dimensions plugin]: /doc/plugins/store_dimensions.md#readme
+[upload_endpoint plugin]: /doc/plugins/upload_endpoint.md#readme
+[validation_helpers plugin]: /doc/plugins/validation_helpers.md#readme
+[versions plugin]: /doc/plugins/versions.md#readme
+
+<!-- Demos -->
 [rails demo]: https://github.com/erikdahlstrand/shrine-rails-example
-[shrine-tus]: https://github.com/shrinerb/shrine-tus
-[uppy aws s3 multipart]: https://uppy.io/docs/aws-s3-multipart/
-[uppy-s3_multipart]: https://github.com/janko/uppy-s3_multipart
-[resumable uploads walkthrough]: https://github.com/shrinerb/shrine/wiki/Adding-Resumable-Uploads
+[roda demo]: https://github.com/shrinerb/shrine/tree/master/demo
 [resumable demo]: https://github.com/shrinerb/shrine-tus-demo
-[backgrounding libraries]: https://github.com/shrinerb/shrine/wiki/Backgrounding-Libraries
-[Mounting Endpoints]: https://github.com/shrinerb/shrine/wiki/Mounting-Endpoints
-[S3 lifecycle Console]: http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html
-[S3 lifecycle API]: https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Client.html#put_bucket_lifecycle_configuration-instance_method
-[Roda]: https://github.com/jeremyevans/roda
+
+<!-- Misc -->
+[`#read`]: https://ruby-doc.org/core/IO.html#method-i-read
+[`#eof?`]: https://ruby-doc.org/core/IO.html#method-i-eof
+[`#rewind`]: https://ruby-doc.org/core/IO.html#method-i-rewind
+[`#close`]: https://ruby-doc.org/core/IO.html#method-i-close
+[`IO`]: https://ruby-doc.org/core/IO.html
 [Refile]: https://github.com/refile/refile
+[Roda]: https://github.com/jeremyevans/roda
+
+<!-- Project -->
+[Shrine]: https://shrinerb.com
+[external]: https://shrinerb.com/#external
+[plugins]: https://shrinerb.com/#plugins
 [CoC]: CODE_OF_CONDUCT.md
 [MIT License]: http://opensource.org/licenses/MIT