shrine 2.5.0 → 2.6.0

data/lib/shrine/plugins/recache.rb

@@ -20,7 +20,7 @@ class Shrine
     # Recaching will be automatically triggered in a "before save" callback,
     # but if you're using the attacher directly, you can call it manually:
     #
-    #     attacher.recache if attacher.attached?
+    #     attacher.recache if attacher.changed?
     module Recache
       module AttacherMethods
         def save

data/lib/shrine/plugins/refresh_metadata.rb

@@ -0,0 +1,29 @@
+class Shrine
+  module Plugins
+    # The `refresh_metadata` plugin allows you to re-extract metadata from an
+    # uploaded file.
+    #
+    #     plugin :refresh_metadata
+    #
+    # It provides `UploadedFile#refresh_metadata!` method, which calls
+    # `Shrine#extract_metadata` with the uploaded file opened for reading,
+    # and updates the existing metadata hash with the results.
+    #
+    #     uploaded_file.refresh_metadata!
+    #     uploaded_file.metadata # re-extracted metadata
+    #
+    # For remote storages this will make an HTTP request to open the file for
+    # reading, but only the portion of the file needed for extracting each
+    # metadata value will be downloaded.
+    module RefreshMetadata
+      module FileMethods
+        def refresh_metadata!(context = {})
+          refreshed_metadata = open { uploader.extract_metadata(self, context) }
+          metadata.merge!(refreshed_metadata)
+        end
+      end
+    end
+
+    register_plugin(:refresh_metadata, RefreshMetadata)
+  end
+end

data/lib/shrine/plugins/remote_url.rb

@@ -21,8 +21,12 @@ class Shrine
     #     attacher.remote_url = "http://example.com/cool-image.png"
     #
     # The file will by default be downloaded using [Down], which is a wrapper
-    # around the open-uri standard library. It's a good practice to limit the
-    # maximum filesize of the remote file:
+    # around the `open-uri` standard library. Note that Down expects the given
+    # URL to be URI-encoded.
+    #
+    # ## Maximum size
+    #
+    # It's a good practice to limit the maximum filesize of the remote file:
     #
     #     plugin :remote_url, max_size: 20*1024*1024 # 20 MB
     #
@@ -34,20 +38,38 @@ class Shrine
     #
     #     plugin :remote_url, max_size: nil
     #
-    # If you need to additionally customize how the file is downloaded, you can
-    # override the `:downloader`:
+    # ## Custom downloader
+    #
+    # If you want to customize how the file is downloaded, you can override the
+    # `:downloader` parameter and provide your own implementation. For example,
+    # you can ensure the URL is URI-encoded (using the [Addressable] gem) before
+    # passing it to Down:
+    #
+    #     require "down"
+    #     require "addressable/uri"
     #
     #     plugin :remote_url, max_size: 20*1024*1024, downloader: ->(url, max_size:) do
+    #       url = Addressable::URI.encode(Addressable::URI.decode(url))
     #       Down.download(url, max_size: max_size, max_redirects: 4, read_timeout: 3)
     #     end
     #
+    # ## Errors
+    #
     # If download errors, the error is rescued and a validation error is added
     # equal to the error message. You can change the default error message:
     #
     #     plugin :remote_url, error_message: "download failed"
     #     plugin :remote_url, error_message: ->(url, error) { I18n.t("errors.download_failed") }
     #
+    # ## Background
+    #
+    # If you want the file to be downloaded from the URL in the background, you
+    # can use the [shrine-url] storage which allows you to assign a custom URL
+    # as cached file ID, and pair that with the `backgrounding` plugin.
+    #
     # [Down]: https://github.com/janko-m/down
+    # [Addressable]: https://github.com/sporkmonger/addressable
+    # [shrine-url]: https://github.com/janko-m/shrine-url
     module RemoteUrl
       def self.configure(uploader, opts = {})
         raise Error, "The :max_size option is required for remote_url plugin" if !opts.key?(:max_size) && !uploader.opts.key?(:remote_url_max_size)

data/lib/shrine/plugins/remove_invalid.rb

@@ -1,8 +1,9 @@
 class Shrine
   module Plugins
-    # The `remove_invalid` plugin automatically deletes a cached file if it was
-    # invalid and deassigns it from the record. If there was a previous file
-    # attached, it will be assigned back, otherwise `nil` will be assigned.
+    # The `remove_invalid` plugin automatically deletes a new assigned file if
+    # it was invalid and deassigns it from the record. If there was a previous
+    # file attached, it will be assigned back, otherwise no attachment will be
+    # assigned.
     #
     #     plugin :remove_invalid
     module RemoveInvalid
@@ -10,7 +11,7 @@ class Shrine
         def validate
           super
         ensure
-          if errors.any? && cached?
+          if errors.any? && changed?
             _delete(get, action: :validate)
             _set(@old)
             remove_instance_variable(:@old)

data/lib/shrine/plugins/restore_cached_data.rb

@@ -1,28 +1,25 @@
 class Shrine
   module Plugins
-    # The `restore_cached_data` plugin re-extracts cached file's metadata on
-    # assignment. This happens when an uploaded file is retained on validation
-    # errors, or when assigning direct uploaded files. In both cases you
-    # usually want to re-extract metadata on the server side, mainly to prevent
+    # The `restore_cached_data` plugin re-extracts metadata when assigning
+    # already cached files, i.e. when the attachment has been retained on
+    # validation errors or assigned from a direct upload. In both cases you may
+    # want to re-extract metadata on the server side, mainly to prevent
     # tempering, but also in case of direct uploads to obtain metadata that
     # couldn't be extracted on the client side.
     #
     #     plugin :restore_cached_data
     #
-    # This will give an opened `UploadedFile` for metadata extraction. For
-    # remote storages this will make an HTTP request, and since metadata is
-    # typically found in the beginning of the file, Shrine will download only
-    # the amount of bytes necessary for extracting the metadata.
+    # It uses the `refresh_metadata` plugin to re-extract metadata.
     module RestoreCachedData
+      def self.load_dependencies(uploader, *)
+        uploader.plugin :refresh_metadata
+      end
+
       module AttacherMethods
         private
 
         def assign_cached(cached_file)
-          uploaded_file(cached_file) do |file|
-            real_metadata = file.open { cache.extract_metadata(file, context) }
-            file.metadata.update(real_metadata)
-          end
-
+          uploaded_file(cached_file) { |file| file.refresh_metadata!(context) }
           super(cached_file)
         end
       end

data/lib/shrine/plugins/sequel.rb

@@ -22,7 +22,7 @@ class Shrine
     # saves again with a stored attachment, you can detect this in callbacks:
     #
     #     class User < Sequel::Model
-    #       include ImageUploader[:avatar]
+    #       include ImageUploader::Attachment.new(:avatar)
     #
     #       def before_save
     #         super
@@ -48,7 +48,7 @@ class Shrine
     # attachment, you can do it directly on the model.
     #
     #     class User < Sequel::Model
-    #       include ImageUploader[:avatar]
+    #       include ImageUploader::Attachment.new(:avatar)
     #       validates_presence_of :avatar
     #     end
     #
@@ -82,12 +82,12 @@ class Shrine
           module_eval <<-RUBY, __FILE__, __LINE__ + 1 if opts[:sequel_callbacks]
             def before_save
               super
-              #{@name}_attacher.save if #{@name}_attacher.attached?
+              #{@name}_attacher.save if #{@name}_attacher.changed?
             end
 
             def after_save
               super
-              db.after_commit{#{@name}_attacher.finalize} if #{@name}_attacher.attached?
+              db.after_commit{#{@name}_attacher.finalize} if #{@name}_attacher.changed?
             end
 
             def after_destroy

data/lib/shrine/plugins/signature.rb

@@ -0,0 +1,146 @@
+class Shrine
+  module Plugins
+    # The `signature` plugin provides the ability to calculate a hash from file
+    # content. The hash can then be used as a checksum or just as a unique
+    # signature of the file.
+    #
+    #     plugin :signature
+    #
+    # The plugin adds a `calculate_signature` instance and class method to
+    # `Shrine`, which accepts the IO object and hashing algorithm and returns
+    # the calculated hash.
+    #
+    #     Shrine.calculate_signature(io, :md5)
+    #     #=> "9a0364b9e99bb480dd25e1f0284c8555"
+    #
+    # You can then use the `add_metadata` plugin to add a new metadata field
+    # with the calculated hash.
+    #
+    #     plugin :add_metadata
+    #
+    #     add_metadata :md5 do |io, context|
+    #       calculate_signature(io, :md5)
+    #     end
+    #
+    # This will generate a hash for each uploaded file, but if you want to
+    # generate one only for the original file, you can add a conditional:
+    #
+    #     add_metadata :md5 do |io, context|
+    #       calculate_signature(io, :md5) if context[:action] == :cache
+    #     end
+    #
+    # The following hashing algorithms are supported:
+    #
+    # * `sha1`
+    # * `sha256`
+    # * `sha384`
+    # * `sha512`
+    # * `md5`
+    # * `crc32`
+    #
+    # You can also choose which format will the calculated hash be encoded in:
+    #
+    #     Shrine.calculate_signature(io, :md5, format: :hex)
+    #
+    # The following encoding formats are supported:
+    #
+    # * `none`
+    # * `hex` (default)
+    # * `base64`
+    module Signature
+      module ClassMethods
+        # Calculates `algorithm` hash of the contents of the IO object, and
+        # encodes it into `format`.
+        def calculate_signature(io, algorithm, format: :hex)
+          algorithm = algorithm.downcase # support uppercase algorithm names like :MD5
+          SignatureCalculator.new(algorithm, format: format).call(io)
+        end
+      end
+
+      module InstanceMethods
+        # Calculates `algorithm` hash of the contents of the IO object, and
+        # encodes it into `format`.
+        def calculate_signature(io, algorithm, format: :hex)
+          self.class.calculate_signature(io, algorithm, format: format)
+        end
+      end
+
+      class SignatureCalculator
+        SUPPORTED_ALGORITHMS = [:sha1, :sha256, :sha384, :sha512, :md5, :crc32]
+        SUPPORTED_FORMATS    = [:none, :hex, :base64]
+
+        attr_reader :algorithm, :format
+
+        def initialize(algorithm, format:)
+          raise ArgumentError, "hash algorithm not supported: #{algorithm}" unless SUPPORTED_ALGORITHMS.include?(algorithm)
+          raise ArgumentError, "hash format not supported: #{format}" unless SUPPORTED_FORMATS.include?(format)
+
+          @algorithm = algorithm
+          @format    = format
+        end
+
+        def call(io)
+          hash = send(:"calculate_#{algorithm}", io)
+          io.rewind
+
+          encoded_hash = send(:"encode_#{format}", hash)
+          encoded_hash
+        end
+
+        private
+
+        def calculate_sha1(io)
+          calculate_digest(:SHA1, io)
+        end
+
+        def calculate_sha256(io)
+          calculate_digest(:SHA256, io)
+        end
+
+        def calculate_sha384(io)
+          calculate_digest(:SHA384, io)
+        end
+
+        def calculate_sha512(io)
+          calculate_digest(:SHA512, io)
+        end
+
+        def calculate_md5(io)
+          calculate_digest(:MD5, io)
+        end
+
+        def calculate_crc32(io)
+          require "zlib"
+          crc = 0
+          crc = Zlib.crc32(io.read(16*1024, buffer ||= ""), crc) until io.eof?
+          crc.to_s
+        end
+
+        def calculate_digest(name, io)
+          require "digest"
+          digest = Digest.const_get(name).new
+          digest.update(io.read(16*1024, buffer ||= "")) until io.eof?
+          digest.digest
+        end
+
+        def encode_none(hash)
+          hash
+        end
+
+        def encode_hex(hash)
+          hash.unpack("H*").first
+        end
+
+        def encode_base64(hash)
+          require "base64"
+          Base64.encode64(hash)
+        end
+      end
+
+      SUPPORTED_ALGORITHMS = SignatureCalculator::SUPPORTED_ALGORITHMS
+      SUPPORTED_FORMATS    = SignatureCalculator::SUPPORTED_FORMATS
+    end
+
+    register_plugin(:signature, Signature)
+  end
+end

data/lib/shrine/plugins/store_dimensions.rb

@@ -1,7 +1,8 @@
 class Shrine
   module Plugins
     # The `store_dimensions` plugin extracts and stores dimensions of the
-    # uploaded image using the [fastimage] gem.
+    # uploaded image using the [fastimage] gem, which has built-in protection
+    # agains [image bombs].
     #
     #     plugin :store_dimensions
     #
@@ -18,15 +19,27 @@ class Shrine
     #     # or
     #     image.dimensions #=> [300, 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`:
+    # You can provide your own custom dimensions analyzer, and reuse any of the
+    # built-in analyzers; you just need to return a two-element array of width
+    # and height, or nil to signal that dimensions weren't extracted.
+    #
+    #     require "mini_magick"
     #
     #     plugin :store_dimensions, analyzer: ->(io, analyzers) do
     #       dimensions = analyzers[:fastimage].call(io)
     #       dimensions || MiniMagick::Image.new(io).dimensions
     #     end
     #
+    # You can also use methods for extracting the dimensions directly:
+    #
+    #     # or YourUploader.extract_dimensions(io)
+    #     Shrine.extract_dimensions(io) # calls the defined analyzer
+    #     #=> [300, 400]
+    #
+    #     # or YourUploader.dimensions_analyzers
+    #     Shrine.dimensions_analyzers[:fastimage].call(io) # calls a built-in analyzer
+    #     #=> [300, 400]
+    #
     # [fastimage]: https://github.com/sdsykes/fastimage
     # [image bombs]: https://www.bamsoftware.com/hacks/deflate.html
     module StoreDimensions
@@ -34,6 +47,30 @@ class Shrine
         uploader.opts[:dimensions_analyzer] = opts.fetch(:analyzer, uploader.opts.fetch(:dimensions_analyzer, :fastimage))
       end
 
+      module ClassMethods
+        # Determines the dimensions of the IO object by calling the specified
+        # analyzer.
+        def extract_dimensions(io)
+          analyzer = opts[:dimensions_analyzer]
+          analyzer = dimensions_analyzers[analyzer] if analyzer.is_a?(Symbol)
+          args = [io, dimensions_analyzers].take(analyzer.arity.abs)
+
+          dimensions = analyzer.call(*args)
+          io.rewind
+
+          dimensions
+        end
+
+        # Returns a hash of built-in dimensions analyzers, where keys are
+        # analyzer names and values are `#call`-able objects which accepts the
+        # IO object.
+        def dimensions_analyzers
+          @dimensions_analyzers ||= DimensionsAnalyzer::SUPPORTED_TOOLS.inject({}) do |hash, tool|
+            hash.merge!(tool => DimensionsAnalyzer.new(tool).method(:call))
+          end
+        end
+      end
+
       module InstanceMethods
         # We update the metadata with "width" and "height".
         def extract_metadata(io, context)
@@ -47,30 +84,14 @@ class Shrine
 
         private
 
-        # If the `io` is an uploaded file, copies its dimensions, otherwise
-        # calls the predefined or custom analyzer.
+        # Extracts dimensions using the specified analyzer.
         def extract_dimensions(io)
-          analyzer = opts[:dimensions_analyzer]
-          analyzer = dimensions_analyzers[analyzer] if analyzer.is_a?(Symbol)
-          args = [io, dimensions_analyzers].take(analyzer.arity.abs)
-
-          dimensions = analyzer.call(*args)
-          io.rewind
-
-          dimensions
+          self.class.extract_dimensions(io)
         end
 
+        # Returns a hash of built-in dimensions analyzers.
         def dimensions_analyzers
-          Hash.new { |hash, key| method(:"_extract_dimensions_with_#{key}") }
-        end
-
-        def _extract_dimensions_with_fastimage(io)
-          require "fastimage"
-
-          dimensions = FastImage.size(io)
-          io.rewind
-
-          dimensions
+          self.class.dimensions_analyzers
         end
       end
 
@@ -87,6 +108,29 @@ class Shrine
           [width, height] if width || height
         end
       end
+
+      class DimensionsAnalyzer
+        SUPPORTED_TOOLS = [:fastimage]
+
+        def initialize(tool)
+          raise ArgumentError, "unsupported mime type analyzer tool: #{tool}" unless SUPPORTED_TOOLS.include?(tool)
+
+          @tool = tool
+        end
+
+        def call(io)
+          dimensions = send(:"extract_with_#{@tool}", io)
+          io.rewind
+          dimensions
+        end
+
+        private
+
+        def extract_with_fastimage(io)
+          require "fastimage"
+          FastImage.size(io)
+        end
+      end
     end
 
     register_plugin(:store_dimensions, StoreDimensions)