shrine 2.4.1 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 93c5aa709ec2574b80b2a5d3b62f1f6d5b2cd312
-  data.tar.gz: f6f13f2f4b24c6961a846634462c9d1aa2c16e7e
+  metadata.gz: 9bfafd65b7f7fe8b99b1c5f93ef378bfc3dc7eac
+  data.tar.gz: 698ed63662d4394c346f5ae2946e892de53d694e
 SHA512:
-  metadata.gz: 712eaa97b81d90b928b0e7967740d79e0f4320af5b67a811e8a991f0e91e103568f70cc08683aa5e38fd3235021869a5c8634f08d67d961971edacc0aa9cb5b9
-  data.tar.gz: fa531d81b429dbd94cfab836f50180aa6eed61e33eceaffe0b4d901398228cedfb19d9add18a0ebdb5c131d803b6c072a8e6972b9ea1c9cd9095f4da6e0f401f
+  metadata.gz: 2fcf2377c360c399342238366a1458f48f078d7b946b52af09b3e9acdbc8761e7b07270700f6a9b09b4195a43536947d6fc145da10c75667f88bd95dd9284edf
+  data.tar.gz: f293b1ba574687eae1edc8abad8fbdfbb2db2a4028470964f612ccf51a9e74a8dd810caf2e8dc6c784b9136fc6503ac168175d955404b923def1fd89eafc1a61

data/README.md

@@ -18,6 +18,7 @@ Add Shrine to the Gemfile and write an initializer which sets up the storage and
 loads the ORM plugin:
 
 ```rb
+# Gemfile
 gem "shrine"
 ```
 
@@ -32,6 +33,7 @@ Shrine.storages = {
 
 Shrine.plugin :sequel # :activerecord
 Shrine.plugin :cached_attachment_data # for forms
+Shrine.plugin :rack_file # for non-Rails apps
 ```
 
 Next decide how you will name the attachment attribute on your model, and run a
@@ -47,7 +49,8 @@ end                                           # end
 ```
 
 Now you can create an uploader class for the type of files you want to upload,
-and add the attachment attribute to your model which will accept files:
+and add a virtual attribute for handling attachments using this uploader to
+your model:
 
 ```rb
 class ImageUploader < Shrine
@@ -57,15 +60,13 @@ end
 
 ```rb
 class Photo < Sequel::Model # ActiveRecord::Base
-  include ImageUploader[:image]
+  include ImageUploader[:image] # adds an `image` virtual attribute
 end
 ```
 
-Let's now add the form fields needed for attaching files. We need a file
-field for choosing files, and a hidden field for retaining the uploaded file
-in case of validation errors and [direct uploads]. Note that the file field
-needs to go *after* the hidden field, so that attaching a new file can always
-override whatever is in the hidden field.
+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 [direct uploads].
 
 ```erb
 <form action="/photos" method="post" enctype="multipart/form-data">
@@ -80,13 +81,14 @@ override whatever is in the hidden field.
 <% end %>
 ```
 
-Note the `enctype="multipart/form-data"` HTML attribute, which is required for
-submitting files through the form. The Rails form builder will automatically
-generate it for you when you add a file field.
+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, though the Rails form builder
+will automatically generate it for you.
 
 Now in your router/controller the attachment request parameter can be assigned
-to the model like any other attribute. Note that for non-Rails apps you will
-need to load the `rack_file` plugin which handles Rack's uploaded file hash.
+to the model like any other attribute:
 
 ```rb
 post "/photos" do
@@ -95,65 +97,217 @@ post "/photos" do
 end
 ```
 
-Finally, you can use the URL of the attached file to display it:
+Once a file is uploaded and attached to the record, you can retrieve a URL to
+the uploaded file and display it:
 
 ```erb
 <img src="<%= @photo.image_url %>">
 ```
 
-## Attachment
+## Storage
 
-When we assign an IO object to the record, Shrine will upload it to the
-registered `:cache` storage, which acts as a temporary storage, and write the
-location, storage, and metadata of the uploaded file to a single
-`<attachment>_data` column:
+A "storage" in Shrine is an object responsible for managing files on a specific
+storage service (filesystem, Amazon S3 etc), which implements a generic method
+interface. Storages are configured directly and registered under a name in
+`Shrine.storages`, so that they can be later used by uploaders.
 
 ```rb
-photo = Photo.new
-photo.image = File.open("waterfall.jpg")
-photo.image_data #=> '{"storage":"cache","id":"9260ea09d8effd.jpg","metadata":{...}}'
+# Gemfile
+gem "aws-sdk", "~> 2.1" # for Amazon S3 storage
+```
+```rb
+require "shrine/storage/s3"
+
+s3_options = {
+  access_key_id:     "abc",
+  secret_access_key: "xyz",
+  region:            "my-region",
+  bucket:            "my-bucket",
+}
 
-photo.image      #=> #<Shrine::UploadedFile>
-photo.image_url  #=> "/uploads/cache/9260ea09d8effd.jpg"
+Shrine.storages = {
+  cache: Shrine::Storage::S3.new(prefix: "cache", **s3_options),
+  store: Shrine::Storage::S3.new(prefix: "store", **s3_options),
+}
 ```
 
-The Shrine attachment module added the following methods to the `Photo` model:
+The above example sets up Amazon S3 storage both for temporary and permanent
+storage, which allows for [direct uploads]. The `:cache` and `:store` names are
+special only in terms that the attacher will automatically pick them up, but
+you can also register more than two storages under different names.
 
-* `#image=` – caches the file and saves the result into `image_data`
-* `#image` – returns `Shrine::UploadedFile` instantiated from `image_data`
-* `#image_url` – calls `image.url` if attachment is present, otherwise returns nil
-* `#image_attacher` – returns instance of `Shrine::Attacher` which handles attaching
+Shrine ships with [FileSystem] and [S3] storage, take a look at their
+documentation for more details on various features they support. There are also
+[many more Shrine storages][external storages] shipping as external gems.
 
-In addition to assigning new files, you can also assign already cached files
-using their JSON representation:
+## Uploader
+
+Uploaders are subclasses of `Shrine`, and are essentially wrappers around
+storages. In addition to actually calling the underlying storage when they need
+to, they also perform many generic tasks which aren't related to a particular
+storage (like processing, extracting metadata, logging etc).
 
 ```rb
-photo.image = '{
-  "storage": "cache",
-  "id": "9260ea09d8effd.jpg",
-  "metadata": { ... }
-}'
+class ImageUploader < 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 you can structure them any way that
+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.
+
+```rb
+uploaded_file = uploader.upload(file)
+uploaded_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)
+* closing the file
+
+### IO abstraction
+
+Shrine is able to upload any IO-like object that respond to `#read`, `#size`,
+`#rewind`, `#eof?` and `#close`. This foremost includes all real IO 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
+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.
+
+Finally, the `Shrine::UploadedFile` object, returned by uploading, is itself an
+IO-like object. This makes it incredibly easy 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.
+
+### Deleting
+
+The uploader can also delete uploaded files via `#delete`. Internally this just
+delegates to the uploaded file, but some plugins bring additional behaviour
+(e.g. logging).
+
+```rb
+uploaded_file = uploader.upload(file)
+# ...
+uploader.delete(uploaded_file)
+```
+
+## Uploaded file
+
+The `Shrine::UploadedFile` object represents the file that was uploaded to the
+storage. It contains the following information:
+
+* `storage` – identifier of the storage the file was uploaded to
+* `id` – the location of the file on the storage
+* `metadata` – file metadata that was extracted during upload
+
+```rb
+uploaded_file = uploader.upload(file)
+
+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.download #=> #<Tempfile>
+uploaded_file.exists?  #=> true
+uploaded_file.open { |io| io.read }
+uploaded_file.delete
 ```
 
-This allows Shrine to retain uploaded files in case of validation errors, and
-handle [direct uploads], via the hidden form field.
+It also implements the IO-like interface that conforms to Shrine's IO
+abstraction, which allows it to be uploaded 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
+```
+
+## 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.
+
+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.
+
+```rb
+Shrine.plugin :sequel # :activerecord
+```
+
+```rb
+class Photo < Sequel::Model # ActiveRecord::Base
+  include ImageUploader[:image]                 #
+  include ImageUploader.attachment(:image)      # these are all equivalent
+  include ImageUploader::Attachment.new(:image) #
+end
+```
+
+You can choose whichever of these three syntaxes you prefer. In any case this
+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
 
 The ORM plugin that we loaded adds appropriate callbacks, so when record is
-saved the attachment is uploaded to permanent storge (`:store`), and when
-record is destroyed the attachment is destroyed as well:
+saved the attachment is uploaded to permanent storage, and when record is
+deleted the attachment is deleted as well.
 
 ```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_url #=> "/uploads/cache/0sdfllasfi842.jpg"
+photo.image      #=> #<Shrine::UploadedFile @data={...}>
+photo.image_url  #=> "/uploads/cache/0sdfllasfi842.jpg"
+photo.image_data #=> '{"storage":"cache","id":"0sdfllasfi842.jpg","metadata":{...}}'
 
+# the cached file is promoted to permanent storage and saved to `image_data` column
 photo.save
-photo.image_url #=> "/uploads/store/l02kladf8jlda.jpg"
+photo.image      #=> #<Shrine::UploadedFile @data={...}>
+photo.image_url  #=> "/uploads/store/l02kladf8jlda.jpg"
+photo.image_data #=> '{"storage":"store","id":"l02kladf8jlda.jpg","metadata":{...}}'
 
+# the attached file is deleted with the record
 photo.destroy
 photo.image.exists? #=> false
 ```
 
-The ORM plugin will also delete replaced attachments:
+If there is already a file attached, and the attachment is overriden (either
+with a new file or no file), the previous attachment will get deleted when the
+record gets saved.
 
 ```rb
 photo.update(image: new_file) # changes the attachment and deletes previous
@@ -161,138 +315,148 @@ photo.update(image: new_file) # changes the attachment and deletes previous
 photo.update(image: nil)      # removes the attachment and deletes previous
 ```
 
-In all these examples we used `image` as the name of the attachment, but we can
-create attachment modules for any kind of attachments:
+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
-class VideoUploader < Shrine
-  # video attachment logic
-end
-```
-```rb
-class Movie < Sequel::Model
-  include VideoUploader[:video] # uses "video_data" column
-end
+photo.image = '{
+  "storage": "cache",
+  "id": "9260ea09d8effd.jpg",
+  "metadata": { ... }
+}'
 ```
 
-### Attacher
+## Attacher
 
-The model attachment interface under-the-hood just delegates to a
-`Shrine::Attacher` object. If whether you don't want to add additional methods
-to your model, prefer explicitness over callbacks, or use Shrine with custom
-models, you can use `Shrine::Attacher` directly:
+The model attachment attributes and callbacks just delegate the behaviour
+to a `Shrine::Attacher` object.
 
 ```rb
-attacher = ImageUploader::Attacher.new(photo, :image) # equivalent to `photo.image_attacher`
-
-attacher.cache #=> #<ImageUploader @storage_key=:cache>
-attacher.store #=> #<ImageUploader @storage_key=:store>
+attacher = ImageUploader::Attacher.new(photo, :image) # returned by `photo.image_attacher`
 
 attacher.assign(file) # equivalent to `photo.image = file`
 attacher.get          # equivalent to `photo.image`
 attacher.url          # equivalent to `photo.image_url`
-
-attacher.finalize     # promotes cached file to store, deletes old attachment (after save callback)
-attacher.destroy      # deletes attachment (after destory callback)
 ```
 
-See [Using Attacher] guide for more details.
+The attacher is what drives attaching files to models, 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.
 
-### Multiple files
+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.
 
-Sometimes we want to allow users to upload multiple files at once. This can be
-achieved with by adding a `multiple` HTML attribute to the file field: `<input
-type="file" multiple>`.
+For more information about `Shrine::Attacher`, see [Using Attacher] guide.
 
-Shrine doesn't accept multiple files on single a attachment attribute, but you
-can instead attach each file to a separate database record, which is a much
-more flexible solution.
+## Plugin system
 
-The best way is to [directly upload][direct uploads] selected files, and then
-send the data of uploaded files as nested attributes for associated records.
-Alternatively you can send all selected files at once, and then transform them
-into nested association attributes in the controller.
+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.
 
-## Uploader
+```rb
+Shrine.plugin :logging # adds logging
+```
 
-"Uploaders" are subclasses of `Shrine`, and this is where we define all our
-attachment logic. Uploader objects act as a wrappers around a storage; they
-don't know anything about models, and are stateless.
+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 DocumentUploader < Shrine
-  # document uploading logic
+class ImageUploader < Shrine
+  plugin :store_dimensions # extract image dimensions only for this uploader and its descendants
 end
 ```
+
+## Metadata
+
+Shrine automatically extracts available file metadata and saves them to the
+`Shrine::UploadedFile`. You can access them through the `#metadata` hash or via
+metadata methods:
+
 ```rb
-uploader = DocumentUploader.new(:store)
-uploaded_file = uploader.upload(File.open("resume.pdf"))
-uploaded_file #=> #<Shrine::UploadedFile>
-uploaded_file.to_json #=> '{"storage":"store","id":"0sdfllasfi842.pdf","metadata":{...}}'
-```
+uploaded_file.metadata #=>
+# {
+#   "filename" => "matrix.mp4",
+#   "mime_type" => "video/mp4",
+#   "size" => 345993,
+# }
 
-The `Shrine#upload` method does the following:
+uploaded_file.original_filename #=> "matrix.mp4"
+uploaded_file.extension         #=> "mp4"
+uploaded_file.mime_type         #=> "video/mp4"
+uploaded_file.size              #=> 345993
+```
 
-* calls processing
-* extracts metadata
-* generates unique location
-* uploads file(s) (this is where the storage is called)
-* closes uploaded file(s)
+### MIME type
 
-Shrine requires the input for uploading to be an IO-like object. So, `File`,
-`Tempfile` and `StringIO` instances are all valid inputs. The object doesn't
-have to be an actual IO, it's enough that it responds to: `#read(*args)`,
-`#size`, `#eof?`, `#rewind` and `#close`. `ActionDispatch::Http::UploadedFile`
-is one such object, as well as `Shrine::UploadedFile` itself.
+By default "mime_type" will be inherited from `#content_type` of the uploaded
+file, which is set from the "Content-Type" request header, but 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.
 
-The result of uploading is a `Shrine::UploadedFile` object, which represents
-the uploaded file on the storage, and is defined by its underlying data hash.
+However, if you load the `determine_mime_type` plugin, that will make Shrine
+always extract the MIME type from **file content** .
 
 ```rb
-uploaded_file.url      #=> "uploads/938kjsdf932.mp4"
-uploaded_file.metadata #=> {...}
-uploaded_file.download #=> #<Tempfile:/var/folders/k7/6zx6dx6x7ys3rv3srh0nyfj00000gn/T/20151004-74201-1t2jacf.mp4>
-uploaded_file.exists?  #=> true
-uploaded_file.open { |io| io.read }
-uploaded_file.delete
-# ...
+Shrine.plugin :determine_mime_type
 ```
-
-This is the same object that is returned when we access the attachment through
-the record:
-
 ```rb
-photo.image #=> #<Shrine::UploadedFile>
+File.write("image.png", "<?php ... ?>") # PHP file with a .png extension
+photo = Photo.create(image: File.open("image.png"))
+photo.image.mime_type #=> "text/x-php"
 ```
 
-### Plugins
+By the default the UNIX [`file`] utility is used, but you can also choose a
+different analyzer, see plugin's documentation for more details.
 
-Shrine comes with a small core which provides only the essential functionality,
-and any additional features are available via plugins. This way you can choose
-exactly what and how much Shrine does for you. See the [website] for a complete
-list of plugins.
+### Custom metadata
 
-The plugin system respects inheritance, so you can choose to load a plugin
-globally or only for a specific uploader.
+In addition to the built-in metadata, you can also extract and store completely
+custom metadata with the `add_metadata` plugin. For example, if we're uploading
+videos, we could store additional video-specific metadata:
 
 ```rb
-Shrine.plugin :logging # enables logging for all uploaders
+require "streamio-ffmpeg"
 
-class ImageUploader < Shrine
-  plugin :backup # stores backups only for this uploader and its descendants
+class VideoUploader < Shrine
+  plugin :add_metadata
+
+  add_metadata do |io, context|
+    movie = FFMPEG::Movie.new(io.path)
+
+    { "duration"   => movie.duration,
+      "bitrate"    => movie.bitrate,
+      "resolution" => movie.resolution,
+      "frame_rate" => movie.frame_rate }
+  end
 end
 ```
+```rb
+video.metadata["duration"]   #=> 7.5
+video.metadata["bitrate"]    #=> 481
+video.metadata["resolution"] #=> "640x480"
+video.metadata["frame_rate"] #=> 16.72
+```
 
 ## Processing
 
-Shrine allows you to perform file processing in functional style; you receive
-the original file as the input, and return processed files as the output.
+You can have Shrine perform file processing before uploading to storage. It's
+generally best to process files prior to uploading to permanent storage,
+because at that point the selected file has been succesfully validated, and
+this part can be moved into a background job.
 
-Processing can be performed whenever a file is uploaded. On attaching this
-happens twice; first the raw file is cached to temporary storage ("cache"
-action), then when the record is saved the cached file is "promoted" to
-permanent storage ("store" action). We generally want to process on the "store"
-action, because it happens after file validations and can be backgrounded.
+This promote phase is called `:store`, and we can use the `processing` plugin
+to define processing for that phase:
 
 ```rb
 class ImageUploader < Shrine
@@ -304,11 +468,16 @@ class ImageUploader < Shrine
 end
 ```
 
-Ok, now how do we do the actual processing? Well, Shrine actually doesn't ship
+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 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
+# Gemfile
+gem "image_processing"
+gem "mini_magick", ">= 4.3.5"
+```
 ```rb
 require "image_processing/mini_magick"
 
@@ -317,23 +486,31 @@ class ImageUploader < Shrine
   plugin :processing
 
   process(:store) do |io, context|
-    resize_to_limit(io.download, 700, 700)
+    resize_to_limit!(io.download, 800, 800)
   end
 end
 ```
 
 Here the `io` is a cached `Shrine::UploadedFile`, so we need to download it to
-a `File`, since this is what image_processing gem recognizes.
+a file, since file processing tools usually work with files on the filesystem.
+
+Shrine treats file processing as a functional transformation; you are given the
+original file, and how you're going to perform processing is entirely up to
+you, you only need to return the processed files at the end of the block. Then
+instead of uploading the original file, Shrine will continue to upload the
+files that the processing block returned.
 
 ### Versions
 
 Sometimes we want to generate multiple files as the result of processing. If
 we're uploading images, we might want to store various thumbnails alongside the
-original image. If we're uploading videos, we might want to save a screenshot
-or transcode it into different formats.
+original image. If we're uploading videos, we might want to save screenshots
+or transcode the video into different formats.
 
-To save multiple files, we just need to load the `versions` plugin, and then in
-`#process` we can return a Hash of files:
+To be able to save multiple files, we just need to load the `versions` plugin,
+and then in processing block we can return a Hash of files. It is recommended
+to also load the `delete_raw` plugin, so that processed files are automatically
+deleted after uploading.
 
 ```rb
 require "image_processing/mini_magick"
@@ -341,45 +518,60 @@ require "image_processing/mini_magick"
 class ImageUploader < Shrine
   include ImageProcessing::MiniMagick
   plugin :processing
-  plugin :versions
+  plugin :versions   # enable Shrine to handle a hash of files
+  plugin :delete_raw # delete processed files after uploading
 
   process(:store) do |io, context|
-    size_700 = resize_to_limit(io.download, 700, 700)
-    size_500 = resize_to_limit(size_700,    500, 500)
-    size_300 = resize_to_limit(size_500,    300, 300)
+    original = io.download
+
+    size_800 = resize_to_limit!(original, 800, 800)
+    size_500 = resize_to_limit(size_800,  500, 500)
+    size_300 = resize_to_limit(size_500,  300, 300)
 
-    {large: size_700, medium: size_500, small: size_300}
+    {original: io, large: size_800, medium: size_500, small: size_300}
   end
 end
 ```
 
-By defining processing on instance-level Shrine gives you a lot of flexibility.
-You could choose the processing order which yields the best performance, even
-add parallelization, and when processing logic gets complex you could extract
-everything into a PORO class. It is recommended to load the `delete_raw` plugin
-so that processed files are automatically deleted after uploading.
-
-Each version will be saved to the attachment column, and the attachment getter
-will simply return a Hash of `Shrine::UploadedFile` objects:
+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.
 
 ```rb
-photo.image #=> {large: ..., medium: ..., small: ...}
+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.image #=>
+# {
+#   :original => #<Shrine::UploadedFile @data={"id"=>"9sd84.jpg", ...}>,
+#   :large    => #<Shrine::UploadedFile @data={"id"=>"lg043.jpg", ...}>,
+#   :medium   => #<Shrine::UploadedFile @data={"id"=>"kd9fk.jpg", ...}>,
+#   :small    => #<Shrine::UploadedFile @data={"id"=>"932fl.jpg", ...}>,
+# }
+
+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"
+```
 
-# With the store_dimensions plugin (requires fastimage gem)
-photo.image[:large].width  #=> 700
-photo.image[:medium].width #=> 500
-photo.image[:small].width  #=> 300
+The `versions` plugin also expands `#<attachment>_url` to accept version names:
 
-# The plugin expands this method to accept version names.
+```rb
 photo.image_url(:large) #=> "..."
 ```
 
 ### Custom processing
 
 Your processing tool doesn't have to be in any way designed for Shrine
-([image_processing] is a generic library), you only need to return processed
-files as IO objects, e.g. `File` objects. Here's an example of processing a
-video with [ffmpeg]:
+([image_processing] that we saw earlier is a generic library), the only thing
+that you need to do is return processed files as some kind of IO objects. Here
+is an example of transcoding a video using [ffmpeg]:
 
 ```rb
 require "streamio-ffmpeg"
@@ -387,6 +579,7 @@ require "streamio-ffmpeg"
 class VideoUploader < Shrine
   plugin :processing
   plugin :versions
+  plugin :delete_raw
 
   process(:store) do |io, context|
     mov        = io.download
@@ -404,286 +597,136 @@ class VideoUploader < Shrine
 end
 ```
 
-### Triggering processing
-
-Whenever a file is uploaded by the attacher, an additional `:action` parameter
-is added to the context, which holds a symbol name describing what the file was
-uploaded for. For example, for caching files `action: :cache` will be sent, for
-promoting `action: :store`, while for backing up attacher sends `action:
-:backup`.
-
-The argument to the `process` declaration is the name of that action. When
-uploading via the uploader, you can add `:action` option with the value of the
-processing block you want performed before uploading.
-
-```rb
-uploader = ImageUploader.new(:store)
-uploader.upload(file, action: :store) # performs processing defined under ":store"
-```
-
-You can also define and call processing for a custom action:
-
-```rb
-class ImageUploader < Shrine
-  process(:my_action) { |io, context| special_processing(io) }
-end
-```
-```rb
-uploader.upload(file, action: :my_action)
-```
+## Context
 
-Finally, you can also call defined processing directly, without uploading the
-results, using `Shrine#process`.
+The `#upload` (and `#delete`) methods accept a hash of options as the second
+argument, which is forwarded to all other tasks like processing, extracting
+metadata and generating location.
 
 ```rb
-uploader.process(file, action: :my_action) # returns processed files without uploading
+uploader.upload(file, {foo: "bar"}) # context hash is forwarded to all tasks around upload
 ```
 
-## Context
-
-You may have noticed the `context` variable floating around as the second
-argument for processing. This variable is present all the way from input file
-to uploaded file, and can contain useful information depending on the situation:
+Some options are actually recognized by Shrine, like `:location` and
+`:upload_options`, and some are added by plugins. However, most options are
+there just to provide you context, for more flexibility in performing tasks and
+better logging.
 
-* `context[:record]` -- the model instance
-* `context[:name]` -- attachment name on the model
-* `context[:action]` -- identifier for the action being performed (`:cache`, `:store`, `:recache`, `:backup`, ...)
-* `context[:version]` -- version name of the IO in the argument
-* ...
+The attacher automatically includes additional `context` information for each
+upload and delete:
 
-The `context` is useful for doing conditional processing, validation,
-generating location etc, and it is also used by some plugins internally.
+* `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].guest?
+    trim_video(io, 300) if context[:record].user.free_plan?
   end
 end
 ```
 
-The context is just a hash that is passed to the uploader methods. If you're
-using the uploader directly, you can pass the context directly:
-
-```rb
-uploader.upload(file, {foo: "bar"}) # passing context hash directly
-```
-
-## Metadata
-
-Shrine automatically extracts and stores available file metadata:
-
-```rb
-photo = Photo.create(image: image)
-
-photo.image.metadata #=>
-# {
-#   "filename"  => "nature.jpg",
-#   "mime_type" => "image/jpeg",
-#   "size"      => 345993,
-# }
-
-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 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
-default uses the UNIX [file] utility to determine the actual MIME type:
-
-```rb
-Shrine.plugin :determine_mime_type
-```
-```rb
-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"
-```
-
-### Custom metadata
-
-You can also extract and store completely custom metadata with the
-`add_metadata` plugin:
-
-```rb
-require "mini_magick"
-
-class ImageUploader < Shrine
-  plugin :add_metadata
-
-  add_metadata :exif do |io, context|
-    MiniMagick::Image.new(io.path).exif
-  end
-end
-```
-```rb
-photo.image.metadata["exif"]
-# or
-photo.image.exif
-```
-
 ## Validation
 
-Validations are registered inside a `Attacher.validate` block, and you can load
-the `validation_helpers` plugin to get some convenient file validation methods:
+Shrine can perform file validations for files assigned to the model. The
+validations are registered inside a `Attacher.validate` block, and you can load
+the `validation_helpers` plugin to get convenient file validation methods:
 
 ```rb
-class VideoUploader < Shrine
+class DocumentUploader < Shrine
   plugin :validation_helpers
 
   Attacher.validate do
-    validate_max_size 50*1024*1024, message: "is too large (max is 50 MB)"
-    validate_mime_type_inclusion ["video/mp4"]
+    validate_max_size 5*1024*1024, message: "is too large (max is 5 MB)"
+    validate_mime_type_inclusion ["application/pdf"]
   end
 end
 ```
 
 ```rb
-trailer = Trailer.new
-trailer.video = File.open("matrix.mp4")
-trailer.valid? #=> false
-trailer.errors.to_hash #=> {video: ["is too large (max is 50 MB)"]}
+user = User.new
+user.cv = File.open("cv.pdf")
+user.valid? #=> false
+user.errors.to_hash #=> {cv: ["is too large (max is 5 MB)"]}
 ```
 
 You can also do custom validations:
 
 ```rb
-class VideoUploader < Shrine
+class DocumentUploader < Shrine
   Attacher.validate do
-    errors << "is longer than 5 minutes" if get.duration > 300
+    errors << "has more than 3 pages" if get.metadata["pages"] > 3
   end
 end
 ```
 
+When file validations fail, Shrine will by default keep the invalid cached file
+assigned to the model instance. If you want the invalid file to be deassigned,
+you can load the `remove_invalid` plugin.
+
 The `Attacher.validate` block is executed in context of a `Shrine::Attacher`
 instance:
 
 ```rb
-class VideoUploader < Shrine
+class DocumentUploader < Shrine
   Attacher.validate do
     self   #=> #<Shrine::Attacher>
 
     get    #=> #<Shrine::UploadedFile>
-    record # the model instance
-    errors # array of error messages for this file
+    record #=> #<User>
+    name   #=> :cv
   end
 end
 ```
 
-## Locations
-
-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
-photo = Photo.create(image: File.open("nature.jpg"))
-photo.image.id #=> "photo/34/image/34krtreds2df.jpg"
-```
+## Location
 
-If you want to generate locations on your own, you can override
-`Shrine#generate_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. You can change how the location is generated by overriding
+`#generate_location`:
 
 ```rb
 class ImageUploader < Shrine
   def generate_location(io, context)
-    if context[:record]
-      "#{context[:record].class}/#{super}"
-    else
-      super
-    end
+    type  = context[:record].class.name.downcase if context[:record]
+    style = context[:version] == :original ? "originals" : "thumbs" if context[:version]
+    name  = super # the default unique identifier
+
+    [type, style, name].compact.join("/")
   end
 end
 ```
-
-Note that there should always be a random component in the location, so that
-dirty tracking is 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 a `:location`:
-
-```rb
-uploader = MyUploader.new(:store)
-file = File.open("nature.jpg")
-uploader.upload(file, location: "some/specific/location.jpg")
-```
-
-## Storage
-
-"Storages" are objects which know how to manage files on a particular service.
-Other than [FileSystem], Shrine also ships with Amazon [S3] storage:
-
-```rb
-gem "aws-sdk", "~> 2.1"
-```
-```rb
-require "shrine/storage/s3"
-
-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-bucket"
-)
-```
-
-```rb
-photo = Photo.new(image: File.open("image.png"))
-photo.image_url #=> "/uploads/cache/j4k343ui12ls9.png"
-photo.save
-photo.image_url #=> "https://my-bucket.s3.amazonaws.com/0943sf8gfk13.png"
 ```
-
-Note that any options passed to `image_url` will be forwarded to the underlying
-storage, see the documentation of the storage that you're using for which URL
-options it supports.
-
-You can see the full documentation for [FileSystem] and [S3] storages. There
-are also many other Shrine storages available, see [External] section on the
-website.
-
-### Upload options
-
-Many storages accept additional upload options, which you can pass via the
-`upload_options` plugin, or manually when uploading:
-
-```rb
-uploader = MyUploader.new(:store)
-uploader.upload(file, upload_options: {acl: "private"})
+uploads/
+  photos/
+    originals/
+      la98lda74j3g.jpg
+    thumbs/
+      95kd8kafg80a.jpg
+      ka8agiaf9gk4.jpg
 ```
 
-### Clearing cache
+Note that there should always be a random component in the location, so that
+any ORM dirty tracking is detected properly. Inside `#generate_location` you
+can also access the extracted metadata through `context[:metadata]`.
 
-From time to time you'll want to clean your temporary storage from old files.
-Amazon S3 provides [a built-in solution][s3 lifecycle], and for FileSystem you
-can put something like this in your Rake task:
+When uploading single files, it's possible to bypass `#generate_location` via
+the uploader, by specifying `:location`:
 
 ```rb
-file_system = Shrine.storages[:cache]
-file_system.clear!(older_than: Time.now - 7*24*60*60) # delete files older than 1 week
+uploader.upload(file, location: "some/specific/location.mp4")
 ```
 
 ## Direct uploads
 
-Shrine comes with a `direct_upload` plugin for asynchronous uploads to your app
-or an external service like Amazon S3. It provides a [Roda] endpoint which you
-can mount in your app:
+Shrine comes with a `direct_upload` plugin that can be used for client-side
+asynchronous uploads to your app or an external service like Amazon S3. It
+provides a [Roda] app which you can mount in your app:
 
 ```rb
+# Gemfile
 gem "roda"
 ```
 ```rb
@@ -695,25 +738,26 @@ Rails.application.routes.draw do
 end
 ```
 
-This endpoint provides the following routes:
+The above setup will provide the following endpoints:
 
 * `POST /images/cache/upload` - for direct uploads to your app
 * `GET /images/cache/presign` - for direct uploads to external service (e.g. Amazon S3)
 
-These routes can be used to asynchronously start caching the file the moment
-the user selects it, using JavaScript file upload libraries like
-[jQuery-File-Upload], [Dropzone] or [FineUploader].
+Now when the user selects a file, the client can immediately start uploading
+the file asynchronously using one of these endpoints. For JavaScript you can
+use generic file upload libraries like [jQuery-File-Upload], [Dropzone] or
+[FineUploader].
 
-See the [direct_upload] plugin documentation and [Direct Uploads to S3] guide
-for more details, as well as the [Roda][roda_demo] and [Rails][rails_demo]
-demo apps which implement multiple uploads directly to S3.
+See the [direct_upload] plugin documentation and [Direct Uploads to S3][direct uploads]
+guide for more details, as well as the [Roda][roda_demo] and
+[Rails][rails_demo] demo apps which implement multiple uploads directly to S3.
 
 ## Backgrounding
 
-Shrine is the first file upload library designed for backgrounding support.
+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 really easy to plug in your favourite backgrounding library:
+which makes it easy to plug in your favourite backgrounding library:
 
 ```rb
 Shrine.plugin :backgrounding
@@ -738,23 +782,71 @@ end
 ```
 
 The above puts all promoting (uploading cached file to permanent storage) and
-deleting of files into a background Sidekiq job. Obviously instead of Sidekiq
-you can use [any other backgrounding library][backgrounding libraries].
+deleting of files into background jobs using Sidekiq. Obviously instead of
+Sidekiq you can use [any other backgrounding library][backgrounding libraries].
 
-The main advantages of Shrine's backgrounding support over other file upload
+The main advantages of Shrine's backgrounding support over other file attachment
 libraries are:
 
-* **User experience** – After starting the background job, Shrine will save the
+* **User experience** – Before starting the background job, Shrine will save the
   record with the cached attachment so that it can be immediately shown to the
   user. With other file upload libraries users cannot see the file until the
   background job has finished.
-* **Simplicity** – Instead of writing the workers for you, Shrine allows you
-  to use your own workers in a very simple way. Also, no extra columns are
-  required.
-* **Generality** – The above solution will automatically work for all uploaders,
+* **Simplicity** – Instead of shipping with workers for you, Shrine allows you
+  to write your own workers and plug them in very easily. And no extra
+  columns are required.
+* **Generality** – This setup will automatically be used for all uploaders,
   types of files and models.
-* **Safety** – All of Shrine's code has been designed to take delayed storing
-  into account, and concurrent requests are handled well.
+* **Safety** – All of Shrine's features have been designed to take delayed
+  storing into account, and concurrent requests are handled as well.
+
+## Clearing cache
+
+From time to time you'll want to clean your temporary storage from old files.
+Amazon S3 provides [a built-in solution][S3 lifecycle], and for FileSystem you
+can run something like this periodically:
+
+```rb
+file_system = Shrine.storages[:cache]
+file_system.clear!(older_than: Time.now - 7*24*60*60) # delete files older than 1 week
+```
+
+## 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
+accessed in other uploader actions. You can store there anything that you find
+convenient.
+
+```rb
+Shrine.opts[:type] = "file"
+
+class DocumentUploader < Shrine; end
+class ImageUploader < Shrine
+  opts[:type] = "image"
+end
+
+DocumentUploader.opts[:type] #=> "file"
+ImageUploader.opts[:type]    #=> "image"
+```
+
+Because `opts` is cloned in subclasses, overriding settings works with
+inheritance. The `opts` hash is used internally by plugins to store
+configuration.
 
 ## On-the-fly processing
 
@@ -780,10 +872,10 @@ be retried, while the previous chunks remain uploaded.
 [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
 networks, with the possibility to resume the upload even after the browser is
-closed or the device shut down. You can use a client library like
+closed or the device are shut down. You can use a client library like
 [tus-js-client] to upload the file to [tus-ruby-server], and attach the
 uploaded file to a record using [shrine-url]. See [shrine-tus-demo] for an
-example integration.
+example of complete implementation.
 
 Another option might be to do chunked uploads directly to your storage service,
 if the storage service supports it (e.g. Amazon S3 or Google Cloud Storage).
@@ -792,8 +884,8 @@ if the storage service supports it (e.g. Amazon S3 or Google Cloud Storage).
 
 Shrine was heavily inspired by [Refile] and [Roda]. From Refile it borrows the
 idea of "backends" (here named "storages"), attachment interface, and direct
-uploads. From Roda it borrows the implementation of an extensible [plugin
-system].
+uploads. From Roda it borrows the implementation of an extensible plugin
+system.
 
 ## Similar libraries
 
@@ -802,45 +894,47 @@ system].
 * Dragonfly
 * Refile
 
+## Code of Conduct
+
+Everyone interacting in the Shrine project’s codebases, issue trackers, and
+mailing lists is expected to follow the [Shrine code of conduct][CoC].
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License].
 
-[image_processing]: https://github.com/janko-m/image_processing
-[fastimage]: https://github.com/sdsykes/fastimage
-[file]: http://linux.die.net/man/1/file
-[image bombs]: https://www.bamsoftware.com/hacks/deflate.html
-[aws-sdk]: https://github.com/aws/aws-sdk-ruby
-[jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
-[Dropzone]: https://github.com/enyo/dropzone
-[FineUploader]: https://github.com/FineUploader/fine-uploader
-[Roda]: https://github.com/jeremyevans/roda
-[Refile]: https://github.com/refile/refile
-[plugin system]: http://twin.github.io/the-plugin-system-of-sequel-and-roda/
-[MIT License]: http://opensource.org/licenses/MIT
-[ships with over 35 plugins]: http://shrinerb.com#plugins
 [motivation]: https://twin.github.io/better-file-uploads-with-shrine-motivation/
 [FileSystem]: http://shrinerb.com/rdoc/classes/Shrine/Storage/FileSystem.html
 [S3]: http://shrinerb.com/rdoc/classes/Shrine/Storage/S3.html
-[External]: http://shrinerb.com#external
-[`Shrine::UploadedFile`]: http://shrinerb.com/rdoc/classes/Shrine/Plugins/Base/FileMethods.html
-[direct uploads]: #direct-uploads
+[direct uploads]: http://shrinerb.com/rdoc/files/doc/direct_s3_md.html
+[external storages]: http://shrinerb.com/#external
+[`rack_file`]: http://shrinerb.com/rdoc/classes/Shrine/Plugins/RackFile.html
+[Using Attacher]: http://shrinerb.com/rdoc/files/doc/attacher_md.html
+[plugins]: http://shrinerb.com/#plugins
+[`file`]: http://linux.die.net/man/1/file
+[backgrounding]: http://shrinerb.com/rdoc/classes/Shrine/Plugins/Backgrounding.html
+[Context]: https://github.com/janko-m/shrine#context
+[image_processing]: https://github.com/janko-m/image_processing
 [ffmpeg]: https://github.com/streamio/streamio-ffmpeg
+[jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
+[Dropzone]: https://github.com/enyo/dropzone
+[FineUploader]: https://github.com/FineUploader/fine-uploader
 [direct_upload]: http://shrinerb.com/rdoc/classes/Shrine/Plugins/DirectUpload.html
 [Cloudinary]: https://github.com/janko-m/shrine-cloudinary
 [Imgix]: https://github.com/janko-m/shrine-imgix
 [Uploadcare]: https://github.com/janko-m/shrine-uploadcare
 [Attache]: https://github.com/choonkeat/attache
-[roda_demo]: /demo
-[rails_demo]: https://github.com/erikdahlstrand/shrine-rails-example
-[Direct Uploads to S3]: http://shrinerb.com/rdoc/files/doc/direct_s3_md.html
-[website]: http://shrinerb.com
-[backgrounding libraries]: https://github.com/janko-m/shrine/wiki/Backgrounding-libraries
+[Dragonfly]: http://markevans.github.io/dragonfly/
 [tus]: http://tus.io
 [tus-ruby-server]: https://github.com/janko-m/tus-ruby-server
 [tus-js-client]: https://github.com/tus/tus-js-client
 [shrine-tus-demo]: https://github.com/janko-m/shrine-tus-demo
 [shrine-url]: https://github.com/janko-m/shrine-url
-[s3 lifecycle]: http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html
-[Dragonfly]: http://markevans.github.io/dragonfly/
-[Using Attacher]: http://shrinerb.com/rdoc/files/doc/attacher_md.html
+[Roda]: https://github.com/jeremyevans/roda
+[Refile]: https://github.com/refile/refile
+[MIT License]: http://opensource.org/licenses/MIT
+[CoC]: https://github.com/janko-m/shrine/blob/master/CODE_OF_CONDUCT.md
+[roda_demo]: https://github.com/janko-m/shrine/tree/master/demo
+[rails_demo]: https://github.com/erikdahlstrand/shrine-rails-example
+[backgrounding libraries]: https://github.com/janko-m/shrine/wiki/Backgrounding-libraries
+[S3 lifecycle]: http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html