shrine 1.4.2 → 2.0.0

data/lib/shrine/plugins/activerecord.rb

@@ -7,10 +7,11 @@ class Shrine
     #
     #     plugin :activerecord
     #
-    # Now whenever an "attachment" module is included, additional callbacks are
-    # added to the model:
+    # ## Callbacks
     #
-    # * `before_save` -- Currently only used by the recache plugin.
+    # Now the attachment module will add additional callbacks to the model:
+    #
+    # * `before_save` -- Used by the recache plugin.
     # * `after_commit on: [:create, :update]` -- Promotes the attachment, deletes replaced ones.
     # * `after_commit on: [:destroy]` -- Deletes the attachment.
     #
@@ -25,8 +26,27 @@ class Shrine
     # `after_commit` callbacks won't get called, so in order to test uploading
     # you should first disable transactions for those tests.
     #
-    # If you want to put some parts of this lifecycle into a background job,
-    # see the backgrounding plugin.
+    # If you want to put promoting/deleting into a background job, see the
+    # backgrounding plugin.
+    #
+    # Since attaching first saves the record with a cached attachment, then
+    # saves again with a stored attachment, you can detect this in callbacks:
+    #
+    #     class User < ActiveRecord::Base
+    #       include ImageUploader[:avatar]
+    #
+    #       before_save do
+    #         if avatar_data_changed? && avatar_attacher.cached?
+    #           # cached
+    #         end
+    #
+    #         if avatar_data_changed? && avatar_attacher.stored?
+    #           # promoted
+    #         end
+    #       end
+    #     end
+    #
+    # ## Validations
     #
     # Additionally, any Shrine validation errors will be added to
     # ActiveRecord's errors upon validation. If you want to validate presence
@@ -36,13 +56,13 @@ class Shrine
     #       include ImageUploader[:avatar]
     #       validates_presence_of :avatar
     #     end
-    #
-    # [optimistic locking]: http://api.rubyonrails.org/classes/ActiveRecord/Locking/Optimistic.html
     module Activerecord
       module AttachmentMethods
         def included(model)
           super
 
+          return unless model < ::ActiveRecord::Base
+
           model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
             validate do
               #{@name}_attacher.errors.each do |message|
@@ -75,15 +95,18 @@ class Shrine
       module AttacherMethods
         private
 
-        # Updates the current attachment with the new one, unless the current
-        # attachment has changed.
-        def update(uploaded_file)
-          if record.send("#{name}_data") == record.reload.send("#{name}_data")
-            record.send("#{name}_data=", uploaded_file.to_json)
-            record.save(validate: false)
-          end
+        # Proceeds with updating the record unless the attachment has changed.
+        def swap(uploaded_file)
+          return if record.send(:"#{name}_data") != record.reload.send(:"#{name}_data")
+          super
         rescue ::ActiveRecord::RecordNotFound
         end
+
+        # Saves the record after assignment, skipping validations.
+        def update(uploaded_file)
+          super
+          record.save(validate: false)
+        end
       end
     end
 

data/lib/shrine/plugins/background_helpers.rb

@@ -1,2 +1,3 @@
+warn "The background_helpers Shrine plugin has been renamed to \"backgrounding\". Loading the plugin through \"background_helpers\" will stop working in Shrine 3."
 require "shrine/plugins/backgrounding"
 Shrine::Plugins.register_plugin(:background_helpers, Shrine::Plugins::Backgrounding)

data/lib/shrine/plugins/backgrounding.rb

@@ -32,19 +32,30 @@ class Shrine
     #
     # Internally these methods will resolve all necessary objects, do the
     # promotion/deletion, and in case of promotion update the record with the
-    # stored attachment. Concurrency issues, like record being deleted or
-    # attachment being changed, are handled automatically.
+    # stored attachment.
     #
     # The examples above used Sidekiq, but obviously you can just as well use
     # any other backgrounding library. This setup will work globally for all
     # uploaders.
     #
-    # Both methods return the record (if it exists and the action didn't
+    # The backgrounding plugin affects the `Shrine::Attacher` in a way that
+    # `#_promote` and `#_delete` spawn background jobs, while `#promote` and
+    # `#delete!` are always synchronous:
+    #
+    #     # asynchronous (spawn background jobs)
+    #     attacher._promote
+    #     attacher._delete(attachment)
+    #
+    #     # synchronous
+    #     attacher.promote
+    #     attacher.delete!(attachment)
+    #
+    # Both methods return the `Shrine::Attacher` instance (if the action didn't
     # abort), so you can use it to do additional actions:
     #
     #     def perform(data)
-    #       record = Shrine::Attacher.promote(data)
-    #       record.update(published: true) if record.is_a?(Post)
+    #       attacher = Shrine::Attacher.promote(data)
+    #       attacher.record.update(published: true) if attacher && attacher.record.is_a?(Post)
     #     end
     #
     # You can also write custom background jobs with `Attacher.dump` and
@@ -52,6 +63,7 @@ class Shrine
     #
     #     class User < Sequel::Model
     #       def after_commit
+    #         super
     #         if some_condition
     #           data = Shrine::Attacher.dump(avatar_attacher)
     #           SomethingJob.perform_async(data)
@@ -69,7 +81,7 @@ class Shrine
     #
     # If you're generating versions, and you want to process some versions in
     # the foreground before kicking off a background job, you can use the
-    # `recache` plugin.
+    # recache plugin.
     module Backgrounding
       module AttacherClassMethods
         # If block is passed in, stores it to be called on promotion. Otherwise
@@ -79,12 +91,13 @@ class Shrine
             shrine_class.opts[:backgrounding_promote] = block
           else
             attacher = load(data)
-            cached_file = attacher.uploaded_file(data["uploaded_file"])
-            phase = data["phase"].to_sym
+            cached_file = attacher.uploaded_file(data["attachment"])
+            phase = data["phase"].to_sym if data["phase"]
 
+            return if cached_file != attacher.get
             attacher.promote(cached_file, phase: phase) or return
 
-            attacher.record
+            attacher
           end
         end
 
@@ -95,23 +108,18 @@ class Shrine
             shrine_class.opts[:backgrounding_delete] = block
           else
             attacher = load(data)
-            uploaded_file = attacher.uploaded_file(data["uploaded_file"])
-            context = {name: attacher.name, record: attacher.record, phase: data["phase"].to_sym}
+            uploaded_file = attacher.uploaded_file(data["attachment"])
+            phase = data["phase"].to_sym if data["phase"]
 
-            attacher.store.delete(uploaded_file, context)
+            attacher.delete!(uploaded_file, phase: phase)
 
-            attacher.record
+            attacher
           end
         end
 
-        # Dumps all the information about the attacher in a serializable hash
-        # suitable for passing as an argument to background jobs.
+        # Delegates to `Attacher#dump`.
         def dump(attacher)
-          {
-            "uploaded_file" => attacher.get && attacher.get.to_json,
-            "record"        => [attacher.record.class.to_s, attacher.record.id],
-            "attachment"    => attacher.name.to_s,
-          }
+          attacher.dump
         end
 
         # Loads the data created by #dump, resolving the record and returning
@@ -122,7 +130,7 @@ class Shrine
           record = find_record(record_class, record_id) ||
             record_class.new.tap { |object| object.id = record_id }
 
-          name = data["attachment"]
+          name = data["name"]
           attacher = record.send("#{name}_attacher")
 
           attacher
@@ -132,38 +140,42 @@ class Shrine
       module AttacherMethods
         # Calls the promoting block (if registered) with a serializable data
         # hash.
-        def _promote
+        def _promote(uploaded_file = get, phase: nil)
           if background_promote = shrine_class.opts[:backgrounding_promote]
-            data = self.class.dump(self).merge("phase" => "store")
-            instance_exec(data, &background_promote) if promote?(get)
+            data = self.class.dump(self).merge(
+              "attachment" => uploaded_file.to_json,
+              "phase"      => (phase.to_s if phase),
+            )
+            instance_exec(data, &background_promote)
           else
             super
           end
         end
 
-        # Returns early if attachments don't match.
-        def promote(cached_file, *)
-          return if cached_file != get
-          super
-        end
-
-        private
-
         # Calls the deleting block (if registered) with a serializable data
         # hash.
-        def delete!(uploaded_file, phase:)
+        def _delete(uploaded_file, phase: nil)
           if background_delete = shrine_class.opts[:backgrounding_delete]
             data = self.class.dump(self).merge(
-              "uploaded_file" => uploaded_file.to_json,
-              "phase"         => phase.to_s,
+              "attachment" => uploaded_file.to_json,
+              "phase"      => (phase.to_s if phase),
             )
             instance_exec(data, &background_delete)
-
             uploaded_file
           else
-            super(uploaded_file, phase: phase)
+            super
           end
         end
+
+        # Dumps all the information about the attacher in a serializable hash
+        # suitable for passing as an argument to background jobs.
+        def dump
+          {
+            "attachment" => (get && get.to_json),
+            "record"     => [record.class.to_s, record.id.to_s],
+            "name"       => name.to_s,
+          }
+        end
       end
     end
 

data/lib/shrine/plugins/backup.rb

@@ -23,9 +23,11 @@ class Shrine
     # you can set `delete: false` until you manually back up the existing
     # stored files.
     module Backup
-      def self.configure(uploader, storage:, delete: true)
-        uploader.opts[:backup_storage] = storage
-        uploader.opts[:backup_delete] = delete
+      def self.configure(uploader, opts = {})
+        uploader.opts[:backup_storage] = opts.fetch(:storage, uploader.opts[:backup_storage])
+        uploader.opts[:backup_delete] = opts.fetch(:delete, uploader.opts.fetch(:backup_delete, true))
+
+        raise Error, "The :storage option is required for backup plugin" if uploader.opts[:backup_storage].nil?
       end
 
       module AttacherMethods
@@ -67,7 +69,7 @@ class Shrine
 
         # Deleted the stored file from the backup storage.
         def delete_backup!(deleted_file)
-          delete!(backup_file(deleted_file), phase: :backup)
+          _delete(backup_file(deleted_file), phase: :backup)
         end
 
         def backup_store

data/lib/shrine/plugins/cached_attachment_data.rb

@@ -20,16 +20,16 @@ class Shrine
     # both cached and stored files). This keeps Rails logs cleaner.
     module CachedAttachmentData
       module AttachmentMethods
-        def initialize(name)
+        def initialize(*)
           super
 
           module_eval <<-RUBY, __FILE__, __LINE__ + 1
-            def cached_#{name}_data
-              #{name}_attacher.read_cached
+            def cached_#{@name}_data
+              #{@name}_attacher.read_cached
             end
 
-            def cached_#{name}_data=(value)
-              #{name}_attacher.assign(value)
+            def cached_#{@name}_data=(value)
+              #{@name}_attacher.assign(value)
             end
           RUBY
         end

data/lib/shrine/plugins/data_uri.rb

@@ -45,22 +45,22 @@ class Shrine
       DEFAULT_CONTENT_TYPE = "text/plain"
       DATA_URI_REGEXP = /\Adata:([-\w.+]+\/[-\w.+]+)?(;base64)?,(.*)\z/m
 
-      def self.configure(uploader, filename: nil, error_message: DEFAULT_ERROR_MESSAGE)
-        uploader.opts[:data_uri_filename] = filename
-        uploader.opts[:data_uri_error_message] = error_message
+      def self.configure(uploader, opts = {})
+        uploader.opts[:data_uri_filename] = opts.fetch(:filename, uploader.opts[:data_uri_filename])
+        uploader.opts[:data_uri_error_message] = opts.fetch(:error_message, uploader.opts[:data_uri_error_message])
       end
 
       module AttachmentMethods
-        def initialize(name)
+        def initialize(*)
           super
 
           module_eval <<-RUBY, __FILE__, __LINE__ + 1
-            def #{name}_data_uri=(uri)
-              #{name}_attacher.data_uri = uri
+            def #{@name}_data_uri=(uri)
+              #{@name}_attacher.data_uri = uri
             end
 
-            def #{name}_data_uri
-              #{name}_attacher.data_uri
+            def #{@name}_data_uri
+              #{@name}_attacher.data_uri
             end
           RUBY
         end
@@ -82,7 +82,7 @@ class Shrine
 
             assign DataFile.new(content, content_type: content_type, filename: filename)
           else
-            message = shrine_class.opts[:data_uri_error_message]
+            message = shrine_class.opts[:data_uri_error_message] || DEFAULT_ERROR_MESSAGE
             message = message.call(uri) if message.respond_to?(:call)
             errors.replace [message]
             @data_uri = uri

data/lib/shrine/plugins/default_storage.rb

@@ -12,9 +12,9 @@ class Shrine
     #
     #     plugin :default_storage, store: ->(record, name) { :"store_#{record.username}" }
     module DefaultStorage
-      def self.configure(uploader, cache: nil, store: nil)
-        uploader.opts[:default_storage_cache] = cache
-        uploader.opts[:default_storage_store] = store
+      def self.configure(uploader, opts = {})
+        uploader.opts[:default_storage_cache] = opts.fetch(:cache, uploader.opts[:default_storage_cache])
+        uploader.opts[:default_storage_store] = opts.fetch(:store, uploader.opts[:default_storage_store])
       end
 
       module AttacherMethods
@@ -29,7 +29,7 @@ class Shrine
             options[:store] = store
           end
 
-          super(record, name, **options)
+          super
         end
       end
     end

data/lib/shrine/plugins/default_url.rb

@@ -20,10 +20,16 @@ class Shrine
       end
 
       module AttacherMethods
+        def url(**options)
+          super || default_url(**options)
+        end
+
         private
 
         def default_url(**options)
-          default_url_block.call(context.merge(options){|k,old,new|old})
+          if default_url_block
+            default_url_block.call(context.merge(options){|k,old,new|old})
+          end
         end
 
         def default_url_block

data/lib/shrine/plugins/default_url_options.rb

@@ -9,7 +9,7 @@ class Shrine
     # and the latter will always have precedence over default options.
     module DefaultUrlOptions
       def self.configure(uploader, **options)
-        uploader.opts[:default_url_options] = options
+        uploader.opts[:default_url_options] = (uploader.opts[:default_url_options] || {}).merge(options)
       end
 
       module FileMethods

data/lib/shrine/plugins/delete_promoted.rb

@@ -8,9 +8,9 @@ class Shrine
     #     plugin :delete_promoted
     module DeletePromoted
       module AttacherMethods
-        def promote(uploaded_file, *)
+        def promote(uploaded_file = get, **options)
           result = super
-          delete!(uploaded_file, phase: :promote)
+          _delete(uploaded_file, phase: :promote)
           result
         end
       end

data/lib/shrine/plugins/delete_raw.rb

@@ -11,8 +11,8 @@ class Shrine
     #
     #     plugin :delete_raw, storages: [:store]
     module DeleteRaw
-      def self.configure(uploader, storages: nil)
-        uploader.opts[:delete_uploaded_storages] = storages
+      def self.configure(uploader, opts = {})
+        uploader.opts[:delete_raw_storages] = opts.fetch(:storages, uploader.opts[:delete_raw_storages])
       end
 
       module InstanceMethods
@@ -27,8 +27,8 @@ class Shrine
         end
 
         def delete_uploaded?(io)
-          opts[:delete_uploaded_storages].nil? ||
-          opts[:delete_uploaded_storages].include?(storage_key)
+          opts[:delete_raw_storages].nil? ||
+          opts[:delete_raw_storages].include?(storage_key)
         end
       end
     end

data/lib/shrine/plugins/determine_mime_type.rb

@@ -15,12 +15,12 @@ class Shrine
     # :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] you need to install separately.
+    #   [Windows equivalent] needs to be installed separately.
     #
     # :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 should work on Windows.
+    #   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.
@@ -32,10 +32,15 @@ class Shrine
     #   *extension*. Note that unlike other solutions, this analyzer is not
     #   guaranteed to return the actual MIME type of the file.
     #
-    # If none of these quite suit your needs, you can use a custom analyzer:
+    # :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.
     #
-    #     plugin :determine_mime_type, analyzer: ->(io) do
-    #       # returns the extracted MIME type
+    # If none of these quite suit your needs, you can build a custom analyzer:
+    #
+    #     plugin :determine_mime_type, analyzer: ->(io, analyzers) do
+    #       analyzers[:mimemagic].call(io) || analyzers[:file].call(io)
     #     end
     #
     # [file]: http://linux.die.net/man/1/file
@@ -44,22 +49,8 @@ class Shrine
     # [mimemagic]: https://github.com/minad/mimemagic
     # [mime-types]: https://github.com/mime-types/ruby-mime-types
     module DetermineMimeType
-      def self.load_dependencies(uploader, analyzer: :file)
-        case analyzer
-        when :file      then require "open3"
-        when :filemagic then require "filemagic"
-        when :mimemagic then require "mimemagic"
-        when :mime_types
-          begin
-            require "mime/types/columnar"
-          rescue LoadError
-            require "mime/types"
-          end
-        end
-      end
-
-      def self.configure(uploader, analyzer: :file)
-        uploader.opts[:mime_type_analyzer] = analyzer
+      def self.configure(uploader, opts = {})
+        uploader.opts[:mime_type_analyzer] = opts.fetch(:analyzer, :file)
       end
 
       # How many bytes we have to read to get the magic file header which
@@ -67,55 +58,71 @@ class Shrine
       MAGIC_NUMBER = 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)
           analyzer = opts[:mime_type_analyzer]
+          return super if analyzer == :default
 
-          mime_type = if io.respond_to?(:mime_type)
-            io.mime_type
-          elsif analyzer.is_a?(Symbol)
-            send(:"_extract_mime_type_with_#{analyzer}", io)
-          else
-            analyzer.call(io)
-          end
+          analyzer = mime_type_analyzers[analyzer] if analyzer.is_a?(Symbol)
+          args = [io, mime_type_analyzers].take(analyzer.arity.abs)
 
+          mime_type = analyzer.call(*args)
           io.rewind
 
           mime_type
         end
 
-        private
+        def mime_type_analyzers
+          Hash.new { |hash, key| method(:"_extract_mime_type_with_#{key}") }
+        end
 
-        # Uses the UNIX file utility to extract the MIME type. It does so only
-        # if it's a file, because even though the utility accepts standard
-        # input, it would mean that we have to read the whole file in memory.
         def _extract_mime_type_with_file(io)
-          cmd = ["file", "--mime-type", "--brief"]
+          require "open3"
+
+          cmd = ["file", "--mime-type", "--brief", "--"]
 
           if io.respond_to?(:path)
-            mime_type, _ = Open3.capture2(*cmd, io.path)
+            mime_type, * = Open3.capture2(*cmd, io.path)
           else
-            mime_type, _ = Open3.capture2(*cmd, "-", stdin_data: io.read(MAGIC_NUMBER), binmode: true)
+            mime_type, * = Open3.capture2(*cmd, "-", stdin_data: io.read(MAGIC_NUMBER), binmode: true)
+            io.rewind
           end
 
           mime_type.strip unless mime_type.empty?
         end
 
-        # Uses the ruby-filemagic gem to magically extract the MIME type.
+        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)
+          require "filemagic"
+
           filemagic = FileMagic.new(FileMagic::MAGIC_MIME_TYPE)
-          filemagic.buffer(io.read(MAGIC_NUMBER))
-        end
+          mime_type = filemagic.buffer(io.read(MAGIC_NUMBER))
 
-        # Uses the mimemagic gem to extract the MIME type.
-        def _extract_mime_type_with_mimemagic(io)
-          MimeMagic.by_magic(io).type
+          io.rewind
+          filemagic.close
+
+          mime_type
         end
 
-        # Uses the mime-types gem to determine MIME type from file extension.
         def _extract_mime_type_with_mime_types(io)
+          begin
+            require "mime/types/columnar"
+          rescue LoadError
+            require "mime/types"
+          end
+
           if filename = extract_filename(io)
             mime_type = MIME::Types.of(filename).first
             mime_type.to_s if mime_type