shrine 0.9.0

data/lib/shrine/plugins/store_dimensions.rb

@@ -0,0 +1,82 @@
+class Shrine
+  module Plugins
+    # The store_dimensions plugin extracts and stores dimensions of the
+    # uploaded image using the [fastimage] gem.
+    #
+    #     plugin :store_dimensions
+    #
+    # You can access the dimensions through `#width` and `#height` methods:
+    #
+    #     uploader = Shrine.new(:store)
+    #     uploaded_file = uploader.upload(File.open("image.jpg"))
+    #
+    #     uploaded_file.width  #=> 300
+    #     uploaded_file.height #=> 500
+    #
+    # The fastimage gem has built-in protection against [image bombs]. However,
+    # if for some reason it doesn't suit your needs, you can provide a custom
+    # `:analyzer`:
+    #
+    #     plugin :store_dimensions, analyzer: ->(io) do
+    #       MiniMagick::Image.new(io).dimensions #=> [300, 500]
+    #     end
+    #
+    # [fastimage]: https://github.com/sdsykes/fastimage
+    # [image bombs]: https://www.bamsoftware.com/hacks/deflate.html
+    module StoreDimensions
+      def self.load_dependencies(uploader, analyzer: :fastimage)
+        case analyzer
+        when :fastimage then require "fastimage"
+        end
+      end
+
+      def self.configure(uploader, analyzer: :fastimage)
+        uploader.opts[:dimensions_analyzer] = analyzer
+      end
+
+      module InstanceMethods
+        # We update the metadata with "width" and "height".
+        def extract_metadata(io, context)
+          width, height = extract_dimensions(io)
+
+          super.update(
+            "width"  => width,
+            "height" => height,
+          )
+        end
+
+        # If the `io` is an uploaded file, copies its dimensions, otherwise
+        # calls the predefined or custom analyzer.
+        def extract_dimensions(io)
+          analyzer = opts[:dimensions_analyzer]
+
+          if io.respond_to?(:width) && io.respond_to?(:height)
+            [io.width, io.height]
+          elsif analyzer.is_a?(Symbol)
+            send(:"_extract_dimensions_with_#{analyzer}", io)
+          else
+            analyzer.call(io)
+          end
+        end
+
+        private
+
+        def _extract_dimensions_with_fastimage(io)
+          FastImage.size(io)
+        end
+      end
+
+      module FileMethods
+        def width
+          metadata["width"] && Integer(metadata["width"])
+        end
+
+        def height
+          metadata["height"] && Integer(metadata["height"])
+        end
+      end
+    end
+
+    register_plugin(:store_dimensions, StoreDimensions)
+  end
+end

data/lib/shrine/plugins/validation_helpers.rb

@@ -0,0 +1,168 @@
+class Shrine
+  module Plugins
+    # The validation_helpers plugin provides helper methods for validating
+    # attached files.
+    #
+    #     class ImageUploader < Shrine
+    #       plugin :validation_helpers
+    #
+    #       Attacher.validate do
+    #         if record.guest?
+    #           validate_max_size 5*1024*1024
+    #         end
+    #       end
+    #     end
+    #
+    # The validation methods are instance-level, the `Attacher.validate` block
+    # is evaluated in context of an instance of `Shrine::Attacher`, so you can
+    # easily to conditional validation.
+    #
+    # If you would like to change default validation error messages, you can
+    # pass in the `:default_messages` option to the plugin:
+    #
+    #     plugin :validation_helpers, default_messages: {
+    #       max_size: ->(max) { I18n.t("errors.file.max_size", max: max) },
+    #       mime_type_inclusion: ->(whitelist) { I18n.t("errors.file.mime_type_inclusion", whitelist: whitelist) },
+    #     }
+    #
+    # If you would like to change the error message inline, you can pass the
+    # `:message` option to any validation method:
+    #
+    #     validate_mime_type_inclusion [/^image/], message: "is not an image"
+    #
+    # For a complete list of all validation helpers, see AttacherMethods.
+    module ValidationHelpers
+      def self.configure(uploader, default_messages: {})
+        uploader.opts[:validation_helpers_default_messages] = default_messages
+      end
+
+      DEFAULT_MESSAGES = {
+        max_size: ->(max) { "is larger than #{max.to_f/1024/1024} MB" },
+        min_size: ->(min) { "is smaller than #{min.to_f/1024/1024} MB" },
+        max_width: ->(max) { "is wider than #{max} px" },
+        min_width: ->(min) { "is narrower than #{min} px" },
+        max_height: ->(max) { "is taller than #{max} px" },
+        min_height: ->(min) { "is shorter than #{min} px" },
+        mime_type_inclusion: ->(list) { "isn't of allowed type: #{list.inspect}" },
+        mime_type_exclusion: ->(list) { "is of forbidden type: #{list.inspect}" },
+        extension_inclusion: ->(list) { "isn't in allowed format: #{list.inspect}" },
+        extension_exclusion: ->(list) { "is in forbidden format: #{list.inspect}" },
+      }
+
+      module AttacherClassMethods
+        def default_validation_messages
+          @default_validation_messages ||= DEFAULT_MESSAGES.merge(
+            shrine_class.opts[:validation_helpers_default_messages])
+        end
+      end
+
+      module AttacherMethods
+        # Validates that the file is not larger than `max`.
+        def validate_max_size(max, message: nil)
+          if get.size > max
+            errors << error_message(:max_size, message, max)
+          end
+        end
+
+        # Validates that the file is not smaller than `min`.
+        def validate_min_size(min, message: nil)
+          if get.size < min
+            errors << error_message(:min_size, message, min)
+          end
+        end
+
+        # Validates that the file is not wider than `max`. Requires the
+        # store_dimensions plugin.
+        def validate_max_width(max, message: nil)
+          raise Error, ":store_dimensions plugin is required" if !get.respond_to?(:width)
+          if get.width > max
+            errors << error_message(:max_width, message, max)
+          end
+        end
+
+        # Validates that the file is not narrower than `min`. Requires the
+        # store_dimensions plugin.
+        def validate_min_width(min, message: nil)
+          raise Error, ":store_dimensions plugin is required" if !get.respond_to?(:width)
+          if get.width < min
+            errors << error_message(:min_width, message, min)
+          end
+        end
+
+        # Validates that the file is not taller than `max`. Requires the
+        # store_dimensions plugin.
+        def validate_max_height(max, message: nil)
+          raise Error, ":store_dimensions plugin is required" if !get.respond_to?(:height)
+          if get.height > max
+            errors << error_message(:max_height, message, max)
+          end
+        end
+
+        # Validates that the file is not shorter than `min`. Requires the
+        # store_dimensions plugin.
+        def validate_min_height(min, message: nil)
+          raise Error, ":store_dimensions plugin is required" if !get.respond_to?(:height)
+          if get.height < min
+            errors << error_message(:min_height, message, min)
+          end
+        end
+
+        # Validates that the MIME type is in the `whitelist`. The whitelist is
+        # an array of strings or regexes.
+        #
+        #     validate_mime_type_inclusion ["audio/mp3", /^video/]
+        def validate_mime_type_inclusion(whitelist, message: nil)
+          if whitelist.none? { |mime_type| regex(mime_type) =~ get.mime_type.to_s }
+            errors << error_message(:mime_type_inclusion, message, whitelist)
+          end
+        end
+
+        # Validates that the MIME type is not in the `blacklist`. The blacklist
+        # is an array of strings or regexes.
+        #
+        #     validate_mime_type_exclusion ["image/gif", /^audio/]
+        def validate_mime_type_exclusion(blacklist, message: nil)
+          if blacklist.any? { |mime_type| regex(mime_type) =~ get.mime_type.to_s }
+            errors << error_message(:mime_type_exclusion, message, blacklist)
+          end
+        end
+
+        # Validates that the extension is in the `whitelist`. The whitelist
+        # is an array of strings or regexes.
+        #
+        #     validate_extension_inclusion [/jpe?g/]
+        def validate_extension_inclusion(whitelist, message: nil)
+          if whitelist.none? { |extension| regex(extension) =~ get.extension.to_s }
+            errors << error_message(:extension_inclusion, message, whitelist)
+          end
+        end
+
+        # Validates that the extension is not in the `blacklist`. The blacklist
+        # is an array of strings or regexes.
+        #
+        #     validate_extension_exclusion ["mov", /^mp*/]
+        def validate_extension_exclusion(blacklist, message: nil)
+          if blacklist.any? { |extension| regex(extension) =~ get.extension.to_s }
+            errors << error_message(:extension_exclusion, message, blacklist)
+          end
+        end
+
+        private
+
+        # Converts a string to a regex.
+        def regex(string)
+          string.is_a?(Regexp) ? string : /^#{Regexp.escape(string)}$/
+        end
+
+        # Returns the direct message if given, otherwise uses the default error
+        # message.
+        def error_message(type, message, object)
+          message ||= self.class.default_validation_messages.fetch(type)
+          message.is_a?(String) ? message : message.call(object)
+        end
+      end
+    end
+
+    register_plugin(:validation_helpers, ValidationHelpers)
+  end
+end

data/lib/shrine/plugins/versions.rb

@@ -0,0 +1,177 @@
+class Shrine
+  module Plugins
+    # The versions plugin enables your uploader to deal with versions. To
+    # generate versions, you simply return a hash of versions in `Shrine#process`:
+    #
+    #     class ImageUploader < Shrine
+    #       plugin :versions, names: [:large, :medium, :small]
+    #
+    #       def process(io, context)
+    #         if context[:phase] == :store
+    #           size_700 = process_to_limit!(io.download, 700, 700)
+    #           size_500 = process_to_limit!(size_700,    500, 500)
+    #           size_300 = process_to_limit!(size_500,    300, 300)
+    #
+    #           {large: size_700, medium: size_500, small: size_300}
+    #         end
+    #       end
+    #     end
+    #
+    # Now when you access the attachment through the model, a hash of uploaded
+    # files will be returned:
+    #
+    #     user.avatar #=>
+    #     # {
+    #     #   large:  #<Shrine::UploadedFile>,
+    #     #   medium: #<Shrine::UploadedFile>,
+    #     #   small:  #<Shrine::UploadedFile>,
+    #     # }
+    #     user.avatar.class #=> Hash
+    #
+    #     # With the store_dimensions plugin
+    #     user.avatar[:large].width  #=> 700
+    #     user.avatar[:medium].width #=> 500
+    #     user.avatar[:small].width  #=> 300
+    #
+    # The plugin also extends the `avatar_url` method to accept versions:
+    #
+    #     user.avatar_url(:medium)
+    #
+    # This method plays nice when generating versions in a background job,
+    # since it will just point to the original cached file until the versions
+    # are done processing:
+    #
+    #     user.avatar #=> #<Shrine::UploadedFile>
+    #     user.avatar_url(:medium) #=> "http://example.com/original.jpg"
+    #
+    #     # the versions have finished generating
+    #
+    #     user.avatar_url(:medium) #=> "http://example.com/medium.jpg"
+    #
+    # Any additional options will be properly forwarded to the underlying
+    # storage:
+    #
+    #     user.avatar_url(:medium, download: true)
+    #
+    # You can also easily generate default URLs for specific versions, since
+    # the `context` will include the version name:
+    #
+    #     class ImageUploader
+    #       def default_url(io, context)
+    #         "/images/defaults/#{context[:version]}.jpg"
+    #       end
+    #     end
+    #
+    # When deleting versions, any multi delete capabilities will be leveraged,
+    # so when usingStorage::S3, deleting versions will issue only a single HTTP
+    # request.
+    module Versions
+      def self.load_dependencies(uploader, *)
+        uploader.plugin :multi_delete
+      end
+
+      def self.configure(uploader, names:)
+        uploader.opts[:version_names] = names
+      end
+
+      module ClassMethods
+        def version_names
+          opts[:version_names]
+        end
+
+        # Checks that the identifier is a registered version.
+        def version?(name)
+          version_names.map(&:to_s).include?(name.to_s)
+        end
+
+        # Asserts that the hash doesn't contain any unknown versions.
+        def versions!(hash)
+          hash.select do |name, version|
+            version?(name) or raise Error, "unknown version: #{name.inspect}"
+          end
+        end
+
+        # Filters the hash to contain only the registered versions.
+        def versions(hash)
+          hash.select { |name, version| version?(name) }
+        end
+
+        # Converts a hash of data into a hash of versions.
+        def uploaded_file(object, &block)
+          if object.is_a?(Hash) && !object.key?("storage")
+            versions(object).inject({}) do |result, (name, data)|
+              result.update(name.to_sym => super(data, &block))
+            end
+          else
+            super
+          end
+        end
+      end
+
+      module InstanceMethods
+        # Checks whether all versions are uploaded by this uploader.
+        def uploaded?(uploaded_file)
+          if (hash = uploaded_file).is_a?(Hash)
+            hash.all? { |name, version| super(version) }
+          else
+            super
+          end
+        end
+
+        private
+
+        # Stores each version individually. It asserts that all versions are
+        # known, because later the versions will be silently filtered, so
+        # we want to let the user know that they forgot to register a new
+        # version.
+        def _store(io, context)
+          if (hash = io).is_a?(Hash)
+            self.class.versions!(hash).inject({}) do |result, (name, version)|
+              result.update(name => super(version, version: name, **context))
+            end
+          else
+            super
+          end
+        end
+
+        # Deletes each file individually, but uses S3's multi delete
+        # capabilities.
+        def _delete(uploaded_file, context)
+          if (versions = uploaded_file).is_a?(Hash)
+            super(versions.values, context)
+            versions
+          else
+            super
+          end
+        end
+      end
+
+      module AttacherMethods
+        # Smart versioned URLs, which include the version name in the default
+        # URL, and properly forwards any options to the underlying storage.
+        def url(version = nil, **options)
+          if get.is_a?(Hash)
+            if version
+              raise Error, "unknown version: #{version.inspect}" if !shrine_class.version_names.include?(version)
+              if file = get[version]
+                file.url(**options)
+              else
+                default_url(options.merge(version: version))
+              end
+            else
+              raise Error, "must call #{name}_url with the name of the version"
+            end
+          else
+            if get || version.nil?
+              super(**options)
+            else
+              default_url(options.merge(version: version))
+            end
+          end
+        end
+      end
+    end
+
+    register_plugin(:versions, Versions)
+  end
+end

data/lib/shrine/storage/file_system.rb

@@ -0,0 +1,165 @@
+require "down"
+
+require "fileutils"
+require "pathname"
+
+class Shrine
+  module Storage
+    class FileSystem
+      attr_reader :directory, :subdirectory, :host, :permissions
+
+      # The `directory` is the root directory where uploaded files will be
+      # stored. In web applications this is typically the "public/" directory,
+      # to make the files available via URL.
+      #
+      # If `:subdirectory` is given, #url will return a URL relative to
+      # `directory` (and include `:subdirectory`). So, `FileSystem.new('public',
+      # subdirectory: 'uploads')` will upload files to "public/uploads", and
+      # URLs will be "/uploads/*".
+      #
+      # In applications it's common to serve files over CDN, so an additional
+      # `:host` option can be provided. This option can also be used without
+      # `:subdirectory`, if for example files are located on another server
+      # which requires an IP address.
+      #
+      # By default FileSystem will clean empty directories when files get
+      # deleted. However, if this puts too much load on the filesystem, it can
+      # be disabled with `clean: false`.
+      #
+      # Optional folder and file permissions can be set through the
+      # `:permissions` option.
+      def initialize(directory, subdirectory: nil, host: nil, clean: true, permissions: nil)
+        if subdirectory
+          @subdirectory = Pathname(relative(subdirectory))
+          @directory = Pathname(directory).join(@subdirectory)
+        else
+          @directory = Pathname(directory)
+        end
+
+        @host = host
+        @permissions = permissions
+        @clean = clean
+
+        @directory.mkpath
+        @directory.chmod(permissions) if permissions
+      end
+
+      # Copies the file into the given location.
+      def upload(io, id, metadata = {})
+        IO.copy_stream(io, path!(id)); io.rewind
+        path(id).chmod(permissions) if permissions
+      end
+
+      # Downloads the file from the given location, and returns a `Tempfile`.
+      def download(id)
+        Down.copy_to_tempfile(id, open(id))
+      end
+
+      # Moves the file to the given location. This gets called by the "moving"
+      # plugin.
+      def move(io, id, metadata = {})
+        if io.respond_to?(:path)
+          FileUtils.mv io.path, path!(id)
+        else
+          FileUtils.mv io.storage.path(io.id), path!(id)
+          io.storage.clean(io.id) if io.storage.clean?
+        end
+        path(id).chmod(permissions) if permissions
+      end
+
+      # Returns true if the file is a `File` or a UploadedFile uploaded by the
+      # FileSystem storage.
+      def movable?(io, id)
+        io.respond_to?(:path) ||
+          (io.is_a?(UploadedFile) && io.storage.is_a?(Storage::FileSystem))
+      end
+
+      # Opens the file on the given location in read mode.
+      def open(id)
+        path(id).open("rb")
+      end
+
+      # Returns the contents of the file as a String.
+      def read(id)
+        path(id).binread
+      end
+
+      # Returns true if the file exists on the filesystem.
+      def exists?(id)
+        path(id).exist?
+      end
+
+      # Delets the file, and by default deletes the containing directory if
+      # it's empty.
+      def delete(id)
+        path(id).delete
+        clean(id) if clean?
+      end
+
+      # If #subdirectory is present, returns the path relative to #directory,
+      # with an optional #host in front. Otherwise returns the full path to the
+      # file (also with an optional #host).
+      def url(id, **options)
+        if subdirectory
+          File.join(host || "", subdirectory, id)
+        else
+          if host
+            File.join(host, path(id))
+          else
+            path(id).to_s
+          end
+        end
+      end
+
+      # Without any options it deletes all files from the #directory (and this
+      # requires confirmation). If `:older_than` is passed in (a `Time`
+      # object), deletes all files which were last modified before that time.
+      def clear!(confirm = nil, older_than: nil)
+        if older_than
+          directory.find do |path|
+            path.mtime < older_than ? path.rmtree : Find.prune
+          end
+        else
+          raise Shrine::Confirm unless confirm == :confirm
+          directory.rmtree
+          directory.mkpath
+          directory.chmod(permissions) if permissions
+        end
+      end
+
+      protected
+
+      # Returns the full path to the file.
+      def path(id)
+        directory.join(relative(id))
+      end
+
+      # Cleans all empty subdirectories up the hierarchy.
+      def clean(id)
+        path(id).dirname.ascend do |pathname|
+          if pathname.children.empty? && pathname != directory
+            pathname.rmdir
+          else
+            break
+          end
+        end
+      end
+
+      def clean?
+        @clean
+      end
+
+      private
+
+      # Creates all intermediate directories for that location.
+      def path!(id)
+        path(id).dirname.mkpath
+        path(id)
+      end
+
+      def relative(path)
+        path.sub(%r{^/}, "")
+      end
+    end
+  end
+end