shrine 3.1.0 → 3.4.0

data/doc/direct_s3.md

@@ -76,6 +76,7 @@ If you're using [Uppy], this is the recommended CORS configuration for the
     <AllowedHeader>x-amz-content-sha256</AllowedHeader>
     <AllowedHeader>content-type</AllowedHeader>
     <AllowedHeader>content-disposition</AllowedHeader>
+    <ExposeHeader>ETag</ExposeHeader>
   </CORSRule>
   <CORSRule>
     <AllowedOrigin>*</AllowedOrigin>
@@ -85,6 +86,31 @@ If you're using [Uppy], this is the recommended CORS configuration for the
 </CORSConfiguration>
 ```
 
+Or in JSON format:
+
+```json
+[
+    {
+        "AllowedOrigins": [ "https://my-app.com" ],
+        "AllowedMethods": [ "GET", "POST", "PUT" ],
+        "MaxAgeSeconds": 3000,
+        "AllowedHeaders": [
+            "Authorization",
+            "x-amz-date",
+            "x-amz-content-sha256",
+            "Content-Type",
+            "Content-Disposition"
+        ],
+        "ExposeHeaders": [ "ETag" ]
+    },
+    {
+        "AllowedOrigins": [ "*" ],
+        "AllowedMethods": [ "GET" ],
+        "MaxAgeSeconds": 3000
+    }
+]
+```
+
 Replace `https://my-app.com` with the URL to your app (in development you can
 set this to `*`). Once you've hit "Save", it may take some time for the
 new CORS settings to be applied.

data/doc/external/articles.md

@@ -4,48 +4,60 @@ title: Articles
 
 ## Official articles
 
-* [Introducing Shrine](http://twin.github.io/introducing-shrine)
-* [Asynchronous File Uploads](http://twin.github.io/file-uploads-asynchronous-world)
-* [Shrine 2.0 Released](https://twin.github.io/shrine-2-0-released/)
-* [Shrine meets Transloadit](https://twin.github.io/shrine-meets-transloadit/)
-* [Resumable File Uploads in Ruby](https://twin.github.io/resumable-file-uploads-in-ruby/)
-* [Adding Direct S3 Uploads to a Roda App with Shrine](https://github.com/shrinerb/shrine/wiki/Adding-Direct-S3-Uploads)
-* [Adding Resumable Uploads to a Roda App with Shrine](https://github.com/shrinerb/shrine/wiki/Adding-Resumable-Uploads)
-* [Better File Uploads with Shrine: Motivation](https://twin.github.io/better-file-uploads-with-shrine-motivation/)
-* [Better File Uploads with Shrine: Uploader](https://twin.github.io/better-file-uploads-with-shrine-uploader/)
-* [Better File Uploads with Shrine: Attachment](https://twin.github.io/better-file-uploads-with-shrine-attachment/)
-* [Better File Uploads with Shrine: Processing](https://twin.github.io/better-file-uploads-with-shrine-processing/)
-* [Better File Uploads with Shrine: Metadata](https://twin.github.io/better-file-uploads-with-shrine-metadata/)
-* [Better File Uploads with Shrine: Direct Uploads](https://twin.github.io/better-file-uploads-with-shrine-direct-uploads)
-* [Shrine 3.0 Released](https://twin.github.io/shrine-3-0-released/)
-
-## Other Articles
-
-* [Uploading files with Shrine in Hanami](http://katafrakt.me/2016/02/04/shrine-hanami-uploads/)
-* [Rails File Uploading You Can Believe in with Shrine](http://www.sitepoint.com/rails-file-uploading-you-can-believe-in-with-shrine/)
-* [Uploading Files With Rails and Shrine](https://code.tutsplus.com/tutorials/uploading-files-with-rails-and-shrine--cms-27596)
-* [Upload images using Shrine.rb and Dropzone.js](https://codyeatworld.com/2017/04/18/rails-uploading-images-confidently-with-shrine-rb/)
-* [Background file uploads to S3 using Shrine](http://elixirator.com/blog/2017/background-file-uploads-to-s3-using-shrine.html)
-* [Rails + Shrine + DropzoneJS](https://stephencodes.com/rails-5-shrine-dropzonejs/)
-* [Uploading Files with Rails and ActionCable](https://scotch.io/tutorials/uploading-files-with-rails-and-actioncable)
-* [Creating Streaming Radio With Rails and Icecast](https://scotch.io/tutorials/creating-online-streaming-radio-with-rails-and-icecast)
-* [Multiple Photo Upload using Shrine](https://github.com/pyksoft/multi-photo-upload#multiple-photo-upload-using-shrine)
-* [Store Your Files on S3: Setup & Configuration](https://www.ironin.it/blog/store-your-files-on-s3-using-the-ruby-shrine-gem-part-1.html)
-* [Store Your Files on S3: Direct Uploads](https://www.ironin.it/blog/store-your-files-on-s3-using-the-ruby-shrine-gem-part-2.html)
-* [Store Your Files on S3: Uploading from a URL](https://www.ironin.it/blog/store-your-files-on-s3-using-the-ruby-shrine-gem-part-3.html)
-* [How to use Trix and Shrine for WYSIWYG Editing with Drag-and-Drop Image Uploading](http://headway.io/blog/how-to-use-trix-and-shrine-for-wysiwyg-editing-with-drag-and-drop-image-uploading/)
-* [Happy users uploading files with Rails 5, Shrine, and Vue.js](https://itnext.io/happy-users-uploading-files-with-rails-5-shrine-and-vue-js-bbcc470a327f)
-* [Notes on study of shrine implementation](https://bibwild.wordpress.com/2018/09/12/notes-on-study-of-shrine-implementation/)
-* [GraphQL file upload with Shrine](https://blog.stanko.io/graphql-file-upload-with-shrine-45fa26463c68)
-
-## Videos
-
-* [wroc_love.rb – Handling file uploads for a modern developer](https://www.youtube.com/watch?v=fP2JGjTZU2s)
-* [File Uploads in Rails with Shrine (GoRails)](https://gorails.com/episodes/file-uploading-with-shrine?autoplay=1)
-* [Direct File Uploads to S3: Part 1 (GoRails)](https://gorails.com/episodes/direct-file-uploads-to-s3-part-1?autoplay=1)
-* [Direct File Uploads to S3: Part 2 (GoRails)](https://gorails.com/episodes/direct-file-uploads-to-s3-part-2?autoplay=1)
-* [Direct File Uploads to S3: Part 3 (GoRails)](https://gorails.com/episodes/direct-file-uploads-to-s3-part-3?autoplay=1)
-* [Backgrounding and Video Transcoding (GoRails)](https://gorails.com/episodes/shrine-background-and-video-transcoding?autoplay=1)
-* [Multiple File Uploads with Shrine (GoRails)](https://gorails.com/episodes/multiple-file-uploads-with-shrine?autoplay=1)
-* [Trix WYSIWYG Editor And File Uploads (GoRails)](https://gorails.com/episodes/trix-editor?autoplay=1)
-* [Uploading Files to DigitalOcean Spaces (GoRails)](https://gorails.com/episodes/digital-ocean-spaces-with-rails?autoplay=1)
+| Article                                                                                                                      | Published             |
+| :-------                                                                                                                     | --------:             |
+| [Better File Uploads with Shrine: Eager Processing](https://twin.github.io/better-file-uploads-with-shrine-eager-processing) | 12 Dec 2019 |
+| [Shrine 3.0 Released](https://twin.github.io/shrine-3-0-released/)                                                           | 14 Oct 2019 |
+| [Upcoming Features in Shrine 3.0](https://twin.github.io/upcoming-features-in-shrine-3-0/)                                   | 29 Aug 2019 |
+| [Better File Uploads with Shrine: Direct Uploads](https://twin.github.io/better-file-uploads-with-shrine-direct-uploads/)    | 08 Jan 2018 |
+| [Better File Uploads with Shrine: Metadata](https://twin.github.io/better-file-uploads-with-shrine-metadata/)                | 07 Nov 2016 |
+| [Better File Uploads with Shrine: Processing](https://twin.github.io/better-file-uploads-with-shrine-processing/)            | 31 Oct 2016 |
+| [Better File Uploads with Shrine: Attachment](https://twin.github.io/better-file-uploads-with-shrine-attachment/)            | 17 Sep 2016 |
+| [Better File Uploads with Shrine: Uploader](https://twin.github.io/better-file-uploads-with-shrine-uploader/)                | 16 Sep 2016 |
+| [Better File Uploads with Shrine: Motivation](https://twin.github.io/better-file-uploads-with-shrine-motivation/)            | 11 Sep 2016 |
+| [Resumable File Uploads in Ruby](https://twin.github.io/resumable-file-uploads-in-ruby/)                                     | 04 Sep 2016 |
+| [Shrine meets Transloadit](https://twin.github.io/shrine-meets-transloadit/)                                                 | 11 Jul 2016 |
+| [Shrine 2.0 Released](https://twin.github.io/shrine-2-0-released/)                                                           | 20 May 2016 |
+| [Asynchronous File Uploads](http://twin.github.io/file-uploads-asynchronous-world)                                           | 18 Jan 2016 |
+| [Introducing Shrine](http://twin.github.io/introducing-shrine)                                                               | 04 Oct 2015 |
+
+## Community articles
+
+| Article                                                                                                                                                                                                                                                               | Published             |
+| :------                                                                                                                                                                                                                                                               | --------:             |
+| [Microsoft Azure data storage library](https://syndicode.com/2019/12/17/microsoft-azure-data-storage-library-rewrite-the-existing-library-to-get-things-done/)                                                                                                        | 17 Dec 2019 |
+| [How to use REST clients / native apps to make Shrine client uploads and S3 work for you (no Javascript, just backend)](https://dev.to/rob117/how-to-use-rest-clients--native-apps-to-make-shrine-client-uploads-and-s3-work-for-you-no-javascript-just-backend-322h) | 16 Feb 2019 |
+| [GraphQL file upload with Shrine](https://blog.stanko.io/graphql-file-upload-with-shrine-45fa26463c68)                                                                                                                                                                | 02 Jan 2019 |
+| [Notes on study of shrine implementation](https://bibwild.wordpress.com/2018/09/12/notes-on-study-of-shrine-implementation/)                                                                                                                                          | 12 Sep 2018 |
+| [Happy users uploading files with Rails 5, Shrine, and Vue.js](https://itnext.io/happy-users-uploading-files-with-rails-5-shrine-and-vue-js-bbcc470a327f)                                                                                                             | 04 Sep 2018 |
+| [Rails 5 + Shrine + DropzoneJS](https://stephencodes.com/rails-5-shrine-dropzonejs/)                                                                                                                                                                                  | 20 Oct 2018 |
+| [How to use Trix and Shrine for WYSIWYG Editing with Drag-and-Drop Image Uploading](http://headway.io/blog/how-to-use-trix-and-shrine-for-wysiwyg-editing-with-drag-and-drop-image-uploading/)                                                                        | 26 Jan 2018 |
+| [Store Your Files on S3: Part 3 – Uploading from a URL](https://www.ironin.it/blog/store-your-files-on-s3-using-the-ruby-shrine-gem-part-3.html)                                                                                                                               | 28 Dec 2017 |
+| [Store Your Files on S3: Part 2 – Direct Uploads](https://www.ironin.it/blog/store-your-files-on-s3-using-the-ruby-shrine-gem-part-2.html)                                                                                                                                     | 15 Dec 2017 |
+| [Store Your Files on S3: Part 1 – Setup & Configuration](https://www.ironin.it/blog/store-your-files-on-s3-using-the-ruby-shrine-gem-part-1.html)                                                                                                                              | 27 Nov 2017 |
+| [Creating Streaming Radio With Rails and Icecast](https://scotch.io/tutorials/creating-online-streaming-radio-with-rails-and-icecast)                                                                                                                                 | 06 Nov 2017 |
+| [Multiple Photo Upload using Shrine](https://github.com/pyksoft/multi-photo-upload#multiple-photo-upload-using-shrine)                                                                                                                                                | 02 Nov 2017 |
+| [Uploading Files with Rails and ActionCable](https://scotch.io/tutorials/uploading-files-with-rails-and-actioncable)                                                                                                                                                  | 19 Oct 2017 |
+| [Background file uploads to S3 using Shrine](https://elixirator.com/blog/background-file-uploads-to-s3-using-shrine/)                                                                                                                                                 | 21 Jul 2017 |
+| [Upload images using Shrine.rb and Dropzone.js](https://codyeatworld.com/2017/04/18/rails-uploading-images-confidently-with-shrine-rb/)                                                                                                                               | 18 Apr 2017 |
+| [Uploading Files With Rails and Shrine](https://code.tutsplus.com/tutorials/uploading-files-with-rails-and-shrine--cms-27596)                                                                                                                                         | 26 Dec 2016 |
+| [Rails File Uploading You Can Believe in with Shrine](http://www.sitepoint.com/rails-file-uploading-you-can-believe-in-with-shrine/)                                                                                                                                  | 11 Apr 2016 |
+| [Uploading files with Shrine in Hanami](http://katafrakt.me/2016/02/04/shrine-hanami-uploads/)                                                                                                                                                                        | 04 Feb 2016 |
+
+## Screencasts
+
+| Screencast                                                                                                             | Source  | Published             |
+| :----                                                                                                                  | :------ | --------:             |
+| [Testing File Uploads in Rails with Shrine](https://gorails.com/episodes/testing-file-uploads-with-shrine?autoplay=1)  | GoRails | 23 Mar 2020 |
+| [File Uploads in Rails with Shrine](https://gorails.com/episodes/rails-file-uploads-with-shrine?autoplay=1)            | GoRails | 16 Mar 2020 |
+| [Uploading Files to DigitalOcean Spaces](https://gorails.com/episodes/digital-ocean-spaces-with-rails?autoplay=1)      | GoRails | 31 Oct 2017 |
+| [Trix WYSIWYG Editor And File Uploads](https://gorails.com/episodes/trix-editor?autoplay=1)                            | GoRails | 03 Oct 2017 |
+| [Multiple File Uploads with Shrine](https://gorails.com/episodes/multiple-file-uploads-with-shrine?autoplay=1)         | GoRails | 14 Dec 2016 |
+| [Backgrounding and Video Transcoding](https://gorails.com/episodes/shrine-background-and-video-transcoding?autoplay=1) | GoRails | 03 Nov 2016 |
+
+## Talks
+
+| Talk                                                                                        | Source         | Date                  |
+| :----                                                                                       | :------        | --------:             |
+| [Handling file uploads for a modern developer](https://www.youtube.com/watch?v=fP2JGjTZU2s) | wroc_love.rb   | 24 Mar 2019 |
+| [Shrine – Handle File Uploads like it's 2017](https://www.youtube.com/watch?v=plD-RkKEay0)  | Melbourne Ruby | 27 Feb 2017 |

data/doc/external/extensions.md

@@ -4,44 +4,50 @@ title: Extensions
 
 ## Storages
 
-* [shrine-aliyun-oss](https://github.com/zillou/shrine-aliyun-oss)
-* [shrine-cloudinary](https://github.com/shrinerb/shrine-cloudinary)
-* [shrine-flickr](https://github.com/shrinerb/shrine-flickr)
-* [shrine-fog](https://github.com/shrinerb/shrine-fog)
-* [shrine-ftp](https://github.com/ProjectResound/shrine-ftp)
-* [shrine-google_cloud_storage](https://github.com/renchap/shrine-google_cloud_storage)
-* [shrine-gdrive_storage](https://github.com/edwardsharp/shrine-gdrive_storage)
-* [shrine-gridfs](https://github.com/shrinerb/shrine-gridfs)
-* [shrine-imgix](https://github.com/shrinerb/shrine-imgix)
-* [shrine-memory](https://github.com/shrinerb/shrine-memory)
-* [shrine-redis](https://github.com/dbongo/shrine-redis)
-* [shrine-scp](https://github.com/jordanandree/shrine-scp)
-* [shrine-sql](https://github.com/shrinerb/shrine-sql)
-* [shrine-thumbor](https://github.com/havran/shrine-thumbor)
-* [shrine-transloadit](https://github.com/shrinerb/shrine-transloadit)
-* [shrine-uploadcare](https://github.com/shrinerb/shrine-uploadcare)
-* [shrine-url](https://github.com/shrinerb/shrine-url)
-* [shrine-storage-you_tube](https://github.com/thedyrt/shrine-storage-you_tube)
-* [shrine-webdav](https://github.com/funbox/shrine-webdav)
+| Gem                                                                                   | Description                                                                 |
+| :----                                                                                 | :----------                                                                 |
+| [shrine-aliyun-oss](https://github.com/zillou/shrine-aliyun-oss)                      | Storage using [Alibaba Cloud OSS](https://www.alibabacloud.com/product/oss) |
+| [shrine-cloudinary](https://github.com/shrinerb/shrine-cloudinary)                    | Storage using [Cloudinary](https://cloudinary.com/)                         |
+| [shrine-flickr](https://github.com/shrinerb/shrine-flickr)                            | Storage using [Flickr](https://flickr.com/)                                 |
+| [shrine-fog](https://github.com/shrinerb/shrine-fog)                                  | Storage using [Fog](http://fog.io/)                                         |
+| [shrine-ftp](https://github.com/ProjectResound/shrine-ftp)                            | Storage using an FTP server                                                 |
+| [shrine-google_cloud_storage](https://github.com/renchap/shrine-google_cloud_storage) | Storage using [Google Cloud Storage](https://cloud.google.com/storage/)     |
+| [shrine-gdrive_storage](https://github.com/edwardsharp/shrine-gdrive_storage)         | Storage using [Google Drive](https://www.google.com/drive/)                 |
+| [shrine-gridfs](https://github.com/shrinerb/shrine-gridfs)                            | Storage using [Mongo GridFS](https://docs.mongodb.com/manual/core/gridfs/)  |
+| [shrine-redis](https://github.com/dbongo/shrine-redis)                                | Storage using [Redis](https://redis.io/)                                    |
+| [shrine-scp](https://github.com/jordanandree/shrine-scp)                              | Storage using `scp`                                                         |
+| [shrine-sql](https://github.com/shrinerb/shrine-sql)                                  | Storage using an SQL database                                               |
+| [shrine-uploadcare](https://github.com/shrinerb/shrine-uploadcare)                    | Storage using [Uploadcare](https://uploadcare.com)                          |
+| [shrine-url](https://github.com/shrinerb/shrine-url)                                  | Storage for handling remote URLs                                            |
+| [shrine-storage-you_tube](https://github.com/thedyrt/shrine-storage-you_tube)         | Storage using [YouTube](https://www.youtube.com/)                           |
+| [shrine-webdav](https://github.com/funbox/shrine-webdav)                              | Storage using a [WebDAV](https://en.wikipedia.org/wiki/WebDAV) server       |
 
 ## Plugins
 
-* [administrate-field-shrine](https://github.com/catsky/administrate-field-shrine)
-* [rails_admin_shrine](https://github.com/iquest/rails_admin_shrine)
-* [shrine-color](https://github.com/jnylen/shrine-color)
-* [shrine-configurable_storage](https://github.com/SleeplessByte/shrine-configurable_storage)
-* [shrine-content_addressable](https://github.com/SleeplessByte/shrine-content_addressable)
-* [shrine-lambda](https://github.com/texpert/shrine-lambda)
-* [hanami-shrine](https://github.com/katafrakt/hanami-shrine)
-* [shrine-mongoid](https://github.com/shrinerb/shrine-mongoid)
-* [shrine-rails](https://github.com/abepetrillo/shrine-rails)
-* [shrine-reform](https://github.com/shrinerb/shrine-reform)
-* [shrine-rom](https://github.com/shrinerb/shrine-rom)
-* [shrine-tus](https://github.com/shrinerb/shrine-tus)
+| Gem                                                                                         | Description                                                           |
+| :----                                                                                       | :--------                                                             |
+| [administrate-field-shrine](https://github.com/catsky/administrate-field-shrine)            | Plugin for [Administrate](https://github.com/thoughtbot/administrate) |
+| [rails_admin_shrine](https://github.com/iquest/rails_admin_shrine)                          | Plugin for [RailsAdmin](https://github.com/sferik/rails_admin)        |
+| [shrine-blurhash](https://github.com/renchap/shrine-blurhash)                               | Plugin for computing [Blurhash](https://blurha.sh/) on images         |
+| [shrine-cloudimage](https://github.com/janklimo/shrine-cloudimage)                          | Plugin for [Cloudimage](https://www.cloudimage.io/)                   |
+| [shrine-color](https://github.com/jnylen/shrine-color)                                      | Plugin for finding dominant color in an image                         |
+| [shrine-configurable_storage](https://github.com/SleeplessByte/shrine-configurable_storage) | Plugin for lazy storage registration                                  |
+| [shrine-content_addressable](https://github.com/SleeplessByte/shrine-content_addressable)   | Plugin for generating content addressable locations                   |
+| [shrine-imgix](https://github.com/shrinerb/shrine-imgix)                                    | Plugin for [Imgix](https://www.imgix.com/)                            |
+| [shrine-transloadit](https://github.com/shrinerb/shrine-transloadit)                        | Plugin for [Transloadit](https://transloadit.com/)                    |
+| [shrine-lambda](https://github.com/texpert/shrine-lambda)                                   | Plugin for [AWS Lambda](https://aws.amazon.com/lambda/)               |
+| [hanami-shrine](https://github.com/katafrakt/hanami-shrine)                                 | Plugin for [Hanami](https://hanamirb.org/)                            |
+| [shrine-mongoid](https://github.com/shrinerb/shrine-mongoid)                                | Plugin for [Mongoid](https://mongoid.org)                             |
+| [shrine-rails](https://github.com/abepetrillo/shrine-rails)                                 | Plugin for [Rails](https://rubyonrails.org/)                          |
+| [shrine-rom](https://github.com/shrinerb/shrine-rom)                                        | Plugin for [ROM](https://rom-rb.org/)                                 |
+| [shrine-tus](https://github.com/shrinerb/shrine-tus)                                        | Plugin for [tus](https://tus.io) server integration                   |
 
 ## Libraries
 
-* [ckeditor](https://github.com/galetahub/ckeditor)
-* [imgproxy](https://github.com/imgproxy/imgproxy.rb)
-* [rails_admin](https://github.com/sferik/rails_admin)
-* [uppy-s3_multipart](https://github.com/janko/uppy-s3_multipart)
+| Gem                                                             | Description                                                                     |
+| :-----                                                          | :-------                                                                        |
+| [ckeditor](https://github.com/galetahub/ckeditor)               | Integration for [CKEditor](https://ckeditor.com/ckeditor-4/)                    |
+| [faster_s3_url](https://github.com/jrochkind/faster_s3_url)     | Optimized generation of public and presigned AWS S3 GET URLs                    |
+| [imgproxy](https://github.com/imgproxy/imgproxy.rb)             | Integration for [imgproxy](https://github.com/imgproxy/imgproxy)                |
+| [rails_admin](https://github.com/sferik/rails_admin)            | Integration for [RailsAdmin](https://github.com/sferik/rails_admin)             |
+| [uppy-s3_multipart](https://github.com/janko/uppy-s3_multipart) | Integration for [Uppy AWS S3 Multipart](https://uppy.io/docs/aws-s3-multipart/) |

data/doc/external/misc.md

@@ -4,14 +4,29 @@ title: Miscellaneous
 
 ## Demos
 
-* [Dropzone demo](https://github.com/codyeatworld/example-shrine-dropzone)
-* [Hanami demo](https://github.com/katafrakt/hanami-shrine-example)
-* [Rails demo](https://github.com/erikdahlstrand/shrine-rails-example)
-* [Resumable uploads demo](https://github.com/shrinerb/shrine-tus-demo)
-* [Roda demo (official)](https://github.com/shrinerb/shrine/tree/master/demo)
-* [ROM & dry-rb demo](https://github.com/shrinerb/shrine-rom/tree/master/demo)
-* [Transloadit demo](https://github.com/shrinerb/shrine-transloadit/tree/master/demo)
+| Demo                                                                                | Description                                      |
+| :---                                                                                | :----------                                      |
+| [Dropzone demo](https://github.com/codyeatworld/example-shrine-dropzone)            | Shows direct upload using [Dropzone.js]          |
+| [Hanami demo](https://github.com/katafrakt/hanami-shrine-example)                   | Shows file attachment in [Hanami]                |
+| [Crop demo](https://github.com/shrinerb/shrine-crop-example)                        | Shows image cropping using [Cropper.js]          |
+| [Rails demo](https://github.com/erikdahlstrand/shrine-rails-example)                | Shows direct upload in [Rails]                   |
+| [Resumable uploads demo](https://github.com/shrinerb/shrine-tus-demo)               | Shows resumable direct upload on [tus]           |
+| [Roda demo (official)](https://github.com/shrinerb/shrine/tree/master/demo)         | Shows direct upload in [Roda]                    |
+| [rom-rb & dry-rb demo](https://github.com/shrinerb/shrine-rom/tree/master/demo)     | Shows file attachment with [rom-rb] and [dry-rb] |
+| [Transloadit demo](https://github.com/shrinerb/shrine-transloadit/tree/master/demo) | Shows file processing using [Transloadit]        |
 
 ## Projects
 
-* [Cortex CMS](https://docs.cortexcms.org)
+| Project                                 | Description                                                             |
+| :------                                 | :----------                                                             |
+| [CortexCMS](https://docs.cortexcms.org) | An open source, enterprise content management and distribution platform |
+
+[Dropzone.js]: https://www.dropzonejs.com/
+[Hanami]: https://hanamirb.org/
+[Cropper.js]: https://github.com/fengyuanchen/cropperjs
+[Rails]: https://rubyonrails.org/
+[tus]: https://tus.io/
+[Roda]: https://roda.jeremyevans.net/
+[rom-rb]: https://rom-rb.org/
+[dry-rb]: https://dry-rb.org/
+[Transloadit]: https://transloadit.com/

data/doc/getting_started.md

@@ -37,22 +37,26 @@ will use to store all information about the attachment:
 ```rb
 Sequel.migration do
   change do
-    add_column :photos, :image_data, :text # or :jsonb
+    add_column :photos, :image_data, :text # or :jsonb   
   end
 end
 ```
+
 <!--ActiveRecord-->
 ```rb
 class AddImageDataToPhotos < ActiveRecord::Migration
   def change
-    add_column :photos, :image_data, :text # or :jsonb
+    add_column :photos, :image_data, :text # or :jsonb   
   end
 end
 ```
+
 <!--Rails-->
+```rb
+$ rails generate migration add_image_data_to_photos image_data:text  # or image_data:jsonb 
 ```
-$ rails generate migration add_image_data_to_photos image_data:text
-```
+If using `jsonb` consider adding a [gin index] for fast key-value pair searchability within `image_data`.
+
 <!--END_DOCUSAURUS_CODE_TABS-->
 
 Now you can create an uploader class for the type of files you want to upload,
@@ -110,6 +114,14 @@ form @photo, action: "/photos", enctype: "multipart/form-data" do |f|
   f.button "Create"
 end
 ```
+<!--HTML-->
+```erb
+<form action="/photos" method="post" enctype="multipart/form-data">
+  <input name="photo[image]" type="hidden" value="<%= @photo.cached_image_data %>" />
+  <input name="photo[image] "type="file" />
+  <input type="submit" value="Create" />
+</form>
+```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
 Note that the file field needs to go *after* the hidden field, so that
@@ -167,9 +179,13 @@ specific storage service, by implementing a common public interface. Storage
 instances are registered under an identifier in `Shrine.storages`, so that they
 can later be used by [uploaders][uploader].
 
-Previously we've shown the [FileSystem] storage which saves files to disk, but
-Shrine also ships with [S3] storage which stores files on [AWS S3] (or any
-S3-compatible service such as [DigitalOcean Spaces] or [MinIO]).
+Shrine ships with the following storages:
+
+* [`Shrine::Storage::FileSystem`][FileSystem] – stores files on disk
+* [`Shrine::Storage::S3`][S3] – stores files on [AWS S3] (or [DigitalOcean Spaces], [MinIO], ...)
+* [`Shrine::Storage::Memory`][Memory] – stores file in memory (convenient for [testing][Testing with Shrine])
+
+Here is how we might configure Shrine with S3 storage:
 
 ```rb
 # Gemfile
@@ -180,9 +196,9 @@ require "shrine/storage/s3"
 
 s3_options = {
   bucket:            "<YOUR BUCKET>", # required
+  region:            "<YOUR REGION>", # required
   access_key_id:     "<YOUR ACCESS KEY ID>",
   secret_access_key: "<YOUR SECRET ACCESS KEY>",
-  region:            "<YOUR REGION>",
 }
 
 Shrine.storages = {
@@ -196,9 +212,9 @@ suitable for [direct uploads][presigned upload]. The `:cache` and `:store`
 names are special only in terms that the [attacher] will automatically pick
 them up, you can also register more storage objects under different names.
 
-See the [FileSystem] and [S3] storage docs for more details. There are [many
-more Shrine storages][storages] provided by external gems, and you can also
-[create your own storage][Creating Storages].
+See the [FileSystem]/[S3]/[Memory] storage docs for more details. There are
+[many more Shrine storages][storages] provided by external gems, and you can
+also [create your own storage][Creating Storages].
 
 ## Uploader
 
@@ -256,14 +272,14 @@ Shrine is able to upload any IO-like object that implement methods [`#read`],
 [`#rewind`], [`#eof?`] and [`#close`] whose behaviour matches the [`IO`] class.
 This includes but is not limited to the following objects:
 
-* `File`
-* `Tempfile`
-* `StringIO`
-* `ActionDispatch::Http::UploadedFile` (Rails form upload)
-* `Shrine::RackFile` ([`rack_file`][rack_file plugin] plugin)
-* `Shrine::DataFile` ([`data_uri`][data_uri plugin] plugin)
-* `Shrine::UploadedFile`
-* `Down::ChunkedIO` ([Down] gem)
+* [`File`](https://ruby-doc.org/core/File.html)
+* [`Tempfile`](https://ruby-doc.org/stdlib/libdoc/tempfile/rdoc/Tempfile.html)
+* [`StringIO`](https://ruby-doc.org/stdlib/libdoc/stringio/rdoc/StringIO.html)
+* [`ActionDispatch::Http::UploadedFile`](https://api.rubyonrails.org/classes/ActionDispatch/Http/UploadedFile.html)
+* [`Shrine::RackFile`](https://shrinerb.com/docs/plugins/rack_file)
+* [`Shrine::DataFile`](https://shrinerb.com/docs/plugins/data_uri)
+* [`Shrine::UploadedFile`](#uploaded-file)
+* [`Down::ChunkedIO`](https://github.com/janko/down#streaming)
 * ...
 
 ```rb
@@ -424,9 +440,9 @@ See [Using Attacher] guide for more details.
 
 ### Temporary storage
 
-Shrine uses temporary storage to support retaining uploaded files across form
-redisplays and [direct uploads]. But you can disable this behaviour, and have
-files go straight to permanent storage:
+Shrine uses temporary storage to support [file validation][validation] and
+[direct uploads]. If you don't need these features, you can tell Shrine to
+upload files directly to permanent storage:
 
 ```rb
 Shrine.plugin :model, cache: false
@@ -446,7 +462,7 @@ attacher.file.storage_key #=> :store
 
 ## Plugin system
 
-By default Shrine comes with a small core which provides only the essential
+By default, Shrine comes with a small core which provides only the essential
 functionality. All additional features are available via [plugins], which also
 ship with Shrine. This way you can choose exactly what and how much Shrine does
 for you, and you load the code only for features that you use.
@@ -469,6 +485,12 @@ If you want to extend Shrine functionality with custom behaviour, you can also
 [create your own plugin][Creating Plugins]. There are also additional [external
 plugins] created by others.
 
+> NOTE: An uploader class will inherit a copy of current superclass' plugin
+> options at the time of subclassing. This means you should *not* load
+> additional plugins on a superclass after the subclass has already been
+> created, because new options will not get applied to the subclass, which
+> can result in errors.
+
 ## Metadata
 
 Shrine automatically extracts some basic file metadata and saves them to the
@@ -504,7 +526,7 @@ gem "marcel", "~> 0.3"
 Shrine.plugin :determine_mime_type, analyzer: :marcel
 ```
 ```rb
-photo = Photo.create(image: StringIO.new("<?php ... ?>"))
+photo = Photo.new(image: StringIO.new("<?php ... ?>"))
 photo.image.mime_type #=> "application/x-php"
 ```
 
@@ -517,10 +539,10 @@ the [Extracting Metadata] guide for more details.
 
 ## Processing
 
-Shrine allows you to process attached files up front or on-the-fly. For
-example, if your app is accepting image uploads, you can generate a predefined
-set of of thumbnails when the image is attached to a record, or you can have
-thumbnails generated dynamically as they're needed.
+Shrine allows you to process attached files both "eagerly" and "on-the-fly".
+For example, if your app is accepting image uploads, you can generate a
+predefined set of thumbnails when the image is attached to a record, or you
+can have thumbnails generated dynamically as they're needed.
 
 For image processing, it's recommended to use the **[ImageProcessing]** gem,
 which is a high-level wrapper for processing with
@@ -530,17 +552,19 @@ which is a high-level wrapper for processing with
 $ brew install imagemagick vips
 ```
 
-### Processing up front
+### Eager processing
 
-You can use the [`derivatives`][derivatives plugin] plugin to generate a set of
-pre-defined processed files:
+We can use the [`derivatives`][derivatives plugin] plugin to generate a
+pre-defined set of processed files (e.g. image thumbnails). We do this by
+registering a derivatives processor block and then explicitly triggering
+creation:
 
 ```rb
 # Gemfile
 gem "image_processing", "~> 1.8"
 ```
 ```rb
-Shrine.plugin :derivatives
+Shrine.plugin :derivatives, create_on_promote: true
 ```
 ```rb
 require "image_processing/mini_magick"
@@ -559,32 +583,29 @@ end
 ```
 ```rb
 photo = Photo.new(image: file)
-photo.image_derivatives! # calls derivatives processor and uploads results
-photo.save
+photo.save # automatically creates derivatives on promotion
 ```
 
-If you're allowing the attached file to be updated later on, in your update
-route make sure to trigger derivatives creation for new attachments:
+You can then retrieve the URL of a processed derivative:
 
 ```rb
-photo.image_derivatives! if photo.image_changed?
+photo.image_url(:large) #=> "https://s3.amazonaws.com/path/to/large.jpg"
 ```
 
-After the processed files are uploaded, their data is saved into the
-`<attachment>_data` column. You can then retrieve the derivatives as
-[`Shrine::UploadedFile`][uploaded file] objects:
+The derivatives data is stored in the `<attachment>_data` column, and you can
+retrieve them as [`Shrine::UploadedFile`][uploaded file] objects:
 
 ```rb
-photo.image(:large)            #=> #<Shrine::UploadedFile ...>
-photo.image(:large).url        #=> "/uploads/store/lg043.jpg"
-photo.image(:large).size       #=> 5825949
-photo.image(:large).mime_type  #=> "image/jpeg"
+photo.image(:large)           #=> #<Shrine::UploadedFile id="path/to/large.jpg" storage=:store metadata={...}>
+photo.image(:large).url       #=> "https://s3.amazonaws.com/path/to/large.jpg"
+photo.image(:large).size      #=> 5825949
+photo.image(:large).mime_type #=> "image/jpeg"
 ```
 
-For more details, see the [`derivatives`][derivatives plugin] plugin
-documentation and the [File Processing] guide.
+For more details, see the [File Processing] guide and the
+[`derivatives`][derivatives plugin] plugin documentation.
 
-### Processing on-the-fly
+### On-the-fly processing
 
 On-the-fly processing is provided by the
 [`derivation_endpoint`][derivation_endpoint plugin] plugin. To set it up, we
@@ -597,24 +618,28 @@ processing we want to perform:
 gem "image_processing", "~> 1.8"
 ```
 ```rb
-# config/initializers/shrine.rb (Rails)
+# config/initializers/rails.rb (Rails)
+# ...
+Shrine.plugin :derivation_endpoint, secret_key: "<YOUR_SECRET_KEY>"
+```
+```rb
 require "image_processing/mini_magick"
 
-Shrine.plugin :derivation_endpoint,
-  secret_key: "<YOUR SECRET KEY>",
-  prefix:     "derivations" # needs to match the mount point in routes
+class ImageUploader < Shrine
+  plugin :derivation_endpoint, prefix: "derivations/image" # matches mount point
 
-Shrine.derivation :thumbnail do |file, width, height|
-  ImageProcessing::MiniMagick
-    .source(file)
-    .resize_to_limit!(width.to_i, height.to_i)
+  derivation :thumbnail do |file, width, height|
+    ImageProcessing::MiniMagick
+      .source(file)
+      .resize_to_limit!(width.to_i, height.to_i)
+  end
 end
 ```
 ```rb
 # config/routes.rb (Rails)
 Rails.application.routes.draw do
   # ...
-  mount Shrine.derivation_endpoint => "/derivations"
+  mount ImageUploader.derivation_endpoint => "/derivations/image"
 end
 ```
 
@@ -623,7 +648,7 @@ processing:
 
 ```rb
 photo.image.derivation_url(:thumbnail, 600, 400)
-#=> "/derivations/thumbnail/600/400/eyJpZCI6ImZvbyIsInN0b3JhZ2UiOiJzdG9yZSJ9?signature=..."
+#=> "/derivations/image/thumbnail/600/400/eyJpZCI6ImZvbyIsInN0b3JhZ2UiOiJzdG9yZSJ9?signature=..."
 ```
 
 The on-the-fly processing feature is highly customizable, see the
@@ -661,36 +686,85 @@ For more details, see the [File Validation] guide and
 
 ## Location
 
-Shrine automatically generated random locations before uploading files. By
-default the hierarchy is flat, meaning all files are stored in the root
-directory of the storage. The [`pretty_location`][pretty_location plugin]
-plugin provides a good default hierarchy, but you can also override
-`#generate_location` with a custom implementation:
+Shrine automatically generates random locations before uploading files. By
+default, the hierarchy is flat, meaning all files are stored in the root
+directory of the storage.
+
+```
+024d9fe83bf4fafb.jpg
+768a336bf54de219.jpg
+adfaa363629f7fc5.png
+...
+```
+
+The [`pretty_location`][pretty_location plugin] plugin provides a good default
+hierarchy:
+
+```rb
+Shrine.plugin :pretty_location
+```
+```
+user/
+  564/
+    avatar/
+      aa3e0cd715.jpg
+      thumb-493g82jf23.jpg
+photo/
+  123/
+    image/
+      13f8a7bc18.png
+      thumb-9be62da67e.png
+...
+```
+
+But you can also override `Shrine#generate_location` with a custom
+implementation, for example:
 
 ```rb
 class ImageUploader < Shrine
   def generate_location(io, record: nil, derivative: nil, **)
-    type  = record.class.name.downcase if record
-    style = derivative ? "thumbs" : "originals"
-    name  = super # the default unique identifier
+    return super unless record
 
-    [type, style, name].compact.join("/")
+    table  = record.class.table_name
+    id     = record.id
+    prefix = derivative || "original"
+
+    "uploads/#{table}/#{id}/#{prefix}-#{super}"
   end
 end
 ```
 ```
 uploads/
   photos/
-    originals/
-      la98lda74j3g.jpg
-    thumbs/
-      95kd8kafg80a.jpg
-      ka8agiaf9gk4.jpg
+    123/
+      original-afe929b8b4.jpg
+      small-ad61f25883.jpg
+      medium-41b75c42bb.jpg
+      large-73e67abe50.jpg
+...
 ```
 
-Note that there should always be a random component in the location, so that
-the ORM dirty tracking is detected properly. Inside `#generate_location` you
-can also access the extracted metadata through the `:metadata` option.
+> There should always be a random component in the location, so that the ORM
+  dirty tracking is detected properly.
+
+The `Shrine#generate_location` method contains a lot of useful context for the
+upcoming upload:
+
+```rb
+class ImageUploader < Shrine
+  def generate_location(io, record: nil, name: nil, derivative: nil, metadata: {}, **options)
+    storage_key #=> :cache, :store, ...
+    io          #=> #<File>, #<Shrine::UploadedFile>, ...
+    record      #=> #<Photo>, #<User>, ...
+    name        #=> :image, :avatar, ...
+    derivative  #=> :small, :medium, :large, ... (derivatives plugin)
+    metadata    #=> { "filename" => "nature.jpg", "mime_type" => "image/jpeg", "size" => 18573, ... }
+    options     #=> { ... other uploader options ... }
+
+    # ...
+  end
+end
+```
 
 ## Direct uploads
 
@@ -725,7 +799,7 @@ Shrine.plugin :upload_endpoint
 # config/routes.rb (Rails)
 Rails.application.routes.draw do
   # ...
-  mount ImageUploader.upload_endpoint(:cache) => "/images/upload" # POST /images/upload
+  mount Shrine.upload_endpoint(:cache) => "/upload" # POST /upload
 end
 ```
 
@@ -835,7 +909,7 @@ resumable uploads from scratch, it includes a complete JavaScript example
 
 ## Backgrounding
 
-The [`backgrounding`][backgrounding plugin] allows you to move file promotion
+The [`backgrounding`][backgrounding plugin] plugin allows you to move file promotion
 and deletion into a background job, using the backgrounding library [of your
 choice][Backgrounding Libraries]:
 
@@ -852,7 +926,7 @@ end
 class PromoteJob
   include Sidekiq::Worker
 
-  def perform(attacher_class, record_class, record.id, name, file_data)
+  def perform(attacher_class, record_class, record_id, name, file_data)
     attacher_class = Object.const_get(attacher_class)
     record         = Object.const_get(record_class).find(record_id) # if using Active Record
 
@@ -896,6 +970,8 @@ s3 = Shrine.storages[:cache]
 s3.clear! { |object| object.last_modified < Time.now - 7*24*60*60 } # delete files older than 1 week
 ```
 
+For S3, it may be easier and cheaper to use [S3 bucket lifecycle expiration rules](http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html)  instead.
+
 ## Logging
 
 The [`instrumentation`][instrumentation plugin] plugin sends and logs events for
@@ -946,7 +1022,6 @@ In tests you might want to tell Shrine to log only warnings:
 Shrine.logger.level = Logger::WARN
 ```
 
-[Advantages of Shrine]: https://shrinerb.com/docs/advantages
 [Creating Plugins]: https://shrinerb.com/docs/creating-plugins
 [Creating Storages]: https://shrinerb.com/docs/creating-storages
 [Direct Uploads to S3]: https://shrinerb.com/docs/direct-s3
@@ -957,24 +1032,19 @@ Shrine.logger.level = Logger::WARN
 [Using Attacher]: https://shrinerb.com/docs/attacher
 [FileSystem]: https://shrinerb.com/docs/storage/file-system
 [S3]: https://shrinerb.com/docs/storage/s3
+[Memory]: https://shrinerb.com/docs/storage/memory
+[Testing with Shrine]: https://shrinerb.com/docs/testing
 [`Shrine::UploadedFile`]: https://shrinerb.com/rdoc/classes/Shrine/UploadedFile/InstanceMethods.html
 
 [attacher]: #attacher
 [attachment]: #attaching
-[backgrounding]: #backgrounding
 [direct uploads]: #direct-uploads
 [io abstraction]: #io-abstraction
 [location]: #location
 [metadata]: #metadata
-[up front]: #processing-up-front
-[on-the-fly]: #processing-on-the-fly
-[plugin system]: #plugin-system
-[simple upload]: #simple-direct-upload
 [presigned upload]: #presigned-direct-upload
-[resumable upload]: #resumable-direct-upload
 [storage]: #storage
 [uploaded file]: #uploaded-file
-[uploading]: #uploading
 [uploader]: #uploader
 [validation]: #validation
 
@@ -1042,3 +1112,4 @@ Shrine.logger.level = Logger::WARN
 [storages]: https://shrinerb.com/docs/external/extensions#storages
 [plugins]: https://shrinerb.com/plugins
 [external plugins]: https://shrinerb.com/docs/external/extensions#plugins
+[gin index]: https://www.postgresql.org/docs/current/datatype-json.html#JSON-INDEXING