shrine 3.0.0.alpha → 3.0.0.beta

data/doc/plugins/default_url.md

@@ -1,7 +1,7 @@
 # Default URL
 
 The [`default_url`][default_url] plugin allows setting the URL which will be
-returned when the attachment is missing.
+returned when there is no attached file.
 
 ```rb
 plugin :default_url
@@ -11,13 +11,24 @@ Attacher.default_url do |options|
 end
 ```
 
-`Attacher#url` returns the default URL when attachment is missing. Any passed
-in URL options will be present in the `options` hash.
+The `Attacher#url` method will return the default URL when attachment is
+missing:
 
 ```rb
-attacher.url #=> "/avatar/missing.jpg"
-# or
 user.avatar_url #=> "/avatar/missing.jpg"
+# or
+attacher.url #=> "/avatar/missing.jpg"
+```
+
+Any URL options passed will be available in the default URL block:
+
+```rb
+attacher.url(foo: "bar")
+```
+```rb
+Attacher.default_url do |options|
+  options #=> { foo: "bar" }
+end
 ```
 
 The default URL block is evaluated in the context of an instance of
@@ -25,10 +36,11 @@ The default URL block is evaluated in the context of an instance of
 
 ```rb
 Attacher.default_url do |options|
-  self #=> #<Shrine::Attacher>
+  self    #=> #<Shrine::Attacher>
 
-  name   #=> :avatar
-  record #=> #<User>
+  name    #=> :avatar
+  record  #=> #<User>
+  context #=> { ... }
 end
 ```
 
@@ -41,7 +53,7 @@ option:
 plugin :default_url, host: "https://example.com"
 ```
 ```rb
-user.avatar_url #=> "https://example.com/avatar/missing.jpg"
+attacher.url #=> "https://example.com/avatar/missing.jpg"
 ```
 
 [default_url]: /lib/shrine/plugins/default_url.rb

data/doc/plugins/derivation_endpoint.md

@@ -28,6 +28,7 @@ process them on-the-fly.
   - [Skipping download](#skipping-download)
 * [Derivation API](#derivation-api)
 * [Plugin Options](#plugin-options)
+* [Instrumentation](#instrumentation)
 
 ## Quick start
 
@@ -785,6 +786,53 @@ derivation.option(:upload_location)
 | `:upload_storage`              | Storage to which the derivations will be uploaded                                                                                     | same storage as the source file                      |
 | `:version`                     | Version number to append to the URL for cache busting                                                                                 | `nil`                                                |
 
+## Instrumentation
+
+If the `instrumentation` plugin has been loaded, the `determine_mime_type` plugin
+adds instrumentation around derivation processing.
+
+```rb
+# instrumentation plugin needs to be loaded *before* derivation_endpoint
+plugin :instrumentation
+plugin :derivation_endpoint
+```
+
+Derivation processing will trigger a `derivation.shrine` event with the
+following payload:
+
+| Key           | Description                                     |
+| :--           | :----                                           |
+| `:derivation` | `Shrine::Derivation` object for this processing |
+| `:uploader`   | The uploader class that sent the event          |
+
+A default log subscriber is added as well which logs these events:
+
+```
+Derivation (492ms) – {:name=>:thumbnail, :args=>[600, 600], :uploader=>Shrine}
+```
+
+You can also use your own log subscriber:
+
+```rb
+plugin :derivation_endpoint, log_subscriber: -> (event) {
+  Shrine.logger.info JSON.generate(
+    name:     event.name,
+    duration: event.duration,
+    name:     event[:derivation].name,
+    args:     event[:derivation].args,
+  )
+}
+```
+```
+{"name":"derivation","duration":492,"name":"thumbnail","args":[600,600],"uploader":"Shrine"}
+```
+
+Or disable logging altogether:
+
+```rb
+plugin :derivation_endpoint, log_subscriber: nil
+```
+
 [derivation_endpoint]: /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

data/doc/plugins/derivatives.md

@@ -12,6 +12,7 @@ plugin :derivatives
 
 * [API overview](#api-overview)
 * [Creating derivatives](#creating-derivatives)
+  - [Derivatives storage](#derivatives-storage)
   - [Nesting derivatives](#nesting-derivatives)
 * [Retrieving derivatives](#retrieving-derivatives)
 * [Derivative URL](#derivative-url)
@@ -20,7 +21,6 @@ plugin :derivatives
   - [Source file](#source-file)
 * [Adding derivatives](#adding-derivatives)
 * [Uploading derivatives](#uploading-derivatives)
-  - [Derivatives storage](#derivatives-storage)
   - [Uploader options](#uploader-options)
   - [File deletion](#file-deletion)
 * [Merging derivatives](#merging-derivatives)
@@ -50,8 +50,8 @@ class, and it's layered in the following way:
 
 When you have a file attached, you can generate derivatives from it and save
 them alongside the attached file. The simplest way to do this is to define a
-processor which returns the processed files, and then trigger it with
-`Attacher#create_derivatives` when you want to generate the derivatives.
+processor which returns the processed files, and then trigger it when you want
+to create derivatives.
 
 Here is an example of generating image thumbnails:
 
@@ -85,7 +85,7 @@ end
 photo.image #=> #<Shrine::UploadedFile @id="original.jpg" @storage_key=:store ...>
 photo.image_derivatives #=> {}
 
-photo.image_attacher.create_derivatives(:thumbnails) # calls processor and uploads results
+photo.image_derivatives!(:thumbnails) # calls registered processor and uploads results
 photo.image_derivatives #=>
 # {
 #   small:  #<Shrine::UploadedFile @id="small.jpg" @storage_key=:store ...>,
@@ -111,12 +111,68 @@ photo.image_data #=>
 # }
 ```
 
-Any additional options passed to `Attacher#create_derivatives` are forwarded to
-[`Attacher#upload_derivatives`](#uploading-derivatives).
+When using `Shrine::Attacher` directly, derivatives are created using
+`Attacher#create_derivatives`:
+
+```rb
+attacher.file #=> #<Shrine::UploadedFile @id="original.jpg" @storage_key=:store ...>
+attacher.derivatives #=> {}
+
+attacher.create_derivatives(:thumbnails) # calls registered processor and uploads results
+attacher.derivatives #=>
+# {
+#   small:  #<Shrine::UploadedFile @id="small.jpg" @storage_key=:store ...>,
+#   medium: #<Shrine::UploadedFile @id="medium.jpg" @storage_key=:store ...>,
+#   large:  #<Shrine::UploadedFile @id="large.jpg" @storage_key=:store ...>,
+# }
+```
+
+### Derivatives storage
+
+By default, derivatives are uploaded to the permanent storage of the attacher.
+You can change the default destination storage with the `:storage` plugin
+option:
 
 ```rb
-attacher.create_derivatives(:thumbnails, storage: :other_store)                  # specify destination storage
-attacher.create_derivatives(:thumbnails, upload_options: { acl: "public-read" }) # pass uploader options
+plugin :derivatives, storage: :other_store
+```
+
+The storage can be dynamic based on the derivative name:
+
+```rb
+plugin :derivatives, storage: -> (derivative) do
+  if derivative == :thumb
+    :thumbnail_store
+  else
+    :store
+  end
+end
+```
+
+You can also set this option with `Attacher.derivatives_storage`:
+
+```rb
+Attacher.derivatives_storage :other_store
+# or
+Attacher.derivatives_storage do |derivative|
+  if derivative == :thumb
+    :thumbnail_store
+  else
+    :store
+  end
+end
+```
+
+The storage block is evaluated in the context of a `Shrine::Attacher` instance:
+
+```rb
+Attacher.derivatives_storage do |derivative|
+  self   #=> #<Shrine::Attacher>
+
+  record  #=> #<Photo>
+  name    #=> :image
+  context #=> { ... }
+end
 ```
 
 ### Nesting derivatives
@@ -284,8 +340,8 @@ Attacher.derivatives_processor :my_processor do |original|
 end
 ```
 
-Moreover, any options passed to `Attacher#process_derivatives` will be
-forwarded to the processor:
+Moreover, any options passed to `Attacher#process_derivatives` (or
+`Attacher#create_derivatives`) will be forwarded to the processor:
 
 ```rb
 attacher.process_derivatives(:my_processor, foo: "bar")
@@ -315,7 +371,7 @@ attacher.process_derivatives(:my_processor) # downloads attached file and passes
 If you already have the source file locally, or if you're calling multiple
 processors in a row and want to avoid downloading the same source file each
 time, you can pass the source file as the second argument to
-`Attacher#process_derivatives`:
+`Attacher#process_derivatives` (or `Attacher#create_derivatives`):
 
 ```rb
 # this way the source file is downloaded only once
@@ -406,63 +462,18 @@ attacher.upload_derivative(:thumb, thumbnail_file)
 #=> #<Shrine::UploadedFile>
 ```
 
-### Derivatives storage
-
-By default, derivatives are uploaded to the permanent storage of the attacher
-(`:store` by default). You can specify a different destination storage for
-`Attacher#upload_derivative(s)` with the `:storage` option:
-
-```rb
-attacher.upload_derivatives(derivatives, storage: :other_store)
-```
-
-You can also set a default derivatives storage on the plugin level:
-
-```rb
-plugin :derivatives, storage: :other_store
-```
-
-The storage can be dynamic based on the derivative name:
-
-```rb
-plugin :derivatives, storage: -> (derivative) do
-  if derivative == :thumb
-    :thumbnail_store
-  else
-    :store
-  end
-end
-```
-
-You can also set this option with `Attacher.derivatives_storage`:
-
-```rb
-Attacher.derivatives_storage :other_store
-# or
-Attacher.derivatives_storage do |derivative|
-  if derivative == :thumb
-    :thumbnail_store
-  else
-    :store
-  end
-end
-```
+### Uploader options
 
-The storage block is evaluated in the context of a `Shrine::Attacher` instance:
+You can specify the destination storage by passing `:storage` option to
+`Attacher#upload_derivative(s)`. This will override the [default derivatives
+storage](#derivatives-storage) setting.
 
 ```rb
-Attacher.derivatives_storage do |derivative|
-  self   #=> #<Shrine::Attacher>
-
-  record  #=> #<Photo>
-  name    #=> :image
-  context #=> { ... }
-end
+attacher.upload_derivative(:thumb, thumnbail_file, storage: :other_store)
+#=> #<Shrine::UploadedFile @id="thumb.jpg" @storage_key=:other_store ...>
 ```
 
-### Uploader options
-
-Any options other than `:storage` will be forwarded to the uploader:
+Any other options will be forwarded to the uploader:
 
 ```rb
 attacher.upload_derivative :thumb, thumbnail_file,

data/doc/plugins/entity.md

@@ -102,6 +102,19 @@ attacher = photo.image_attacher
 attacher.store_key #=> :other_store
 ```
 
+You can retrieve an `Attacher` instance from the entity *class* as well. In
+this case it will not be initialized with any entity instance.
+
+```rb
+attacher = Photo.image_attacher
+attacher #=> #<ImageUploader::Attacher>
+attacher.record #=> nil
+attacher.name   #=> nil
+
+attacher = Photo.image_attacher(store: :other_store)
+attacher.store_key #=> :other_store
+```
+
 ## Attacher
 
 ### Loading entity
@@ -133,9 +146,21 @@ You can also load an entity into an existing attacher with
 ```rb
 photo = Photo.new(image_data: '{"id":"...","storage":"...","metadata":{...}}')
 
-attacher.file #=> nil
 attacher.load_entity(photo, :image)
-attacher.file #=> #<ImageUploader::UploadedFile>
+attacher.record #=> #<Photo>
+attacher.name   #=> :image
+attacher.file   #=> #<ImageUploader::UploadedFile>
+```
+
+Or just `Attacher#set_entity` if you don't want to load attachment data:
+
+```rb
+photo = Photo.new(image_data: '{"id":"...","storage":"...","metadata":{...}}')
+
+attacher.set_entity(photo, :image) # doesn't load attachment data
+attacher.record #=> #<Photo>
+attacher.name   #=> :image
+attacher.file   #=> nil
 ```
 
 ### Reloading

data/doc/plugins/included.md

@@ -1,18 +1,19 @@
 # Included
 
 The [`included`][included] plugin allows you to hook up to the `.included` hook
-of the attachment module, and call additional methods on the model which
+of the attachment module, and call additional methods on the model that
 includes it.
 
 ```rb
 plugin :included do |name|
-  before_save do
-    # ...
-  end
+  # called when attachment module is included into a model
+
+  self #=> #<Photo>
+  name #=> :image
 end
 ```
-
-If you want to define additional methods on the model, it's recommended to use
-the `module_include` plugin instead.
+```rb
+Photo.include Shrine::Attachment(:image)
+```
 
 [included]: /lib/shrine/plugins/included.rb

data/doc/plugins/metadata_attributes.md

@@ -7,7 +7,9 @@ method:
 
 ```rb
 plugin :metadata_attributes, :size => :size, :mime_type => :type
+
 # or
+
 plugin :metadata_attributes
 Attacher.metadata_attributes :size => :size, :mime_type => :type
 ```
@@ -28,19 +30,32 @@ user.avatar_size #=> nil
 user.avatar_type #=> nil
 ```
 
+If you're using the [`entity`][entity] plugin, metadata attributes will be
+added to `Attacher#column_values`:
+
+```rb
+attacher.assign(io)
+attacher.column_values #=>
+# {
+#   :image_data => '{ ... }',
+#   :image_size => 95724,
+#   :image_type => "image/jpeg",
+# }
+```
+
 If you want to specify the full record attribute name, pass the record
 attribute name as a string instead of a symbol.
 
 ```rb
 Attacher.metadata_attributes :filename => "original_filename"
-
-# ...
-
+```
+```rb
 photo.image = image
 photo.original_filename #=> "nature.jpg"
 ```
 
-If any corresponding metadata attribute doesn't exist on the record, that
-metadata sync will be silently skipped.
+Any metadata attributes that were declared but are missing on the record will
+be skipped.
 
 [metadata_attributes]: /lib/shrine/plugins/metadata_attributes.rb
+[entity]: /doc/plugins/entity.md#readme

data/doc/plugins/model.md

@@ -41,6 +41,17 @@ photo.image.storage_key #=> :cache
 photo.image_data        #=> '{"id":"...","storage":"cache","metadata":{...}}'
 ```
 
+#### `#<name>_changed?`
+
+Calls `Attacher#changed?` which returns whether the attachment has changed.
+
+```rb
+photo = Photo.new
+photo.image_changed? #=> false
+photo.image = file
+photo.image_changed? #=> true
+```
+
 #### Disabling caching
 
 If you don't want to use temporary storage, you can have `#<name>=` upload
@@ -118,14 +129,23 @@ You can also load an entity into an existing attacher with
 `Attacher#load_model`.
 
 ```rb
-photo    = Photo.new(image_data: '{"id":"...","storage":"...","metadata":{...}}')
-attacher = ImageUploader::Attacher.from_model(photo, :image)
+photo = Photo.new(image_data: '{"id":"...","storage":"...","metadata":{...}}')
 
 attacher.file #=> nil
 attacher.load_model(photo, :image)
 attacher.file #=> #<ImageUploader::UploadedFile>
 ```
 
+Or just `Attacher#set_model` if you don't want to load attachment data:
+
+```rb
+photo = Photo.new(image_data: '{"id":"...","storage":"...","metadata":{...}}')
+
+attacher.file #=> nil
+attacher.set_model(photo, :image) # doesn't load attachment data
+attacher.file #=> nil
+```
+
 ### Writing attachment data
 
 The `Attacher#write` method writes attachment data to the `#<name>_data`

data/doc/plugins/persistence.md

@@ -0,0 +1,89 @@
+# Persistence
+
+This is an internal plugin that provides uniform persistence interface across
+different persistence plugins (e.g. [`activerecord`][activerecord],
+[`sequel`][sequel]).
+
+## Atomic promotion
+
+If you're promoting cached file to permanent storage
+[asynchronously][backgrounding], and want to handle the possibility of
+attachment changing during promotion, you can use `Attacher#atomic_promote`:
+
+```rb
+# in your controller
+attacher.attach_cached(io)
+attacher.cached? #=> true
+```
+```rb
+# in a background job
+attacher.atomic_promote # promotes cached file and persists
+attacher.stored? #=> true
+```
+
+After the cached file is uploaded to permanent storage, the record is reloaded
+in order to check whether the attachment hasn't changed, and if it hasn't the
+attachment is persisted. If the attachment has changed,
+`Shrine::AttachmentChanged` exception is raised.
+
+If you want to execute code after the attachment change check but before
+persistence, you can pass a block:
+
+```rb
+attacher.atomic_promote do |reloaded_attacher|
+  # run code after attachment change check but before persistence
+end
+```
+
+You can pass `:reload` and `:persist` options to change how the record is
+reloaded and pesisted. See the [`atomic_helpers`][atomic_helpers] plugin docs
+for more details.
+
+Any other options are forwarded to `Attacher#promote`:
+
+```rb
+attacher.atomic_promote(metadata: true) # re-extract metadata
+```
+
+## Atomic persistence
+
+If you're updating something based on the attached file
+[asynchronously][backgrounding], you might want to handle the possibility of
+the attachment changing in the meanwhile. You can do that with
+`Attacher#atomic_persist`:
+
+```rb
+# in a background job
+attacher.refresh_metadata! # refresh_metadata plugin
+attacher.atomic_persist # persists attachment data
+```
+
+The record is first reloaded in order to check whether the attachment hasn't
+changed, and if it hasn't the attachment is persisted. If the attachment has
+changed, `Shrine::AttachmentChanged` exception is raised.
+
+If you want to execute code after the attachment change check but before
+persistence, you can pass a block:
+
+```rb
+attacher.atomic_persist do |reloaded_attacher|
+  # run code after attachment change check but before persistence
+end
+```
+
+You can pass `:reload` and `:persist` options to change how the record is
+reloaded and pesisted. See the [`atomic_helpers`][atomic_helpers] plugin docs
+for more details.
+
+## Simple Persistence
+
+To simply save attachment changes to the underlying record, use
+`Attacher#persist`:
+
+```rb
+attacher.attach(io)
+attacher.persist # saves the underlying record
+```
+
+[activerecord]: /doc/plugins/activerecord.md#readme
+[sequel]: /doc/plugins/sequel.md#readme