shrine 2.19.4 → 3.0.0.alpha

data/lib/shrine/attachment.rb

@@ -27,40 +27,6 @@ class Shrine
       def initialize(name, **options)
         @name    = name.to_sym
         @options = options
-
-        define_attachment_methods!
-      end
-
-      # Defines attachment methods for the specified attachment name. These
-      # methods will be added to any model that includes this module.
-      def define_attachment_methods!
-        attachment = self
-        name = attachment_name
-
-        define_method :"#{name}_attacher" do |**options|
-          if !instance_variable_get(:"@#{name}_attacher") || options.any?
-            instance_variable_set(:"@#{name}_attacher", attachment.build_attacher(self, options))
-          else
-            instance_variable_get(:"@#{name}_attacher")
-          end
-        end
-
-        define_method :"#{name}=" do |value|
-          send(:"#{name}_attacher").assign(value)
-        end
-
-        define_method :"#{name}" do
-          send(:"#{name}_attacher").get
-        end
-
-        define_method :"#{name}_url" do |*args|
-          send(:"#{name}_attacher").url(*args)
-        end
-      end
-
-      # Creates an instance of the corresponding Attacher subclass.
-      def build_attacher(object, options)
-        shrine_class::Attacher.new(object, @name, @options.merge(options))
       end
 
       # Returns name of the attachment this module provides.
@@ -75,17 +41,11 @@ class Shrine
 
       # Returns class name with attachment name included.
       #
-      #     Shrine[:image].to_s #=> "#<Shrine::Attachment(image)>"
-      def to_s
-        "#<#{self.class.inspect}(#{attachment_name})>"
-      end
-
-      # Returns class name with attachment name included.
-      #
-      #     Shrine[:image].inspect #=> "#<Shrine::Attachment(image)>"
+      #     Shrine::Attachment.new(:image).to_s #=> "#<Shrine::Attachment(image)>"
       def inspect
         "#<#{self.class.inspect}(#{attachment_name})>"
       end
+      alias to_s inspect
 
       # Returns the Shrine class that this attachment's class is namespaced
       # under.

data/lib/shrine/plugins/activerecord.rb

@@ -8,9 +8,14 @@ class Shrine
     #
     # [doc/plugins/activerecord.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/activerecord.md
     module Activerecord
-      def self.configure(uploader, opts = {})
-        uploader.opts[:activerecord_callbacks] = opts.fetch(:callbacks, uploader.opts.fetch(:activerecord_callbacks, true))
-        uploader.opts[:activerecord_validations] = opts.fetch(:validations, uploader.opts.fetch(:activerecord_validations, true))
+      def self.load_dependencies(uploader, **)
+        uploader.plugin :model
+        uploader.plugin :atomic_helpers
+      end
+
+      def self.configure(uploader, **opts)
+        uploader.opts[:activerecord] ||= { callbacks: true, validations: true }
+        uploader.opts[:activerecord].merge!(opts)
       end
 
       module AttachmentMethods
@@ -21,60 +26,132 @@ class Shrine
 
           name = attachment_name
 
-          if shrine_class.opts[:activerecord_validations]
+          if shrine_class.opts[:activerecord][:validations]
             model.validate do
-              send("#{name}_attacher").errors.each do |message|
-                errors.add(name, *message)
+              # validation plugin integration
+              if send(:"#{name}_attacher").respond_to?(:errors)
+                send(:"#{name}_attacher").errors.each do |message|
+                  errors.add(name, *message)
+                end
               end
             end
           end
 
-          if shrine_class.opts[:activerecord_callbacks]
+          if shrine_class.opts[:activerecord][:callbacks]
             model.before_save do
-              attacher = send("#{name}_attacher")
-              attacher.save if attacher.changed?
+              if send(:"#{name}_attacher").changed?
+                send(:"#{name}_attacher").save
+              end
             end
 
             [:create, :update].each do |action|
               model.after_commit on: action do
-                attacher = send("#{name}_attacher")
-                attacher.finalize if attacher.changed?
+                if send(:"#{name}_attacher").changed?
+                  send(:"#{name}_attacher").finalize
+                  send(:"#{name}_attacher").activerecord_persist
+                end
               end
             end
 
             model.after_commit on: :destroy do
-              send("#{name}_attacher").destroy
+              send(:"#{name}_attacher").destroy_attached
             end
           end
-        end
-      end
 
-      module AttacherClassMethods
-        # Needed by the `backgrounding` plugin.
-        def find_record(record_class, record_id)
-          record_class.where(id: record_id).first
+          # reload the attacher on record reload
+          define_method :reload do |*args|
+            result = super(*args)
+            instance_variable_set(:"@#{name}_attacher", nil)
+            result
+          end
         end
       end
 
       module AttacherMethods
+        # Promotes cached file to permanent storage in an atomic way. It's
+        # intended to be called from a background job.
+        #
+        #     attacher.assign(file)
+        #     attacher.cached? #=> true
+        #
+        #     # ... in background job ...
+        #
+        #     attacher.atomic_promote
+        #     attacher.stored? #=> true
+        #
+        # It accepts `:reload` and `:persist` strategies:
+        #
+        #     attacher.atomic_promote(reload: :lock)    # uses database locking (default)
+        #     attacher.atomic_promote(reload: :fetch)   # reloads with no locking
+        #     attacher.atomic_promote(reload: ->(&b){}) # custom reloader
+        #     attacher.atomic_promote(reload: false)    # skips reloading
+        #
+        #     attacher.atomic_promote(persist: :save) # persists stored file (default)
+        #     attacher.atomic_promote(persist: ->{})  # custom persister
+        #     attacher.atomic_promote(persist: false) # skips persistence
+        def activerecord_atomic_promote(**options, &block)
+          abstract_atomic_promote(activerecord_strategies(**options), &block)
+        end
+        alias atomic_promote activerecord_atomic_promote
+
+        # Persist the the record only if the attachment hasn't changed.
+        # Optionally yields reloaded attacher to the block before persisting.
+        # It's intended to be called from a background job.
+        #
+        #     # ... in background job ...
+        #
+        #     attacher.file.metadata["foo"] = "bar"
+        #     attacher.write
+        #
+        #     attacher.atomic_persist
+        def activerecord_atomic_persist(*args, **options, &block)
+          abstract_atomic_persist(*args, activerecord_strategies(**options), &block)
+        end
+        alias atomic_persist activerecord_atomic_persist
+
+        # Called in the `after_commit` callback after finalization.
+        def activerecord_persist
+          activerecord_save
+        end
+        alias persist activerecord_persist
+
         private
 
-        # Saves the record after assignment, skipping validations.
-        def update(uploaded_file)
-          super
+        # Resolves strategies for atomic promotion and persistence.
+        def activerecord_strategies(reload: :lock, persist: :save, **options)
+          reload  = method(:"activerecord_#{reload}")  if reload.is_a?(Symbol)
+          persist = method(:"activerecord_#{persist}") if persist.is_a?(Symbol)
+
+          { reload: reload, persist: persist, **options }
+        end
+
+        # Implements the "fetch" reload strategy for #atomic_promote and
+        # #atomic_persist.
+        def activerecord_fetch
+          yield record.clone.reload
+        end
+
+        # Implements the "lock" reload strategy for #atomic_promote and
+        # #atomic_persist.
+        def activerecord_lock
+          record.transaction { yield record.clone.reload(lock: true) }
+        end
+
+        # Implements the "save" persist strategy for #atomic_promote and
+        # #atomic_persist.
+        def activerecord_save
           record.save(validate: false)
         end
 
-        # If the data attribute represents a JSON column, it needs to receive a
-        # Hash.
-        def convert_before_write(value)
-          activerecord_json_column? ? value : super
+        # ActiveRecord JSON column attribute needs to be assigned with a Hash.
+        def serialize_column(data)
+          activerecord_json_column? ? data : super
         end
 
         # Returns true if the data attribute represents a JSON or JSONB column.
         def activerecord_json_column?
           return false unless record.is_a?(ActiveRecord::Base)
-          return false unless column = record.class.columns_hash[data_attribute.to_s]
+          return false unless column = record.class.columns_hash[attribute.to_s]
 
           [:json, :jsonb].include?(column.type)
         end

data/lib/shrine/plugins/add_metadata.rb

@@ -7,12 +7,12 @@ class Shrine
     # [doc/plugins/add_metadata.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/add_metadata.md
     module AddMetadata
       def self.configure(uploader)
-        uploader.opts[:add_metadata_definitions] ||= []
+        uploader.opts[:add_metadata] ||= { definitions: [] }
       end
 
       module ClassMethods
         def add_metadata(name = nil, &block)
-          opts[:add_metadata_definitions] << [name, block]
+          opts[:add_metadata][:definitions] << [name, block]
 
           metadata_method(name) if name
         end
@@ -31,25 +31,24 @@ class Shrine
       end
 
       module InstanceMethods
-        def extract_metadata(io, context = {})
+        def extract_metadata(io, **options)
           metadata = super
-          context  = context.merge(metadata: metadata)
 
-          extract_custom_metadata(io, context)
+          extract_custom_metadata(io, **options, metadata: metadata)
 
           metadata
         end
 
         private
 
-        def extract_custom_metadata(io, context)
-          opts[:add_metadata_definitions].each do |name, block|
-            result = instance_exec(io, context, &block)
+        def extract_custom_metadata(io, **options)
+          opts[:add_metadata][:definitions].each do |name, block|
+            result = instance_exec(io, options, &block)
 
             if name
-              context[:metadata].merge! name.to_s => result
+              options[:metadata].merge! name.to_s => result
             else
-              context[:metadata].merge! result.transform_keys(&:to_s) if result
+              options[:metadata].merge! result.transform_keys(&:to_s) if result
             end
 
             # rewind between metadata blocks

data/lib/shrine/plugins/atomic_helpers.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+class Shrine
+  class AttachmentChanged < Error
+  end
+
+  module Plugins
+    # Documentation lives in [doc/plugins/atomic_helpers.md] on GitHub.
+    #
+    # [doc/plugins/atomic_helpers.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/atomic_helpers.md
+    class AtomicHelpers
+      module AttacherClassMethods
+        # Retrieves the attacher from the given entity/model and verifies that
+        # the attachment hasn't changed. It raises `Shrine::AttachmentChanged`
+        # exception if the attached file doesn't match.
+        #
+        #     Shrine::Attacher.retrieve(model: photo, name: :image, data: data)
+        #     #=> #<ImageUploader::Attacher>
+        def retrieve(model: nil, entity: nil, name:, data:, **options)
+          fail ArgumentError, "either :model or :entity is required" unless model || entity
+
+          record = model || entity
+
+          attacher   = record.send(:"#{name}_attacher", **options) if record.respond_to?(:"#{name}_attacher")
+          attacher ||= from_model(record, name, **options) if model
+          attacher ||= from_entity(record, name, **options) if entity
+
+          if attacher.file != attacher.class.from_data(data).file
+            fail Shrine::AttachmentChanged, "attachment has changed"
+          end
+
+          attacher
+        end
+      end
+
+      module AttacherMethods
+        # Like #promote, but additionally persists the promoted file
+        # atomically. You need to specify `:reload` and `:persist` strategies
+        # when calling the method:
+        #
+        #     attacher.abstract_atomic_promote(
+        #       reload:  reload_strategy,
+        #       persist: persist_strategy,
+        #     )
+        #
+        # This more convenient to use with ORM plugins, which provide defaults
+        # for reloading and persistence.
+        def abstract_atomic_promote(reload:, persist:, **options, &block)
+          original_file = file
+
+          result = promote(**options)
+
+          begin
+            abstract_atomic_persist(original_file, reload: reload, persist: persist, &block)
+            result
+          rescue Shrine::AttachmentChanged
+            destroy(background: true)
+            raise
+          end
+        end
+
+        # Reloads the record to check whether the attachment has changed. If it
+        # hasn't, it persists the record. Otherwise it raises
+        # `Shrine::AttachmentChanged` exception.
+        #
+        #     attacher.abstract_atomic_persist(
+        #       reload:  reload_strategy,
+        #       persist: persist_strategy,
+        #     )
+        #
+        # This more convenient to use with ORM plugins, which provide defaults
+        # for reloading and persistence.
+        def abstract_atomic_persist(original_file = file, reload:, persist:)
+          abstract_reload(reload) do |attacher|
+            if attacher && attacher.file != original_file
+              fail Shrine::AttachmentChanged, "attachment has changed"
+            end
+
+            yield attacher if block_given?
+
+            abstract_persist(persist)
+          end
+        end
+
+        protected
+
+        # Calls the reload strategy and yields a reloaded attacher from the
+        # reloaded record.
+        def abstract_reload(strategy)
+          return yield if strategy == false
+
+          strategy.call do |record|
+            reloaded_attacher = dup
+            reloaded_attacher.load_entity(record, name)
+
+            yield reloaded_attacher
+          end
+        end
+
+        # Calls the persist strategy.
+        def abstract_persist(strategy)
+          return if strategy == false
+
+          strategy.call
+        end
+      end
+    end
+
+    register_plugin(:atomic_helpers, AtomicHelpers)
+  end
+end

data/lib/shrine/plugins/attacher_options.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+class Shrine
+  module Plugins
+    module AttacherOptions
+      module AttacherMethods
+        def initialize(**options)
+          super
+          @options = {}
+        end
+
+        def attach_options(options = nil)
+          handle_option(:attach, options)
+        end
+
+        def promote_options(options = nil)
+          handle_option(:promote, options)
+        end
+
+        def destroy_options(options = nil)
+          handle_option(:destroy, options)
+        end
+
+        def attach_cached(io, **options)
+          super(io, **attach_options, **options)
+        end
+
+        def attach(io, **options)
+          super(io, **attach_options, **options)
+        end
+
+        def promote_cached(**options)
+          super(**promote_options, **options)
+        end
+
+        def destroy_attached(**options)
+          super(**destroy_options, **options)
+        end
+
+        private
+
+        def handle_option(name, options)
+          if options
+            @options[name] ||= {}
+            @options[name].merge!(options)
+          else
+            @options[name] || {}
+          end
+        end
+      end
+    end
+
+    register_plugin(:attacher_options, AttacherOptions)
+  end
+end