shrine 2.19.4 → 3.4.0

data/doc/plugins/rack_file.md

@@ -1,4 +1,6 @@
-# Rack File
+---
+title: Rack File
+---
 
 The [`rack_file`][rack_file] plugin enables uploaders to accept Rack uploaded
 file hashes for uploading.
@@ -7,6 +9,8 @@ file hashes for uploading.
 plugin :rack_file
 ```
 
+## Usage
+
 When a file is uploaded to your Rack application using the
 `multipart/form-data` parameter encoding, Rack converts the uploaded file to a
 hash.
@@ -33,6 +37,8 @@ user.avatar = file_hash
 attacher.assign(file_hash)
 ```
 
+## API
+
 Internally the Rack uploaded file hash will be converted into an IO object
 using `Shrine.rack_file`, which you can also use directly:
 
@@ -48,4 +54,4 @@ Note that this plugin is not needed in Rails applications, as Rails already
 wraps the Rack uploaded file hash into an `ActionDispatch::Http::UploadedFile`
 object.
 
-[rack_file]: /lib/shrine/plugins/rack_file.rb
+[rack_file]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/rack_file.rb

data/doc/plugins/rack_response.md

@@ -1,4 +1,6 @@
-# Rack Response
+---
+title: Rack Response
+---
 
 The [`rack_response`][rack_response] plugin allows you to convert an
 `UploadedFile` object into a triple consisting of status, headers, and body,
@@ -8,6 +10,8 @@ suitable for returning as a response in a Rack-based application.
 plugin :rack_response
 ```
 
+## Usage
+
 To convert a `Shrine::UploadedFile` into a Rack response, simply call
 `#to_rack_response`:
 
@@ -107,6 +111,6 @@ uploaded_file.open(
 uploaded_file.to_rack_response
 ```
 
-[rack_response]: /lib/shrine/plugins/rack_response.rb
+[rack_response]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/rack_response.rb
 [range requests]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests
 [Rack::Sendfile]: https://www.rubydoc.info/github/rack/rack/Rack/Sendfile

data/doc/plugins/recache.md

@@ -1,4 +1,6 @@
-# Re-cache
+---
+title: Re-cache
+---
 
 The [`recache`][recache] plugin allows you to process your attachment after
 validations succeed, but before the attachment is promoted. This is useful for
@@ -26,4 +28,4 @@ you're using the attacher directly, you can call it manually:
 attacher.recache if attacher.changed?
 ```
 
-[recache]: /lib/shrine/plugins/recache.rb
+[recache]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/recache.rb

data/doc/plugins/refresh_metadata.md

@@ -1,4 +1,6 @@
-# Refresh Metadata
+---
+title: Refresh Metadata
+---
 
 The [`refresh_metadata`][refresh_metadata] plugin allows you to re-extract
 metadata from an uploaded file.
@@ -7,27 +9,65 @@ metadata from an uploaded file.
 plugin :refresh_metadata
 ```
 
-It provides `UploadedFile#refresh_metadata!` method, which triggers metadata
-extraction (calls `Shrine#extract_metadata`) with the uploaded file opened for
-reading, and updates the existing metadata hash with the results.
+It provides `#refresh_metadata!` method, which triggers metadata extraction
+(calls `Shrine#extract_metadata`) with the uploaded file opened for reading,
+and updates the existing metadata hash with the results. This can be done
+on the `Shrine::Attacher` or the `Shrine::UploadedFile` level.
+
+## Attacher
+
+Calling `#refresh_metadata!` on a `Shrine::Attacher` object will re-extract
+metadata of the attached file, and when used with a [model], it will write new
+file data back into the attachment attribute.
+
+```rb
+attacher.refresh_metadata!
+attacher.file.metadata    # re-extracted metadata
+attacher.record.file_data #=> '{ ... data with updated metadata ... }'
+```
+
+The `Attacher#context` hash will be forwarded to metadata extraction, as well
+as any options that you pass in.
+
+```rb
+# via context
+attacher.context[:foo] = "bar"
+attacher.refresh_metadata! # passes `{ foo: "bar" }` options to metadata extraction
+
+# via arguments
+attacher.refresh_metadata!(foo: "bar") # passes `{ foo: "bar" }` options to metadata extraction
+```
+
+## Uploaded File
+
+The `#refresh_metadata!` method can be called on a `Shrine::UploadedFile` object
+as well.
 
 ```rb
 uploaded_file.refresh_metadata!
 uploaded_file.metadata # re-extracted metadata
 ```
 
-For remote storages this will make an HTTP request to open the file for
-reading, but only the portion of the file needed for extracting each metadata
-value will be downloaded.
+If the uploaded file is not open, it is opened before and closed after metadata
+extraction. For remote storage services this will make an HTTP request.
+However, only the portion of the file needed for extracting metadata will be
+downloaded.
 
 If the uploaded file is already open, it is passed to metadata extraction as
 is.
 
 ```rb
 uploaded_file.open do
-  uploaded_file.refresh_metadata!
+  uploaded_file.refresh_metadata! # uses the already opened file
   # ...
 end
 ```
 
-[refresh_metadata]: /lib/shrine/plugins/refresh_metadata.rb
+Any options passed in will be forwarded to metadata extraction:
+
+```rb
+uploaded_file.refresh_metadata!(foo: "bar") # passes `{ foo: "bar" }` options to metadata extraction
+```
+
+[refresh_metadata]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/refresh_metadata.rb
+[model]: https://shrinerb.com/docs/plugins/model

data/doc/plugins/remote_url.md

@@ -1,4 +1,6 @@
-# Remote URL
+---
+title: Remote URL
+---
 
 The [`remote_url`][remote_url] plugin allows you to attach files from a remote
 location.
@@ -7,82 +9,117 @@ location.
 plugin :remote_url, max_size: 20*1024*1024
 ```
 
-If for example your attachment is called "avatar", this plugin will add
-`#avatar_remote_url` and `#avatar_remote_url=` methods to your model.
+## Usage
 
-```rb
-user.avatar #=> nil
-user.avatar_remote_url = "http://example.com/cool-image.png"
-user.avatar #=> #<Shrine::UploadedFile>
+The plugin will add the `#<name>_remote_url` writer to your model, which
+downloads the remote file and uploads it to temporary storage.
 
-user.avatar.mime_type         #=> "image/png"
-user.avatar.size              #=> 43423
-user.avatar.original_filename #=> "cool-image.png"
+```rb
+photo.image_remote_url = "http://example.com/cool-image.png"
+photo.image.mime_type         #=> "image/png"
+photo.image.size              #=> 43423
+photo.image.original_filename #=> "cool-image.png"
 ```
 
-You can also use `#remote_url=` and `#remote_url` methods directly on the
-`Shrine::Attacher`:
+If you're using `Shrine::Attacher` directly, you can use
+`Attacher#assign_remote_url`:
 
 ```rb
-attacher.remote_url = "http://example.com/cool-image.png"
+attacher.assign_remote_url("http://example.com/cool-image.png")
+attacher.file.mime_type         #=> "image/png"
+attacher.file.size              #=> 43423
+attacher.file.original_filename #=> "cool-image.png"
 ```
 
+## Downloader
+
 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
+gem. This will use the [Down::NetHttp] backend by default, which is a wrapper
 around [open-uri].
 
-## Dynamic options
+You can pass options to the downloader via the `:downloader` option:
 
-You can dynamically pass options to the downloader by using
-`Attacher#assign_remote_url`:
+```rb
+attacher.assign_remote_url url, downloader: {
+  headers: { "Authorization" => "Basic ..." },
+  read_timeout: 30, open_timeout: 30,
+  max_redirects: 5,
+  # ...
+}
+```
+
+You can also change the downloader:
 
 ```rb
-attacher.assign_remote_url(url, downloader: { 'Authorization' => 'Basic ...' })
+# Gemfile
+gem "http"
+```
+```rb
+require "down/http"
+
+plugin :remote_url, downloader: -> (url, **options) {
+  Down::Http.download(url, **options) do |client|
+    client.follow(max_hops: 2).timeout(connect: 2, read: 2)
+  end
+}
 ```
 
-You can also pass any other `Shrine#upload` options:
+Any `Down::NotFound` and `Down::TooLarge` exceptions will be rescued and
+converted into validation errors. If you want to convert any other exceptions
+into validation errors, you can raise them as
+`Shrine::Plugins::RemoteUrl::DownloadError`:
 
 ```rb
-attacher.assign_remote_url(url, metadata: { "mime_type" => "text/plain" })
+plugin :remote_url, downloader: -> (url, **options) {
+  begin
+    RestClient.get(url)
+  rescue RestClient::ExceptionWithResponse => error
+    raise Shrine::Plugins::RemoteUrl::DownloadError, "remote file not found"
+  end
+}
 ```
 
-## Maximum size
+### Calling downloader
 
-It's a good practice to limit the maximum filesize of the remote file:
+You can call the downloader directly with `Shrine.remote_url`:
 
 ```rb
-plugin :remote_url, max_size: 20*1024*1024 # 20 MB
+# or YourUploader.remote_url(...)
+file = Shrine.remote_url("https://example.com/image.jpg")
+file #=> #<Tempfile:...>
 ```
 
-Now if a file that is bigger than 20MB is assigned, download will be terminated
-as soon as it gets the "Content-Length" header, or the size of currently
-downloaded content surpasses the maximum size. However, if for whatever reason
-you don't want to limit the maximum file size, you can set `:max_size` to nil:
+You can pass additional options as well:
 
 ```rb
-plugin :remote_url, max_size: nil
+# or YourUploader.remote_url(...)
+Shrine.remote_url("https://example.com/image.jpg", headers: { "Cookie" => "..." })
 ```
 
-## Custom downloader
+## Uploader options
 
-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:
+Any additional options passed to `Attacher#assign_remote_url` will be forwarded
+to `Attacher#assign` (and `Shrine#upload`):
 
 ```rb
-# Gemfile
-gem "http"
+attacher.assign_remote_url(url, metadata: { "mime_type" => "text/plain" })
 ```
+
+## Maximum size
+
+It's a good practice to limit the maximum filesize of the remote file:
+
 ```rb
-require "down/http"
+plugin :remote_url, max_size: 20*1024*1024 # 20 MB
+```
 
-down = Down::Http.new do |client|
-  client
-    .follow(max_hops: 2)
-    .timeout(connect: 2, read: 2)
-end
+Now if a file that is bigger than 20MB is assigned, download will be terminated
+as soon as it gets the "Content-Length" header, or the size of currently
+downloaded content surpasses the maximum size. However, if for whatever reason
+you don't want to limit the maximum file size, you can set `:max_size` to nil:
 
-plugin :remote_url, max_size: 20*1024*1024, downloader: down.method(:download)
+```rb
+plugin :remote_url, max_size: nil
 ```
 
 ## Errors
@@ -103,11 +140,10 @@ file ID, and pair that with the `backgrounding` plugin.
 
 ## File extension
 
-When attaching from a remote URL, the uploaded file location will have the
-extension inferred from the URL. However, some URLs might not have an
-extension, in which case the uploaded file location also won't have the
-extension. If you want the upload location to always have an extension, you can
-load the `infer_extension` plugin to infer it from the MIME type.
+When attaching from a remote URL, the uploaded file location will inherit the
+extension from the URL. However, some URLs might not have an extension. To
+handle this case, you can use the `infer_extension` plugin to infer the
+extension from the MIME type.
 
 ```rb
 plugin :infer_extension
@@ -156,8 +192,9 @@ Or disable logging altogether:
 plugin :remote_url, log_subscriber: nil
 ```
 
-[remote_url]: /lib/shrine/plugins/remote_url.rb
+[remote_url]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/remote_url.rb
 [Down]: https://github.com/janko/down
+[Down::NetHttp]: https://github.com/janko/down#downnethttp
 [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/remove_attachment.md

@@ -1,4 +1,6 @@
-# Remove Attachment
+---
+title: Remove Attachment
+---
 
 The [`remove_attachment`][remove_attachment] plugin allows you to delete
 attachments through checkboxes on the web form.
@@ -7,12 +9,31 @@ attachments through checkboxes on the web form.
 plugin :remove_attachment
 ```
 
-If for example your attachment is called "avatar", this plugin will add
-`#remove_avatar` and `#remove_avatar=` methods to your model. This allows you
-to add a form field for removing attachments:
+The plugin adds the `#remove_<name>` accessor to your model, which removes the
+attached file if it receives a truthy value:
 
 ```rb
-form.check_box :remove_avatar
+photo.image #=> #<Shrine::UploadedFile>
+photo.remove_image = 'true'
+photo.image #=> nil
 ```
 
-[remove_attachment]: /lib/shrine/plugins/remove_attachment.rb
+This allows you to add a checkbox form field for removing attachments:
+
+```rb
+form_for photo do |f|
+  # ...
+  f.check_box :remove_image
+end
+```
+
+If you're using the `Shrine::Attacher` directly, you can use the
+`Attacher#remove` accessor:
+
+```rb
+attacher.file #=> #<Shrine::UploadedFile>
+attacher.remove = '1'
+attacher.file #=> nil
+```
+
+[remove_attachment]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/remove_attachment.rb

data/doc/plugins/remove_invalid.md

@@ -1,12 +1,27 @@
-# Remove Invalid
+---
+title: Remove Invalid
+---
 
-The [`remove_invalid`][remove_invalid] plugin automatically deletes a new
-assigned file if it was invalid and deassigns it from the record. If there was
-a previous file attached, it will be assigned back, otherwise no attachment
-will be assigned.
+The [`remove_invalid`][remove_invalid] plugin automatically deletes and
+deassigns a new assigned file if it was invalid. If there was a previous file
+attached, it will be assigned back.
 
 ```rb
 plugin :remove_invalid
 ```
 
-[remove_invalid]: /lib/shrine/plugins/remove_invalid.rb
+```rb
+# without previous file
+photo.image        #=> nil
+photo.image = file # validation fails, assignment is reverted
+photo.valid?       #=> false
+photo.image        #=> nil
+
+# with previous file
+photo.image        #=> #<Shrine::UploadedFile id="foo" ...>
+photo.image = file # validation fails, assignment is reverted
+photo.valid?       #=> false
+photo.image        #=> #<Shrine::UploadedFile id="foo" ...>
+```
+
+[remove_invalid]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/remove_invalid.rb

data/doc/plugins/restore_cached_data.md

@@ -1,4 +1,6 @@
-# Restore Cached Data
+---
+title: Restore Cached Data
+---
 
 The [`restore_cached_data`][restore_cached_data] plugin re-extracts metadata
 when assigning already cached files, i.e. when the attachment has been retained
@@ -10,7 +12,13 @@ extracted on the client side.
 ```rb
 plugin :restore_cached_data
 ```
+```rb
+photo.image = { "id" => "path/to/image.jpg", "storage" => "cache", "metadata" => {} }
+photo.image.metadata #=> { "size" => 4823763, "mime_type" => "image/jpeg", ... }
+```
 
-It uses the `refresh_metadata` plugin to re-extract metadata.
+It uses the [`refresh_metadata`][refresh_metadata] plugin to re-extract
+metadata.
 
-[restore_cached_data]: /lib/shrine/plugins/restore_cached_data.rb
+[restore_cached_data]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/restore_cached_data.rb
+[refresh_metadata]: https://shrinerb.com/docs/plugins/refresh_metadata

data/doc/plugins/sequel.md

@@ -1,67 +1,191 @@
-# Sequel
+---
+title: Sequel
+---
 
-The [`sequel`][sequel] plugin extends the "attachment" interface with support
-for Sequel.
+The [`sequel`][sequel] plugin adds [Sequel] integration to the attachment
+interface. It is built on top of the [`model`][model] plugin.
 
 ```rb
-plugin :sequel
+Shrine.plugin :sequel
 ```
 
-## Callbacks
+## Attachment
 
-Now the attachment module will add additional callbacks to the model:
+Including a `Shrine::Attachment` module into a `Sequel::Model` subclass will:
 
-* "before save" – Used by the `recache` plugin.
-* "after commit" (save) – Promotes the attachment, deletes replaced ones.
-* "after commit" (destroy) – Deletes the attachment.
+* add [model] attachment methods
+* add [validations](#validations) and [hooks](#hooks) to tie attachment process
+  to the record lifecycle
 
-If you want to put promoting/deleting into a background job, see the
-`backgrounding` plugin.
+```rb
+class Photo < Sequel::Model # has `image_data` column
+  include ImageUploader::Attachment(:image) # adds methods, callbacks & validations
+end
+```
+```rb
+photo = Photo.new
+
+photo.image = file # cache attachment
+
+photo.image      #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:cache ...>
+photo.image_data #=> '{"id":"bc2e13.jpg","storage":"cache","metadata":{...}}'
+
+photo.save # persist, promote attachment, then persist again
+
+photo.image      #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
+photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
 
-Since attaching first saves the record with a cached attachment, then saves
-again with a stored attachment, you can detect this in callbacks:
+photo.destroy # delete attachment
+
+photo.image.exists? #=> false
+```
+
+### Hooks
+
+#### After Save
+
+After a record is saved and the transaction is committed, `Attacher#finalize`
+is called, which promotes cached file to permanent storage and deletes previous
+file if any.
 
 ```rb
-class User < Sequel::Model
-  include ImageUploader::Attachment.new(:avatar)
+photo = Photo.new
 
-  def before_save
-    super
+photo.image = file
+photo.image.storage_key #=> :cache
 
-    if changed_columns.include?(:avatar) && avatar_attacher.cached?
-      # cached
-    elsif changed_columns.include?(:avatar) && avatar_attacher.stored?
-      # promoted
-    end
+photo.save
+photo.image.storage_key #=> :store
+```
+
+#### After Destroy
+
+After a record is destroyed and the transaction is committed,
+`Attacher#destroy_attached` method is called, which deletes stored attached
+file if any.
+
+```rb
+photo = Photo.find(photo_id)
+photo.image #=> #<Shrine::UploadedFile>
+photo.image.exists? #=> true
+
+photo.destroy
+photo.image.exists? #=> false
+```
+
+#### Overriding hooks
+
+You can override any of the following attacher methods to modify callback
+behaviour:
+
+* `Attacher#sequel_before_save`
+* `Attacher#sequel_after_save`
+* `Attacher#sequel_after_destroy`
+
+```rb
+class Shrine::Attacher
+  def sequel_after_save
+    super
+    # ...
   end
 end
 ```
 
-If you don't want the attachment module to add any callbacks to the model, and
-would instead prefer to call these actions manually, you can disable callbacks:
+#### Skipping Hooks
+
+If you don't want the attachment module to add any hooks to your model, you can
+set `:hooks` to `false`:
+
+```rb
+plugin :sequel, hooks: false
+```
+
+### Validations
+
+If you're using the [`validation`][validation] plugin, the attachment module
+will automatically merge attacher errors with model errors.
 
 ```rb
-plugin :sequel, callbacks: false
+class ImageUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    validate_max_size 10 * 1024 * 1024
+  end
+end
+```
+```rb
+photo = Photo.new
+photo.image = file
+photo.valid?
+photo.errors #=> { image: ["size must not be greater than 10.0 MB"] }
 ```
 
-## Validations
+#### Attachment Presence
 
-Additionally, any Shrine validation errors will added to Sequel's errors upon
-validation. Note that if you want to validate presence of the attachment, you
-can do it directly on the model.
+If you want to validate presence of the attachment, you can use Sequel's
+presence validator:
 
 ```rb
-class User < Sequel::Model
-  include ImageUploader::Attachment.new(:avatar)
-  validates_presence_of :avatar
+class Photo < Sequel::Model
+  include ImageUploader::Attachment(:image)
+
+  def validate
+    super
+    validates_presence :image
+  end
 end
 ```
 
-If don't want the attachment module to merge file validations errors into model
-errors, you can disable it:
+#### Skipping Validations
+
+If don't want the attachment module to merge file validations errors into
+model errors, you can set `:validations` to `false`:
 
 ```rb
 plugin :sequel, validations: false
 ```
 
-[sequel]: /lib/shrine/plugins/sequel.rb
+## Attacher
+
+You can also use `Shrine::Attacher` directly (with or without the
+`Shrine::Attachment` module):
+
+```rb
+class Photo < Sequel::Model # has `image_data` column
+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":{...}}'
+
+photo.save        # persist
+attacher.finalize # promote
+photo.save        # persist
+
+attacher.file    #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
+photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
+```
+
+### Persistence
+
+The following persistence methods are added to `Shrine::Attacher`:
+
+| Method                    | Description                                                            |
+| :-----                    | :----------                                                            |
+| `Attacher#atomic_promote` | calls `Attacher#promote` and persists if the attachment hasn't changed |
+| `Attacher#atomic_persist` | saves changes if the attachment hasn't changed                         |
+| `Attacher#persist`        | saves any changes to the underlying record                             |
+
+See [persistence] docs for more details.
+
+[sequel]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/sequel.rb
+[Sequel]: https://sequel.jeremyevans.net/
+[model]: https://shrinerb.com/docs/plugins/model
+[validation]: https://shrinerb.com/docs/plugins/validation
+[persistence]: https://shrinerb.com/docs/plugins/persistence