shrine 2.10.1 → 2.11.0

data/doc/advantages.md

@@ -0,0 +1,346 @@
+# Advantages of Shrine
+
+There are many popular file upload solutions for Ruby out there – [Paperclip],
+[CarrierWave], [Dragonfly], [Refile], and [Active Storage], to name the most
+popular ones. This guide will attempt to cover some of the main advantages that
+Shrine offers compared to these alternatives.
+
+## Generality
+
+Many alternative file upload solutions are coupled to either Rails (Active
+Storage) or Active Record itself (Paperclip, CarrierWave, Dragonfly). This is
+not ideal, as Rails-specific solutions fragment the Ruby community between
+developers that use Rails and developers that don't. There are many great web
+frameworks ([Sinatra], [Roda], [Cuba], [Hanami], [Grape] etc.) and database
+libraries ([Sequel], [ROM], [Hanami::Model] etc.) out there that people use
+instead of Rails and Active Record.
+
+Shrine, on the other hand, doesn't make any assumptions about which web
+framework or ORM you're using. Any HTTP-specific functionality is implemented
+on top of [Rack], the Ruby web server interface that powers all the popular
+Ruby web frameworks (including Rails). The integrations for specific ORMs are
+provided as plugins.
+
+```rb
+# Rack-based plugins
+Shrine.plugin :upload_endpoint
+Shrine.plugin :presign_endpoint
+Shrine.plugin :download_endpoint
+Shrine.plugin :rack_response
+Shrine.plugin :rack_file
+
+# ORM plugins
+Shrine.plugin :activerecord
+Shrine.plugin :sequel
+Shrine.plugin :mongoid # https://github.com/shrinerb/shrine-mongoid
+Shrine.plugin :hanami # https://github.com/katafrakt/hanami-shrine
+```
+
+## Modularity
+
+Shrine uses a [plugin system] that allows you to pick and choose the features
+that you want, which makes it very flexible. Moreover, you're only loading the
+code for features that you use, which means that Shrine will generally load
+very fast.
+
+```rb
+Shrine.plugin :logging # loads the logging feature
+```
+
+### Dependencies
+
+Shrine is very diligent when it comes to dependencies. It has only one
+mandatory dependency - [Down], a gem for streaming downloads from a URL. Some
+Shrine plugins require more dependencies, but you only need to load them if
+you're using those plugins. Moreover, for the same task you can often choose
+between different dependencies.
+
+For example, if you want to determine MIME type from file content, upon loading
+the `determine_mime_type` plugin you can choose whether you want to use the
+[`file`] command, [FileMagic], [FastImage], [MimeMagic] or [Marcel] gem to do
+that. For determining MIME type from file extension you can choose between
+[mime-types] or [mini_mime] gems. Likewise, for `store_dimensions` plugin you
+can choose between [FastImage], [MiniMagick] or [ruby-vips] gems for extracting
+image dimensions.
+
+```rb
+Shrine.plugin :determine_mime_type, analyzer: :marcel
+Shrine.plugin :store_dimensions,    analyzer: :mini_magick
+```
+
+With this approach you have control over your dependencies and are free to
+choose the combination that best suit your needs.
+
+## 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 also no `CarrierWave::Uploader::Base` and `Paperclip::Attachment` [God
+objects]. The `Shrine` class is responsible for uploading files to the storage
+(which are simple Ruby classes), `Shrine::UploadedFile` exposes extracted
+metadata and can retrieve the file from the storage, and `Shrine::Attacher`
+wraps those two classes to provide an interface for attaching files to database
+records.
+
+```rb
+photo.image          #=> #<Shrine::UploadedFile>
+photo.image.storage  #=> #<Shrine::Storage::S3>
+photo.image.uploader #=> #<Shrine>
+photo.image_attacher #=> #<Shrine::Attacher>
+```
+
+Special care was taken to make integrating new ORMs and storages possible with
+minimal amount of code.
+
+## 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:
+
+* images can be processed on-the-fly, while videos should be transcoded on upload
+* you might want to store images on one service and videos on another
+* tools for extracting image metadata are different than ones for video metadata
+
+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
+other plugins would be loaded only for a specific uploader.
+
+```rb
+Shrine.plugin :activerecord
+Shrine.plugin :logging
+```
+```rb
+class ImageUploader < Shrine
+  plugin :store_dimensions
+end
+```
+```rb
+class VideoUploader < Shrine
+  plugin :default_storage, store: :vimeo
+end
+```
+
+## Processing
+
+Instead of writing yet another vendored solution for generating image
+thumbnails, the **[ImageProcessing]** gem was created to be used with Shrine,
+but it can also be used with any other file upload library. It's very flexible
+and 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"
+
+thumbnail = ImageProcessing::MiniMagick
+  .source(image)
+  .resize_to_limit(400, 400)
+  .call # convert input.jpg -auto-orient -resize 400x400> -sharpen 0x1 output.jpg
+
+thumbnail #=> #<Tempfile:/var/folders/.../image_processing20180316-18446-1j247h6.png>
+```
+
+### libvips
+
+Probably the biggest ImageProcessing feature is the support for **[libvips]**.
+Libvips is an image processing library which can process images multiple times
+faster than ImageMagick and has significantly lower memory usage (see [Why is
+libvips quick]). 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)
+```
+
+### Other processors
+
+Using other processors for other types of files doesn't require remembering any
+specific API, you just call them in the same processing block where you're
+calling ImageProcessing. Shrine's processing block acts as a functional
+transformation: you get the original file on the input, and you're expected to
+return processed file(s) on the output.
+
+```rb
+class VideoUploader < Shrine
+  plugin :processing
+
+  process(:store) do |io, context|
+    # define your processing
+  end
+end
+```
+
+### On-the-fly processing
+
+Shrine is primarily designed for processing files on upload, since that's
+applicable to all types of files, while on-the-fly processing that [Dragonfly],
+[Refile], and [Active Storage] offer makes sense only for images.
+
+However, there are many specialized solutions that provide on-the-fly
+processing functionality, both open source and commercial, and it's fairly easy
+to apply them to files uploaded by Shrine.
+
+```rb
+Dragonfly.app
+  .fetch_url(photo.image_url) # image uploaded by Shrine
+  .thumb("800x800")
+  .url #=> "/attachments/W1siZnUiLCJodHRwOi8vd3d3LnB1YmxpY2RvbWFpbn..."
+```
+
+## Metadata
+
+Shrine automatically [extracts metadata][metadata] from each uploaded file,
+including derivates like image thumbnails, and saves them into the database
+column. In addition to filename, filesize, and MIME type that are extracted by
+default, you can also extract [image dimensions][store_dimensions], or your own
+[custom metadata][add_metadata]. This metadata can additionally be
+[validated][validation].
+
+```rb
+photo.image.metadata #=>
+# {
+#   "size" => 42487494,
+#   "filename" => "nature.jpg",
+#   "mime_type" => "image/jpeg",
+#   "width" => 600,
+#   "height" => 400,
+#   ...
+# }
+```
+
+## Direct Uploads
+
+Instead of submitting selected files synchronously via the form, it's better to
+start uploading files asynchronously as soon as they're selected. Shrine
+streamlines this workflow, allowing you to upload directly [to your
+app][upload_endpoint] or [to the cloud][presign_endpoint].
+
+[Refile] and [Active Storage] provide this functionality as well, and they also
+ship with a custom plug-and-play JavaScript solution for integrating these
+endpoints. In contrast, Shrine doesn't ship with any custom JavaScript but
+instead recommends using **[Uppy]**. Uppy is a flexible JavaScript file upload
+library that allows uploading to a [custom endpoint][XHRUpload], to [AWS
+S3][AwsS3], or even to a [resumable endpoint][Tus], with the possibility to use
+UI components such as a simple [status bar][StatusBar] or a complete
+[dashboard][Dashboard]. Since Uppy is maintained by the whole JavaScript
+community, it will generally be better than any homegrown solution.
+
+## Backgrounding
+
+Unlike most other file upload solutions, where background processing is an
+afterthought, Shrine was designed with this feature in mind from day one. It
+is supported via the `backgrounding` plugin, which provides a flexible API
+that allows using [any backgrounding library][backgrounding libraries].
+
+## Large Files
+
+Some applications need to handle large files such as videos, and Shrine doesn't
+fall short in this department. It uses and encourages streaming uploads and
+downloads, where only a small part of the file is loaded into memory at any
+given time. This keeps memory usage very low regardless of the size of the
+files.
+
+Shrine storages also automatically support [partial downloads][Down streaming]
+(provided by the [Down] gem), which allows you to read only a portion of the
+file. This can be useful for extracting metadata, because common information such
+as MIME type or image dimensions are typically written in the beginning of the
+file, so it's enough to download just the first few kilobytes of the file.
+
+### Resumable uploads
+
+Another challenge with large files is that it can be difficult for users
+to upload them to your app, especially on flaky internet connections. With
+a simple HTTP request, should there be any interruption during the execution,
+the whole upload needs to be retried from the beginning.
+
+To fix this problem, the community has created an open HTTP-based protocol for
+resumable uploads – **[tus]**. There even exists a [Ruby server
+implementation][tus-ruby-server] for this protocol ready to use. Finally, for
+attaching files uploaded via the tus protocol you can use the [shrine-tus] gem.
+
+## Security
+
+It's important 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.
+
+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].
+
+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 immediately terminate the download if it reads
+from the `Content-Length` response header that the file will be too large. For
+chunked responses (where `Content-Length` header is absent) the download will
+will be terminated as soon as the received content surpasses the specified
+limit.
+
+[Paperclip]: https://github.com/thoughtbot/paperclip
+[CarrierWave]: https://github.com/carrierwaveuploader/carrierwave
+[Dragonfly]: http://markevans.github.io/dragonfly/
+[Refile]: https://github.com/refile/refile
+[Active Storage]: https://github.com/rails/rails/tree/master/activestorage#active-storage
+[Rack]: https://rack.github.io
+[Sinatra]: http://sinatrarb.com
+[Roda]: http://roda.jeremyevans.net
+[Cuba]: http://cuba.is
+[Hanami]: http://hanamirb.org
+[Grape]: https://github.com/ruby-grape/grape
+[Sequel]: http://sequel.jeremyevans.net
+[ROM]: http://rom-rb.org
+[Hanami::Model]: https://github.com/hanami/model
+[plugin system]: https://twin.github.io/the-plugin-system-of-sequel-and-roda/
+[Down]: https://github.com/janko-m/down
+[`file`]: http://linux.die.net/man/1/file
+[FileMagic]: https://github.com/blackwinter/ruby-filemagic
+[FastImage]: https://github.com/sdsykes/fastimage
+[MimeMagic]: https://github.com/minad/mimemagic
+[Marcel]: https://github.com/basecamp/marcel
+[mime-types]: https://github.com/mime-types/ruby-mime-types
+[mini_mime]: https://github.com/discourse/mini_mime
+[MiniMagick]: https://github.com/minimagick/minimagick
+[ruby-vips]: https://github.com/jcupitt/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-m/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
+[libvips]: http://jcupitt.github.io/libvips/
+[Why is libvips quick]: https://github.com/jcupitt/libvips/wiki/Why-is-libvips-quick
+[metadata]: https://shrinerb.com/rdoc/files/doc/metadata_md.html
+[store_dimensions]: https://shrinerb.com/rdoc/classes/Shrine/Plugins/StoreDimensions.html
+[add_metadata]: https://shrinerb.com/rdoc/classes/Shrine/Plugins/AddMetadata.html
+[validation]: https://shrinerb.com/rdoc/files/doc/validation_md.html
+[upload_endpoint]: https://shrinerb.com/rdoc/classes/Shrine/Plugins/UploadEndpoint.html
+[presign_endpoint]: https://shrinerb.com/rdoc/classes/Shrine/Plugins/PresignEndpoint.html
+[Uppy]: https://uppy.io
+[XHRUpload]: https://uppy.io/docs/xhrupload/
+[AwsS3]: https://uppy.io/docs/aws-s3/
+[Tus]: https://uppy.io/docs/tus/
+[StatusBar]: https://uppy.io/examples/statusbar/
+[Dashboard]: https://uppy.io/examples/dashboard/
+[background job]: http://shrinerb.com/rdoc/classes/Shrine/Plugins/Backgrounding.html
+[backgrounding libraries]: https://github.com/shrinerb/shrine/wiki/Backgrounding-libraries
+[Down streaming]: https://github.com/janko-m/down#streaming
+[tus]: https://tus.io
+[tus-ruby-server]: https://github.com/janko-m/tus-ruby-server
+[shrine-tus]: https://github.com/shrinerb/shrine-tus
+[ImageTragick]: https://imagetragick.com

data/doc/attacher.md

@@ -233,4 +233,4 @@ attacher.delete!(stored_file)        # delegates to `Shrine#delete`
 The `#cache!` and `#store!` only upload the file to the storage, they don't
 write to record's data column.
 
-[file migrations]: http://shrinerb.com/rdoc/files/doc/migrating_storage_md.html
+[file migrations]: https://shrinerb.com/rdoc/files/doc/migrating_storage_md.html

data/doc/carrierwave.md

@@ -40,7 +40,7 @@ via [direct uploads]):
 ```rb
 Shrine.storages = {
   cache: Shrine::Storage::S3.new(prefix: "cache", **s3_options),
-  store: Shrine::Storage::S3.new(prefix: "store", **s3_options),
+  store: Shrine::Storage::S3.new(**s3_options),
 }
 ```
 
@@ -570,11 +570,11 @@ that you can use for retaining the cached file:
 ```rb
 Shrine.plugin :cached_attachment_data
 ```
-```erb
-<%= form_for @user do |f| %>
-  <%= f.hidden_field :avatar, value: @user.cached_avatar_data %>
-  <%= f.file_field :avatar %>
-<% end %>
+```rb
+form_for @user do |f|
+  f.hidden_field :avatar, value: @user.cached_avatar_data
+  f.file_field :avatar
+end
 ```
 
 #### `#remote_<attachment>_url`
@@ -711,9 +711,9 @@ Shrine::Storage::S3.new(endpoint: "https://s3-accelerate.amazonaws.com", **optio
 
 [image_processing]: https://github.com/janko-m/image_processing
 [demo app]: https://github.com/shrinerb/shrine/tree/master/demo
-[Reprocessing versions]: http://shrinerb.com/rdoc/files/doc/regenerating_versions_md.html
+[Reprocessing versions]: https://shrinerb.com/rdoc/files/doc/regenerating_versions_md.html
 [shrine-fog]: https://github.com/shrinerb/shrine-fog
-[direct uploads]: http://shrinerb.com/rdoc/files/doc/direct_s3_md.html
-[`Shrine::Storage::S3`]: http://shrinerb.com/rdoc/classes/Shrine/Storage/S3.html
+[direct uploads]: https://shrinerb.com/rdoc/files/doc/direct_s3_md.html
+[`Shrine::Storage::S3`]: https://shrinerb.com/rdoc/classes/Shrine/Storage/S3.html
 [`Shrine::Storage::GoogleCloudStorage`]: https://github.com/renchap/shrine-google_cloud_storage
 [`Shrine::Storage::Fog`]: https://github.com/shrinerb/shrine-fog

data/doc/creating_storages.md

@@ -1,10 +1,8 @@
 # Creating a New Storage
 
-## Essentials
-
 Shrine ships with the FileSystem and S3 storages, but it's also easy to create
-your own. A storage is a class which needs to implement to the following
-methods:
+your own. A storage is a class which needs to implement `#upload`, `#url`,
+`#open`, `#exists?`, and `#delete` methods.
 
 ```rb
 class Shrine
@@ -14,16 +12,16 @@ class Shrine
         # uploads `io` to the location `id`, can accept upload options
       end
 
-      def url(id, **options)
-        # returns URL to the remote file, accepts options for customizing the URL
+      def open(id, **options)
+        # returns the remote file as an IO-like object
       end
 
-      def open(id)
-        # returns the remote file as an IO-like object
+      def url(id, **options)
+        # returns URL to the remote file, can accept URL options
       end
 
       def exists?(id)
-        # checks if the file exists on the storage
+        # returns whether the file exists on storage
       end
 
       def delete(id)
@@ -36,10 +34,27 @@ end
 
 ## Upload
 
-The job of `Storage#upload` is to upload the given IO object to the storage.
-It's recommended to use [HTTP.rb] for uploading, as it accepts any IO object
-that responds to `#read` (not just file objects), and it streams the IO data
-directly to the socket, making it suitable for large uploads.
+The `#upload` storage method is called by `Shrine#upload`, it accepts an IO
+object (`io`) and upload location (`id`) and is expected to upload the IO
+content to the specified location. It's also given `:shrine_metadata` that was
+extracted from the IO, which can be used for specifying request headers on
+upload. The storage can also support custom upload options (which can be
+utilized with the `upload_options` plugin).
+
+```rb
+class MyStorage
+  # ...
+  def upload(io, id, shrine_metadata: {}, **upload_options)
+    # uploads `io` to the location `id`, can accept upload options
+  end
+  # ...
+end
+```
+
+Unless you're already using a Ruby SDK, it's recommended to use [HTTP.rb] for
+uploading. It accepts any IO object that responds to `#read` (not just file
+objects), and it streams the request body directly to the TCP socket, both for
+raw and multipart uploads, making it suitable for large uploads.
 
 ```rb
 require "http"
@@ -63,8 +78,9 @@ def upload(io, id, shrine_metadata: {}, **upload_options)
 end
 ```
 
-Likewise, if you need to save some information into the metadata after upload,
-you can modify the metadata hash:
+Likewise, if you need to save some information into the metadata after upload
+(e.g. if the MIME type of the file changes on upload), you can modify the
+metadata hash:
 
 ```rb
 def upload(io, id, shrine_metadata: {}, **upload_options)
@@ -73,99 +89,175 @@ def upload(io, id, shrine_metadata: {}, **upload_options)
 end
 ```
 
+## Open
+
+The `#open` storage method is called by various `Shrine::UploadedFile` methods
+that retrieve uploaded file content. It accepts the file location and is
+expected to return an IO-like object (that implements `#read`, `#size`,
+`#rewind`, `#eof?`, and `#close`) that represents the uploaded file.
+
+
+```rb
+class MyStorage
+  # ...
+  def open(id, **options)
+    # returns the remote file as an IO-like object
+  end
+  # ...
+end
+```
+
+Ideally, the returned IO object should lazily retrieve uploaded content, so
+that in cases where metadata needs to be extracted from an uploaded file, only
+a small portion of the file will be downloaded.
+
+It's recommended to use the [Down] gem for this. If the storage exposes its
+files over HTTP, you can use `Down.open`, otherwise if it's possible to stream
+chunks of content from the storage, that can be wrapped in a `Down::ChunkedIO`.
+It's recommended to use the [`Down::Http`] backend, as the [HTTP.rb] gem
+allocates an order of magnitude less memory when reading the response body
+compared to `Net::HTTP`.
+
+The storage can support additional options to customize how the file will be
+opened, `Shrine::UploadedFile#open` and `Shrine::UploadedFile#download` will
+forward any given options to `#open`.
+
 ## Download
 
-Shrine automatically downloads the file to a Tempfile using `#open`. However,
-if you would like to do custom downloading, you can define `#download` and
-Shrine will use that instead:
+`Shrine::UploadedFile#download` by default uses the `#open` storage method to
+stream file content to a Tempfile. However, if you would like to use your own
+custom way of downloading to a file, you can define `#download` on the storage
+and `Shrine::UploadedFile#download` will automatically call that instead.
 
 ```rb
-class Shrine
-  module Storage
-    class MyStorage
-      # ...
+class MyStorage
+  # ...
+  def download(id, **options)
+    # download the uploaded file to a Tempfile
+  end
+  # ...
+end
+```
 
-      def download(id)
-        # download the file to a Tempfile
-      end
+The storage can support additional options to customize how the file will be
+downloaded, `Shrine::UploadedFile#download` will forward any given options to
+`#download`.
 
-      # ...
-    end
+## Url
+
+The `#url` storage method is called by `Shrine::UploadedFile#url`, it accepts a
+file location and is expected to return a resolvable URL to the uploaded file.
+Custom URL options can be supported if needed, `Shrine::UploadedFile#url` will
+forward any given options to `#url`.
+
+```rb
+class MyStorage
+  # ...
+  def url(id, **options)
+    # returns URL to the remote file, can accept URL options
   end
+  # ...
 end
 ```
 
-## Presign
+If the storage does not have uploaded files accessible via HTTP, the `#url`
+method should return `nil`. Note that in this case users can use the
+`download_endpoint` or `rack_response` plugins to create a downloadable link,
+which are implemented in terms of `#open`.
 
-If the storage service supports direct uploads, and requires fetching
-additional information from the server, you can implement a `#presign` method,
-which will be used by the `presign_endpoint` plugin. The method should return an
-object which responds to
+## Exists
 
-* `#url` – returns the URL to which the file should be uploaded to
-* `#fields` – returns a `Hash` of request parameters that should be used for the upload
-* `#headers` – returns a `Hash` of request headers that should be used for the upload (optional)
+The `#exists?` storage method is called by `Shrine::UploadedFile#exists?`, it
+accepts a file location and should return `true` if the file exists on the
+storage and `false` otherwise.
 
 ```rb
-class Shrine
-  module Storage
-    class MyStorage
-      # ...
+class MyStorage
+  # ...
+  def exists?(id)
+    # returns whether the file exists on storage
+  end
+  # ...
+end
+```
 
-      def presign(id, **options)
-        # returns an object which responds to #url and #presign
-      end
+## Delete
 
-      # ...
-    end
+The `#delete` storage method is called by `Shrine::UploadedFile#delete`, it
+accepts a file location and is expected to delete the file from the storage.
+
+```rb
+class MyStorage
+  # ...
+  def delete(id)
+    # deletes the file from the storage
   end
+  # ...
 end
 ```
 
-## Move
+For convenience of use, this method should not raise an exception if the file
+doesn't exist.
+
+## Presign
 
-If your storage can move files, you can add 2 additional methods, and they will
-automatically get used by the `moving` plugin:
+If the storage service supports direct uploads, and requires fetching
+additional information from the server, you can implement a `#presign` method,
+which will be called by the `presign_endpoint` plugin. The `#presign` method
+should return a Hash with the following keys:
+
+* `:method` – HTTP verb that should be used
+* `:url` – URL to which the file should be uploaded to
+* `:fields` – Hash of request parameters that should be used for the upload (optional)
+* `:headers` – Hash of request headers that should be used for the upload (optional)
 
 ```rb
-class Shrine
-  module Storage
-    class MyStorage
-      # ...
+class MyStorage
+  # ...
+  def presign(id, **options)
+    # returns a Hash with :method, :url, :fields, and :headers keys
+  end
+  # ...
+end
+```
 
-      def move(io, id, **upload_options)
-        # does the moving of the `io` to the location `id`
-      end
+The storage can support additional options to customize how the presign will be
+generated, those can be forwarded via the `:presign_options` option on the
+`presign_endpoint` plugin.
 
-      def movable?(io, id)
-        # whether the given `io` is movable to the location `id`
-      end
+## Move
 
-      # ...
-    end
+If your storage can move files, you can add the additional `#move` and
+`#movable?` methods, and they will automatically get used if the `moving`
+plugin is loaded.
+
+```rb
+class MyStorage
+  # ...
+  def move(io, id, **upload_options)
+    # does the moving of the `io` to the location `id`
+  end
+
+  def movable?(io, id)
+    # whether the given `io` is movable to the location `id`
   end
+  # ...
 end
 ```
 
-## Clearing
+## Clear
 
 While this method is not used by Shrine, it is good to give users the
 possibility to delete all files in a storage, and the conventional name for
-this method is `#clear!`:
+this method is `#clear!`.
 
 ```rb
-class Shrine
-  module Strorage
-    class MyStorage
-      # ...
-
-      def clear!
-        # deletes all files in the storage
-      end
-
-      # ...
-    end
+class MyStorage
+  # ...
+  def clear!
+    # deletes all files in the storage
   end
+  # ...
 end
 ```
 
@@ -175,18 +267,12 @@ If your storage supports updating data of existing files (e.g. some metadata),
 the convention is to create an `#update` method:
 
 ```rb
-class Shrine
-  module Storage
-    class MyStorage
-      # ...
-
-      def update(id, options = {})
-        # update data of the file
-      end
-
-      # ...
-    end
+class MyStorage
+  # ...
+  def update(id, **options)
+    # update data of the file
   end
+  # ...
 end
 ```
 
@@ -226,4 +312,6 @@ tests for your storage. There will likely be some edge cases that won't be
 tested by the linter.
 
 [HTTP.rb]: https://github.com/httprb/http
-[fake IO]: https://github.com/shrinerb/shrine-cloudinary/blob/ca587c580ea0762992a2df33fd590c9a1e534905/test/test_helper.rb#L20-L27
+[fake IO]: https://github.com/shrinerb/shrine/blob/master/test/support/fakeio.rb
+[Down]: https://github.com/janko-m/down
+[`Down::Http`]: https://github.com/janko-m/down#httprb