shrine 2.11.0 → 2.12.0

data/doc/paperclip.md

@@ -19,7 +19,8 @@ class Photo < ActiveRecord::Base
       bucket:            "my-bucket",
       access_key_id:     "abc",
       secret_access_key: "xyz",
-    }
+    },
+    s3_region: "eu-west-1",
 end
 ```
 
@@ -30,6 +31,7 @@ Shrine.storages[:store] = Shrine::Storage::S3.new(
   bucket:            "my-bucket",
   access_key_id:     "abc",
   secret_access_key: "xyz",
+  region:            "eu-west-1",
 )
 ```
 
@@ -102,16 +104,17 @@ class ImageUploader < Shrine
   plugin :versions
 
   process(:store) do |io, context|
-    original = io.download
-    pipeline = ImageProcessing::MiniMagick.source(original)
+    versions = { original: io } # retain original
 
-    size_800 = pipeline.resize_to_limit!(800, 800)
-    size_500 = pipeline.resize_to_limit!(500, 500)
-    size_300 = pipeline.resize_to_limit!(300, 300)
+    io.download do |original|
+      pipeline = ImageProcessing::MiniMagick.source(original)
 
-    original.close!
+      versions[:large]  = pipeline.resize_to_limit!(800, 800)
+      versions[:medium] = pipeline.resize_to_limit!(500, 500)
+      versions[:small]  = pipeline.resize_to_limit!(300, 300)
+    end
 
-    { original: io, large: size_800, medium: size_500, small: size_300 }
+    versions # return the hash of processed files
   end
 end
 ```

data/doc/processing.md

@@ -91,7 +91,7 @@ defaults for the web.
 Since we'll be storing multiple derivates of the original file, we'll need to
 also load the `versions` plugin, which allows us to return a Hash of processed
 files. For processing we'll be using the `ImageProcessing::MiniMagick` backend,
-which performs processing with [ImageMagick]/[GraphicsMagick].
+which performs processing with [ImageMagick] or [GraphicsMagick].
 
 ```sh
 $ brew install imagemagick
@@ -110,16 +110,17 @@ class ImageUploader < Shrine
   plugin :delete_raw
 
   process(:store) do |io, context|
-    original = io.download
-    pipeline = ImageProcessing::MiniMagick.source(original)
+    versions = { original: io } # retain original
 
-    size_800 = pipeline.resize_to_limit!(800, 800)
-    size_500 = pipeline.resize_to_limit!(500, 500)
-    size_300 = pipeline.resize_to_limit!(300, 300)
+    io.download do |original|
+      pipeline = ImageProcessing::MiniMagick.source(original)
 
-    original.close!
+      versions[:large]  = pipeline.resize_to_limit!(800, 800)
+      versions[:medium] = pipeline.resize_to_limit!(500, 500)
+      versions[:small]  = pipeline.resize_to_limit!(300, 300)
+    end
 
-    { original: io, large: size_800, medium: size_500, small: size_300 }
+    versions # return the hash of processed files
   end
 end
 ```
@@ -144,16 +145,17 @@ class ImageUploader < Shrine
   plugin :delete_raw
 
   process(:store) do |io, context|
-    original = io.download
-    pipeline = ImageProcessing::Vips.source(original)
+    versions = { original: io } # retain original
 
-    size_800 = pipeline.resize_to_limit!(800, 800)
-    size_500 = pipeline.resize_to_limit!(500, 500)
-    size_300 = pipeline.resize_to_limit!(300, 300)
+    io.download do |original|
+      pipeline = ImageProcessing::Vips.source(original) # instead of ImageProcessing::MiniMagick
 
-    original.close!
+      versions[:large]  = pipeline.resize_to_limit!(800, 800)
+      versions[:medium] = pipeline.resize_to_limit!(500, 500)
+      versions[:small]  = pipeline.resize_to_limit!(300, 300)
+    end
 
-    { original: io, large: size_800, medium: size_500, small: size_300 }
+    versions # return the hash of processed files
   end
 end
 ```
@@ -218,23 +220,24 @@ class ImageUploader < Shrine
   plugin :delete_raw
 
   process(:store) do |io, context|
-    original = io.download
-    pipeline = ImageProcessing::Vips.source(original)
+    versions = { original: io } # retain original
 
-    # the `io` object contains the MIME type of the original file
-    if io.mime_type != "image/png"
-      pipeline = pipeline
-        .convert("jpeg")
-        .saver(interlace: true)
-    end
+    io.download do |original|
+      pipeline = ImageProcessing::Vips.source(original)
 
-    size_800 = pipeline.resize_to_limit!(800, 800)
-    size_500 = pipeline.resize_to_limit!(500, 500)
-    size_300 = pipeline.resize_to_limit!(300, 300)
+      # Shrine::UploadedFile object contains information about the MIME type
+      unless %w[image/png].include?(io.mime_type)
+        pipeline = pipeline
+          .convert("jpeg")
+          .saver(interlace: true)
+      end
 
-    original.close!
+      versions[:large]  = pipeline.resize_to_limit!(800, 800)
+      versions[:medium] = pipeline.resize_to_limit!(500, 500)
+      versions[:small]  = pipeline.resize_to_limit!(300, 300)
+    end
 
-    { original: io, large: size_800, medium: size_500, small: size_300 }
+    versions # return the hash of processed files
   end
 end
 ```
@@ -281,6 +284,7 @@ class VideoUploader < Shrine
 
     { original: io, transcoded: transcoded, screenshot: screenshot }
   end
+end
 ```
 
 ## On-the-fly processing
@@ -324,6 +328,7 @@ basic [configuration][Dragonfly configuration]:
 Dragonfly.app.configure do
   url_format "/attachments/:job"
   secret "my secure secret" # used to generate the protective SHA
+  plugin :imagemagick
 end
 
 use Dragonfly::Middleware
@@ -340,6 +345,8 @@ updated):
 
 ```rb
 Shrine::Storage::S3.new(upload_options: { acl: "public-read" }, **other_options)
+# ...
+Shrine.plugin :default_url_options, cache: { public: true }, store: { public: true }
 ```
 
 Now you can generate Dragonfly URLs from `Shrine::UploadedFile` objects:
@@ -347,7 +354,7 @@ Now you can generate Dragonfly URLs from `Shrine::UploadedFile` objects:
 ```rb
 def thumbnail_url(uploaded_file, dimensions)
   Dragonfly.app
-    .fetch(uploaded_file.url(public: true))
+    .fetch(uploaded_file.url)
     .thumb(dimensions)
     .url
 end

data/doc/refile.md

@@ -72,16 +72,17 @@ class ImageUploader < Shrine
   plugin :versions
 
   process(:store) do |io, context|
-    original = io.download
-    pipeline = ImageProcessing::MiniMagick.source(original)
+    versions = { original: io } # retain original
 
-    size_800 = pipeline.resize_to_limit!(800, 800)
-    size_500 = pipeline.resize_to_limit!(500, 500)
-    size_300 = pipeline.resize_to_limit!(300, 300)
+    io.download do |original|
+      pipeline = ImageProcessing::MiniMagick.source(original)
 
-    original.close!
+      versions[:large]  = pipeline.resize_to_limit!(800, 800)
+      versions[:medium] = pipeline.resize_to_limit!(500, 500)
+      versions[:small]  = pipeline.resize_to_limit!(300, 300)
+    end
 
-    { original: io, large: size_800, medium: size_500, small: size_300 }
+    versions # return the hash of processed files
   end
 end
 ```

data/lib/shrine.rb

@@ -806,16 +806,17 @@ class Shrine
         #
         #     # or
         #
-        #     uploaded_file.open { |io| io.read }
-        #     #=> "..."
+        #     uploaded_file.open { |io| io.read } # the IO is automatically closed
         def open(*args)
-          return to_io unless block_given?
+          @io.close if @io && !(@io.respond_to?(:closed?) && @io.closed?)
+          @io = storage.open(id, *args)
+
+          return @io unless block_given?
 
           begin
-            @io = storage.open(id, *args)
             yield @io
           ensure
-            @io.close if @io
+            @io.close
             @io = nil
           end
         end
@@ -836,7 +837,6 @@ class Shrine
         #     # or
         #
         #     uploaded_file.download { |tempfile| tempfile.read } # tempfile is deleted
-        #     #=> "..."
         def download(*args)
           if storage.respond_to?(:download)
             tempfile = storage.download(id, *args)
@@ -967,7 +967,7 @@ class Shrine
         # Returns an opened IO object for the uploaded file by calling `#open`
         # on the storage.
         def io
-          @io ||= storage.open(id)
+          @io || open
         end
       end
     end

data/lib/shrine/plugins/data_uri.rb

@@ -151,7 +151,7 @@ class Shrine
         # 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)
-          return if uri == ""
+          return if uri == "" || uri.nil?
 
           data_file = shrine_class.data_uri(uri)
           assign(data_file)

data/lib/shrine/plugins/determine_mime_type.rb

@@ -177,13 +177,14 @@ class Shrine
 
             status = thread.value
 
-            raise Error, stderr.read unless status.success?
+            raise Error, "file command failed to spawn: #{stderr.read}" if status.nil?
+            raise Error, "file command failed: #{stderr.read}" unless status.success?
             $stderr.print(stderr.read)
 
             stdout.read.strip
           end
         rescue Errno::ENOENT
-          raise Error, "The `file` command-line tool is not installed"
+          raise Error, "file command-line tool is not installed"
         end
 
         def extract_with_fastimage(io)

data/lib/shrine/plugins/download_endpoint.rb

@@ -9,13 +9,15 @@ class Shrine
   module Plugins
     # The `download_endpoint` plugin provides a Rack endpoint for downloading
     # uploaded files from specified storages. This can be useful when files
-    # from your storages aren't accessible over URL (e.g. database storages) or
+    # 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.
     #
-    #     plugin :download_endpoint, storages: [:store], prefix: "attachments"
+    # You can configure the plugin with the path prefix which the endpoint will
+    # be mounted on.
     #
-    # After loading the plugin the endpoint should be mounted on the specified
-    # prefix:
+    #     plugin :download_endpoint, prefix: "attachments"
+    #
+    # The endpoint should then be mounted on the specified prefix:
     #
     #     # config.ru (Rack)
     #     map "/attachments" do
@@ -29,38 +31,31 @@ class Shrine
     #       mount Shrine.download_endpoint => "/attachments"
     #     end
     #
-    # Now all stored files can be downloaded through the endpoint, and the
-    # endpoint will efficiently stream the file from the storage when the
-    # storage supports it. `UploadedFile#url` will automatically return the URL
-    # to the endpoint for files uploaded to specified storages:
+    # Any uploaded file can be downloaded through this endpoint. When a file is
+    # requested, its content will be efficiently streamed from the storage into
+    # the response body.
     #
-    #     user.avatar.url #=> "/attachments/eyJpZCI6ImFkdzlyeTM5ODJpandoYWla"
+    # Links to the download endpoint are generated by calling
+    # `UploadedFile#download_url` instead of the usual `UploadedFile#url`.
     #
-    # :storages
-    # :  An array of storage keys for which `UploadedFile#url` should generate
-    #    download endpoint URLs.
+    #     uploaded_file.download_url #=> "/attachments/eyJpZCI6ImFkdzlyeTM5ODJpandoYWla"
     #
-    # :prefix
-    # :  The location where the download endpoint was mounted. If it was
-    #    mounted at the root level, this should be set to nil.
+    # Note that streaming the file through your app might impact the request
+    # throughput of your app, depending on which web server is used. It's
+    # recommended to either configure a CDN to serve these files:
     #
-    # :host
-    # :  The host that you want the download URLs to use (e.g. your app's domain
-    #    name or a CDN). By default URLs are relative.
+    #     plugin :download_endpoint, host: "http://abc123.cloudfront.net"
     #
-    # :disposition
-    # :  Can be set to "attachment" if you want that the user is always
-    #    prompted to download the file when visiting the download URL.
-    #    The default is "inline".
+    # or configure the endpoint to redirect to the direct file URL:
     #
-    # Note that streaming the file through your app might impact the request
-    # throughput of your app, depending on which web server is used. In any
-    # case, it's recommended to use some kind of cache in front of the web
-    # server.
+    #     plugin :download_endpoint, redirect: true
+    #     # or
+    #     plugin :download_endpoint, redirect: -> (uploaded_file, request) do
+    #       # return URL which the request will redirect to
+    #     end
     #
-    # If you want to authenticate the downloads, it's recommended you use the
-    # `rack_response` plugin directly. With it you can return file responses
-    # from inside your router/controller.
+    # Alternatively, you can stream files yourself from your controller using
+    # the `rack_response` plugin, which this plugin uses internally.
     #
     # [Roda]: https://github.com/jeremyevans/roda
     module DownloadEndpoint
@@ -68,13 +63,35 @@ class Shrine
         uploader.plugin :rack_response
       end
 
+      # Accepts the following options:
+      #
+      # :prefix
+      # :  The location where the download endpoint was mounted. If it was
+      #    mounted at the root level, this should be set to nil.
+      #
+      # :host
+      # :  The host that you want the download URLs to use (e.g. your app's domain
+      #    name or a CDN). By default URLs are relative.
+      #
+      # :disposition
+      # :  Can be set to "attachment" if you want that the user is always
+      #    prompted to download the file when visiting the download URL.
+      #    The default is "inline".
+      #
+      # :redirect
+      # :  If set to `true`, requests will redirect to the direct file URL. If
+      #    set to a proc object, the proc will called with the `UploadedFile`
+      #    instance and the `Rack::Request` object, and is expected to return
+      #    the URL to which the request will redirect to. Defaults to `false`,
+      #    meaning that the file content will be served through the endpoint.
       def self.configure(uploader, opts = {})
         uploader.opts[:download_endpoint_storages] = opts.fetch(:storages, uploader.opts[:download_endpoint_storages])
         uploader.opts[:download_endpoint_prefix] = opts.fetch(:prefix, uploader.opts[:download_endpoint_prefix])
         uploader.opts[:download_endpoint_disposition] = opts.fetch(:disposition, uploader.opts.fetch(:download_endpoint_disposition, "inline"))
         uploader.opts[:download_endpoint_host] = opts.fetch(:host, uploader.opts[:download_endpoint_host])
+        uploader.opts[:download_endpoint_redirect] = opts.fetch(:redirect, uploader.opts.fetch(:download_endpoint_redirect, false))
 
-        raise Error, "The :storages option is required for download_endpoint plugin" if uploader.opts[:download_endpoint_storages].nil?
+        Shrine.deprecation("The :storages download_endpoint option is deprecated, you should use UploadedFile#download_url for generating URLs to the download endpoint.") if uploader.opts[:download_endpoint_storages]
 
         uploader.assign_download_endpoint(App) unless uploader.const_defined?(:DownloadEndpoint)
       end
@@ -96,6 +113,7 @@ class Shrine
           endpoint_class = Class.new(klass)
           endpoint_class.opts[:shrine_class] = self
           endpoint_class.opts[:disposition]  = opts[:download_endpoint_disposition]
+          endpoint_class.opts[:redirect]     = opts[:download_endpoint_redirect]
 
           @download_endpoint = endpoint_class
 
@@ -113,19 +131,20 @@ class Shrine
         # uploaded file's id. For other uploaded files that aren't in the list
         # of storages it just returns their original URL.
         def url(**options)
-          if shrine_class.opts[:download_endpoint_storages].include?(storage_key.to_sym)
+          if download_storages && download_storages.include?(storage_key.to_sym)
+            Shrine.deprecation("The :storages option for download_endpoint plugin is deprecated and will be obsolete in Shrine 3. Use UploadedFile#download_url instead.")
             download_url
           else
             super
           end
         end
 
-        private
-
         def download_url
           [download_host, *download_prefix, download_identifier].join("/")
         end
 
+        private
+
         # Generates URL-safe identifier from data, filtering only a subset of
         # metadata that the endpoint needs to prevent the URL from being too
         # long.
@@ -145,6 +164,10 @@ class Shrine
         def download_prefix
           shrine_class.opts[:download_endpoint_prefix]
         end
+
+        def download_storages
+          shrine_class.opts[:download_endpoint_storages]
+        end
       end
 
       # Routes incoming requests. It first asserts that the storage is existent
@@ -156,21 +179,32 @@ class Shrine
           r.on storage_names do |storage_name|
             r.get /(.*)/ do |id|
               data = { "id" => id, "storage" => storage_name, "metadata" => {} }
-              stream_file(data)
+              serve_file(data)
             end
           end
 
           r.get /(.*)/ do |identifier|
             data = serializer.load(identifier)
-            stream_file(data)
+            serve_file(data)
           end
         end
 
         private
 
-        def stream_file(data)
+        # Streams or redirects to the uploaded file.
+        def serve_file(data)
           uploaded_file = get_uploaded_file(data)
-          range         = env["HTTP_RANGE"]
+
+          if redirect
+            redirect_to_file(uploaded_file)
+          else
+            stream_file(uploaded_file)
+          end
+        end
+
+        # Streams the uploaded file content.
+        def stream_file(uploaded_file)
+          range = env["HTTP_RANGE"]
 
           status, headers, body = uploaded_file.to_rack_response(disposition: disposition, range: range)
           headers["Cache-Control"] = "max-age=#{365*24*60*60}" # cache for a year
@@ -178,6 +212,17 @@ class Shrine
           request.halt [status, headers, body]
         end
 
+        # Redirects to the uploaded file's direct URL or the specified URL proc.
+        def redirect_to_file(uploaded_file)
+          if redirect == true
+            redirect_url = uploaded_file.url
+          else
+            redirect_url = redirect.call(uploaded_file, request)
+          end
+
+          request.redirect redirect_url
+        end
+
         # Returns a Shrine::UploadedFile, or returns 404 if file doesn't exist.
         def get_uploaded_file(data)
           uploaded_file = shrine_class.uploaded_file(data)
@@ -207,6 +252,10 @@ class Shrine
           shrine_class.download_endpoint_serializer
         end
 
+        def redirect
+          opts[:redirect]
+        end
+
         def disposition
           opts[:disposition]
         end