shrine 2.19.4 → 3.4.0

data/doc/plugins/keep_files.md

@@ -1,22 +1,19 @@
-# Keep Files
+---
+title: 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
+```
+```rb
+photo.image #=> #<Shrine::UploadedFile>
+photo.destroy
+photo.image.exists? #=> true
 ```
 
-[keep_files]: /lib/shrine/plugins/keep_files.rb
-[event store]: http://docs.geteventstore.com/introduction/event-sourcing-basics/
+[keep_files]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/keep_files.rb

data/doc/plugins/metadata_attributes.md

@@ -1,9 +1,10 @@
-# Metadata Attributes
+---
+title: Metadata Attributes
+---
 
-The [`metadata_attributes`][metadata_attributes] plugin allows you to sync
-attachment metadata to additional record attributes. You can provide a hash of
-mappings to the plugin call itself or the `Attacher.metadata_attributes`
-method:
+The [`metadata_attributes`][metadata_attributes] plugin allows you to write
+attachment metadata to additional record attributes. You can configure the
+plugin with a hash of mappings:
 
 ```rb
 plugin :metadata_attributes, :size => :size, :mime_type => :type
@@ -12,7 +13,7 @@ plugin :metadata_attributes
 Attacher.metadata_attributes :size => :size, :mime_type => :type
 ```
 
-The above configuration will sync `size` metadata field to `<attachment>_size`
+The above configuration will write `size` metadata field to `<attachment>_size`
 record attribute, and `mime_type` metadata field to `<attachment>_type` record
 attribute.
 
@@ -28,19 +29,47 @@ user.avatar_size #=> nil
 user.avatar_type #=> nil
 ```
 
+## Model and Entity
+
+With the [`model`][model] plugin, any method that internally calls
+`Attacher#write` will trigger metadata attributes writing (`Attacher#assign`,
+`Attacher#attach`, `Attacher#change`, `Attacher#set`).
+
+```rb
+attacher.file.metadata["mime_type"] = "other/type"
+attacher.write
+attacher.record.avatar_type #=> "other/type"
+```
+
+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",
+# }
+```
+
+Any metadata attributes that were declared but are missing on the record will
+be skipped.
+
+## Full attribute name
+
 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.
-
-[metadata_attributes]: /lib/shrine/plugins/metadata_attributes.rb
+[metadata_attributes]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/metadata_attributes.rb
+[entity]: https://shrinerb.com/docs/plugins/entity
+[model]: https://shrinerb.com/docs/plugins/model

data/doc/plugins/mirroring.md

@@ -0,0 +1,118 @@
+---
+title: Mirroring
+---
+
+The [`mirroring`][mirroring] plugin enables replicating uploads and deletes to
+other storages. This can be useful for setting up a backup storage, or when
+migrating files from one storage to another.
+
+```rb
+Shrine.plugin :mirroring, mirror: { store: :other_store }
+```
+
+With the above setup, any upload and delete to `:store` will be replicated to
+`:other_store`.
+
+```rb
+file = Shrine.upload(io, :store) # uploads to :store and :other_store
+file.delete                      # deletes from :store and :other_store
+```
+
+You can skip mirroring for a specific upload/delete call by passing `mirror:
+false`:
+
+```rb
+file = Shrine.upload(io, :store, mirror: false) # skips mirroring
+file.delete(mirror: false)                      # skips mirroring
+```
+
+## Multiple storages
+
+You can mirror to multiple storages by specifying an array:
+
+```rb
+Shrine.plugin :mirroring, mirror: {
+  store: [:other_store_1, :other_store_2]
+}
+```
+
+## Backup storage
+
+If you want the mirror storage to act as a backup, you can disable mirroring
+deletes:
+
+```rb
+Shrine.plugin :mirroring, mirror: { ... }, delete: false
+```
+
+## Backgrounding
+
+You can have mirroring performed in a background job:
+
+```rb
+Shrine.mirror_upload_block do |file, **options|
+  MirrorUploadJob.perform_async(file.shrine_class.name, file.data)
+end
+
+Shrine.mirror_delete_block do |file|
+  MirrorDeleteJob.perform_async(file.shrine_class.name, file.data)
+end
+```
+```rb
+class MirrorUploadJob
+  include Sidekiq::Worker
+
+  def perform(shrine_class, file_data)
+    shrine_class = Object.const_get(shrine_class)
+
+    file = shrine_class.uploaded_file(file_data)
+    file.mirror_upload
+  end
+end
+```
+```rb
+class MirrorDeleteJob
+  include Sidekiq::Worker
+
+  def perform(shrine_class, file_data)
+    shrine_class = Object.const_get(shrine_class)
+
+    file = shrine_class.uploaded_file(file_data)
+    file.mirror_delete
+  end
+end
+```
+
+## API
+
+You can disable automatic mirroring and perform mirroring manually:
+
+```rb
+# disable automatic mirroring of uploads and deletes
+Shrine.plugin :mirroring, mirror: { ... }, upload: false, delete: false
+```
+
+To perform mirroring, you can call `UploadedFile#mirror_upload` and
+`UploadedFile#mirror_delete`:
+
+```rb
+file = Shrine.upload(io, :store) # upload to :store
+file.mirror_upload               # upload to :other_store
+
+file.delete                      # delete from :store
+file.mirror_delete               # delete from :other_store
+```
+
+If you've set up backgrounding, you can use
+`UploadedFile#mirror_upload_background` and
+`UploadedFile#mirror_delete_background` to call the background block instead:
+
+```rb
+file = Shrine.upload(io, :store) # upload to :store
+file.mirror_upload_background    # spawn mirror upload background job
+
+file.delete                      # delete from :store
+file.mirror_delete_background    # spawn mirror delete background job
+```
+
+[mirroring]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/mirroring.rb

data/doc/plugins/model.md

@@ -0,0 +1,210 @@
+---
+title: Model
+---
+
+The [`model`][model] plugin provides integration for handling attachment 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:
+
+* add [entity] attachment methods
+* add `#<name>=` and `#<name>_changed?` methods
+
+```rb
+class Photo
+  attr_accessor :image_data
+
+  include ImageUploader::Attachment(:image)
+end
+```
+```rb
+photo = Photo.new
+
+photo.image = file
+
+photo.image      #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:cache ...>
+photo.image_data #=> '{"id":"bc2e13.jpg","storage":"cache","metadata":{...}}'
+
+photo.image_attacher.finalize
+
+photo.image      #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
+photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
+```
+
+#### `#<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":{...}}'
+```
+
+#### `#<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
+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 `model: false`:
+
+```rb
+class Photo
+  attr_reader :image_data
+
+  include ImageUploader::Attachment(:image, model: false)
+end
+```
+
+## Attacher
+
+You can also use `Shrine::Attacher` directly (with or without the
+`Shrine::Attachment` module):
+
+```rb
+class Photo
+  attr_accessor :image_data
+end
+```
+```rb
+photo    = Photo.new
+attacher = ImageUploader::Attacher.from_model(photo, :image)
+
+attacher.assign(file) # cache
+
+attacher.file    #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:cache ...>
+photo.image_data #=> '{"id":"bc2e13.jpg","storage":"cache","metadata":{...}}'
+
+attacher.finalize # promote
+
+attacher.file    #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
+photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
+```
+
+### 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.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`
+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]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/model.rb
+[entity]: https://shrinerb.com/docs/plugins/entity
+[column serializer]: https://shrinerb.com/docs/plugins/column#serializer

data/doc/plugins/module_include.md

@@ -1,4 +1,6 @@
-# Module Include
+---
+title: Module Include
+---
 
 The [`module_include`][module_include] plugin allows you to extend Shrine's
 core classes for the given uploader with modules/methods.
@@ -39,4 +41,4 @@ end
 The above defines an additional `#<attachment>_size` method on the attachment
 module, which is what is included in your model.
 
-[module_include]: /lib/shrine/plugins/module_include.rb
+[module_include]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/module_include.rb

data/doc/plugins/multi_cache.md

@@ -0,0 +1,24 @@
+---
+title: Multi Cache
+---
+
+The [`multi_cache`][multi_cache] plugin allows an attacher to accept files from
+additional temporary storages.
+
+```rb
+Shrine.storages = { cache: ..., cache_one: ..., cache_two: ..., store: ... }
+
+Shrine.plugin :multi_cache, additional_cache: [:cache_one, :cache_two]
+```
+```rb
+photo.image = { "id" => "...", "storage" => "cache", "metadata" => { ... } }
+photo.image.storage_key #=> :cache
+# or
+photo.image = { "id" => "...", "storage" => "cache_one", "metadata" => { ... } }
+photo.image.storage_key #=> :cache_one
+# or
+photo.image = { "id" => "...", "storage" => "cache_two", "metadata" => { ... } }
+photo.image.storage_key #=> :cache_two
+```
+
+[multi_cache]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/multi_cache.rb

data/doc/plugins/persistence.md

@@ -0,0 +1,101 @@
+---
+title: Persistence
+---
+
+This is an internal plugin that provides uniform persistence interface across
+different persistence plugins (e.g. [`activerecord`][activerecord],
+[`sequel`][sequel]).
+
+For these activerecord and sequel, atomic persistence is implemented in terms
+of database locks, eg "SELECT... FOR UPDATE". For more discussion of concurrency
+challenges, see the [atomic_helpers] documentation.
+
+## 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. For instance, one way to allow concurrent
+changes to metadata, perhaps in different background workers,  without
+overwriting each other might be:
+
+```rb
+attacher.atomic_persist do |reloaded_attacher|
+  # run code after attachment change check but before persistence
+  attacher.file.metadata.merge!(reloaded_attacher.file.metadata)
+  attacher.file.metadata["some_key"] = "changed_value"
+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]: https://shrinerb.com/docs/plugins/activerecord
+[sequel]: https://shrinerb.com/docs/plugins/sequel
+[atomic_helpers]: https://shrinerb.com/docs/plugins/atomic_helpers
+[backgrounding]: https://shrinerb.com/docs/plugins/backgrounding

data/doc/plugins/presign_endpoint.md

@@ -1,4 +1,6 @@
-# Presign Endpoint
+---
+title: Presign Endpoint
+---
 
 The [`presign_endpoint`][presign_endpoint] plugin provides a Rack endpoint
 which generates the URL, fields, and headers that can be used to upload files
@@ -11,6 +13,8 @@ more.
 plugin :presign_endpoint
 ```
 
+## Setup
+
 The plugin adds a `Shrine.presign_endpoint` method which, given a storage
 identifier, returns a Rack application that accepts GET requests and generates
 a presign for the specified storage. You can run this Rack application inside
@@ -60,7 +64,7 @@ create a custom controller action and handle presign requests there using
 # config/routes.rb (Rails)
 Rails.application.routes.draw do
   # ...
-  post "/images/presign", to: "presigns#image"
+  get "/images/presign", to: "presigns#image"
 end
 ```
 ```rb
@@ -130,7 +134,8 @@ option:
 
 ```rb
 plugin :presign_endpoint, presign: -> (id, options, request) do
-  # return a Hash with :url, :fields, and :headers keys
+  # return a Hash with :method, :url, :fields, and :headers keys
+  Shrine.storages[:cache].presign(id, options)
 end
 ```
 
@@ -156,7 +161,7 @@ Shrine.presign_endpoint(:cache, presign_location: "${filename}")
 Shrine.presign_response(:cache, env, presign_location: "${filename}")
 ```
 
-[presign_endpoint]: /lib/shrine/plugins/presign_endpoint.rb
+[presign_endpoint]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/presign_endpoint.rb
 [Uppy]: https://uppy.io
 [Amazon S3]: https://aws.amazon.com/s3/
 [Google Cloud Storage]: https://cloud.google.com/storage/

data/doc/plugins/pretty_location.md

@@ -1,4 +1,6 @@
-# Pretty Location
+---
+title: Pretty Location
+---
 
 The [`pretty_location`][pretty_location] plugin attempts to generate a nicer
 folder structure for uploaded files.
@@ -13,7 +15,7 @@ generated locations will typically look like this:
 
 ```rb
 "user/564/avatar/thumb-493g82jf23.jpg"
-# :model/:id/:attachment/:version-:uid.:extension
+# :model/:id/:attachment/:derivative-:uid.:extension
 ```
 
 By default if a record class is inside a namespace, only the "inner" class name
@@ -40,6 +42,17 @@ plugin :pretty_location, identifier: :email
 # "user/foo@bar.com/profile_picture/493g82jf23.jpg"
 ```
 
+By default, the class name will be only downcased. We can also have the class
+name underscored with the `:class_underscore` option:
+
+```ruby
+plugin :pretty_location
+# "blogpost/aa357797-5845-451b-8662-08eecdc9f762/image/493g82jf23.jpg"
+
+plugin :pretty_location, class_underscore: :true
+# "blog_post/aa357797-5845-451b-8662-08eecdc9f762/image/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.
@@ -51,4 +64,4 @@ def generate_location(io, record: nil, **context)
 end
 ```
 
-[pretty_location]: /lib/shrine/plugins/pretty_location.rb
+[pretty_location]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/pretty_location.rb

data/doc/plugins/processing.md

@@ -1,4 +1,6 @@
-# Processing
+---
+title: Processing
+---
 
 Shrine uploaders can define the `#process` method, which will get called
 whenever a file is uploaded. It is given the original file, and is expected to
@@ -65,5 +67,5 @@ uploader.process(file, action: :store) # only process
 If you want the result of processing to be multiple files, use the `versions`
 plugin.
 
-[processing]: /lib/shrine/plugins/processing.rb
+[processing]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/processing.rb
 [image_processing]: https://github.com/janko/image_processing