shrine 2.18.1 → 2.19.0

data/doc/attacher.md

@@ -184,8 +184,7 @@ attacher.promote(cached_file, action: :custom_name)
 ```
 
 The `:action` parameter is optional; it can be used for triggering a certain
-processing block, and it is also automatically printed by the `logging` plugin
-to aid in debugging.
+processing block, or for additional context during instrumentation.
 
 As a matter of fact, all additional options passed to `#promote` will be
 forwarded to `Shrine#upload`. So unless you're generating versions, you can do

data/doc/carrierwave.md

@@ -613,10 +613,11 @@ Shrine.plugin :keep_files, cached: true, replaced: true
 
 #### `move_to_cache`, `move_to_store`
 
-Shrine brings this functionality through the `moving` plugin.
+You can tell the `FileSystem` storage that it should move files by specifying
+the `:move` upload option:
 
 ```rb
-Shrine.plugin :moving, storages: [:cache]
+Shrine.plugin :upload_options, cache: { move: true }, store: { move: true }
 ```
 
 #### `validate_integrity`, `ignore_integrity_errors`

data/doc/creating_storages.md

@@ -204,26 +204,6 @@ The storage can support additional options to customize how the presign will be
 generated, those can be forwarded via the `:presign_options` option on the
 `presign_endpoint` plugin.
 
-## Move
-
-If your storage can move files, you can add the additional `#move` and
-`#movable?` methods, and they will automatically get used if the `moving`
-plugin is loaded.
-
-```rb
-class MyStorage
-  # ...
-  def move(io, id, **upload_options)
-    # does the moving of the `io` to the location `id`
-  end
-
-  def movable?(io, id)
-    # whether the given `io` is movable to the location `id`
-  end
-  # ...
-end
-```
-
 ## Clear
 
 While this method is not used by Shrine, it is good to give users the

data/doc/design.md

@@ -188,7 +188,7 @@ Shrine::Attachment.new(:image).instance_methods #=> [:image=, :image, :image_url
 
 # equivalents
 Shrine::Attachment.new(:image)
-Shrine.attachment(:image)
+Shrine::Attachment(:image)
 Shrine[:image]
 ```
 

data/doc/metadata.md

@@ -21,9 +21,27 @@ The following metadata is extracted by default:
 | `mime_type` | extracted from `io.content_type`                   |
 | `size`      | extracted from `io.size`                           |
 
+You can access extracted metadata in three ways:
 
-Under the hood `Shrine#extract_metadata` is called, which you can also use
-directly to extract metadata from any IO object.
+```rb
+# via methods (if they're defined)
+uploaded_file.size
+uploaded_file.original_filename
+uploaded_file.mime_type
+
+# via the metadata hash
+uploaded_file.metadata["size"]
+uploaded_file.metadata["filename"]
+uploaded_file.metadata["mime_type"]
+
+# via the #[] operator
+uploaded_file["size"]
+uploaded_file["filename"]
+uploaded_file["mime_type"]
+```
+
+Under the hood, `Shrine#upload` calls `Shrine#extract_metadata`, which you can
+also use directly to extract metadata from any IO object:
 
 ```rb
 uploader.extract_metadata(io) #=>
@@ -34,51 +52,61 @@ uploader.extract_metadata(io) #=>
 # }
 ```
 
-By default these values are determined from the following attributes on the IO
-object:
+`Shrine#upload` accepts a `:metadata` option which accepts the following values:
 
-* `filename` – `io.original_filename` or `io.path`
-* `mime_type` – `io.content_type`
-* `size` – `io.size`
+  * `Hash` – adds/overrides extracted metadata with the given hash
 
-Note that you can also manually add or override metadata on upload by passing
-the `:metadata` option to `Shrine#upload`:
+    ```rb
+    uploaded_file = uploader.upload(file, metadata: { "filename" => "Matrix[1999].mp4", "foo" => "bar" })
+    uploaded_file.original_filename #=> "Matrix[1999].mp4"
+    uploaded_file.metadata["foo"]   #=> "bar"
+    ```
 
-```rb
-uploaded_file = uploader.upload(file, metadata: { "filename" => "Matrix[1999].mp4", "foo" => "bar" })
-uploaded_file.original_filename #=> "Matrix[1999].mp4"
-uploaded_file.metadata["foo"]   #=> "bar"
-```
+  * `false` – skips metadata extraction (useful in tests)
+
+    ```rb
+    uploaded_file = uploader.upload(file, metadata: false)
+    uploaded_file.metadata #=> {}
+    ```
+
+  * `true` – forces metadata extraction when a `Shrine::UploadedFile` is being
+    uploaded (by default metadata is simply copied over)
+
+    ```rb
+    uploaded_file = uploader.upload(uploaded_file, metadata: true)
+    uploaded_file.metadata # re-extracted metadata
+    ```
 
 ## MIME type
 
 By default, the `mime_type` metadata will be copied over from the
-`#content_type` attribute of the input file, if present. However, since
+`#content_type` attribute of the input file (if present). However, since
 `#content_type` value comes from the `Content-Type` header of the upload
 request, it's *not guaranteed* to hold the actual MIME type of the file (browser
 determines this header based on file extension). Moreover, only
-`ActionDispatch::Http::UploadedFile` and `Shrine::Plugins::RackFile::UploadedFile`
-objects have `#content_type` defined, so when uploading simple file objects
-`mime_type` will be nil. That makes relying on `#content_type` both a security
-risk and limiting.
+`ActionDispatch::Http::UploadedFile`, `Shrine::Plugins::RackFile::UploadedFile`,
+and `Shrine::Plugins::DataUri::DataFile` objects have `#content_type` defined,
+so, when uploading simple file objects, `mime_type` will be nil. That makes
+relying on `#content_type` both a security risk and limiting.
 
-To remedy that, Shrine comes with a `determine_mime_type` plugin which is able
-to extract the MIME type from IO *content*. When you load it, the `mime_type`
-plugin will now be determined using the UNIX [`file`] command.
+To remedy that, Shrine comes with a
+[`determine_mime_type`][determine_mime_type] plugin which is able to extract
+the MIME type from IO *content*:
 
 ```rb
-Shrine.plugin :determine_mime_type
+# Gemfile
+gem "marcel", "~> 0.3"
+```
+```rb
+Shrine.plugin :determine_mime_type, analyzer: :marcel
 ```
 ```rb
 uploaded_file = uploader.upload StringIO.new("<?php ... ?>")
-uploaded_file.mime_type #=> "text/x-php"
+uploaded_file.mime_type #=> "application/x-php"
 ```
 
-The `file` command won't correctly determine the MIME type in all cases, that's
-why the `determine_mime_type` plugin comes with different MIME type analyzers.
-So, instead of the `file` command you can use gems like [MimeMagic] or
-[Marcel], as well as mix-and-match the analyzers to suit your needs. See the
-plugin documentation for more details.
+You can choose different analyzers, and even mix-and-match them. See the
+[`determine_mime_type`][determine_mime_type] plugin docs for more details.
 
 ## Image Dimensions
 
@@ -165,13 +193,10 @@ uploaded_file.metadata #=>
 
 The yielded `io` object will not always be an object that responds to `#path`.
 If you're using the `data_uri` plugin, the `io` will be a `StringIO` wrapper.
-When the `restore_cached_data` plugin is loaded, any assigned cached file will
-get their metadata extracted, and `io` will be a `Shrine::UploadedFile` object.
-If you're using a metadata analyzer that requires the source file to be on
-disk, you can use `Shrine.with_file` to ensure you have a file object.
-
-Also, be aware that metadata is extracted before file validation, so you'll
-need to handle the cases where the file is not of expected type.
+With `restore_cached_data` or `refresh_metadata` plugins, `io` might be a
+`Shrine::UploadedFile` object. If you're using a metadata analyzer that
+requires the source file to be on disk, you can use `Shrine.with_file` to
+ensure you have a file object.
 
 ## Metadata columns
 
@@ -319,3 +344,4 @@ end
 [MiniMagick]: https://github.com/minimagick/minimagick
 [ruby-vips]: https://github.com/libvips/ruby-vips
 [tus server]: https://github.com/janko/tus-ruby-server
+[determine_mime_type]: /doc/plugins/determine_mime_type.md#readme

data/doc/paperclip.md

@@ -182,16 +182,17 @@ but without the possibility of false negatives.
 
 In Paperclip you enable logging by setting `Paperclip.options[:log] = true`,
 however, this only logs ImageMagick commands. Shrine has full logging support,
-which measures processing, uploading and deleting individually, along with
-context for debugging:
+which measures processing, uploading and deleting individually:
 
 ```rb
-Shrine.plugin :logging
+Shrine.plugin :instrumentation
 ```
 ```
-2015-10-09T20:06:06.676Z #25602: STORE[cache] ImageUploader[:avatar] User[29543] 1 file (0.1s)
-2015-10-09T20:06:06.854Z #25602: PROCESS[store]: ImageUploader[:avatar] User[29543] 1-3 files (0.22s)
-2015-10-09T20:06:07.133Z #25602: DELETE[destroyed]: ImageUploader[:avatar] User[29543] 3 files (0.07s)
+Metadata (32ms) – {:storage=>:store, :io=>StringIO, :uploader=>Shrine}
+Upload (1523ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :io=>StringIO, :upload_options=>{}, :uploader=>Shrine}
+Exists (755ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}
+Download (1002ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :download_options=>{}, :uploader=>Shrine}
+Delete (700ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}
 ```
 
 ## Attachments

data/doc/plugins/data_uri.md

@@ -26,6 +26,8 @@ You can also use `#data_uri=` and `#data_uri` methods directly on the
 attacher.data_uri = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA"
 ```
 
+## Errors
+
 If the data URI wasn't correctly parsed, an error message will be added to the
 attachment column. You can change the default error message:
 
@@ -54,7 +56,9 @@ load the `infer_extension` plugin to infer it from the MIME type.
 plugin :infer_extension
 ```
 
-## `Shrine.data_uri`
+## API
+
+### `Shrine.data_uri`
 
 If you just want to parse the data URI and create an IO object from it, you can
 do that with `Shrine.data_uri`. If the data URI cannot be parsed, a
@@ -86,10 +90,10 @@ io = Shrine.data_uri("data:,content", filename: "foo.txt")
 io.original_filename #=> "foo.txt"
 ```
 
-## `UploadedFile#data_uri` and `UploadedFile#base64`
+### `UploadedFile#data_uri` and `UploadedFile#base64`
 
-This plugin also adds UploadedFile#data_uri method, which returns a
-base64-encoded data URI of the file content, and UploadedFile#base64, which
+This plugin also adds `UploadedFile#data_uri` method, which returns a
+base64-encoded data URI of the file content, and `UploadedFile#base64`, which
 simply returns the file content base64-encoded.
 
 ```rb
@@ -97,6 +101,48 @@ uploaded_file.data_uri #=> "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA"
 uploaded_file.base64   #=> "iVBORw0KGgoAAAANSUhEUgAAAAUA"
 ```
 
+## Instrumentation
+
+If the `instrumentation` plugin has been loaded, the `data_uri` plugin adds
+instrumentation around data URI parsing.
+
+```rb
+# instrumentation plugin needs to be loaded *before* data_uri
+plugin :instrumentation
+plugin :data_uri
+```
+
+Parsing data URIs will trigger a `data_uri.shrine` event with the following
+payload:
+
+| Key         | Description                            |
+| :--         | :----                                  |
+| `:data_uri` | The data URI string                    |
+| `:uploader` | The uploader class that sent the event |
+
+A default log subscriber is added as well which logs these events:
+
+```
+Data URI (5ms) – {:uploader=>Shrine}
+```
+
+You can also use your own log subscriber:
+
+```rb
+plugin :data_uri, log_subscriber: -> (event) {
+  Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, uploader: event[:uploader])
+}
+```
+```
+{"name":"data_uri","duration":5,"uploader":"Shrine"}
+```
+
+Or disable logging altogether:
+
+```rb
+plugin :data_uri, log_subscriber: nil
+```
+
 [data_uri]: /lib/shrine/plugins/data_uri.rb
 [data URIs]: https://tools.ietf.org/html/rfc2397
 [HTML5 Canvas]: https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API

data/doc/plugins/derivation_endpoint.md

@@ -5,6 +5,30 @@ dynamically processing uploaded files on request. This allows you to create
 URLs to files that might not have been generated yet, and have the endpoint
 process them on-the-fly.
 
+## Contents
+
+* [Quick start](#quick-start)
+* [How it works](#how-it-works)
+  - [Performance](#performance)
+* [Derivation response](#derivation-response)
+* [Dynamic settings](#dynamic-settings)
+* [Host](#host)
+* [Prefix](#prefix)
+* [Expiration](#expiration)
+* [Response headers](#response-headers)
+  - [Content Type](#content-type)
+  - [Content Disposition](#content-disposition)
+  - [Cache Control](#cache-control)
+* [Uploading](#uploading)
+  - [Redirecting](#redirecting)
+  - [Deleting derivatives](#deleting-derivatives)
+* [Cache busting](#cache-busting)
+* [Accessing source file](#accessing-source-file)
+* [Downloading](#downloading)
+  - [Skipping download](#skipping-download)
+* [Derivation API](#derivation-api)
+* [Plugin Options](#plugin-options)
+
 ## Quick start
 
 We first load the plugin, providing a secret key and a path prefix to where the

data/doc/plugins/determine_mime_type.md

@@ -69,18 +69,60 @@ plugin :determine_mime_type, analyzer: -> (io, analyzers) do
 end
 ```
 
-## Other Usage
+## API
 
 You can also use the methods for determining the MIME type directly:
 
 ```rb
 # or YourUploader.determine_mime_type(io)
-Shrine.determine_mime_type(io) # calls the defined analyzer
-#=> "image/jpeg"
+Shrine.determine_mime_type(io) #=> "image/jpeg" (calls the defined analyzer)
+# or just
+Shrine.mime_type(io) #=> "image/jpeg" (calls the defined analyzer)
 
 # or YourUploader.mime_type_analyzers
-Shrine.mime_type_analyzers[:file].call(io) # calls a built-in analyzer
-#=> "image/jpeg"
+Shrine.mime_type_analyzers[:file].call(io) #=> "image/jpeg" (calls a built-in analyzer)
+```
+
+## Instrumentation
+
+If the `instrumentation` plugin has been loaded, the `determine_mime_type` plugin
+adds instrumentation around MIME type analyzation.
+
+```rb
+# instrumentation plugin needs to be loaded *before* determine_mime_type
+plugin :instrumentation
+plugin :determine_mime_type
+```
+
+Analyzing MIME type will trigger a `mime_type.shrine` event with the following
+payload:
+
+| Key         | Description                            |
+| :--         | :----                                  |
+| `:io`       | The IO object                          |
+| `:uploader` | The uploader class that sent the event |
+
+A default log subscriber is added as well which logs these events:
+
+```
+MIME Type (33ms) – {:io=>StringIO, :uploader=>Shrine}
+```
+
+You can also use your own log subscriber:
+
+```rb
+plugin :determine_mime_type, log_subscriber: -> (event) {
+  Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
+}
+```
+```
+{"name":"mime_type","duration":24,"io":"#<StringIO:0x00007fb7c5b08b80>","uploader":"Shrine"}
+```
+
+Or disable logging altogether:
+
+```rb
+plugin :determine_mime_type, log_subscriber: nil
 ```
 
 [determine_mime_type]: /lib/shrine/plugins/determine_mime_type.rb

data/doc/plugins/infer_extension.md

@@ -9,15 +9,7 @@ extension might not be known.
 plugin :infer_extension
 ```
 
-Ordinarily, the upload location will gain the inferred extension only if it
-couldn't be determined from the filename. However, you can pass `force: true`
-to force the inferred extension to be used rather than an extension from the
-original filename. This can be used to canonicalize extensions (jpg, jpeg =>
-jpeg), or replace an incorrect original extension.
-
-```rb
-plugin :infer_extension, force: true
-```
+## Inferrers
 
 By default `MIME::Types` will be used for inferring the extension, but you can
 also choose a different inferrer:
@@ -43,6 +35,8 @@ plugin :infer_extension, inferrer: -> (mime_type, inferrers) do
 end
 ```
 
+## API
+
 You can also use methods for inferring extension directly:
 
 ```rb
@@ -53,6 +47,48 @@ Shrine.extension_inferrers[:mime_types].call("image/jpeg")
 # => ".jpeg"
 ```
 
+## Instrumentation
+
+If the `instrumentation` plugin has been loaded, the `infer_extension` plugin
+adds instrumentation around inferring extension.
+
+```rb
+# instrumentation plugin needs to be loaded *before* infer_extension
+plugin :instrumentation
+plugin :infer_extension
+```
+
+Inferring extension will trigger a `extension.shrine` event with the following
+payload:
+
+| Key          | Description                            |
+| :--          | :----                                  |
+| `:mime_type` | MIME type to infer extension from      |
+| `:uploader`  | The uploader class that sent the event |
+
+A default log subscriber is added as well which logs these events:
+
+```
+Extension (5ms) – {:mime_type=>"image/jpeg", :uploader=>Shrine}
+```
+
+You can also use your own log subscriber:
+
+```rb
+plugin :infer_extension, log_subscriber: -> (event) {
+  Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
+}
+```
+```
+{"name":"extension","duration":5,"mime_type":"image/jpeg","uploader":"Shrine"}
+```
+
+Or disable logging altogether:
+
+```rb
+plugin :infer_extension, log_subscriber: nil
+```
+
 [infer_extension]: /lib/shrine/plugins/infer_extension.rb
 [mime-types]: https://github.com/mime-types/ruby-mime-types
 [mini_mime]: https://github.com/discourse/mini_mime