shrine 2.16.0 → 2.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a54ce86ad9f430b7c0896fa83db280316dd3e48a27bff320445b561b966bdcd
-  data.tar.gz: 2924f5048e3ff3991d49da834000564612eba1749576c7ea42cf446cb025c7ed
+  metadata.gz: e01f77764b72ba6acce9663b1dc0652afb5c645682aaec7972ebeeda8e326655
+  data.tar.gz: 5f9e8accd7448390a6f3cd25158eb01295ec6e1ac9fb8e70b10c2adf56f34e4a
 SHA512:
-  metadata.gz: 7a0e9566b2b6b7a78c2a85019108147bcd071b46cef63fb1cdc848ee1fb1a8cf086afce8bf62d966e88cbeefe35d4437d471c7a7180a8abd34682d47fe62b60b
-  data.tar.gz: 013cb42c24c2af94c2aa84344c5ce9e07e6001dfb56a06e2b6f4c4805969c4fa2d45421a455e34d1ec9290607c5ffebddd0114d91871cd99e84b6623cb65527e
+  metadata.gz: 1bb7469736eeb705faa8bc68e7afa1373d0d3e0af221e5a1372bf829f4c0c553726b4a5cc3aa82081e5c54781636bf8d4a4e97a703f08dfc0ed0162d8470aa9b
+  data.tar.gz: d0b0bd017bb9e79c2f7761640ed664ea8f673975ee86871d18df550c04838bdf7df0a3e50a0c96b0b59d9192b459ace9052a909624da7dc8ed6a5dc313a84c70

data/CHANGELOG.md

@@ -1,3 +1,53 @@
+## 2.17.0 (2019-05-06)
+
+* `data_uri` – Add `Attacher#assign_data_uri` which accepts additional `Shrine#upload` options (@janko)
+
+* `remote_url` – Accept additional `Shrine#upload` options in `Attacher#assign_remote_url` (@janko)
+
+* `download_endpoint` – Allow passing options to `Shrine.download_endpoint` (@janko)
+
+* `download_endpoint` – Fix `Shrine.download_endpoint` not being accepted by Rails' `#mount` (@janko)
+
+* `download_endpoint` – Remove Roda dependency (@janko)
+
+* `presign_endpoint` – Soft-rename `Shrine::Plugins::PresignEndpoint::App` class to `Shrine::PresignEndpoint` (@janko)
+
+* `upload_endpoint` – Soft-rename `Shrine::Plugins::UploadEndpoint::App` class to `Shrine::UploadEndpoint` (@janko)
+
+* `processing` – Fix defining process blocks being applied to `Shrine` superclasses (@ksol)
+
+* `derivation_endpoint` – Add `ETag` header to prevent `Rack::ETag` from buffering file content (@janko)
+
+* `rack_response` – Add `ETag` header to prevent `Rack::ETag` from buffering file content (@janko)
+
+* `download_endpoint` – Add `ETag` header to prevent `Rack::ETag` from buffering file content (@janko)
+
+* `default_url` – Add `:host` for specifying the URL host (@janko)
+
+* `versions` – Fix uploaded versions being deleted when string version names are used (@janko)
+
+* `versions` – Allow `Attacher#url` to accept version name indifferently (@FunkyloverOne)
+
+* Improve performance of cleaning empty directories on deletion in `FileSystem` storage (@adamniedzielski)
+
+* Drop MRI 2.3 support (@janko)
+
+* `metadata_attributes` – Fix `Attacher#assign` not accepting additional options anymore (@janko)
+
+* `derivation_endpoint` – Add support for Rack < 2 (@Antsiscool)
+
+* `derivation_endpoint` – Fix `:upload` option being incompatible with `moving` plugin (@speedo-spin)
+
+* `determine_mime_type` – Allow passing options to analzyers (Marcel accepts `:filename_fallback` option) (@hmistry)
+
+* `determine_mime_type` – Revert "Extended determine MIME type with Marcel" (@hmistry)
+
+* `rack_response` – improve performance for upper bounded `Range` header values (@zarqman)
+
+* `rack_response` – prevent response body from yielding `nil`-chunks (@zarqman)
+
+* `parsed_json` – Accepts hashes with symbols keys (@aglushkov)
+
 ## 2.16.0 (2019-02-18)
 
 * `derivation_endpoint` – Add `:upload_open_options` for download option for derivation result (@janko)

data/doc/plugins/data_uri.md

@@ -34,6 +34,15 @@ plugin :data_uri, error_message: "data URI was invalid"
 plugin :data_uri, error_message: ->(uri) { I18n.t("errors.data_uri_invalid") }
 ```
 
+## Upload options
+
+If you want to pass additional options for `Shrine#upload`, you can use
+`#assign_data_uri`:
+
+```rb
+attacher.assign_data_uri(uri, metadata: { "mime_type" => "text/plain" })
+```
+
 ## File extension
 
 A data URI doesn't convey any information about the file extension, so when

data/doc/plugins/default_url.md

@@ -32,4 +32,16 @@ Attacher.default_url do |options|
 end
 ```
 
+## Host
+
+If the default URL is relative, the URL host can be specified via the `:host`
+option:
+
+```rb
+plugin :default_url, host: "https://example.com"
+```
+```rb
+user.avatar_url #=> "https://example.com/avatar/missing.jpg"
+```
+
 [default_url]: /lib/shrine/plugins/default_url.rb

data/doc/plugins/derivation_endpoint.md

@@ -445,9 +445,10 @@ plugin :derivation_endpoint, upload: true,
 
 ### Redirecting
 
-You can configure the endpoint to redirect to the uploaded derivative on the
-storage instead of serving it through the endpoint (which is the default
-behaviour) by setting both `:upload` and `:upload_redirect` to `true`:
+If you are using remote cloud storages, you can configure the endpoint to
+redirect the client to the uploaded derivative on the remote storage instead of
+serving it through the endpoint (which is the default behaviour) by setting both
+`:upload` and `:upload_redirect` to `true`:
 
 ```rb
 plugin :derivation_endpoint, upload: true,
@@ -463,6 +464,22 @@ plugin :derivation_endpoint, upload: true,
                              upload_redirect_url_options: { public: true }
 ```
 
+If you are using the local filesystem storage, then redirecting does not make
+sense.
+
+### Deleting derivatives
+
+When you use the `:upload` options and upload the derivatives to storage, there
+will come a time when you need to delete the derivatives because the original
+file is being replaced, deleted, or some other reason. In this case, you can
+delete the derivatives before deleting the record or updating the record with
+the new original file.
+
+```rb
+# photo is the model and image is the file attachment
+photo.image.derivation(:thumbnail).delete
+```
+
 ## Cache busting
 
 The derivation endpoint response instructs browsers, CDNs and other clients to
@@ -567,8 +584,8 @@ these errors converted to 404 responses by adding them to `:download_errors`:
 
 ```rb
 plugin :derivation_endpoint, download_errors: [
-  Errno::ENOENT,              # raised by Shrine::Storage::FileSystem
-  Aws::S3::Errors::NoSuchKey, # raised by Shrine::Storage::S3
+  Errno::ENOENT,             # raised by Shrine::Storage::FileSystem
+  Aws::S3::Errors::NotFound, # raised by Shrine::Storage::S3
 ]
 ```
 

data/doc/plugins/determine_mime_type.md

@@ -9,17 +9,19 @@ plugin :determine_mime_type
 
 By default the UNIX [file] utility is used to determine the MIME type, and the
 result is automatically written to the `mime_type` metadata field. You can
-choose a different built-in MIME type analyzer:
+choose a different built-in MIME type analyzer, for example:
 
 ```rb
 plugin :determine_mime_type, analyzer: :marcel
 ```
 
+## Analyzers
+
 The following analyzers are accepted:
 
 | Name            | Description                                                                                                                                                                                                                                                                       |
 | :------         | :-----------                                                                                                                                                                                                                                                                      |
-| `:file`         | (Default). Uses the [file] utility to determine the MIME type from file contents. It is installed by default on most operating systems, but the [Windows equivalent] needs to be installed separately.                                                                            |
+| `:file`         | (**Default**). Uses the [file] utility to determine the MIME type from file contents. It is installed by default on most operating systems, but the [Windows equivalent] needs to be installed separately.                                                                            |
 | `:fastimage`    | Uses the [fastimage] gem to determine the MIME type from file contents. Fastimage is optimized for speed over accuracy. Best used for image content.                                                                                                                              |
 | `:filemagic`    | Uses the [ruby-filemagic] gem to determine the MIME type from file contents, using a similar MIME database as the `file` utility. Unlike the `file` utility, ruby-filemagic works on Windows without any setup.                                                                   |
 | `:mimemagic`    | Uses the [mimemagic] gem to determine the MIME type from file contents. Unlike ruby-filemagic, mimemagic is a pure-ruby solution, so it will work across all Ruby implementations.                                                                                                |
@@ -28,8 +30,33 @@ The following analyzers are accepted:
 | `:mini_mime`    | Uses the [mini_mime] gem to determine the MIME type from the file extension. Note that unlike other solutions, this analyzer is not guaranteed to return the actual MIME type of the file.                                                                                        |
 | `:content_type` | Retrieves the value of the `#content_type` attribute of the IO object. Note that this value normally comes from the "Content-Type" request header, so it's not guaranteed to hold the actual MIME type of the file.                                                               |
 
-A single analyzer is not going to properly recognize all types of files, so you
-can build your own custom analyzer for your requirements, where you can combine
+You'll need to ensure the file utility or gem is in installed on your system
+for Shrine to use the analyzer.
+
+## Analyzer Options
+
+Currently, Marcel is the only analyzer that accepts options to be passed in.
+Analyzer options can be set in one of two ways:
+
+```rb
+plugin :determine_mime_type, analyzer: :marcel, analyzer_options: { filename_fallback: true }
+
+# or
+
+plugin :determine_mime_type, analyzer: -> (io, analyzers) do
+  mime_type = analyzers[:marcel].call(io, filename_fallback: true)
+end
+```
+
+The `:filename_fallback` option for Marcel analyzer lets it use the filename as
+a fallback option when it fails to determine the MIME type from the file
+content. Set `:filename_fallback` to `true` in order to fallback to using the
+filename or set to `false` to not use the filename (this is the default).
+
+## Issues
+
+If you find using a single analyzer is not able to recognize all of the file
+types in your application, you can build your own custom analyzer and combine
 the built-in analyzers. For example, if you want to correctly determine MIME
 type of .css, .js, .json, .csv, .xml, or similar text-based files, you can
 combine `file` and `mime_types` analyzers:
@@ -42,7 +69,9 @@ plugin :determine_mime_type, analyzer: -> (io, analyzers) do
 end
 ```
 
-You can also use methods for determining the MIME type directly:
+## Other Usage
+
+You can also use the methods for determining the MIME type directly:
 
 ```rb
 # or YourUploader.determine_mime_type(io)

data/doc/plugins/download_endpoint.md

@@ -3,12 +3,7 @@
 The [`download_endpoint`][download_endpoint] plugin provides a Rack app for
 downloading uploaded files from specified storages. This can be useful when
 files from your storage isn't accessible over URL (e.g. database storages) or
-if you want to authenticate your downloads. It requires the [Roda] gem.
-
-```rb
-# Gemfile
-gem "roda" # dependency of the download_endpoint plugin
-```
+if you want to authenticate your downloads.
 
 You can configure the plugin with the path prefix which the endpoint will be
 mounted on.
@@ -104,6 +99,14 @@ plugin :download_endpoint, redirect: -> (uploaded_file, request) do
 end
 ```
 
+## Ad-hoc options
+
+You can override any of the options above when creating the endpoint:
+
+```rb
+Shrine.download_endpoint(disposition: "attachment")
+```
+
 ## Custom endpoint
 
 If you want to have more control on download requests, you can use the
@@ -120,4 +123,3 @@ If you want to have more control on download requests, you can use the
 | `:redirect`         | Whether to redirect to uploaded files on the storage                              | `false`  |
 
 [download_endpoint]: /lib/shrine/plugins/download_endpoint.rb
-[Roda]: https://github.com/jeremyevans/roda

data/doc/plugins/remote_url.md

@@ -37,7 +37,13 @@ You can dynamically pass options to the downloader by using
 `Attacher#assign_remote_url`:
 
 ```rb
-attacher.assign_remote_url("http://example.com/cool-image.png", downloader: { 'Authorization' => 'Basic ...' })
+attacher.assign_remote_url(url, downloader: { 'Authorization' => 'Basic ...' })
+```
+
+You can also pass any other `Shrine#upload` options:
+
+```rb
+attacher.assign_remote_url(url, metadata: { "mime_type" => "text/plain" })
 ```
 
 ## Maximum size

data/doc/release_notes/2.17.0.md

@@ -0,0 +1,129 @@
+## New features
+
+* The `download_endpoint` plugin now accepts ad-hoc options when creating the
+  endpoint instance, which override any plugin options.
+
+  ```rb
+  Shrine.download_enpdoint(disposition: "attachment")
+  ```
+
+* The `Shrine::Attacher#assign_remote_url` method in the `remote_url` plugin
+  now accepts additional options forwarded to `Shrine#upload`.
+
+  ```rb
+  attacher.assign_remote_url(url, metadata: { "mime_type" => "text/plain" })
+  ```
+
+* The `Shrine::Attacher#assign_data_uri` method has been added to the
+  `data_uri` plugin, which accepts additional `Shrine#upload` options.
+
+  ```rb
+  attacher.assign_data_uri(uri, metadata: { "filename" => "custom.txt" })
+  ```
+
+* The `default_url` plugin now accepts a `:host` option for specifying the URL
+  host.
+
+  ```rb
+  plugin :default_url, host: "https://example.com"
+
+  Attacher.default_url { "/#{name}/missing.png" }
+  ```
+  ```rb
+  user.avatar_url #=> "https://example.com/avatar/missing.png"
+  ```
+
+## Other improvements
+
+* The `derivation_endpoint` plugin now works correctly when `moving` plugin
+  is loaded and `upload: true` is set.
+
+* The `Shrine.download_endpoint` object is now compatible with the Rails router
+  again (this was broken in Shrine 2.15.0).
+
+* The `rack_response` plugin was in certain cases producing `nil`-chunks for
+  the response body, which caused exceptions with some web servers. This has
+  now been fixed.
+
+* The `rack_response` plugin now stops retrieving file content that goes past
+  the range specified in the `Range` header. This improves performance for
+  storage classes that internally use `Down::ChunkedIO`.
+
+* The `derivation_endpoint`, `rack_response`, and `download_endpoint` plugins
+  now include `ETag` in the headers of responses, preventing the `Rack::ETag`
+  middleware from buffering the response body.
+
+* Fixed inheritance of `process` blocks in the `processing` plugin. Now adding
+  `process` blocks in the `Shrine` subclass won't affect the superclass.
+
+* Improved performance of `Shrine::Storage::FileSystem#delete` by switching
+  from `Dir.foreach` to `Dir.empty?`.
+
+* The `parsed_json` plugin now accepts hashes with symbol keys.
+
+* The `versions` plugin now accepts string version names in
+  `Shrine::Attacher#url`.
+
+* The `versions` plugin now supports returning a hash of versions with string
+  names inside the `process` block.
+
+* The `download_endpoint` plugin has been rewritten to use plain Rack, so Roda
+  isn't a dependency anymore.
+
+* The endpoint's `#inspect` and `#to_s` outputs in `upload_endpoint`,
+  `presign_endpoint`, `download_endpoint`, and `derivation_endpoint` plugins
+  have been simplified. Now the `rake routes` command output in Rails apps
+  should be much more compact.
+
+  ```rb
+  # BEFORE:
+  ImageUploader.upload_endpoint(:cache)  #=> #<Shrine::Plugins::UploadEndpoint::App:0x00007f91bec17dc8 @max_size=nil, @rack_response=nil, @shrine_class=ImageUploader, @storage_key=:cache, @upload=nil, @upload_context=nil>
+  ImageUploader.presign_endpoint(:cache) #=> #<Shrine::Plugins::PresignEndpoint::App:0x00007f91beca4ea8 @presign=nil, @presign_location=nil, @presign_options=nil, @rack_response=nil, @shrine_class=ImageUploader, @storage_key=:cache>
+  ImageUploader.download_endpoint        #=> #<Class:0x00007f91bed1fa90>
+  ImageUploader.derivation_endpoint      #=> #<Shrine::DerivationEndpoint:0x00007f91bed4c900 @options={}, @shrine_class=ImageUploader>
+
+  # AFTER:
+  ImageUploader.upload_endpoint(:cache)  #=> #<ImageUploader::UploadEndpoint(:cache)>
+  ImageUploader.presign_endpoint(:cache) #=> #<ImageUploader::PresignEndpoint(:cache)>
+  ImageUploader.download_endpoint        #=> #<ImageUploader::DownloadEndpoint>
+  ImageUploader.derivation_endpoint      #=> #<ImageUploader::DerivationEndpoint>
+  ```
+
+* The `derivation_endpoint` plugin is now compatible with Rack 1.6.
+
+* The `metadata_attributes` plugin now preserves `Attacher#assign` method
+  signature, by retaining the second `options` argument.
+
+## Backwards compatibility
+
+* The support for MRI 2.3 has been dropped.
+
+* The automatic filename fallback was removed from the `:marcel` analyzer in
+  `determine_mime_type` plugin, as in some cases it caused MIME type to be
+  incorrectly determined and could cause potential security issues. You can
+  still opt in for it:
+
+  ```rb
+  plugin :determine_mime_type, analyzer: :marcel, analyzer_options: { filename_fallback: true }
+  ```
+
+* The `Shrine::Plugins::UploadEndpoint::App` class from the `upload_endpoint`
+  plugin has been renamed to `Shrine::UploadEndpoint`. The old constant will be
+  removed in Shrine 3.
+
+* The `Shrine::Plugins::PresignEndpoint::App` class from the `presign_endpoint`
+  plugin has been renamed to `Shrine::PresignEndpoint`. The old constant will
+  be removed in Shrine 3.
+
+* The `Shrine::Plugins::DownloadEndpoint::App` class is not a `Roda` subclass
+  anymore, it's now a PORO whose instance responds to `#call`. This shouldn't
+  affect your code unless you were calling Roda methods on that class.
+
+* The plugin options of `upload_enpdoint`, `presign_endpoint`, and
+  `download_endpoint` are now internally stored in a different place in
+  `Shrine.opts`. This shouldn't affect your code unless you were accessing
+  these options directly.
+
+* The `Shrine::UrlSigner` internal class in `derivation_endpoint` plugin has
+  been updated. This shouldn't affect your code unless you were
+  using/overriding that class.

data/doc/storage/s3.md

@@ -254,12 +254,11 @@ Shrine::Storage::S3(client: client, bucket: "my-bucket")
 
 ## Accelerate endpoint
 
-To use Amazon S3's [Transfer Acceleration] feature, you can change the
-`:endpoint` of the underlying client to the accelerate endpoint, and this will
-be applied both to regular and presigned uploads, as well as download URLs.
+To use Amazon S3's [Transfer Acceleration] feature, set
+`:use_accelerate_endpoint` to `true` when initializing the storage:
 
 ```rb
-Shrine::Storage::S3.new(endpoint: "https://s3-accelerate.amazonaws.com")
+Shrine::Storage::S3.new(use_accelerate_enpdoint: true, **other_options)
 ```
 
 ## Clearing cache

data/lib/shrine/plugins/data_uri.rb

@@ -83,11 +83,11 @@ class Shrine
         # the content type, decodes it, wrappes it in a StringIO and assigns it.
         # If it fails, it sets the error message and assigns the uri in an
         # instance variable so that it shows up on the UI.
-        def data_uri=(uri)
+        def assign_data_uri(uri, **options)
           return if uri == "" || uri.nil?
 
           data_file = shrine_class.data_uri(uri)
-          assign(data_file)
+          assign(data_file, **options)
         rescue ParseError => error
           message = shrine_class.opts[:data_uri_error_message] || error.message
           message = message.call(uri) if message.respond_to?(:call)
@@ -95,6 +95,11 @@ class Shrine
           @data_uri = uri
         end
 
+        # Alias for #assign_data_uri.
+        def data_uri=(uri)
+          assign_data_uri(uri)
+        end
+
         # Form builders require the reader as well.
         def data_uri
           @data_uri

data/lib/shrine/plugins/default_url.rb

@@ -6,7 +6,9 @@ class Shrine
     #
     # [doc/plugins/default_url.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/default_url.md
     module DefaultUrl
-      def self.configure(uploader, &block)
+      def self.configure(uploader, opts = {}, &block)
+        uploader.opts[:default_url_host] = opts.fetch(:host, uploader.opts[:default_url_host])
+
         if block
           uploader.opts[:default_url] = block
           Shrine.deprecation("Passing a block to default_url plugin is deprecated and will probably be removed in future versions of Shrine. Use `Attacher.default_url { ... }` instead.")
@@ -27,16 +29,26 @@ class Shrine
         private
 
         def default_url(**options)
-          if default_url_block
-            instance_exec(options, &default_url_block)
-          elsif shrine_class.opts[:default_url]
-            shrine_class.opts[:default_url].call(context.merge(options){|k, old, new| old})
+          url = if default_url_block
+                  instance_exec(options, &default_url_block)
+                elsif shrine_class.opts[:default_url]
+                  shrine_class.opts[:default_url].call(context.merge(options){|k, old, new| old})
+                end
+
+          if default_url_host
+            [default_url_host, url].join
+          else
+            url
           end
         end
 
         def default_url_block
           shrine_class.opts[:default_url_block]
         end
+
+        def default_url_host
+          shrine_class.opts[:default_url_host]
+        end
       end
     end