shrine 2.19.3 → 3.6.0

data/doc/plugins/signature.md

@@ -1,4 +1,6 @@
-# Signature
+---
+title: Signature
+---
 
 The [`signature`][signature] plugin provides the ability to calculate a hash
 from file content. This hash can be used as a checksum or just as a unique
@@ -39,7 +41,7 @@ calculated hash.
 ```rb
 plugin :add_metadata
 
-add_metadata :md5 do |io, context|
+add_metadata :md5 do |io|
   calculate_signature(io, :md5)
 end
 ```
@@ -48,11 +50,20 @@ This will generate a hash for each uploaded file, but if you want to generate
 one only for the original file, you can add a conditional:
 
 ```rb
-add_metadata :md5 do |io, context|
-  calculate_signature(io, :md5) if context[:action] == :cache
+add_metadata :md5 do |io, action: nil, **|
+  calculate_signature(io, :md5) if action == :cache
 end
 ```
 
+## Rewinding
+
+If you want to calculate signature from a non-rewindable IO object, you can
+tell Shrine to skip rewinding:
+
+```rb
+Shrine.calculate_signature(io, :md5, rewind: false)
+```
+
 ## Instrumentation
 
 If the `instrumentation` plugin has been loaded, the `signature` plugin adds
@@ -95,4 +106,4 @@ Or disable logging altogether:
 plugin :signature, log_subscriber: nil
 ```
 
-[signature]: /lib/shrine/plugins/signature.rb
+[signature]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/signature.rb

data/doc/plugins/store_dimensions.md

@@ -1,4 +1,6 @@
-# Store Dimensions
+---
+title: Store Dimensions
+---
 
 The [`store_dimensions`][store_dimensions] plugin extracts dimensions of
 uploaded images and stores them into the metadata hash (by default it uses the
@@ -70,6 +72,16 @@ Shrine.dimensions(io) #=> [300, 400] (calls the defined analyzer)
 Shrine.dimensions_analyzers[:fastimage].call(io) #=> [300, 400] (calls a built-in analyzer)
 ```
 
+### Disabling auto-extraction
+
+If you want to use the dimensions extraction methods but not automatically
+extract dimensions on upload, you can setup this plugin with the
+`auto_extraction: false` option.
+
+```rb
+plugin :store_dimensions, auto_extraction: false
+```
+
 ## Errors
 
 By default, any exceptions that the analyzer raises while extracting dimensions
@@ -129,7 +141,7 @@ Or disable logging altogether:
 plugin :store_dimensions, log_subscriber: nil
 ```
 
-[store_dimensions]: /lib/shrine/plugins/store_dimensions.rb
+[store_dimensions]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/store_dimensions.rb
 [fastimage]: https://github.com/sdsykes/fastimage
 [mini_magick]: https://github.com/minimagick/minimagick
 [ruby-vips]: https://github.com/libvips/ruby-vips

data/doc/plugins/tempfile.md

@@ -1,4 +1,6 @@
-# Tempfile
+---
+title: Tempfile
+---
 
 The [`tempfile`][tempfile] plugin makes it easier to reuse a single copy of an
 uploaded file on disk.
@@ -39,4 +41,4 @@ when the given IO object is an open `UploadedFile`. Since `Shrine.with_file` is
 typically called on the `Shrine` class directly, it's recommended to load this
 plugin globally.
 
-[tempfile]: /lib/shrine/plugins/tempfile.rb
+[tempfile]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/tempfile.rb

data/doc/plugins/type_predicates.md

@@ -0,0 +1,96 @@
+---
+title: Type Predicates
+---
+
+The [`type_predicates`][type_predicates] plugin adds predicate methods to
+`Shrine::UploadedFile` based on the MIME type. By default, it uses the
+[MiniMime] gem for looking up MIME types.
+
+```rb
+# Gemfile
+gem "mini_mime"
+```
+```rb
+Shrine.plugin :type_predicates
+```
+
+## General predicates
+
+The plugin adds four predicate methods based on the general type of the file:
+
+```rb
+file.image? # returns true for any "image/*" MIME type
+file.video? # returns true for any "video/*" MIME type
+file.audio? # returns true for any "audio/*" MIME type
+file.text?  # returns true for any "text/*" MIME type
+```
+
+If `mime_type` metadata value is nil, `Shrine::Error` will be raised.
+
+## Specific predicates
+
+The `UploadedFile#type?` method takes a file extension, and returns whether the
+`mime_type` metadata value of the uploaded file matches the MIME type
+associated to the given file extension.
+
+```rb
+file.type?(:jpg) # returns true if MIME type is "image/jpeg"
+file.type?(:svg) # returns true if MIME type is "image/svg+xml"
+file.type?(:mov) # returns true if MIME type is "video/quicktime"
+file.type?(:ppt) # returns true if MIME type is "application/vnd.ms-powerpoint"
+...
+```
+
+For convenience, you can create predicate methods for specific file types:
+
+```rb
+Shrine.plugin :type_predicates, methods: %i[jpg svg mov ppt]
+```
+```rb
+file.jpg? # returns true if MIME type is "image/jpeg"
+file.svg? # returns true if MIME type is "image/svg+xml"
+file.mov? # returns true if MIME type is "video/quicktime"
+file.ppt? # returns true if MIME type is "application/vnd.ms-powerpoint"
+```
+
+If `mime_type` metadata value is nil, or the underlying MIME type library
+doesn't recognize a given type, `Shrine::Error` will be raised.
+
+### MIME database
+
+The MIME type lookup by file extension is done by the underlying MIME type
+library ([MiniMime] by default). You can change the MIME type library via the
+`:mime` plugin option:
+
+```rb
+Shrine.plugin :type_predicates, mime: :marcel # requires adding "marcel" gem to the Gemfile
+```
+
+The following MIME type libraries are supported:
+
+| Name          | Description                                                           |
+| :----         | :---------                                                            |
+| `:mini_mime`  | (**Default**.) Uses [MiniMime] gem to look up MIME type by extension. |
+| `:mime_types` | Uses [mime-types] gem to look up MIME type by extension.              |
+| `:mimemagic`  | Uses [MimeMagic] gem to look up MIME type by extension.               |
+| `:marcel`     | Uses [Marcel] gem to look up MIME type by extension.                  |
+| `:rack_mime`  | Uses [Rack::Mime] to look up MIME type by extension.                  |
+
+You can also specify a custom block, which receives the extension and is
+expected to return the corresponding MIME type. Inside the block you can call
+into existing MIME type libraries:
+
+```rb
+Shrine.plugin :type_predicates, mime: -> (extension) do
+  mime_type   = Shrine.type_lookup(extension, :marcel)
+  mime_type ||= Shrine.type_lookup(extension, :mini_mime)
+  mime_type
+end
+```
+
+[type_predicates]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/type_predicates.rb
+[MiniMime]: https://github.com/discourse/mini_mime
+[mime-types]: https://github.com/mime-types/ruby-mime-types
+[MimeMagic]: https://github.com/minad/mimemagic
+[Marcel]: https://github.com/basecamp/marcel
+[Rack::Mime]: https://github.com/rack/rack/blob/master/lib/rack/mime.rb

data/doc/plugins/upload_endpoint.md

@@ -1,4 +1,6 @@
-# Upload Endpoint
+---
+title: Upload Endpoint
+---
 
 The [`upload_endpoint`][upload_endpoint] plugin provides a Rack endpoint which
 accepts file uploads and forwards them to specified storage. On the client side
@@ -8,6 +10,8 @@ it's recommended to use [Uppy] for asynchronous uploads.
 plugin :upload_endpoint
 ```
 
+## Setup
+
 The plugin adds a `Shrine.upload_endpoint` method which, given a storage
 identifier, returns a Rack application that accepts multipart POST requests,
 and uploads received files to the specified storage. You can run this Rack
@@ -91,16 +95,9 @@ plugin :upload_endpoint, max_size: 20*1024*1024 # 20 MB
 If the uploaded file is larger than the specified value, a `413 Payload Too
 Large` response will be returned.
 
-## Context
-
-The upload context will *not* contain `:record` and `:name` values, as the
-upload happens independently of a database record. The endpoint will send the
-following upload context:
+## Uploader options
 
-* `:action` – holds the value `:upload`
-* `:request` – holds an instance of `Rack::Request`
-
-You can update the upload context via `:upload_context`:
+You can pass additional uploader options via `:upload_context`:
 
 ```rb
 plugin :upload_endpoint, upload_context: -> (request) do
@@ -108,13 +105,16 @@ plugin :upload_endpoint, upload_context: -> (request) do
 end
 ```
 
+Note that the uploader will *not* receive `:record` and `:name` values, as the
+upload happens independently of a database record.
+
 ## Upload
 
 You can also customize the upload itself via the `:upload` option:
 
 ```rb
-plugin :upload_endpoint, upload: -> (io, context, request) do
-  Shrine.upload(io, :cache, context)
+plugin :upload_endpoint, upload: -> (io, options, request) do
+  Shrine.upload(io, :cache, **options)
 end
 ```
 
@@ -173,5 +173,5 @@ and the endpoint will automatically use it to verify the uploaded data.
 
 If the checksums don't match, a `460 Checksum Mismatch` response is returned.
 
-[upload_endpoint]: /lib/shrine/plugins/upload_endpoint.rb
+[upload_endpoint]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/upload_endpoint.rb
 [Uppy]: https://uppy.io

data/doc/plugins/upload_options.md

@@ -1,4 +1,6 @@
-# Upload Options
+---
+title: Upload Options
+---
 
 The [`upload_options`][upload_options] plugin allows you to automatically pass
 additional upload options to storage on every upload:
@@ -11,8 +13,8 @@ Keys are names of the registered storages, and values are either hashes or
 blocks.
 
 ```rb
-plugin :upload_options, store: -> (io, context) do
-  if [:original, :thumb].include?(context[:version])
+plugin :upload_options, store: -> (io, options) do
+  if options[:derivative]
     { acl: "public-read" }
   else
     { acl: "private" }
@@ -27,4 +29,4 @@ the uploader.
 uploader.upload(file, upload_options: { acl: "public-read" })
 ```
 
-[upload_options]: /lib/shrine/plugins/upload_options.rb
+[upload_options]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/upload_options.rb

data/doc/plugins/{default_url_options.md → url_options.md}

@@ -1,11 +1,13 @@
-# Default URL Options
+---
+title: URL Options
+---
 
-The [`default_url_options`][default_url_options] plugin allows you to specify
+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 :default_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,
@@ -13,8 +15,8 @@ which will receive the UploadedFile object along with any options that were
 passed to `UploadedFile#url`.
 
 ```rb
-plugin :default_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
 ```
 
@@ -22,4 +24,4 @@ In both cases the default options are merged with options passed to
 `UploadedFile#url`, and the latter will always have precedence over default
 options.
 
-[default_url_options]: /lib/shrine/plugins/default_url_options.rb
+[url_options]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/url_options.rb

data/doc/plugins/validation.md

@@ -0,0 +1,97 @@
+---
+title: Validation
+---
+
+The [`validation`][validation] plugin provides a framework for validating
+attached files. For some useful validators, see the
+[`validation_helpers`][validation_helpers] plugin.
+
+```rb
+plugin :validation
+```
+
+## Usage
+
+The `Attacher.validate` method is used to register a validation block, which
+is called on attachment:
+
+```rb
+class VideoUploader < Shrine
+  Attacher.validate do
+    if file.duration > 5*60*60
+      errors << "duration must not be longer than 5 hours"
+    end
+  end
+end
+```
+```rb
+attacher.assign(file)
+attacher.errors #=> ["duration must not be longer than 5 hours"]
+```
+
+The validation block is executed in context of a `Shrine::Attacher` instance:
+
+```rb
+class VideoUploader < Shrine
+  Attacher.validate do
+    self    #=> #<Shrine::Attacher>
+
+    file    #=> #<Shrine::UploadedFile>
+    record  #=> #<Movie>
+    name    #=> :video
+    context #=> { ... }
+  end
+end
+```
+
+## Inheritance
+
+If you're subclassing an uploader that has validations defined, you can call
+those validations via `super()`:
+
+```rb
+class ApplicationUploader < Shrine
+  Attacher.validate { validate_max_size 5.megabytes }
+end
+```
+```rb
+class ImageUploader < ApplicationUploader
+  Attacher.validate do
+    super() # empty parentheses are required
+    validate_mime_type %w[image/jpeg image/png image/webp]
+  end
+end
+```
+
+## Validation options
+
+You can pass options to the validator via the `:validate` option:
+
+```rb
+attacher.assign(file, validate: { foo: "bar" })
+```
+```rb
+class MyUploader < Shrine
+  Attacher.validate do |**options|
+    options #=> { foo: "bar" }
+  end
+end
+```
+
+You can also skip validation by passing `validate: false`:
+
+```rb
+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/validation_helpers.md

@@ -1,4 +1,6 @@
-# Validation Helpers
+---
+title: Validation Helpers
+---
 
 The [`validation_helpers`][validation_helpers] plugin provides helper methods
 for validating attached files based on extracted metadata.
@@ -7,8 +9,9 @@ for validating attached files based on extracted metadata.
 plugin :validation_helpers
 
 Attacher.validate do
-  validate_mime_type_inclusion %w[image/jpeg image/png image/gif]
-  validate_max_size 5*1024*1024 if record.guest?
+  validate_mime_type %w[image/jpeg image/png image/webp]
+  validate_max_size 5*1024*1024 # bytes
+  # ...
 end
 ```
 
@@ -38,8 +41,8 @@ accept a list of MIME types, and validate that the `mime_type` metadata value
 is/is not a member of that list.
 
 ```rb
-validate_mime_type_inclusion %w[image/jpeg image/png image/gif] # file must be a JPEG, PNG or a GIF image
-validate_mime_type_exclusion %w[application/x-php]              # file must not be a PHP script
+validate_mime_type_inclusion %w[image/jpeg image/png image/webp] # file must be a JPEG, PNG or a WEBP image
+validate_mime_type_exclusion %w[application/x-php]               # file must not be a PHP script
 ```
 
 Instead of `#validate_mime_type_inclusion` you can also use just
@@ -52,8 +55,8 @@ accept a list of file extensions, and validate that the `filename` metadata
 value extension is/is not a member of that list.
 
 ```rb
-validate_extension_inclusion %w[jpg jpeg png gif] # file must have .jpg, .jpeg, .png, or .gif extension
-validate_extension_exclusion %w[php]              # file must not have a .php extension
+validate_extension_inclusion %w[jpg jpeg png webp] # file must have .jpg, .jpeg, .png, or .webp extension
+validate_extension_exclusion %w[php]               # file must not have a .php extension
 ```
 
 Instead of `#validate_extension_inclusion` you can also use just
@@ -132,7 +135,7 @@ easily do conditional validation:
 
 ```rb
 Attacher.validate do
-  if validate_mime_type_inclusion %w[image/jpeg image/png image/gif]
+  if validate_mime_type_inclusion %w[image/jpeg image/png image/webp]
     validate_max_width 2000
     validate_max_height 2000
   end
@@ -147,11 +150,11 @@ the `:default_messages` option to the plugin:
 ```rb
 plugin :validation_helpers, default_messages: {
   max_size:            -> (max)  { I18n.t("errors.file.max_size", max: max) },
-  min_size:            -> (max)  { I18n.t("errors.file.min_size", min: min) },
+  min_size:            -> (min)  { I18n.t("errors.file.min_size", min: min) },
   max_width:           -> (max)  { I18n.t("errors.file.max_width", max: max) },
-  min_width:           -> (max)  { I18n.t("errors.file.min_width", min: min) },
+  min_width:           -> (min)  { I18n.t("errors.file.min_width", min: min) },
   max_height:          -> (max)  { I18n.t("errors.file.max_height", max: max) },
-  min_height:          -> (max)  { I18n.t("errors.file.min_height", min: min) },
+  min_height:          -> (min)  { I18n.t("errors.file.min_height", min: min) },
   max_dimensions:      -> (dims) { I18n.t("errors.file.max_dimensions", dims: dims) },
   min_dimensions:      -> (dims) { I18n.t("errors.file.min_dimensions", dims: dims) },
   mime_type_inclusion: -> (list) { I18n.t("errors.file.mime_type_inclusion", list: list) },
@@ -166,8 +169,8 @@ If you would like to change the error message inline, you can pass the
 
 ```rb
 Attacher.validate do
-  validate_mime_type %w[image/jpeg image/png image/gif], message: "must be JPEG, PNG or GIF"
+  validate_mime_type %w[image/jpeg image/png image/webp], message: "must be JPEG, PNG or WEBP"
 end
 ```
 
-[validation_helpers]: /lib/shrine/plugins/validation_helpers.rb
+[validation_helpers]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/validation_helpers.rb

data/doc/plugins/versions.md

@@ -1,4 +1,6 @@
-# Versions
+---
+title: Versions
+---
 
 The [`versions`][versions] plugin enables your uploader to deal with versions,
 by allowing you to return a Hash of files when processing.
@@ -15,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|
@@ -47,10 +49,10 @@ user.avatar_data #=>
 
 user.avatar #=>
 # {
-#   :original => #<Shrine::UploadedFile @data={"id"=>"0gsdf.jpg", ...}>,
-#   :large    => #<Shrine::UploadedFile @data={"id"=>"lg043.jpg", ...}>,
-#   :medium   => #<Shrine::UploadedFile @data={"id"=>"kd9fk.jpg", ...}>,
-#   :small    => #<Shrine::UploadedFile @data={"id"=>"932fl.jpg", ...}>,
+#   :original => #<Shrine::UploadedFile id=0gsdf.jpg" ...}>,
+#   :large    => #<Shrine::UploadedFile id=lg043.jpg" ...}>,
+#   :medium   => #<Shrine::UploadedFile id=kd9fk.jpg" ...}>,
+#   :small    => #<Shrine::UploadedFile id=932fl.jpg" ...}>,
 # }
 
 user.avatar[:medium]     #=> #<Shrine::UploadedFile>
@@ -118,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|
@@ -144,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
@@ -161,20 +163,14 @@ 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
 ```
 
-## Re-create Versions
-
-If you want to re-create a single or all versions, refer to the [reprocessing
-versions] guide for details.
-
-[versions]: /lib/shrine/plugins/versions.rb
-[reprocessing versions]: /doc/regenerating_versions.md#readme
+[versions]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/versions.rb
 [image_processing]: https://github.com/janko/image_processing