shrine 2.12.0 → 2.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4876f91bcf2a7fc1c06f6eba68fda62e450a6363f0948387e91f48988a0b295
-  data.tar.gz: 514cd9b743ae1d574ba60f16d842a9c3dd14190b56091bd6df1f45d244c9ad7e
+  metadata.gz: 9f51ec7d13c7f830e1cebb7d12c6444aad0b0c2df6c7d57e2cec61da7e8bc8b1
+  data.tar.gz: 9c75a7232d0e10910582a418646fa850305ef2cc164a6a8bc6e021ec52ac5de7
 SHA512:
-  metadata.gz: 6132a5c6c94a7913b1093af118870ac3b9e7e7a35fffabc6e2aec7d58884cad5b3020a7500d755907b7e456e73ce4ba618443bd3a3013ffb0e9ed57149f500f3
-  data.tar.gz: 2e788af689a199e722eec66caedf6eb263fe6f2854fa039cc3c55b20d937faf18ee0bd758cb1e1b9ecb774a09c8e9f7dbe366ea143f4992129e500cc9f10a9ba
+  metadata.gz: 03c0e1e29b8ba35b64fc6e33ab1a297a7f843726e3e7d21bca57449d1b36ee14c2781c3a2ddc6aa1f5bf36aeff9c7f8e77ee1eec8658cc3177bf701b9e942362
+  data.tar.gz: 3d2e11839c487fbd1782bc41751718a6d8e601070aa4c2a03f469f79a9b6fd176d2f5da9db37f2d1236ec1c64bb480c580217061f1d67c87eec0a2f86ae46d74

data/CHANGELOG.md

@@ -1,3 +1,33 @@
+## 2.13.0 (2018-11-04)
+
+* Specify UTF-8 charset in `Content-Type` response header in `presign_endpoint` plugin (@janko-m)
+
+* Specify UTF-8 charset in `Content-Type` response header in `upload_endpoint` plugin (@janko-m)
+
+* Force UTF-8 encoding on filenames coming from Rack's multipart request params in `rack_file` plugin (@janko-m)
+
+* Allow `:host` in `S3#url` to specify a host URL with an additional path prefix (@janko-m)
+
+* Revert adding bucket name to URL path in `S3#url` when `:host` is used with `:force_path_style` (@janko-m)
+
+* In `upload_endpoint` error with "Upload Not Valid" when `file` parameter is present but not a file (@janko-m)
+
+* Allow `Attacher#assign` to accept options for `Shrine#upload` (@janko-m)
+
+* Add `:metadata` option to `Shrine#upload` for manually overriding extracted metadata (@janko-m)
+
+* Add `:force` option to `infer_extension` plugin for always replacing the current extension (@jrochkind)
+
+* Add `:public` option to `S3#initialize` for enabling public uploads (@janko-m)
+
+* Add ability to specify a custom `:signer` for `Shrine::Storage::S3#url` (@janko-m)
+
+* In `S3#upload` do multipart upload for large non-file IO objects (@janko-m)
+
+* In `S3#upload` switch to `Aws::S3::Object#upload_stream` for multipart uploads of IO objects of unknown size (@janko-m)
+
+* In `S3#upload` deprecate using aws-sdk-s3 lower than 1.14 when uploading IO objects of unknown size (@janko-m)
+
 ## 2.12.0 (2018-08-22)
 
 * Ignore nil values when assigning files from a remote URL (@janko-m)

data/README.md

@@ -19,6 +19,7 @@ If you're curious how it compares to other file attachment libraries, see the [A
 - Documentation: [shrinerb.com](https://shrinerb.com)
 - Demo code: [Roda][roda demo] / [Rails][rails demo]
 - Source: [github.com/shrinerb/shrine](https://github.com/shrinerb/shrine)
+- Wiki: [github.com/shrinerb/shrine/wiki](https://github.com/shrinerb/shrine/wiki)
 - Bugs: [github.com/shrinerb/shrine/issues](https://github.com/shrinerb/shrine/issues)
 - Help & Discussion: [groups.google.com/group/ruby-shrine](https://groups.google.com/forum/#!forum/ruby-shrine)
 
@@ -202,6 +203,14 @@ Some of the tasks performed by `#upload` include:
 * uploading (this is where the storage is called)
 * closing the uploaded file
 
+Additional upload options can be passed via `:upload_options`, and they will be
+forwarded directly to `Storage#upload` (see the documentation of your storage
+for the list of available options):
+
+```rb
+uploader.upload(file, upload_options: { acl: "public-read" })
+```
+
 ### IO abstraction
 
 Shrine is able to upload any IO-like object that responds to `#read`,
@@ -351,8 +360,8 @@ photo.update(image: nil)      # removes the attachment and deletes previous
 
 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.
+to retain cached files in case of validation errors and handle [direct uploads]
+via the hidden form field.
 
 ```rb
 photo.image = '{"id":"9260ea09d8effd.jpg","storage":"cache","metadata":{...}}'
@@ -361,7 +370,7 @@ photo.image = '{"id":"9260ea09d8effd.jpg","storage":"cache","metadata":{...}}'
 ## Attacher
 
 The model attachment attributes and callbacks just delegate the behaviour
-to ther underlying `Shrine::Attacher` object.
+to their underlying `Shrine::Attacher` object.
 
 ```rb
 photo.image_attacher #=> #<Shrine::Attacher>
@@ -397,6 +406,14 @@ photo.image = file # uploads to :other_cache storage
 photo.save         # promotes to :other_store storage
 ```
 
+You can also skip the temporary storage altogether and upload files directly to
+the primary storage:
+
+```rb
+uploaded_file = attacher.store!(file) # upload file directly to permanent storage
+attacher.set(uploaded_file)           # attach the uploaded file
+```
+
 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
@@ -471,13 +488,22 @@ By the default the UNIX [`file`] utility is used to determine the MIME type,
 but you can also choose a different analyzer – see the plugin documentation for
 more details.
 
-### Custom metadata
+### Other metadata
 
 In addition to `size`, `filename`, and `mime_type`, you can also extract image
 dimensions using the `store_dimensions` plugin, as well as any custom metadata
 using the `add_metadata` plugin. Check out the [Extracting Metadata] guide for
 more details.
 
+Note that you can also manually override extracted metadata by passing the
+`:metadata` option to `Shrine#upload`:
+
+```rb
+uploaded_file = uploader.upload(file, metadata: { "filename" => "Matrix[1999].mp4", "foo" => "bar" })
+uploaded_file.original_filename #=> "Matrix[1999].mp4"
+uploaded_file.metadata["foo"]   #=> "bar"
+```
+
 ## Processing
 
 Shrine's `processing` plugin allows you to intercept when the cached file is
@@ -552,23 +578,23 @@ The `versions` plugin also expands `#<attachment>_url` to accept version names:
 photo.image_url(:large) #=> "https://..."
 ```
 
-For more details, including examples of how to do custom processing, see the
-[File Processing] guide.
+For more details, including examples of how to do custom and on-the-fly
+processing, see the [File Processing] guide.
 
 ## Context
 
 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.
+argument, which is forwarded down the chain and be available for processing,
+extracting metadata and generating location.
 
 ```rb
 uploader.upload(file, { foo: "bar" }) # context hash is forwarded to all tasks around upload
 ```
 
-Some options are actually recognized by Shrine, like `:location` and
-`:upload_options`, some are added by plugins, and the rest are there just to
-provide additional context, for more flexibility in performing tasks and more
-descriptive logging.
+Some options are actually recognized by Shrine (such as `:location`,
+`:upload_options`, and `:metadata`), some are added by plugins, and the rest are
+there just to provide additional context, for more flexibility in performing
+tasks and more descriptive logging.
 
 The attacher automatically includes additional `context` information for each
 upload and delete operation:
@@ -659,11 +685,30 @@ responsive during upload, so the user can fill in other fields while the files
 are being uploaded, and if you display a progress bar they can see when the
 upload will finish.
 
-The asynchronous uploads will have to go to a separate endpoint than the one
-where the form is submitted. You can use Shrine's `upload_endpoint` plugin to
-create a Rack app that accepts file uploads and forwards them to the specified
-storage. We want to set it up to upload to *temporary* storage (`:cache`),
-because we're replacing the caching step from the default synchronous workflow.
+These asynchronous uploads will have to go to an endpoint separate from the one
+where the form is submitted. This can be an endpoint in your app, or an
+endpoint of a cloud service. In either case, the uploads should go to
+*temporary* storage (`:cache`), to ensure there won't be any orphan files in
+the primary storage (`:store`).
+
+Once files are uploaded on the client side, their data can be submitted to the
+server and attached to a record, just like with raw files. The only difference
+is that they won't be additionally uploaded to temporary storage on assignment,
+as they were already uploaded on the client side. Note that by default **Shrine
+won't extract metadata from directly uploaded files**, instead it will just copy
+metadata that was extacted on the client side; see [this section][metadata direct uploads]
+for the rationale and instructions on how to opt in.
+
+For handling client side uploads it's recommended to use **[Uppy]**. Uppy is a
+very flexible modern JavaScript file upload library, which happens to integrate
+nicely with Shrine.
+
+### Simple direct upload
+
+The simplest approach is creating an upload endpoint in your app that will
+receive uploads and forward them to the specified storage. You can use the
+`upload_endpoint` Shrine plugin to create a Rack app that handles uploads,
+and mount it inside your application.
 
 ```rb
 Shrine.plugin :upload_endpoint
@@ -682,38 +727,101 @@ Rails.application.routes.draw do
 end
 ```
 
-The above will add a `POST /images/upload` route to your app. You can now
-use the **[Uppy]** JavaScript library to upload files to this endpoint as soon
-they're selected, and write the result to the hidden field. The JavaScript code
-for this will depend on your application, see [this walkthrough][direct uploads
-walkthrough] that adds direct uploads from scratch.
+The above will add a `POST /images/upload` route to your app. You can now use
+Uppy's [XHR Upload][uppy xhr upload] plugin to upload selected files to this
+endpoint, and have the uploaded file data submitted to your app. The client
+side code for this will depend on your application, see [this
+walkthrough][direct uploads walkthrough] for an example of adding simple direct
+uploads from scratch.
+
+If you wanted to implement this enpdoint yourself, this is how it could roughly
+look like in Sinatra:
+
+```rb
+Shrine.plugin :rack_file # only if not using Rails
+```
+```rb
+post "/images/upload" do
+  uploader = ImageUploader.new(:cache)
+  file     = Shrine.rack_file(params["file"]) # only `params[:file]` in Rails
+
+  uploaded_file = uploader.upload(file)
+
+  json uploaded_file.data
+end
+```
+
+### Presigned direct upload
+
+If you want to free your app from receiving file uploads, you can also upload
+files directly to the cloud (AWS S3, Google Cloud etc). In this flow the client
+is required to first fetch upload parameters from the server, and then use these
+parameters to make the upload. The `presign_endpoint` Shrine plugin can be used
+to create a Rack app that generates these upload parameters (provided that the
+underlying storage implements `#presign`):
+
+```rb
+Shrine.plugin :presign_endpoint
+```
+```rb
+# config.ru (Rack)
+map "/presign" do
+  run Shrine.presign_endpoint(:cache)
+end
+
+# OR
+
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  mount Shrine.presign_endpoint(:cache) => "/presign"
+end
+```
+
+The above will add a `GET /presign` route to your app. You can now hook Uppy's
+[AWS S3][uppy aws s3] plugin to this endpoint and have it upload directly to
+S3. See [this walkthrough][direct S3 uploads walkthrough] that shows adding
+direct S3 uploads from scratch, as well as the [Direct Uploads to S3][direct S3
+uploads guide] guide that provides some useful tips. Also check out the
+[Roda][roda demo] / [Rails][rails demo] demo app which implements multiple
+uploads directly to S3.
+
+If you wanted to implement this enpdoint yourself, this is how it could roughly
+look like for S3 storage in Sinatra:
 
-You can also upload files directly to the cloud (AWS S3, Google Cloud etc),
-using Shrine's `presign_endpoint` plugin. See [this walkthrough][direct S3
-uploads walkthrough] that adds direct S3 uploads from scratch using Uppy, as
-well as the [Direct Uploads to S3][direct S3 uploads guide] guide that provides
-some useful tips. Also check out the [Roda][roda demo] or [Rails][rails demo]
-demo app which implements multiple uploads directly to S3.
+```rb
+get "/presign" do
+  storage  = Shrine.storages[:cache]
+  location = SecureRandom.hex + File.extname(params["filename"].to_s)
+
+  presign_data = storage.presign(location, content_type: params["type"])
+
+  json presign_data
+end
+```
 
-### Resumable uploads
+### Resumable direct upload
 
-When your app is dealing with large uploads (e.g. videos), keep in mind that it
+If your app is dealing with large uploads (e.g. videos), keep in mind that it
 can be challening for your users to upload these large files to your app. Many
 users might not have a great internet connection, and if it happens to break at
-any point during uploading, they would need to restart the upload from the
-beginning.
+any point during uploading, they need to retry the upload from the beginning.
 
-Luckily, there is a solution for this. **[Tus.io][tus]** is an open protocol
-for resumable file uploads, which enables the client and the server to achieve
+This problem has been solved by **[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 connections, by enabling the upload to
 be resumed in case of interruptions, even after the browser was closed or the
 device was shut down.
 
-On the client side you can use [Uppy][uppy tus] with [tus-js-client], have it
-upload files to a [tus-ruby-server], and finally attach the uploaded files with
-the help of [shrine-tus]. See [this walkthrough][resumable uploads walkthrough]
-that adds resumable uploads from scratch, as well as the [Roda demo][resumable
-demo] for a complete example.
+[tus-ruby-server] provides a Ruby server implemenation of the tus protocol.
+Uppy's [Tus][uppy tus] plugin can then be configured to do resumable uploads to
+a tus-ruby-server instance, and then the uploaded files can be attached to the
+record with the help of [shrine-tus]. See [this walkthrough][resumable uploads
+walkthrough] that adds resumable uploads from scratch, as well as the
+[demo][resumable demo] for a complete example.
+
+Alternatively, you can have resumable uploads directly to S3 using Uppy's [AWS
+S3 Multipart][uppy aws s3 multipart] plugin, accompanied with the
+[uppy-s3_multipart] gem.
 
 ## Backgrounding
 
@@ -869,7 +977,7 @@ The gem is available as open source under the terms of the [MIT License].
 [mongoid plugin]: https://github.com/shrinerb/shrine-mongoid
 [image_processing]: https://github.com/janko-m/image_processing
 [ImageMagick]: https://www.imagemagick.org/script/index.php
-[libvips]: http://jcupitt.github.io/libvips/
+[libvips]: http://libvips.github.io/libvips/
 [validation_helpers plugin]: https://shrinerb.com/rdoc/classes/Shrine/Plugins/ValidationHelpers.html
 [upload_endpoint plugin]: https://shrinerb.com/rdoc/classes/Shrine/Plugins/UploadEndpoint.html
 [presign_endpoint plugin]: https://shrinerb.com/rdoc/classes/Shrine/Plugins/PresignEndpoint.html
@@ -888,13 +996,17 @@ The gem is available as open source under the terms of the [MIT License].
 [Extracting Metadata]: https://shrinerb.com/rdoc/files/doc/metadata_md.html
 [File Processing]: https://shrinerb.com/rdoc/files/doc/processing_md.html
 [File Validation]: https://shrinerb.com/rdoc/files/doc/validation_md.html
+[metadata direct uploads]: https://github.com/shrinerb/shrine/blob/master/doc/metadata.md#direct-uploads
+[uppy xhr upload]: https://uppy.io/docs/xhr-upload/
 [direct uploads walkthrough]: https://github.com/shrinerb/shrine/wiki/Adding-Direct-App-Uploads
+[uppy aws s3]: https://uppy.io/docs/aws-s3/
 [direct S3 uploads walkthrough]: https://github.com/shrinerb/shrine/wiki/Adding-Direct-S3-Uploads<Paste>
 [direct S3 uploads guide]: https://shrinerb.com/rdoc/files/doc/direct_s3_md.html
 [roda demo]: https://github.com/shrinerb/shrine/tree/master/demo
 [rails demo]: https://github.com/erikdahlstrand/shrine-rails-example
-[tus-js-client]: https://github.com/tus/tus-js-client
 [shrine-tus]: https://github.com/shrinerb/shrine-tus
+[uppy aws s3 multipart]: https://uppy.io/docs/aws-s3-multipart/
+[uppy-s3_multipart]: https://github.com/janko-m/uppy-s3_multipart
 [resumable uploads walkthrough]: https://github.com/shrinerb/shrine/wiki/Adding-Resumable-Uploads
 [resumable demo]: https://github.com/shrinerb/shrine-tus-demo
 [backgrounding libraries]: https://github.com/shrinerb/shrine/wiki/Backgrounding-libraries

data/doc/advantages.md

@@ -1,6 +1,6 @@
 # Advantages of Shrine
 
-There are many popular file upload solutions for Ruby out there – [Paperclip],
+There are many existing 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.
@@ -8,15 +8,15 @@ 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.
+Storage) or Active Record itself (Paperclip, 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]) and database libraries
+([Sequel], [ROM], [Hanami::Model]) 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
+framework or ORM you're using. Any web-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.
@@ -36,6 +36,31 @@ Shrine.plugin :mongoid # https://github.com/shrinerb/shrine-mongoid
 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:
+
+* Storage classes encapsulate file operations for the underlying service
+* `Shrine` handles uploads and manages plugins
+* `Shrine::UploadedFile` repesents a file that was uploaded to a storage
+* `Shrine::Attacher` handles attaching files to records
+* `Shrine::Attachment` adds convenience methods to model instances
+
+```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 storages and ORMs possible with
+minimal amount of code.
+
 ## Modularity
 
 Shrine uses a [plugin system] that allows you to pick and choose the features
@@ -47,53 +72,32 @@ very fast.
 Shrine.plugin :logging # loads the logging feature
 ```
 
+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.
+
 ### 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.
+Shrine plugins require additional dependencies, but you only need to load them
+if you're using those plugins.
+
+Moreover, Shrine often let you choose between multiple alternative dependencies
+for doing the same task. For example, the `determine_mime_type` plugin allows
+you to choose between the [`file`] command, [FileMagic], [FastImage],
+[MimeMagic], or [Marcel] gem for determining the MIME type, while the
+`store_dimensions` plugin can extract dimensions using [FastImage],
+[MiniMagick], or [ruby-vips] gem.
 
 ```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
+This approach gives you control over your dependencies by allowing you 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
@@ -125,11 +129,12 @@ 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.
+Instead of having yet another vendored solution for generating image
+thumbnails, Shrine chose to adopt a generic **[ImageProcessing]** gem. The
+ImageProcessing gem was created for Shrine, but it can be used in any other
+file upload library. It has a very flexible API 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"
@@ -145,10 +150,11 @@ thumbnail #=> #<Tempfile:/var/folders/.../image_processing20180316-18446-1j247h6
 ### 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.
+libvips is also a full-featured image processing library, which can process
+images very rapidly – often multiple times faster than ImageMagick – with low
+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"
@@ -166,11 +172,9 @@ ImageProcessing::Vips.resize_to_fit(800, 800).call(original)
 
 ### 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.
+Shrine's processing block simply executes the Ruby code inside it, so you can
+call there any other processor your want. The only thing that Shrine requires
+is that processed files are returned as the block result.
 
 ```rb
 class VideoUploader < Shrine
@@ -182,28 +186,6 @@ class VideoUploader < Shrine
 end
 ```
 
-### On-the-fly processing
-
-Shrine is primarily designed for processing files on upload, since that's
-applicable to all types of files, though on-the-fly processing that [Dragonfly],
-[Refile], and [Active Storage] can make managing image thumbnails a lot easier.
-
-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
-def thumbnail_url(uploaded_file, dimensions)
-  Dragonfly.app
-    .fetch(uploaded_file.url)
-    .thumb(dimensions)
-    .url
-end
-```
-```rb
-thumbnail_url(photo.image, "500x400") #=> "/attachments/W1siZnUiLCJodHRwOi8vd3d3LnB1YmxpY2RvbWFpbn..."
-```
-
 ## Metadata
 
 Shrine automatically [extracts metadata][metadata] from each uploaded file,
@@ -227,35 +209,38 @@ photo.image.metadata #=>
 
 ## 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
+Instead of submitting selected files synchronously via the form, it's generally
+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
+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
+S3][AwsS3], or even to a [resumable endpoint][Tus]. It comes with a set of UI
+components, ranging from a simple [status bar][StatusBar] to a full-featured
 [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].
+In most file upload solutions background processing was an afterthought, which
+resulted in complex implementations. Shrine was designed with backgrounding
+feature in mind from day one. It is supported via the `backgrounding` plugin
+and can be used with [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.
+If your application needs to handle large files (such as videos), Shrine will
+go out of the way to make this as resilient and performant as possible.
+
+### Streaming
+
+Shrine uses and encourages streaming uploads and downloads, where only a small
+part of the file is loaded into memory at any given time. This means that
+Shrine will use very little memory 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
@@ -265,22 +250,25 @@ 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.
+Another challenge with large files is that it can be difficult for your users
+to upload them to your app, especially on flaky internet connections. Since by
+default an upload is made in a single long HTTP request, any connection
+failures will cause the upload to fail and have to be restarted from the
+beginning.
 
 To fix this problem, [Transloadit] company has created an open HTTP-based
 protocol for resumable uploads – **[tus]**. To use it, you can choose from
 numerous client and server [implementations][tus implementations] of the
-protocol. In this case you would typically have a [JavaScript
-client][tus-js-client] (via [Uppy][uppy tus]) upload to a [Ruby
-server][tus-ruby-server], and then attach uploaded files using the handy
-[Shrine integration][shrine-tus].
+protocol. In a typical app you would have a [JavaScript client][tus-js-client]
+(via [Uppy][uppy tus]) upload to a [Ruby server][tus-ruby-server], and then
+attach uploaded files using the handy [Shrine integration][shrine-tus].
+
+Alternatively, you can have [resumable multipart uploads directly to
+S3][uppy-s3_multipart].
 
 ## Security
 
-It's important to care about security when handling file uploads, and
+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
@@ -324,15 +312,15 @@ limit.
 [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
+[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-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
+[libvips]: http://libvips.github.io/libvips/
+[Why is libvips quick]: https://github.com/libvips/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
@@ -356,3 +344,5 @@ limit.
 [tus-ruby-server]: https://github.com/janko-m/tus-ruby-server
 [shrine-tus]: https://github.com/shrinerb/shrine-tus
 [ImageTragick]: https://imagetragick.com
+[uppy-s3_multipart]: https://github.com/janko-m/uppy-s3_multipart
+[OWASP]: https://www.owasp.org/index.php/Unrestricted_File_Upload