shrine 2.19.4 → 3.0.0.alpha

data/doc/plugins/entity.md

@@ -0,0 +1,204 @@
+# Entity
+
+The [`entity`][entity] plugin provides integration for handling attachments on
+immutable structs. It is built on top of the [`column`][column] plugin.
+
+```rb
+plugin :entity
+```
+
+## Attachment
+
+Including a `Shrine::Attachment` module into an entity class will add the
+following instance methods:
+
+* `#<name>` – returns the attached file
+* `#<name>_url` – returns the attached file URL
+* `#<name>_attacher` – returns a `Shrine::Attacher` instance
+
+These methods read attachment data from the `#<name>_data` attribute on the
+entity instance.
+
+```rb
+class Photo < Entity(:image_data)
+  include ImageUploader::Attachment(:image)
+end
+```
+```rb
+photo = Photo.new(image_data: '{"id":"...","storage":"...","metadata":{...}}')
+photo.image          #=> #<ImageUploader::UploadedFile>
+photo.image_url      #=> "https://example.com/image.jpg"
+photo.image_attacher #=> #<ImageUploader::Attacher>
+```
+
+#### `#<name>`
+
+Calls `Attacher#get`, which returns an `UploadedFile` object instantiated from
+attachment data.
+
+```rb
+photo = Photo.new(image_data: '{"id":"foo.jpg","storage":"store","metadata":{...}}')
+photo.image             #=> #<ImageUploader::UploadedFile>
+photo.image.id          #=> "foo.jpg"
+photo.image.storage_key #=> :store
+photo.image.metadata    #=> { ... }
+```
+
+If no file is attached, `nil` is returned.
+
+```rb
+photo = Photo.new(image_data: nil)
+photo.image #=> nil
+```
+
+#### `#<name>_url`
+
+Calls `Attacher#url`, which returns the URL to the attached file.
+
+```rb
+photo = Photo.new(image_data: {"id":"foo.jpg","storage":"...","metadata":{...}})
+photo.image_url #=> "https://example.com/foo.jpg"
+```
+
+If no file is attached, `nil` is returned.
+
+```rb
+photo = Photo.new(image_data: nil)
+photo.image_url #=> nil
+```
+
+#### `#<name>_attacher`
+
+Calls `Attacher.from_entity`, which returns an `Attacher` instance backed by
+the entity object.
+
+```rb
+photo = Photo.new
+photo.image_attacher           #=> #<ImageUploader::Attacher>
+photo.image_attacher.record    #=> #<Photo>
+photo.image_attacher.name      #=> :image
+photo.image_attacher.attribute #=> :image_data
+```
+
+Any additional options will be forwarded to `Attacher#initialize`.
+
+```rb
+photo    = Photo.new
+attacher = photo.image_attacher(cache: :other_cache)
+attacher.cache_key #=> :other_cache
+```
+
+You can also specify default attacher options when including
+`Shrine::Attachment`:
+
+```rb
+class Photo < Entity(:image_data)
+  include ImageUploader::Attachment(:image, store: :other_store)
+end
+```
+```rb
+photo    = Photo.new
+attacher = photo.image_attacher
+attacher.store_key #=> :other_store
+```
+
+## Attacher
+
+### Loading entity
+
+The `Attacher.from_entity` method can be used for creating an `Attacher`
+instance backed by an entity object.
+
+```rb
+photo    = Photo.new(image_data: '{"id":"...","storage":"...","metadata":{...}}')
+attacher = ImageUploader::Attacher.from_entity(photo, :image)
+
+attacher.record    #=> #<Photo>
+attacher.name      #=> :image
+attacher.attribute #=> :image_data
+
+attacher.file #=> #<ImageUploader::UploadedFile>
+```
+
+Any additional options are forwarded to `Attacher#initialize`.
+
+```rb
+attacher = ImageUploader::Attacher.from_entity(photo, :image, cache: :other_cache)
+attacher.cache_key #=> :other_cache
+```
+
+You can also load an entity into an existing attacher with
+`Attacher#load_entity`.
+
+```rb
+photo = Photo.new(image_data: '{"id":"...","storage":"...","metadata":{...}}')
+
+attacher.file #=> nil
+attacher.load_entity(photo, :image)
+attacher.file #=> #<ImageUploader::UploadedFile>
+```
+
+### Reloading
+
+The `Attacher#reload` method reloads attached file from the attachment data on
+the entity attribute.
+
+```rb
+photo = Photo.new
+
+attacher = ImageUploader::Attacher.from_entity(photo, :image)
+attacher.file #=> nil
+
+photo.image_data = '{"id":"...","storage":"...","metadata":{...}}'
+
+attacher.file #=> nil
+attacher.reload
+attacher.file #=> #<ImageUploader::UploadedFile>
+```
+
+### Column values
+
+The `Attacher#column_values` method returns a hash with the entity attribute as
+key and current attachment data as value.
+
+```rb
+attacher = ImageUploader::Attacher.from_entity(Photo.new, :image)
+attacher.attach(io)
+
+attacher.column_values #=> { :image_data => '{"id":"...","storage":"...","metadata":{...}}' }
+```
+
+The `Attacher#attribute` method returns just the entity attribute from which
+attached file data is read.
+
+```rb
+attacher = ImageUploader::Attacher.from_entity(Photo.new, :image)
+attacher.attribute #=> :image_data
+```
+
+### Entity data
+
+The `Attacher#record` method returns the entity instance from which the
+attacher was loaded.
+
+```rb
+attacher = ImageUploader::Attacher.from_entity(Photo.new, :image)
+attacher.record #=> #<Photo>
+```
+
+The `Attacher#name` method returns the name of the attachment from which the
+attacher was loaded.
+
+```rb
+attacher = ImageUploader::Attacher.from_entity(Photo.new, :image)
+attacher.name #=> :image
+```
+
+## Serialization
+
+By default, attachment data is serialized into JSON using the `JSON` standard
+library. If you want to change how data is serialized, see the
+[`column`][column serializer] plugin docs.
+
+[entity]: /lib/shrine/plugins/entity.rb
+[column serializer]: /doc/plugins/column.md#serializer

data/doc/plugins/infer_extension.md

@@ -11,19 +11,19 @@ plugin :infer_extension
 
 ## Inferrers
 
-By default `MIME::Types` will be used for inferring the extension, but you can
-also choose a different inferrer:
+By default, the [mini_mime] gem will be used for inferring the extension, but
+you can also choose a different inferrer:
 
 ```rb
-plugin :infer_extension, inferrer: :mini_mime
+plugin :infer_extension, inferrer: :mime_types
 ```
 
 The following inferrers are accepted:
 
-| Name          | Description                                                                             |
-| :------------ | :-----------                                                                            |
-| `:mime_types` | (Default). Uses the [mime-types] gem to infer the appropriate extension from MIME type. |
-| `:mini_mime`  | Uses the [mini_mime] gem to infer the appropriate extension from MIME type.             |
+| Name          | Description                                                                            |
+| :------------ | :-----------                                                                           |
+| `:mini_mime`  | (Default). Uses the [mini_mime] gem to infer the appropriate extension from MIME type. |
+| `:mime_types` | Uses the [mime-types] gem to infer the appropriate extension from MIME type.           |
 
 You can also define your own inferrer, with the possibility to call the
 built-in inferrers:
@@ -31,7 +31,7 @@ built-in inferrers:
 ```rb
 plugin :infer_extension, inferrer: -> (mime_type, inferrers) do
   # don't add extension if the file is a text file
-  inferrers[:rack_mime].call(mime_type) unless mime_type == "text/plain"
+  inferrers[:mini_mime].call(mime_type) unless mime_type == "text/plain"
 end
 ```
 

data/doc/plugins/instrumentation.md

@@ -1,7 +1,7 @@
 # Instrumentation
 
-The [`instrumentation`][instrumentation] plugin sends events for various
-operations to a centralized notification component. In addition to that it
+The [`instrumentation`][instrumentation] plugin publishes events for various
+operations to a centralized notification component. In addition to that, it
 provides default logging for these events.
 
 ```rb
@@ -40,6 +40,13 @@ Download (1002ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1
 Delete (700ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}
 ```
 
+It uses `Shrine.logger` for logging, which allows you to change where and how
+are the logs going to be written:
+
+```rb
+Shrine.logger = Rails.logger # in Rails apps
+```
+
 You can choose to log only certain events, e.g. we can exclude metadata
 extraction:
 
@@ -79,6 +86,7 @@ The following events are instrumented by the `instrumentation` plugin:
 
 * [`upload.shrine`](#uploadshrine)
 * [`download.shrine`](#downloadshrine)
+* [`open.shrine`](#openshrine)
 * [`exists.shrine`](#existsshrine)
 * [`delete.shrine`](#deleteshrine)
 * [`metadata.shrine`](#metadatashrine)
@@ -94,21 +102,33 @@ following payload:
 | `: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    |
+| `:metadata`       | Metadata extracted during upload       |
+| `:options`        | Any additional uploader options        |
 | `: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:
+The `download.shrine` event is logged on `UploadedFile#stream` (which includes
+`UploadedFile#download`), 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 |
+| Key                 | Description                              |
+| :--                 | :----                                    |
+| `:storage`          | The storage identifier                   |
+| `:location`         | The location of the uploaded file        |
+| `:download_options` | Any download options that were specified |
+| `:uploader`         | The uploader class that sent the event   |
+
+### open.shrine
+
+The `download.shrine` event is logged on `UploadedFile#open` or when uploaded
+file is implicitly opened on calling an IO method.
+
+| Key                 | Description                              |
+| :--                 | :----                                    |
+| `:storage`          | The storage identifier                   |
+| `:location`         | The location of the uploaded file        |
+| `:download_options` | Any download options that were specified |
+| `:uploader`         | The uploader class that sent the event   |
 
 ### exists.shrine
 
@@ -141,7 +161,7 @@ following payload:
 | :--               | :----                                  |
 | `:storage`        | The storage identifier                 |
 | `:io`             | The uploaded IO object                 |
-| `:options`        | Some additional context information    |
+| `:options`        | Any options sent to the uploader       |
 | `:uploader`       | The uploader class that sent the event |
 
 ## API

data/doc/plugins/keep_files.md

@@ -1,22 +1,12 @@
 # Keep Files
 
-The [`keep_files`][keep_files] plugin gives you the ability to prevent files
-from being deleted. This functionality is useful when implementing soft
-deletes, or when implementing some kind of [event store] where you need to
-track history.
-
-The plugin accepts the following options:
-
-| Option       | Description                                                                     |
-| :------      | :----------                                                                     |
-| `:destroyed` | If set to `true`, destroying the record won't delete the associated attachment. |
-| `:replaced`  | If set to `true`, uploading a new attachment won't delete the old one.          |
-
-For example, the following will keep destroyed and replaced files:
+The [`keep_files`][keep_files] plugin prevents file deletion when the attacher
+is about to destroy currently attached or previously attached file. This
+functionality is useful when implementing soft deletes, versioning, or in
+general any scenario where you need to track history.
 
 ```rb
-plugin :keep_files, destroyed: true, replaced: true
+plugin :keep_files
 ```
 
 [keep_files]: /lib/shrine/plugins/keep_files.rb
-[event store]: http://docs.geteventstore.com/introduction/event-sourcing-basics/

data/doc/plugins/model.md

@@ -0,0 +1,157 @@
+# Model
+
+The [`model`][model] plugin provides integration for handling atatchments on
+mutable structs. It is built on top of the [`entity`][entity] plugin.
+
+```rb
+plugin :model
+```
+
+## Attachment
+
+Including a `Shrine::Attachment` module into a model class will, in addition to
+methods from the `entity` plugin, add the `#<name>=` method for attaching
+files.
+
+These methods read and write attachment data to the `#<name>_data` attribute on
+the model instance.
+
+```rb
+class Photo < Model(:image_data)
+  include ImageUploader::Attachment(:image)
+end
+```
+```rb
+photo = Photo.new
+photo.image = file
+photo.image          #=> #<ImageUploader::UploadedFile>
+photo.image_url      #=> "https://example.com/foo.jpg"
+photo.image_attacher #=> #<ImageUploader::Attacher>
+```
+
+#### `#<name>=`
+
+Calls `Attacher#assign` by default, which uploads the file to temporary storage
+and attaches it, updating the model attribute.
+
+```rb
+photo = Photo.new
+photo.image = file
+photo.image.storage_key #=> :cache
+photo.image_data        #=> '{"id":"...","storage":"cache","metadata":{...}}'
+```
+
+#### Disabling caching
+
+If you don't want to use temporary storage, you can have `#<name>=` upload
+directly to permanent storage.
+
+```rb
+plugin :model, cache: false
+```
+```rb
+photo = Photo.new
+photo.image = file
+photo.image.storage_key #=> :store
+photo.image_data        #=> '{"id":"...","storage":"store","metadata":{...}}'
+```
+
+This can be configured on the attacher level as well:
+
+```rb
+photo = Photo.new
+photo.image_attacher(model_cache: false)
+photo.image = file
+photo.image.storage_key #=> :store
+```
+
+#### `#<name>_attacher`
+
+Returns an `Attacher` instance backed by the model instance, memoized in an
+instance variable.
+
+```rb
+photo = Photo.new
+photo.image_attacher #=> #<ImageUploader::Attacher> (memoizes the instance)
+photo.image_attacher #=> #<ImageUploader::Attacher> (returns memoized instance)
+```
+
+When attacher options are passed, the attacher instance is refreshed:
+
+```rb
+photo = Photo.new
+photo.image_attacher(cache: :other_cache)
+photo.image_attacher.cache_key #=> :other_cache
+```
+
+### Entity
+
+If you still want to include `Shrine::Attachment` modules to immutable
+entities, you can disable "model" behaviour by passing `type: :entity`:
+
+```rb
+class Photo < Entity(:image_data)
+  include ImageUploader::Attachment(:image, type: :entity)
+end
+```
+
+## Attacher
+
+### Loading model
+
+The `Attacher.from_model` method can be used for creating an `Attacher`
+instance backed by a model object.
+
+```rb
+photo    = Photo.new
+attacher = ImageUploader::Attacher.from_model(photo, :image)
+
+attacher.record    #=> #<Photo>
+attacher.name      #=> :image
+attacher.attribute #=> :image_data
+
+attacher.attach(io)
+photo.image_data #=> '{"id":"...","storage":"...","metadata":{...}}'
+```
+
+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)
+
+attacher.file #=> nil
+attacher.load_model(photo, :image)
+attacher.file #=> #<ImageUploader::UploadedFile>
+```
+
+### Writing attachment data
+
+The `Attacher#write` method writes attachment data to the `#<name>_data`
+attribute on the model instance.
+
+```rb
+photo    = Photo.new
+attacher = ImageUploader::Attacher.from_model(photo, :image)
+
+attacher.file = uploaded_file
+photo.image_data #=> nil
+
+attacher.write
+photo.image_data #=> '{"id":"...","storage":"...","metadata":{...}}'
+```
+
+The `Attacher#write` method is automatically called on `Attacher#set`, as well
+as `Attacher#assign`, `Attacher#attach_cached`, `Attacher#attach`,
+`Attacher#promote` and any other attacher method that calls `Attacher#set`.
+
+## Serialization
+
+By default, attachment data is serialized into JSON using the `JSON` standard
+library. If you want to change how data is serialized, see the
+[`column`][column serializer] plugin docs.
+
+[model]: /lib/shrine/plugins/model.rb
+[entity]: /doc/plugins/entity.md#readme
+[column serializer]: /doc/plugins/column.md#serializer