shrine 2.15.0 → 2.16.0

data/doc/plugins/restore_cached_data.md

@@ -1,14 +1,16 @@
 # Restore Cached Data
 
-The `restore_cached_data` plugin re-extracts metadata when assigning already
-cached files, i.e. when the attachment has been retained on validation errors
-or assigned from a direct upload. In both cases you may want to re-extract
-metadata on the server side, mainly to prevent tempering, but also in case of
-direct uploads to obtain metadata that couldn't be extracted on the client
-side.
+The [`restore_cached_data`][restore_cached_data] plugin re-extracts metadata
+when assigning already cached files, i.e. when the attachment has been retained
+on validation errors or assigned from a direct upload. In both cases you may
+want to re-extract metadata on the server side, mainly to prevent tempering,
+but also in case of direct uploads to obtain metadata that couldn't be
+extracted on the client side.
 
 ```rb
 plugin :restore_cached_data
 ```
 
 It uses the `refresh_metadata` plugin to re-extract metadata.
+
+[restore_cached_data]: /lib/shrine/plugins/restore_cached_data.rb

data/doc/plugins/sequel.md

@@ -1,6 +1,7 @@
 # Sequel
 
-The `sequel` plugin extends the "attachment" interface with support for Sequel.
+The [`sequel`][sequel] plugin extends the "attachment" interface with support
+for Sequel.
 
 ```rb
 plugin :sequel
@@ -62,3 +63,5 @@ errors, you can disable it:
 ```rb
 plugin :sequel, validations: false
 ```
+
+[sequel]: /lib/shrine/plugins/sequel.rb

data/doc/plugins/signature.md

@@ -1,8 +1,8 @@
 # Signature
 
-The `signature` plugin provides the ability to calculate a hash from file
-content. This hash can be used as a checksum or just as a unique signature for
-the uploaded file.
+The [`signature`][signature] plugin provides the ability to calculate a hash
+from file content. This hash can be used as a checksum or just as a unique
+signature for the uploaded file.
 
 ```rb
 Shrine.plugin :signature
@@ -47,3 +47,5 @@ Shrine.calculate_signature(io, :sha256, format: :base64)
 ```
 
 The supported encoding formats are `hex` (default), `base64`, and `none`.
+
+[signature]: /lib/shrine/plugins/signature.rb

data/doc/plugins/store_dimensions.md

@@ -1,7 +1,8 @@
 # Store Dimensions
 
-The `store_dimensions` plugin extracts dimensions of uploaded images and stores
-them into the metadata hash (by default it uses the [fastimage] gem).
+The [`store_dimensions`][store_dimensions] plugin extracts dimensions of
+uploaded images and stores them into the metadata hash (by default it uses the
+[fastimage] gem).
 
 ```rb
 plugin :store_dimensions
@@ -63,6 +64,7 @@ Shrine.dimensions_analyzers[:fastimage].call(io) # calls a built-in analyzer
 #=> [300, 400]
 ```
 
+[store_dimensions]: /lib/shrine/plugins/store_dimensions.rb
 [fastimage]: https://github.com/sdsykes/fastimage
 [mini_magick]: https://github.com/minimagick/minimagick
 [ruby-vips]: https://github.com/libvips/ruby-vips

data/doc/plugins/tempfile.md

@@ -1,7 +1,7 @@
 # Tempfile
 
-The `tempfile` plugin makes it easier to reuse a single copy of an uploaded
-file on disk.
+The [`tempfile`][tempfile] plugin makes it easier to reuse a single copy of an
+uploaded file on disk.
 
 ```rb
 Shrine.plugin :tempfile
@@ -38,3 +38,5 @@ This plugin also modifies `Shrine.with_file` to call `UploadedFile#tempfile`
 when the given IO object is an open `UploadedFile`. Since `Shrine.with_file` is
 typically called on the `Shrine` class directly, it's recommended to load this
 plugin globally.
+
+[tempfile]: /lib/shrine/plugins/tempfile.rb

data/doc/plugins/upload_endpoint.md

@@ -1,8 +1,8 @@
 # Upload Endpoint
 
-The `upload_endpoint` plugin provides a Rack endpoint which accepts file
-uploads and forwards them to specified storage. On the client side it's
-recommended to use [Uppy] for asynchronous uploads.
+The [`upload_endpoint`][upload_endpoint] plugin provides a Rack endpoint which
+accepts file uploads and forwards them to specified storage. On the client side
+it's recommended to use [Uppy] for asynchronous uploads.
 
 ```rb
 plugin :upload_endpoint
@@ -120,4 +120,5 @@ You can override any of the options above when creating the endpoint:
 Shrine.upload_endpoint(:cache, max_size: 20*1024*1024)
 ```
 
+[upload_endpoint]: /lib/shrine/plugins/upload_endpoint.rb
 [Uppy]: https://uppy.io

data/doc/plugins/upload_options.md

@@ -1,7 +1,7 @@
 # Upload Options
 
-The `upload_options` plugin allows you to automatically pass additional upload
-options to storage on every upload:
+The [`upload_options`][upload_options] plugin allows you to automatically pass
+additional upload options to storage on every upload:
 
 ```rb
 plugin :upload_options, cache: { acl: "private" }
@@ -26,3 +26,5 @@ the uploader.
 ```rb
 uploader.upload(file, upload_options: { acl: "public-read" })
 ```
+
+[upload_options]: /lib/shrine/plugins/upload_options.rb

data/doc/plugins/validation_helpers.md

@@ -1,7 +1,7 @@
 # Validation Helpers
 
-The `validation_helpers` plugin provides helper methods for validating attached
-files based on extracted metadata.
+The [`validation_helpers`][validation_helpers] plugin provides helper methods
+for validating attached files based on extracted metadata.
 
 ```rb
 plugin :validation_helpers
@@ -127,3 +127,5 @@ Attacher.validate do
   validate_mime_type_inclusion %w[image/jpeg image/png image/gif], message: "must be JPEG, PNG or GIF"
 end
 ```
+
+[validation_helpers]: /lib/shrine/plugins/validation_helpers.rb

data/doc/plugins/versions.md

@@ -1,7 +1,7 @@
 # Versions
 
-The `versions` plugin enables your uploader to deal with versions, by allowing
-you to return a Hash of files when processing.
+The [`versions`][versions] plugin enables your uploader to deal with versions,
+by allowing you to return a Hash of files when processing.
 
 ```rb
 plugin :versions
@@ -175,5 +175,6 @@ end
 If you want to re-create a single or all versions, refer to the [reprocessing
 versions] guide for details.
 
+[versions]: /lib/shrine/plugins/versions.rb
 [reprocessing versions]: /doc/regenerating_versions.md#readme
 [image_processing]: https://github.com/janko/image_processing

data/doc/release_notes/2.15.0.md

@@ -53,7 +53,7 @@
   host], change response headers of derivatives ([`Content-Type`],
   [`Content-Disposition`]), add [URL expiration], [cache][uploading]
   generated derivatives to a Shrine storage and more. Check out the
-  [documentation] for more details.
+  [documentation][derivation_endpoint] for more details.
 
 ## Other improvements
 
@@ -74,7 +74,7 @@
   relying on multiple invocations returning the same object, you will need to
   modify your code.
 
-[derivation_endpoint]: /doc/plugins/derivation_endpoint.md
+[derivation_endpoint]: /doc/plugins/derivation_endpoint.md#readme
 [CDN host]: /doc/plugins/derivation_endpoint.md#host
 [`Content-Type`]: /doc/plugins/derivation_endpoint.md#content-type
 [`Content-Disposition`]: /doc/plugins/derivation_endpoint.md#content-disposition

data/doc/release_notes/2.16.0.md

@@ -0,0 +1,52 @@
+## New Features
+
+* The `:download_options` option has been added to the `download_endpoint`
+  plugin, for specifying options passed to `Storage#open`.
+
+  ```rb
+  plugin :download_endpoint,
+    download_options: {
+      sse_customer_algorithm: "AES256",
+      sse_customer_key:       "secret_key",
+      sse_customer_key_md5:   "secret_key_md5",
+    }
+  ```
+
+* The `:upload_open_options` option has been added to the `derivation_endpoint`
+  plugin, for specifying options passed to `Storage#open` when downloading a
+  cached derivation result.
+
+  ```rb
+  plugin :download_endpoint,
+    upload: true,
+    upload_open_options: { response_content_encoding: "gzip" }
+  ```
+
+## Other improvements
+
+* The `rack_response` and `derivation_endpoint` plugins now don't return any
+  `Content-Type` response header if the MIME type could not be determined from
+  the file extension. Previously it the `Content-Type` header would default to
+  `application/octet-stream`, which would force the browser to view the file
+  as generic binary content, as opposed to doing its own MIME type sniffing.
+
+* Fixed `delete_raw` plugin breaking `derivation_endpoint` when `:upload` was
+  enabled.
+
+* Fixed a few things in the `Shrine::Derivation` API:
+
+  * `Derivation#upload` doesn't close the input file anymore
+  * `Derivation#upload` now requires input file to respond to `#path`
+  * `Derivation#upload` now deletes the internally generated derivation result
+  * `Derivation#processed` now works when derivation result is a `File` object
+
+* The official demo app now shows the `derivation_endpoint` plugin.
+
+* The `#to_rack_response` method from the `rack_response` plugin now always
+  opens the `UploadedFile`, and does so upfront. This means if ther are any
+  download errors, they will bubble up from `#to_rack_response` as opposed to
+  when the response body is iterated over.
+
+* When `store_dimensions` plugin was overriding `Shrine#extract_metadata`, it
+  made the second argument (the `context` hash) mandatory. This has been fixed,
+  now the second argument is optional again.

data/doc/storage/s3.md

@@ -65,7 +65,7 @@ Shrine::Storage::S3.new(prefix: "cache", **s3_options)
 ## Upload options
 
 Sometimes you'll want to add additional upload options to all S3 uploads. You
-can do that by passing the `:upload` option:
+can do that by passing the `:upload_options` option:
 
 ```rb
 Shrine::Storage::S3.new(upload_options: { acl: "private" }, **s3_options)
@@ -288,6 +288,6 @@ can scale exponentially by using more prefixes.
 [presigning]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#presigned_post-instance_method
 [aws-sdk-s3]: https://github.com/aws/aws-sdk-ruby/tree/master/gems/aws-sdk-s3
 [Transfer Acceleration]: http://docs.aws.amazon.com/AmazonS3/latest/dev/transfer-acceleration.html
-[object lifecycle]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#put-instance_method
+[object lifecycle]: http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html
 [serve private content via CloudFront]: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/PrivateContent.html
 [`Aws::CloudFront::UrlSigner`]: https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/CloudFront/UrlSigner.html

data/lib/shrine/plugins/_urlsafe_serialization.rb

@@ -5,6 +5,8 @@ require "json"
 
 class Shrine
   module Plugins
+    # This is an internal plugin used by download_endpoint and
+    # derivation_endpoint plugins.
     module UrlsafeSerialization
       module ClassMethods
         def urlsafe_serialize(hash)

data/lib/shrine/plugins/activerecord.rb

@@ -4,6 +4,9 @@ require "active_record"
 
 class Shrine
   module Plugins
+    # Documentation lives in [doc/plugins/activerecord.md] on GitHub.
+    #
+    # [doc/plugins/activerecord.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/activerecord.md
     module Activerecord
       def self.configure(uploader, opts = {})
         uploader.opts[:activerecord_callbacks] = opts.fetch(:callbacks, uploader.opts.fetch(:activerecord_callbacks, true))

data/lib/shrine/plugins/add_metadata.rb

@@ -2,6 +2,9 @@
 
 class Shrine
   module Plugins
+    # Documentation lives in [doc/plugins/add_metadata.md] on GitHub.
+    #
+    # [doc/plugins/add_metadata.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/add_metadata.md
     module AddMetadata
       def self.configure(uploader)
         uploader.opts[:metadata] ||= []

data/lib/shrine/plugins/backgrounding.rb

@@ -2,6 +2,9 @@
 
 class Shrine
   module Plugins
+    # Documentation lives in [doc/plugins/backgrounding.md] on GitHub.
+    #
+    # [doc/plugins/backgrounding.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/backgrounding.md
     module Backgrounding
       module AttacherClassMethods
         # If block is passed in, stores it to be called on promotion. Otherwise

data/lib/shrine/plugins/backup.rb

@@ -2,6 +2,9 @@
 
 class Shrine
   module Plugins
+    # Documentation lives in [doc/plugins/backup.md] on GitHub.
+    #
+    # [doc/plugins/backup.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/backup.md
     module Backup
       def self.configure(uploader, opts = {})
         uploader.opts[:backup_storage] = opts.fetch(:storage, uploader.opts[:backup_storage])

data/lib/shrine/plugins/cached_attachment_data.rb

@@ -2,6 +2,9 @@
 
 class Shrine
   module Plugins
+    # Documentation lives in [doc/plugins/cached_attachment_data.md] on GitHub.
+    #
+    # [doc/plugins/cached_attachment_data.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/cached_attachment_data.md
     module CachedAttachmentData
       module AttachmentMethods
         def initialize(*)

data/lib/shrine/plugins/copy.rb

@@ -2,6 +2,9 @@
 
 class Shrine
   module Plugins
+    # Documentation lives in [doc/plugins/copy.md] on GitHub.
+    #
+    # [doc/plugins/copy.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/copy.md
     module Copy
       module AttachmentMethods
         def initialize(*)

data/lib/shrine/plugins/data_uri.rb

@@ -8,6 +8,9 @@ require "forwardable"
 
 class Shrine
   module Plugins
+    # Documentation lives in [doc/plugins/data_uri.md] on GitHub.
+    #
+    # [doc/plugins/data_uri.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/data_uri.md
     module DataUri
       class ParseError < Error; end
 

data/lib/shrine/plugins/default_storage.rb

@@ -2,6 +2,9 @@
 
 class Shrine
   module Plugins
+    # Documentation lives in [doc/plugins/default_storage.md] on GitHub.
+    #
+    # [doc/plugins/default_storage.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/default_storage.md
     module DefaultStorage
       def self.configure(uploader, opts = {})
         uploader.opts[:default_storage_cache] = opts.fetch(:cache, uploader.opts[:default_storage_cache])

data/lib/shrine/plugins/default_url.rb

@@ -2,6 +2,9 @@
 
 class Shrine
   module Plugins
+    # Documentation lives in [doc/plugins/default_url.md] on GitHub.
+    #
+    # [doc/plugins/default_url.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/default_url.md
     module DefaultUrl
       def self.configure(uploader, &block)
         if block

data/lib/shrine/plugins/default_url_options.rb

@@ -2,6 +2,9 @@
 
 class Shrine
   module Plugins
+    # Documentation lives in [doc/plugins/default_url_options.md] on GitHub.
+    #
+    # [doc/plugins/default_url_options.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/default_url_options.md
     module DefaultUrlOptions
       def self.configure(uploader, options = {})
         uploader.opts[:default_url_options] ||= {}

data/lib/shrine/plugins/delete_promoted.rb

@@ -2,6 +2,9 @@
 
 class Shrine
   module Plugins
+    # Documentation lives in [doc/plugins/delete_promoted.md] on GitHub.
+    #
+    # [doc/plugins/delete_promoted.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/delete_promoted.md
     module DeletePromoted
       module AttacherMethods
         def promote(uploaded_file = get, **options)

data/lib/shrine/plugins/delete_raw.rb

@@ -2,6 +2,9 @@
 
 class Shrine
   module Plugins
+    # Documentation lives in [doc/plugins/delete_raw.md] on GitHub.
+    #
+    # [doc/plugins/delete_raw.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/delete_raw.md
     module DeleteRaw
       def self.configure(uploader, opts = {})
         uploader.opts[:delete_raw_storages] = opts.fetch(:storages, uploader.opts[:delete_raw_storages])
@@ -13,7 +16,7 @@ class Shrine
         # Deletes the file that was uploaded, unless it's an UploadedFile.
         def copy(io, context)
           super
-          if io.respond_to?(:path) && io.path && delete_raw?
+          if io.respond_to?(:path) && io.path && delete_raw? && context[:delete] != false
             begin
               File.delete(io.path)
             rescue Errno::ENOENT

data/lib/shrine/plugins/derivation_endpoint.rb

@@ -8,6 +8,9 @@ require "tempfile"
 
 class Shrine
   module Plugins
+    # Documentation lives in [doc/plugins/derivation_endpoint.md] on GitHub.
+    #
+    # [doc/plugins/derivation_endpoint.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/derivation_endpoint.md
     module DerivationEndpoint
       def self.load_dependencies(uploader, opts = {})
         uploader.plugin :rack_response
@@ -26,10 +29,17 @@ class Shrine
       end
 
       module ClassMethods
+        # Returns a mountable Rack app that handles derivation requests.
         def derivation_endpoint(**options)
           Shrine::DerivationEndpoint.new(shrine_class: self, options: options)
         end
 
+        # Calls the derivation endpoint passing the request information, and
+        # returns the Rack response triple.
+        #
+        # It uses a trick where it removes the derivation path prefix from the
+        # path info before calling the Rack app, which is what web framework
+        # routers do before they're calling a mounted Rack app.
         def derivation_response(env, **options)
           script_name = env["SCRIPT_NAME"]
           path_info   = env["PATH_INFO"]
@@ -50,6 +60,8 @@ class Shrine
           end
         end
 
+        # Registers a derivation block, which is called when the corresponding
+        # derivation URL is requested.
         def derivation(name, &block)
           derivations[name] = block
         end
@@ -64,14 +76,23 @@ class Shrine
       end
 
       module FileMethods
+        # Generates a URL to a derivation with the receiver as the source file.
+        # Any arguments provided will be included in the URL and passed to the
+        # derivation block. Accepts additional URL options.
         def derivation_url(name, *args, **options)
           derivation(name, *args).url(**options)
         end
 
+        # Calls the specified derivation with the receiver as the source file,
+        # returning a Rack response triple. The derivation endpoint ultimately
+        # calls this method.
         def derivation_response(name, *args, env:, **options)
           derivation(name, *args, **options).response(env)
         end
 
+        # Returns a Shrine::Derivation object created from the provided
+        # arguments. This object offers additional methods for operating with
+        # derivatives on a lower level.
         def derivation(name, *args, **options)
           Shrine::Derivation.new(
             name:    name,
@@ -99,6 +120,7 @@ class Shrine
       @options = options
     end
 
+    # Returns an URL to the derivation.
     def url(**options)
       Derivation::Url.new(self).call(
         host:       option(:host),
@@ -110,26 +132,35 @@ class Shrine
       )
     end
 
+    # Returns the derivation result in form of a Rack response triple.
     def response(env)
       Derivation::Response.new(self).call(env)
     end
 
+    # Returns the derivation result as a File/Tempfile or a
+    # Shrine::UploadedFile object.
     def processed
       Derivation::Processed.new(self).call
     end
 
+    # Calls the derivation block and returns the direct result.
     def generate(file = nil)
       Derivation::Generate.new(self).call(file)
     end
 
+    # Uploads the derivation result to a dedicated destination on the specified
+    # Shrine storage.
     def upload(file = nil)
       Derivation::Upload.new(self).call(file)
     end
 
+    # Returns a Shrine::UploadedFile object pointing to the uploaded derivation
+    # result.
     def retrieve
       Derivation::Retrieve.new(self).call
     end
 
+    # Deletes the derivation result from the storage.
     def delete
       Derivation::Delete.new(self).call
     end
@@ -157,12 +188,18 @@ class Shrine
     option :type
     option :upload,                      default: -> { false }
     option :upload_location,             default: -> { default_upload_location }, result: -> (o) { upload_location(o) }
+    option :upload_open_options,         default: -> { {} }
     option :upload_options,              default: -> { {} }
     option :upload_redirect,             default: -> { false }
     option :upload_redirect_url_options, default: -> { {} }
     option :upload_storage,              default: -> { source.storage_key.to_sym }
     option :version
 
+    # Retrieves the value of a derivation option.
+    #
+    # * If specified as a raw value, returns that value
+    # * If specified as a block, evaluates that it and returns the result
+    # * If unspecified, returns the default value
     def option(name)
       option_definition = self.class.options.fetch(name)
 
@@ -186,16 +223,21 @@ class Shrine
 
     private
 
-    # append version and extension to upload location if specified
+    # When bumping the version, we also append it to the upload location to
+    # ensure we're not retrieving old derivatives.
     def upload_location(location)
       location = location.sub(/(?=(\.\w+)?$)/, "-#{option(:version)}") if option(:version)
       location
     end
 
+    # For derivation "thumbnail" with arguments "600/400" and source id of
+    # "1f6375ad.ext", returns "thumbnail-600-400-1f6375ad".
     def default_filename
       [name, *args, File.basename(source.id, ".*")].join("-")
     end
 
+    # For derivation "thumbnail" with arguments "600/400" and source id of
+    # "1f6375ad.ext", returns "1f6375ad/thumbnail-600-400".
     def default_upload_location
       directory = source.id.sub(/\.[^\/]+/, "")
       filename  = [name, *args].join("-")
@@ -203,6 +245,7 @@ class Shrine
       [directory, filename].join("/")
     end
 
+    # Allows caching for 1 year or until the URL expires.
     def default_cache_control
       if option(:expires_in)
         "public, max-age=#{option(:expires_in)}"
@@ -218,6 +261,7 @@ class Shrine
         @derivation = derivation
       end
 
+      # Creates methods that delegate to derivation parameters.
       def self.delegate(*names)
         names.each do |name|
           protected define_method(name) {
@@ -255,14 +299,16 @@ class Shrine
                    metadata: [])
 
       params = {}
-      params[:expires_at]  = (Time.now.utc + expires_in).to_i if expires_in
+      params[:expires_at]  = (Time.now + expires_in).to_i if expires_in
       params[:version]     = version if version
       params[:type]        = type if type
       params[:filename]    = filename if filename
       params[:disposition] = disposition if disposition
 
+      # serializes the source uploaded file into an URL-safe format
       source_component = source.urlsafe_dump(metadata: metadata)
 
+      # generate signed URL
       signed_url(name, *args, source_component, params)
     end
 
@@ -294,6 +340,15 @@ class Shrine
       [status, headers, body]
     end
 
+    # Verifies validity of the URL, then extracts parameters from it (such as
+    # derivation name, arguments and source file), and generates a derivation
+    # response.
+    #
+    # Returns "403 Forbidden" if signature is invalid, or if the URL has
+    # expired.
+    #
+    # Returns "404 Not Found" if derivation block is not defined, or if source
+    # file was not found on the storage.
     def handle_request(request)
       verify_signature!(request)
       check_expiry!(request)
@@ -305,12 +360,10 @@ class Shrine
 
       # request params override statically configured options
       options = self.options.dup
-
       options[:type]        = request.params["type"]        if request.params["type"]
       options[:disposition] = request.params["disposition"] if request.params["disposition"]
       options[:filename]    = request.params["filename"]    if request.params["filename"]
-
-      options[:expires_in]  = expires_in(request) if request.params["expires_at"]
+      options[:expires_in]  = expires_in(request)           if request.params["expires_at"]
 
       derivation = uploaded_file.derivation(name, *args, **options)
 
@@ -322,6 +375,7 @@ class Shrine
         error!(404, "Source file not found")
       end
 
+      # tell clients to cache the derivation result if it was successful
       if status == 200 || status == 206
         headers["Cache-Control"] = derivation.option(:cache_control)
       end
@@ -331,6 +385,7 @@ class Shrine
 
     private
 
+    # Return an error response if the signature is invalid.
     def verify_signature!(request)
       signer = UrlSigner.new(secret_key)
       signer.verify_url("#{request.path_info[1..-1]}?#{request.query_string}")
@@ -338,6 +393,7 @@ class Shrine
       error!(403, error.message.capitalize)
     end
 
+    # Return an error response if URL has expired.
     def check_expiry!(request)
       if request.params["expires_at"]
         error!(403, "Request has expired") if expires_in(request) <= 0
@@ -366,7 +422,8 @@ class Shrine
 
   class Derivation::Response < Derivation::Command
     delegate :type, :disposition, :filename,
-             :upload, :upload_redirect, :upload_redirect_url_options
+             :upload, :upload_open_options,
+             :upload_redirect, :upload_redirect_url_options
 
     def call(env)
       if upload
@@ -384,27 +441,39 @@ class Shrine
       file_response(derivative, env)
     end
 
+    # Generates a Rack response triple from a local file using `Rack::File`.
+    # Fills in `Content-Type` and `Content-Disposition` response headers from
+    # derivation options and file extension of the derivation result.
     def file_response(file, env)
-      file.close
       response = rack_file_response(file.path, env)
 
       status = response[0]
 
+      content_type   = type || response[1]["Content-Type"]
+      content_length = response[1]["Content-Length"]
+      content_range  = response[1]["Content-Range"]
+
       filename  = self.filename
       filename += File.extname(file.path) if File.extname(filename).empty?
 
       headers = {}
-      headers["Content-Type"]        = type || response[1]["Content-Type"]
+      headers["Content-Type"]        = content_type if content_type
       headers["Content-Disposition"] = content_disposition(filename)
-      headers["Content-Length"]      = response[1]["Content-Length"]
-      headers["Content-Range"]       = response[1]["Content-Range"] if response[1]["Content-Range"]
+      headers["Content-Length"]      = content_length
+      headers["Content-Range"]       = content_range if content_range
       headers["Accept-Ranges"]       = "bytes"
 
       body = Rack::BodyProxy.new(response[2]) { File.delete(file.path) }
 
+      file.close
+
       [status, headers, body]
     end
 
+    # This is called when `:upload` is enabled. Checks the storage for already
+    # uploaded derivation result, otherwise calls the derivation block and
+    # uploads the result. If the derivation result is already uploaded, uses
+    # the `rack_response` plugin to generate a Rack response triple.
     def upload_response(env)
       uploaded_file = derivation.retrieve
 
@@ -414,7 +483,11 @@ class Shrine
       end
 
       if upload_redirect
-        File.delete(derivative.path) if derivative
+        # we don't need the local derivation result here
+        if derivative
+          derivative.close
+          File.delete(derivative.path)
+        end
 
         redirect_url = uploaded_file.url(upload_redirect_url_options)
 
@@ -423,6 +496,7 @@ class Shrine
         if derivative
           file_response(derivative, env)
         else
+          uploaded_file.open(**upload_open_options)
           uploaded_file.to_rack_response(
             type:        type,
             disposition: disposition,
@@ -433,8 +507,10 @@ class Shrine
       end
     end
 
+    # We call `Rack::File` with no default `Content-Type`, and make sure we
+    # stay compatible with both Rack 2.x and 1.6.x.
     def rack_file_response(path, env)
-      server = Rack::File.new("", {}, "application/octet-stream")
+      server = Rack::File.new("", {}, nil)
 
       if Rack.release > "2"
         server.serving(Rack::Request.new(env), path)
@@ -445,6 +521,8 @@ class Shrine
       end
     end
 
+    # Returns disposition and filename formatted for the `Content-Disposition`
+    # header.
     def content_disposition(filename)
       ContentDisposition.format(disposition: disposition, filename: filename)
     end
@@ -455,29 +533,10 @@ class Shrine
 
     def call
       if upload
-        upload_result
+        derivation.retrieve || derivation.upload
       else
-        local_result
-      end
-    end
-
-    private
-
-    def local_result
-      derivation.generate
-    end
-
-    def upload_result
-      uploaded_file = derivation.retrieve
-
-      unless uploaded_file
-        derivative    = derivation.generate
-        uploaded_file = derivation.upload(derivative)
-
-        derivative.unlink
+        derivation.generate
       end
-
-      uploaded_file
     end
   end
 
@@ -494,6 +553,9 @@ class Shrine
 
     private
 
+    # Calls the derivation block with the source file and derivation arguments.
+    # If a file object is given, passes that as the source file, otherwise
+    # downloads the source uploaded file.
     def generate(file)
       if download
         with_downloaded(file) do |file|
@@ -508,6 +570,8 @@ class Shrine
       end
     end
 
+    # Massages the derivation result, ensuring it's opened in binary mode,
+    # rewinded and flushed to disk.
     def normalize(derivative)
       if derivative.is_a?(Tempfile)
         derivative.open
@@ -534,17 +598,17 @@ class Shrine
       end
     end
 
+    # Downloads the source uploaded file from the storage.
     def download_source
-      download_args = download_options.any? ? [download_options] : []
-      downloaded    = false
-
-      source.download(*download_args) do |file|
-        downloaded = true
-        yield file
+      begin
+        file = source.download(**download_options)
+      rescue *download_errors
+        raise Derivation::SourceNotFound, "source file \"#{source.id}\" was not found on storage :#{source.storage_key}"
       end
-    rescue *download_errors
-      raise if downloaded # re-raise if the error didn't happen on download
-      raise Derivation::SourceNotFound, "source file \"#{source.id}\" was not found on storage :#{source.storage_key}"
+
+      yield file
+    ensure
+      file.close! if file
     end
 
     def derivation_block
@@ -559,16 +623,38 @@ class Shrine
   class Derivation::Upload < Derivation::Command
     delegate :upload_location, :upload_storage, :upload_options
 
+    # Uploads the derivation result to the dedicated location on the storage.
+    # If a file object is given, uploads that to the storage, otherwise calls
+    # the derivation block and uploads the result.
     def call(derivative = nil)
-      derivative ||= derivation.generate
-
-      uploader.upload derivative,
-        location:       upload_location,
-        upload_options: upload_options
+      with_derivative(derivative) do |uploadable|
+        uploader.upload uploadable,
+          location:       upload_location,
+          upload_options: upload_options,
+          delete:         false # disable delete_raw plugin
+      end
     end
 
     private
 
+    def with_derivative(derivative)
+      if derivative
+        # we want to keep the provided file open and rewinded
+        File.open(derivative.path, binmode: true) do |file|
+          yield file
+        end
+      else
+        # generate the derivative and delete it afterwards
+        begin
+          file = derivation.generate
+          yield file
+        ensure
+          file.close
+          File.delete(file.path)
+        end
+      end
+    end
+
     def uploader
       shrine_class.new(upload_storage)
     end
@@ -577,6 +663,8 @@ class Shrine
   class Derivation::Retrieve < Derivation::Command
     delegate :upload_location, :upload_storage
 
+    # Returns a Shrine::UploadedFile object pointing to the uploaded derivation
+    # result it exists on the storage.
     def call
       if storage.exists?(upload_location)
         shrine_class::UploadedFile.new(
@@ -596,6 +684,7 @@ class Shrine
   class Derivation::Delete < Derivation::Command
     delegate :upload_location, :upload_storage
 
+    # Deletes the uploaded derivation result from the storage.
     def call
       storage.delete(upload_location)
     end
@@ -616,6 +705,8 @@ class Shrine
       @secret_key = secret_key
     end
 
+    # Returns a URL with the `signature` query parameter generated from the
+    # given path components and query parameters.
     def signed_url(*components, params)
       path  = Rack::Utils.escape_path(components.join("/"))
       query = Rack::Utils.build_query(params)
@@ -627,6 +718,10 @@ class Shrine
       "#{path}?#{query}"
     end
 
+    # Calculcates the signature from the URL and checks whether it matches the
+    # value in the `signature` query parameter. Raises `InvalidSignature` if
+    # the `signature` parameter is missing or its value doesn't match the
+    # calculated signature.
     def verify_url(path_with_query)
       path, query = path_with_query.split("?")
 
@@ -645,6 +740,8 @@ class Shrine
       end
     end
 
+    # Uses HMAC-SHA-256 algorithm to generate a signature from the given string
+    # using the secret key.
     def generate_signature(string)
       OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, secret_key, string)
     end