shrine 3.0.0.rc → 3.0.0

data/doc/creating_plugins.md

@@ -1,6 +1,13 @@
-# Writing a Plugin
+---
+id: creating-plugins
+title: Writing a Plugin
+---
+
+Shrine has a lot of plugins built-in, but you can use Shrine's plugin system to
+create your own.
+
+## Definition
 
-Shrine has a lot of plugins built-in, but you can also easily create your own.
 Simply put, a plugin is a module:
 
 ```rb
@@ -11,9 +18,9 @@ end
 Shrine.plugin MyPlugin
 ```
 
-If you would like to load plugins with a symbol, like you already load plugins
-that ship with Shrine, you need to put the plugin in
-`shrine/plugins/my_plugin.rb` in the load path, and register it:
+If you would like to load plugins with a symbol (like you already do with
+plugins that ship with Shrine), you need to put the plugin in
+`shrine/plugins/my_plugin.rb` in your load path and register it:
 
 ```rb
 # shrine/plugins/my_plugin.rb
@@ -31,6 +38,8 @@ end
 Shrine.plugin :my_plugin
 ```
 
+## Methods
+
 The way to make plugins actually extend Shrine's core classes is by defining
 special modules inside the plugin. Here's a list of all "special" modules:
 
@@ -51,7 +60,7 @@ uploading:
 ```rb
 module MyPlugin
   module InstanceMethods
-    def upload(io, context)
+    def upload(io, **options)
       time = Time.now
       result = super
       duration = Time.now - time
@@ -61,40 +70,51 @@ module MyPlugin
 end
 ```
 
-Notice that we can call `super` to get the original behaviour. In addition to
-these modules, you can also make your plugin configurable:
+Notice that we can call `super` to get the original behaviour.
 
-```rb
-Shrine.plugin :my_plugin, foo: "bar"
-```
+## Configuration
 
-You can do this by adding a `.configure` method to your plugin, which will be
-given any passed in arguments or blocks. Typically you'll want to save these
-options into Shrine's `opts`, so that you can access them inside of Shrine's
-methods.
+You'll likely want to make your plugin configurable. You can do that by
+overriding the `.configure` class method and storing received options into
+`Shrine.opts`:
 
 ```rb
 module MyPlugin
-  def self.configure(uploader, options = {})
-    uploader # The uploader class which called `.plugin`
-    uploader.opts[:my_plugin_options] = options
+  def self.configure(uploader, **opts)
+    uploader.opts[:my_plugin] ||= {}
+    uploader.opts[:my_plugin].merge!(opts)
   end
 
   module InstanceMethods
-    def foo
-      opts[:my_plugin_options] #=> {foo: "bar"}
+    def upload(io, **options)
+      opts[:my_plugin] #=> { ... }
+      # ...
     end
   end
 end
 ```
 
+Users can now pass these configuration options when loading your plugin:
+
+```rb
+Shrine.plugin :my_plugin, foo: "bar"
+```
+
+## Dependencies
+
 If your plugin depends on other plugins, you can load them inside of
-`.load_dependencies` (which is given the same arguments as `.configure`):
+`.load_dependencies`:
 
 ```rb
 module MyPlugin
-  def self.load_dependencies(uploader, *)
+  def self.load_dependencies(uploader, **opts)
     uploader.plugin :derivatives # depends on the derivatives plugin
   end
 end
 ```
+
+The dependencies will get loaded before your plugin, allowing you to override
+methods of your dependencies in your method modules.
+
+The same configuration options passed to `.configure` are passed to
+`.load_dependencies` as well.

data/doc/creating_storages.md

@@ -1,4 +1,7 @@
-# Writing a Storage
+---
+id: creating-storages
+title: Writing a Storage
+---
 
 Shrine ships with the FileSystem and S3 storages, but it's also easy to create
 your own. A storage is a class which needs to implement `#upload`, `#url`,

data/doc/design.md

@@ -1,4 +1,6 @@
-# The Design of Shrine
+---
+title: The Design of Shrine
+---
 
 *If you want an in-depth walkthrough through the Shrine codebase, see [Notes on study of shrine implementation] article by Jonathan Rochkind.*
 
@@ -187,8 +189,8 @@ Shrine::Attachment.new(:image).instance_methods #=> [:image=, :image, :image_url
 
 # equivalents
 Shrine::Attachment.new(:image)
+Shrine::Attachment[:image]
 Shrine::Attachment(:image)
-Shrine[:image]
 ```
 
 We can include this module to a model:
@@ -206,7 +208,7 @@ photo.image_url    # shorthand for `photo.image_attacher.url`
 photo.image_attacher #=> #<Shrine::Attacher>
 ```
 
-When an ORM plugin is loaded, the `Shrine::Attachment` module also
+When a persistence plugin is loaded, the `Shrine::Attachment` module also
 automatically:
 
 * syncs Shrine's validation errors with the record
@@ -214,7 +216,7 @@ automatically:
 * deletes the uploaded file if attachment was replaced/removed or the record
   destroyed
 
-[Using Attacher]: /doc/attacher.md#readme
+[Using Attacher]: https://shrinerb.com/docs/attacher
 [Notes on study of shrine implementation]: https://bibwild.wordpress.com/2018/09/12/notes-on-study-of-shrine-implementation/
-[Creating a New Plugin]: /doc/creating_plugins.md#readme
+[Creating a New Plugin]: https://shrinerb.com/docs/creating-plugins
 [Plugin system of Sequel and Roda]: https://twin.github.io/the-plugin-system-of-sequel-and-roda/

data/doc/direct_s3.md

@@ -1,4 +1,7 @@
-# Direct Uploads to S3
+---
+id: direct-s3
+title: Direct Uploads to S3
+---
 
 Shrine gives you the ability to upload files directly to Amazon S3 (or any
 other storage service that accepts direct uploads). Uploading directly to a
@@ -23,12 +26,14 @@ storage service is beneficial for several reasons:
   request-response lifecycle might not be able to finish before the request
   times out.
 
+## Storage
+
 To start, let's set both temporary and permanent storage to S3, with the
 temporary storage uploading to the `cache/` prefix:
 
 ```rb
 # Gemfile
-gem "shrine", "~> 2.11"
+gem "shrine", "~> 3.0"
 gem "aws-sdk-s3", "~> 1.14"
 ```
 ```rb
@@ -375,6 +380,6 @@ setup] guide.
 [lifecycle Console]: http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html
 [lifecycle API]: https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Client.html#put_bucket_lifecycle_configuration-instance_method
 [Minio]: https://minio.io
-[minio setup]: /doc/testing.md#minio
-[metadata direct uploads]: /doc/metadata.md#direct-uploads
+[minio setup]: https://shrinerb.com/docs/testing#minio
+[metadata direct uploads]: https://shrinerb.com/docs/metadata#direct-uploads
 [content_disposition]: https://github.com/shrinerb/content_disposition

data/doc/external/articles.md

@@ -0,0 +1,50 @@
+---
+title: Articles
+---
+
+## Official articles
+
+* [Introducing Shrine](http://twin.github.io/introducing-shrine)
+* [Asynchronous File Uploads](http://twin.github.io/file-uploads-asynchronous-world)
+* [Shrine 2.0 Released](https://twin.github.io/shrine-2-0-released/)
+* [Shrine meets Transloadit](https://twin.github.io/shrine-meets-transloadit/)
+* [Resumable File Uploads in Ruby](https://twin.github.io/resumable-file-uploads-in-ruby/)
+* [Adding Direct S3 Uploads to a Roda App with Shrine](https://github.com/shrinerb/shrine/wiki/Adding-Direct-S3-Uploads)
+* [Adding Resumable Uploads to a Roda App with Shrine](https://github.com/shrinerb/shrine/wiki/Adding-Resumable-Uploads)
+* [Better File Uploads with Shrine: Motivation](https://twin.github.io/better-file-uploads-with-shrine-motivation/)
+* [Better File Uploads with Shrine: Uploader](https://twin.github.io/better-file-uploads-with-shrine-uploader/)
+* [Better File Uploads with Shrine: Attachment](https://twin.github.io/better-file-uploads-with-shrine-attachment/)
+* [Better File Uploads with Shrine: Processing](https://twin.github.io/better-file-uploads-with-shrine-processing/)
+* [Better File Uploads with Shrine: Metadata](https://twin.github.io/better-file-uploads-with-shrine-metadata/)
+* [Better File Uploads with Shrine: Direct Uploads](https://twin.github.io/better-file-uploads-with-shrine-direct-uploads)
+
+## Other Articles
+
+* [Uploading files with Shrine in Hanami](http://katafrakt.me/2016/02/04/shrine-hanami-uploads/)
+* [Rails File Uploading You Can Believe in with Shrine](http://www.sitepoint.com/rails-file-uploading-you-can-believe-in-with-shrine/)
+* [Uploading Files With Rails and Shrine](https://code.tutsplus.com/tutorials/uploading-files-with-rails-and-shrine--cms-27596)
+* [Upload images using Shrine.rb and Dropzone.js](https://codyeatworld.com/2017/04/18/rails-uploading-images-confidently-with-shrine-rb/)
+* [Background file uploads to S3 using Shrine](http://elixirator.com/blog/2017/background-file-uploads-to-s3-using-shrine.html)
+* [Rails + Shrine + DropzoneJS](https://stephencodes.com/rails-5-shrine-dropzonejs/)
+* [Uploading Files with Rails and ActionCable](https://scotch.io/tutorials/uploading-files-with-rails-and-actioncable)
+* [Creating Streaming Radio With Rails and Icecast](https://scotch.io/tutorials/creating-online-streaming-radio-with-rails-and-icecast)
+* [Multiple Photo Upload using Shrine](https://github.com/pyksoft/multi-photo-upload#multiple-photo-upload-using-shrine)
+* [Store Your Files on S3: Setup & Configuration](https://www.ironin.it/blog/store-your-files-on-s3-using-the-ruby-shrine-gem-part-1.html)
+* [Store Your Files on S3: Direct Uploads](https://www.ironin.it/blog/store-your-files-on-s3-using-the-ruby-shrine-gem-part-2.html)
+* [Store Your Files on S3: Uploading from a URL](https://www.ironin.it/blog/store-your-files-on-s3-using-the-ruby-shrine-gem-part-3.html)
+* [How to use Trix and Shrine for WYSIWYG Editing with Drag-and-Drop Image Uploading](http://headway.io/blog/how-to-use-trix-and-shrine-for-wysiwyg-editing-with-drag-and-drop-image-uploading/)
+* [Happy users uploading files with Rails 5, Shrine, and Vue.js](https://itnext.io/happy-users-uploading-files-with-rails-5-shrine-and-vue-js-bbcc470a327f)
+* [Notes on study of shrine implementation](https://bibwild.wordpress.com/2018/09/12/notes-on-study-of-shrine-implementation/)
+* [GraphQL file upload with Shrine](https://blog.stanko.io/graphql-file-upload-with-shrine-45fa26463c68)
+
+## Videos
+
+* [wroc_love.rb – Handling file uploads for a modern developer](https://www.youtube.com/watch?v=fP2JGjTZU2s)
+* [File Uploads in Rails with Shrine (GoRails)](https://gorails.com/episodes/file-uploading-with-shrine?autoplay=1)
+* [Direct File Uploads to S3: Part 1 (GoRails)](https://gorails.com/episodes/direct-file-uploads-to-s3-part-1?autoplay=1)
+* [Direct File Uploads to S3: Part 2 (GoRails)](https://gorails.com/episodes/direct-file-uploads-to-s3-part-2?autoplay=1)
+* [Direct File Uploads to S3: Part 3 (GoRails)](https://gorails.com/episodes/direct-file-uploads-to-s3-part-3?autoplay=1)
+* [Backgrounding and Video Transcoding (GoRails)](https://gorails.com/episodes/shrine-background-and-video-transcoding?autoplay=1)
+* [Multiple File Uploads with Shrine (GoRails)](https://gorails.com/episodes/multiple-file-uploads-with-shrine?autoplay=1)
+* [Trix WYSIWYG Editor And File Uploads (GoRails)](https://gorails.com/episodes/trix-editor?autoplay=1)
+* [Uploading Files to DigitalOcean Spaces (GoRails)](https://gorails.com/episodes/digital-ocean-spaces-with-rails?autoplay=1)

data/doc/external/extensions.md

@@ -0,0 +1,46 @@
+---
+title: Extensions
+---
+
+## Storages
+
+* [shrine-aliyun-oss](https://github.com/zillou/shrine-aliyun-oss)
+* [shrine-cloudinary](https://github.com/shrinerb/shrine-cloudinary)
+* [shrine-flickr](https://github.com/shrinerb/shrine-flickr)
+* [shrine-fog](https://github.com/shrinerb/shrine-fog)
+* [shrine-ftp](https://github.com/ProjectResound/shrine-ftp)
+* [shrine-google_cloud_storage](https://github.com/renchap/shrine-google_cloud_storage)
+* [shrine-gdrive_storage](https://github.com/edwardsharp/shrine-gdrive_storage)
+* [shrine-gridfs](https://github.com/shrinerb/shrine-gridfs)
+* [shrine-imgix](https://github.com/shrinerb/shrine-imgix)
+* [shrine-memory](https://github.com/shrinerb/shrine-memory)
+* [shrine-redis](https://github.com/dbongo/shrine-redis)
+* [shrine-scp](https://github.com/jordanandree/shrine-scp)
+* [shrine-sql](https://github.com/shrinerb/shrine-sql)
+* [shrine-thumbor](https://github.com/havran/shrine-thumbor)
+* [shrine-transloadit](https://github.com/shrinerb/shrine-transloadit)
+* [shrine-uploadcare](https://github.com/shrinerb/shrine-uploadcare)
+* [shrine-url](https://github.com/shrinerb/shrine-url)
+* [shrine-storage-you_tube](https://github.com/thedyrt/shrine-storage-you_tube)
+* [shrine-webdav](https://github.com/funbox/shrine-webdav)
+
+## Plugins
+
+* [administrate-field-shrine](https://github.com/catsky/administrate-field-shrine)
+* [rails_admin_shrine](https://github.com/iquest/rails_admin_shrine)
+* [shrine-color](https://github.com/jnylen/shrine-color)
+* [shrine-configurable_storage](https://github.com/SleeplessByte/shrine-configurable_storage)
+* [shrine-content_addressable](https://github.com/SleeplessByte/shrine-content_addressable)
+* [shrine-lambda](https://github.com/texpert/shrine-lambda)
+* [hanami-shrine](https://github.com/katafrakt/hanami-shrine)
+* [shrine-mongoid](https://github.com/shrinerb/shrine-mongoid)
+* [shrine-rails](https://github.com/abepetrillo/shrine-rails)
+* [shrine-reform](https://github.com/shrinerb/shrine-reform)
+* [shrine-tus](https://github.com/shrinerb/shrine-tus)
+
+## Libraries
+
+* [ckeditor](https://github.com/galetahub/ckeditor)
+* [imgproxy](https://github.com/imgproxy/imgproxy.rb)
+* [rails_admin](https://github.com/sferik/rails_admin)
+* [uppy-s3_multipart](https://github.com/janko/uppy-s3_multipart)

data/doc/external/misc.md

@@ -0,0 +1,17 @@
+---
+title: Miscellaneous
+---
+
+## Demos
+
+* [Dropzone demo](https://github.com/codyeatworld/example-shrine-dropzone)
+* [Hanami demo](https://github.com/katafrakt/hanami-shrine-example)
+* [Rails demo](https://github.com/erikdahlstrand/shrine-rails-example)
+* [Resumable uploads demo](https://github.com/shrinerb/shrine-tus-demo)
+* [Roda demo (official)](https://github.com/shrinerb/shrine/tree/master/demo)
+* [ROM & dry-rb demo](https://github.com/shrinerb/shrine-rom/tree/master/demo)
+* [Transloadit demo](https://github.com/shrinerb/shrine-transloadit/tree/master/demo)
+
+## Projects
+
+* [Cortex CMS](https://docs.cortexcms.org)

data/doc/getting_started.md

@@ -0,0 +1,1038 @@
+---
+id: getting-started
+title: Getting Started
+---
+
+## Quick start
+
+Add Shrine to the Gemfile and write an initializer which sets up the storage
+and loads integration for your persistence library:
+
+```rb
+# Gemfile
+gem "shrine", "~> 3.0"
+```
+
+```rb
+require "shrine"
+require "shrine/storage/file_system"
+
+Shrine.storages = {
+  cache: Shrine::Storage::FileSystem.new("public", prefix: "uploads/cache"), # temporary
+  store: Shrine::Storage::FileSystem.new("public", prefix: "uploads"),       # permanent
+}
+
+Shrine.plugin :sequel # or :activerecord
+Shrine.plugin :cached_attachment_data # for retaining the cached file across form redisplays
+Shrine.plugin :restore_cached_data # re-extract metadata when attaching a cached file
+Shrine.plugin :rack_file # for non-Rails apps
+```
+
+Next decide how you will name the attachment attribute on your model, and run a
+migration that adds an `<attachment>_data` text or JSON column, which Shrine
+will use to store all information about the attachment:
+
+<!--DOCUSAURUS_CODE_TABS-->
+<!--Sequel-->
+```rb
+Sequel.migration do
+  change do
+    add_column :photos, :image_data, :text # or :jsonb
+  end
+end
+```
+<!--ActiveRecord-->
+```rb
+class AddImageDataToPhotos < ActiveRecord::Migration
+  def change
+    add_column :photos, :image_data, :text # or :jsonb
+  end
+end
+```
+<!--Rails-->
+```sh
+$ rails generate migration add_image_data_to_photos image_data:text
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+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. If you do not care about adding plugins or additional processing,
+you can use `Shrine::Attachment`.
+
+```rb
+class ImageUploader < Shrine
+  # plugins and uploading logic
+end
+```
+<!--DOCUSAURUS_CODE_TABS-->
+<!--Sequel-->
+```rb
+class Photo < Sequel::Model
+  include ImageUploader::Attachment(:image) # adds an `image` virtual attribute
+end
+```
+<!--ActiveRecord-->
+```rb
+class Photo < ActiveRecord::Base
+  include ImageUploader::Attachment(:image) # adds an `image` virtual attribute
+end
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+Let's now add the form fields which will use this virtual attribute (NOT the
+`<attachment>_data` column 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].
+
+<!--DOCUSAURUS_CODE_TABS-->
+<!--Rails form builder-->
+```rb
+form_for @photo do |f|
+  f.hidden_field :image, value: @photo.cached_image_data
+  f.file_field :image
+  f.submit
+end
+```
+<!--Simple Form-->
+```rb
+simple_form_for @photo do |f|
+  f.input :image, as: :hidden, input_html: { value: @photo.cached_image_data }
+  f.input :image, as: :file
+  f.button :submit
+end
+```
+<!--Forme-->
+```rb
+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
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+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).
+
+When the form is submitted, in your router/controller you can assign the file
+from request params to the attachment attribute on the model.
+
+<!--DOCUSAURUS_CODE_TABS-->
+<!--Rails-->
+```rb
+class PhotosController < ApplicationController
+  def create
+    Photo.create(photo_params)
+    # ...
+  end
+
+  private
+
+  def photo_params
+    params.require(:photo).permit(:image)
+  end
+end
+```
+<!--Sinatra-->
+```rb
+post "/photos" do
+  Photo.create(params[:photo])
+  # ...
+end
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+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:
+
+<!--DOCUSAURUS_CODE_TABS-->
+<!--Rails-->
+```erb
+<%= image_tag @photo.image_url %>
+```
+<!--HTML-->
+```erb
+<img src="<%= @photo.image_url %>" />
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+## Storage
+
+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 be 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.14" # for AWS S3 storage
+```
+```rb
+require "shrine/storage/s3"
+
+s3_options = {
+  bucket:            "<YOUR BUCKET>", # required
+  access_key_id:     "<YOUR ACCESS KEY ID>",
+  secret_access_key: "<YOUR SECRET ACCESS KEY>",
+  region:            "<YOUR REGION>",
+}
+
+Shrine.storages = {
+  cache: Shrine::Storage::S3.new(prefix: "cache", **s3_options),
+  store: Shrine::Storage::S3.new(**s3_options),
+}
+```
+
+The above example sets up S3 for both temporary and permanent storage, which is
+suitable for [direct uploads][presigned upload]. 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.
+
+See the [FileSystem] and [S3] storage docs for more details. There are [many
+more Shrine storages][storages] provided by external gems, and you can also
+[create your own storage][Creating Storages].
+
+## Uploader
+
+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 MyUploader < Shrine
+  # image attachment logic
+end
+```
+
+It's common to create an uploader for each type of file that you want to handle
+(`ImageUploader`, `VideoUploader`, `AudioUploader` etc), but really you can
+organize them in any way you like.
+
+### Uploading
+
+The main method of the uploader is `Shrine.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
+MyUploader.upload(file, :store) #=> #<Shrine::UploadedFile>
+```
+
+Internally this instantiates the uploader with the storage and calls
+`Shrine#upload`:
+
+```rb
+uploader = MyUploader.new(:store)
+uploader.upload(file) #=> #<Shrine::UploadedFile>
+```
+
+Some of the tasks performed by `#upload` include:
+
+* extracting [metadata]
+* generating [location]
+* uploading (this is where the [storage] is called)
+* closing the uploaded file
+
+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(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 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, 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 be converted into an IO-like object
+with the [`rack_file`][rack_file plugin] plugin.
+
+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 Shrine::UploadedFile.new(...)               # upload from Shrine storage
+```
+
+## Uploaded file
+
+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:
+
+| 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::S3>
+uploaded_file.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 { |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][io abstraction], which allows it to be uploaded again to other
+storages.
+
+```rb
+uploaded_file.read   # returns content of the uploaded file
+uploaded_file.eof?   # returns true if the whole IO was read
+uploaded_file.rewind # rewinds the IO
+uploaded_file.close  # closes the IO
+```
+
+For more details, see the [Retrieving Uploads] guide and
+[`Shrine::UploadedFile`] API docs.
+
+## Attaching
+
+To attach uploaded files to database records, Shrine offers an attachment
+interface built on top of uploaders and uploaded files. There are integrations
+for various persistence libraries ([ActiveRecord][activerecord plugin],
+[Sequel][sequel plugin], [ROM][rom plugin], [Hanami][hanami plugin],
+[Mongoid][mongoid plugin]), but you can also attach files to plain structs
+([mutable][model plugin] or [immutable][entity plugin]).
+
+```rb
+Shrine.plugin :sequel # :activerecord
+```
+
+### Attachment module
+
+The easiest way to attach files is with the `Shrine::Attachment` module:
+
+```rb
+class Photo < Sequel::Model # ActiveRecord::Base
+  include ImageUploader::Attachment.new(:image) #
+  include ImageUploader::Attachment[:image]     # use a preferred syntax
+  include ImageUploader::Attachment(:image)     #
+end
+```
+
+The included module will add attachment methods for the specified attribute:
+
+| 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 persistence plugin we loaded will add callbacks that ensure cached files
+are automatically promoted to permanent storage on when record is saved, and
+that attachments are deleted when the record is destroyed.
+
+```rb
+# no file is attached
+photo.image #=> nil
+
+# the assigned file is cached to temporary storage and written to `image_data` column
+photo.image = File.open("waterfall.jpg")
+photo.image      #=> #<Shrine::UploadedFile @data={...}>
+photo.image_url  #=> "/uploads/cache/0sdfllasfi842.jpg"
+photo.image_data #=> '{"id":"0sdfllasfi842.jpg","storage":"cache","metadata":{...}}'
+
+# the cached file is promoted to permanent storage and saved to `image_data` column
+photo.save
+photo.image      #=> #<Shrine::UploadedFile @data={...}>
+photo.image_url  #=> "/uploads/store/l02kladf8jlda.jpg"
+photo.image_data #=> '{"id":"l02kladf8jlda.jpg","storage":"store","metadata":{...}}'
+
+# the attached file is deleted with the record
+photo.destroy
+photo.image.exists? #=> false
+```
+
+If there is already a file attached and a new file is attached, the previous
+attachment will get deleted when the record gets saved.
+
+```rb
+photo.update(image: new_file) # changes the attachment and deletes previous
+photo.update(image: nil)      # removes the attachment and deletes previous
+```
+
+### Attacher
+
+The methods and callbacks added by the `Shrine::Attachment` module just
+delegate the behaviour to an underlying `Shrine::Attacher` object.
+
+```rb
+photo.image_attacher #=> #<Shrine::Attacher>
+```
+
+The `Shrine::Attacher` object can be instantiated and used directly:
+
+```rb
+attacher = ImageUploader::Attacher.from_model(photo, :image)
+
+attacher.assign(file) # equivalent to `photo.image = file`
+attacher.file         # equivalent to `photo.image`
+attacher.url          # equivalent to `photo.image_url`
+```
+
+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.
+
+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.
+
+### Temporary storage
+
+Shrine uses temporary storage to support retaining uploaded files across form
+redisplays and [direct uploads]. But you can disable this behaviour, and have
+files go straight to permanent storage:
+
+```rb
+Shrine.plugin :model, cache: false
+```
+<!--DOCUSAURUS_CODE_TABS-->
+<!--Attachment-->
+```rb
+photo.image = File.open("waterfall.jpg")
+photo.image.storage_key #=> :store
+```
+<!--Attacher-->
+```rb
+attacher.attach File.open("waterfall.jpg")
+attacher.file.storage_key #=> :store
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+## Plugin system
+
+By default Shrine comes with a small core which provides only the essential
+functionality. All additional features are available via [plugins], which also
+ship with Shrine. This way you can choose exactly what and how much Shrine does
+for you, and you load the code only for features that you use.
+
+```rb
+Shrine.plugin :instrumentation # adds instrumentation
+```
+
+Plugins add behaviour by extending Shrine core classes via module inclusion, and
+many of them also accept configuration options. The plugin system respects
+inheritance, so you can choose to load a plugin globally or per uploader.
+
+```rb
+class ImageUploader < Shrine
+  plugin :store_dimensions # extract image dimensions only for this uploader and its descendants
+end
+```
+
+If you want to extend Shrine functionality with custom behaviour, you can also
+[create your own plugin][Creating Plugins]. There are also additional [external
+plugins] created by others.
+
+## Metadata
+
+Shrine automatically extracts some basic file metadata and saves them to the
+`Shrine::UploadedFile`. You can access them through the `#metadata` hash or via
+metadata methods:
+
+```rb
+uploaded_file.metadata #=>
+# {
+#   "filename" => "matrix.mp4",
+#   "mime_type" => "video/mp4",
+#   "size" => 345993,
+# }
+
+uploaded_file.original_filename #=> "matrix.mp4"
+uploaded_file.extension         #=> "mp4"
+uploaded_file.mime_type         #=> "video/mp4"
+uploaded_file.size              #=> 345993
+```
+
+### MIME type
+
+By default, `mime_type` metadata will be set from the `#content_type` attribute
+of the uploaded file (if it exists), 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
+# Gemfile
+gem "marcel", "~> 0.3"
+```
+```rb
+Shrine.plugin :determine_mime_type, analyzer: :marcel
+```
+```rb
+photo = Photo.create(image: StringIO.new("<?php ... ?>"))
+photo.image.mime_type #=> "application/x-php"
+```
+
+### Other metadata
+
+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 process attached files up front 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.
+
+For image processing, it's recommended to use the **[ImageProcessing]** gem,
+which is a high-level wrapper for processing with
+[MiniMagick][ImageProcessing::MiniMagick] and [libvips][ImageProcessing::Vips].
+
+```sh
+$ brew install imagemagick vips
+```
+
+### Processing up front
+
+You can use the [`derivatives`][derivatives plugin] plugin to generate a set of
+pre-defined processed files:
+
+```rb
+# Gemfile
+gem "image_processing", "~> 1.8"
+```
+```rb
+Shrine.plugin :derivatives
+```
+```rb
+require "image_processing/mini_magick"
+
+class ImageUploader < Shrine
+  Attacher.derivatives_processor do |original|
+    magick = ImageProcessing::MiniMagick.source(original)
+
+    {
+      large:  magick.resize_to_limit!(800, 800),
+      medium: magick.resize_to_limit!(500, 500),
+      small:  magick.resize_to_limit!(300, 300),
+    }
+  end
+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 trigger derivatives creation for new attachments:
+
+```rb
+photo.image_derivatives! if photo.image_changed?
+```
+
+After the processed files are uploaded, their data is saved into the
+`<attachment>_data` column. You can then retrieve the derivatives as
+[`Shrine::UploadedFile`][uploaded file] objects:
+
+```rb
+photo.image(:large)            #=> #<Shrine::UploadedFile ...>
+photo.image(:large).url        #=> "/uploads/store/lg043.jpg"
+photo.image(:large).size       #=> 5825949
+photo.image(:large).mime_type  #=> "image/jpeg"
+```
+
+For more details, see the [`derivatives`][derivatives plugin] plugin
+documentation and the [File Processing] guide.
+
+### Processing on-the-fly
+
+On-the-fly processing is provided by the
+[`derivation_endpoint`][derivation_endpoint plugin] plugin. It comes with a
+[mountable][Mounting Endpoints] Rack app which applies processing on request
+and returns processed files.
+
+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:
+
+```rb
+# Gemfile
+gem "image_processing", "~> 1.8"
+```
+```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" # needs to match the mount point in routes
+
+  derivation :thumbnail do |file, width, height|
+    ImageProcessing::MiniMagick
+      .source(file)
+      .resize_to_limit!(width.to_i, height.to_i)
+  end
+end
+```
+
+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 on-the-fly processing feature is highly customizable, see the
+[`derivation_endpoint`][derivation_endpoint plugin] plugin documentation for
+more details.
+
+## Validation
+
+The [`validation`][validation plugin] plugin allows performing validation for
+attached files. For common validations, the
+[`validation_helpers`][validation_helpers plugin] plugin provides useful
+validators for built in metadata:
+
+```rb
+Shrine.plugin :validation_helpers
+```
+```rb
+class DocumentUploader < Shrine
+  Attacher.validate do
+    validate_max_size 5*1024*1024, message: "is too large (max is 5 MB)"
+    validate_mime_type %w[application/pdf]
+  end
+end
+```
+
+```rb
+user = User.new
+user.cv = File.open("cv.pdf", "rb")
+user.valid? #=> false
+user.errors.to_hash #=> {:cv=>["is too large (max is 5 MB)"]}
+```
+
+For more details, see the [File Validation] guide and
+[`validation_helpers`][validation_helpers plugin] plugin docs.
+
+## Location
+
+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
+  def generate_location(io, record: nil, derivative: nil, **)
+    type  = record.class.name.downcase if record
+    style = derivative ? "thumbs" : "originals"
+    name  = super # the default unique identifier
+
+    [type, style, name].compact.join("/")
+  end
+end
+```
+```plaintext
+uploads/
+  photos/
+    originals/
+      la98lda74j3g.jpg
+    thumbs/
+      95kd8kafg80a.jpg
+      ka8agiaf9gk4.jpg
+```
+
+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 the `:metadata` option.
+
+## Direct uploads
+
+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. Then, instead of attaching a raw
+file to your model, you assign the cached file JSON data.
+
+```rb
+# in the regular synchronous flow
+photo.image = file
+
+# in the direct upload flow
+photo.image = '{"id":"...","storage":"cache","metadata":{...}}'
+```
+
+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 to upload directly to an endpoint in your app, which
+forwards uploads to the specified storage. The
+[`upload_endpoint`][upload_endpoint plugin] Shrine plugin provides a
+[mountable][Mounting Endpoints] Rack app that implements this endpoint:
+
+```rb
+Shrine.plugin :upload_endpoint
+```
+```rb
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  # ...
+  mount ImageUploader.upload_endpoint(:cache) => "/images/upload" # POST /images/upload
+end
+```
+
+Then you can configure Uppy's [XHR Upload][uppy xhr-upload] plugin to upload to
+this endpoint. See [this walkthrough][Adding Direct App Uploads] for adding
+simple direct uploads from scratch, it includes a complete JavaScript example
+(there is also the [Roda][roda demo] / [Rails][rails demo] demo app).
+
+### Presigned direct 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:
+
+```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 app that generates upload parameters:
+
+```rb
+Shrine.plugin :presign_endpoint
+```
+```rb
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  # ...
+  mount Shrine.presign_endpoint(:cache) => "/s3/params" # GET /s3/params
+end
+```
+
+Then you can configure Uppy's [AWS S3][uppy aws-s3] plugin to fetch params from
+your endpoint before uploading to S3. See [this walkthrough][Adding Direct S3
+Uploads] for adding direct uploads to S3 from scratch, it includes a complete
+JavaScript example (there is also the [Roda][roda demo] / [Rails][rails demo]
+demo). See also the [Direct Uploads to S3] guide for more details.
+
+### Resumable direct upload
+
+If your app is accepting large uploads, you can improve resilience by making
+the uploads **resumable**. This can significantly improve experience for users
+on slow and flaky internet connections.
+
+#### Uppy S3 Multipart
+
+You can achieve resumable uploads directly to S3 with the [AWS S3
+Multipart][uppy aws-s3-multipart] Uppy plugin, accompanied with
+`uppy_s3_multipart` Shrine plugin provided by the [uppy-s3_multipart] gem.
+
+```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
+```
+
+See the [uppy-s3_multipart] docs for more details.
+
+#### Tus protocol
+
+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.
+
+```rb
+# Gemfile
+gem "tus-server", "~> 2.0"
+gem "shrine-tus", "~> 2.1"
+```
+```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
+```
+
+See [this walkthrough][Adding Resumable Uploads] for adding tus-powered
+resumable uploads from scratch, it includes a complete JavaScript example
+(there is also a [demo app][resumable demo]). See also [shrine-tus] and
+[tus-ruby-server] docs for more details.
+
+## Backgrounding
+
+The [`backgrounding`][backgrounding plugin] allows you to move file promotion
+and deletion into a background job, using the backgrounding library [of your
+choice][Backgrounding Libraries]:
+
+```rb
+Shrine.plugin :backgrounding
+Shrine::Attacher.promote_block do
+  PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
+end
+Shrine::Attacher.destroy_block do
+  DestroyJob.perform_async(self.class.name, data)
+end
+```
+```rb
+class PromoteJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record.id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
+    attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
+    attacher.atomic_promote
+  rescue Shrine::AttachmentChanged, ActiveRecord::RecordNotFound
+    # attachment has changed or the record has been deleted, nothing to do
+  end
+end
+```
+```rb
+class DestroyJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, data)
+    attacher_class = Object.const_get(attacher_class)
+
+    attacher = attacher_class.from_data(data)
+    attacher.destroy
+  end
+end
+```
+
+## Clearing cache
+
+Shrine doesn't automatically delete files uploaded to temporary storage, instead
+you should set up a separate recurring task that will automatically delete old
+cached files.
+
+Most Shrine storage classes come with a `#clear!` method, which you can call in
+a recurring script. For FileSystem and S3 storage it would look like this:
+
+```rb
+# FileSystem storage
+file_system = Shrine.storages[:cache]
+file_system.clear! { |path| path.mtime < Time.now - 7*24*60*60 } # delete files older than 1 week
+```
+```rb
+# S3 storage
+s3 = Shrine.storages[:cache]
+s3.clear! { |object| object.last_modified < Time.now - 7*24*60*60 } # delete files older than 1 week
+```
+
+## Logging
+
+The [`instrumentation`][instrumentation plugin] plugin sends and logs events for
+important operations:
+
+```rb
+Shrine.plugin :instrumentation, notifications: ActiveSupport::Notifications
+
+uploaded_file = Shrine.upload(io, :store)
+uploaded_file.exists?
+uploaded_file.download
+uploaded_file.delete
+```
+```plaintext
+Metadata (32ms) – {:storage=>:store, :io=>StringIO, :uploader=>Shrine}
+Upload (1523ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :io=>StringIO, :upload_options=>{}, :uploader=>Shrine}
+Exists (755ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}
+Download (1002ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :download_options=>{}, :uploader=>Shrine}
+Delete (700ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}
+```
+
+Some plugins add their own instrumentation as well when they detect that the
+`instrumentation` plugin has been loaded. For that to work, the
+`instrumentation` plugin needs to be loaded *before* any of these plugins.
+
+| Plugin                | Instrumentation                         |
+| :-----                | :--------------                         |
+| `derivation_endpoint` | instruments file processing             |
+| `derivatives`         | instruments file processing             |
+| `determine_mime_type` | instruments analyzing MIME type         |
+| `store_dimensions`    | instruments extracting image dimensions |
+| `signature`           | instruments calculating signature       |
+| `infer_extension`     | instruments inferring extension         |
+| `remote_url`          | instruments remote URL downloading      |
+| `data_uri`            | instruments data URI parsing            |
+
+For instrumentation, warnings, and other logging, Shrine uses its internal
+logger. You can tell Shrine to use a different logger. For example, if you're
+using Rails, you might want to tell it to use the Rails logger:
+
+```rb
+Shrine.logger = Rails.logger
+```
+
+In tests you might want to tell Shrine to log only warnings:
+
+```rb
+Shrine.logger.level = Logger::WARN
+```
+
+[Advantages of Shrine]: https://shrinerb.com/docs/advantages
+[Creating Plugins]: https://shrinerb.com/docs/creating-plugins
+[Creating Storages]: https://shrinerb.com/docs/creating-storages
+[Direct Uploads to S3]: https://shrinerb.com/docs/direct-s3
+[Extracting Metadata]: https://shrinerb.com/docs/metadata
+[File Processing]: https://shrinerb.com/docs/processing
+[File Validation]: https://shrinerb.com/docs/validation
+[Retrieving Uploads]: https://shrinerb.com/docs/retrieving-uploads
+[Using Attacher]: https://shrinerb.com/docs/attacher
+[FileSystem]: https://shrinerb.com/docs/storage/file-system
+[S3]: https://shrinerb.com/docs/storage/s3
+[`Shrine::UploadedFile`]: https://shrinerb.com/rdoc/classes/Shrine/UploadedFile/InstanceMethods.html
+
+[attacher]: #attacher
+[attachment]: #attachment
+[backgrounding]: #backgrounding
+[direct uploads]: #direct-uploads
+[io abstraction]: #io-abstraction
+[location]: #location
+[metadata]: #metadata
+[up front]: #processing-up-front
+[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
+
+[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
+
+[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
+[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
+
+[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/
+
+[ImageProcessing]: https://github.com/janko/image_processing
+[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
+[`file`]: http://linux.die.net/man/1/file
+
+[activerecord plugin]: https://shrinerb.com/docs/plugins/activerecord
+[add_metadata plugin]: https://shrinerb.com/docs/plugins/add_metadata
+[backgrounding plugin]: https://shrinerb.com/docs/plugins/backgrounding
+[derivation_endpoint plugin]: https://shrinerb.com/docs/plugins/derivation_endpoint
+[derivatives plugin]: https://shrinerb.com/docs/plugins/derivatives
+[determine_mime_type plugin]: https://shrinerb.com/docs/plugins/determine_mime_type
+[instrumentation plugin]: https://shrinerb.com/docs/plugins/instrumentation
+[hanami plugin]: https://github.com/katafrakt/hanami-shrine
+[model plugin]: https://shrinerb.com/docs/plugins/model
+[entity plugin]: https://shrinerb.com/docs/plugins/entity
+[mongoid plugin]: https://github.com/shrinerb/shrine-mongoid
+[presign_endpoint plugin]: https://shrinerb.com/docs/plugins/presign_endpoint
+[pretty_location plugin]: https://shrinerb.com/docs/plugins/pretty_location
+[rack_file plugin]: https://shrinerb.com/docs/plugins/rack_file
+[rom plugin]: https://github.com/shrinerb/shrine-rom
+[sequel plugin]: https://shrinerb.com/docs/plugins/sequel
+[signature plugin]: https://shrinerb.com/docs/plugins/signature
+[store_dimensions plugin]: https://shrinerb.com/docs/plugins/store_dimensions
+[upload_endpoint plugin]: https://shrinerb.com/docs/plugins/upload_endpoint
+[validation_helpers plugin]: https://shrinerb.com/docs/plugins/validation_helpers
+[validation plugin]: https://shrinerb.com/docs/plugins/validation
+
+[rails demo]: https://github.com/erikdahlstrand/shrine-rails-example
+[roda demo]: https://github.com/shrinerb/shrine/tree/master/demo
+[resumable demo]: https://github.com/shrinerb/shrine-tus-demo
+
+[`#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
+
+[storages]: https://shrinerb.com/docs/external/extensions#storages
+[plugins]: https://shrinerb.com/plugins
+[external plugins]: https://shrinerb.com/docs/external/extensions#plugins