shrine 2.18.1 → 2.19.0

data/doc/plugins/instrumentation.md

@@ -0,0 +1,170 @@
+# Instrumentation
+
+The [`instrumentation`][instrumentation] plugin sends events for various
+operations to a centralized notification component. In addition to that it
+provides default logging for these events.
+
+```rb
+Shrine.plugin :instrumentation
+```
+
+By default, the notification component is assumed to be
+[ActiveSupport::Notifications], but [dry-monitor] is supported as well:
+
+```rb
+# Gemfile
+gem "dry-monitor"
+```
+```rb
+require "dry-monitor"
+
+Shrine.plugin :instrumentation, notifications: Dry::Monitor::Notifications.new(:test)
+```
+
+## Logging
+
+By default, the `instrumentation` plugin adds logging to the instrumented
+events:
+
+```rb
+uploaded_file = Shrine.upload(StringIO.new("file"), :store)
+uploaded_file.exists?
+uploaded_file.download
+uploaded_file.delete
+```
+```
+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}
+```
+
+You can choose to log only certain events, e.g. we can exclude metadata
+extraction:
+
+```rb
+Shrine.plugin :instrumentation, log_events: [
+  :upload,
+  :exists,
+  :download,
+  :delete,
+]
+```
+
+You can also use your own log subscriber:
+
+```rb
+Shrine.plugin :instrumentation, log_subscriber: -> (event) {
+  Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
+}
+```
+```
+{"name":"metadata","duration":0,"storage":"store","io":"#<StringIO:0x00007fd1d4a1b9d8>","options":{},"uploader":"Shrine"}
+{"name":"upload","duration":0,"storage":"store","location":"dbeb3c3ed664059eb41a608e54a29f54","io":"#<StringIO:0x00007fd1d4a1b9d8>","upload_options":{},"options":{"location":"dbeb3c3ed664059eb41a608e54a29f54","metadata":{"filename":null,"size":4,"mime_type":null}},"uploader":"Shrine"}
+{"name":"exists","duration":0,"storage":"store","location":"dbeb3c3ed664059eb41a608e54a29f54","uploader":"Shrine"}
+{"name":"download","duration":0,"storage":"store","location":"dbeb3c3ed664059eb41a608e54a29f54","download_options":{},"uploader":"Shrine"}
+{"name":"delete","duration":0,"storage":"store","location":"dbeb3c3ed664059eb41a608e54a29f54","uploader":"Shrine"}
+```
+
+Or disable logging altogether:
+
+```rb
+Shrine.plugin :instrumentation, log_subscriber: nil
+```
+
+## Events
+
+The following events are instrumented by the `instrumentation` plugin:
+
+* [`upload.shrine`](#uploadshrine)
+* [`download.shrine`](#downloadshrine)
+* [`exists.shrine`](#existsshrine)
+* [`delete.shrine`](#deleteshrine)
+* [`metadata.shrine`](#metadatashrine)
+
+### upload.shrine
+
+The `upload.shrine` event is logged on `Shrine#upload`, and contains the
+following payload:
+
+| Key               | Description                            |
+| :--               | :----                                  |
+| `:storage`        | The storage identifier                 |
+| `:location`       | The location of the uploaded file      |
+| `:io`             | The uploaded IO object                 |
+| `:upload_options` | Any upload options that were specified |
+| `:options`        | Some additional context information    |
+| `:uploader`       | The uploader class that sent the event |
+
+### download.shrine
+
+The `download.shrine` event is logged on `UploadedFile#open` (which includes
+`UploadedFile#download` and `UploadedFile#stream` methods as well), and
+contains the following payload:
+
+| Key               | Description                            |
+| :--               | :----                                  |
+| `:storage`        | The storage identifier                 |
+| `:location`       | The location of the uploaded file      |
+| `:download_options` | Any upload options that were specified |
+| `:uploader`       | The uploader class that sent the event |
+
+### exists.shrine
+
+The `exists.shrine` event is logged on `UploadedFile#exists?`, and contains the
+following payload:
+
+| Key               | Description                            |
+| :--               | :----                                  |
+| `:storage`        | The storage identifier                 |
+| `:location`       | The location of the uploaded file      |
+| `:uploader`       | The uploader class that sent the event |
+
+### delete.shrine
+
+The `delete.shrine` event is logged on `UploadedFile#delete`, and contains the
+following payload:
+
+| Key               | Description                            |
+| :--               | :----                                  |
+| `:storage`        | The storage identifier                 |
+| `:location`       | The location of the uploaded file      |
+| `:uploader`       | The uploader class that sent the event |
+
+### metadata.shrine
+
+The `metadata.shrine` event is logged on `Shrine#upload`, and contains the
+following payload:
+
+| Key               | Description                            |
+| :--               | :----                                  |
+| `:storage`        | The storage identifier                 |
+| `:io`             | The uploaded IO object                 |
+| `:options`        | Some additional context information    |
+| `:uploader`       | The uploader class that sent the event |
+
+## API
+
+The `instrumentation` plugin adds `Shrine.instrument` and `Shrine.subscribe`
+methods:
+
+```rb
+# sends a `my_event.shrine` event to the notifications component
+Shrine.instrument(:my_event, foo: "bar") do
+  # do work
+end
+```
+```rb
+# subscribes to `my_event.shrine` events on the notifications component
+Shrine.subscribe(:my_event) do |event|
+  event.name #=> :my_event
+  event.payload #=> { foo: "bar", uploader: Shrine }
+  event[:foo] #=> "bar"
+  event.duration #=> 15 (in milliseconds)
+end
+```
+
+[instrumentation]: /lib/shrine/plugins/instrumentation.rb
+[ActiveSupport::Notifications]: https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html
+[dry-monitor]: https://github.com/dry-rb/dry-monitor

data/doc/plugins/presign_endpoint.md

@@ -69,7 +69,7 @@ class PresignsController < ApplicationController
   def image
     # ... we can perform authentication here ...
 
-    set_rack_response ImageUploader.presign_response(:cache, env)
+    set_rack_response ImageUploader.presign_response(:cache, request.env)
   end
 
   private

data/doc/plugins/pretty_location.md

@@ -28,4 +28,27 @@ plugin :pretty_location, namespace: "/"
 # "blog/user/.../493g82jf23.jpg"
 ```
 
+By default, if there is a record present, the record `id` will is used in the location.
+If you want to use a different identifier for the record, you can pass in
+the `:identifier` option with the desired method/attribute name as the value:
+
+```rb
+plugin :pretty_location, identifier: "uuid"
+# "user/aa357797-5845-451b-8662-08eecdc9f762/profile_picture/493g82jf23.jpg"
+
+plugin :pretty_location, identifier: :email
+# "user/foo@bar.com/profile_picture/493g82jf23.jpg"
+```
+
+For a more custom identifier logic, you can overwrite the method
+`#generate_location` and call `#pretty_location` with the identifier you have
+calculated.
+
+```rb
+def generate_location(io, record: nil, **context)
+  identifier = record.email if record.is_a?(User)
+  pretty_location(io, record: record, identifier: identifier, **context)
+end
+```
+
 [pretty_location]: /lib/shrine/plugins/pretty_location.rb

data/doc/plugins/remote_url.md

@@ -27,9 +27,9 @@ You can also use `#remote_url=` and `#remote_url` methods directly on the
 attacher.remote_url = "http://example.com/cool-image.png"
 ```
 
-The file will by default be downloaded using [Down], which is a wrapper around
-the `open-uri` standard library. Note that Down expects the given URL to be
-URI-encoded.
+By default, the file will be downloaded using `Down.download` from the [Down]
+gem. This will use the `Down::NetHttp` backend by default, which is a wrapper
+around [open-uri].
 
 ## Dynamic options
 
@@ -67,16 +67,22 @@ plugin :remote_url, max_size: nil
 
 If you want to customize how the file is downloaded, you can override the
 `:downloader` parameter and provide your own implementation. For example, you
-can use the HTTP.rb Down backend for downloading:
+can use the [http.rb] Down backend for downloading:
 
+```rb
+# Gemfile
+gem "http"
+```
 ```rb
 require "down/http"
 
-plugin :remote_url, max_size: 20*1024*1024, downloader: -> (url, max_size:, **options) do
-  Down::Http.download(url, max_size: max_size, **options) do |http|
-    http.follow(max_hops: 2).timeout(connect: 2, read: 2)
-  end
+down = Down::Http.new do |client|
+  client
+    .follow(max_hops: 2)
+    .timeout(connect: 2, read: 2)
 end
+
+plugin :remote_url, max_size: 20*1024*1024, downloader: down.method(:download)
 ```
 
 ## Errors
@@ -107,6 +113,51 @@ load the `infer_extension` plugin to infer it from the MIME type.
 plugin :infer_extension
 ```
 
+## Instrumentation
+
+If the `instrumentation` plugin has been loaded, the `remote_url` plugin adds
+instrumentation around remote URL downloading.
+
+```rb
+# instrumentation plugin needs to be loaded *before* remote_url
+plugin :instrumentation
+plugin :remote_url
+```
+
+Downloading remote URLs will trigger a `remote_url.shrine` event with the
+following payload:
+
+| Key                 | Description                            |
+| :--                 | :----                                  |
+| `:remote_url`       | The remote URL string                  |
+| `:download_options` | Any download options passed in         |
+| `:uploader`         | The uploader class that sent the event |
+
+A default log subscriber is added as well which logs these events:
+
+```
+Remote URL (1550ms) – {:remote_url=>"https://example.com/image.jpg",:download_options=>{},:uploader=>Shrine}
+```
+
+You can also use your own log subscriber:
+
+```rb
+plugin :remote_url, log_subscriber: -> (event) {
+  Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
+}
+```
+```
+{"name":"remote_url","duration":5,"remote_url":"https://example.com/image.jpg","download_options":{},"uploader":"Shrine"}
+```
+
+Or disable logging altogether:
+
+```rb
+plugin :remote_url, log_subscriber: nil
+```
+
 [remote_url]: /lib/shrine/plugins/remote_url.rb
 [Down]: https://github.com/janko/down
+[open-uri]: https://ruby-doc.org/stdlib/libdoc/open-uri/rdoc/OpenURI.html
+[http.rb]: https://github.com/httprb/http
 [shrine-url]: https://github.com/shrinerb/shrine-url

data/doc/plugins/signature.md

@@ -8,15 +8,31 @@ signature for the uploaded file.
 Shrine.plugin :signature
 ```
 
+## API
+
 The plugin adds a `#calculate_signature` instance and class method to the
 uploader. The method accepts an IO object and a hashing algorithm, and returns
 the calculated hash.
 
 ```rb
-Shrine.calculate_signature(io, :md5)
-#=> "9a0364b9e99bb480dd25e1f0284c8555"
+Shrine.calculate_signature(io, :md5) #=> "9a0364b9e99bb480dd25e1f0284c8555"
+# or just
+Shrine.signature(io, :md5) #=> "9a0364b9e99bb480dd25e1f0284c8555"
 ```
 
+The following hashing algorithms are supported: SHA1, SHA256, SHA384, SHA512,
+MD5, and CRC32.
+
+You can also choose which format will the calculated hash be encoded in:
+
+```rb
+Shrine.calculate_signature(io, :sha256, format: :base64)
+```
+
+The supported encoding formats are `hex` (default), `base64`, and `none`.
+
+## Adding metadata
+
 You can then use the `add_metadata` plugin to add a new metadata field with the
 calculated hash.
 
@@ -37,15 +53,46 @@ add_metadata :md5 do |io, context|
 end
 ```
 
-The following hashing algorithms are supported: SHA1, SHA256, SHA384, SHA512,
-MD5, and CRC32.
+## Instrumentation
 
-You can also choose which format will the calculated hash be encoded in:
+If the `instrumentation` plugin has been loaded, the `signature` plugin adds
+instrumentation around signature calculation.
 
 ```rb
-Shrine.calculate_signature(io, :sha256, format: :base64)
+# instrumentation plugin needs to be loaded *before* signature
+plugin :instrumentation
+plugin :signature
 ```
 
-The supported encoding formats are `hex` (default), `base64`, and `none`.
+Calculating signature will trigger a `signature.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 :signature, log_subscriber: -> (event) {
+  Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
+}
+```
+```
+{"name":"signature","duration":24,"io":"#<StringIO:0x00007fb7c5b08b80>","uploader":"Shrine"}
+```
+
+Or disable logging altogether:
+
+```rb
+plugin :signature, log_subscriber: nil
+```
 
 [signature]: /lib/shrine/plugins/signature.rb

data/doc/plugins/store_dimensions.md

@@ -8,6 +8,8 @@ uploaded images and stores them into the metadata hash (by default it uses the
 plugin :store_dimensions
 ```
 
+## Metadata
+
 The dimensions are stored as "width" and "height" metadata values on the
 Shrine::UploadedFile object. For convenience the plugin also adds `#width`,
 `#height` and `#dimensions` reader methods.
@@ -24,6 +26,8 @@ image.height #=> 500
 image.dimensions #=> [300, 500]
 ```
 
+## Analyzers
+
 By default the [fastimage] gem is used to extract dimensions. You can choose a
 different built-in analyzer via the `:analyzer` option:
 
@@ -52,16 +56,77 @@ plugin :store_dimensions, analyzer: -> (io, analyzers) do
 end
 ```
 
+## API
+
 You can use methods for extracting the dimensions directly:
 
 ```rb
 # or YourUploader.extract_dimensions(io)
-Shrine.extract_dimensions(io) # calls the defined analyzer
-#=> [300, 400]
+Shrine.extract_dimensions(io) #=> [300, 400] (calls the defined analyzer)
+# or just
+Shrine.dimensions(io) #=> [300, 400] (calls the defined analyzer)
 
 # or YourUploader.dimensions_analyzers
-Shrine.dimensions_analyzers[:fastimage].call(io) # calls a built-in analyzer
-#=> [300, 400]
+Shrine.dimensions_analyzers[:fastimage].call(io) #=> [300, 400] (calls a built-in analyzer)
+```
+
+## Errors
+
+By default, any exceptions that the analyzer raises while extracting dimensions
+will be caught and a warning will be printed out. This allows you to have the
+plugin loaded even for files that are not images.
+
+However, you can choose different strategies for handling these exceptions:
+
+```rb
+plugin :store_dimensions, on_error: :warn        # prints a warning (default)
+plugin :store_dimensions, on_error: :fail        # raises the exception
+plugin :store_dimensions, on_error: :ignore      # ignores exceptions
+plugin :store_dimensions, on_error: -> (error) { # custom handler
+  # report the exception to your exception handler
+}
+```
+
+## Instrumentation
+
+If the `instrumentation` plugin has been loaded, the `store_dimensions` plugin
+adds instrumentation around dimensions extraction.
+
+```rb
+# instrumentation plugin needs to be loaded *before* store_dimensions
+plugin :instrumentation
+plugin :store_dimensions
+```
+
+Extracting metadata will send a `image_dimensions.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:
+
+```
+Image Dimensions (108ms) – {:io=>File, :uploader=>Shrine}
+```
+
+You can also use your own log subscriber:
+
+```rb
+plugin :store_dimensions, log_subscriber: -> (event) {
+  Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
+}
+```
+```
+{"name":"image_dimensions","duration":114,"io":"#<File:0x00007fc445371d90>","uploader":"Shrine"}
+```
+
+Or disable logging altogether:
+
+```rb
+plugin :store_dimensions, log_subscriber: nil
 ```
 
 [store_dimensions]: /lib/shrine/plugins/store_dimensions.rb