shrine 1.4.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0c096588cbb135f27c0646661a10884af2d130aa
-  data.tar.gz: cb699c483ecd3e9309dbdcbddfd1c7fb919664b8
+  metadata.gz: 25b8acff9f68f0cc11cbadc0eeb39a5bdcf839d1
+  data.tar.gz: 666390819abcf036b20f46ecf04b1a30fef68a28
 SHA512:
-  metadata.gz: 62d92df4fb94a72f6f6f4e31331ac50b116f0536da7594240d517bb9fa7553cc73e3ff53221b4dc68dbe95fb67e957f6ca34d7f62abb0034889fbfb09498e011
-  data.tar.gz: f01073235dce4eaa882c5b419e162bcfe1ef327754978ae55a6f47b0c7687c4331d9143485dd32696729f83e8087c56e60c9c3c584128416f322efa158c7393b
+  metadata.gz: be25b88ca4629b8a1e052ed442b5530d1661a0f23a4d3d7cb0cb2e6f6538379c1a46a22e921091a3a718755e1f4378bd97a25312bde436134cdd3ac0ba487194
+  data.tar.gz: cf90025e05a3f0790bde9ba0763a66e75c6aba48a1b5586a4a814947693154d1a345ae90c447341f349cf9e3abf29a62e2fe6ab211993fc1685ad38cef479b33

data/README.md

@@ -1,6 +1,6 @@
 # Shrine
 
-Shrine is a toolkit for file uploads in Ruby applications.
+Shrine is a toolkit for handling file uploads in Ruby applications.
 
 If you're new, you're encouraged to read the [introductory blog post] which
 explains the motivation behind Shrine.
@@ -10,7 +10,7 @@ explains the motivation behind Shrine.
 - Documentation: [shrinerb.com](http://shrinerb.com)
 - Source: [github.com/janko-m/shrine](https://github.com/janko-m/shrine)
 - Bugs: [github.com/janko-m/shrine/issues](https://github.com/janko-m/shrine/issues)
-- Help & Dicussion: [groups.google.com/group/ruby-shrine](https://groups.google.com/forum/#!forum/ruby-shrine)
+- Help & Discussion: [groups.google.com/group/ruby-shrine](https://groups.google.com/forum/#!forum/ruby-shrine)
 
 ## Installation
 
@@ -18,11 +18,11 @@ explains the motivation behind Shrine.
 gem "shrine"
 ```
 
-Shrine has been tested on MRI 2.1, MRI 2.2, MRI 2.3, JRuby and Rubinius.
+Shrine has been tested on MRI 2.1, MRI 2.2, MRI 2.3 and JRuby.
 
 ## Basics
 
-Here's a basic example showing how file upload works in Shrine:
+Here's an example showing how basic file upload works in Shrine:
 
 ```rb
 require "shrine"
@@ -34,7 +34,6 @@ uploader = Shrine.new(:file_system)
 
 uploaded_file = uploader.upload(File.open("movie.mp4"))
 uploaded_file      #=> #<Shrine::UploadedFile>
-uploaded_file.url  #=> "/uploads/9260ea09d8effd.mp4"
 uploaded_file.data #=>
 # {
 #   "storage"  => "file_system",
@@ -43,27 +42,25 @@ uploaded_file.data #=>
 # }
 ```
 
-First we add the storage we want to use to Shrine's registry. Storages are
-simple Ruby classes which perform the actual uploads. We instantiate a `Shrine`
-with the storage name, and when we call `#upload` Shrine does the following:
+Let's see what's going on here:
 
-* extracts metadata from the file
-* generates a unique location for the file
-* uploads the file using the underlying storage
-* closes the file
-* returns a `Shrine::UploadedFile` with relevant data
+First we registered the storage we want to use under a name. Storages are plain
+Ruby classes which encapsulate file management on a particular service. We can
+then instantiate `Shrine` as a wrapper around that storage. A call to `upload`
+uploads the given file to the underlying storage.
 
-The argument to `Shrine#upload` needs to be an IO-like object. So, `File`,
-`Tempfile` and `StringIO` are all valid arguments. But the object doesn't have
-to be an actual IO, it's enough that it responds to these 5 methods:
-`#read(*args)`, `#size`, `#eof?`, `#rewind` and `#close`.
-`ActionDispatch::Http::UploadedFile` is one such object.
+The argument to `upload` needs to be an IO-like object. So, `File`, `Tempfile`
+and `StringIO` are all valid arguments. The object doesn't have to be an actual
+IO, though, it's enough that it responds to these 5 methods: `#read(*args)`,
+`#size`, `#eof?`, `#rewind` and `#close`. `ActionDispatch::Http::UploadedFile`
+is one such object, as well as `Shrine::UploadedFile` itself.
 
-The returned object is a [`Shrine::UploadedFile`], which represents the file
-that was uploaded, and we can do a lot with it:
+The result of uploading is a `Shrine::UploadedFile` object, which represents
+the uploaded file on the storage. It is defined solely by its data hash. We can
+do a lot with it:
 
 ```rb
-uploaded_file.url      #=> "/uploads/938kjsdf932.mp4"
+uploaded_file.url      #=> "uploads/938kjsdf932.mp4"
 uploaded_file.metadata #=> {...}
 uploaded_file.read     #=> "..."
 uploaded_file.exists?  #=> true
@@ -72,16 +69,15 @@ uploaded_file.delete
 # ...
 ```
 
-To read about the metadata that is stored with the uploaded file, see the
-[metadata](#metadata) section.
-
 ## Attachment
 
-In web applications, instead of managing files directly, we rather want to
-treat them as "attachments" to records and tie them to their lifecycle. In
-Shrine we do this by generating and including "attachment" modules.
+In web applications we usually want work with files on a higher level. We want
+to treat them as "attachments" to records, by persisting their information to a
+database column and tying their lifecycle to the record. For this Shrine offers
+a higher-level attachment interface.
 
-Firstly we need to assign the special `:cache` and `:store` storages:
+First we need to register temporary and permanent storage which will be used
+internally:
 
 ```rb
 require "shrine"
@@ -93,88 +89,90 @@ Shrine.storages = {
 }
 ```
 
-These storages will by default be used for caching and storing attachments, but
-you can use additional storages with the `default_storage` plugin. Next we
-should create an uploader specific to the type of files we're uploading:
+The `:cache` and `:store` are only special in terms that they will be used
+automatically (but that can be changed with the default_storage plugin). Next,
+we create an uploader class specific to the type of attachment we want, so that
+later we can have different uploading logic for different attachment types.
 
 ```rb
 class ImageUploader < Shrine
-  # your logic for uploading files
+  # your logic for uploading images
 end
 ```
 
-Now if we assume that we have a "User" model, and we want our users to have an
-"avatar", we can generate and include an "attachment" module:
+Finally, to add an attachment to a model, we generate a named "attachment"
+module using the uploader and include it:
 
 ```rb
-class User
-  include ImageUploader[:avatar] # requires "avatar_data" attribute
+class Photo
+  include ImageUploader[:image] # requires "image_data" attribute
 end
 ```
 
-Now our model has gained special methods for attaching avatars:
+Now our model has gained special methods for attaching files:
 
 ```rb
-user = User.new
-user.avatar = File.open("avatar.jpg") # uploads the file to cache
-user.avatar      #=> #<Shrine::UploadedFile>
-user.avatar_url  #=> "/uploads/9260ea09d8effd.jpg"
-user.avatar_data #=> "{\"storage\":\"cache\",\"id\":\"9260ea09d8effd.jpg\",\"metadata\":{...}}"
+photo = Photo.new
+photo.image = File.open("nature.jpg") # uploads the file to cache
+photo.image      #=> #<Shrine::UploadedFile>
+photo.image_url  #=> "/uploads/cache/9260ea09d8effd.jpg"
+photo.image_data #=> "{\"storage\":\"cache\",\"id\":\"9260ea09d8effd.jpg\",\"metadata\":{...}}"
 ```
 
-The attachment module has added `#avatar`, `#avatar=` and `#avatar_url`
-methods to our User, using regular module inclusion.
+The attachment module has added `#image`, `#image=` and `#image_url`
+methods to our `Photo`, using regular module inclusion.
 
 ```rb
-Shrine[:avatar] #=> #<Shrine::Attachment(avatar)>
-Shrine[:avatar].is_a?(Module) #=> true
-Shrine[:avatar].instance_methods #=> [:avatar=, :avatar, :avatar_url, :avatar_attacher]
+Shrine[:image] #=> #<Shrine::Attachment(image)>
+Shrine[:image].is_a?(Module) #=> true
+Shrine[:image].instance_methods #=> [:image=, :image, :image_url, :image_attacher]
 
 Shrine[:document] #=> #<Shrine::Attachment(document)>
 Shrine[:document].instance_methods #=> [:document=, :document, :document_url, :document_attacher]
 
-# If you prefer to be more explicit, you can use the expanded forms
-Shrine.attachment(:avatar)
+# Expanded forms
+Shrine.attachment(:image)
 Shrine::Attachment.new(:document)
 ```
 
-* `#avatar=` – caches the file and saves a JSON representation into `avatar_data`
-* `#avatar` – returns a `Shrine::UploadedFile` based on the data from `avatar_data`
-* `#avatar_url` – calls `avatar.url` if attachment is present, otherwise returns nil.
+* `#image=` – caches the file and saves JSON data into `image_data`
+* `#image` – returns a `Shrine::UploadedFile` based on data from `image_data`
+* `#image_url` – calls `image.url` if attachment is present, otherwise returns nil.
 
-This is how you would typically create the form for a `@user`:
+This is how you would typically create the form for a `@photo`:
 
 ```erb
-<form action="/users" method="post" enctype="multipart/form-data">
-  <input name="user[avatar]" type="hidden" value="<%= @user.avatar_data %>">
-  <input name="user[avatar]" type="file">
+<form action="/photos" method="post" enctype="multipart/form-data">
+  <input name="photo[image]" type="hidden" value="<%= @photo.image_data %>">
+  <input name="photo[image]" type="file">
 </form>
 ```
 
 The "file" field is for file upload, while the "hidden" field is to make the
 file persist in case of validation errors, and for direct uploads. This code
-works because `#avatar=` also accepts already cached files via their JSON
+works because `#image=` also accepts an already cached file via its JSON
 representation:
 
 ```rb
-user.avatar = '{"id":"9jsdf02kd", "storage":"cache", "metadata": {...}}'
+photo.image = '{"id":"9jsdf02kd", "storage":"cache", "metadata": {...}}'
 ```
 
 ### ORM
 
-Your models probably won't be POROs, so Shrine ships with plugins for
-Sequel and ActiveRecord ORMs. Shrine uses the `<attachment>_data` column
-for storing attachments, so you'll need to add it in a migration:
+Even though you can use Shrine's attachment interface with plain Ruby objects,
+it's much more common to use it with an ORM. Shrine ships with plugins for
+Sequel and ActiveRecord ORMs. It uses the `<attachment>_data` column for
+storing data for uploaded files, so you'll need to add it in a migration.
 
 ```rb
-add_column :users, :avatar_data, :text # or a JSON column
+add_column :movies, :video_data, :text # or a JSON column
 ```
 ```rb
 Shrine.plugin :sequel # or :activerecord
 ```
 ```rb
-class User < Sequel::Model
-  include ImageUploader[:avatar]
+class Movie < Sequel::Model
+  include VideoUploader[:video]
 end
 ```
 
@@ -182,77 +180,61 @@ In addition to getters and setters, the ORM plugins add the appropriate
 callbacks:
 
 ```rb
-user.avatar = File.open("avatar.jpg")
-user.avatar.storage_key #=> "cache"
-user.save
-user.avatar.storage_key #=> "store"
-user.destroy
-user.avatar.exists? #=> false
-```
-
-*NOTE: The record will first be saved with the cached attachment, and afterwards
-(in an "after commit" hook) updated with the stored attachment. This is done so
-that processing/storing isn't performed inside a database transaction. If you're
-doing processing, there will be a bried period of time when the record will exist
-with an unprocessed attachment, so you may need to account for that.*
-
-## Direct uploads
+movie.video = File.open("video.mp4")
+movie.video_url #=> "/uploads/cache/0sdfllasfi842.mp4"
 
-Shrine comes with a `direct_upload` plugin which provides a [Roda] endpoint
-that accepts file uploads. This allows you to asynchronously start caching the
-file the moment the user selects it (e.g. using the [jQuery-File-Upload] JS
-library), which gives a nice experience to the user.
+movie.save
+movie.video_url #=> "/uploads/store/l02kladf8jlda.mp4"
 
-```rb
-Shrine.plugin :direct_upload # Provides a Roda endpoint
-```
-```rb
-Rails.application.routes.draw do
-  mount ImageUploader::UploadEndpoint => "/attachments/images"
-end
-```
-```js
-$('[type="file"]').fileupload({
-  url:       '/attachments/images/cache/upload',
-  paramName: 'file',
-  add:       function(e, data) { /* Disable the submit button */ },
-  progress:  function(e, data) { /* Add a nice progress bar */ },
-  done:      function(e, data) { /* Fill in the hidden field with the result */ }
-});
+movie.destroy
+movie.video.exists? #=> false
 ```
 
-The plugin also provides a route that can be used for doing direct S3 uploads.
-See the documentation of the plugin for more details, as well as the [example
-app] to see how easy it is to implement multiple uploads directly to S3.
+First the raw file is cached to temporary storage on assignment, then on saving
+the cached file is uploaded to permanent storage. Destroying the record
+destroys the attachment.
+
+*NOTE: The record will first be saved with the cached attachment, and
+afterwards (in an "after commit" hook) updated with the stored attachment. This
+is done so that processing/storing isn't performed inside a database
+transaction. If you're doing processing, there will be a period of time when
+the record will be saved with an unprocessed attachment, so you may need to
+account for that.*
 
 ## Processing
 
 Whenever a file is uploaded, `Shrine#process` is called, and this is where
 you're expected to define your processing.
 
+```rb
+class ImageUploader < Shrine
+  def process(io, context)
+    # ...
+  end
+end
+```
+
+Shrine's uploaders are stateless; the `#process` method is simply a function
+which takes an input `io` and returns processed file(s) as output. Since it's
+called for each upload, attaching the file will call it twice, first when
+raw file is cached to temporary storage on assignment, then when cached file
+is uploaded to permanent storage on saving. We usually want to process in the
+latter phase (after file validations):
+
 ```rb
 class ImageUploader < Shrine
   def process(io, context)
     if context[:phase] == :store
-      # processing...
+      # ...
     end
   end
 end
 ```
 
-The `io` is the file being uploaded, and `context` we'll leave for later. You
-may be wondering why we need this conditional. Well, when an attachment is
-assigned and saved, an "upload" actually happens two times. First the file is
-"uploaded" to cache on assignment, and then the cached file is reuploaded to
-store on save. You could theoretically do processing in both phases, depending
-on your preferences (although it's generally not recommended to process on
-caching, because it happens before file validations; use the `recache` plugin
-instead).
-
 Ok, now how do we do the actual processing? Well, Shrine actually doesn't ship
 with any file processing functionality, because that is a generic problem that
-belongs in a separate gem. If the type of files you're uploading are images, I
-created the [image_processing] gem which you can use with Shrine:
+belongs in separate libraries. If the type of files you're uploading are
+images, I created the [image_processing] gem which you can use with Shrine:
 
 ```rb
 require "image_processing/mini_magick"
@@ -268,20 +250,14 @@ class ImageUploader < Shrine
 end
 ```
 
-Notice that we needed to call `io.download`. This is because the original file
-was already stored to cache, and now this cached file is being uploaded to
-store. The cached file is an instance of `Shrine::UploadedFile`, but for
-processing we need to work with actual files, so we first need to download it.
-
-In general, processing works in a way that if `#process` returns a file, Shrine
-continues storing that file, otherwise if nil is returned, Shrine continues
-storing the original file.
+Since here `io` is a cached `Shrine::UploadedFile`, we need to download it to
+a file, as image_processing only accepts real files.
 
 ### Versions
 
 If you're uploading images, often you'll want to store various thumbnails
-alongside your original image. For that you just need to load the `versions`
-plugin, and now in `#process` you can return a Hash of versions:
+alongside your original image. You can do that by loading the versions plugin,
+and in `#process` simply returning a Hash of versions:
 
 ```rb
 require "image_processing/mini_magick"
@@ -302,25 +278,24 @@ class ImageUploader < Shrine
 end
 ```
 
-As you see, instead of a complex class-level DSL, Shrine provides a very simple
-instance-level interface where you're in complete control over processing. The
-processed files are Ruby Tempfiles and they should eventually get deleted by
-themselves, but you can also use the `moving` plugin to delete them immediately
-after upload.
+Being able to define processing on instance level provides a lot of flexibility,
+allowing things like choosing the order or adding parallelization. It is
+recommended to use the delete_raw plugin for automatically deleting processed
+files after uploading.
 
-Now when you access the stored attachment, a Hash of versions will be returned
-instead:
+The attachment getter will simply return the processed attachment as a Hash of
+versions:
 
 ```rb
-user.avatar.class #=> Hash
+photo.image.class #=> Hash
 
 # With the store_dimensions plugin
-user.avatar[:large].width  #=> 700
-user.avatar[:medium].width #=> 500
-user.avatar[:small].width  #=> 300
+photo.image[:large].width  #=> 700
+photo.image[:medium].width #=> 500
+photo.image[:small].width  #=> 300
 
 # The plugin expands this method to accept version names.
-user.avatar_url(:large) #=> "..."
+photo.image_url(:large) #=> "..."
 ```
 
 ## Context
@@ -337,28 +312,28 @@ class ImageUploader < Shrine
 end
 ```
 ```rb
-user = User.new
-user.avatar = File.open("avatar.jpg")  # "cache"
-user.save                              # "store"
+photo = Photo.new
+photo.image = File.open("image.jpg") # "cache"
+photo.save                           # "store"
 ```
 ```
-{:name=>:avatar, :record=>#<User:0x007fe1627f1138>, :phase=>:cache}
-{:name=>:avatar, :record=>#<User:0x007fe1627f1138>, :phase=>:store}
+{:name=>:image, :record=>#<Photo:0x007fe1627f1138>, :phase=>:cache}
+{:name=>:image, :record=>#<Photo:0x007fe1627f1138>, :phase=>:store}
 ```
 
-The `:name` is the name of the attachment, in this case "avatar". The `:record`
-is the model instance, in this case instance of `User`. Lastly, the `:phase`;
-by default the two main phases of attaching are "cache" and "store", but some
-plugins add more of them, and there are different ones for deleting files.
+The `:name` is the name of the attachment, in this case "image". The `:record`
+is the model instance, in this case instance of `Photo`. Lastly, the `:phase`
+is a symbol which indicates the purpose of the upload (by default there are
+only `:cache` and `:store`, but some plugins add more of them).
 
-Context is really useful for doing conditional processing and validation, since
-we have access to the record and attachment name. In general the context is
-used deeply in Shrine for various purposes.
+Context is useful for doing conditional processing and validation, since we
+have access to the record and attachment name, and it is also used by some
+plugins internally.
 
 ## Validations
 
-Validations are registered by calling `Shrine::Attacher.validate`, and are best
-done with the `validation_helpers` plugin:
+Validations are registered by calling `Attacher.validate`, and are best done
+with the validation_helpers plugin:
 
 ```rb
 class DocumentUploader < Shrine
@@ -366,7 +341,7 @@ class DocumentUploader < Shrine
 
   Attacher.validate do
     # Evaluated inside an instance of Shrine::Attacher.
-    if record.guest?
+    if record.resume?
       validate_max_size 10*1024*1024, message: "is too large (max is 10 MB)"
       validate_mime_type_inclusion ["application/pdf"]
     end
@@ -375,72 +350,53 @@ end
 ```
 
 ```rb
-user = User.new
-user.resume = File.open("resume.pdf")
-user.valid? #=> false
-user.errors.to_hash #=> {resume: ["is too large (max is 2 MB)"]}
+document = Document.new(resume: true)
+document.file = File.open("resume.pdf")
+document.valid? #=> false
+document.errors.to_hash #=> {file: ["is too large (max is 2 MB)"]}
 ```
 
 ## Metadata
 
-By default Shrine extracts and stores general file metadata:
+Shrine automatically extracts and stores general file metadata:
 
 ```rb
-class UsersController < ApplicationController
-  def create
-    user = User.create(params[:user])
-    user.avatar.metadata #=>
-    # {
-    #   "filename"  => "my_avatar.jpg",
-    #   "mime_type" => "image/jpeg",
-    #   "size"      => 345993,
-    # }
+photo = Photo.create(image: image)
+photo.image.metadata #=>
+# {
+#   "filename"  => "nature.jpg",
+#   "mime_type" => "image/jpeg",
+#   "size"      => 345993,
+# }
 
-    user.avatar.original_filename #=> "my_avatar.jpg"
-    user.avatar.mime_type         #=> "image/jpeg"
-    user.avatar.size              #=> 345993
-  end
-end
+photo.image.original_filename #=> "nature.jpg"
+photo.image.extension         #=> "jpg"
+photo.image.mime_type         #=> "image/jpeg"
+photo.image.size              #=> 345993
 ```
 
 ### MIME type
 
 By default, "mime_type" is inherited from `#content_type` of the uploaded file,
-which holds the value of the "Content-Type" header added by the browser solely
-based on the extension of the uploaded file. This means that by default
-Shrine's "mime_type" is *not* guaranteed to hold the actual MIME type of the
-file.
+which is set from the "Content-Type" request header, which 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 help with that Shrine provides the `determine_mime_type` plugin, which by
+To help with that Shrine provides the determine_mime_type plugin, which by
 default uses the UNIX [file] utility to determine the actual MIME type:
 
 ```rb
 Shrine.plugin :determine_mime_type
 ```
 ```rb
-user = User.create(avatar: File.open("image.mp4")) # image with a .mp4 extension
-user.avatar.mime_type #=> "image/png"
-```
-
-### Dimensions
-
-If you're uploading images and you want to store dimensions, you can use the
-`store_dimensions` plugin which extracts dimensions using the [fastimage] gem.
-
-```rb
-ImageUploader.plugin :store_dimensions
-```
-```rb
-user = User.create(avatar: File.open("image.jpg"))
-user.avatar.width  #=> 400
-user.avatar.height #=> 500
+File.write("image.jpg", "<?php ... ?>") # PHP file with a .jpg extension
+photo = Photo.create(image: File.open("image.jpg"))
+photo.image.mime_type #=> "text/x-php"
 ```
 
-The fastimage gem has built-in protection against [image bombs].
-
 ### Custom metadata
 
-You can also extract and store custom metadata, by overriding
+You can also extract and store custom metadata by overriding
 `Shrine#extract_metadata`:
 
 ```rb
@@ -453,49 +409,55 @@ class ImageUploader < Shrine
 end
 ```
 
-Note that if you're extracting custom metadata from Ruby, you should always
-rewind the file afterwards.
+Note that you should always rewind the `io` after reading from it.
 
 ## Locations
 
-By default files will all be put in the same folder. If you want that each
-attachment has its own directory, you can use the `pretty_location` plugin:
+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 of the storage.
+If you want that each attachment has its own directory, you can load the
+pretty_location plugin:
 
 ```rb
 Shrine.plugin :pretty_location
 ```
 ```rb
-user = User.create(avatar: File.open("avatar.jpg"))
-user.avatar.id #=> "user/34/avatar/34krtreds2df.jpg"
+photo = Photo.create(image: File.open("nature.jpg"))
+photo.image.id #=> "photo/34/image/34krtreds2df.jpg"
 ```
 
-If you want to generate your own locations, simply override
+If you want to generate locations on your own, simply override
 `Shrine#generate_location`:
 
 ```rb
 class ImageUploader < Shrine
   def generate_location(io, context)
-    "#{context[:record].class}/#{super}"
+    if context[:record]
+      "#{context[:record].class}/#{super}"
+    else
+      super
+    end
   end
 end
 ```
 
-Note that there should always be a random component in the location, otherwise
-dirty tracking won't be detected properly (you can use `Shrine#generate_uid`).
-Inside this method you can access the extracted metadata through
+Note that there should always be a random component in the location, for dirty
+tracking to be detected properly (you can use `Shrine#generate_uid`). Inside
+`#generate_location` you can access the extracted metadata through
 `context[:metadata]`.
 
 When using the uploader directly, it's possible to bypass `#generate_location`
-by passing in `:location`:
+by passing a `:location`:
 
 ```rb
-file = File.open("avatar.jpg")
-Shrine.new(:store).upload(file, location: "some/specific/location.jpg")
+uploader = Shrine.new(:store)
+file = File.open("nature.jpg")
+uploader.upload(file, location: "some/specific/location.jpg")
 ```
 
 ## Storage
 
-Other than [FileSystem], Shrine also ships with [S3] storage:
+Other than [FileSystem], Shrine also ships with Amazon [S3] storage:
 
 ```rb
 gem "aws-sdk", "~> 2.1"
@@ -507,42 +469,71 @@ Shrine.storages[:store] = Shrine::Storage::S3.new(
   access_key_id:     "<ACCESS_KEY_ID>",      # "xyz"
   secret_access_key: "<SECRET_ACCESS_KEY>",  # "abc"
   region:            "<REGION>",             # "eu-west-1"
-  bucket:            "<BUCKET>",             # "my-app"
+  bucket:            "<BUCKET>",             # "my-bucket"
 )
 ```
 
 ```rb
-user = User.new(avatar: File.open(:avatar))
-user.avatar.url #=> "/uploads/j4k343ui12ls9.jpg"
-user.save
-user.avatar.url #=> "https://my-bucket.s3-eu-west-1.amazonaws.com/0943sf8gfk13.jpg"
+movie = Movie.new(video: File.open("video.mp4"))
+movie.video_url #=> "/uploads/cache/j4k343ui12ls9.jpg"
+movie.save
+movie.video_url #=> "https://my-bucket.s3-eu-west-1.amazonaws.com/0943sf8gfk13.mp4"
 ```
 
-If you're using S3 both for cache and store, saving the record will avoid
-reuploading the file by issuing an S3 COPY command instead. Also, the
-`versions` plugin takes advantage of S3's MULTI DELETE capabilities, so
-versions are deleted with a single HTTP request.
+If you're using S3 both for cache and store, uploading a cached file to store
+will simply do an S3 COPY request instead of downloading and reuploading the
+file. Also, the versions plugin takes advantage of S3's MULTI DELETE
+capabilities, so versions are deleted with a single HTTP request.
 
 See the full documentation for [FileSystem] and [S3] storages. There are also
 many other Shrine storages available, see the [Plugins & Storages] section.
 
-### Clearing cache
+## Upload options
 
-You will want to periodically clean your cache storage. Amazon S3 provides [a
-built-in solution](http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html),
-and for FileSystem you can put something like this in your Rake task:
+Many storages accept additional upload options, which you can pass via the
+upload_options plugin, or manually when uploading:
 
 ```rb
-file_system = Shrine.storages[:cache]
-file_system.clear!(older_than: Time.now - 7*24*60*60) # delete files older than 1 week
+uploader = Shrine.new(:store)
+uploader.upload(file, upload_options: {acl: "private"})
+```
+
+## Direct uploads
+
+Shrine comes with a direct_upload plugin which provides a [Roda] endpoint that
+accepts file uploads. This allows you to asynchronously start caching the file
+the moment the user selects it via AJAX (e.g. using the [jQuery-File-Upload] JS
+library).
+
+```rb
+Shrine.plugin :direct_upload # Provides a Roda endpoint
+```
+```rb
+Rails.application.routes.draw do
+  mount VideoUploader::UploadEndpoint => "/attachments/videos"
+end
+```
+```js
+$('[type="file"]').fileupload({
+  url:       '/attachments/videos/cache/upload',
+  paramName: 'file',
+  add:       function(e, data) { /* Disable the submit button */ },
+  progress:  function(e, data) { /* Add a nice progress bar */ },
+  done:      function(e, data) { /* Fill in the hidden field with the result */ }
+});
 ```
 
+The plugin also provides a route that can be used for doing direct S3 uploads.
+See the documentation of the plugin for more details, as well as the
+[Roda](https://github.com/janko-m/shrine-example)/[Rails](https://github.com/erikdahlstrand/shrine-rails-example)
+example app which demonstrates multiple uploads directly to S3.
+
 ## Background jobs
 
-Shrine is the first uploading library designed from day one to be used with
-background jobs. Backgrounding parts of file upload is essential for scaling
-and good user experience, and Shrine provides a `backgrounding` plugin which
-makes it really easy to plug in your backgrounding library:
+Shrine is the first file upload library designed for backgrounding support.
+Moving phases of managing attachments to background jobs is essential for
+scaling and good user experience, and Shrine provides a backgrounding plugin
+which makes it really easy to plug in your favourite backgrounding library:
 
 ```rb
 Shrine.plugin :backgrounding
@@ -567,8 +558,8 @@ end
 ```
 
 The above puts all promoting (moving to store) and deleting of files into a
-background Sidekiq job. Obviously instead of Sidekiq you can just as well use
-any other backgrounding library.
+background Sidekiq job. Obviously instead of Sidekiq you can use any other
+backgrounding library.
 
 The main advantages of Shrine's backgrounding support over other file upload
 libraries are:
@@ -583,14 +574,25 @@ libraries are:
 * **Generality** – The above solution will automatically work for all uploaders,
   types of files and models.
 * **Safety** – All of Shrine's code has been designed to take delayed storing
-  into account, so concurrency issues should be nonexistent.
+  into account, and concurrent requests are handled well.
+
+## Clearing cache
+
+You will want to periodically clean your temporary storage. Amazon S3 provides
+[a built-in solution](http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html),
+and for FileSystem you can put something like this in your Rake task:
+
+```rb
+file_system = Shrine.storages[:cache]
+file_system.clear!(older_than: Time.now - 7*24*60*60) # delete files older than 1 week
+```
 
 ## Plugins
 
 Shrine comes with a small core which provides only the essential functionality,
-and all additional features are available via plugins. This way you can choose
-exactly how much Shrine does for you. Shrine itself [ships with over 35
-plugins], most of which I haven't managed to cover here.
+and any additional features are available via plugins. This way you can choose
+exactly what and how much Shrine does for you. Shrine itself [ships with over
+35 plugins], most of which I didn't cover here.
 
 The plugin system respects inheritance, so you can choose which plugins will
 be applied to which uploaders: