shrine 3.0.0.rc → 3.0.0

data/doc/plugins/activerecord.md

@@ -1,10 +1,12 @@
-# Active Record
+---
+title: Active Record
+---
 
 The [`activerecord`][activerecord] plugin adds [Active Record] integration to
 the attachment interface. It is built on top of the [`model`][model] plugin.
 
 ```rb
-plugin :activerecord
+Shrine.plugin :activerecord
 ```
 
 ## Attachment
@@ -78,6 +80,24 @@ Active Record currently has a [bug with transaction callbacks], so if you have
 any "after commit" callbacks, make sure to include Shrine's attachment module
 *after* they have all been defined.
 
+#### Overriding callbacks
+
+You can override any of the following attacher methods to modify callback
+behaviour:
+
+* `Attacher#activerecord_before_save`
+* `Attacher#activerecord_after_save`
+* `Attacher#activerecord_after_destroy`
+
+```rb
+class Shrine::Attacher
+  def activerecord_after_save
+    super
+    # ...
+  end
+end
+```
+
 #### Skipping Callbacks
 
 If you don't want the attachment module to add any callbacks to your model, you
@@ -195,10 +215,10 @@ The following persistence methods are added to `Shrine::Attacher`:
 
 See [persistence] docs for more details.
 
-[activerecord]: /lib/shrine/plugins/activerecord.rb
+[activerecord]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/activerecord.rb
 [Active Record]: https://guides.rubyonrails.org/active_record_basics.html
-[model]: /doc/plugins/model.md#readme
+[model]: https://shrinerb.com/docs/plugins/model
 [callbacks]: https://guides.rubyonrails.org/active_record_callbacks.html
 [bug with transaction callbacks]: https://github.com/rails/rails/issues/14493
-[validation]: /doc/plugins/validation.md#readme
-[persistence]: /doc/plugins/persistence.md#readme
+[validation]: https://shrinerb.com/docs/plugins/validation
+[persistence]: https://shrinerb.com/docs/plugins/persistence

data/doc/plugins/add_metadata.md

@@ -1,4 +1,6 @@
-# Add Metadata
+---
+title: Add Metadata
+---
 
 The [`add_metadata`][add_metadata] plugin provides a convenient method for
 extracting and adding custom metadata values.
@@ -114,4 +116,4 @@ add_metadata :bar do |io, metadata:, **|
 end
 ```
 
-[add_metadata]: /lib/shrine/plugins/add_metadata.rb
+[add_metadata]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/add_metadata.rb

data/doc/plugins/atomic_helpers.md

@@ -1,4 +1,6 @@
-# Atomic Helpers
+---
+title: Atomic Helpers
+---
 
 The [`atomic_helpers`][atomic_helpers] plugin provides API for retrieving and
 persisting attachments in a concurrency-safe way, which is useful when using
@@ -174,4 +176,4 @@ attacher.abstract_atomic_persist(**options) do |reloaded_attacher|
 end
 ```
 
-[atomic_helpers]: /lib/shrine/plugins/atomic_helpers.rb
+[atomic_helpers]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/atomic_helpers.rb

data/doc/plugins/backgrounding.md

@@ -1,4 +1,6 @@
-# Backgrounding
+---
+title: Backgrounding
+---
 
 The [`backgrounding`][backgrounding] plugin enables you to move promoting and
 deleting of files into background jobs. This is especially useful if you're
@@ -8,20 +10,10 @@ processing [derivatives] and storing files to a remote storage service.
 Shrine.plugin :backgrounding # load the plugin globally
 ```
 
-The plugin provides `Attacher.promote_block` and `Attacher.destroy_block`
-methods, which allow you to register blocks that will get executed in place of
-synchronous promotion and deletion. Inside them you can spawn your background
-jobs:
+## Setup
+
+Define background jobs that will promote and destroy attachments:
 
-```rb
-# register backgrounding blocks for all uploaders
-Shrine::Attacher.promote_block do
-  PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
-end
-Shrine::Attacher.destroy_block do
-  DestroyJob.perform_async(self.class.name, data)
-end
-```
 ```rb
 class PromoteJob
   include Sidekiq::Worker
@@ -50,12 +42,21 @@ class DestroyJob
 end
 ```
 
-If you don't want to apply backgrounding for all uploaders, you can register
-backgrounding blocks only for a specific uploader:
+Then, in your initializer, you can configure all uploaders to use these jobs:
+
+```rb
+Shrine::Attacher.promote_block do
+  PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
+end
+Shrine::Attacher.destroy_block do
+  DestroyJob.perform_async(self.class.name, data)
+end
+```
+
+Alternatively, you can setup backgrounding only for specific uploaders:
 
 ```rb
 class MyUploader < Shrine
-  # register backgrounding blocks only for this uploader
   Attacher.promote_block do
     PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
   end
@@ -65,20 +66,11 @@ class MyUploader < Shrine
 end
 ```
 
-Backgrounding will automatically get triggered as part of your attachment flow
-if you're using `Shrine::Attachment` with a persistence plugin such as
-`activerecord` or `sequel`:
-
-```rb
-photo = Photo.new
-photo.image = file
-photo.save    # spawns promote job
-photo.destroy # spawns destroy job
-```
+## How it works
 
-In terms of `Shrine::Attacher`, the background jobs are spawned on
-`Attacher#promote_cached` (called on `Attacher#finalize`) and
-`Attacher#destroy_attached`:
+If backgrounding blocks are registered, they will be automatically called on
+`Attacher#promote_cached` and `Attacher#destroy_previous` (called by
+`Attacher#finalize`), and `Attacher#destroy_attached`.
 
 ```rb
 attacher.assign(file)
@@ -86,23 +78,30 @@ attacher.finalize         # spawns promote job
 attacher.destroy_attached # spawns destroy job
 ```
 
-## Promotion
+These methods are automatically called as part of the attachment flow if you're
+using `Shrine::Attachment` with a persistence plugin such as `activerecord` or
+`sequel`.
 
-While background deletion acts only on file data, background promotion is more
-complex as it deals with persistence and concurrency safety:
+```rb
+photo = Photo.new
+photo.image = file
+photo.save    # spawns promote job
+photo.destroy # spawns destroy job
+```
+
+### Atomic promotion
+
+Inside the promote job, we use `Attacher.retrieve` and
+`Attacher#atomic_promote` for concurrency safety. These methods are provided
+by the [`atomic_helpers`][atomic_helpers] plugin, which is loaded automatically
+by your persistence plugin (`activerecord`, `sequel`).
 
 ```rb
 attacher = Shrine::Attacher.retrieve(model: record, name: name, file: file_data)
 attacher.atomic_promote
 ```
 
-The `Attacher.retrieve` and `Attacher#atomic_promote` methods are provided by
-the [`atomic_helpers`][atomic_helpers] plugin, which is automatically loaded by
-your persistence plugin (`activerecord`, `sequel`). They add concurrency safety
-by verifying that the attachment hasn't changed on the outside before or after
-promotion.
-
-When we remove the concurrency safety, promotion would look like this:
+Without concurrency safety, promotion would look like this:
 
 ```rb
 attacher = record.send(:"#{name}_attacher")
@@ -110,7 +109,7 @@ attacher.promote
 attacher.persist
 ```
 
-## Backgrounding blocks
+## Registering backgrounding blocks
 
 The blocks registered by `Attacher.promote_block` and `Attacher#destroy_block`
 are by default evaluated in context of a `Shrine::Attacher` instance. You can
@@ -154,6 +153,46 @@ photo.image = file
 photo.save # executes the promote block above
 ```
 
-[backgrounding]: /lib/shrine/plugins/backgrounding.rb
-[derivatives]: /doc/plugins/derivatives.md#readme
-[atomic_helpers]: /doc/plugins/atomic_helpers.md#readme
+## Calling backgrounding blocks
+
+If you want to call backgrounding blocks directly, you can do that by calling
+`Attacher#promote_background` and `Attacher#destroy_background`.
+
+```rb
+attacher.promote_background # calls promote block directly
+attacher.destroy_background # calls destroy block directly
+```
+
+Any options passed to these methods will be forwarded to the background block:
+
+```rb
+attacher.promote_background(foo: "bar")
+```
+```rb
+# with instance eval
+Shrine::Attacher.promote_block do |**options|
+  options #=> { foo: "bar" }
+end
+
+# without instance eval
+Shrine::Attacher.promote_block do |attacher, **options|
+  options #=> { foo: "bar" }
+end
+```
+
+## Disabling backgrounding
+
+If you've registered backgrounding blocks, but want to temporarily disable them
+and make the execution synchronous, you can override them on the attacher level
+and call the default behaviour:
+
+```rb
+photo.image_attacher.promote_block(&:promote)
+photo.image_attacher.destroy_block(&:destroy)
+
+# ... now promotion and deletion will be synchronous ...
+```
+
+[backgrounding]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/backgrounding.rb
+[derivatives]: https://shrinerb.com/docs/plugins/derivatives
+[atomic_helpers]: https://shrinerb.com/docs/plugins/atomic_helpers

data/doc/plugins/cached_attachment_data.md

@@ -1,4 +1,6 @@
-# Cached Attachment Data
+---
+title: Cached Attachment Data
+---
 
 The [`cached_attachment_data`][cached_attachment_data] plugin adds the ability
 to retain the cached file across form redisplays, which means the file doesn't
@@ -22,4 +24,4 @@ This method delegates to `Attacher#cached_data`:
 attacher.cached_data #=> '{"id":"38k25.jpg","storage":"cache","metadata":{...}}'
 ```
 
-[cached_attachment_data]: /lib/shrine/plugins/cached_attachment_data.rb
+[cached_attachment_data]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/cached_attachment_data.rb

data/doc/plugins/column.md

@@ -1,4 +1,6 @@
-# Column
+---
+title: Column
+---
 
 The [`column`][column] plugin provides interface for serializing and
 deserializing attachment data in format suitable for persisting in a database
@@ -87,4 +89,4 @@ Shrine::Attacher.new(column_serializer: Oj)  # use custom serializer
 Shrine::Attacher.new(column_serializer: nil) # disable serialization
 ```
 
-[column]: /lib/shrine/plugins/column.rb
+[column]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/column.rb

data/doc/plugins/data_uri.md

@@ -1,4 +1,6 @@
-# Data URI
+---
+title: Data URI
+---
 
 The [`data_uri`][data_uri] plugin enables you to upload files as [data URIs].
 This plugin is useful for example when using [HTML5 Canvas].
@@ -7,6 +9,8 @@ This plugin is useful for example when using [HTML5 Canvas].
 plugin :data_uri
 ```
 
+## Usage
+
 The plugin will add the `#<name>_data_uri` writer to your model, which parses
 the given data URI string and uploads it to temporary storage:
 
@@ -62,7 +66,7 @@ do that with `Shrine.data_uri`. If the data URI cannot be parsed, a
 `Shrine::Plugins::DataUri::ParseError` will be raised.
 
 ```rb
-# or YourUploader.data_uri("...")
+# or YourUploader.data_uri(...)
 io = Shrine.data_uri("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA")
 io.content_type #=> "image/png"
 io.size         #=> 21
@@ -87,7 +91,7 @@ io = Shrine.data_uri("data:,content", filename: "foo.txt")
 io.original_filename #=> "foo.txt"
 ```
 
-### Generating data URI
+## Generating data URI
 
 This plugin also adds `UploadedFile#data_uri` method, which returns a
 base64-encoded data URI of the file content, and `UploadedFile#base64`, which
@@ -119,7 +123,7 @@ payload:
 
 A default log subscriber is added as well which logs these events:
 
-```
+```plaintext
 Data URI (5ms) – {:uploader=>Shrine}
 ```
 
@@ -130,7 +134,7 @@ plugin :data_uri, log_subscriber: -> (event) {
   Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, uploader: event[:uploader])
 }
 ```
-```
+```plaintext
 {"name":"data_uri","duration":5,"uploader":"Shrine"}
 ```
 
@@ -140,6 +144,6 @@ Or disable logging altogether:
 plugin :data_uri, log_subscriber: nil
 ```
 
-[data_uri]: /lib/shrine/plugins/data_uri.rb
+[data_uri]: https://github.com/shrinerb/shrine/blob/master/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/default_storage.md

@@ -1,4 +1,6 @@
-# Default Storage
+---
+title: Default Storage
+---
 
 The [`default_storage`][default_storage] plugin allows you to change the
 default temporary and permanent storage a `Shrine::Attacher` object will use
@@ -39,5 +41,5 @@ Attacher.default_store { :other_store }
 The dynamic block is useful in combination with the
 [`dynamic_storage`][dynamic_storage] plugin.
 
-[default_storage]: /lib/shrine/plugins/default_storage.rb
-[dynamic_storage]: /doc/plugins/dynamic_storage.md#readme
+[default_storage]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/default_storage.rb
+[dynamic_storage]: https://shrinerb.com/docs/plugins/dynamic_storage

data/doc/plugins/default_url.md

@@ -1,4 +1,6 @@
-# Default URL
+---
+title: Default URL
+---
 
 The [`default_url`][default_url] plugin allows setting the URL which will be
 returned when there is no attached file.
@@ -56,4 +58,4 @@ plugin :default_url, host: "https://example.com"
 attacher.url #=> "https://example.com/avatar/missing.jpg"
 ```
 
-[default_url]: /lib/shrine/plugins/default_url.rb
+[default_url]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/default_url.rb

data/doc/plugins/delete_raw.md

@@ -1,4 +1,6 @@
-# Delete Raw
+---
+title: Delete Raw
+---
 
 The [`delete_raw`][delete_raw] plugin will automatically delete raw files that
 have been uploaded. This is especially useful when doing processing, to ensure
@@ -22,4 +24,4 @@ to the uploader:
 uploader.upload(file, delete: false)
 ```
 
-[delete_raw]: /lib/shrine/plugins/delete_raw.rb
+[delete_raw]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/delete_raw.rb

data/doc/plugins/derivation_endpoint.md

@@ -1,35 +1,12 @@
-# Derivation Endpoint
+---
+title: Derivation Endpoint
+---
 
 The [`derivation_endpoint`][derivation_endpoint] plugin provides a Rack app for
 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)
-* [Instrumentation](#instrumentation)
-
 ## Quick start
 
 We first load the plugin, providing a secret key and a path prefix to where the
@@ -91,7 +68,7 @@ generates an URL consisting of the configured [path prefix](#prefix),
 derivation name and arguments, serialized uploaded file, and an URL signature
 generated using the configured secret key:
 
-```
+```plaintext
 /  derivations/image  /  thumbnail  /  600/400  /  eyJmZvbyIb3JhZ2UiOiJzdG9yZSJ9  ?  signature=...
   └──── prefix ─────┘  └── name ──┘  └─ args ─┘  └─── serialized source file ───┘
 ```
@@ -434,6 +411,8 @@ fetch the original uploaded file, call the derivation block, upload the
 derivative to the storage, and serve the derivative. If the derivative does
 exist on checking, the endpoint will download the derivative and serve it.
 
+### Upload location
+
 The default upload location for derivatives is `<source id>/<name>-<args>`.
 This can be changed with the `:upload_location` option:
 
@@ -449,6 +428,8 @@ response won't know the appropriate `Content-Type` header value to set, and the
 generic `application/octet-stream` will be used. It's recommended to use the
 [`:type`](#content-type) option to set the appropriate `Content-Type` value.
 
+### Upload storage
+
 The target storage used is the same as for the source uploaded file. The
 `:upload_storage` option can be used to specify a different Shrine storage:
 
@@ -457,6 +438,8 @@ plugin :derivation_endpoint, upload: true,
                              upload_storage: :thumbnail_storage
 ```
 
+### Upload options
+
 Additional storage-specific upload options can be passed via `:upload_options`:
 
 ```rb
@@ -464,6 +447,8 @@ plugin :derivation_endpoint, upload: true,
                              upload_options: { acl: "public-read" }
 ```
 
+### Upload open options
+
 Additional storage-specific download options for the uploaded derivation result
 can be passed via `:upload_open_options`:
 
@@ -484,8 +469,7 @@ plugin :derivation_endpoint, upload: true,
                              upload_redirect: true
 ```
 
-In that case additional storage-specific URL options can be passed in for the
-redirect URL:
+Additional storage-specific URL options can be passed in for the redirect URL:
 
 ```rb
 plugin :derivation_endpoint, upload: true,
@@ -493,18 +477,58 @@ plugin :derivation_endpoint, upload: true,
                              upload_redirect_url_options: { public: true }
 ```
 
-If you are using the local filesystem storage, then redirecting does not make
-sense.
+Note that redirecting only makes sense if you're using remote storage services
+such as AWS S3 or Google Cloud Storage.
 
 ### Deleting derivatives
 
 When the original attachment is deleted, its uploaded derivatives will not be
-automatically deleted, you will need to do the deletion manually. You can do
-that by calling `Shrine::Derivation#delete` for each derivation you're using:
+automatically deleted, you will need to do the deletion manually. To ensure
+this gets called both on destroying and replacing, you can add that code to
+`Attacher#destroy`.
+
+The easiest way is to delete the directory containing your derivatives:
+
+```rb
+class ImageUploader < Shrine
+  class Attacher
+    def destroy(*args)
+      super
+
+      derivatives_directory = file.id
+      storage               = store.storage
+
+      storage.delete_prefixed(derivatives_directory)
+    end
+  end
+end
+```
+
+This is under the assumption that your storage implements `#delete_prefixed`
+and that you're using default [`:upload_location`](#upload-location).
+
+Alternatively, you can delete each derivative individually using
+`Derivation#delete`:
 
 ```rb
-# photo is the model and image is the file attachment
-photo.image.derivation(:thumbnail).delete
+class ImageUploader < Shrine
+  DERIVATIONS = [
+    [:thumbnail, 800, 800],
+    [:thumbnail, 600, 400],
+    [:thumbnail, 400, 300],
+    ...
+  ]
+
+  class Attacher
+    def destroy(*args)
+      super
+
+      DERIVATIONS.each do |args|
+        file.derivation(*args).delete
+      end
+    end
+  end
+end
 ```
 
 ## Cache busting
@@ -771,7 +795,7 @@ derivation.option(:upload_location)
 | `:download_options`            | Additional options to pass when downloading the source uploaded file                                                                  | `{}`                                                 |
 | `:expires_in`                  | Number of seconds after which the URL will not be available anymore                                                                   | `nil`                                                |
 | `:filename`                    | Filename the browser will assume when the derivative is downloaded to disk                                                            | `<name>-<args>-<source id basename>`                 |
-| `:host`                        | URL host to use when generated URLs                                                                                                   | `nil`                                                |
+| `:host`                        | URL host to use when for URLs                                                                                                         | `nil`                                                |
 | `:metadata`                    | List of metadata keys the source uploaded file should include in the derivation block                                                 | `[]`                                                 |
 | `:prefix`                      | Path prefix added to the URLs                                                                                                         | `nil`                                                |
 | `:secret_key`                  | Key used to sign derivation URLs in order to prevent tampering                                                                        | required                                             |
@@ -806,7 +830,7 @@ following payload:
 
 A default log subscriber is added as well which logs these events:
 
-```
+```plaintext
 Derivation (492ms) – {:name=>:thumbnail, :args=>[600, 600], :uploader=>Shrine}
 ```
 
@@ -822,7 +846,7 @@ plugin :derivation_endpoint, log_subscriber: -> (event) {
   )
 }
 ```
-```
+```plaintext
 {"name":"derivation","duration":492,"name":"thumbnail","args":[600,600],"uploader":"Shrine"}
 ```
 
@@ -832,7 +856,7 @@ Or disable logging altogether:
 plugin :derivation_endpoint, log_subscriber: nil
 ```
 
-[derivation_endpoint]: /lib/shrine/plugins/derivation_endpoint.rb
+[derivation_endpoint]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/derivation_endpoint.rb
 [ImageProcessing]: https://github.com/janko/image_processing
 [`Content-Type`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
 [`Content-Disposition`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition