shrine 3.0.1 → 3.3.0

data/doc/validation.md

@@ -88,10 +88,11 @@ when defining more validations:
 class ApplicationUploader < Shrine
   Attacher.validate { validate_max_size 5*1024*1024 }
 end
-
+```
+```rb
 class ImageUploader < ApplicationUploader
   Attacher.validate do
-    super() # empty braces are required
+    super() # empty parentheses are required
     validate_mime_type %w[image/jpeg image/png image/webp]
   end
 end

data/lib/shrine.rb

@@ -1,21 +1,21 @@
 # frozen_string_literal: true
 
-require "shrine/version"
 require "shrine/uploaded_file"
 require "shrine/attacher"
 require "shrine/attachment"
 require "shrine/plugins"
+require "shrine/version"
 
 require "securerandom"
 require "json"
 require "tempfile"
 require "logger"
 
-# Core class that represents uploader.
-# Base implementation is defined in InstanceMethods and ClassMethods.
+# Core class that handles uploading files to specified storage.
 class Shrine
   # A generic exception used by Shrine.
-  class Error < StandardError; end
+  class Error < StandardError
+  end
 
   # Raised when a file is not a valid IO.
   class InvalidFile < Error
@@ -68,9 +68,9 @@ class Shrine
     #
     #     Shrine.plugin MyPlugin
     #     Shrine.plugin :my_plugin
-    def plugin(plugin, *args, &block)
+    def plugin(plugin, *args, **kwargs, &block)
       plugin = Plugins.load_plugin(plugin) if plugin.is_a?(Symbol)
-      plugin.load_dependencies(self, *args, &block) if plugin.respond_to?(:load_dependencies)
+      Plugins.load_dependencies(plugin, self, *args, **kwargs, &block)
       self.include(plugin::InstanceMethods) if defined?(plugin::InstanceMethods)
       self.extend(plugin::ClassMethods) if defined?(plugin::ClassMethods)
       self::UploadedFile.include(plugin::FileMethods) if defined?(plugin::FileMethods)
@@ -79,7 +79,7 @@ class Shrine
       self::Attachment.extend(plugin::AttachmentClassMethods) if defined?(plugin::AttachmentClassMethods)
       self::Attacher.include(plugin::AttacherMethods) if defined?(plugin::AttacherMethods)
       self::Attacher.extend(plugin::AttacherClassMethods) if defined?(plugin::AttacherClassMethods)
-      plugin.configure(self, *args, &block) if plugin.respond_to?(:configure)
+      Plugins.configure(plugin, self, *args, **kwargs, &block)
       plugin
     end
 
@@ -297,7 +297,7 @@ class Shrine
     # Retrieves the location for the given IO and context. First it looks
     # for the `:location` option, otherwise it calls #generate_location.
     def get_location(io, location: nil, **options)
-      location ||= generate_location(io, options)
+      location ||= generate_location(io, **options)
       location or fail Error, "location generated for #{io.inspect} was nil"
     end
 

data/lib/shrine/attacher.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 class Shrine
-  # Core class which handles attaching files to model instances.
-  # Base implementation is defined in InstanceMethods and ClassMethods.
+  # Core class that handles attaching files. It uses Shrine and
+  # Shrine::UploadedFile objects internally.
   class Attacher
     @shrine_class = ::Shrine
 
@@ -39,16 +39,17 @@ class Shrine
 
       # Initializes the attached file, temporary and permanent storage.
       def initialize(file: nil, cache: :cache, store: :store)
-        @file    = file
-        @cache   = cache
-        @store   = store
-        @context = {}
+        @file     = file
+        @cache    = cache
+        @store    = store
+        @context  = {}
+        @previous = nil
       end
 
       # Returns the temporary storage identifier.
-      def cache_key; @cache; end
+      def cache_key; @cache.to_sym; end
       # Returns the permanent storage identifier.
-      def store_key; @store; end
+      def store_key; @store.to_sym; end
 
       # Returns the uploader that is used for the temporary storage.
       def cache; shrine_class.new(cache_key); end
@@ -69,6 +70,10 @@ class Shrine
       def assign(value, **options)
         return if value == "" # skip empty hidden field
 
+        if value.is_a?(Hash) || value.is_a?(String)
+          return if uploaded_file(value) == file # skip assignment for current file
+        end
+
         attach_cached(value, **options)
       end
 
@@ -89,7 +94,7 @@ class Shrine
       #     attacher.attach_cached({ "id" => "...", "storage" => "cache", "metadata" => {} })
       def attach_cached(value, **options)
         if value.is_a?(String) || value.is_a?(Hash)
-          change(cached(value, **options), **options)
+          change(cached(value, **options))
         else
           attach(value, storage: cache_key, action: :cache, **options)
         end
@@ -111,7 +116,7 @@ class Shrine
       def attach(io, storage: store_key, **options)
         file = upload(io, storage, **options) if io
 
-        change(file, **options)
+        change(file)
       end
 
       # Deletes any previous file and promotes newly attached cached file.
@@ -138,7 +143,7 @@ class Shrine
       def finalize
         destroy_previous
         promote_cached
-        remove_instance_variable(:@previous) if changed?
+        @previous = nil
       end
 
       # Plugins can override this if they want something to be done in a
@@ -211,8 +216,8 @@ class Shrine
       #     attacher.change(uploaded_file)
       #     attacher.file #=> #<Shrine::UploadedFile>
       #     attacher.changed? #=> true
-      def change(file, **)
-        @previous = dup unless @file == file
+      def change(file)
+        @previous = dup if change?(file)
         set(file)
       end
 
@@ -254,7 +259,7 @@ class Shrine
       #     attacher.attach(file)
       #     attacher.changed? #=> true
       def changed?
-        instance_variable_defined?(:@previous)
+        !!@previous
       end
 
       # Returns whether a file is attached.
@@ -368,6 +373,11 @@ class Shrine
         attached? && !cached?
       end
 
+      # Whether assigning the given file is considered a change.
+      def change?(file)
+        @file != file
+      end
+
       # Returns whether the file is uploaded to specified storage.
       def uploaded?(file, storage_key)
         file&.storage_key == storage_key

data/lib/shrine/attachment.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 class Shrine
-  # Core class which creates attachment modules for specified attribute names
-  # that are included into model classes.
-  # Base implementation is defined in InstanceMethods and ClassMethods.
+  # Core class that provides an attachment interface for a specified attribute
+  # name, which can be added to model/entity classes. The model/entity plugins
+  # define the main interface, which delegates to a Shrine::Attacher object.
   class Attachment < Module
     @shrine_class = ::Shrine
 
@@ -22,8 +22,8 @@ class Shrine
       # Shorthand for `Attachment.new`.
       #
       #   Shrine::Attachment[:image]
-      def [](*args)
-        new(*args)
+      def [](*args, **options)
+        new(*args, **options)
       end
     end
 

data/lib/shrine/plugins.rb

@@ -18,6 +18,28 @@ class Shrine
       plugin
     end
 
+    # Delegate call to the plugin in a way that works across Ruby versions.
+    def self.load_dependencies(plugin, uploader, *args, **kwargs, &block)
+      return unless plugin.respond_to?(:load_dependencies)
+
+      if kwargs.any?
+        plugin.load_dependencies(uploader, *args, **kwargs, &block)
+      else
+        plugin.load_dependencies(uploader, *args, &block)
+      end
+    end
+
+    # Delegate call to the plugin in a way that works across Ruby versions.
+    def self.configure(plugin, uploader, *args, **kwargs, &block)
+      return unless plugin.respond_to?(:configure)
+
+      if kwargs.any?
+        plugin.configure(uploader, *args, **kwargs, &block)
+      else
+        plugin.configure(uploader, *args, &block)
+      end
+    end
+
     # Register the given plugin with Shrine, so that it can be loaded using
     # `Shrine.plugin` with a symbol. Should be used by plugin files. Example:
     #

data/lib/shrine/plugins/activerecord.rb

@@ -55,7 +55,7 @@ class Shrine
           # reload the attacher on record reload
           define_method :reload do |*args|
             result = super(*args)
-            instance_variable_set(:"@#{name}_attacher", nil)
+            send(:"#{name}_attacher").reload
             result
           end
         end

data/lib/shrine/plugins/add_metadata.rb

@@ -9,8 +9,8 @@ class Shrine
       end
 
       module ClassMethods
-        def add_metadata(name = nil, &block)
-          opts[:add_metadata][:definitions] << [name, block]
+        def add_metadata(name = nil, **options, &block)
+          opts[:add_metadata][:definitions] << [name, options, block]
 
           metadata_method(name) if name
         end
@@ -22,7 +22,7 @@ class Shrine
         private
 
         def _metadata_method(name)
-          FileMethods.send(:define_method, name) do
+          self::UploadedFile.send(:define_method, name) do
             metadata[name.to_s]
           end
         end
@@ -40,10 +40,12 @@ class Shrine
         private
 
         def extract_custom_metadata(io, **options)
-          opts[:add_metadata][:definitions].each do |name, block|
-            result = instance_exec(io, options, &block)
+          opts[:add_metadata][:definitions].each do |name, definition_options, block|
+            result = instance_exec(io, **options, &block)
 
-            if name
+            if result.nil? && definition_options[:skip_nil]
+              # Do not store this metadata
+            elsif name
               options[:metadata].merge! name.to_s => result
             else
               options[:metadata].merge! result.transform_keys(&:to_s) if result
@@ -55,8 +57,17 @@ class Shrine
         end
       end
 
+      module AttacherMethods
+        def add_metadata(new_metadata, &block)
+          file!.add_metadata(new_metadata, &block)
+          set(file) # trigger model write
+        end
+      end
+
       module FileMethods
-        # methods will be dynamically defined here through `Shrine.add_metadata`
+        def add_metadata(new_metadata, &block)
+          @metadata = @metadata.merge(new_metadata, &block)
+        end
       end
     end
 

data/lib/shrine/plugins/backgrounding.rb

@@ -36,8 +36,8 @@ class Shrine
 
       module AttacherMethods
         # Inherits global hooks if defined.
-        def initialize(*args)
-          super
+        def initialize(**args)
+          super(**args)
           @destroy_block = self.class.destroy_block
           @promote_block = self.class.promote_block
         end

data/lib/shrine/plugins/default_storage.rb

@@ -34,12 +34,12 @@ class Shrine
           if @cache.respond_to?(:call)
             if @cache.arity == 2
               Shrine.deprecation("Passing record & name argument to default storage block is deprecated and will be removed in Shrine 4. Use a block without arguments instead.")
-              @cache.call(record, name)
+              @cache.call(record, name).to_sym
             else
-              instance_exec(&@cache)
+              instance_exec(&@cache).to_sym
             end
           else
-            @cache
+            super
           end
         end
 
@@ -47,12 +47,12 @@ class Shrine
           if @store.respond_to?(:call)
             if @store.arity == 2
               Shrine.deprecation("Passing record & name argument to default storage block is deprecated and will be removed in Shrine 4. Use a block without arguments instead.")
-              @store.call(record, name)
+              @store.call(record, name).to_sym
             else
-              instance_exec(&@store)
+              instance_exec(&@store).to_sym
             end
           else
-            @store
+            super
           end
         end
       end

data/lib/shrine/plugins/default_url.rb

@@ -25,7 +25,7 @@ class Shrine
         def default_url(**options)
           return unless default_url_block
 
-          url = instance_exec(options, &default_url_block)
+          url = instance_exec(**options, &default_url_block)
 
           [*default_url_host, url].join
         end

data/lib/shrine/plugins/derivation_endpoint.rb

@@ -392,6 +392,7 @@ class Shrine
       options[:type]        = request.params["type"]        if request.params["type"]
       options[:disposition] = request.params["disposition"] if request.params["disposition"]
       options[:filename]    = request.params["filename"]    if request.params["filename"]
+      options[:version]     = request.params["version"]     if request.params["version"]
       options[:expires_in]  = expires_in(request)           if request.params["expires_at"]
 
       derivation = uploaded_file.derivation(name, *args, **options)
@@ -475,9 +476,9 @@ class Shrine
       file_response(derivative, env)
     end
 
-    # Generates a Rack response triple from a local file using `Rack::File`.
-    # Fills in `Content-Type` and `Content-Disposition` response headers from
-    # derivation options and file extension of the derivation result.
+    # Generates a Rack response triple from a local file. Fills in
+    # `Content-Type` and `Content-Disposition` response headers from derivation
+    # options and file extension of the derivation result.
     def file_response(file, env)
       response = rack_file_response(file.path, env)
 
@@ -511,7 +512,7 @@ class Shrine
       end
 
       if upload_redirect
-        redirect_url = uploaded_file.url(upload_redirect_url_options)
+        redirect_url = uploaded_file.url(**upload_redirect_url_options)
 
         [302, { "Location" => redirect_url }, []]
       else
@@ -528,10 +529,14 @@ class Shrine
       end
     end
 
-    # We call `Rack::File` with no default `Content-Type`, and make sure we
+    # We call `Rack::Files` with no default `Content-Type`, and make sure we
     # stay compatible with both Rack 2.x and 1.6.x.
     def rack_file_response(path, env)
-      server = Rack::File.new("", {}, nil)
+      if Rack.release >= "2.1"
+        server = Rack::Files.new("", {}, nil)
+      else
+        server = Rack::File.new("", {}, nil)
+      end
 
       if Rack.release > "2"
         server.serving(Rack::Request.new(env), path)
@@ -734,7 +739,7 @@ class Shrine
     def verify_signature(string, signature)
       if signature.nil?
         fail InvalidSignature, "missing \"signature\" param"
-      elsif signature != generate_signature(string)
+      elsif !Rack::Utils.secure_compare(signature, generate_signature(string))
         fail InvalidSignature, "provided signature does not match the calculated signature"
       end
     end

data/lib/shrine/plugins/derivatives.rb

@@ -4,8 +4,6 @@ class Shrine
   module Plugins
     # Documentation can be found on https://shrinerb.com/docs/plugins/derivatives
     module Derivatives
-      NOOP_PROCESSOR = -> (*) { Hash.new }
-
       LOG_SUBSCRIBER = -> (event) do
         Shrine.logger.info "Derivatives (#{event.duration}ms) – #{{
           processor:         event[:processor],
@@ -21,7 +19,7 @@ class Shrine
       end
 
       def self.configure(uploader, log_subscriber: LOG_SUBSCRIBER, **opts)
-        uploader.opts[:derivatives] ||= { processors: {}, storage: proc { store_key } }
+        uploader.opts[:derivatives] ||= { processors: {}, processor_settings: {}, storage: proc { store_key } }
         uploader.opts[:derivatives].merge!(opts)
 
         # instrumentation plugin integration
@@ -40,8 +38,8 @@ class Shrine
         def define_model_methods(name)
           super if defined?(super)
 
-          define_method(:"#{name}_derivatives!") do |*args|
-            send(:"#{name}_attacher").create_derivatives(*args)
+          define_method(:"#{name}_derivatives!") do |*args, **options|
+            send(:"#{name}_attacher").create_derivatives(*args, **options)
           end
         end
       end
@@ -52,18 +50,36 @@ class Shrine
         #     Attacher.derivatives_processor :thumbnails do |original|
         #       # ...
         #     end
-        def derivatives_processor(name = :default, &block)
+        #
+        # By default, Shrine will convert the source IO object into a file
+        # before it's passed to the processor block. You can set `download:
+        # false` to pass the source IO object to the processor block as is.
+        #
+        #     Attacher.derivatives_processor :thumbnails, download: false do |original|
+        #       # ...
+        #     end
+        #
+        # This can be useful if you'd like to defer or avoid a possibly
+        # expensive download operation for processor logic that does not
+        # require it.
+        def derivatives_processor(name = :default, download: true, &block)
           if block
-            shrine_class.opts[:derivatives][:processors][name.to_sym] = block
+            shrine_class.derivatives_options[:processors][name.to_sym] = block
+            shrine_class.derivatives_options[:processor_settings][name.to_sym] = { download: download }
           else
-            processor   = shrine_class.opts[:derivatives][:processors][name.to_sym]
-            processor ||= NOOP_PROCESSOR if name == :default
-
-            fail Error, "derivatives processor #{name.inspect} not registered" unless processor
-
-            processor
+            shrine_class.derivatives_options[:processors].fetch(name.to_sym) do
+              fail Error, "derivatives processor #{name.inspect} not registered" unless name == :default
+            end
           end
         end
+        alias derivatives derivatives_processor
+
+        # Returns settings for the given derivatives processor.
+        #
+        #     Attacher.derivatives_processor_settings(:thumbnails) #=> { download: true }
+        def derivatives_processor_settings(name)
+          shrine_class.derivatives_options[:processor_settings][name.to_sym] || {}
+        end
 
         # Specifies default storage to which derivatives will be uploaded.
         #
@@ -78,9 +94,9 @@ class Shrine
         #     end
         def derivatives_storage(storage_key = nil, &block)
           if storage_key || block
-            shrine_class.opts[:derivatives][:storage] = storage_key || block
+            shrine_class.derivatives_options[:storage] = storage_key || block
           else
-            shrine_class.opts[:derivatives][:storage]
+            shrine_class.derivatives_options[:storage]
           end
         end
       end
@@ -146,6 +162,7 @@ class Shrine
         def promote(**options)
           super
           promote_derivatives
+          create_derivatives if create_derivatives_on_promote?
         end
 
         # Uploads any cached derivatives to permanent storage.
@@ -179,9 +196,9 @@ class Shrine
         #     end
         #
         #     attacher.create_derivatives(:my_processor)
-        def create_derivatives(*args)
-          files = process_derivatives(*args)
-          add_derivatives(files)
+        def create_derivatives(*args, storage: nil, **options)
+          files = process_derivatives(*args, **options)
+          add_derivatives(files, storage: storage)
         end
 
         # Uploads given hash of files and adds uploaded files to the
@@ -226,8 +243,6 @@ class Shrine
         #     hash[:thumb] #=> #<Shrine::UploadedFile>
         def upload_derivatives(files, **options)
           map_derivative(files) do |path, file|
-            path = derivative_path(path)
-
             upload_derivative(path, file, **options)
           end
         end
@@ -237,6 +252,7 @@ class Shrine
         #     hash = attacher.upload_derivative(:thumb, thumb)
         #     hash[:thumb] #=> #<Shrine::UploadedFile>
         def upload_derivative(path, file, storage: nil, **options)
+          path      = derivative_path(path)
           storage ||= derivative_storage(path)
 
           file.open    if file.is_a?(Tempfile)       # refresh file descriptor
@@ -268,8 +284,10 @@ class Shrine
 
           source ||= file!
 
-          if source.is_a?(UploadedFile)
-            source.download do |file|
+          processor_settings = self.class.derivatives_processor_settings(processor_name) || {}
+
+          if processor_settings[:download]
+            shrine_class.with_file(source) do |file|
               _process_derivatives(processor_name, file, **options)
             end
           else
@@ -373,7 +391,7 @@ class Shrine
         #     attacher.derivatives #=> { thumb: #<Shrine::UploadedFile> }
         def set_derivatives(derivatives)
           self.derivatives = derivatives
-          set file # trigger model writing
+          set file # trigger model write
           derivatives
         end
 
@@ -441,7 +459,7 @@ class Shrine
         #     attacher.derivatives #=> { thumb: #<Shrine::UploadedFile> }
         #     attacher.change(file)
         #     attacher.derivatives #=> {}
-        def change(*args)
+        def change(*)
           result = super
           set_derivatives({})
           result
@@ -462,8 +480,8 @@ class Shrine
         # Iterates through nested derivatives and maps results.
         #
         #     attacher.map_derivative(derivatives) { |path, file| ... }
-        def map_derivative(*args, &block)
-          shrine_class.map_derivative(*args, &block)
+        def map_derivative(derivatives, **options, &block)
+          shrine_class.map_derivative(derivatives, **options, &block)
         end
 
         private
@@ -472,7 +490,9 @@ class Shrine
         def _process_derivatives(processor_name, source, **options)
           processor = self.class.derivatives_processor(processor_name)
 
-          result = instrument_derivatives(processor_name, options) do
+          return {} unless processor
+
+          result = instrument_derivatives(processor_name, source, options) do
             instance_exec(source, **options, &processor)
           end
 
@@ -484,20 +504,22 @@ class Shrine
         end
 
         # Sends a `derivatives.shrine` event for instrumentation plugin.
-        def instrument_derivatives(processor_name, processor_options, &block)
+        def instrument_derivatives(processor_name, source, processor_options, &block)
           return yield unless shrine_class.respond_to?(:instrument)
 
           shrine_class.instrument(
             :derivatives,
             processor:         processor_name,
             processor_options: processor_options,
+            io:                source,
+            attacher:          self,
             &block
           )
         end
 
         # Returns symbolized array or single key.
         def derivative_path(path)
-          path = path.map { |key| key.is_a?(String) ? key.to_sym : key }
+          path = Array(path).map { |key| key.is_a?(String) ? key.to_sym : key }
           path = path.first if path.one?
           path
         end
@@ -519,6 +541,11 @@ class Shrine
             o2
           end
         end
+
+        # Whether to automatically create derivatives on promotion
+        def create_derivatives_on_promote?
+          shrine_class.derivatives_options[:create_on_promote]
+        end
       end
 
       module ClassMethods
@@ -575,6 +602,11 @@ class Shrine
             yield path, object
           end
         end
+
+        # Returns derivatives plugin options.
+        def derivatives_options
+          opts[:derivatives]
+        end
       end
 
       module FileMethods