shrine 0.9.0

data/lib/shrine/plugins/activerecord.rb

@@ -0,0 +1,89 @@
+require "active_record"
+
+class Shrine
+  module Plugins
+    # The activerecord plugin extends the "attachment" interface with support
+    # for ActiveRecord.
+    #
+    #     plugin :activerecord
+    #
+    # Now whenever an "attachment" module is included, additional callbacks are
+    # added to the model:
+    #
+    # * `before_save` -- Currently only used by the recache plugin.
+    # * `after_commit on: [:create, :update]` -- Promotes the attachment, deletes replaced ones.
+    # * `after_commit on: [:destroy]` -- Deletes the attachment.
+    #
+    # Note that if your tests are wrapped in transactions, the `after_commit`
+    # callbacks won't get called, so in order to test uploading you should first
+    # disable these transactions for those tests.
+    #
+    # If you want to put some parts of this lifecycle into a background job, see
+    # the background_helpers plugin.
+    #
+    # Additionally, any Shrine validation errors will added to ActiveRecord's
+    # errors upon validation. Note that if you want to validate presence of the
+    # attachment, you can do it directly on the model.
+    #
+    #     class User < ActiveRecord::Base
+    #       include ImageUploader[:avatar]
+    #       validates_presence_of :avatar
+    #     end
+    module Activerecord
+      module AttachmentMethods
+        def included(model)
+          super
+
+          model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            validate do
+              #{@name}_attacher.errors.each do |message|
+                errors.add(:#{@name}, message)
+              end
+            end
+
+            before_save do
+              #{@name}_attacher.save
+            end
+
+            after_commit on: [:create, :update] do
+              #{@name}_attacher.replace
+              #{@name}_attacher._promote
+            end
+
+            after_commit on: :destroy do
+              #{@name}_attacher.destroy
+            end
+          RUBY
+        end
+      end
+
+      module AttacherClassMethods
+        # Needed by the background_helpers plugin.
+        def find_record(record_class, record_id)
+          record_class.find(record_id)
+        end
+      end
+
+      module AttacherMethods
+        private
+
+        # We save the record after updating, raising any validation errors.
+        def update(uploaded_file)
+          super
+          record.save!
+        end
+
+        # If we're in a transaction, then promoting is happening inline. If
+        # we're not, then this is happening in a background job. In that case
+        # when we're checking that the attachment changed during storing, we
+        # need to first reload the record to pick up new columns.
+        def changed?(uploaded_file)
+          record.reload
+          super
+        end
+      end
+    end
+
+    register_plugin(:activerecord, Activerecord)
+  end
+end

data/lib/shrine/plugins/background_helpers.rb

@@ -0,0 +1,148 @@
+class Shrine
+  module Plugins
+    # The background_helpers plugin enables you to intercept phases of
+    # uploading and put them into background jobs. This doesn't require any
+    # additional columns.
+    #
+    #     plugin :background_helpers
+    #
+    # ## Promoting
+    #
+    # If you're doing processing, or your `:store` is something other than
+    # Storage::FileSystem, it's recommended to put promoting (moving to store)
+    # into a background job. This plugin allows you to do that by calling
+    # `Shrine::Attacher.promote`:
+    #
+    #     Shrine::Attacher.promote { |data| UploadJob.perform_async(data) }
+    #
+    # When you call `Shrine::Attacher.promote` with a block, it will save the
+    # block and call it on every promotion. Then in your background job you can
+    # again call `Shrine::Attacher.promote` with the data, and internally it
+    # will resolve all necessary objects, do the promoting and update the
+    # record.
+    #
+    #     class UploadJob
+    #       include Sidekiq::Worker
+    #
+    #       def perform(data)
+    #         Shrine::Attacher.promote(data)
+    #       end
+    #     end
+    #
+    # Shrine automatically handles all concurrency issues, such as canceling
+    # promoting if the attachment has changed in the meanwhile.
+    #
+    # ## Deleting
+    #
+    # If your `:store` is something other than Storage::FileSystem, it's
+    # recommended to put deleting files into a background job. This plugin
+    # allows you to do that by calling `Shrine::Attacher.delete`:
+    #
+    #     Shrine::Attacher.delete { |data| DeleteJob.perform_async(data) }
+    #
+    # When you call `Shrine::Attacher.delete` with a block, it will save the
+    # block and call it on every delete. Then in your background job you can
+    # again call `Shrine::Attacher.delete` with the data, and internally it
+    # will resolve all necessary objects, and delete the file.
+    #
+    #     class DeleteJob
+    #       include Sidekiq::Worker
+    #
+    #       def perform(data)
+    #         Shrine::Attacher.delete(data)
+    #       end
+    #     end
+    #
+    # ## Conclusion
+    #
+    # The examples above used Sidekiq, but obviously you can just as well use
+    # any other backgrounding library. Also, if you want you can use
+    # backgrounding just for certain uploaders:
+    #
+    #     class ImageUploader < Shrine
+    #       Attacher.promote { |data| UploadJob.perform_async(data) }
+    #       Attacher.delete { |data| DeleteJob.perform_async(data) }
+    #     end
+    #
+    # If you would like to speed up your uploads and deletes, you can use the
+    # parallelize plugin, either as a replacement or an addition to
+    # background_helpers.
+    module BackgroundHelpers
+      module AttacherClassMethods
+        # If block is passed in, stores it to be called on promotion. Otherwise
+        # resolves data into objects and calls Attacher#promote.
+        def promote(data = nil, &block)
+          if block
+            shrine_class.opts[:background_promote] = block
+          else
+            record_class, record_id = data["record"]
+            record_class = Object.const_get(record_class)
+            record = find_record(record_class, record_id)
+
+            name = data["attachment"]
+            attacher = record.send("#{name}_attacher")
+            cached_file = attacher.uploaded_file(data["uploaded_file"])
+
+            attacher.promote(cached_file)
+          end
+        end
+
+        # If block is passed in, stores it to be called on deletion. Otherwise
+        # resolves data into objects and calls Shrine.delete.
+        def delete(data = nil, &block)
+          if block
+            shrine_class.opts[:background_delete] = block
+          else
+            record_class, record_id = data["record"]
+            record = Object.const_get(record_class).new
+            record.id = record_id
+
+            name, phase = data["attachment"], data["phase"]
+            shrine_class = record.send("#{name}_attacher").shrine_class
+            uploaded_file = shrine_class.uploaded_file(data["uploaded_file"])
+            context = {name: name.to_sym, record: record, phase: phase.to_sym}
+
+            shrine_class.delete(uploaded_file, context)
+          end
+        end
+      end
+
+      module AttacherMethods
+        # Calls the promoting block with the data if it's been registered.
+        def _promote
+          if background_promote = shrine_class.opts[:background_promote]
+            data = {
+              "uploaded_file" => get.to_json,
+              "record"        => [record.class.to_s, record.id],
+              "attachment"    => name,
+            }
+
+            instance_exec(data, &background_promote) if promote?(get)
+          else
+            super
+          end
+        end
+
+        private
+
+        # Calls the deleting block with the data if it's been registered.
+        def delete!(uploaded_file, phase:)
+          if background_delete = shrine_class.opts[:background_delete]
+            data = {
+              "uploaded_file" => uploaded_file.to_json,
+              "record"        => [record.class.to_s, record.id],
+              "attachment"    => name,
+              "phase"         => phase,
+            }
+
+            instance_exec(data, &background_delete)
+          else
+            super
+          end
+        end
+      end
+    end
+
+    register_plugin(:background_helpers, BackgroundHelpers)
+  end
+end

data/lib/shrine/plugins/cached_attachment_data.rb

@@ -0,0 +1,47 @@
+class Shrine
+  module Plugins
+    # The cached_attachment_data adds a method for assigning cached files that
+    # is more convenient for forms.
+    #
+    #     plugin :cached_attachment_data
+    #
+    # If for example your attachment is called "avatar", this plugin will add
+    # `#cached_avatar_data` and `#cached_avatar_data=` methods to your model.
+    # This allows you to write your hidden field without explicitly setting
+    # `:value`:
+    #
+    #     <%= form_for @user do |f| %>
+    #       <%= f.hidden_field :cached_avatar_data %>
+    #       <%= f.field_field :avatar %>
+    #     <% end %>
+    #
+    # Additionally, the hidden field will only be set when the attachment is
+    # cached (as opposed to the default where `user.avatar_data` will return
+    # both cached and stored files). This keeps Rails logs cleaner.
+    module CachedAttachmentData
+      module AttachmentMethods
+        def initialize(name)
+          super
+
+          module_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def cached_#{name}_data
+              #{name}_attacher.read_cached
+            end
+
+            def cached_#{name}_data=(value)
+              #{name}_attacher.assign(value)
+            end
+          RUBY
+        end
+      end
+
+      module AttacherMethods
+        def read_cached
+          get.to_json if get && cache.uploaded?(get)
+        end
+      end
+    end
+
+    register_plugin(:cached_attachment_data, CachedAttachmentData)
+  end
+end

data/lib/shrine/plugins/data_uri.rb

@@ -0,0 +1,93 @@
+require "base64"
+
+class Shrine
+  module Plugins
+    # The data_uri plugin enables you to upload files as [data URIs].
+    # This plugin is useful for example when using [HTML5 Canvas].
+    #
+    #     plugin :data_uri
+    #
+    # If for example your attachment is called "avatar", this plugin will add
+    # `#avatar_data_uri` and `#avatar_data_uri=` methods to your model.
+    #
+    #     user.avatar #=> nil
+    #     user.avatar_data_uri = "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA"
+    #     user.avatar #=> #<Shrine::UploadedFile>
+    #
+    #     user.avatar.mime_type         #=> "image/jpeg"
+    #     user.avatar.size              #=> 43423
+    #     user.avatar.original_filename #=> nil
+    #
+    # If the data URI wasn't correctly parsed, an error message will added to
+    # the attachment column. You can change the default error message:
+    #
+    #     plugin :data_uri, error_message: "data URI was invalid"
+    #     plugin :data_uri, error_message: ->(uri) { I18n.t("errors.data_uri_invalid") }
+    #
+    # [data URIs]: https://tools.ietf.org/html/rfc2397
+    # [HTML5 Canvas]: https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API
+    module DataUri
+      DEFAULT_ERROR_MESSAGE = "data URI was invalid"
+      DEFAULT_CONTENT_TYPE = "text/plain"
+      DATA_URI_REGEXP = /\Adata:([-\w]+\/[-\w\+\.]+)?;base64,(.*)/m
+
+      def self.configure(uploader, error_message: DEFAULT_ERROR_MESSAGE)
+        uploader.opts[:data_uri_error_message] = error_message
+      end
+
+      module AttachmentMethods
+        def initialize(name)
+          super
+
+          module_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def #{name}_data_uri=(uri)
+              #{name}_attacher.data_uri = uri
+            end
+
+            def #{name}_data_uri
+              #{name}_attacher.data_uri
+            end
+          RUBY
+        end
+      end
+
+      module AttacherMethods
+        # Handles assignment of a data URI. If the regexp matches, it extracts
+        # the content type, decodes it, wrappes it in a StringIO and assigns it.
+        # 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 == ""
+
+          if match = uri.match(DATA_URI_REGEXP)
+            content_type = match[1] || DEFAULT_CONTENT_TYPE
+            content      = Base64.decode64(match[2])
+
+            assign DataFile.new(content, content_type: content_type)
+          else
+            message = shrine_class.opts[:data_uri_error_message]
+            message = message.call(uri) if message.respond_to?(:call)
+            errors << message
+            @data_uri = uri
+          end
+        end
+
+        # Form builders require the reader as well.
+        def data_uri
+          @data_uri
+        end
+      end
+
+      class DataFile < StringIO
+        attr_reader :content_type
+
+        def initialize(content, content_type: nil)
+          @content_type = content_type
+          super(content)
+        end
+      end
+    end
+
+    register_plugin(:data_uri, DataUri)
+  end
+end

data/lib/shrine/plugins/default_storage.rb

@@ -0,0 +1,39 @@
+class Shrine
+  module Plugins
+    # The default_storage plugin enables you to change which storages are going
+    # to be used for this uploader's attacher (the default is `:cache` and
+    # `:store`).
+    #
+    #     plugin :default_storage, cache: :special_cache, store: :special_store
+    #
+    # You can also pass a block and choose the values depending on the record
+    # values and the name of the attachment. This is useful if you're using the
+    # dynamic_storage plugin. Example:
+    #
+    #     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
+      end
+
+      module AttacherMethods
+        def initialize(record, name, **options)
+          if cache = shrine_class.opts[:default_storage_cache]
+            cache = cache.call(record, name) if cache.respond_to?(:call)
+            options[:cache] = cache
+          end
+
+          if store = shrine_class.opts[:default_storage_store]
+            store = store.call(record, name) if store.respond_to?(:call)
+            options[:store] = store
+          end
+
+          super
+        end
+      end
+    end
+
+    register_plugin(:default_storage, DefaultStorage)
+  end
+end

data/lib/shrine/plugins/delete_invalid.rb

@@ -0,0 +1,25 @@
+class Shrine
+  module Plugins
+    # The delete_invalid plugin immediately deletes the assigned attachment if
+    # it failed validation.
+    #
+    #     plugin :delete_invalid
+    #
+    # By default an attachment is always cached before it's validated. This
+    # way the attachment will persist when the form is resubmitted, which is
+    # consistent with the other fields in the form. However, if this is a
+    # concern, you can load this plugin.
+    module DeleteInvalid
+      module AttacherMethods
+        # Delete the assigned uploaded file if it was invalid.
+        def validate
+          super
+        ensure
+          delete!(get, phase: :invalid) if !errors.empty?
+        end
+      end
+    end
+
+    register_plugin(:delete_invalid, DeleteInvalid)
+  end
+end

data/lib/shrine/plugins/determine_mime_type.rb

@@ -0,0 +1,119 @@
+class Shrine
+  module Plugins
+    # The determine_mime_type plugin stores the actual MIME type of the
+    # uploaded file.
+    #
+    #     plugin :determine_mime_type
+    #
+    # The plugin accepts the following analyzers:
+    #
+    # :file
+    # : (Default). Uses the UNIX [file] utility to determine the MIME type
+    #   from file contents.
+    #
+    # :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.
+    #
+    # :mimemagic
+    # : Uses the [mimemagic] gem to determine the MIME type from file contents.
+    #   Unlike ruby-filemagic, mimemagic is a pure-ruby solution, so it will
+    #   work across all Ruby implementations.
+    #
+    # :mime_types
+    # : Uses the [mime-types] gem to determine the MIME type from the file
+    #   *extension*. Note that unlike other solutions, this analyzer is not
+    #   guaranteed to return the actual MIME type of the file.
+    #
+    # By default the UNIX [file] utility is used to detrmine the MIME type, but
+    # you can change it:
+    #
+    #     plugin :determine_mime_type, analyzer: :filemagic
+    #
+    # If none of these quite suit your needs, you can use a custom analyzer:
+    #
+    #     plugin :determine_mime_type, analyzer: ->(io) do
+    #       if io.path.end_with?(".odt")
+    #         "application/vnd.oasis.opendocument.text"
+    #       else
+    #         MimeMagic.by_magic(io).type
+    #       end
+    #     end
+    #
+    # [file]: http://linux.die.net/man/1/file
+    # [ruby-filemagic]: https://github.com/blackwinter/ruby-filemagic
+    # [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
+      end
+
+      module InstanceMethods
+        # 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]
+
+          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
+        end
+
+        private
+
+        # 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)
+          if io.respond_to?(:path)
+            mime_type, _ = Open3.capture2("file", "-b", "--mime-type", io.path)
+            mime_type.strip unless mime_type.empty?
+          end
+        end
+
+        # Uses the ruby-filemagic gem to magically extract the MIME type.
+        def _extract_mime_type_with_filemagic(io)
+          filemagic = FileMagic.new(FileMagic::MAGIC_MIME_TYPE)
+          data = io.read(1024); io.rewind
+          filemagic.buffer(data)
+        end
+
+        # Uses the mimemagic gem to extract the MIME type.
+        def _extract_mime_type_with_mimemagic(io)
+          MimeMagic.by_magic(io).type
+        end
+
+        # Uses the mime-types gem to determine MIME type from file extension.
+        def _extract_mime_type_with_mime_types(io)
+          if filename = extract_filename(io)
+            mime_type = MIME::Types.of(filename).first
+            mime_type.to_s if mime_type
+          end
+        end
+      end
+    end
+
+    register_plugin(:determine_mime_type, DetermineMimeType)
+  end
+end