shrine 2.6.1 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0474d268473ec2255e7710efdc424ea7abcaa129
-  data.tar.gz: 75489de0c246f813fd48fd707e0f9e1355de7f80
+  metadata.gz: 2156db4347bf54e372dd3865a117b38e14638419
+  data.tar.gz: 6fc29c5c7837f3355240b85ff313579b35953a62
 SHA512:
-  metadata.gz: 65de646144983c25c985aaca273c503bff2391c53f3267cae93d4d535ad398ffffb6833f6b3f6d12fb1e8d2fba04aa80c395389c351c808a36d51ea39fe797e9
-  data.tar.gz: d4ebe688c1f33850f0a91df74528b3761aa0e842f9d97aa4b64ab6d9b5bfd3d6f4b1c62f3a32b488b2f2e109cfe009b90c2cc6987c248f9420df77869284fec6
+  metadata.gz: 634e5d0bec22737521cef1b2b7eab82871e3be1d13988a171a6686e3f3885d2514531ede958ca757dc9a84c526b049f9d2bb5bccb4119f4c8c090a1272ba88c7
+  data.tar.gz: bfa00d5f2ae6ca28e66cb0e26872cfb127fe00e13b12bf0eddd9965b295a5ea4b7418bf1d74f4e3deb059aa8a66d3262b120f968b369d71f675a3c5b9d265c4f

data/README.md

@@ -74,11 +74,17 @@ uploaded file in case of validation errors and [direct uploads].
   <input name="photo[image]" type="file">
 </form>
 
-<!-- Rails: -->
+<!-- ActionView::Helpers::FormHelper -->
 <%= form_for @photo do |f| %>
   <%= f.hidden_field :image, value: @photo.cached_image_data %>
   <%= f.file_field :image %>
 <% end %>
+
+<!-- SimpleForm -->
+<%= simple_form_for @photo do |f| %>
+  <%= f.input :image, as: :hidden, input_html: {value: @photo.cached_image_data} %>
+  <%= f.input :image, as: :file %>
+<% end %>
 ```
 
 Note that the file field needs to go *after* the hidden field, so that
@@ -113,7 +119,7 @@ interface. Storages are configured directly and registered under a name in
 
 ```rb
 # Gemfile
-gem "aws-sdk", "~> 2.1" # for Amazon S3 storage
+gem "aws-sdk-s3", "~> 1.2" # for Amazon S3 storage
 ```
 ```rb
 require "shrine/storage/s3"
@@ -405,7 +411,7 @@ by default Shrine's "mime_type" is **not guaranteed** to hold the actual MIME
 type of the file.
 
 However, if you load the `determine_mime_type` plugin, that will make Shrine
-always extract the MIME type from **file content** .
+always extract the MIME type from **file content**.
 
 ```rb
 Shrine.plugin :determine_mime_type
@@ -680,6 +686,22 @@ class DocumentUploader < Shrine
 end
 ```
 
+Validations are inherited from superclasses, but you need to call them manually
+when defining more validations:
+
+```ruby
+class ApplicationUploader < Shrine
+  Attacher.validate { validate_max_size 5.megabytes }
+end
+
+class ImageUploader < ApplicationUploader
+  Attacher.validate do
+    super() # empty braces are required
+    validate_mime_type_inclusion %w[image/jpeg image/jpg image/png]
+  end
+end
+```
+
 ## Location
 
 Before Shrine uploads a file, it generates a random location for it. By default
@@ -721,37 +743,50 @@ uploader.upload(file, location: "some/specific/location.mp4")
 
 ## Direct uploads
 
-Shrine comes with a `direct_upload` plugin that can be used for client-side
-asynchronous uploads to your app or an external service like Amazon S3. It
-provides a [Roda] app which you can mount in your app:
+While having files uploaded on form submit is simplest to implement, it doesn't
+provide the best user experience, because the user doesn't know how long they
+need to wait for the file to get uploaded.
+
+To improve the user experience, the application can actually start uploading
+the file **asynchronously** already when it has been selected, and provide a
+progress bar. This way the user can estimate when the upload is going to
+finish, and they can continue filling in other fields in the form while the
+file is being uploaded.
+
+Shrine comes with the `upload_endpoint` plugin, which provides a Rack endpoint
+that accepts file uploads and forwards them to specified storage. We want to
+set it up to upload to *temporary* storage, because we're replacing the caching
+step in the default synchronous workflow.
 
 ```rb
-# Gemfile
-gem "roda"
-```
-```rb
-Shrine.plugin :direct_upload
+Shrine.plugin :upload_endpoint
 ```
 ```rb
 Rails.application.routes.draw do
-  mount ImageUploader::UploadEndpoint => "/images"
+  mount ImageUploader.upload_endpoint(:cache) => "/images/upload"
 end
 ```
 
-The above setup will provide the following endpoints:
+The above created a `POST /images/upload` endpoint. You can now use a
+client-side file upload library like [FineUploader], [Dropzone] or
+[jQuery-File-Upload] to upload files asynchronously to the `/images/upload`
+endpoint the moment they are selected. Once the file has been uploaded, the
+endpoint will return JSON data of the uploaded file, which the client can then
+write to a hidden attachment field, to be submitted instead of the raw file.
 
-* `POST /images/cache/upload` - for direct uploads to your app
-* `GET /images/cache/presign` - for direct uploads to external service (e.g. Amazon S3)
+Many popular storage services can accept file uploads directly from the client
+([Amazon S3], [Google Cloud Storage], [Microsoft Azure Storage] etc), which
+means you can avoid uploading files through your app. If you're using one of
+these storage services, you can use the `presign_endpoint` plugin to generate
+URL, fields, and headers that can be used to upload files directly to the
+storage service. The only difference from the `upload_endpoint` workflow is
+that the client has the extra step of fetching the request information before
+uploading the file.
 
-Now when the user selects a file, the client can immediately start uploading
-the file asynchronously using one of these endpoints. The JSON data of the
-uploaded file can then be written to the hidden attachment field, and submitted
-instead of the file. For JavaScript you can use generic file upload libraries
-like [jQuery-File-Upload], [Dropzone] or [FineUploader].
-
-See the [direct_upload] plugin documentation and [Direct Uploads to S3][direct uploads]
-guide for more details, as well as the [Roda][roda_demo] and
-[Rails][rails_demo] demo apps which implement multiple uploads directly to S3.
+See the [upload_endpoint] and [presign_endpoint] plugin documentations and
+[Direct Uploads to S3][direct uploads] guide for more details, as well as the
+[Roda][roda_demo] and [Rails][rails_demo] demo apps which implement multiple
+uploads directly to S3.
 
 ## Backgrounding
 
@@ -917,10 +952,14 @@ The gem is available as open source under the terms of the [MIT License].
 [Context]: https://github.com/janko-m/shrine#context
 [image_processing]: https://github.com/janko-m/image_processing
 [ffmpeg]: https://github.com/streamio/streamio-ffmpeg
-[jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
-[Dropzone]: https://github.com/enyo/dropzone
 [FineUploader]: https://github.com/FineUploader/fine-uploader
-[direct_upload]: http://shrinerb.com/rdoc/classes/Shrine/Plugins/DirectUpload.html
+[Dropzone]: https://github.com/enyo/dropzone
+[jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
+[Amazon S3]: https://aws.amazon.com/s3/
+[Google Cloud Storage]: https://cloud.google.com/storage/
+[Microsoft Azure Storage]: https://azure.microsoft.com/en-us/services/storage/
+[upload_endpoint]: http://shrinerb.com/rdoc/classes/Shrine/Plugins/UploadEndpoint.html
+[presign_endpoint]: http://shrinerb.com/rdoc/classes/Shrine/Plugins/PresignEndpoint.html
 [Cloudinary]: https://github.com/janko-m/shrine-cloudinary
 [Imgix]: https://github.com/janko-m/shrine-imgix
 [Uploadcare]: https://github.com/janko-m/shrine-uploadcare

data/doc/attacher.md

@@ -40,6 +40,14 @@ also tell it to use different temporary and permanent storage:
 ImageUploader::Attacher.new(photo, :image, cache: :other_cache, store: :other_store)
 ```
 
+Note that you can pass the `:cache` and `:store` options via `Attachment.new` too:
+
+```rb
+class Photo < Sequel::Model
+  include ImageUploader::Attachment.new(:image, cache: :other_cache, store: :other_store)
+end
+```
+
 The attacher will use the `<attachment>_data` attribute for storing information
 about the attachment.
 

data/doc/carrierwave.md

@@ -39,8 +39,8 @@ via [direct uploads]):
 
 ```rb
 Shrine.storages = {
-  cache: Shrine::Storages::S3.new(prefix: "cache", **s3_options),
-  store: Shrine::Storages::S3.new(prefix: "store", **s3_options),
+  cache: Shrine::Storage::S3.new(prefix: "cache", **s3_options),
+  store: Shrine::Storage::S3.new(prefix: "store", **s3_options),
 }
 ```
 

data/doc/creating_storages.md

@@ -87,11 +87,12 @@ end
 
 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 `direct_upload` plugin. The method should return an
+which will be used by the `presign_endpoint` plugin. The method should return an
 object which responds to
 
 * `#url` – returns the URL to which the file should be uploaded to
-* `#fields` – returns a hash of request parameters for the upload
+* `#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)
 
 ```rb
 class Shrine

data/doc/direct_s3.md

@@ -1,7 +1,8 @@
 # Direct Uploads to S3
 
-Shrine gives you the ability to upload files directly to Amazon S3, which is
-beneficial for several use cases:
+Shrine gives you the ability to upload files directly to Amazon S3 (or any
+other storage service that accepts direct uploads). Uploading directly to a
+storage service is beneficial for several reasons:
 
 * Accepting uploads is resource-intensive for the server, and delegating it to
   an external service makes scaling easier.
@@ -18,7 +19,7 @@ beneficial for several use cases:
   changes the location.
 
 * If your request workers have a timeout configured or you're using Heroku,
-  uploading a large files to S3 or any external service inside the
+  uploading large files to S3 or any external service inside the
   request-response lifecycle might not be able to finish before the request
   times out.
 
@@ -27,7 +28,7 @@ different prefixes (or even buckets):
 
 ```rb
 # Gemfile
-gem "aws-sdk", "~> 2.1"
+gem "aws-sdk-s3", "~> 1.2"
 ```
 ```rb
 require "shrine/storage/s3"
@@ -54,12 +55,12 @@ documentation on how to write a CORS file.
 
 http://docs.aws.amazon.com/AmazonS3/latest/dev/cors.html
 
-Note that it may take some time for the CORS settings to be applied, due to
-DNS propagation.
+Note that due to DNS propagation it may take some time for update of the CORS
+settings to be applied.
 
 ## File hash
 
-After direct S3 uploads we'll need to manually construct Shrine's
+After direct S3 uploads we'll need to manually construct Shrine's JSON
 representation of an uploaded file:
 
 ```rb
@@ -67,9 +68,9 @@ representation of an uploaded file:
   "id": "349234854924394", # requied
   "storage": "cache", # required
   "metadata": {
-    "size": 45461, # optional
+    "size": 45461, # optional, but recommended
     "filename": "foo.jpg", # optional
-    "mime_type": "image/jpeg", # optional
+    "mime_type": "image/jpeg" # optional
   }
 }
 ```
@@ -84,47 +85,50 @@ representation of an uploaded file:
 * Single or multiple file uploads
 * Some JavaScript needed
 
-When the user selects the file, we dynamically fetch the presign from the
-server, and use this information to start uploading the file to S3. The
-`direct_upload` plugin gives us this presign route, so we just need to mount it
-in our application:
+When the user selects a file in the form, on the client-side we asynchronously
+fetch the presign information from the server, and use this information to
+upload the file to S3. The `presign_endpoint` plugin gives us this presign
+route, so we just need to mount it in our application:
 
 ```rb
-# Gemfile
-gem "roda"
-```
-```rb
-plugin :direct_upload
+Shrine.plugin :presign_endpoint
 ```
 ```rb
 Rails.application.routes.draw do
-  mount ImageUploader::UploadEndpoint => "/images"
+  mount Shrine.presign_endpoint(:cache) => "/presign"
 end
 ```
 
-This gives your application a `GET /images/cache/presign` route, which
-returns the S3 URL which the file should be uploaded to, along with the
-necessary request parameters:
+The above will create a `GET /presign` route, which returns the S3 URL which
+the file should be uploaded to, along with the required POST parameters and
+request headers.
 
 ```rb
-# GET /images/cache/presign
+# GET /presign
 {
-  "url" => "https://my-bucket.s3-eu-west-1.amazonaws.com",
-  "fields" => {
-    "key" => "cache/b7d575850ba61b44c8a9ff889dfdb14d88cdc25f8dd121004c8",
-    "policy" => "eyJleHBpcmF0aW9uIjoiMjAxNS0QwMToxMToyOVoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJzaHJpbmUtdGVzdGluZyJ9LHsia2V5IjoiYjdkNTc1ODUwYmE2MWI0NGU3Y2M4YTliZmY4OGU5ZGZkYjE2NTQ0ZDk4OGNkYzI1ZjhkZDEyMTAwNGM4In0seyJ4LWFtei1jcmVkZW50aWFsIjoiQUtJQUlKRjU1VE1aWlk0NVVUNlEvMjAxNTEwMjQvZXUtd2VzdC0xL3MzL2F3czRfcmVxdWVzdCJ9LHsieC1hbXotYWxnb3JpdGhtIjoiQVdTNC1ITUFDLVNIQTI1NiJ9LHsieC1hbXotZGF0ZSI6IjIwMTUxMDI0VDAwMTEyOVoifV19",
-    "x-amz-credential" => "AKIAIJF55TMZYT6Q/20151024/eu-west-1/s3/aws4_request",
-    "x-amz-algorithm" => "AWS4-HMAC-SHA256",
-    "x-amz-date" => "20151024T001129Z",
-    "x-amz-signature" => "c1eb634f83f96b69bd675f535b3ff15ae184b102fcba51e4db5f4959b4ae26f4"
-  }
+  "url": "https://my-bucket.s3-eu-west-1.amazonaws.com",
+  "fields": {
+    "key": "cache/b7d575850ba61b44c8a9ff889dfdb14d88cdc25f8dd121004c8",
+    "policy": "eyJleHBpcmF0aW9uIjoiMjAxNS0QwMToxMToyOVoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJzaHJpbmUtdGVzdGluZyJ9LHsia2V5IjoiYjdkNTc1ODUwYmE2MWI0NGU3Y2M4YTliZmY4OGU5ZGZkYjE2NTQ0ZDk4OGNkYzI1ZjhkZDEyMTAwNGM4In0seyJ4LWFtei1jcmVkZW50aWFsIjoiQUtJQUlKRjU1VE1aWlk0NVVUNlEvMjAxNTEwMjQvZXUtd2VzdC0xL3MzL2F3czRfcmVxdWVzdCJ9LHsieC1hbXotYWxnb3JpdGhtIjoiQVdTNC1ITUFDLVNIQTI1NiJ9LHsieC1hbXotZGF0ZSI6IjIwMTUxMDI0VDAwMTEyOVoifV19",
+    "x-amz-credential": "AKIAIJF55TMZYT6Q/20151024/eu-west-1/s3/aws4_request",
+    "x-amz-algorithm": "AWS4-HMAC-SHA256",
+    "x-amz-date": "20151024T001129Z",
+    "x-amz-signature": "c1eb634f83f96b69bd675f535b3ff15ae184b102fcba51e4db5f4959b4ae26f4"
+  },
+  "headers": {}
 }
 ```
 
-For uploading to S3 you'll probably want to use a JavaScript file upload
-library like [jQuery-File-Upload], [Dropzone] or [FineUploader]. After the
-upload you should create a JSON representation of the uploaded file, which you
-can write to the hidden attachment field:
+You can now use a client-side file upload library like [FineUploader],
+[Dropzone] or [jQuery-File-Upload] to upload selected files directly to S3.
+When the user selects a file, the client can make a request to the presign
+endpoint, and use the returned request information to upload the selected file
+directly to S3.
+
+Once the file has been uploaded, you can generate a JSON representation of the
+uploaded file on the client-side, and write it to the hidden attachment field.
+The `id` field needs to be equal to the `key` presign field minus the storage
+`:prefix`.
 
 ```html
 <input type='hidden' name='photo[image]' value='{
@@ -138,8 +142,9 @@ can write to the hidden attachment field:
 }'>
 ```
 
-See the [demo app] for an example JavaScript implementation of multiple direct
-S3 uploads.
+This JSON string will now be submitted and assigned to the attachment attribute
+instead of the raw file. See the [demo app] for an example JavaScript
+implementation of multiple direct S3 uploads.
 
 ## Strategy B (static)
 
@@ -147,14 +152,17 @@ S3 uploads.
 * Only for single uploads
 * No JavaScript needed
 
-An alternative to the previous strategy is generating a file upload form
-immediately when the page is rendered, and then file upload can be either
-asynchronous, or synchronous with redirection. For generating the form we can
-use `Shrine::Storage::S3#presign`, which returns a [`Aws::S3::PresignedPost`]
-object, which has `#url` and `#fields` methods:
+An alternative to the previous strategy is to generate an S3 upload form on
+page render. The user can then select a file and submit it directly to S3. For
+generating the form we can use `Shrine::Storage::S3#presign`, which returns a
+[`Aws::S3::PresignedPost`] object with `#url` and `#fields` attributes:
 
 ```erb
-<% presign = Shrine.storages[:cache].presign(SecureRandom.hex, success_action_redirect: new_album_url) %>
+<%
+  presign = Shrine.storages[:cache].presign SecureRandom.hex,
+    success_action_redirect: new_album_url,
+    allow_any: ['utf8', 'authenticity_token']
+%>
 
 <form action="<%= presign.url %>" method="post" enctype="multipart/form-data">
   <input type="file" name="file">
@@ -165,9 +173,13 @@ object, which has `#url` and `#fields` methods:
 </form>
 ```
 
-If you're doing synchronous upload with redirection, the redirect URL will
-include the object key in the query parameters, which you can use to generate
-Shrine's uploaded file representation:
+Note the additional `success_action_redirect` option which tells S3 where to
+redirect to after the file has been uploaded. We also tell S3 to exclude the
+`utf8` and `authenticity_token` fields that the Rails form builder generates.
+
+Let's assume we specified the redirect URL to be a page which renders the form
+for a new record. S3 will include some information about the upload in form of
+GET parameters in the URL, out of which we only need the `key` parameter:
 
 ```erb
 <%
@@ -186,21 +198,24 @@ Shrine's uploaded file representation:
 
 ## Metadata
 
-With direct uploads any metadata has to be extracted on the client, since
-caching the file doesn't touch your application. When the cached file is stored,
-Shrine's default behaviour is to simply copy over cached file's metadata.
+With direct uploads any metadata has to be extracted on the client-side, since
+the file upload doesn't touch the application, so the Shrine uploader doesn't
+get a chance to extract the metadata. When directly uploaded file is promoted
+to permanent storage, Shrine's default behaviour is to just copy the received
+metadata.
 
 If you want to re-extract metadata on the server before file validation, you
 can load the `restore_cached_data`. That will make Shrine open the S3 file for
-reading, give it for metadata extraction, and then override the metadata
-received from the client with one extracted by Shrine.
+reading, pass it for metadata extraction, and then override the metadata
+received from the client with the extracted ones.
 
 ```rb
 plugin :restore_cached_data
 ```
 
 Note that if you don't need this metadata before file validation, and you would
-like to have it extracted in a background job, you can do the following trick:
+like to have it extracted in a background job, you can do that with the
+following trick:
 
 ```rb
 class MyUploader < Shrine
@@ -218,8 +233,7 @@ end
 
 Since directly uploaded files will stay in your temporary storage, you will
 want to periodically delete the old ones that were already promoted. Luckily,
-Amazon provides [a built-in solution](http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html)
-for that.
+Amazon provides [a built-in solution][object lifecycle] for that.
 
 ## Eventual consistency
 
@@ -250,9 +264,10 @@ Shrine::Attacher.promote do |data|
 end
 ```
 
-[`Aws::S3::PresignedPost`]: http://docs.aws.amazon.com/sdkforruby/api/Aws/S3/Bucket.html#presigned_post-instance_method
+[`Aws::S3::PresignedPost`]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Bucket.html#presigned_post-instance_method
 [demo app]: https://github.com/janko-m/shrine/tree/master/demo
 [Dropzone]: https://github.com/enyo/dropzone
 [jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
 [FineUploader]: https://github.com/FineUploader/fine-uploader
 [Amazon S3 Data Consistency Model]: http://docs.aws.amazon.com/AmazonS3/latest/dev/Introduction.html#ConsistencyMode
+[object lifecycle]: http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html

data/doc/multiple_files.md

@@ -89,8 +89,9 @@ to add the `multiple` attribute to the file field.
 
 You can then use a generic JavaScript file upload library like
 [jQuery-File-Upload], [Dropzone] or [FineUploader] to asynchronously upload
-each the selected files to your app or an external service. See the
-`direct_upload` plugin, and [Direct Uploads to S3] guide for more details.
+each of the selected files to your app or to an external service. See the
+`upload_endpoint` and `presign_endpoint` plugins, and [Direct Uploads to S3]
+guide for more details.
 
 After each upload finishes, you can generate a nested hash for the new
 associated record, and write the uploaded file JSON to the attachment field: