shrine 3.0.0.beta2 → 3.0.0.beta3

data/doc/plugins/derivation_endpoint.md

@@ -58,7 +58,7 @@ apply to an attached file. For example, we can generate image thumbnails using
 the [ImageProcessing] gem:
 
 ```rb
-gem "image_processing", "~> 1.2"
+gem "image_processing", "~> 1.8"
 ```
 ```rb
 require "image_processing/mini_magick"
@@ -117,13 +117,12 @@ derivation :thumbnail do |file, arg1, arg2, ...|
 
   # ... do processing ...
 
-  # return result as a File/Tempfile object or String/Pathname path
+  # return result as a File or Tempfile object
 end
 ```
 
-The derivation block is expected to return the processed file is a
-`File`/`Tempfile` object or a `String`/`Pathname` path. The resulting file is
-then rendered in the HTTP response.
+The derivation block is expected to return the processed file as a `File` or
+`Tempfile` object. The resulting file is then rendered in the HTTP response.
 
 ### Performance
 

data/doc/plugins/derivatives.md

@@ -5,13 +5,14 @@ the main attached file. The processed file data will be saved together with the
 main attachment data in the same record attribute.
 
 ```rb
-plugin :derivatives
+Shrine.plugin :derivatives
 ```
 
 ## Contents
 
 * [API overview](#api-overview)
 * [Creating derivatives](#creating-derivatives)
+  - [Naming processors](#naming-processors)
   - [Derivatives storage](#derivatives-storage)
   - [Nesting derivatives](#nesting-derivatives)
 * [Retrieving derivatives](#retrieving-derivatives)
@@ -57,21 +58,19 @@ Here is an example of generating image thumbnails:
 
 ```rb
 # Gemfile
-gem "image_processing", "~> 1.2"
+gem "image_processing", "~> 1.8"
 ```
 ```rb
 require "image_processing/mini_magick"
 
 class ImageUploader < Shrine
-  plugin :derivatives
-
-  Attacher.derivatives_processor :thumbnails do |original|
-    processor = ImageProcessing::MiniMagick.source(original)
+  Attacher.derivatives_processor do |original|
+    magick = ImageProcessing::MiniMagick.source(original)
 
     {
-      small:  processor.resize_to_limit!(300, 300),
-      medium: processor.resize_to_limit!(500, 500),
-      large:  processor.resize_to_limit!(800, 800),
+      small:  magick.resize_to_limit!(300, 300),
+      medium: magick.resize_to_limit!(500, 500),
+      large:  magick.resize_to_limit!(800, 800),
     }
   end
 end
@@ -82,20 +81,20 @@ class Photo < Model(:image_data)
 end
 ```
 ```rb
-photo.image #=> #<Shrine::UploadedFile @id="original.jpg" @storage_key=:store ...>
-photo.image_derivatives #=> {}
+photo = Photo.new(image: file)
+photo.image_derivatives! # calls derivatives processor and uploads results
+photo.save
+```
 
-photo.image_derivatives!(:thumbnails) # calls registered processor and uploads results
-photo.image_derivatives #=>
-# {
-#   small:  #<Shrine::UploadedFile @id="small.jpg" @storage_key=:store ...>,
-#   medium: #<Shrine::UploadedFile @id="medium.jpg" @storage_key=:store ...>,
-#   large:  #<Shrine::UploadedFile @id="large.jpg" @storage_key=:store ...>,
-# }
+If you're allowing the attached file to be updated later on, in your update
+route make sure to create derivatives for new attachments:
+
+```rb
+photo.image_derivatives! if photo.image_changed?
 ```
 
-The derivatives data is stored in the `#<name>_data` record attribute alongside
-the main file data:
+Once derivatives have been created, their data is stored in the `#<name>_data`
+record attribute alongside the main file data:
 
 ```rb
 photo.image_data #=>
@@ -111,16 +110,23 @@ photo.image_data #=>
 # }
 ```
 
+You can then retrieve derivatives as follows:
+
+```rb
+photo.image(:large)           #=> #<Shrine::UploadedFile>
+photo.image(:large).url       #=> "https://s3.amazonaws.com/path/to/large.jpg"
+photo.image(:large).size      #=> 43843
+photo.image(:large).mime_type #=> "image/jpeg"
+```
+
 The `#<name>_derivatives!` model method delegates to
 `Attacher#create_derivatives`, which you can use if you're using
 `Shrine::Attacher` directly:
 
 ```rb
-attacher.file #=> #<Shrine::UploadedFile @id="original.jpg" @storage_key=:store ...>
-attacher.derivatives #=> {}
-
-attacher.create_derivatives(:thumbnails) # calls registered processor and uploads results
-attacher.derivatives #=>
+attacher.file               #=> #<Shrine::UploadedFile @id="original.jpg" @storage_key=:store ...>
+attacher.create_derivatives # calls registered processor and uploads results
+attacher.derivatives        #=>
 # {
 #   small:  #<Shrine::UploadedFile @id="small.jpg" @storage_key=:store ...>,
 #   medium: #<Shrine::UploadedFile @id="medium.jpg" @storage_key=:store ...>,
@@ -130,14 +136,39 @@ attacher.derivatives #=>
 
 By default, the `Attacher#create_derivatives` method downloads the attached
 file, calls the processor, uploads results to attacher's permanent storage, and
-saves uploaded files on the attacher.
-
-Any additional arguments are forwarded to
+saves uploaded files on the attacher. Any additional arguments are forwarded to
 [`Attacher#process_derivatives`](#processing-derivatives):
 
 ```rb
-attacher.create_derivatives(:thumbnails, different_source) # pass a different source file
-attacher.create_derivatives(:thumbnails, foo: "bar")       # pass custom options to the processor
+attacher.create_derivatives(different_source) # pass a different source file
+attacher.create_derivatives(foo: "bar")       # pass custom options to the processor
+```
+
+### Naming processors
+
+If you want to have multiple processors for an uploader, you can assign each
+processor a name. Then when creating derivatives you can specify the name of
+the desired processor.
+
+```rb
+class ImageUploader < Shrine
+  Attacher.derivatives_processor :thumbnails do |original|
+    # ...
+  end
+
+  Attacher.derivatives_processor :crop do |original|
+    # ...
+  end
+
+  # ...
+end
+```
+```rb
+# ...
+photo.image_derivatives!(:thumbnails)
+# or
+attacher.create_derivatives(:thumbnails)
+# ...
 ```
 
 ### Derivatives storage
@@ -244,7 +275,7 @@ photo.image_derivatives #=> { thumbnail: { small: ..., medium: ..., large: ... }
 
 photo.image_derivatives.dig(:thumbnail, :small) #=> #<Shrine::UploadedFile>
 photo.image_derivatives(:thumbnail, :small)     #=> #<Shrine::UploadedFile>
-photo.image(:thumbnails :small)                 #=> #<Shrine::UploadedFile>
+photo.image(:thumbnails, :small)                #=> #<Shrine::UploadedFile>
 ```
 
 When using `Shrine::Attacher` directly, you can retrieve derivatives using
@@ -288,7 +319,7 @@ You can use the [`default_url`][default_url] plugin to set up URL fallbacks:
 
 ```rb
 Attacher.default_url do |derivative: nil, **|
-  "https://fallbacks.com/#{derivative}.jpg" if derivative
+  "https://my-app.com/fallbacks/#{derivative}.jpg" if derivative
 end
 ```
 ```rb

data/doc/plugins/download_endpoint.md

@@ -5,11 +5,13 @@ downloading uploaded files from specified storages. This can be useful when
 files from your storage isn't accessible over URL (e.g. database storages) or
 if you want to authenticate your downloads.
 
+## Global Endpoint 
+
 You can configure the plugin with the path prefix which the endpoint will be
 mounted on.
 
 ```rb
-plugin :download_endpoint, prefix: "attachments"
+Shrine.plugin :download_endpoint, prefix: "attachments"
 ```
 
 The plugin adds a `Shrine.download_endpoint` method which returns a Rack
@@ -30,6 +32,57 @@ Links to the download endpoint are generated by calling
 ```rb
 uploaded_file.download_url #=> "/attachments/eyJpZCI6ImFkdzlyeTM..."
 ```
+## Endpoint via Uploader
+
+You can also configure the plugin in the uploader directly - just make sure to mount it via your Uploader-class.
+
+```rb
+class ImageUploader  < Shrine
+  plugin :download_endpoint, prefix: "images"
+end
+```
+
+```rb
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  # ...
+  mount ImageUploader.download_endpoint => "/images"
+end
+```
+
+*Hint: For shrine versions 2.x -> ensure that you don't include the plugin twice (globally and in your uploader class - see #408)*
+
+## Calling from a controller
+
+If you want to run additional code around the download (such as authentication),
+mounting the download endpoint in your router might be limiting. You can instead
+create a custom controller action and handle download requests there using
+`Shrine.download_response`:
+
+```rb
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  # ...
+  get "/attachments/*rest", to: "downloads#image"
+end
+```
+```rb
+# app/controllers/downloads_controller.rb (Rails)
+class DownloadsController < ApplicationController
+  def image
+    # ... we can perform authentication here ...
+    set_rack_response ImageUploader.download_response(request.env)
+  end
+
+  private
+
+  def set_rack_response((status, headers, body))
+    self.status = status
+    self.headers.merge!(headers)
+    self.response_body = body
+  end
+end
+```
 
 ## Host
 

data/doc/plugins/entity.md

@@ -248,5 +248,6 @@ By default, attachment data is serialized into JSON using the `JSON` standard
 library. If you want to change how data is serialized, see the
 [`column`][column serializer] plugin docs.
 
+[column]: /doc/plugins/column.md#readme
 [entity]: /lib/shrine/plugins/entity.rb
 [column serializer]: /doc/plugins/column.md#serializer

data/doc/plugins/form_assign.md

@@ -0,0 +1,53 @@
+# Form Assign
+
+The [`form_assign`][form_assign] plugin allows attaching file from form params
+without a form object.
+
+```rb
+plugin :form_assign
+```
+
+The `Attacher#form_assign` method will detect the file param and assign it to
+the attacher:
+
+```rb
+attacher = photo.image_attacher
+attacher.form_assign("image" => file, "title" => "...", "description" => "...")
+attacher.file #=> #<Shrine::UploadedFile>
+```
+
+It works with `remote_url`, `data_uri`, and `remove_attachment` plugins:
+
+```rb
+# remote_url plugin
+attacher.form_assign("image_remote_url" => "https://example.com/...")
+attacher.file #=> #<Shrine::UploadedFile>
+```
+```rb
+# data_uri plugin
+attacher.form_assign("image_data_uri" => "data:image/jpeg;base64,...")
+attacher.file #=> #<Shrine::UploadedFile>
+```
+```rb
+# remove_attachment plugin
+attacher.form_assign("remove_image" => "1")
+attacher.file #=> nil
+```
+
+The return value is a hash with form params, with file param replaced with
+cached file data, which can later be assigned again to the record.
+
+```rb
+attacher.form_assign("image" => file, "title" => "...", "description" => "...")
+#=> { :image => '{"id":"...","storage":"...","metadata":"..."}', "title" => "...", "description" => "..." }
+```
+
+You can also have attached file data returned as the `<name>_data` attribute,
+suitable for persisting.
+
+```rb
+attacher.form_assign({ "image" => image, ... }, result: :attributes)
+#=> { :image_data => '{"id":"...","storage":"...","metadata":"..."}', "title" => "...", "description" => "..." }
+```
+
+[form_assign]: /lib/shrine/plugins/form_assign.rb

data/doc/plugins/mirroring.md

@@ -12,8 +12,16 @@ With the above setup, any upload and delete to `:store` will be replicated to
 `:other_store`.
 
 ```rb
-uploaded_file = Shrine.upload(io, :store) # uploads to :store and :other_store
-uploaded_file.delete                      # deletes from :store and :other_store
+file = Shrine.upload(io, :store) # uploads to :store and :other_store
+file.delete                      # deletes from :store and :other_store
+```
+
+You can skip mirroring for a specific upload/delete call by passing `mirror:
+false`:
+
+```rb
+file = Shrine.upload(io, :store, mirror: false) # skips mirroring
+file.delete(mirror: false)                      # skips mirroring
 ```
 
 ## Multiple storages
@@ -40,42 +48,43 @@ Shrine.plugin :mirroring, mirror: { ... }, delete: false
 You can have mirroring performed in a background job:
 
 ```rb
-Shrine.mirror_upload do |uploaded_file|
-  MirrorUploadJob.perform_async(uploaded_file.shrine_class, uploaded_file.data)
+Shrine.mirror_upload_block do |file|
+  MirrorUploadJob.perform_later(file.shrine_class, file.data)
 end
 
-Shrine.mirror_delete do |uploaded_file|
-  MirrorDeleteJob.perform_async(uploaded_file.shrine_class, uploaded_file.data)
+Shrine.mirror_delete_block do |file|
+  MirrorDeleteJob.perform_later(file.shrine_class, file.data)
 end
 ```
 ```rb
-class MirrorUploadJob
-  include Sidekiq::Worker
+class MirrorUploadJob < ActiveJob::Base
   def perform(shrine_class, file_data)
-    uploaded_file = Object.const_get(shrine_class).uploaded_file(file_data)
-    uploaded_file.mirror_upload
+    file = shrine_class.uploaded_file(file_data)
+    file.mirror_upload
   end
 end
 ```
 ```rb
-class MirrorDeleteJob
-  include Sidekiq::Worker
+class MirrorDeleteJob < ActiveJob::Base
   def perform(shrine_class, file_data)
-    uploaded_file = Object.const_get(shrine_class).uploaded_file(file_data)
-    uploaded_file.mirror_delete
+    file = shrine_class.uploaded_file(file_data)
+    file.mirror_delete
   end
 end
 ```
 
 ## API
 
-You can mirror manually via `UploadedFile#mirror_upload` and
-`UploadedFile#mirror_delete`:
+You can disable automatic mirroring and perform mirroring manually:
 
 ```rb
 # disable automatic mirroring of uploads and deletes
 Shrine.plugin :mirroring, mirror: { ... }, upload: false, delete: false
 ```
+
+To perform mirroring, you can call `UploadedFile#mirror_upload` and
+`UploadedFile#mirror_delete`:
+
 ```rb
 file = Shrine.upload(io, :store) # upload to :store
 file.mirror_upload               # upload to :other_store
@@ -84,4 +93,16 @@ file.delete                      # delete from :store
 file.mirror_delete               # delete from :other_store
 ```
 
+If you've set up backgrounding, you can use
+`UploadedFile#mirror_upload_background` and
+`UploadedFile#mirror_delete_background` to call the background block instead:
+
+```rb
+file = Shrine.upload(io, :store) # upload to :store
+file.mirror_upload_background    # spawn mirror upload background job
+
+file.delete                      # delete from :store
+file.mirror_delete_background    # spawn mirror delete background job
+```
+
 [mirroring]: /lib/shrine/plugins/mirroring.rb

data/doc/plugins/multi_cache.md

@@ -0,0 +1,22 @@
+# Multi Cache
+
+The [`multi_cache`][multi_cache] plugin allows an attacher to accept files from
+additional temporary storages.
+
+```rb
+Shrine.storages = { cache: ..., cache_one: ..., cache_two: ..., store: ... }
+
+Shrine.plugin :multi_cache, additional_cache: [:cache_one, :cache_two]
+```
+```rb
+photo.image = { "id" => "...", "storage" => "cache", "metadata" => { ... } }
+photo.image.storage_key #=> :cache
+# or
+photo.image = { "id" => "...", "storage" => "cache_one", "metadata" => { ... } }
+photo.image.storage_key #=> :cache_one
+# or
+photo.image = { "id" => "...", "storage" => "cache_two", "metadata" => { ... } }
+photo.image.storage_key #=> :cache_two
+```
+
+[multi_cache]: /lib/shrine/plugins/multi_cache.rb

data/doc/plugins/presign_endpoint.md

@@ -60,7 +60,7 @@ create a custom controller action and handle presign requests there using
 # config/routes.rb (Rails)
 Rails.application.routes.draw do
   # ...
-  post "/images/presign", to: "presigns#image"
+  get "/images/presign", to: "presigns#image"
 end
 ```
 ```rb