shrine 3.0.0.beta2 → 3.0.0.beta3

data/doc/advantages.md

@@ -39,12 +39,9 @@ Shrine.plugin :hanami # https://github.com/katafrakt/hanami-shrine
 
 ## Simplicity
 
-Shrine was designed with simplicity in mind. Where other solutions favour
-complex class-level DSLs, Shrine chooses simple instance-level interfaces where
-you can write regular Ruby code.
-
-There are no `CarrierWave::Uploader::Base` and `Paperclip::Attachment` [god
-objects], Shrine has several core classes each with clear responsibilities:
+Where some popular file attachment libraries have [god objects]
+(`CarrierWave::Uploader::Base` and `Paperclip::Attachment`), Shrine has several
+core classes, each with a clear set of responsibilities:
 
 * Storage classes encapsulate file operations for the underlying service
 * `Shrine` handles uploads and manages plugins
@@ -59,14 +56,16 @@ photo.image.uploader #=> #<Shrine>
 photo.image_attacher #=> #<Shrine::Attacher>
 ```
 
-Special care was taken to make integrating new storages and ORMs possible with
-minimal amount of code.
+The attachment functionality is decoupled from persistence and storage, which
+makes it much easier to reason about. Also, special care was taken to make
+integrating new storages and ORMs possible with minimal amount of code.
 
 ## Modularity
 
 Shrine uses a [plugin system] that allows you to pick and choose the features
-that you want. Moreover, you're only loading the code for features that you
-use, which means that Shrine will generally load very fast.
+that you want. Moreover, you'll only be loading code for the features you've
+selected, which means that Shrine will generally much faster than the
+alternatives.
 
 ```rb
 Shrine.plugin :instrumentation
@@ -77,11 +76,9 @@ require "shrine/plugins/instrumentation"
 Shrine.plugin Shrine::Plugins::Instrumentation
 ```
 
-Shrine comes with a complete attachment functionality, but it also exposes many
-low level APIs that can be used for building your own customized attachment
-flow. For example, if you prefer the `Attachment`/`Blob` architecture Active
-Storage provides, you can ditch the Shrine's attachment implementation and use
-uploaders and uploaded files that are decoupled from attachment:
+Shrine recommends a certain type of attachment flow, but it still offers good
+low-level abstractions that give you the flexibility to build your own
+attachment flow.
 
 ```rb
 uploaded_file = ImageUploader.upload(image, :store) # metadata extraction, upload location generation
@@ -101,8 +98,8 @@ uploaded_file.delete
 
 Shrine is very diligent when it comes to dependencies. It has two mandatory
 dependencies – [Down] and [ContentDisposition] – which are loaded only by
-components that need them. Some Shrine plugins require additional dependencies,
-but you only need to load them if you're using those plugins.
+components that need them. Some Shrine plugins also require additional
+dependencies, but you only need to load them if you're using those plugins.
 
 Moreover, Shrine often gives you the ability choose between multiple
 alternative dependencies for doing the same task. For example, the
@@ -117,33 +114,36 @@ Shrine.plugin :store_dimensions,    analyzer: :mini_magick
 ```
 
 This approach gives you control over your dependencies by allowing you to
-choose the combination that best suit your needs.
+choose the combination that best suits your needs.
 
 ## Inheritance
 
 Shrine is designed to handle any types of files. If you're accepting uploads of
 multiple types of files, such as videos and images, chances are that the logic
-for handling them will be very different:
+for handling them will differ:
 
 * small images can be processed on-the-fly, but large files should be processed in a background job
-* which storage service is most suitable might depend on the filetype (images, documents, audios, videos)
-* different filetypes have different metadata to extract which require different tools
+* you might want to store different files to different storage services (images, documents, audios, videos)
+* extracting metadata might require different tools depending on the filetype
 
 With Shrine you can create isolated uploaders for each type of file. Plugins
-that you want to be applied to both uploaders can be applied globally, while
+that you want to be applied to all uploaders can be applied globally, while
 other plugins would be loaded only for a specific uploader.
 
 ```rb
+# loaded for all plugins
 Shrine.plugin :activerecord
 Shrine.plugin :instrumentation
 ```
 ```rb
 class ImageUploader < Shrine
+  # loaded only for ImageUploader
   plugin :store_dimensions
 end
 ```
 ```rb
 class VideoUploader < Shrine
+  # loaded only for VideoUploader
   plugin :default_storage, store: :vimeo
 end
 ```
@@ -151,31 +151,28 @@ end
 ## Processing
 
 Most file attachment libraries give you the ability to process files either "on
-upload" (Paperclip, CarrierWave) or "on-the-fly" (Dragonfly, Refile, Active
-Storage). Having only one option is not ideal, because some type of files
-it's more suitable to process on-the-fly (image thumbnails, document previews),
-while other types of files should be processed in a background job (video
-transcoding, raw images)
+attachment" (Paperclip, CarrierWave) or "on-the-fly" (Dragonfly, Refile, Active
+Storage). However, you should ideally be able to choose both, because both
+approaches have their pros and cons. For example, on-the-fly processing is only
+suitable for fast processing (image thumbnails, document previews), longer
+running processing should be moved into a background job (video transcoding,
+raw images).
 
 Shrine is the first file attachment library that has support for both
-processing on upload and on-the-fly. So, if you're handling image uploads, you
-can choose to either generate a set of pre-defined image thumbnails in a
+processing on attachment and on-the-fly. So, if you're handling image uploads,
+you can choose to either generate a set of pre-defined image thumbnails in a
 background job:
 
 ```rb
 class ImageUploader < Shrine
-  process(:store) do |io|
-    versions = { original: io }
-
-    io.download do |original|
-      pipeline = ImageProcessing::MiniMagick.source(original)
-
-      versions[:large]  = pipeline.resize_to_limit!(800, 800)
-      versions[:medium] = pipeline.resize_to_limit!(500, 500)
-      versions[:small]  = pipeline.resize_to_limit!(300, 300)
-    end
-
-    versions
+  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
 ```
@@ -206,11 +203,11 @@ Many file attachment libraries, such as CarrierWave, Paperclip, Dragonfly and
 Refile, implement their own image processing macros. Instead of creating
 yet another in-house implementation, the **[ImageProcessing]** gem was created.
 
-Even though the ImageProcessing gem was created for Shrine, it's completely
-generic and can be used standalone, or in any other file upload library (e.g.
-Active Storage uses it now as well). It takes care of many details for you,
-such as [auto orienting] the input image and [sharpening] the thumbnails after
-they are resized.
+While the ImageProcessing gem was created for Shrine, it's completely generic
+and can be used standalone or with any other file upload library (e.g. Active
+Storage 6+ uses it). It takes care of many details for you, such as [auto
+orienting] the input image and [sharpening] the thumbnails after they are
+resized.
 
 ```rb
 require "image_processing"
@@ -234,17 +231,11 @@ The `ImageProcessing::Vips` backend implements the same API as
 `ImageProcessing::MiniMagick`, so you can easily swap one for the other.
 
 ```rb
-require "image_processing/mini_magick"
 require "image_processing/vips"
-require "open-uri"
 
-original = open("https://upload.wikimedia.org/wikipedia/commons/3/36/Hopetoun_falls.jpg")
-
-ImageProcessing::MiniMagick.resize_to_fit(800, 800).call(original)
-#=> 1.0s
-
-ImageProcessing::Vips.resize_to_fit(800, 800).call(original)
-#=> 0.2s (5x faster)
+ImageProcessing::Vips
+  .source(image)
+  .resize_to_limit!(400, 400)
 ```
 
 ### Other processors
@@ -253,20 +244,20 @@ Both processing "on upload" and "on-the-fly" work in a way that you define a
 Ruby block, which accepts a source file and is expected to return a processed
 file. How you're going to do the processing is entirely up to you.
 
-This allows you to use any tool you want. For example, you could use the
-[image_optim] gem to perform additional image optimizations:
+This allows you to use any tool you want. For example, you could implement
+video transcoding:
 
 ```rb
 class VideoUploader < Shrine
-  derivation :thumbnail do |file, width, height|
-    thumbnail = ImageProcessing::MiniMagick
-      .source(file)
-      .resize_to_limit!(width, height)
+  Attacher.derivatives_processor do |original|
+    transcoded = Tempfile.new ["transcoded", ".mp4"]
+    screenshot = Tempfile.new ["screenshot", ".jpg"]
 
-    image_optim = ImageOptim.new
-    image_optim.optimize_image!(thumbnail.path)
+    movie = FFMPEG::Movie.new(original.path)
+    movie.transcode(transcoded.path)
+    movie.screenshot(screenshot.path)
 
-    thumbnail
+    { transcoded: transcoded, screenshot: screenshot }
   end
 end
 ```
@@ -291,7 +282,7 @@ photo.image.metadata #=>
 # }
 ```
 
-For common metadata there are already [validation macros][validation_helpers],
+For common metadata you can use the built-in [validators][validation_helpers],
 but you can also [validate any custom metadata][custom validations].
 
 ```rb
@@ -299,11 +290,11 @@ class DocumentUploader < Shrine
   Attacher.validate do
     # validation macros
     validate_max_size 10*1024*1024
-    validate_mime_type_inclusion %W[application/pdf]
+    validate_mime_type %W[application/pdf]
 
     # custom validations
-    if get.metadata["page_count"] > 30
-      errors << "has too many pages (max is 30)"
+    if file["page_count"] > 30
+      errors << "must not have more than 30 pages"
     end
   end
 end
@@ -317,6 +308,21 @@ feature in mind from day one. It is supported via the
 [`backgrounding`][backgrounding] plugin and can be used with [any backgrounding
 library][backgrounding libraries].
 
+```rb
+Shrine::Attacher.promote_block do
+  PromoteJob.perform_later(self.class, record, name, file_data)
+end
+```
+```rb
+class PromoteJob < ActiveJob::Base
+  def perform(attacher_class, record, name, file_data)
+    attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
+    attacher.create_derivatives # perform processing
+    attacher.atomic_promote
+  end
+end
+```
+
 ## Direct Uploads
 
 Shrine doesn't come with a plug-and-play JavaScript solution for client-side
@@ -350,24 +356,25 @@ memory usage.
 Alternatively, you can have [resumable multipart uploads directly to
 S3][uppy-s3_multipart].
 
-## Security
+## Summary
+
+Shrine is general purpose, it can integrate with any web framework and any
+database library. It has core classes with clearly defined responsibilities,
+which provide both higher and lower level abstractions. The functionality is
+very modular, you can pick and choose features that you need.
 
-It's [important][OWASP] to care about security when handling file uploads, and
-Shrine bakes in many good practices. For starters, it uses a separate
-"temporary" storage for direct uploads, making it easy to periodically clear
-uploads that didn't end up being attached and difficult for the attacker to
-flood the main storage.
+With Shrine you can process both on attachment and on-the-fly, depending on
+what is more suitable for your requirements. Processing is just a functional
+transformation, which makes it easier to use the processing tool of your
+choice. You can also move processing into a background job.
 
-File processing and upload to permanent storage is done outside of a database
-transaction, and only after the file has been successfully validated. The
-`determine_mime_type` plugin determines MIME type from the file content (rather
-than relying on the `Content-Type` request header), preventing exploits like
-[ImageTragick].
+Shrine automatically extracts metadata from the main file and any processed
+files. In addition to built-in metadata you can also extract any custom
+metadata. Any extracted metadata can be validated on attachment.
 
-The `remote_url` plugin requires specifying a `:max_size` option, which limits
-the maximum allowed size of the remote file. The [Down] gem which the
-`remote_url` plugin uses will [terminate the download early][Down max size]
-when it realizes it's too large.
+Finally, Shrine integrates with Uppy, a full-featured JavaScript file upload
+library. It allows you to do direct uploads to your app or to S3. For large
+files you can also make the uploads resumable.
 
 [Paperclip]: https://github.com/thoughtbot/paperclip
 [CarrierWave]: https://github.com/carrierwaveuploader/carrierwave
@@ -397,7 +404,6 @@ when it realizes it's too large.
 [ruby-vips]: https://github.com/libvips/ruby-vips
 [god objects]: https://en.wikipedia.org/wiki/God_object
 [ImageMagick]: https://www.imagemagick.org
-[refile-mini_magick]: https://github.com/refile/refile-mini_magick
 [ImageProcessing]: https://github.com/janko/image_processing
 [auto orienting]: https://www.imagemagick.org/script/command-line-options.php#auto-orient
 [sharpening]: https://photography.tutsplus.com/tutorials/what-is-image-sharpening--cms-26627
@@ -423,10 +429,6 @@ when it realizes it's too large.
 [tus implementations]: https://tus.io/implementations.html
 [tus-ruby-server]: https://github.com/janko/tus-ruby-server
 [shrine-tus]: https://github.com/shrinerb/shrine-tus
-[ImageTragick]: https://imagetragick.com
 [uppy-s3_multipart]: https://github.com/janko/uppy-s3_multipart
-[OWASP]: https://www.owasp.org/index.php/Unrestricted_File_Upload
-[image_optim]: https://github.com/toy/image_optim
 [validation_helpers]: /doc/plugins/validation_helpers.md#readme
 [custom validations]: /doc/validation.md#custom-validations
-[Down max size]: https://github.com/janko/down#maximum-size

data/doc/attacher.md

@@ -1,283 +1,453 @@
 # Using Attacher
 
-The most convenient way to use Shrine is through the model, using the interface
-provided by Shrine's attachment module. This way you can interact with the
-attachment just like with any other column attribute, and adding attachment
-fields to the form just works.
+This guide explains what is `Shrine::Attacher` and how to use it.
+
+## Contents
+
+* [Introduction](#introduction)
+* [Storage](#storage)
+* [Attaching](#attaching)
+  - [Attaching cached](#attaching-cached)
+  - [Attaching stored](#attaching-stored)
+  - [Uploading](#uploading)
+  - [Changes](#changes)
+* [Finalizing](#finalizing)
+  - [Promoting](#promoting)
+  - [Replacing](#replacing)
+* [Retrieving](#retreiving)
+  - [File](#file)
+  - [Attached](#attached)
+  - [URL](#url)
+  - [Data](#data)
+* [Deleting](#deleting)
+* [Context](#context)
+
+## Introduction
+
+The attachment logic is handled by a `Shrine::Attacher` object. The
+`Shrine::Attachment` module simply provides a convenience layer around a
+`Shrine::Attacher` object, which can be accessed via the `#<name>_attacher`
+attribute.
 
 ```rb
-class Photo < Sequel::Model
-  include ImageUploader::Attachment.new(:image)
+class Photo
+  include ImageUploader::Attachment(:image)
 end
 ```
+```rb
+photo = Photo.new
+photo.image_attacher #=> #<ImageUploader::Attacher>
+```
 
-However, if you don't want to add additional methods on the model and prefer
-explicitness, or you need more control, you can achieve the same behaviour
-using the `Shrine::Attacher` object, which is what the attachment interface
-uses under the hood.
+We can also instantiate the same `Shrine::Attacher` object directly:
 
 ```rb
-attacher = ImageUploader::Attacher.new(photo, :image) # equivalent to `photo.image_attacher`
-attacher.assign(file)                                 # equivalent to `photo.image = file`
-attacher.get                                          # equivalent to `photo.image`
+attacher = ImageUploader::Attacher.from_model(photo, :image)
+attacher.file # called by `photo.image`
+attacher.url  # called by `photo.image_url`
 ```
 
-The attacher will use the `<attachment>_data` attribute for storing information
-about the attachment.
+The `model`, `entity`, and `column` plugins provide additional
+`Shrine::Attacher` methods (such as `Shrine::Attacher.from_model` we see
+above), but in this guide we'll focus only on the core `Shrine::Attacher`
+methods.
+
+So, we'll assume a `Shrine::Attacher` object not backed by any model/entity:
 
 ```rb
-attacher.data_attribute #=> :image_data
+attacher = Shrine::Attacher.new
 ```
 
-## Initializing
+## Storage
 
-The attacher object exposes the objects it uses:
+By default, an `Attacher` will use the `:cache` storage as the **temporary**
+storage, and the `:store` storage as the **permanent** storage.
 
 ```rb
-attacher.record #=> #<Photo>
-attacher.name   #=> :image
-attacher.cache  #=> #<ImageUploader @storage_key=:cache>
-attacher.store  #=> #<ImageUploader @storage_key=:store>
+Shrine.storages = {
+  cache: Shrine::Storage::Memory.new,
+  store: Shrine::Storage::Memory.new,
+}
+```
+```rb
+attacher = Shrine::Attacher.new
+attacher.cache_key #=> :cache
+attacher.store_key #=> :store
 ```
 
-The attacher will automatically use `:cache` and `:store` storages, but you can
-also tell it to use different temporary and permanent storage:
+We can also change the default storage:
 
 ```rb
-ImageUploader::Attacher.new(photo, :image, cache: :other_cache, store: :other_store)
+attacher = Shrine::Attacher.new(cache: :other_cache, store: :other_store)
+attacher.cache_key #=> :other_cache
+attacher.store_key #=> :other_store
+```
 
-# OR
+You can also change default attacher options on the `Shrine::Attachment`
+module:
 
-photo.image_attacher(cache: :other_cache, store: :other_store)
-photo.image = file # uploads to :other_cache storage
-photo.save         # promotes to :other_store storage
+```rb
+class Photo
+  include ImageUploader::Attachment(:image, cache: :other_cache, store: :other_store)
+end
 ```
 
-You can pass the `:cache` and `:store` options via `Attachment.new` too:
+The `Attacher#cache` and `Attacher#store` methods will retrieve corresponding
+uploaders:
 
 ```rb
-class Photo < Sequel::Model
-  include ImageUploader::Attachment.new(:image, cache: :other_cache, store: :other_store)
-end
+attacher.cache #=> #<MyUploader @storage_key=:cache>
+attacher.store #=> #<MyUploader @storage_key=:store>
+```
+
+## Attaching
+
+### Attaching cached
+
+For attaching files submitted via a web form, `Attacher#assign` can be used:
+
+```rb
+attacher.assign(file)
 ```
 
-Note that it's not necessary to use the temporary storage, see the next section
-for more details.
+If given a raw file, it will upload it to temporary storage:
 
-## Assignment
+```rb
+attacher.assign(file)
+attacher.file #=> #<Shrine::UploadedFile @id="asdf.jpg", @storage_key=:cache>
+```
 
-The `#assign` method accepts either an IO object to be cached, or an already
-cached file in form of a JSON string, and assigns the cached result to record's
-`<attachment>_data` attribute.
+If given cached file data (JSON or Hash), it will set the cached file:
 
 ```rb
-# uploads the `io` object to temporary storage, and writes to the data column
-attacher.assign(io)
+attacher.assign('{"id":"asdf.jpg","storage":"cache","metadata":{...}}')
+attacher.file #=> #<Shrine::UploadedFile @id="asdf.jpg", @storage_key=:cache>
+```
+
+If given an empty string, it will no-op:
 
-# writes the given cached file to the data column
-attacher.assign('{"id":"9260ea09d8effd.jpg","storage":"cache","metadata":{ ... }}')
+```rb
+attacher.assign("") # no-op
 ```
 
-When assigning an IO object, any additional options passed to `#assign` will be
-forwarded to `Shrine#upload`. This allows you to do things like overriding
-metadata, setting upload location, or passing upload options:
+If given `nil`, it will clear the attached file:
 
 ```rb
-attacher.assign io,
-  metadata:       { "filename" => "myfile.txt" },
-  location:       "custom/location",
-  upload_options: { acl: "public-read" }
+attacher.file #=> <Shrine::UploadedFile>
+attacher.assign(nil)
+attacher.file #=> nil
 ```
 
-If you're attaching a cached file and want to override its metadata before
-assignment, you can do it like so:
+This plays nicely with the recommended HTML form fields for the attachment. If
+you're not using the `hidden` form field (and therefore don't need empty
+strings to be handled), you can also use `Attacher#attach_cached`:
 
 ```rb
-cached_file = Shrine.uploaded_file('{"id":"9260ea09d8effd.jpg","storage":"cache","metadata":{ ... }}')
-cached_file.metadata["filename"] = "myfile.txt"
+# uploads file to cache
+attacher.attach_cached(file)
+
+# sets cached file
+attacher.attach_cached('{"id":"asdf.jpg","storage":"cache","metadata":{...}}')
+attacher.attach_cached("id" => "asdf.jpg", "storage" => "cache", "metadata" => { ... })
+attacher.attach_cached(id: "asdf.jpg", storage: "cache", metadata: { ... })
 
-attacher.assign(cached_file.to_json)
+# unsets attached file
+attacher.attach_cached(nil)
 ```
 
-For security reasons `#assign` doesn't accept files uploaded to permanent
-storage, but you can use `#set` to attach any `Shrine::UploadedFile` object.
-You can use this to skip temporary storage altogether and upload files directly
-to permanent storage:
+### Attaching stored
+
+The `Attacher#attach` method uploads a given file to permanent storage:
 
 ```rb
-uploaded_file = attacher.store!(file) # upload a file directly to permanent storage
-attacher.set(uploaded_file)          # attach the uploaded file
+attacher.attach(file)
+attacher.file #=> #<Shrine::UploadedFile @id="asdf.jpg" @storage=:store>
 ```
 
-## Retrieval
+This method is useful when attaching files from scripts, where validation
+doesn't need to be performed, and where temporary storage can be skipped.
 
-The `#get` method reads record's `<attachment>_data` attribute, and constructs
-a `Shrine::UploadedFile` object from it.
+You can specify a different destination storage with the `:storage` option:
 
 ```rb
-attacher.get #=> #<Shrine::UploadedFile>
+attacher.attach(file, storage: :other_store)
+attacher.file #=> #<Shrine::UploadedFile @id="asdf.jpg" @storage=:other_store>
 ```
 
-The `#read` method will just return the value of the underlying
-`<attachment>_data` attribute.
+Any additional options passed to `Attacher#attach`, `Attacher#attach_cached`
+and `Attacher#assign` are forwarded to the uploader:
 
 ```rb
-attacher.read #=> '{"id":"dsg024lfs.jpg","storage":"cache","metadata":{...}}'
+attacher.attach(file, metadata: { "foo" => "bar" })       # adding metadata
+attacher.attach(file, upload_options: { acl: "private" }) # setting upload options
+attacher.attach(file, location: "path/to/file")           # setting upload location
 ```
 
-In general you can use `#uploaded_file` to contruct a `Shrine::UploadedFile`
-from a JSON string.
+### Uploading
+
+If you want to upload a file to without attaching it, you can use
+`Attacher#upload`:
 
 ```rb
-attachment_data = '{"id":"dsg024lfs.jpg","storage":"cache","metadata":{...}}'
-attacher.uploaded_file(attachment_data) #=> #<Shrine::UploadedFile>
+attacher.upload(file)               #=> #<Shrine::UploadedFile @storage=:store ...>
+attacher.upload(file, :cache)       #=> #<Shrine::UploadedFile @storage=:cache ...>
+attacher.upload(file, :other_store) #=> #<Shrine::UploadedFile @storage=:other_store ...>
 ```
 
-## URL
+This is useful if you want to attacher [context](#context) such as `:record`
+and `:name` to be automatically passed to the uploader.
 
-The `#url` method returns the URL to the attached file, and returns `nil` if
-no file is attached.
+You can also pass additional options for `Shrine#upload`:
 
 ```rb
-attacher.url # calls `attacher.get.url`
+attacher.upload(file, metadata: { "foo" => "bar" })       # adding metadata
+attacher.upload(file, upload_options: { acl: "private" }) # setting upload options
+attacher.upload(file, location: "path/to/file")           # setting upload location
 ```
 
-## State
+### Changes
+
+When a new file is attached, calling [`Attacher#finalize`](#finalization) will
+perform additional actions such as promotion and deleting any previous file.
+It will also trigger [validation].
 
-You can ask the attacher whether the currently attached file is cached or
-stored.
+You can check whether a new file has been attached with `Attacher#changed?`:
 
 ```rb
-attacher.cached?
-attacher.stored?
+attacher.changed? #=> true
 ```
 
-## Validations
+You can use `Attacher#change` to attach an `UploadedFile` object as is:
 
-Whenever a file is assigned via `#assign` or `#set`, the file validations are
-automatically run, and you can access the validation errors through `#errors`:
+```rb
+uploaded_file #=> #<Shrine::UploadedFile>
+attacher.change(uploaded_file)
+attacher.file #=> #<Shrine::UploadedFile> (same object)
+attacher.changed? #=> true
+
+```
+
+If you want to attach a file without triggering dirty tracking or validation,
+you can use `Attacher#set`:
 
 ```rb
-attacher.assign(large_file)
-attacher.errors #=> ["is larger than 10 MB"]
+uploaded_file #=> #<Shrine::UploadedFile>
+attacher.set(uploaded_file)
+attacher.file #=> #<Shrine::UploadedFile> (same object)
+attacher.changed? #=> false
 ```
 
-## Promoting
+## Finalizing
 
-After the attachment is assigned and you run validations, it should be promoted
-to permanent storage after the record is saved. You can use `#finalize` for
-that, since that will also automatically delete any previously attached files.
+After the file is attached (with `Attacher#assign`, `Attacher#attach_cached`,
+or `Attacher#attach`), and data has been validated, the attachment can be
+"finalized":
 
 ```rb
-# Replaces previous attachment and replaces new
 attacher.finalize
 ```
 
-This is normally automatically added to a callback by the ORM plugin when going
-through the model. Internally this calls `#promote`, which uploads a given
-`Shrine::UploadedFile` to permanent storage, and swaps it with the current
-attachment, unless a new file was attached in the meanwhile.
+The `Attacher#finalize` method performs [promoting](#promoting) and
+[replacing](#replacing). It also clears dirty tracking:
 
 ```rb
-# uploads cached file to permanent storage and replaces the current one
-attacher.promote(cached_file, action: :custom_name)
+attacher.changed? #=> true
+attacher.finalize
+attacher.changed? #=> false
 ```
 
-The `:action` parameter is optional; it can be used for triggering a certain
-processing block, or for additional context during instrumentation.
+### Promoting
+
+`Attacher#finalize` checks if the attached file has been uploaded to temporary
+storage, and in this case uploads it to permanent storage.
+
+```rb
+attacher.attach_cached(io)
+attacher.finalize # uploads attached file to permanent storage
+attacher.file #=> #<Shrine::UploadedFile @storage=:store ...>
+```
 
-As a matter of fact, all additional options passed to `#promote` will be
-forwarded to `Shrine#upload`. So unless you're generating versions, you can do
-things like override metadata, set upload location, or pass upload options:
+Internally it calls `Attacher#promote_cached`, which you can call directly if
+you want to pass any promote options:
 
 ```rb
-attacher.promote cached_file,
-  metadata:       { "filename" => "myfile.txt" },
-  location:       "custom/location",
-  upload_options: { acl: "public-read" }
+attacher.file #=> #<Shrine::UploadedFile @storage=:cache ...>
+attacher.promote_cached # uploads attached file to permanent storage if new and cached
+attacher.file #=> #<Shrine::UploadedFile @storage=:store ...>
 ```
 
-Internally `#promote` calls `#swap`, which will update the record with any
-uploaded file, but will reload the record to check if the current attachment
-hasn't changed (if the `backgrounding` plugin is loaded).
+You can also call `Attacher#promote` if you want to upload attached file to
+permanent storage, regardless of whether it's cached or newly attached:
 
 ```rb
-attacher.swap(uploaded_file)
+attacher.promote
 ```
 
-Both `#promote` and `#swap` are useful for [file migrations].
+Any options passed to `Attacher#promote_cached` or `Attacher#promote` will be
+forwarded to `Shrine#upload`.
 
-## Backgrounding
+### Replacing
 
-When the `backgrounding` plugin is loaded, it allows you to promote and delete
-files in the background, and the corresponding methods are prefixed with `_`:
+`Attacher#finalize` also deletes the previous attached file if any:
 
 ```rb
-Shrine.plugin :backgrounding
-Shrine::Attacher.promote { |data| PromoteJob.perform_async(data) }
-Shrine::Attacher.delete { |data| DeleteJob.perform_async(data) }
+previous_file = attacher.file
+
+attacher.attach(io)
+attacher.finalize
+
+previous_file.exists? #=> false
 ```
+
+Internally it calls `Attacher#destroy_previous` to do this:
+
 ```rb
-attacher._promote(cached_file)  # calls the registered `Attacher.promote` block
-attacher._delete(uploaded_file) # calls the registered `Attacher.delete` block
+attacher.destroy_previous
 ```
 
-These are automatically used when using Shrine through models.
+## Retrieving
 
-## Context
+### File
+
+The `Attacher#file` is used to retrieve the attached file:
+
+```rb
+attacher.file #=> #<Shrine::UploadedFile>
+```
 
-The attacher sends `#context` to each upload/delete call to the uploader. By
-default it will hold `:record` and `:name`:
+If no file is attached, `Attacher#file` returns nil:
 
 ```rb
-attacher.context #=>
+attacher.file #=> nil
+```
+
+If you want to assert a file is attached, you can use `Attacher#file!`:
+
+```rb
+attacher.file! #~> Shrine::Error: no file is attached
+```
+
+### Attached
+
+You can also check whether a file is attached with `Attacher#attached?`:
+
+```rb
+attacher.attached? # returns whether file is attached
+```
+
+If you want to check to which storage a file is uploaded to, you can use
+`Attacher#cached?` and `Attacher#stored?`:
+
+```rb
+attacher.attach(io)
+attacher.stored?                #=> true (checks current file)
+attacher.stored?(attacher.file) #=> true (checks given file)
+```
+```rb
+attacher.attach_cached(io)
+attacher.cached?                #=> true (checks current file)
+attacher.cached?(attacher.file) #=> true (checks given file)
+```
+
+### URL
+
+The attached file URL can be retrieved with `Attacher#url`:
+
+```rb
+attacher.url #=> "https://example.com/file.jpg"
+```
+
+If no file is attached, `Attacher#url` returns `nil`:
+
+```rb
+attacher.url #=> nil
+```
+
+### Data
+
+You can retrieve plain attached file data with `Attacher#data`:
+
+```rb
+attacher.data #=>
 # {
-#   record: #<Photo...>,
-#   name:   :image,
+#   "id" => "abc123.jpg",
+#   "storage" => "store",
+#   "metadata" => {
+#     "size" => 223984,
+#     "filename" => "nature.jpg",
+#     "mime_type" => "image/jpeg",
+#   }
 # }
 ```
 
-However, you can change/add additional context to be sent when calling the
-uploaders:
+This data can be stored somewhere, and later the attached file can be loaded
+from it:
 
 ```rb
-attacher.context[:foo] = "bar"
+# new attacher
+attacher = Shrine::Attacher.from_data(data)
+attacher.file #=> #<Shrine::UploadedFile>
+
+# existing attacher
+attacher.file #=> nil
+attacher.load_data(data)
+attacher.file #=> #<Shrine::UploadedFile>
+```
+
+Internally `Attacher#uploaded_file` is used to convert uploaded file data into
+a `Shrine::UploadedFile` object:
+
+```rb
+attacher.uploaded_file("id" => "...", "storage" => "...", "metadata" => { ... }) #=> #<Shrine::UploadedFile>
+attacher.uploaded_file(id: "...", storage: "...", metadata: { ... })             #=> #<Shrine::UploadedFile>
+attacher.uploaded_file('{"id":"...","storage":"...","metadata":{...}}')          #=> #<Shrine::UploadedFile>
 ```
 
-This is useful for example if you have immutable model instances, and you want
-to assign a new updated instance. For example both foreground and background
-`#promote` requires that the record is persisted (and its `#id` is present).
+You will likely want to use a higher level abstraction for saving and loading
+this data, see [`column`][column], [`entity`][entity] and [`model`][model]
+plugins for more details.
 
-## Uploading and deleting
+## Deleting
 
-Normally you can upload and delete directly by using the uploader.
+The attached file can be deleted via `Attacher#destroy_attached`:
 
 ```rb
-uploader = ImageUploader.new(:store)
-uploaded_file = uploader.upload(image) # uploads the file to `:store` storage
-uploader.delete(uploaded_file)         # deletes the uploaded file from `:store`
+attacher.destroy_attached
 ```
 
-But the attacher also has wrapper methods for uploading and deleting, which
-also automatically pass in the attacher `#context` (which includes `:record`
-and `:name`):
+This will not delete cached files, to not interrupt any potential
+[backgrounding] that might be in process.
+
+If you want to delete the attached file regardless of storage it's uploaded to,
+you can use `Attacher#destroy`:
 
 ```rb
-attacher.cache!(file) # uploads file to temporary storage
-# => #<Shrine::UploadedFile: @data={"storage" => "cache", ...}>
-attacher.store!(file) # uploads file to permanent storage
-# => #<Shrine::UploadedFile: @data={"storage" => "store", ...}>
-attacher.delete!(uploaded_file) # deletes uploaded file from storage
+attacher.destroy
 ```
 
-These methods only upload/delete files, they don't write to record's data
-column. You can also pass additional options for `Shrine#upload` and
-`Shrine#delete`:
+## Context
+
+The `Attacher#context` hash is automatically forwarded to the uploader on
+`Attacher#upload`. When [`model`][model] or [`entity`][model] plugin is loaded,
+this will include `:record` and `:name` values:
 
 ```rb
-attacher.cache!(file, upload_options: { acl: "public-read" })
-attacher.store!(file, location: "custom/location")
-attacher.delete!(uploaded_file, foo: "bar")
+attacher = Shrine::Attacher.from_model(photo, :image)
+attacher.context #=> { record: #<Photo>, name: :image }
 ```
 
-[file migrations]: /doc/migrating_storage.md#readme
+You can add here any other parameters you want to forward to the uploader:
+
+```rb
+attacher.context[:foo] = "bar"
+```
+
+However, it's generally better practice to pass uploader options directly to
+`Attacher#assign`, `Attacher#attach`, `Attacher#promote` or any other method
+that's calling `Attacher#upload`.
+
+[validation]: /doc/plugins/validation.md#readme
+[column]: /doc/plugins/column.md#readme
+[entity]: /doc/plugins/entity.md#readme
+[model]: /doc/plugins/model.md#readme
+[backgrounding]: /doc/plugins/backgrounding.md#readme