shrine 3.1.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30bd30989579217202b2c51b9a00abe778af7cbab75fc9df78052bc074ce9405
-  data.tar.gz: 5c718df903c203e06ea44afa9c9017fa2cf01a8924c99e86a87be52f52ce0233
+  metadata.gz: 9c012576836f3a56efa91be436999395123342c4650f76f152ef64808ce82ddb
+  data.tar.gz: 5be0e63b923ba28f838b4f692758af3eb975c937c4b63453acc629aab0240eac
 SHA512:
-  metadata.gz: 27f896211caba27686d5988750ce214ec0b31e70e9bbcf8a7d325952a5eee2e4c3293d539bb3074d4384964723bda09edd1acfcdcd387d82a4ef7373ff5787f0
-  data.tar.gz: 3d06d57d2eb1fee1cada71dfa4092a23c4b0bf4d5df8cf76e2fbf2eb4eaf5c9477f333ef241772d917456ebfb3067ad0ce7adc6becc49e15c9129720842cd5b3
+  metadata.gz: da5eb6be96c3cacb0575e124b4238c038709d44f33085a5bfb4ae6cb1702d079ba0c7f1ca775828812c6d8cacd1b75aa5979c564dbe0e1ea52fea0036c0f577e
+  data.tar.gz: fe12c86f5d826581e4ecb1b5e1951ca1330c8d6d288d19001badd79dab646013a2e57faf51d6cf7369669515636dda3058bf42a2128ea04934f7b611a53e97dd

data/CHANGELOG.md

@@ -1,3 +1,85 @@
+## 3.4.0 (2021-06-14)
+
+* `base` – Fix passing options to `Shrine.Attachment` on Ruby 3.0 (@lucianghinda)
+
+* `determine_mime_type` – Return correct `image/svg+xml` MIME type for SVGs with `:fastimage` analyzer (@Bandes)
+
+* `activerecord` – Fix keyword argument warning when adding errors with options (@janko)
+
+* `entity` – Make `Attacher#read` method public (@janko)
+
+* `entity` – Reset attachment dirty tracking in `Attacher#reload` (@janko)
+
+* `activerecord` – Don't load the attacher on `ActiveRecord::Base#reload` if it hasn't yet been initialized (@janko)
+
+* `sequel` – Don't load the attacher on `Sequel::Model#reload` if it hasn't yet been initialized (@janko)
+
+## 3.3.0 (2020-10-04)
+
+* `s3` - Support new `Aws::S3::EncryptionV2::Client` for client-side encryption (@janko)
+
+* `derivation_endpoint` – Reduce possibility of timing attacks when comparing signatures (@esparta)
+
+* `derivatives` – Avoid downloading the attached file when calling default no-op processor (@janko)
+
+* `derivatives` – Add `:download` processor setting for skipping downloading source file (@jrochkind, @janko)
+
+* `derivatives` – Copy non-file source IO objects into local file before passing them to the processor (@jrochkind)
+
+* `sequel` – Call `Attacher#reload` in `Sequel::Model#reload`, which keeps rest of attacher state (@janko, @jrochkind)
+
+* `activerecord` – Call `Attacher#reload` in `ActiveRecord::Base#reload`, which keeps rest of attacher state (@janko, @jrochkind)
+
+* `add_metadata` – Add `:skip_nil` option for excluding metadata keys whose values are nil (@renchap)
+
+* `store_dimensions` – Add `:auto_extraction` option for disabling automatically extracting dimensions on upload (@renchap)
+
+* `mirroring` – Forward original upload options when mirroring upload (@corneverbruggen)
+
+* `derivation_endpoint` – Apply `version` URL option in derivation endpoint (@janko)
+
+* `remove_attachment` – Delete removed file if a new file was attached right after removal (@janko)
+
+* `upload_endpoint` – Fix `Shrine.upload_response` not working in a Rails controller (@pldavid2)
+
+* `presign_endpoint` – Add `OPTIONS` route that newer versions of Uppy check (@janko)
+
+* `derivatives` – Add `:create_on_promote` option for auto-creating derivatives on promotion (@janko)
+
+* `s3` – Add back support for client-side encryption (@janko)
+
+* `memory` – Ensure `Memory#open` returns content in original encoding (@jrochkind)
+
+## 3.2.2 (2020-08-05)
+
+* `s3` – Fix `S3#open` not working on aws-sdk-core 3.104 and above (@janko)
+
+## 3.2.1 (2020-01-12)
+
+* `derivation_endpoint` – Use `Rack::Files` constant on Rack >= 2.1 (@janko)
+
+* Fix Ruby 2.7 warnings regarding separation of positional and keyword arguments (@janko)
+
+* `s3` – Make `S3#open` handle empty S3 objects (@janko)
+
+## 3.2.0 (2019-12-17) [[release notes]](https://shrinerb.com/docs/release_notes/3.2.0)
+
+* `validation` – Run validation on `Attacher#attach` & `Attacher#attach_cached` instead of `Attacher#change` (@janko)
+
+* `remove_invalid` – Activate also when `Attacher#validate` is run manually (@janko)
+
+* `remove_invalid` – Fix incompatibility with `derivatives` plugin (@janko)
+
+* `type_predicates` – Add new plugin with convenient `UploadedFile` predicate methods based on MIME type (@janko)
+
+* `core` – Allow assigning back current attached file data (@janko)
+
+* `derivatives` – Fix `:derivative` value inconsistency when derivatives are being promoted (@janko)
+
+* `add_metadata` – Add `#add_metadata` method for adding metadata to uploaded files (@janko)
+
+* `derivatives` – Add `:io` and `:attacher` values to instrumentation event payload (@janko)
+
 ## 3.1.0 (2019-11-15) [[release notes]](https://shrinerb.com/docs/release_notes/3.1.0)
 
 * `default_storage` – Coerce storage key to symbol in `Attacher#cache_key` & `Attacher#store_key` (@janko)

data/README.md

@@ -8,7 +8,7 @@ Shrine is a toolkit for handling file attachments in Ruby applications. Some hig
 * **Memory friendly** – streaming uploads and [downloads][Retrieving Uploads] make it work great with large files
 * **Cloud storage** – store files on [disk][FileSystem], [AWS S3][S3], [Google Cloud][GCS], [Cloudinary] and others
 * **Persistence integrations** – works with [Sequel], [ActiveRecord], [ROM], [Hanami] and [Mongoid] and others
-* **Flexible processing** – generate thumbnails [up front] or [on-the-fly] using [ImageMagick] or [libvips]
+* **Flexible processing** – generate thumbnails [eagerly] or [on-the-fly] using [ImageMagick] or [libvips]
 * **Metadata validation** – [validate files][validation] based on [extracted metadata][metadata]
 * **Direct uploads** – upload asynchronously [to your app][simple upload] or [to the cloud][presigned upload] using [Uppy]
 * **Resumable uploads** – make large file uploads [resumable][resumable upload] on [S3][uppy-s3_multipart] or [tus][tus-ruby-server]
@@ -57,8 +57,9 @@ Next, add the `<name>_data` column to the table you want to attach files to. For
 an "image" attachment on a `photos` table this would be an `image_data` column:
 
 ```
-$ rails generate migration add_image_data_to_photos image_data:text
+$ rails generate migration add_image_data_to_photos image_data:text # or :jsonb
 ```
+If using `jsonb` consider adding a [gin index] for fast key-value pair searchability within `image_data`.
 
 Now create an uploader class (which you can put in `app/uploaders`) and
 register the attachment on your model:
@@ -127,6 +128,10 @@ system.
 * Refile
 * Active Storage
 
+## Contributing
+
+Please refer to the [contributing page][Contributing].
+
 ## Code of Conduct
 
 Everyone interacting in the Shrine project’s codebases, issue trackers, and
@@ -149,8 +154,8 @@ The gem is available as open source under the terms of the [MIT License].
 [ROM]: https://github.com/shrinerb/shrine-rom
 [Hanami]: https://github.com/katafrakt/hanami-shrine
 [Mongoid]: https://github.com/shrinerb/shrine-mongoid
-[up front]: https://shrinerb.com/docs/getting-started#processing-up-front
-[on-the-fly]: https://shrinerb.com/docs/getting-started#processing-on-the-fly
+[eagerly]: https://shrinerb.com/docs/getting-started#eager-processing
+[on-the-fly]: https://shrinerb.com/docs/getting-started#on-the-fly-processing
 [ImageMagick]: https://github.com/janko/image_processing/blob/master/doc/minimagick.md#readme
 [libvips]: https://github.com/janko/image_processing/blob/master/doc/vips.md#readme
 [validation]: https://shrinerb.com/docs/validation
@@ -170,3 +175,5 @@ The gem is available as open source under the terms of the [MIT License].
 [Roda]: https://github.com/jeremyevans/roda
 [CoC]: /CODE_OF_CONDUCT.md
 [MIT License]: /LICENSE.txt
+[Contributing]: https://github.com/shrinerb/shrine/blob/master/CONTRIBUTING.md
+[gin index]: https://www.postgresql.org/docs/current/datatype-json.html#JSON-INDEXING

data/doc/advantages.md

@@ -93,7 +93,7 @@ low-level abstractions that give you the flexibility to build your own flow.
 ```rb
 uploaded_file = ImageUploader.upload(image, :store) # metadata extraction, upload location generation
 uploaded_file.id       #=> "44ccafc10ce6a4ff22829e8f579ee6b9.jpg"
-uplaoded_file.metadata #=> { ... extracted metadata ... }
+uploaded_file.metadata #=> { ... extracted metadata ... }
 
 data = uploaded_file.to_json # serialization
 # ...
@@ -157,14 +157,14 @@ end
 
 ## Processing
 
-Most file attachment libraries provide either processing files up front
-(Paperclip, CarrierWave) or on-the-fly (Dragonfly, Refile, Active Storage).
+Most file attachment libraries allow you to process files either "eagerly"
+(Paperclip, CarrierWave) or "on-the-fly" (Dragonfly, Refile, Active Storage).
 However, each approach is suitable for different requirements. For instance,
 while on-the-fly processing is suitable for fast processing (image thumbnails,
 document previews), longer running processing (video transcoding, raw images)
 should be moved into a background job.
 
-That's why Shrine supports both [up front][derivatives] and
+That's why Shrine supports both [eager][derivatives] and
 [on-the-fly][derivation_endpoint] processing. For example, if you're handling
 image uploads, you can choose to either generate a set of pre-defined
 thumbnails during attachment:

data/doc/attacher.md

@@ -130,8 +130,8 @@ 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.attach_cached({ "id" => "asdf.jpg", "storage" => "cache", "metadata" => { ... } })
+attacher.attach_cached({ id: "asdf.jpg", storage: "cache", metadata: { ... } })
 
 # unsets attached file
 attacher.attach_cached(nil)

data/doc/carrierwave.md

@@ -1,5 +1,5 @@
 ---
-title: Shrine for CarrierWave Users
+title: Upgrading from CarrierWave
 ---
 
 This guide is aimed at helping CarrierWave users transition to Shrine, and it
@@ -322,19 +322,22 @@ module CarrierwaveShrineSynchronization
 
   private
 
-  # If you'll be using `:prefix` on your Shrine storage, make sure to
-  # subtract it from the path assigned as `:id`.
   def shrine_file(uploader)
     name     = uploader.mounted_as
     filename = read_attribute(name)
-    path     = uploader.store_path(filename)
+    location = uploader.store_path(filename)
+    location = location.sub(%r{^#{storage.prefix}/}, "") if storage.prefix
 
     Shrine.uploaded_file(
       storage:  :store,
-      id:       path,
+      id:       location,
       metadata: { "filename" => filename },
     )
   end
+
+  def storage
+    Shrine.storages[:store]
+  end
 end
 ```
 ```rb
@@ -476,16 +479,25 @@ photo.image.original_filename #=> "avatar.jpg"
 
 #### `#store_dir`, `#cache_dir`
 
-Shrine here provides a `#generate_location` method, which is triggered for all
-storages:
+Shrine here provides a single `#generate_location` method that's triggered for
+all storages:
 
 ```rb
 class ImageUploader < Shrine
-  def generate_location(io, record: nil, **)
-    "#{record.class}/#{record.id}/#{io.original_filename}"
+  def generate_location(io, record: nil, name: nil, **)
+    [ storage_key,
+      record && record.class.name.underscore,
+      record && record.id,
+      super,
+      io.original_filename ].compact.join("/")
   end
 end
 ```
+```
+cache/user/123/2feff8c724e7ce17/nature.jpg
+store/user/456/7f99669fde1e01fc/kitten.jpg
+...
+```
 
 You might also want to use the `pretty_location` plugin for automatically
 generating an organized folder structure.
@@ -498,8 +510,8 @@ For default URLs you can use the `default_url` plugin:
 class ImageUploader < Shrine
   plugin :default_url
 
-  Attacher.default_url do |options|
-    "/attachments/#{name}/default.jpg"
+  Attacher.default_url do |derivative: nil, **|
+    "/fallbacks/#{derivative || "original"}.jpg"
   end
 end
 ```
@@ -654,7 +666,7 @@ shows what are Shrine's equivalents.
 
 #### `root`, `base_path`, `permissions`, `directory_permissions`
 
-In Shrine these are configured on the FileSystem storage directly.
+In Shrine these are configured on the `FileSystem` storage directly.
 
 #### `storage`, `storage_engines`
 

data/doc/changing_derivatives.md

@@ -212,7 +212,7 @@ Photo.find_each do |photo|
   next unless attacher.stored?
 
   square = attacher.file.download do |original|
-    ImageProcessor::MiniMagick
+    ImageProcessing::MiniMagick
       .source(original)
       .resize_to_fill!(150, 150)
   end

data/doc/changing_location.md

@@ -53,16 +53,17 @@ Photo.find_each do |photo|
   next unless attacher.stored? # move only attachments uploaded to permanent storage
 
   old_attacher = attacher.dup
+  current_file = old_attacher.file
 
   attacher.set             attacher.upload(attacher.file)                    # reupload file
   attacher.set_derivatives attacher.upload_derivatives(attacher.derivatives) # reupload derivatives if you have derivatives
 
   begin
-    attacher.atomic_persist           # persist changes if attachment has not changed in the meantime
-    old_attacher.destroy_attached     # delete files on old location
-  rescue Shrine::AttachmentChanged,   # attachment has changed during reuploading
-         ActiveRecord::RecordNotFound # record has been deleted during reuploading
-    attacher.destroy_attached         # delete now orphaned files
+    attacher.atomic_persist(current_file) # persist changes if attachment has not changed in the meantime
+    old_attacher.destroy_attached         # delete files on old location
+  rescue Shrine::AttachmentChanged,       # attachment has changed during reuploading
+         ActiveRecord::RecordNotFound     # record has been deleted during reuploading
+    attacher.destroy_attached             # delete now orphaned files
   end
 end
 ```

data/doc/design.md

@@ -2,22 +2,25 @@
 title: The Design of Shrine
 ---
 
-*If you want an in-depth walkthrough through the Shrine codebase, see [Notes on study of shrine implementation] article by Jonathan Rochkind.*
+*If you want an in-depth walkthrough through the Shrine codebase, see [Notes on
+study of shrine implementation] article by Jonathan Rochkind.*
 
-There are five main types of objects that you deal with in Shrine:
+There are five main types of classes that you deal with in Shrine:
 
-* Storage
-* `Shrine`
-* `Shrine::UploadedFile`
-* `Shrine::Attacher`
-* `Shrine::Attachment`
+| Class | Description |
+| :---- | :---------- |
+| [`Shrine::Storage::*`](#Storage) | Manages files on a particular storage service |
+| [`Shrine`](#Shrine) | Wraps uploads and handles loading plugins |
+| [`Shrine::UploadedFile`](#shrineuploadedfile) | Represents a file uploaded to a storage |
+| [`Shrine::Attacher`](#shrineattacher) | Handles file attachment logic |
+| [`Shrine::Attachment`](#shrineattachment) | Provides convenience model attachment interface |
 
 ## Storage
 
 On the lowest level we have a storage. A storage class encapsulates file
 management logic on a particular service. It is what actually performs uploads,
 generation of URLs, deletions and similar. By convention it is namespaced under
-`Shrine::Storage`.
+`Shrine::Storage::*`.
 
 ```rb
 filesystem = Shrine::Storage::FileSystem.new("uploads")
@@ -26,7 +29,7 @@ filesystem.url("foo") #=> "uploads/foo"
 filesystem.delete("foo")
 ```
 
-A storage is a PORO which responds to certain methods:
+A storage is a PORO which implements the following interface:
 
 ```rb
 class Shrine
@@ -56,13 +59,14 @@ class Shrine
 end
 ```
 
-Storages are typically not used directly, but through `Shrine`.
+Storages are typically not used directly, but through [`Shrine`](#shrine) and
+[`Shrine::UploadedFile`](#shrine-uploadedfile) classes.
 
 ## `Shrine`
 
-A `Shrine` object (also called an "uploader") is essentially a wrapper around
-the `#upload` storage method. First the storage needs to be registered under a
-name:
+The `Shrine` class (also called an "uploader") primarily provides a wrapper
+method around `Storage#upload`. First, the storage needs to be registered under
+a name:
 
 ```rb
 Shrine.storages[:disk] = Shrine::Storage::FileSystem.new("uploads")
@@ -72,7 +76,7 @@ Now we can upload files to the registered storage:
 
 ```rb
 uploaded_file = Shrine.upload(file, :disk)
-uploaded_file #=> #<Shrine::UploadedFile>
+uploaded_file #=> #<Shrine::UploadedFile storage=:disk id="6a9fb596cc554efb" ...>
 ```
 
 The argument to `Shrine#upload` must be an IO-like object. The method does the
@@ -84,63 +88,97 @@ following:
 * closes the file
 * creates a `Shrine::UploadedFile` from the data
 
-`Shrine` class and subclasses are also used for loading plugins that extend all
-core classes. Each `Shrine` subclass has its own subclass of each of the core
-classes (`Shrine::UploadedFile`, `Shrine::Attacher`, and `Shrine::Attachment`),
-which makes it possible to have different `Shrine` subclasses with differently
-customized attachment logic. See [Creating a New Plugin] guide and the [Plugin
-system of Sequel and Roda] article for more details on the design of Shrine's
-plugin system.
+### Plugins
+
+The `Shrine` class is also used for loading plugins, which provide additional
+functionality by extending core classes.
+
+```rb
+Shrine.plugin :derivatives
+
+Shrine::UploadedFile.ancestors #=> [..., Shrine::Plugins::Derivatives::FileMethods, Shrine::UploadedFile::InstanceMethods, ...]
+Shrine::Attacher.ancestors     #=> [..., Shrine::Plugins::Derivatives::AttacherMethods, Shrine::Attacher::InstanceMethods,  ...]
+Shrine::Attachment.ancestors   #=> [..., Shrine::Plugins::Derivatives::AttachmentMethods, Shrine::Attachment::InstanceMethods, ...]
+```
+
+The plugins store their configuration in `Shrine.opts`:
+
+```rb
+Shrine.plugin :derivation_endpoint, secret_key: "foo"
+Shrine.plugin :default_storage, store: :other_store
+Shrine.plugin :activerecord
+
+Shrine.opts #=>
+# { derivation_endpoint: { options: { secret_key: "foo" }, derivations: {} },
+#   default_storage: { store: :other_store },
+#   column: { serializer: Shrine::Plugins::Column::JsonSerializer },
+#   model: { cache: true },
+#   activerecord: { callbacks: true, validations: true } }
+```
+
+Each `Shrine` subclass has its own copy of the core classes, storages and
+options, which makes it possible to customize attachment logic per uploader.
+
+```rb
+MyUploader = Class.new(Shrine)
+MyUploader::UploadedFile.superclass #=> Shrine::UploadedFile
+MyUploader::Attacher.superclass     #=> Shrine::Attacher
+MyUploader::Attachment.superclass   #=> Shrine::Attachment
+```
+
+See [Creating a New Plugin] guide and the [Plugin system of Sequel and Roda]
+article for more details on the design of Shrine's plugin system.
 
 ## `Shrine::UploadedFile`
 
-`Shrine::UploadedFile` represents a file that was uploaded to a storage, and is
-the result of `Shrine#upload`. It is essentially a wrapper around a data hash
-containing information about the uploaded file.
+A `Shrine::UploadedFile` object represents a file that was uploaded to a
+storage, containing upload location, storage, and any metadata extracted during
+the upload.
 
 ```rb
-uploaded_file      #=> #<Shrine::UploadedFile>
-uploaded_file.data #=>
+uploaded_file #=> #<Shrine::UploadedFile id="949sdjg834.jpg" storage=:store metadata={...}>
+
+uploaded_file.id          #=> "949sdjg834.jpg"
+uploaded_file.storage_key #=> :store
+uploaded_file.storage     #=> #<Shrine::Storage::S3>
+uploaded_file.metadata    #=> {...}
+```
+
+It has convenience methods for accessing metadata:
+
+```rb
+uploaded_file.metadata #=>
 # {
-#   "storage"  => "file_system",
-#   "id"       => "9260ea09d8effd.pdf",
-#   "metadata" => {
-#     "filename"  => "resume.pdf",
-#     "mime_type" => "application/pdf",
-#     "size"      => 983294,
-#   },
+#   "filename" => "matrix.mp4",
+#   "mime_type" => "video/mp4",
+#   "size" => 345993,
 # }
+
+uploaded_file.original_filename #=> "matrix.mp4"
+uploaded_file.extension         #=> "mp4"
+uploaded_file.mime_type         #=> "video/mp4"
+uploaded_file.size              #=> 345993
 ```
 
-The data hash contains the storage the file was uploaded to, the location, and
-some metadata: original filename, MIME type and filesize. The
-`Shrine::UploadedFile` object has handy methods which use this data:
+It also has methods that delegate to the storage:
 
 ```rb
-# metadata methods
-uploaded_file.original_filename
-uploaded_file.mime_type
-uploaded_file.size
-# ...
-
-# storage methods
-uploaded_file.url
-uploaded_file.exists?
-uploaded_file.open
-uploaded_file.download
-uploaded_file.delete
-# ...
+uploaded_file.url                     #=> "https://my-bucket.s3.amazonaws.com/949sdjg834.jpg"
+uploaded_file.open { |io| ... }       # opens the uploaded file stream
+uploaded_file.download { |file| ... } # downloads the uploaded file to disk
+uploaded_file.stream(destination)     # streams uploaded content into a writable destination
+uploaded_file.exists?                 #=> true
+uploaded_file.delete                  # deletes the uploaded file from the storage
 ```
 
-A `Shrine::UploadedFile` is itself an IO-like object (representing the
-remote file), so it can be passed to `Shrine#upload` as well.
+A `Shrine::UploadedFile` is itself an IO-like object (built on top of
+`Storage#open`), so it can be passed to `Shrine#upload` as well.
 
 ## `Shrine::Attacher`
 
 We usually want to treat uploaded files as *attachments* to records, saving
-their data into a database column. This is the responsibility of
-`Shrine::Attacher`. A `Shrine::Attacher` uses `Shrine` uploaders and
-`Shrine::UploadedFile` objects internally.
+their data into a database column. This is done by `Shrine::Attacher`, which
+internally uses `Shrine` and `Shrine::UploadedFile` classes.
 
 The attaching process requires a temporary and a permanent storage to be
 registered (by default that's `:cache` and `:store`):
@@ -152,40 +190,50 @@ Shrine.storages = {
 }
 ```
 
-A `Shrine::Attacher` is instantiated with a model instance and an attachment
-name (an "image" attachment will be saved to `image_data` field):
+A `Shrine::Attacher` can be initialized standalone and handle the common
+attachment flow, which includes dirty tracking (promoting cached file to
+permanent storage, deleting previously attached file), validation, processing,
+serialization etc.
+
+```rb
+attacher = Shrine::Attacher.new
+
+# ... user uploads a file ...
+
+attacher.assign(io) # uploads to temporary storage
+attacher.file       #=> #<Shrine::UploadedFile storage=:cache ...>
+
+# ... handle file validations ...
+
+attacher.finalize   # uploads to permanent storage
+attacher.file       #=> #<Shrine::UploadedFile storage=:store ...>
+```
+
+It can also be initialized with a model instance to handle serialization into a
+model attribute:
 
 ```rb
 attacher = Shrine::Attacher.from_model(photo, :image)
 
 attacher.assign(file)
-attacher.file #=> #<Shrine::UploadedFile storage=:cache ...>
-attacher.record.image_data #=> "{\"storage\":\"cache\",\"id\":\"9260ea09d8effd.jpg\",\"metadata\":{...}}"
+photo.image_data #=> "{\"storage\":\"cache\",\"id\":\"9260ea09d8effd.jpg\",\"metadata\":{...}}"
 
 attacher.finalize
-attacher.file #=> #<Shrine::UploadedFile storage=:store ...>
-attacher.record.image_data #=> "{\"storage\":\"store\",\"id\":\"ksdf02lr9sf3la.jpg\",\"metadata\":{...}}"
+photo.image_data #=> "{\"storage\":\"store\",\"id\":\"ksdf02lr9sf3la.jpg\",\"metadata\":{...}}"
 ```
 
-Above a file is assigned by the attacher, which "caches" (uploads) the file to
-the temporary storage. The cached file is then "promoted" (uploaded) to
-permanent storage. Behind the scenes a cached `Shrine::UploadedFile` is given
-to `Shrine#upload`, which works because `Shrine::UploadedFile` is an IO-like
-object. After both caching and promoting the data hash of the uploaded file is
-assigned to the record's column as JSON.
-
-For more details see [Using Attacher].
+For more details, see the [Using Attacher] guide and
+[`entity`][entity]/[`model`][model] plugins.
 
 ## `Shrine::Attachment`
 
-`Shrine::Attachment` is the highest level of abstraction. A
-`Shrine::Attachment` module exposes the `Shrine::Attacher` object through the
-model instance. The `Shrine::Attachment` class is a sublcass of `Module`, which
-means that an instance of `Shrine::Attachment` is a module:
+A `Shrine::Attachment` module provides a convenience model interface around the
+`Shrine::Attacher` object. The `Shrine::Attachment` class is a subclass of
+`Module`, which means that an instance of `Shrine::Attachment` is a module:
 
 ```rb
 Shrine::Attachment.new(:image).is_a?(Module) #=> true
-Shrine::Attachment.new(:image).instance_methods #=> [:image=, :image, :image_url, :image_attacher]
+Shrine::Attachment.new(:image).instance_methods #=> [:image=, :image, :image_url, :image_attacher, ...]
 
 # equivalents
 Shrine::Attachment.new(:image)
@@ -193,30 +241,31 @@ Shrine::Attachment[:image]
 Shrine::Attachment(:image)
 ```
 
-We can include this module to a model:
+We can include this module into a model:
 
 ```rb
-class Photo
-  include Shrine::Attachment(:image)
-end
+Photo.include Shrine::Attachment(:image)
 ```
 ```rb
-photo.image = file # shorthand for `photo.image_attacher.assign(file)`
-photo.image        # shorthand for `photo.image_attacher.get`
-photo.image_url    # shorthand for `photo.image_attacher.url`
+photo.image = file   # shorthand for `photo.image_attacher.assign(file)`
+photo.image          # shorthand for `photo.image_attacher.get`
+photo.image_url      # shorthand for `photo.image_attacher.url`
 
-photo.image_attacher #=> #<Shrine::Attacher>
+photo.image_attacher #=> #<Shrine::Attacher @cache_key=:cache @store_key=:store ...>
 ```
 
-When a persistence plugin is loaded, the `Shrine::Attachment` module also
-automatically:
+When a persistence plugin is loaded ([`activerecord`][activerecord],
+[`sequel`][sequel]), the `Shrine::Attachment` module also automatically:
 
 * syncs Shrine's validation errors with the record
 * triggers promoting after record is saved
-* deletes the uploaded file if attachment was replaced/removed or the record
-  destroyed
+* deletes the uploaded file if attachment was replaced or the record destroyed
 
 [Using Attacher]: https://shrinerb.com/docs/attacher
 [Notes on study of shrine implementation]: https://bibwild.wordpress.com/2018/09/12/notes-on-study-of-shrine-implementation/
 [Creating a New Plugin]: https://shrinerb.com/docs/creating-plugins
 [Plugin system of Sequel and Roda]: https://twin.github.io/the-plugin-system-of-sequel-and-roda/
+[entity]: https://shrinerb.com/docs/plugins/entity
+[model]: https://shrinerb.com/docs/plugins/model
+[activerecord]: https://shrinerb.com/docs/plugins/activerecord
+[sequel]: https://shrinerb.com/docs/plugins/sequel