shrine 3.1.0 → 3.4.0

data/doc/plugins/upload_options.md

@@ -13,7 +13,7 @@ Keys are names of the registered storages, and values are either hashes or
 blocks.
 
 ```rb
-plugin :upload_options, store: -> (io, **options) do
+plugin :upload_options, store: -> (io, options) do
   if options[:derivative]
     { acl: "public-read" }
   else

data/doc/plugins/url_options.md

@@ -4,10 +4,10 @@ title: URL Options
 
 The [`url_options`][url_options] plugin allows you to specify
 URL options that will be applied by default for uploaded files of specified
-storages.
+storages. `url_options` are parameters specific to the storage service.
 
 ```rb
-plugin :url_options, store: { expires_in: 24*60*60 }
+plugin :url_options, store: { expires_in: 24*60*60 } # `expires_in` is a URL option for AWS S3
 ```
 
 You can also generate the default URL options dynamically by using a block,
@@ -15,8 +15,8 @@ which will receive the UploadedFile object along with any options that were
 passed to `UploadedFile#url`.
 
 ```rb
-plugin :url_options, store: -> (io, options) do
-  { response_content_disposition: ContentDisposition.attachment(io.original_filename) }
+plugin :url_options, store: -> (file, options) do
+  { response_content_disposition: ContentDisposition.attachment(file.original_filename) }
 end
 ```
 

data/doc/plugins/validation.md

@@ -34,11 +34,12 @@ The validation block is executed in context of a `Shrine::Attacher` instance:
 ```rb
 class VideoUploader < Shrine
   Attacher.validate do
-    self #=> #<VideoUploader::Attacher>
+    self    #=> #<Shrine::Attacher>
 
-    record #=> #<Movie>
-    name   #=> :video
-    file   #=> #<Shrine::UploadedFile>
+    file    #=> #<Shrine::UploadedFile>
+    record  #=> #<Movie>
+    name    #=> :video
+    context #=> { ... }
   end
 end
 ```
@@ -83,5 +84,14 @@ You can also skip validation by passing `validate: false`:
 attacher.assign(file, validate: false) # skips validation
 ```
 
+## Manual validation
+
+You can also run validation manually via `Attacher#validate`:
+
+```rb
+attacher.set(uploaded_file) # doesn't trigger validation
+attacher.validate           # runs validation
+```
+
 [validation]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/validation.rb
 [validation_helpers]: https://shrinerb.com/docs/plugins/validation_helpers

data/doc/plugins/versions.md

@@ -17,7 +17,7 @@ require "image_processing/mini_magick"
 
 plugin :processing
 
-process(:store) do |io, context|
+process(:store) do |io, **options|
   versions = { original: io } # retain original
 
   io.download do |original|
@@ -120,7 +120,7 @@ In addition to Hashes, the plugin also supports Arrays of files. For example,
 you might want to split a PDf into pages:
 
 ```rb
-process(:store) do |io, context|
+process(:store) do |io, **options|
   versions = { pages: [] }
 
   io.download do |pdf|
@@ -146,7 +146,7 @@ which you can do by adding the yielded `Shrine::UploadedFile` object as one of
 the versions, by convention named `:original`:
 
 ```rb
-process(:store) do |io, context|
+process(:store) do |io, **options|
   # processing thumbnail
   { original: io, thumbnail: thumbnail }
 end
@@ -163,12 +163,12 @@ The version name will be available via `:version` when generating location or a
 default URL.
 
 ```rb
-def generate_location(io, context)
-  "uploads/#{context[:version]}-#{super}"
+def generate_location(io, version: nil, **)
+  "uploads/#{version}-#{super}"
 end
 
-Attacher.default_url do |options|
-  "/images/defaults/#{options[:version]}.jpg"
+Attacher.default_url do |version: nil, **|
+  "/images/defaults/#{version}.jpg"
 end
 ```
 

data/doc/processing.md

@@ -2,16 +2,16 @@
 title: File Processing
 ---
 
-Shrine allows you to process attached files up front or on-the-fly. For
+Shrine allows you to process attached files eagerly 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.
 
 How you're going to implement processing is entirely up to you. For images it's
 recommended to use the **[ImageProcessing]** gem, which provides wrappers for
-processing with [ImageMagick]/[GraphicsMagick] (using the [MiniMagick] gem) or
-[libvips] (using the [ruby-vips] gem; see the [libvips section](#libvips)).
-Here is an example of generating a thumbnail with ImageProcessing:
+processing with [MiniMagick][ImageProcessing::MiniMagick] and
+[libvips][ImageProcessing::Vips]. Here is an example of generating a thumbnail
+with ImageProcessing:
 
 ```
 $ brew install imagemagick
@@ -24,17 +24,21 @@ gem "image_processing", "~> 1.8"
 require "image_processing/mini_magick"
 
 thumbnail = ImageProcessing::MiniMagick
-  .source(image)
-  .resize_to_limit!(600, 400)
+  .source(image)              # input file
+  .resize_to_limit(600, 400)  # resize macro
+  .colorspace("grayscale")    # custom operation
+  .convert("jpeg")            # output type
+  .saver(quality: 90)         # output options
+  .call                       # run the pipeline
 
 thumbnail #=> #<Tempfile:...> (a 600x400 thumbnail of the source image)
 ```
 
-## Processing up front
+## Eager processing
 
 Let's say we're handling images, and want to generate a predefined set of
-thumbnails with various dimensions. We can use the `derivatives` plugin to
-upload and save the processed files:
+thumbnails with various dimensions. We can use the
+**[`derivatives`][derivatives]** plugin to upload and save the processed files:
 
 ```rb
 Shrine.plugin :derivatives
@@ -56,8 +60,11 @@ end
 ```
 ```rb
 photo = Photo.new(image: file)
-photo.image_derivatives! # calls derivatives processor
-photo.save
+
+if photo.valid?
+  photo.image_derivatives! if photo.image_changed? # creates derivatives
+  photo.save
+end
 ```
 
 After the processed files are uploaded, their data is saved into the
@@ -71,27 +78,54 @@ photo.image(:large).size       #=> 5825949
 photo.image(:large).mime_type  #=> "image/jpeg"
 ```
 
-### Automatic processing
+### Conditional derivatives
 
-If you would like derivatives to be automatically created with promotion, you
-can override `Attacher#promote` for call `Attacher#create_derivatives` before
-promotion:
+The `Attacher.derivatives` block is evaluated in context of a
+`Shrine::Attacher` instance:
 
 ```rb
-class Shrine::Attacher
-  def promote(*)
-    create_derivatives
-    super
+Attacher.derivatives do |original|
+  self    #=> #<Shrine::Attacher>
+
+  file    #=> #<Shrine::UploadedFile>
+  record  #=> #<Photo>
+  name    #=> :image
+  context #=> { ... }
+
+  # ...
+end
+```
+
+This gives you the ability to branch the processing logic based on the
+attachment information:
+
+```rb
+Attacher.derivatives do |original|
+  magick = ImageProcessing::MiniMagick.source(original)
+  result = {}
+
+  if record.is_a?(Photo)
+    result[:jpg]  = magick.convert!("jpeg")
+    result[:gray] = magick.colorspace!("grayscale")
+  end
+
+  if file.mime_type == "image/svg+xml"
+    result[:png] = magick.loader(transparent: "white").convert!("png")
   end
+
+  result
 end
 ```
 
+The [`type_predicates`][type_predicates] plugin provides convenient predicate
+methods for branching based on the file type.
+
 ### Backgrounding
 
 Since file processing can be time consuming, it's recommended to move it into a
 background job.
 
-#### With promotion
+#### A) Creating derivatives with promotion
 
 The simplest way is to use the [`backgrounding`][backgrounding] plugin to move
 promotion into a background job, and then create derivatives as part of
@@ -120,7 +154,7 @@ class PromoteJob
 end
 ```
 
-#### Separate from promotion
+#### B) Creating derivatives separately from promotion
 
 Derivatives don't need to be created as part of the attachment flow, you can
 create them at any point after promotion:
@@ -151,7 +185,7 @@ class DerivativesJob
 end
 ```
 
-#### Concurrent processing
+#### C) Creating derivatives concurrently
 
 You can also generate derivatives concurrently:
 
@@ -204,67 +238,98 @@ class DerivativeJob
 end
 ```
 
-### Processing other filetypes
+### URL fallbacks
 
-So far we've only been talking about processing images. However, there is
-nothing image-specific in Shrine's processing API, you can just as well process
-any other types of files. The processing tool doesn't need to have any special
-Shrine integration, the ImageProcessing gem that we saw earlier is a completely
-generic gem.
+If you're creating derivatives in a background job, you'll likely want to use
+some fallbacks for derivative URLs while the background job is still
+processing. You can do that with the [`default_url`][default_url] plugin.
 
-To demonstrate, here is an example of transcoding videos using
-[streamio-ffmpeg]:
+```rb
+Shrine.plugin :default_url
+```
+
+#### A) Fallback to original
+
+You can fall back to the original file URL when the derivative is missing:
 
 ```rb
-# Gemfile
-gem "streamio-ffmpeg"
+Attacher.default_url do |derivative: nil, **|
+  file&.url if derivative
+end
 ```
 ```rb
-require "streamio-ffmpeg"
+photo.image_url(:large) #=> "https://example.com/path/to/original.jpg"
+# ... background job finishes ...
+photo.image_url(:large) #=> "https://example.com/path/to/large.jpg"
+```
 
-class VideoUploader < Shrine
-  Attacher.derivatives do |original|
-    transcoded = Tempfile.new ["transcoded", ".mp4"]
-    screenshot = Tempfile.new ["screenshot", ".jpg"]
+#### B) Fallback to derivative
 
-    movie = FFMPEG::Movie.new(original.path)
-    movie.transcode(transcoded.path)
-    movie.screenshot(screenshot.path)
+You can fall back to another derivative URL when the derivative is missing:
 
-    { transcoded: transcoded, screenshot: screenshot }
-  end
+```rb
+Attacher.default_url do |derivative: nil, **|
+  derivatives[:optimized]&.url if derivative
 end
 ```
+```rb
+photo.image_url(:large) #=> "https://example.com/path/to/optimized.jpg"
+# ... background job finishes ...
+photo.image_url(:large) #=> "https://example.com/path/to/large.jpg"
+```
+
+#### C) Fallback to on-the-fly
+
+You can also fall back to [on-the-fly processing](#on-the-fly-processing),
+which should generally provide the best user experience.
+
+```rb
+THUMBNAILS = {
+  small:  [300, 300],
+  medium: [500, 500],
+  large:  [800, 800],
+}
+
+Attacher.default_url do |derivative: nil, **|
+  file&.derivation_url(:thumbnail, *THUMBNAILS.fetch(derivative)) if derivative
+end
+```
+```rb
+photo.image_url(:large) #=> "../derivations/thumbnail/800/800/..."
+# ... background job finishes ...
+photo.image_url(:large) #=> "https://example.com/path/to/large.jpg"
+```
 
 ## On-the-fly processing
 
-Generating image thumbnails on upload can be a pain to maintain, because
+Having eagerly created image thumbnails can be a pain to maintain, because
 whenever you need to add a new version or change an existing one, you need to
-retroactively apply it to all existing uploads (see the [Managing Derivatives]
-guide for more details).
+retroactively apply it to all existing attachments (see the [Managing
+Derivatives] guide for more details).
 
-As an alternative, it's very common to instead generate thumbnails dynamically
-as they're requested, and then cache them for future requests. This strategy is
-known as "on-the-fly processing", and it's suitable for short-running
-processing such as creating image thumbnails or document previews.
+Sometimes it makes more sense to generate thumbnails dynamically as they're
+requested, and then cache them for future requests. This strategy is known as
+processing "**on-the-fly**" or "**on-demand**", and it's suitable for
+short-running processing such as creating image thumbnails or document
+previews.
 
 Shrine provides on-the-fly processing functionality via the
-[`derivation_endpoint`][derivation_endpoint] plugin. The basic setup is the
-following:
-
-1. load the plugin with a secret key and a path prefix for the endpoint
-2. mount the endpoint into your main app's router
-3. define a processing block for the type files you want to generate
-
-Together it might look something like this:
+**[`derivation_endpoint`][derivation_endpoint]** plugin. You set it up by
+loading the plugin with a secret key (you generate this yourself, maybe via
+something like `SecureRandom.hex`) and a path prefix, mount its Rack app in
+your routes on the configured path prefix, and define processing you want to
+perform:
 
+```rb
+# config/initializers/shrine.rb (Rails)
+# ...
+Shrine.plugin :derivation_endpoint, secret_key: "<SHRINE_SECRET_KEY>"
+```
 ```rb
 require "image_processing/mini_magick"
 
 class ImageUploader < Shrine
-  plugin :derivation_endpoint,
-    secret_key: "<YOUR SECRET KEY>",
-    prefix:     "derivations/image"
+  plugin :derivation_endpoint, prefix: "derivations/image" # matches mount point
 
   derivation :thumbnail do |file, width, height|
     ImageProcessing::MiniMagick
@@ -273,11 +338,11 @@ class ImageUploader < Shrine
   end
 end
 ```
-
 ```rb
 # config/routes.rb (Rails)
 Rails.application.routes.draw do
-  mount ImageUploader.derivation_endpoint => "derivations/image"
+  # ...
+  mount ImageUploader.derivation_endpoint => "/derivations/image"
 end
 ```
 
@@ -293,8 +358,133 @@ The plugin is highly customizable, be sure to check out the
 [documentation][derivation_endpoint], especially the [performance
 section][derivation_endpoint performance].
 
+### Dynamic derivation
+
+If you have multiple types of transformations and don't want to have a
+derivation for each one, you can set up a single derivation that applies any
+series of transformations:
+
+```rb
+class ImageUploader < Shrine
+  derivation :transform do |original, transformations|
+    transformations = Shrine.urlsafe_deserialize(transformations)
+
+    vips = ImageProcessing::Vips.source(original)
+    vips.apply!(transformations)
+  end
+end
+```
+```rb
+photo.image.derivation_url :transform, Shrine.urlsafe_serialize(
+  crop:          [10, 10, 500, 500],
+  resize_to_fit: [300, 300],
+  gaussblur:     1,
+)
+```
+
+You can create a helper method for convenience:
+
+```rb
+def derivation_url(file, transformations)
+  file.derivation_url(:transform, Shrine.urlsafe_serialize(transformations))
+end
+```
+```rb
+derivation_url photo.image,
+  crop:          [10, 10, 500, 500],
+  resize_to_fit: [300, 300],
+  gaussblur:     1
+```
+
+## Processing other filetypes
+
+So far we've only been talking about processing images. However, there is
+nothing image-specific in Shrine's processing API, you can just as well process
+any other types of files. The processing tool doesn't need to have any special
+Shrine integration, the ImageProcessing gem that we saw earlier is a completely
+generic gem.
+
+To demonstrate, here is an example of transcoding videos using
+[streamio-ffmpeg]:
+
+```rb
+# Gemfile
+gem "streamio-ffmpeg"
+```
+```rb
+require "streamio-ffmpeg"
+
+class VideoUploader < Shrine
+  Attacher.derivatives do |original|
+    transcoded = Tempfile.new ["transcoded", ".mp4"]
+    screenshot = Tempfile.new ["screenshot", ".jpg"]
+
+    movie = FFMPEG::Movie.new(original.path)
+    movie.transcode(transcoded.path)
+    movie.screenshot(screenshot.path)
+
+    { transcoded: transcoded, screenshot: screenshot }
+  end
+end
+```
+
+### Polymorphic uploader
+
+Sometimes you might want an attachment attribute to accept multiple types of
+files, and apply different processing depending on the type. Since Shrine's
+processing blocks are evaluated dynamically, you can use conditional logic:
+
+```rb
+class PolymorphicUploader < Shrine
+  IMAGE_TYPES = %w[image/jpeg image/png image/webp]
+  VIDEO_TYPES = %w[video/mp4 video/quicktime]
+  PDF_TYPES   = %w[application/pdf]
+
+  Attacher.validate do
+    validate_mime_type IMAGE_TYPES + VIDEO_TYPES + PDF_TYPES
+    # ...
+  end
+
+  Attacher.derivatives do |original|
+    case file.mime_type
+    when *IMAGE_TYPES then process_derivatives(:image, original)
+    when *VIDEO_TYPES then process_derivatives(:video, original)
+    when *PDF_TYPES   then process_derivatives(:pdf,   original)
+    end
+  end
+
+  Attacher.derivatives :image do |original|
+    # ...
+  end
+
+  Attacher.derivatives :video do |original|
+    # ...
+  end
+
+  Attacher.derivatives :pdf do |original|
+    # ...
+  end
+end
+```
+
 ## Extras
 
+### Automatic derivatives
+
+If you would like derivatives to be automatically created with promotion, you
+can use the `create_on_promote` option built-in to the derivatives plugin.
+
+```rb
+class Shrine::Attacher
+  plugin :derivatives, create_on_promote: true
+end
+```
+
+This shouldn't be needed if you're processing in the
+[background](#backgrounding), as in that case you have a background worker that
+will be called for each attachment, so you can call
+`Attacher#create_derivatives` there.
+
 ### libvips
 
 As mentioned, ImageProcessing gem also has an alternative backend for
@@ -304,7 +494,7 @@ characteristics – it's often **multiple times faster** than ImageMagick and ha
 low memory usage (see [Why is libvips quick]).
 
 Using libvips is as easy as installing it and switching to the
-`ImageProcessing::Vips` backend:
+[`ImageProcessing::Vips`][ImageProcessing::Vips] backend:
 
 ```
 $ brew install vips
@@ -326,7 +516,7 @@ thumbnail = ImageProcessing::Vips
 thumbnail #=> #<Tempfile:...> (a 600x400 thumbnail of the source image)
 ```
 
-### Parallelize uploading
+### Parallelize uploads
 
 If you're generating derivatives, you can parallelize the uploads using the
 [concurrent-ruby] gem:
@@ -351,86 +541,60 @@ Concurrent::Promises.zip(*tasks).wait!
 
 ### External processing
 
-Since processing is so dynamic, you're not limited to using the ImageProcessing
-gem, you can also use a 3rd-party service to generate thumbnails for you. Here
-is an example of generating thumbnails on-the-fly using [ImageOptim.com] (not
-to be confused with the [image_optim] gem):
+You can also integrate Shrine with 3rd-party processing services such as
+[Cloudinary] and [Imgix]. In the most common case, you'd serve images directly
+from these services, see the corresponding plugin docs for more details
+([shrine-cloudinary], [shrine-imgix] and [others][external storages])
+
+You can also choose to use these services as an implementation detail of your
+application, by downloading the processed images and saving them to your
+storage. Here is how you might store files processed by Imgix as derivatives:
 
 ```rb
 # Gemfile
 gem "down", "~> 5.0"
 gem "http", "~> 4.0"
+gem "shrine-imgix", "~> 0.5"
+```
+```rb
+Shrine.plugin :derivatives
+Shrine.plugin :imgix, client: { host: "my-app.imgix.net", secure_url_token: "secret" }
 ```
-
 ```rb
 require "down/http"
 
 class ImageUploader < Shrine
-  plugin :derivation_endpoint,
-    secret_key: "secret",
-    prefix:     "derivations/image",
-    download:   false
-
-  derivation :thumbnail do |width, height|
-    # generate thumbnails using ImageOptim.com
-    down = Down::Http.new(method: :post)
-    down.download("https://im2.io/<USERNAME>/#{width}x#{height}/#{source.url}")
+  IMGIX_THUMBNAIL = -> (file, width, height) do
+    Down::Http.download(file.imgix_url(w: width, h: height))
   end
-end
-```
-
-### Cloudinary
 
-[Cloudinary] is a popular commercial service for on-the-fly image processing,
-so it's a good alternative to the `derivation_endpoint` plugin. The
-[shrine-cloudinary] gem provides a Shrine storage that we can set for our
-temporary and permanent storage:
-
-```rb
-# Gemfile
-gem "shrine-cloudinary"
-```
-
-```rb
-require "cloudinary"
-require "shrine/storage/cloudinary"
-
-Cloudinary.config(
-  cloud_name: "<YOUR_CLOUD_NAME>",
-  api_key:    "<YOUR_API_KEY>",
-  api_secret: "<YOUR_API_SECRET>",
-)
-
-Shrine.storages = {
-  cache: Shrine::Storage::Cloudinary.new(prefix: "cache"),
-  store: Shrine::Storage::Cloudinary.new,
-}
-```
-
-Now when we upload our images to Cloudinary, we can generate URLs with various
-processing parameters:
-
-```rb
-photo.image_url(width: 100, height: 100, crop: :fit)
-#=> "http://res.cloudinary.com/myapp/image/upload/w_100,h_100,c_fit/nature.jpg"
+  Attacher.derivatives do
+    {
+      large:  IMGIX_THUMBNAIL[file, 800, 800],
+      medium: IMGIX_THUMBNAIL[file, 500, 500],
+      small:  IMGIX_THUMBNAIL[file, 300, 300],
+    }
+  end
+end
 ```
 
 [`Shrine::UploadedFile`]: http://shrinerb.com/rdoc/classes/Shrine/UploadedFile/InstanceMethods.html
 [ImageProcessing]: https://github.com/janko/image_processing
-[ImageMagick]: https://www.imagemagick.org
-[GraphicsMagick]: http://www.graphicsmagick.org
-[libvips]: http://libvips.github.io/libvips/
-[Why is libvips quick]: https://github.com/libvips/libvips/wiki/Why-is-libvips-quick
-[ImageOptim.com]: https://imageoptim.com/api
+[ImageProcessing::MiniMagick]: https://github.com/janko/image_processing/blob/master/doc/minimagick.md#readme
+[ImageProcessing::Vips]: https://github.com/janko/image_processing/blob/master/doc/vips.md#readme
 [streamio-ffmpeg]: https://github.com/streamio/streamio-ffmpeg
 [Managing Derivatives]: https://shrinerb.com/docs/changing-derivatives
-[Cloudinary]: https://cloudinary.com
+[Cloudinary]: https://cloudinary.com/
+[Imgix]: https://www.imgix.com/
 [shrine-cloudinary]: https://github.com/shrinerb/shrine-cloudinary
+[shrine-imgix]: https://github.com/shrinerb/shrine-imgix
 [backgrounding]: https://shrinerb.com/docs/plugins/backgrounding
-[ruby-vips]: https://github.com/libvips/ruby-vips
-[MiniMagick]: https://github.com/minimagick/minimagick
 [derivation_endpoint]: https://shrinerb.com/docs/plugins/derivation_endpoint
 [derivation_endpoint performance]: https://shrinerb.com/docs/plugins/derivation_endpoint#performance
 [derivatives]: https://shrinerb.com/docs/plugins/derivatives
 [concurrent-ruby]: https://github.com/ruby-concurrency/concurrent-ruby
-[image_optim]: https://github.com/toy/image_optim
+[default_url]: https://shrinerb.com/docs/plugins/default_url
+[external storages]: https://shrinerb.com/docs/external/extensions#storages
+[libvips]: https://libvips.github.io/libvips/
+[Why is libvips quick]: https://github.com/libvips/libvips/wiki/Why-is-libvips-quick
+[type_predicates]: https://shrinerb.com/docs/plugins/type_predicates