shrine 2.15.0 → 2.16.0

data/doc/plugins/hooks.md

@@ -1,6 +1,6 @@
 # Hooks
 
-The `hooks` plugin allows you to trigger some code around
+The [`hooks`][hooks] plugin allows you to trigger some code around
 processing/storing/deleting of each file.
 
 ```rb
@@ -54,3 +54,5 @@ class ImageUploader < Shrine
   end
 end
 ```
+
+[hooks]: /lib/shrine/plugins/hooks.rb

data/doc/plugins/included.md

@@ -1,7 +1,8 @@
 # Included
 
-The `included` plugin allows you to hook up to the `.included` hook of the
-attachment module, and call additional methods on the model which includes it.
+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
+includes it.
 
 ```rb
 plugin :included do |name|
@@ -13,3 +14,5 @@ end
 
 If you want to define additional methods on the model, it's recommended to use
 the `module_include` plugin instead.
+
+[included]: /lib/shrine/plugins/included.rb

data/doc/plugins/infer_extension.md

@@ -1,9 +1,9 @@
 # Infer Extension
 
-The `infer_extension` plugin allows deducing the appropriate file extension for
-the upload location based on the MIME type of the file. This is useful when
-using `data_uri` and `remote_url` plugins, where the file extension might not
-be known.
+The [`infer_extension`][infer_extension] plugin allows deducing the appropriate
+file extension for the upload location based on the MIME type of the file. This
+is useful when using `data_uri` and `remote_url` plugins, where the file
+extension might not be known.
 
 ```rb
 plugin :infer_extension
@@ -53,5 +53,6 @@ Shrine.extension_inferrers[:mime_types].call("image/jpeg")
 # => ".jpeg"
 ```
 
+[infer_extension]: /lib/shrine/plugins/infer_extension.rb
 [mime-types]: https://github.com/mime-types/ruby-mime-types
 [mini_mime]: https://github.com/discourse/mini_mime

data/doc/plugins/keep_files.md

@@ -1,8 +1,9 @@
 # Keep Files
 
-The `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 [`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:
 
@@ -17,4 +18,5 @@ For example, the following will keep destroyed and replaced files:
 plugin :keep_files, destroyed: true, replaced: true
 ```
 
+[keep_files]: /lib/shrine/plugins/keep_files.rb
 [event store]: http://docs.geteventstore.com/introduction/event-sourcing-basics/

data/doc/plugins/logging.md

@@ -1,6 +1,7 @@
 # Logging
 
-The `logging` plugin logs any storing/processing/deleting that is performed.
+The [`logging`][logging] plugin logs any storing/processing/deleting that is
+performed.
 
 ```rb
 plugin :logging
@@ -37,3 +38,5 @@ plugin :logging, format: :logfmt
 
 Logging is by default disabled in tests, but you can enable it by setting
 `Shrine.logger.level = Logger::INFO`.
+
+[logging]: /lib/shrine/plugins/logging.rb

data/doc/plugins/metadata_attribues.md

@@ -1,8 +1,9 @@
 # Metadata Attributes
 
-The `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 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:
 
 ```rb
 plugin :metadata_attributes, :size => :size, :mime_type => :type
@@ -41,3 +42,5 @@ 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

data/doc/plugins/migration_helpers.md

@@ -1,7 +1,7 @@
 # Migration Helpers
 
-The migration_helpers plugin gives the attacher additional helper methods which
-are convenient when doing file migrations.
+The [`migration_helpers`][migration_helpers] plugin gives the attacher
+additional helper methods which are convenient when doing file migrations.
 
 The plugin also allows convenient delegating to these methods through the
 model, by setting `:delegate`:
@@ -56,3 +56,5 @@ user.avatar_attacher.store #=> #<Shrine @storage_key=:store @storage=#<Shrine::S
 user.avatar_cache
 user.avatar_store
 ```
+
+[migration_helpers]: /lib/shrine/plugins/migration_helpers.rb

data/doc/plugins/module_include.md

@@ -1,7 +1,7 @@
 # Module Include
 
-The `module_include` plugin allows you to extend Shrine's core classes for the
-given uploader with modules/methods.
+The [`module_include`][module_include] plugin allows you to extend Shrine's
+core classes for the given uploader with modules/methods.
 
 ```rb
 plugin :module_include
@@ -38,3 +38,5 @@ 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

data/doc/plugins/moving.md

@@ -1,9 +1,9 @@
 # Moving
 
-The `moving` plugin will *move* files to storages instead of copying them, when
-the storage supports it. For FileSystem this will issue a `mv` command, which
-is instantaneous regardless of the filesize, so in that case loading this
-plugin can significantly speed up the attachment process.
+The [`moving`][moving] plugin will *move* files to storages instead of copying
+them, when the storage supports it. For FileSystem this will issue a `mv`
+command, which is instantaneous regardless of the filesize, so in that case
+loading this plugin can significantly speed up the attachment process.
 
 ```rb
 plugin :moving
@@ -15,3 +15,5 @@ moving to happen only for certain storages, you can set `:storages`:
 ```rb
 plugin :moving, storages: [:cache]
 ```
+
+[moving]: /lib/shrine/plugins/moving.rb

data/doc/plugins/multi_delete.md

@@ -1,7 +1,7 @@
 # Multi Delete
 
-The `multi_delete` plugins allows you to leverage your storage's multi delete
-capabilities.
+The [`multi_delete`][multi_delete] plugins allows you to leverage your
+storage's multi delete capabilities.
 
 ```rb
 plugin :multi_delete
@@ -16,3 +16,5 @@ uploader.delete([file1, file2, file3])
 Now if you're using Storage::S3, deleting an array of files will issue a single
 HTTP request. Some other storages may support multi deletes as well. The
 `versions` plugin uses this plugin for deleting multiple versions at once.
+
+[multi_delete]: /lib/shrine/plugins/multi_delete.rb

data/doc/plugins/parallelize.md

@@ -1,7 +1,7 @@
 # Parallelize
 
-The `parallelize` plugin parallelizes uploads and deletes of multiple versions
-using threads.
+The [`parallelize`][parallelize] plugin parallelizes uploads and deletes of
+multiple versions using threads.
 
 ```rb
 plugin :parallelize
@@ -12,3 +12,5 @@ By default a pool of 3 threads will be used, but you can change that:
 ```rb
 plugin :parallelize, threads: 5
 ```
+
+[parallelize]: /lib/shrine/plugins/parallelize.rb

data/doc/plugins/parsed_json.md

@@ -1,9 +1,11 @@
 # Parsed JSON
 
-The `parsed_json` plugin is suitable for the case when your framework is
-automatically parsing JSON query parameters, allowing you to assign cached
-files with hashes/arrays.
+The [`parsed_json`][parsed_json] plugin is suitable for the case when your
+framework is automatically parsing JSON query parameters, allowing you to
+assign cached files with hashes/arrays.
 
 ```rb
 plugin :parsed_json
 ```
+
+[parsed_json]: /lib/shrine/plugins/parsed_json.rb

data/doc/plugins/presign_endpoint.md

@@ -1,10 +1,11 @@
 # Presign Endpoint
 
-The `presign_endpoint` plugin provides a Rack endpoint which generates the URL,
-fields, and headers that can be used to upload files directly to a storage
-service. On the client side it's recommended to use [Uppy] for asynchronous
-uploads. Storage services that support direct uploads include [Amazon S3],
-[Google Cloud Storage], [Microsoft Azure Storage] and more.
+The [`presign_endpoint`][presign_endpoint] plugin provides a Rack endpoint
+which generates the URL, fields, and headers that can be used to upload files
+directly to a storage service. On the client side it's recommended to use
+[Uppy] for asynchronous uploads. Storage services that support direct uploads
+include [Amazon S3], [Google Cloud Storage], [Microsoft Azure Storage] and
+more.
 
 ```rb
 plugin :presign_endpoint
@@ -126,6 +127,7 @@ You can override any of the options above when creating the endpoint:
 Shrine.presign_endpoint(:cache, presign_location: "${filename}")
 ```
 
+[presign_endpoint]: /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,7 +1,7 @@
 # Pretty Location
 
-The `pretty_location` plugin attempts to generate a nicer folder structure for
-uploaded files.
+The [`pretty_location`][pretty_location] plugin attempts to generate a nicer
+folder structure for uploaded files.
 
 ```rb
 plugin :pretty_location
@@ -27,3 +27,5 @@ plugin :pretty_location, namespace: "_"
 plugin :pretty_location, namespace: "/"
 # "blog/user/.../493g82jf23.jpg"
 ```
+
+[pretty_location]: /lib/shrine/plugins/pretty_location.rb

data/doc/plugins/processing.md

@@ -22,8 +22,8 @@ def process(io, context)
 end
 ```
 
-The `processing` plugin simplifies this by allowing us to declaratively define
-file processing for specified actions.
+The [`processing`][processing] plugin simplifies this by allowing us to
+declaratively define file processing for specified actions.
 
 ```rb
 plugin :processing
@@ -65,4 +65,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
 [image_processing]: https://github.com/janko/image_processing

data/doc/plugins/rack_file.md

@@ -1,7 +1,7 @@
 # Rack File
 
-The `rack_file` plugin enables uploaders to accept Rack uploaded file hashes
-for uploading.
+The [`rack_file`][rack_file] plugin enables uploaders to accept Rack uploaded
+file hashes for uploading.
 
 ```rb
 plugin :rack_file
@@ -47,3 +47,5 @@ io.size              #=> 58342
 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

data/doc/plugins/rack_response.md

@@ -1,8 +1,8 @@
 # Rack Response
 
-The `rack_response` plugin allows you to convert an `UploadedFile` object into
-a triple consisting of status, headers, and body, suitable for returning as a
-response in a Rack-based application.
+The [`rack_response`][rack_response] plugin allows you to convert an
+`UploadedFile` object into a triple consisting of status, headers, and body,
+suitable for returning as a response in a Rack-based application.
 
 ```rb
 plugin :rack_response
@@ -53,8 +53,8 @@ The response `Content-Type` header will default to the value of the `mime_type`
 metadata. A custom content type can be provided via the `:type` option:
 
 ```rb
-_, headers, _ uploaded_file.to_rack_response(type: "text/plain; charset=utf-8")
-headers["Content-Type"] #=> "text/plain; charset=utf-8"
+response = uploaded_file.to_rack_response(type: "text/plain; charset=utf-8")
+response[1]["Content-Type"] #=> "text/plain; charset=utf-8"
 ```
 
 ## Filename
@@ -64,8 +64,8 @@ value of the `filename` metadata. A custom download filename can be provided
 via the `:filename` option:
 
 ```rb
-_, headers, _ uploaded_file.to_rack_response(filename: "my-filename.txt")
-headers["Content-Disposition"] #=> "inline; filename=\"my-filename.txt\""
+response = uploaded_file.to_rack_response(filename: "my-filename.txt")
+response[1]["Content-Disposition"] #=> "inline; filename=\"my-filename.txt\""
 ```
 
 ## Disposition
@@ -74,8 +74,8 @@ The default disposition in the "Content-Disposition" header is `inline`, but it
 can be changed via the `:disposition` option:
 
 ```rb
-_, headers, _ = uploaded_file.to_rack_response(disposition: "attachment")
-headers["Content-Disposition"] #=> "attachment; filename=\"file.txt\""
+response = uploaded_file.to_rack_response(disposition: "attachment")
+response[1]["Content-Disposition"] #=> "attachment; filename=\"file.txt\""
 ```
 
 ## Range
@@ -84,7 +84,6 @@ headers["Content-Disposition"] #=> "attachment; filename=\"file.txt\""
 which accepts a value of the `Range` request header.
 
 ```rb
-env["HTTP_RANGE"] #=> "bytes=100-200"
 status, headers, body = uploaded_file.to_rack_response(range: env["HTTP_RANGE"])
 status                    #=> 206
 headers["Content-Length"] #=> "101"
@@ -92,5 +91,22 @@ headers["Content-Range"]  #=> "bytes 100-200/1000"
 body                      # partial content
 ```
 
+## Download options
+
+The `#to_rack_response` method will automatically open the `UploadedFile` if it
+hasn't been opened yet. If you want to pass additional download options to the
+storage, you can explicitly call `UploadedFile#open` beforehand:
+
+```rb
+uploaded_file.open(
+  sse_customer_algorithm: "AES256",
+  sse_customer_key:       "secret_key",
+  sse_customer_key_md5:   "secret_key_md5",
+)
+
+uploaded_file.to_rack_response
+```
+
+[rack_response]: /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,10 +1,10 @@
 # Re-cache
 
-The `recache` plugin allows you to process your attachment after validations
-succeed, but before the attachment is promoted. This is useful for example when
-you want to generate some versions upfront (so the user immediately sees them)
-and other versions you want to generate in the promotion phase in a background
-job.
+The [`recache`][recache] plugin allows you to process your attachment after
+validations succeed, but before the attachment is promoted. This is useful for
+example when you want to generate some versions upfront (so the user
+immediately sees them) and other versions you want to generate in the promotion
+phase in a background job.
 
 ```rb
 plugin :recache
@@ -25,3 +25,5 @@ you're using the attacher directly, you can call it manually:
 ```rb
 attacher.recache if attacher.changed?
 ```
+
+[recache]: /lib/shrine/plugins/recache.rb

data/doc/plugins/refresh_metadata.md

@@ -1,7 +1,7 @@
 # Refresh Metadata
 
-The `refresh_metadata` plugin allows you to re-extract metadata from an
-uploaded file.
+The [`refresh_metadata`][refresh_metadata] plugin allows you to re-extract
+metadata from an uploaded file.
 
 ```rb
 plugin :refresh_metadata
@@ -29,3 +29,5 @@ uploaded_file.open do
   # ...
 end
 ```
+
+[refresh_metadata]: /lib/shrine/plugins/refresh_metadata.rb

data/doc/plugins/remote_url.md

@@ -1,6 +1,7 @@
 # Remote URL
 
-The `remote_url` plugin allows you to attach files from a remote location.
+The [`remote_url`][remote_url] plugin allows you to attach files from a remote
+location.
 
 ```rb
 plugin :remote_url, max_size: 20*1024*1024
@@ -100,5 +101,6 @@ load the `infer_extension` plugin to infer it from the MIME type.
 plugin :infer_extension
 ```
 
+[remote_url]: /lib/shrine/plugins/remote_url.rb
 [Down]: https://github.com/janko/down
 [shrine-url]: https://github.com/shrinerb/shrine-url

data/doc/plugins/remove_attachment.md

@@ -1,7 +1,7 @@
 # Remove Attachment
 
-The `remove_attachment` plugin allows you to delete attachments through
-checkboxes on the web form.
+The [`remove_attachment`][remove_attachment] plugin allows you to delete
+attachments through checkboxes on the web form.
 
 ```rb
 plugin :remove_attachment
@@ -14,3 +14,5 @@ to add a form field for removing attachments:
 ```rb
 form.check_box :remove_avatar
 ```
+
+[remove_attachment]: /lib/shrine/plugins/remove_attachment.rb

data/doc/plugins/remove_invalid.md

@@ -1,9 +1,12 @@
 # Remove Invalid
 
-The `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 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.
 
 ```rb
 plugin :remove_invalid
 ```
+
+[remove_invalid]: /lib/shrine/plugins/remove_invalid.rb