shrine 0.9.0

data/lib/shrine/plugins/parallelize.rb

@@ -0,0 +1,62 @@
+require "thread/pool"
+
+Thread::Pool.abort_on_exception = true
+
+class Shrine
+  module Plugins
+    # The parallelize plugin parallelizes your uploads and deletes using the
+    # [thread] gem.
+    #
+    #     plugin :parallelize
+    #
+    # This plugin is generally only useful as an addition to the versions
+    # plugin, where multiple files are being uploaded and deleted at once. Note
+    # that it's not possible for this plugin to parallelize processing, but it
+    # should be easy to do that manually.
+    #
+    # By default a pool of 3 threads will be used, but you can change that:
+    #
+    #     plugin :parallelize, threads: 5
+    #
+    # [thread]: https://github.com/meh/ruby-thread
+    module Parallelize
+      def self.configure(uploader, threads: 3)
+        uploader.opts[:parallelize_threads] = threads
+      end
+
+      module InstanceMethods
+        def store(io, context = {})
+          with_pool { |pool| super(io, thread_pool: pool, **context) }
+        end
+
+        def delete(uploaded_file, context = {})
+          with_pool { |pool| super(uploaded_file, thread_pool: pool, **context) }
+        end
+
+        private
+
+        def copy(io, context)
+          context[:thread_pool].process { super }
+        end
+
+        def move(io, context)
+          context[:thread_pool].process { super }
+        end
+
+        def remove(uploaded_file, context)
+          context[:thread_pool].process { super }
+        end
+
+        # We initialize a thread pool with configured number of threads.
+        def with_pool
+          pool = Thread.pool(opts[:parallelize_threads])
+          result = yield pool
+          pool.shutdown
+          result
+        end
+      end
+    end
+
+    register_plugin(:parallelize, Parallelize)
+  end
+end

data/lib/shrine/plugins/pretty_location.rb

@@ -0,0 +1,32 @@
+class Shrine
+  module Plugins
+    # The pretty_location plugin attempts to generate a nicer folder structure
+    # for uploaded files.
+    #
+    #     plugin :pretty_location
+    #
+    # This plugin uses the context information from the Attacher to try to
+    # generate a nested folder structure which separates files for each record.
+    # The newly generated locations will typically look like this:
+    #
+    #     "user/564/avatar/thumb-493g82jf23.jpg"
+    #     # :model/:id/:attachment/:version-:uid.:extension
+    module PrettyLocation
+      module InstanceMethods
+        def generate_location(io, context)
+          type = context[:record].class.name.downcase if context[:record] && context[:record].class.name
+          id   = context[:record].id if context[:record].respond_to?(:id)
+          name = context[:name]
+
+          dirname, slash, basename = super.rpartition("/")
+          basename = "#{context[:version]}-#{basename}" if context[:version]
+          original = dirname + slash + basename
+
+          [type, id, name, original].compact.join("/")
+        end
+      end
+    end
+
+    register_plugin(:pretty_location, PrettyLocation)
+  end
+end

data/lib/shrine/plugins/recache.rb

@@ -0,0 +1,36 @@
+class Shrine
+  module Plugins
+    # The recache plugin allows you to process your attachment after
+    # validations succeed, but before the attachment is promoted. This is
+    # useful for example when you want to generate some versions upfront (so
+    # the user immediately sees them) and other versions you want to generate
+    # in the promotion phase in a background job.
+    #
+    # The phase will be set to `:recache`:
+    #
+    #     class ImageUploader
+    #       plugin :recache
+    #
+    #       def process(io, context)
+    #         case context[:phase]
+    #         when :recache
+    #           # generate cheap versions
+    #         when :store
+    #           # generate more expensive versions
+    #         end
+    #       end
+    #     end
+    module Recache
+      module AttacherMethods
+        def save
+          if get && defined?(@old_attachment) # new file was assigned
+            _set cache!(get, phase: :recache)
+          end
+          super
+        end
+      end
+    end
+
+    register_plugin(:recache, Recache)
+  end
+end

data/lib/shrine/plugins/remote_url.rb

@@ -0,0 +1,127 @@
+class Shrine
+  module Plugins
+    # The remote_url plugin allows you to attach files from a remote location.
+    #
+    #     plugin :remote_url, max_size: 20*1024*1024
+    #
+    # If for example your attachment is called "avatar", this plugin will add
+    # `#avatar_remote_url` and `#avatar_remote_url=` methods to your model.
+    #
+    #     user.avatar #=> nil
+    #     user.avatar_remote_url = "http://example.com/cool-image.png"
+    #     user.avatar #=> #<Shrine::UploadedFile>
+    #
+    #     user.avatar.mime_type         #=> "image/png"
+    #     user.avatar.size              #=> 43423
+    #     user.avatar.original_filename #=> "cool-image.png"
+    #
+    # The file will by default be downloaded using Ruby's open-uri standard
+    # library. Following redirects is disabled for security reasons. It's also
+    # good practice to limit the filesize of the remote file:
+    #
+    #     plugin :remote_url, max_size: 20*1024*1024 # 20 MB
+    #
+    # Now if a file that is bigger than 20MB is assigned, Shrine will terminate
+    # the download as soon as it gets the "Content-Length" header, or the
+    # buffer size surpasses the maximum size. However, if for whatever reason
+    # you don't want to limit the maximum file size, you can set `:max_size` to
+    # nil:
+    #
+    #     plugin :remote_url, max_size: nil
+    #
+    # If download fails, either because the remote file wasn't found, was too
+    # large, or the request redirected, an error will be added to the
+    # attachment. You can change the default error message:
+    #
+    #     plugin :remote_url, error_message: "download failed"
+    #     plugin :remote_url, error_message: ->(url) { I18n.t("errors.download_failed") }
+    #
+    # Finally, if for some reason the way the file is downloaded doesn't suit
+    # your needs, you can provide a custom downloader:
+    #
+    #     plugin :remote_url, downloader: ->(url) do
+    #       request = RestClient::Request.new(method: :get, url: url, raw_response: true)
+    #       response = request.execute
+    #       response.file
+    #     end
+    module RemoteUrl
+      DEFAULT_ERROR_MESSAGE = "file was not found or was too large"
+
+      def self.load_dependencies(uploader, downloader: :open_uri, **)
+        case downloader
+        when :open_uri then require "down"
+        end
+      end
+
+      def self.configure(uploader, downloader: :open_uri, error_message: nil, max_size:)
+        uploader.opts[:remote_url_downloader] = downloader
+        uploader.opts[:remote_url_error_message] = error_message || DEFAULT_ERROR_MESSAGE
+        uploader.opts[:remote_url_max_size] = max_size
+      end
+
+      module AttachmentMethods
+        def initialize(name)
+          super
+
+          module_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def #{name}_remote_url=(url)
+              #{name}_attacher.remote_url = url
+            end
+
+            def #{name}_remote_url
+              #{name}_attacher.remote_url
+            end
+          RUBY
+        end
+      end
+
+      module AttacherMethods
+        # Downloads the remote file and assigns it. If download failed, sets
+        # the error message and assigns the url to an instance variable so that
+        # it shows up in the form.
+        def remote_url=(url)
+          return if url == ""
+
+          if downloaded_file = download(url)
+            assign(downloaded_file)
+          else
+            message = shrine_class.opts[:remote_url_error_message]
+            message = message.call(url) if message.respond_to?(:call)
+            errors << message
+            @remote_url = url
+          end
+        end
+
+        # Form builders require the reader as well.
+        def remote_url
+          @remote_url
+        end
+
+        private
+
+        # Downloads the file using the "down" gem or a custom downloader.
+        # Checks the file size and terminates the download early if the file
+        # is too big.
+        def download(url)
+          downloader = shrine_class.opts[:remote_url_downloader]
+          max_size = shrine_class.opts[:remote_url_max_size]
+
+          if downloader.is_a?(Symbol)
+            send(:"download_with_#{downloader}", url, max_size: max_size)
+          else
+            downloader.call(url, max_size: max_size)
+          end
+        end
+
+        # We silence any download errors, because for the user's point of view
+        # the download simply failed.
+        def download_with_open_uri(url, max_size:)
+          Down.download(url, max_size: max_size)
+        rescue Down::Error
+        end
+      end
+    end
+
+    register_plugin(:remote_url, RemoteUrl)
+  end
+end

data/lib/shrine/plugins/remove_attachment.rb

@@ -0,0 +1,59 @@
+class Shrine
+  module Plugins
+    # The remove_attachment plugin allows you to delete attachments through
+    # checkboxes on the web form.
+    #
+    #     plugin :remove_attachment
+    #
+    # If for example your attachment is called "avatar", this plugin will add
+    # `#remove_avatar` and `#remove_avatar=` methods to your model. This allows
+    # you to easily enable deleting attached files through the form:
+    #
+    #     <%= form_for @user do |f| %>
+    #       <%= f.hidden_field :avatar, value: @user.avatar_data %>
+    #       <%= f.file_field :avatar %>
+    #       Remove attachment: <%= f.check_box :remove_avatar %>
+    #     <% end %>
+    #
+    # Now when the checkbox is ticked and the form is submitted, the attached
+    # file will be removed.
+    module RemoveAttachment
+      module AttachmentMethods
+        def initialize(name)
+          super
+
+          module_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def remove_#{name}=(value)
+              #{name}_attacher.remove = value
+            end
+
+            def remove_#{name}
+              #{name}_attacher.remove
+            end
+          RUBY
+        end
+      end
+
+      module AttacherMethods
+        # We remove the attachment if the value evaluates to true.
+        def remove=(value)
+          @remove = value
+          set(nil) if remove?
+        end
+
+        def remove
+          @remove
+        end
+
+        private
+
+        # Rails sends "0" or "false" if the checkbox hasn't been ticked.
+        def remove?
+          remove && remove != "" && remove !~ /\A0|false$\z/
+        end
+      end
+    end
+
+    register_plugin(:remove_attachment, RemoveAttachment)
+  end
+end

data/lib/shrine/plugins/restore_cached.rb

@@ -0,0 +1,36 @@
+require "json"
+
+class Shrine
+  module Plugins
+    # The restore_cached plugin ensures the cached file data hasn't been
+    # tampered with, by restoring its metadata after assignment. The user can
+    # tamper with the cached file data by modifying the hidden field before
+    # submitting the form.
+    #
+    # Firstly the assignment is terminated if the cached file doesn't exist,
+    # which can happen if the user changes the "id" or "storage" data. If the
+    # cached file exists, the metadata is reextracted from the original file
+    # and replaced with the potentially tampered with ones.
+    #
+    #     plugin :restore_cached
+    module RestoreCached
+      module AttacherMethods
+        private
+
+        def assign_cached(value)
+          uploaded_file = uploaded_file(value) do |file|
+            next unless cache.uploaded?(file)
+            return unless file.exists?
+            uploader = shrine_class.uploader_for(file)
+            real_metadata = uploader.extract_metadata(file.to_io, context)
+            file.metadata.update(real_metadata)
+          end
+
+          super(uploaded_file)
+        end
+      end
+    end
+
+    register_plugin(:restore_cached, RestoreCached)
+  end
+end

data/lib/shrine/plugins/sequel.rb

@@ -0,0 +1,94 @@
+require "sequel"
+
+class Shrine
+  module Plugins
+    # The sequel plugin extends the "attachment" interface with support for
+    # Sequel.
+    #
+    #     plugin :sequel
+    #
+    # 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` -- Promotes the attachment, deletes replaced ones.
+    # * `after_destroy_commit` -- Deletes the attachment.
+    #
+    # Note that if your tests are wrapped in transactions, the `after_commit`
+    # and `after_destroy_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 Sequel'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 < Sequel::Model
+    #       include ImageUploader[:avatar]
+    #       validates_presence_of :avatar
+    #     end
+    module Sequel
+      module AttachmentMethods
+        def initialize(name)
+          super
+
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def validate
+              super
+              #{name}_attacher.errors.each do |message|
+                errors.add(:#{name}, message)
+              end
+            end
+
+            def before_save
+              super
+              #{name}_attacher.save
+            end
+
+            def after_commit
+              super
+              #{name}_attacher.replace
+              #{name}_attacher._promote
+            end
+
+            def after_destroy_commit
+              super
+              #{name}_attacher.destroy
+            end
+          RUBY
+        end
+      end
+
+      module AttacherClassMethods
+        # Needed by the background_helpers plugin.
+        def find_record(record_class, record_id)
+          record_class.with_pk!(record_id)
+        end
+      end
+
+      module AttacherMethods
+        private
+
+        # We save the record after updating, raising any validation errors.
+        def update(uploaded_file)
+          super
+          record.save(raise_on_failure: true)
+        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(:sequel, Sequel)
+  end
+end