shrine 2.1.1 → 2.2.0

data/lib/shrine.rb

@@ -209,13 +209,11 @@ class Shrine
 
         # User is expected to perform processing inside of this method, and
         # return the processed files. Returning nil signals that no proccessing
-        # has been done and that the original file should be used.  When used
-        # with Shrine::Attachment, the context variable will hold the record,
-        # name of the attachment and the phase.
+        # has been done and that the original file should be used.
         #
         #     class ImageUploader < Shrine
         #       def process(io, context)
-        #         case context[:phase]
+        #         case context[:action]
         #         when :cache
         #           # do processing
         #         when :store
@@ -472,7 +470,7 @@ class Shrine
             return if value == "" || value == read || !cache.uploaded?(uploaded_file(value))
             assign_cached(uploaded_file(value))
           else
-            uploaded_file = cache!(value, phase: :cache) if value
+            uploaded_file = cache!(value, action: :cache) if value
             set(uploaded_file)
           end
         end
@@ -504,19 +502,19 @@ class Shrine
         def finalize
           replace
           remove_instance_variable(:@old)
-          _promote(phase: :store) if cached?
+          _promote(action: :store) if cached?
         end
 
         # Promotes the file.
-        def _promote(uploaded_file = get, phase: nil)
-          promote(uploaded_file, phase: phase)
+        def _promote(uploaded_file = get, **options)
+          promote(uploaded_file, **options)
         end
 
         # Uploads the cached file to store, and updates the record with the
         # stored file.
         def promote(uploaded_file = get, **options)
           stored_file = store!(uploaded_file, **options)
-          result = swap(stored_file) or _delete(stored_file, phase: :abort)
+          result = swap(stored_file) or _delete(stored_file, action: :abort)
           result
         end
 
@@ -530,18 +528,18 @@ class Shrine
         # by ORM integrations. If also removes `@old` so that #save and #finalize
         # don't get called for the current attachment anymore.
         def replace
-          _delete(@old, phase: :replace) if @old && !cache.uploaded?(@old)
+          _delete(@old, action: :replace) if @old && !cache.uploaded?(@old)
         end
 
         # Deletes the attachment. Typically this should be called after
         # destroying a record.
         def destroy
-          _delete(get, phase: :destroy) if get && !cache.uploaded?(get)
+          _delete(get, action: :destroy) if get && !cache.uploaded?(get)
         end
 
         # Deletes the uploaded file.
-        def _delete(uploaded_file, phase: nil)
-          delete!(uploaded_file, phase: phase)
+        def _delete(uploaded_file, **options)
+          delete!(uploaded_file, **options)
         end
 
         # Returns the URL to the attached file (internally calls `#url` on the
@@ -573,17 +571,20 @@ class Shrine
 
         # Uploads the file to cache passing context.
         def cache!(io, **options)
-          cache.upload(io, context.merge(options))
+          warn "Sending :phase to Shrine::Attacher#cache! is deprecated and will not be supported in Shrine 3. Use :action instead." if options[:phase]
+          cache.upload(io, context.merge(_equalize_phase_and_action(options)))
         end
 
         # Uploads the file to store passing context.
         def store!(io, **options)
-          store.upload(io, context.merge(options))
+          warn "Sending :phase to Shrine::Attacher#store! is deprecated and will not be supported in Shrine 3. Use :action instead." if options[:phase]
+          store.upload(io, context.merge(_equalize_phase_and_action(options)))
         end
 
         # Deletes the file passing context.
         def delete!(uploaded_file, **options)
-          store.delete(uploaded_file, context.merge(options))
+          warn "Sending :phase to Shrine::Attacher#delete! is deprecated and will not be supported in Shrine 3. Use :action instead." if options[:phase]
+          store.delete(uploaded_file, context.merge(_equalize_phase_and_action(options)))
         end
 
         # Returns the Shrine class related to this attacher.
@@ -593,7 +594,7 @@ class Shrine
 
         private
 
-        # Assigns a cached file (refuses if the file is stored).
+        # Assigns a cached file.
         def assign_cached(cached_file)
           set(cached_file)
         end
@@ -629,6 +630,13 @@ class Shrine
         def context
           {name: name, record: record}
         end
+
+        # Temporary method used for transitioning from :phase to :action.
+        def _equalize_phase_and_action(options)
+          options[:phase]  = options[:action] if options.key?(:action)
+          options[:action] = options[:phase] if options.key?(:phase)
+          options
+        end
       end
 
       module FileClassMethods
@@ -691,6 +699,33 @@ class Shrine
         end
         alias content_type mime_type
 
+        # Opens the underlying IO for reading and yields it to the block,
+        # closing it after the block finishes. Use #to_io for opening without a
+        # block.
+        #
+        #     uploaded_file.open do |io|
+        #       # ...
+        #     end
+        def open
+          @io = storage.open(id)
+          yield @io
+        ensure
+          @io.close
+          @io = nil
+        end
+
+        # Calls `#download` on the storage if it is implemented, otherwise
+        # streams the underlying IO to a Tempfile.
+        def download
+          if storage.respond_to?(:download)
+            storage.download(id)
+          else
+            tempfile = Tempfile.new(["shrine", File.extname(id)], binmode: true)
+            open { |io| IO.copy_stream(io, tempfile.path) }
+            tempfile.tap(&:open)
+          end
+        end
+
         # Part of Shrine::UploadedFile's complying to the IO interface.  It
         # delegates to the internally downloaded file.
         def read(*args)
@@ -728,11 +763,6 @@ class Shrine
           storage.exists?(id)
         end
 
-        # Calls `#download` on the storage, which downloads the file to disk.
-        def download
-          storage.download(id)
-        end
-
         # Uploads a new file to this file's location and returns it.
         def replace(io, context = {})
           uploader.upload(io, context.merge(location: id))
@@ -743,7 +773,7 @@ class Shrine
           storage.delete(id)
         end
 
-        # Added as a Ruby conversion method. It typically downloads the file.
+        # Returns the underlying IO.
         def to_io
           io
         end

data/lib/shrine/plugins/activerecord.rb

@@ -46,6 +46,11 @@ class Shrine
     #       end
     #     end
     #
+    # If you don't want callbacks (e.g. you want to use the attacher object
+    # directly), you can turn them off:
+    #
+    #     plugin :activerecord, callbacks: false
+    #
     # ## Validations
     #
     # Additionally, any Shrine validation errors will be added to
@@ -56,32 +61,48 @@ class Shrine
     #       include ImageUploader[:avatar]
     #       validates_presence_of :avatar
     #     end
+    #
+    # If you're doing validation separately from your models, you can turn off
+    # validations for your models:
+    #
+    #     plugin :activerecord, validations: false
     module Activerecord
+      def self.configure(uploader, opts = {})
+        uploader.opts[:activerecord_callbacks] = opts.fetch(:callbacks, uploader.opts.fetch(:activerecord_callbacks, true))
+        uploader.opts[:activerecord_validations] = opts.fetch(:validations, uploader.opts.fetch(:activerecord_validations, true))
+      end
+
       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|
-                errors.add(:#{@name}, message)
+          if shrine_class.opts[:activerecord_validations]
+            model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              validate do
+                #{@name}_attacher.errors.each do |message|
+                  errors.add(:#{@name}, message)
+                end
               end
-            end
+            RUBY
+          end
 
-            before_save do
-              #{@name}_attacher.save if #{@name}_attacher.attached?
-            end
+          if shrine_class.opts[:activerecord_callbacks]
+            model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              before_save do
+                #{@name}_attacher.save if #{@name}_attacher.attached?
+              end
 
-            after_commit on: [:create, :update] do
-              #{@name}_attacher.finalize if #{@name}_attacher.attached?
-            end
+              after_commit on: [:create, :update] do
+                #{@name}_attacher.finalize if #{@name}_attacher.attached?
+              end
 
-            after_commit on: [:destroy] do
-              #{@name}_attacher.destroy
-            end
-          RUBY
+              after_commit on: [:destroy] do
+                #{@name}_attacher.destroy
+              end
+            RUBY
+          end
         end
       end
 

data/lib/shrine/plugins/add_metadata.rb

@@ -0,0 +1,50 @@
+class Shrine
+  module Plugins
+    # The metadata plugin provides a convenient method for extracting and
+    # adding custom metadata values.
+    #
+    #     plugin :add_metadata
+    #
+    #     add_metadata :exif do |io, context|
+    #       MiniMagick::Image.new(io.path).exif
+    #     end
+    #
+    # The above will add "exif" to the metadata hash, and also add the `#exif`
+    # method to the `UploadedFile`:
+    #
+    #     uploaded_file.metadata["exif"]
+    #     # or
+    #     uploaded_file.exif
+    module AddMetadata
+      def self.configure(uploader)
+        uploader.opts[:metadata] = {}
+      end
+
+      module ClassMethods
+        def add_metadata(name, &block)
+          opts[:metadata][name] = block
+
+          self::UploadedFile.send(:define_method, name) do
+            metadata[name.to_s]
+          end
+        end
+      end
+
+      module InstanceMethods
+        def extract_metadata(io, context)
+          metadata = super
+
+          opts[:metadata].each do |name, block|
+            value = instance_exec(io, context, &block)
+            metadata[name.to_s] = value unless value.nil?
+            io.rewind
+          end
+
+          metadata
+        end
+      end
+    end
+
+    register_plugin(:add_metadata, AddMetadata)
+  end
+end

data/lib/shrine/plugins/backgrounding.rb

@@ -92,10 +92,10 @@ class Shrine
           else
             attacher = load(data)
             cached_file = attacher.uploaded_file(data["attachment"])
-            phase = data["phase"].to_sym if data["phase"]
+            action = data["action"].to_sym if data["action"]
 
             return if cached_file != attacher.get
-            attacher.promote(cached_file, phase: phase) or return
+            attacher.promote(cached_file, action: action) or return
 
             attacher
           end
@@ -109,9 +109,9 @@ class Shrine
           else
             attacher = load(data)
             uploaded_file = attacher.uploaded_file(data["attachment"])
-            phase = data["phase"].to_sym if data["phase"]
+            action = data["action"].to_sym if data["action"]
 
-            attacher.delete!(uploaded_file, phase: phase)
+            attacher.delete!(uploaded_file, action: action)
 
             attacher
           end
@@ -130,8 +130,14 @@ class Shrine
           record = find_record(record_class, record_id) ||
             record_class.new.tap { |object| object.id = record_id }
 
-          name = data["name"]
-          attacher = record.send("#{name}_attacher")
+          name = data["name"].to_sym
+
+          if data["shrine_class"]
+            shrine_class = Object.const_get(data["shrine_class"])
+            attacher = shrine_class::Attacher.new(record, name)
+          else
+            attacher = record.send("#{name}_attacher")
+          end
 
           attacher
         end
@@ -140,11 +146,12 @@ class Shrine
       module AttacherMethods
         # Calls the promoting block (if registered) with a serializable data
         # hash.
-        def _promote(uploaded_file = get, phase: nil)
+        def _promote(uploaded_file = get, phase: nil, action: phase)
           if background_promote = shrine_class.opts[:backgrounding_promote]
             data = self.class.dump(self).merge(
               "attachment" => uploaded_file.to_json,
-              "phase"      => (phase.to_s if phase),
+              "phase"      => (action.to_s if action),
+              "action"     => (action.to_s if action),
             )
             instance_exec(data, &background_promote)
           else
@@ -154,11 +161,12 @@ class Shrine
 
         # Calls the deleting block (if registered) with a serializable data
         # hash.
-        def _delete(uploaded_file, phase: nil)
+        def _delete(uploaded_file, phase: nil, action: phase)
           if background_delete = shrine_class.opts[:backgrounding_delete]
             data = self.class.dump(self).merge(
               "attachment" => uploaded_file.to_json,
-              "phase"      => (phase.to_s if phase),
+              "phase"      => (action.to_s if action),
+              "action"     => (action.to_s if action),
             )
             instance_exec(data, &background_delete)
             uploaded_file
@@ -171,9 +179,10 @@ class Shrine
         # 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,
+            "attachment"   => (get && get.to_json),
+            "record"       => [record.class.to_s, record.id.to_s],
+            "name"         => name.to_s,
+            "shrine_class" => shrine_class.name,
           }
         end
       end

data/lib/shrine/plugins/backup.rb

@@ -64,12 +64,13 @@ class Shrine
 
         # Upload the stored file to the backup storage.
         def store_backup!(stored_file)
-          backup_store.upload(stored_file, context.merge(phase: :backup))
+          options = _equalize_phase_and_action(action: :backup)
+          backup_store.upload(stored_file, context.merge(options))
         end
 
         # 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), action: :backup)
         end
 
         def backup_store
@@ -90,7 +91,7 @@ class Shrine
 
         # We preserve the location when uploading from store to backup.
         def get_location(io, context)
-          if context[:phase] == :backup
+          if context[:action] == :backup
             io.id
           else
             super

data/lib/shrine/plugins/data_uri.rb

@@ -103,7 +103,7 @@ class Shrine
 
         # Returns contents of the file base64-encoded.
         def base64
-          content = storage.read(id)
+          content = open { |io| io.read }
           Base64.encode64(content).chomp
         end
       end

data/lib/shrine/plugins/delete_promoted.rb

@@ -10,7 +10,7 @@ class Shrine
       module AttacherMethods
         def promote(uploaded_file = get, **options)
           result = super
-          _delete(uploaded_file, phase: :promote)
+          _delete(uploaded_file, action: :promote)
           result
         end
       end

data/lib/shrine/plugins/delete_raw.rb

@@ -22,7 +22,7 @@ class Shrine
         def copy(io, context)
           super
           if io.respond_to?(:delete) && !io.is_a?(UploadedFile)
-            io.delete if delete_uploaded?(io)
+            io.delete rescue nil if delete_uploaded?(io)
           end
         end
 

data/lib/shrine/plugins/determine_mime_type.rb

@@ -83,10 +83,19 @@ class Shrine
         def _extract_mime_type_with_file(io)
           require "open3"
 
-          mime_type, status = Open3.capture2("file", "--mime-type", "--brief", "-",
-            stdin_data: magic_header(io), binmode: true)
+          cmd = ["file", "--mime-type", "--brief", "-"]
+          options = {stdin_data: magic_header(io), binmode: true}
 
-          mime_type.strip unless mime_type.empty?
+          begin
+            stdout, stderr, status = Open3.capture3(*cmd, options)
+          rescue Errno::ENOENT
+            raise Error, "The `file` command-line tool is not installed"
+          end
+
+          raise Error, stderr unless status.success?
+          $stderr.print(stderr)
+
+          stdout.strip
         end
 
         def _extract_mime_type_with_mimemagic(io)