shrine 2.5.0 → 2.6.0

data/lib/shrine/plugins/default_url.rb

@@ -29,7 +29,7 @@ class Shrine
       def self.configure(uploader, &block)
         if block
           uploader.opts[:default_url] = block
-          warn "Passing a block to default_url Shrine plugin is deprecated and will probably be removed in future versions of Shrine. Use `Attacher.default_url { ... }` instead."
+          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.")
         end
       end
 

data/lib/shrine/plugins/delete_raw.rb

@@ -21,12 +21,16 @@ class Shrine
         # Deletes the file that was uploaded, unless it's an UploadedFile.
         def copy(io, context)
           super
-          if io.respond_to?(:delete) && !io.is_a?(UploadedFile)
-            io.delete rescue nil if delete_uploaded?(io)
+          if io.respond_to?(:path) && io.path && delete_raw?
+            begin
+              File.delete(io.path)
+            rescue Errno::ENOENT
+              # file might already be deleted by the moving plugin
+            end
           end
         end
 
-        def delete_uploaded?(io)
+        def delete_raw?
           opts[:delete_raw_storages].nil? ||
           opts[:delete_raw_storages].include?(storage_key)
         end

data/lib/shrine/plugins/determine_mime_type.rb

@@ -1,16 +1,17 @@
 class Shrine
   module Plugins
-    # The `determine_mime_type` plugin stores the actual MIME type of the
-    # uploaded file.
+    # The `determine_mime_type` plugin allows you to determine and store the
+    # actual MIME type of the file analyzed from file content.
     #
     #     plugin :determine_mime_type
     #
-    # By default the UNIX [file] utility is used to determine the MIME type, but
-    # you can change it:
+    # 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:
     #
     #     plugin :determine_mime_type, analyzer: :filemagic
     #
-    # The plugin accepts the following analyzers:
+    # The following analyzers are accepted:
     #
     # :file
     # : (Default). Uses the [file] utility to determine the MIME type from file
@@ -33,17 +34,32 @@ class Shrine
     #   guaranteed to return the actual MIME type of the file.
     #
     # :default
-    # : Uses the default way of extracting the MIME type, and that is from the
-    #   "Content-Type" request header, which might not hold the actual MIME type
-    #   of the file.
+    # : Uses the default way of extracting the MIME type, and that is reading
+    #   the `#content_type` attribute of the IO object, which might not hold
+    #   the actual MIME type of the file.
     #
-    # Not all analyzers can recognize all types of files. For those cases you
-    # can build your own analyzer, where you can reuse built-in analyzers:
+    # 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 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:
     #
     #     plugin :determine_mime_type, analyzer: ->(io, analyzers) do
-    #       analyzers[:mimemagic].call(io) || analyzers[:file].call(io)
+    #       mime_type = analyzers[:file].call(io)
+    #       mime_type = analyzers[:mime_types].call(io) if mime_type == "text/plain"
+    #       mime_type
     #     end
     #
+    # You can also use methods for determining the MIME type directly:
+    #
+    #     # or YourUploader.determine_mime_type(io)
+    #     Shrine.determine_mime_type(io) # calls the defined analyzer
+    #     #=> "image/jpeg"
+    #
+    #     # or YourUploader.mime_type_analyzers
+    #     Shrine.mime_type_analyzers[:file].call(io) # calls a built-in analyzer
+    #     #=> "image/jpeg"
+    #
     # [file]: http://linux.die.net/man/1/file
     # [Windows equivalent]: http://gnuwin32.sourceforge.net/packages/file.htm
     # [ruby-filemagic]: https://github.com/blackwinter/ruby-filemagic
@@ -52,24 +68,15 @@ class Shrine
     module DetermineMimeType
       def self.configure(uploader, opts = {})
         uploader.opts[:mime_type_analyzer] = opts.fetch(:analyzer, uploader.opts.fetch(:mime_type_analyzer, :file))
-        uploader.opts[:mime_type_magic_header] = opts.fetch(:magic_header, uploader.opts.fetch(:mime_type_magic_header, MAGIC_NUMBER))
       end
 
-      # How many bytes we need to read in order to determine the MIME type.
-      MAGIC_NUMBER = 256 * 1024
-
-      module InstanceMethods
-        private
-
-        # If a Shrine::UploadedFile was given, it returns its MIME type, since
-        # that value was already determined by this analyzer. Otherwise it calls
-        # a built-in analyzer or a custom one.
-        def extract_mime_type(io)
+      module ClassMethods
+        # Determines the MIME type of the IO object by calling the specified
+        # analyzer.
+        def determine_mime_type(io)
           analyzer = opts[:mime_type_analyzer]
-          return super if analyzer == :default
-
           analyzer = mime_type_analyzers[analyzer] if analyzer.is_a?(Symbol)
-          args = [io, mime_type_analyzers].take(analyzer.arity.abs)
+          args     = [io, mime_type_analyzers].take(analyzer.arity.abs)
 
           mime_type = analyzer.call(*args)
           io.rewind
@@ -77,15 +84,59 @@ class Shrine
           mime_type
         end
 
+        # Returns a hash of built-in MIME type analyzers, where keys are
+        # analyzer names and values are `#call`-able objects which accepts the
+        # IO object.
         def mime_type_analyzers
-          Hash.new { |hash, key| method(:"_extract_mime_type_with_#{key}") }
+          @mime_type_analyzers ||= MimeTypeAnalyzer::SUPPORTED_TOOLS.inject({}) do |hash, tool|
+            hash.merge!(tool => MimeTypeAnalyzer.new(tool).method(:call))
+          end
         end
+      end
 
-        def _extract_mime_type_with_file(io)
+      module InstanceMethods
+        private
+
+        # Calls default behaviour when :default analyzer was specified, which
+        # just reads the `#content_type` attribute, otherwise uses the specified
+        # MIME type analyzer.
+        def extract_mime_type(io)
+          if opts[:mime_type_analyzer] == :default
+            super
+          else
+            self.class.determine_mime_type(io)
+          end
+        end
+
+        # Returns a hash of built-in MIME type analyzers.
+        def mime_type_analyzers
+          self.class.mime_type_analyzers
+        end
+      end
+
+      class MimeTypeAnalyzer
+        SUPPORTED_TOOLS = [:file, :filemagic, :mimemagic, :mime_types]
+        MAGIC_NUMBER    = 256 * 1024
+
+        def initialize(tool)
+          raise ArgumentError, "unsupported mime type analyzer tool: #{tool}" unless SUPPORTED_TOOLS.include?(tool)
+
+          @tool = tool
+        end
+
+        def call(io)
+          mime_type = send(:"extract_with_#{@tool}", io)
+          io.rewind
+          mime_type
+        end
+
+        private
+
+        def extract_with_file(io)
           require "open3"
 
           cmd = ["file", "--mime-type", "--brief", "-"]
-          options = {stdin_data: magic_header(io), binmode: true}
+          options = {stdin_data: io.read(MAGIC_NUMBER), binmode: true}
 
           begin
             stdout, stderr, status = Open3.capture3(*cmd, options)
@@ -99,26 +150,24 @@ class Shrine
           stdout.strip
         end
 
-        def _extract_mime_type_with_mimemagic(io)
-          require "mimemagic"
-
-          mime = MimeMagic.by_magic(io)
-          io.rewind
-
-          mime.type if mime
-        end
-
-        def _extract_mime_type_with_filemagic(io)
+        def extract_with_filemagic(io)
           require "filemagic"
 
           filemagic = FileMagic.new(FileMagic::MAGIC_MIME_TYPE)
-          mime_type = filemagic.buffer(magic_header(io))
+          mime_type = filemagic.buffer(io.read(MAGIC_NUMBER))
           filemagic.close
 
           mime_type
         end
 
-        def _extract_mime_type_with_mime_types(io)
+        def extract_with_mimemagic(io)
+          require "mimemagic"
+
+          mime = MimeMagic.by_magic(io)
+          mime.type if mime
+        end
+
+        def extract_with_mime_types(io)
           begin
             require "mime/types/columnar"
           rescue LoadError
@@ -131,12 +180,15 @@ class Shrine
           end
         end
 
-        def magic_header(io)
-          content = io.read(opts[:mime_type_magic_header])
-          io.rewind
-          content
+        def extract_filename(io)
+          if io.respond_to?(:original_filename)
+            io.original_filename
+          elsif io.respond_to?(:path)
+            File.basename(io.path)
+          end
         end
       end
+
     end
 
     register_plugin(:determine_mime_type, DetermineMimeType)

data/lib/shrine/plugins/direct_upload.rb

@@ -99,10 +99,12 @@ class Shrine
     #
     #     plugin :direct_upload, presign_options: ->(request) do
     #       filename = request.params["filename"]
+    #       content_type = Rack::Mime.mime_type(File.extname(filename))
     #
     #       {
     #         content_length_range: 0..(10*1024*1024),                     # limit filesize to 10MB
     #         content_disposition: "attachment; filename=\"#{filename}\"", # download with original filename
+    #         content_type:        content_type,                           # set correct content type
     #       }
     #     end
     #
@@ -230,7 +232,7 @@ class Shrine
           context = {action: :cache, phase: :cache}
 
           if name != "upload"
-            warn "The \"POST /:storage/:name\" route of the direct_upload Shrine plugin is deprecated, and it will be removed in Shrine 3. Use \"POST /:storage/upload\" instead."
+            Shrine.deprecation("The \"POST /:storage/:name\" route of the direct_upload plugin is deprecated, and it will be removed in Shrine 3. Use \"POST /:storage/upload\" instead.")
             context[:name] = name
           end
 

data/lib/shrine/plugins/download_endpoint.rb

@@ -41,13 +41,22 @@ class Shrine
     #    prompted to download the file when visiting the download URL.
     #    The default is "inline".
     #
-    # This plugin is also suitable on Heroku when using FileSystem storage for
-    # cache. On Heroku files cannot be stored to the "public" folder but rather
-    # to the "tmp" folder, which means that by default it's not possible to
-    # show the URL to the cached file. The download endpoint generates the URL
-    # to any file, regardless of its location.
+    # Note that streaming the file through your app might impact the request
+    # throughput of your app, because on most popular web servers (Puma,
+    # Unicorn, Passenger) workers handling this endpoint will not be able to
+    # serve new requests until the client has fully downloaded the response
+    # body.
+    #
+    # To prevent download endpoint from impacting your request throughput, use
+    # a web server that handles streaming responses and slow clients well, like
+    # [Thin], [Rainbows] or any other [EventMachine]-based web server that
+    # implements `async.callback`.
     #
     # [Roda]: https://github.com/jeremyevans/roda
+    # [Thin]: https://github.com/macournoyer/thin
+    # [Rainbows]: https://rubygems.org/gems/rainbows
+    # [Reel]: https://github.com/celluloid/reel
+    # [EventMachine]: https://github.com/eventmachine
     module DownloadEndpoint
       def self.configure(uploader, opts = {})
         uploader.opts[:download_endpoint_storages] = opts.fetch(:storages, uploader.opts[:download_endpoint_storages])

data/lib/shrine/plugins/logging.rb

@@ -1,5 +1,4 @@
 require "logger"
-require "benchmark"
 require "json"
 
 class Shrine
@@ -157,9 +156,10 @@ class Shrine
         end
 
         def benchmark
-          result = nil
-          duration = Benchmark.realtime { result = yield }
-          [result, duration]
+          start = Time.now
+          result = yield
+          finish = Time.now
+          [result, finish - start]
         end
       end
     end

data/lib/shrine/plugins/metadata_attributes.rb

@@ -0,0 +1,61 @@
+class Shrine
+  module Plugins
+    # The `metadata_attributes` plugin allows you to sync attachment metadata
+    # to additional record attributes.
+    #
+    #     plugin :metadata_values
+    #
+    # It provides `Attacher.metadata_attributes` method which allows you to
+    # specify mappings between metadata fields on the attachment and attribute
+    # names on the record.
+    #
+    #     Attacher.metadata_attributes :size => :size, :mime_type => :type
+    #
+    # The above configuration will sync `size` metadata field to
+    # `<attachment>_size` record attribute, and `mime_type` metadata field to
+    # `<attachment>_type` record attribute.
+    #
+    #     user.avatar = image
+    #     user.avatar.metadata["size"]      #=> 95724
+    #     user.avatar_size                  #=> 95724
+    #     user.avatar.metadata["mime_type"] #=> "image/jpeg"
+    #     user.avatar_type                  #=> "image/jpeg"
+    #
+    #     user.avatar = nil
+    #     user.avatar_size #=> nil
+    #     user.avatar_type #=> nil
+    #
+    # If any corresponding metadata attribute doesn't exist on the record, that
+    # metadata sync will be silently skipped.
+    module MetadataAttributes
+      def self.configure(uploader)
+        uploader.opts[:metadata_attributes_mappings] ||= {}
+      end
+
+      module AttacherClassMethods
+        def metadata_attributes(mappings)
+          shrine_class.opts[:metadata_attributes_mappings].merge!(mappings)
+        end
+      end
+
+      module AttacherMethods
+        def assign(value)
+          super
+          cached_file = get
+
+          shrine_class.opts[:metadata_attributes_mappings].each do |source, destination|
+            next unless record.respond_to?(:"#{name}_#{destination}=")
+
+            if cached_file
+              record.send(:"#{name}_#{destination}=", cached_file.metadata[source.to_s])
+            else
+              record.send(:"#{name}_#{destination}=", nil)
+            end
+          end
+        end
+      end
+    end
+
+    register_plugin(:metadata_attributes, MetadataAttributes)
+  end
+end

data/lib/shrine/plugins/migration_helpers.rb

@@ -1,4 +1,4 @@
-warn "The migration_helpers Shrine plugin is deprecated and will be removed in Shrine 3. Attacher#cached? and Attacher#stored? have been moved to base."
+Shrine.deprecation("The migration_helpers plugin is deprecated and will be removed in Shrine 3. Attacher#cached? and Attacher#stored? have been moved to base.")
 
 class Shrine
   module Plugins

data/lib/shrine/plugins/rack_file.rb

@@ -11,37 +11,44 @@ class Shrine
     # `multipart/form-data` parameter encoding, Rack converts the uploaded file
     # to a hash.
     #
-    #     params[:file] #=>
+    #     file_hash #=>
     #     # {
-    #     #   name: "file"
-    #     #   filename: "cats.png",
-    #     #   type: "image/png",
-    #     #   tempfile: #<Tempfile:/var/folders/3n/3asd/-Tmp-/RackMultipart201-1476-nfw2-0>,
-    #     #   head: "Content-Disposition: form-data; ...",
+    #     #   :name => "file",
+    #     #   :filename => "cats.png",
+    #     #   :type => "image/png",
+    #     #   :tempfile => #<Tempfile:/var/folders/3n/3asd/-Tmp-/RackMultipart201-1476-nfw2-0>,
+    #     #   :head => "Content-Disposition: form-data; ...",
     #     # }
     #
     # Since Shrine only accepts IO objects, you would normally need to fetch
     # the `:tempfile` object and pass it directly. This plugin enables the
-    # uploader and attacher to accept the Rack uploaded file hash as a whole,
-    # which is then internally converted into an IO object.
+    # attacher to accept the Rack uploaded file hash directly, which is
+    # convenient when doing mass attribute assignment.
     #
-    #     uploader.upload(params[:file])
+    #     user.avatar = file_hash
     #     # or
-    #     attacher.assign(params[:file])
-    #     # or
-    #     user.avatar = params[:file]
+    #     attacher.assign(file_hash)
     #
-    # This especially convenient when doing mass attribute assignment with
-    # request parameters. It will also copy the received file information into
-    # metadata.
+    # Internally the Rack uploaded file hash will be converted into an IO
+    # object using `Shrine.rack_file`, which you can also use directly:
     #
-    #     uploaded_file = uploader.upload(params[:file])
-    #     uploaded_file.original_filename #=> "cats.png"
-    #     uploaded_file.mime_type         #=> "image/png"
+    #     # or YourUploader.rack_file(file_hash)
+    #     io = Shrine.rack_file(file_hash)
+    #     io.original_filename #=> "cats.png"
+    #     io.content_type      #=> "image/png"
+    #     io.size              #=> 58342
     #
     # Note that this plugin is not needed in Rails applications, as Rails
-    # already wraps Rack uploaded files in `ActionDispatch::Http::UploadedFile`.
+    # already wraps the Rack uploaded file hash into an
+    # `ActionDispatch::Http::UploadedFile` object.
     module RackFile
+      module ClassMethods
+        # Accepts a Rack uploaded file hash and wraps it in an IO object.
+        def rack_file(hash)
+          UploadedFile.new(hash)
+        end
+      end
+
       module InstanceMethods
         # If `io` is a Rack uploaded file hash, converts it to an IO-like
         # object and calls `super`.
@@ -62,7 +69,8 @@ class Shrine
         # hash, otherwise returns the value unchanged.
         def convert_rack_file(value)
           if rack_file?(value)
-            UploadedFile.new(value)
+            Shrine.deprecation("Passing a Rack uploaded file hash to Shrine#upload is deprecated, use Shrine.rack_file to convert the Rack file hash into an IO object.")
+            self.class.rack_file(value)
           else
             value
           end
@@ -75,26 +83,42 @@ class Shrine
         end
       end
 
+      module AttacherMethods
+        # Checks whether a file is a Rack file hash, and in that case wraps the
+        # hash in an IO-like object.
+        def assign(value)
+          if rack_file?(value)
+            assign(shrine_class.rack_file(value))
+          else
+            super
+          end
+        end
+
+        private
+
+        # Returns whether a given value is a Rack uploaded file hash, by
+        # checking whether it's a hash with `:tempfile` and `:name` keys.
+        def rack_file?(value)
+          value.is_a?(Hash) && value.key?(:tempfile) && value.key?(:name)
+        end
+      end
+
       # This is used to wrap the Rack hash into an IO-like object which Shrine
       # can upload.
       class UploadedFile
-        attr_reader :original_filename, :content_type
-        attr_accessor :tempfile
+        attr_reader :tempfile, :original_filename, :content_type
+        alias :to_io :tempfile
 
-        def initialize(tempfile:, filename: nil, type: nil, **)
-          @tempfile          = tempfile
-          @original_filename = filename
-          @content_type      = type
+        def initialize(hash)
+          @tempfile          = hash[:tempfile]
+          @original_filename = hash[:filename]
+          @content_type      = hash[:type]
         end
 
         def path
           @tempfile.path
         end
 
-        def to_io
-          @tempfile
-        end
-
         extend Forwardable
         delegate Shrine::IO_METHODS.keys => :@tempfile
       end