shrine 2.1.1 → 2.2.0

data/doc/carrierwave.md

@@ -41,22 +41,21 @@ own options that are specific to them.
 
 ### Processing
 
-In Shrine processing is done instance-level in the `#process` method, and can
-be specified for each phase. You can return a single processed file or a hash of
-versions (with the `versions` plugin):
+In Shrine processing is defined and performed on the instance-level, which
+gives a lot of flexibility. You can return a single processed file or a hash of
+versions:
 
 ```rb
 require "image_processing/mini_magick" # part of the "image_processing" gem
 
 class ImageUploader < Shrine
   include ImageProcessing::MiniMagick
+  plugin :processing
   plugin :versions
 
-  def process(io, context)
-    if context[:phase] == :store
-      thumb = resize_to_limit(io.download, 300, 300)
-      {original: io, thumb: thumb}
-    end
+  process(:store) do |io, context|
+    thumbnail = resize_to_limit(io.download, 300, 300)
+    {original: io, thumbnail: thumbnail}
   end
 end
 ```
@@ -496,23 +495,13 @@ them to validation errors.
 
 #### `validate_processing`, `ignore_processing_errors`
 
-Shrine doesn't offer any built-in ways of rescuing processing errors, because
-it completely depends on how you do your processing. You can easily add your
-own rescuing:
-
-```rb
-class ImageUploader < Shrine
-  def process(io, context)
-    # processing
-  rescue SomeProcessingError
-    # handling
-  end
-end
-```
+In Shrine processing is performed *after* validations, and typically
+asynchronously in a background job, so it is expected that you validate files
+before processing.
 
 #### `enable_processing`
 
-You can just do conditionals inside if `Shrine#process`.
+You can just add conditionals in processing code.
 
 #### `ensure_multipart_form`
 

data/doc/changing_location.md

@@ -20,12 +20,12 @@ Shrine.plugin :delete_promoted
 
 User.paged_each do |user|
   attacher = user.avatar_attacher
-  attacher.promote(phase: :migrate) if attacher.stored?
-  # use `attacher._promote(phase: :migrate)` if you want promoting to be backgrounded
+  attacher.promote(action: :migrate) if attacher.stored?
+  # use `attacher._promote(action: :migrate)` if you want promoting to be backgrounded
 end
 ```
 
-The `:phase` is not mandatory, it's just for better introspection when
+The `:action` is not mandatory, it's just for better introspection when
 monitoring background jobs and logs.
 
 Now all your existing attachments should be happily living on new locations.

data/doc/creating_storages.md

@@ -3,32 +3,25 @@
 ## Essentials
 
 Shrine ships with the FileSystem and S3 storages, but it's also easy to create
-your own. A storage is a class which has at least the following methods:
+your own. A storage is a class which needs to implement to the following
+methods:
 
 ```rb
 class Shrine
   module Storage
     class MyStorage
-      def initialize(*args)
-        # initializing logic
-      end
-
-      def upload(io, id, shrine_metadata: {}, **upload_options)
+      def upload(io, id, **options)
         # uploads `io` to the location `id`
       end
 
-      def download(id)
-        # downloads the file from the storage
+      def url(id, **options)
+        # URL to the remote file, accepts options for customizing the URL
       end
 
       def open(id)
         # returns the remote file as an IO-like object
       end
 
-      def read(id)
-        # returns the file contents as a string
-      end
-
       def exists?(id)
         # checks if the file exists on the storage
       end
@@ -36,14 +29,6 @@ class Shrine
       def delete(id)
         # deletes the file from the storage
       end
-
-      def url(id, **options)
-        # URL to the remote file, accepts options for customizing the URL
-      end
-
-      def clear!
-        # deletes all the files in the storage
-      end
     end
   end
 end
@@ -76,6 +61,28 @@ def upload(io, id, shrine_metadata: {}, **upload_options)
 end
 ```
 
+## Download
+
+Shrine automatically downloads the file to a Tempfile using `#open`. However,
+if you would like to implement your own downloading, you can define `#download`
+and Shrine will use that instead:
+
+```rb
+class Shrine
+  module Storage
+    class MyStorage
+      # ...
+
+      def download(id)
+        # download the file to a Tempfile
+      end
+
+      # ...
+    end
+  end
+end
+```
+
 ## Update
 
 If your storage supports updating data of existing files (e.g. some metadata),
@@ -108,7 +115,7 @@ class Shrine
     class MyStorage
       # ...
 
-      def move(io, id, shrine_metadata: {}, **upload_options)
+      def move(io, id, **upload_options)
         # does the moving of the `io` to the location `id`
       end
 
@@ -144,6 +151,26 @@ class Shrine
 end
 ```
 
+## Clearing
+
+While this method is not used by Shrine, it is good to give users the
+possibility to delete all files in a storage, and the conventional name for
+this method is `#clear!`:
+
+class Shrine
+  module Strorage
+    class MyStorage
+      # ...
+
+      def clear!
+        # deletes all files in the storage
+      end
+
+      # ...
+    end
+  end
+end
+
 ## Linter
 
 To check that your storage implements all these methods correctly, you can use

data/doc/direct_s3.md

@@ -49,7 +49,7 @@ Shrine's JSON representation of an uploaded file looks like this:
 The `id`, `storage` fields are optional, while the `metadata` values are
 optional (`metadata.size` is only required to later upload that file to a
 non-S3 storage). After uploading the file to S3, you need to construct this
-JSON and assign it to the hidden attachment field in the form.
+JSON, and then you can assign it to the hidden attachment field in the form.
 
 ## Strategy A (dynamic)
 
@@ -57,22 +57,26 @@ JSON and assign it to the hidden attachment field in the form.
 * Single or multiple file uploads
 * Some JavaScript needed
 
-You can configure the `direct_upload` plugin to expose the presign route, and
-mount the endpoint:
+When the user selects the file, we dynamically request 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:
 
 ```rb
-plugin :direct_upload, presign: true
+plugin :direct_upload
 ```
 ```rb
 Rails.application.routes.draw do
-  mount ImageUploader::UploadEndpoint => "attachments/image"
+  mount ImageUploader::UploadEndpoint => "/image"
 end
 ```
 
-This gives the endpoint a `GET /:storage/presign` route, which generates a
-presign object and returns it as JSON:
+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:
 
 ```rb
+# GET /images/cache/presign
 {
   "url" => "https://my-bucket.s3-eu-west-1.amazonaws.com",
   "fields" => {
@@ -86,30 +90,27 @@ presign object and returns it as JSON:
 }
 ```
 
-When the user attaches a file, you should first request the presign object from
-the direct endpoint, and then upload the file to the given URL with the given
-fields. For uploading to S3 you can use any of the great JavaScript libraries
-out there, [jQuery-File-Upload] for example.
-
-After the upload you create a JSON representation of the uploaded file and
-usually write it to the hidden attachment field in the form:
+For uploading to S3 you'll probably want to use a JavaScript file upload
+library like [jQuery-File-Upload] or [Dropzone]. After the upload you should
+create a JSON representation of the uploaded file, which you can write to
+the hidden attachment field:
 
 ```js
 var image = {
-  id: key.match(/cache\/(.+)/)[1], # we have to remove the prefix part
+  id: key.match(/cache\/(.+)/)[1], // we have to remove the prefix part
   storage: 'cache',
   metadata: {
     size:      data.files[0].size,
-    filename:  data.files[0].name,
-    mime_type: data.files[0].type,
+    filename:  data.files[0].name.match(/[^\/\\]+$/)[0], // IE returns full path
+    mime_type: data.files[0].type
   }
 }
 
-$('input[type=file]').prev().value(JSON.stringify(image))
+$('input[type=file]').prev().val(JSON.stringify(image))
 ```
 
 It's generally a good idea to disable the submit button until the file is
-uploaded, as well as display a progress bar. See the [example app] for the
+uploaded, as well as display a progress bar. See the [example app] for a
 working implementation of multiple direct S3 uploads.
 
 ## Strategy B (static)
@@ -118,10 +119,11 @@ working implementation of multiple direct S3 uploads.
 * Only for single uploads
 * No JavaScript needed
 
-An alternative to the previous strategy is generating a file upload form that
-submits synchronously to S3, and then redirects back to your application.
-For that you can use `Shrine::Storage::S3#presign`, which returns a
-[`Aws::S3::PresignedPost`] object, which has `#url` and `#fields`:
+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:
 
 ```erb
 <% presign = Shrine.storages[:cache].presign(SecureRandom.hex, success_action_redirect: new_album_url) %>
@@ -135,8 +137,9 @@ For that you can use `Shrine::Storage::S3#presign`, which returns a
 </form>
 ```
 
-After the file is submitted, S3 will redirect to the URL you specified and
-include the object key as a query param:
+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:
 
 ```erb
 <%
@@ -153,10 +156,6 @@ include the object key as a query param:
 </form>
 ```
 
-Notice that we needed to fetch and assign the size of the uploaded file. This
-is because this hash is later transformed into an IO which requires `#size`
-to be non-nil (and it is read from the metadata field).
-
 ## Metadata
 
 With direct uploads any metadata has to be extracted on the client, since
@@ -170,6 +169,13 @@ load the restore_cached_data plugin.
 plugin :restore_cached_data
 ```
 
+## Clearing cache
+
+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.
+
 ## Eventual consistency
 
 When uploading objects to Amazon S3, sometimes they may not be available
@@ -193,6 +199,7 @@ backgrounding library to perform the job with a delay:
 
 ```rb
 Shrine.plugin :backgrounding
+
 Shrine::Attacher.promote do |data|
   PromoteJob.perform_in(60, data) # tells a Sidekiq worker to perform in 1 minute
 end
@@ -200,5 +207,6 @@ end
 
 [`Aws::S3::PresignedPost`]: http://docs.aws.amazon.com/sdkforruby/api/Aws/S3/Bucket.html#presigned_post-instance_method
 [example app]: https://github.com/janko-m/shrine-example
+[Dropzone]: https://github.com/enyo/dropzone
 [jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
 [Amazon S3 Data Consistency Model]: http://docs.aws.amazon.com/AmazonS3/latest/dev/Introduction.html#ConsistencyMode

data/doc/paperclip.md

@@ -46,23 +46,21 @@ uploaded_file.original_filename #=> "nature.jpg"
 
 ### Processing
 
-In Shrine you do processing inside the uploader's `#process` method, and unlike
-Paperclip, the processing is done on instance-level, so you have maximum
-flexibility. In Shrine you generate versions by simply returning a hash, and
-also loading the `versions` plugin to make your uploader recognize versions:
+Unlike Paperclip, in Shrine you define and perform processing on
+instance-level, which gives a lot of flexibility. As the result you can return
+a single file or a hash of versions:
 
 ```rb
 require "image_processing/mini_magick" # part of the "image_processing" gem
 
 class ImageUploader < Shrine
   include ImageProcessing::MiniMagick
+  plugin :processing
   plugin :versions
 
-  def process(io, context)
-    if context[:phase] == :store
-      thumb = resize_to_limit(io.download, 300, 300)
-      {original: io, thumb: thumb}
-    end
+  process(:store) do |io, context|
+    thumbnail = resize_to_limit(io.download, 300, 300)
+    {original: io, thumbnail: thumbnail}
   end
 end
 ```

data/doc/refile.md

@@ -107,20 +107,18 @@ on upload (like CarrierWave and Paperclip). However, there are storages which
 you can use which support on-the-fly processing, like [shrine-cloudinary] or
 [shrine-imgix].
 
-In Shrine you do processing by overriding the `#process` method on your
-uploader (for images you can use the [image_processing] gem):
+Processing is defined and performed on the instance level, and the result of
+can be a single file or a hash of versions:
 
 ```rb
 require "image_processing/mini_magick"
 
 class ImageUploader < Shrine
   include ImageProcessing::MiniMagick
+  plugin :processing
 
-  def process(io, context)
-    case context[:phase]
-    when :store
-      resize_to_fit!(io.download, 700, 700)
-    end
+  process(:store) do |io, context|
+    resize_to_fit!(io.download, 700, 700)
   end
 end
 ```
@@ -292,12 +290,11 @@ Shrine.plugin :logging
 
 #### `.processors`, `.processor`
 
-In Shrine processing is done by overriding the `#process` method in your
-uploader:
-
 ```rb
 class MyUploader < Shrine
-  def process(io, context)
+  plugin :processing
+
+  process(:store) do |io, context|
     # ...
   end
 end

data/doc/regenerating_versions.md

@@ -15,14 +15,11 @@ versions:
 
 ```rb
 class ImageUploader < Shrine
-  plugin :versions
-
-  def process(io, context)
-    case context[:phase]
-    when :store
-      thumb = process_thumb(io.download)
-      {original: io, thumb: thumb}
-    end
+  # ...
+
+  process(:store) do |io, context|
+    thumbnail = process_thumbnail(io.download)
+    {original: io, thumbnail: thumbnail}
   end
 end
 ```
@@ -75,15 +72,12 @@ update your processing code to generate it, and deploy it:
 
 ```rb
 class ImageUploader < Shrine
-  plugin :versions
-
-  def process(io, context)
-    case context[:phase]
-    when :store
-      # ...
-      new = some_processing(io.download, *args)
-      {small: small, medium: medium, new: new} # we generate the ":new" version
-    end
+  # ...
+
+  process(:store) do |io, context|
+    # ...
+    new = some_processing(io.download, *args)
+    {small: small, medium: medium, new: new} # we generate the ":new" version
   end
 end
 ```
@@ -119,8 +113,9 @@ old_versions = []
 User.paged_each do |user|
   attacher, attachment = user.avatar_attacher, user.avatar
   if attacher.stored? && attachment[:old_version]
-    old_versions << attachment.delete(:old_version)
-    attacher.swap(attachment)
+    old_version = attachment.delete(:old_version)
+    swapped = attacher.swap(attachment)
+    old_versions << old_version if swapped
   end
 end