shrine 0.9.0

data/lib/shrine/plugins/included.rb

@@ -0,0 +1,48 @@
+class Shrine
+  module Plugins
+    # The included plugin allows you to hook up to the `.included` hook when
+    # of the "attachment" module. This allows you to add additonal methods to
+    # the model whenever an attachment is included.
+    #
+    #     plugin :included do |name|
+    #       define_method("#{name}_width") do
+    #         send(name).width if send(name)
+    #       end
+    #
+    #       define_method("#{name}_height") do
+    #         send(name).height if send(name)
+    #       end
+    #     end
+    #
+    # The block is evaluated in the context of the model, but note that you
+    # cannot use keywords like `def`, instead you should use the
+    # metaprogramming equivalents like `define_method`. Now when an attachment
+    # is included to a model, it will receive the appropriate methods:
+    #
+    #     class User
+    #       include ImageUploader[:avatar]
+    #     end
+    #
+    #     user = User.new
+    #     user.avatar_width  #=> nil
+    #     user.avatar_height #=> nil
+    #
+    #     user.avatar = File.open("avatar.jpg")
+    #     user.avatar_width  #=> 300
+    #     user.avatar_height #=> 500
+    module Included
+      def self.configure(uploader, &block)
+        uploader.opts[:included_block] = block
+      end
+
+      module AttachmentMethods
+        def included(model)
+          super
+          model.instance_exec(@name, &shrine_class.opts[:included_block])
+        end
+      end
+    end
+
+    register_plugin(:included, Included)
+  end
+end

data/lib/shrine/plugins/keep_files.rb

@@ -0,0 +1,54 @@
+class Shrine
+  module Plugins
+    # The keep_files plugin gives you the ability to prevent files from being
+    # deleted. This functionality is useful when implementing soft deletes, or
+    # when implementing some kind of [event store] where you need to track
+    # history.
+    #
+    # The plugin accepts the following options:
+    #
+    # :destroyed
+    # :  If set to `true`, destroying the record won't delete the associated
+    #    attachment.
+    #
+    # :replaced
+    # :  If set to `true`, uploading a new attachment won't delete the old one.
+    #
+    # :cached
+    # :  If set to `true`, cached files that are uploaded to store won't be
+    #    deleted.
+    #
+    # For example, the following will keep destroyed and replaced files:
+    #
+    #     plugin :keep_files, destroyed: true, :replaced: true
+    #
+    # [event store]: http://docs.geteventstore.com/introduction/event-sourcing-basics/
+    module KeepFiles
+      def self.configure(uploader, destroyed: nil, replaced: nil, cached: nil)
+        uploader.opts[:keep_files] = []
+        uploader.opts[:keep_files] << :destroyed if destroyed
+        uploader.opts[:keep_files] << :replaced if replaced
+        uploader.opts[:keep_files] << :cached if cached
+      end
+
+      module ClassMethods
+        def keep?(type)
+          opts[:keep_files].include?(type)
+        end
+
+        # We hook to the generic deleting, and check the appropriate phases.
+        def delete(io, context)
+          case context[:phase]
+          when :cached then super unless keep?(:cached)
+          when :replaced then super unless keep?(:replaced)
+          when :destroyed then super unless keep?(:destroyed)
+          else
+            super
+          end
+        end
+      end
+    end
+
+    register_plugin(:keep_files, KeepFiles)
+  end
+end

data/lib/shrine/plugins/logging.rb

@@ -0,0 +1,158 @@
+require "logger"
+require "benchmark"
+require "json"
+
+class Shrine
+  module Plugins
+    # The logging plugin logs any storing/processing/deleting that is performed.
+    #
+    #     plugin :logging
+    #
+    # This plugin is useful when you want to have overview of what exactly is
+    # going on, or you simply want to have it logged for future debugging.
+    # By default the logging output looks something like this:
+    #
+    #     2015-10-09T20:06:06.676Z #25602: UPLOAD[direct] ImageUploader[:avatar] User[29543] 1 file (0.1s)
+    #     2015-10-09T20:06:06.854Z #25602: PROCESS[promote]: ImageUploader[:avatar] User[29543] 3 files (0.22s)
+    #     2015-10-09T20:06:07.133Z #25602: DELETE[destroyed]: ImageUploader[:avatar] User[29543] 3 files (0.07s)
+    #
+    # The plugin accepts the following options:
+    #
+    # :format
+    # :  This allows you to change the logging output into something that may be
+    #    easier to grep. Accepts `:human` (default), `:json` and `:heroku`.
+    #
+    # :stream
+    # :  The default logging stream is `$stdout`, but you may want to change it,
+    #    e.g. if you log into a file. This option is passed directly to
+    #    `Logger.new` (from the "logger" Ruby standard library).
+    #
+    # :logger
+    # :  This allows you to change the logger entirely. This is useful for example
+    #    in Rails applications, where you might want to assign this option to
+    #    `Rails.logger`.
+    #
+    # The default format is probably easiest to read, but may not be easiest to
+    # grep. If this is important to you, you can switch to another format:
+    #
+    #     plugin :logging, format: :json
+    #     # {"action":"upload","phase":"direct","uploader":"ImageUploader","attachment":"avatar",...}
+    #
+    #     plugin :logging, format: :heroku
+    #     # action=upload phase=direct uploader=ImageUploader attachment=avatar record_class=User ...
+    #
+    # Logging is by default disabled in tests, but you can enable it by setting
+    # `Shrine.logger.level = Logger::INFO`.
+    module Logging
+      def self.configure(uploader, logger: nil, stream: $stdout, format: :human)
+        uploader.logger = logger if logger
+        uploader.opts[:logging_stream] = stream
+        uploader.opts[:logging_format] = format
+      end
+
+      module ClassMethods
+        def logger=(logger)
+          @logger = logger || Logger.new(nil)
+        end
+
+        # Initializes a new logger if it hasn't been initialized.
+        def logger
+          @logger ||= (
+            logger = Logger.new(opts[:logging_stream])
+            logger.level = Logger::INFO
+            logger.level = Logger::WARN if ENV["RACK_ENV"] == "test"
+            logger.formatter = pretty_formatter
+            logger
+          )
+        end
+
+        # It makes logging preamble simpler than the default logger. Also, it
+        # doesn't output timestamps if on Heroku.
+        def pretty_formatter
+          proc do |severity, time, program_name, message|
+            output = "#{Process.pid}: #{message}\n"
+            output.prepend "#{time.utc.iso8601(3)} " unless ENV["DYNO"]
+            output
+          end
+        end
+      end
+
+      module InstanceMethods
+        def store(io, context = {})
+          log("store", context) { super }
+        end
+
+        def delete(uploaded_file, context = {})
+          log("delete", context) { super }
+        end
+
+        private
+
+        def processed(io, context = {})
+          log("process", context) { super }
+        end
+
+        # Collects the data and sends it for logging.
+        def log(action, context)
+          result, duration = benchmark { yield }
+
+          _log(
+            action:       action,
+            phase:        context[:phase],
+            uploader:     self.class,
+            attachment:   context[:name],
+            record_class: (context[:record].class if context[:record]),
+            record_id:    (context[:record].id if context[:record]),
+            files:        count(result),
+            duration:     ("%.2f" % duration).to_f,
+          ) unless result.nil?
+
+          result
+        end
+
+        def _log(data)
+          message = send("_log_message_#{opts[:logging_format]}", data)
+          self.class.logger.info(message)
+        end
+
+        def _log_message_human(data)
+          components = []
+          components << "#{data[:action].upcase}"
+          components.last << "[#{data[:phase]}]" if data[:phase]
+          components << "#{data[:uploader]}"
+          components.last << "[:#{data[:attachment]}]" if data[:attachment]
+          components << "#{data[:record_class]}[#{data[:record_id]}]" if data[:record_class]
+          components << (data[:files] > 1 ? "#{data[:files]} files" : "#{data[:files]} file")
+          components << "(#{data[:duration]}s)"
+          components.join(" ")
+        end
+
+        def _log_message_json(data)
+          data.to_json
+        end
+
+        def _log_message_heroku(data)
+          data.map { |key, value| "#{key}=#{value}" }.join(" ")
+        end
+
+        # We may have one file, a hash of versions, or an array of files or
+        # hashes.
+        def count(object)
+          case object
+          when Hash  then object.count
+          when Array then object.inject(0) { |sum, o| sum += count(o) }
+          else            1
+          end
+        end
+
+        def benchmark
+          result = nil
+          duration = Benchmark.realtime { result = yield }
+          [result, duration]
+        end
+      end
+    end
+
+    register_plugin(:logging, Logging)
+  end
+end

data/lib/shrine/plugins/migration_helpers.rb

@@ -0,0 +1,61 @@
+class Shrine
+  module Plugins
+    # The migration_helpers plugin gives the model additional helper methods
+    # which are convenient when doing attachment migrations.
+    #
+    #     plugin :migration_helpers
+    #
+    # If your attachment's name is "avatar", the model will get `#avatar_cache`
+    # and `#avatar_store` methods.
+    #
+    #     user = User.new
+    #     user.avatar_cache #=> #<Shrine @storage_key=:cache @storage=#<Shrine::Storage::FileSystem @directory=public/uploads>>
+    #     user.avatar_store #=> #<Shrine @storage_key=:store @storage=#<Shrine::Storage::S3:0x007fb8343397c8 @bucket=#<Aws::S3::Bucket name="foo">>>
+    #
+    # The model will also get `#update_avatar` method, which should be used
+    # when doing attachment migrations. It will update the record's attachment
+    # with the result of the passed in block.
+    #
+    #     user.update_avatar do |avatar|
+    #       user.avatar_store.upload(avatar) # saved to the record
+    #     end
+    #
+    # This will get triggered _only_ if the attachment exists and is stored.
+    # The result can be anything that responds to `#to_json` and evaluates to
+    # uploaded files' data.
+    module MigrationHelpers
+      module AttachmentMethods
+        def initialize(name)
+          super
+
+          module_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def update_#{name}(&block)
+              #{name}_attacher.update_stored(&block)
+            end
+
+            def #{name}_cache
+              #{name}_attacher.cache
+            end
+
+            def #{name}_store
+              #{name}_attacher.store
+            end
+          RUBY
+        end
+      end
+
+      module AttacherMethods
+        # Updates the attachment with the result of the block. It will get
+        # called only if the attachment exists and is stored.
+        def update_stored(&block)
+          attachment = get
+          return if attachment.nil? || cache.uploaded?(attachment)
+          new_attachment = block.call(attachment)
+          update(new_attachment) unless changed?(get)
+        end
+      end
+    end
+
+    register_plugin(:migration_helpers, MigrationHelpers)
+  end
+end

data/lib/shrine/plugins/moving.rb

@@ -0,0 +1,75 @@
+class Shrine
+  module Plugins
+    # The moving plugin enables you to move files to specified storages. On
+    # the filesystem moving is istantaneous, since the OS only changes the
+    # pointer, so this plugin is useful when dealing with large files.
+    #
+    # This plugin is also recommended if you're doing processing, since by
+    # default temporary files won't immediately get deleted (Ruby's Tempfiles
+    # usually get deleted only when the process ends).
+    #
+    #     plugin :moving, storages: [:cache]
+    #
+    # The `:storages` option specifies which storages the file will be moved
+    # to. The above will move Rails's uploaded files to cache (without this
+    # plugin it's simply copied over). However, you may want to move cached
+    # files to `:store` as well:
+    #
+    #     plugin :moving, storages: [:cache, :store]
+    #
+    # What exactly means "moving"? Usually this means that the file which is
+    # being uploaded will be deleted afterwards. However, if both the file
+    # being uploaded and the destination are on the filesystem, a `mv` command
+    # will be executed instead. Some other storages may implement moving as
+    # well, usually if also both the `:cache` and `:store` are using the same
+    # storage.
+    module Moving
+      def self.configure(uploader, storages:)
+        uploader.opts[:move_files_to_storages] = storages
+      end
+
+      module InstanceMethods
+        private
+
+        # If the file is movable (usually this means that both the file and
+        # the destination are on the filesystem), use the underlying storage's
+        # ability to move. Otherwise we "imitate" moving by deleting the file
+        # after it was uploaded.
+        def put(io, context)
+          if move?(io, context)
+            if movable?(io, context)
+              move(io, context)
+            else
+              super
+              io.delete if io.respond_to?(:delete)
+            end
+            # Promoting cached files will by default always delete the cached
+            # file. But, if moving plugin is enabled we want the cached file to
+            # be moved instead. However, there is no good way of letting the
+            # Attacher know that it shouldn't attempt to delete the file, so we
+            # make this instance variable hack.
+            io.instance_variable_set("@shrine_deleted", true)
+          else
+            super
+          end
+        end
+
+        # Don't delete the file if it has been moved.
+        def remove(io, context)
+          super unless io.instance_variable_get("@shrine_deleted")
+        end
+
+        # Ask the storage if the given file is movable.
+        def movable?(io, context)
+          storage.respond_to?(:move) && storage.movable?(io, context[:location])
+        end
+
+        def move?(io, context)
+          opts[:move_files_to_storages].include?(storage_key)
+        end
+      end
+    end
+
+    register_plugin(:moving, Moving)
+  end
+end

data/lib/shrine/plugins/multi_delete.rb

@@ -0,0 +1,47 @@
+class Shrine
+  module Plugins
+    # The multi_delete plugins allows you to leverage your storage's multi
+    # delete capabilities.
+    #
+    #     plugin :multi_delete
+    #
+    # This plugin allows you pass an array of files to `Shrine.delete`.
+    #
+    #     Shrine.delete([file1, file2, file3])
+    #
+    # Now if you're using Storage::S3, deleting an array of files will issue a
+    # single HTTP request. Some other storages may support multi deletes as
+    # well. The versions plugin uses this plugin for deleting multiple versions
+    # at once.
+    module MultiDelete
+      module InstanceMethods
+        # This allows `Shrine.delete` to accept an array of files.
+        def uploaded?(uploaded_file)
+          if uploaded_file.is_a?(Array)
+            uploaded_file.all? { |file| super(file) }
+          else
+            super
+          end
+        end
+
+        private
+
+        # Adds the ability to upload multiple files, leveraging the underlying
+        # storage's potential multi delete capability.
+        def _delete(uploaded_file, context)
+          if uploaded_file.is_a?(Array)
+            if storage.respond_to?(:multi_delete)
+              storage.multi_delete(uploaded_file.map(&:id))
+            else
+              uploaded_file.map { |file| super(file, context) }
+            end
+          else
+            super
+          end
+        end
+      end
+    end
+
+    register_plugin(:multi_delete, MultiDelete)
+  end
+end