shrine 2.19.4 → 3.0.0.alpha

data/lib/shrine/plugins/backgrounding.rb

@@ -2,146 +2,178 @@
 
 class Shrine
   module Plugins
-    # Documentation lives in [doc/plugins/backgrounding.md] on GitHub.
+    # The backgrounding plugin allows delaying promotion and deletion into a
+    # background job.
     #
-    # [doc/plugins/backgrounding.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/backgrounding.md
+    # You can register promotion and deletion blocks on an instance of the
+    # attacher, and they will be called as needed.
+    #
+    # ## Promotion
+    #
+    #     attacher.promote_block do
+    #       Attachment::PromoteJob.perform_async(record, name, data)
+    #     end
+    #
+    #     attacher.assign(io)
+    #     attacher.finalize # promote block called
+    #
+    #     attacher.file # cached file
+    #     # ... background job finishes ...
+    #     attacher.file # stored file
+    #
+    # The promote worker can be implemented like this:
+    #
+    #     class Attachment::PromoteJob
+    #       def perform(record, name, data)
+    #         attacher = Shrine::Attacher.retrieve(model: record, name: name, data: data)
+    #         attacher.atomic_promote
+    #       end
+    #     end
+    #
+    # ## Deletion
+    #
+    #     attacher.destroy_block do
+    #       Attachment::DestroyJob.perform_async(data)
+    #     end
+    #
+    #     previous_file = attacher.file
+    #
+    #     attacher.attach(io)
+    #     attacher.finalize # delete hook called
+    #
+    #     previous_file.exists? #=> true
+    #     # ... background job finishes ...
+    #     previous_file.exists? #=> false
+    #
+    #     attacher.destroy_attached
+    #
+    #     attacher.file.exists? #=> true
+    #     # ... background job finishes ...
+    #     attacher.file.exists? #=> false
+    #
+    # The delete worker can be implemented like this:
+    #
+    #     class Attachment::DestroyJob
+    #       def perform(data)
+    #         attacher = Shrine::Attacher.from_data(data)
+    #         attacher.destroy
+    #       end
+    #     end
+    #
+    # ## Global hooks
+    #
+    # You can also register promotion and deletion hooks globally:
+    #
+    #     Shrine::Attacher.promote_block do
+    #       Attachment::PromoteJob.perform_async(record, name, data)
+    #     end
+    #
+    #     Shrine::Attacher.destroy_block do
+    #       Attachment::DestroyJob.perform_async(data)
+    #     end
     module Backgrounding
-      module AttacherClassMethods
-        # If block is passed in, stores it to be called on promotion. Otherwise
-        # resolves data into objects and calls `Attacher#promote`.
-        def promote(data = nil, &block)
-          if block
-            shrine_class.opts[:backgrounding_promote] = block
-          else
-            attacher = load(data)
-            cached_file = attacher.uploaded_file(data["attachment"])
-            action = data["action"].to_sym if data["action"]
-
-            return if cached_file != attacher.get
-            attacher.promote(cached_file, action: action) or return
+      def self.configure(uploader)
+        uploader.opts[:backgrounding] ||= {}
+      end
 
-            attacher
-          end
+      module AttacherClassMethods
+        # Registers a global promotion block.
+        #
+        #     Shrine::Attacher.promote_block do |attacher|
+        #       Attachment::PromoteJob.perform_async(
+        #         attacher.record,
+        #         attacher.name,
+        #         attacher.data,
+        #       )
+        #     end
+        def promote_block(&block)
+          shrine_class.opts[:backgrounding][:promote_block] = block if block
+          shrine_class.opts[:backgrounding][:promote_block]
         end
 
-        # If block is passed in, stores it to be called on deletion. Otherwise
-        # resolves data into objects and calls `Shrine#delete`.
-        def delete(data = nil, &block)
-          if block
-            shrine_class.opts[:backgrounding_delete] = block
-          else
-            attacher = load(data)
-            uploaded_file = attacher.uploaded_file(data["attachment"])
-            action = data["action"].to_sym if data["action"]
-
-            attacher.delete!(uploaded_file, action: action)
-
-            attacher
-          end
+        # Registers a global deletion block.
+        #
+        #     Shrine::Attacher.destroy_block do |attacher|
+        #       Attachment::DeleteJob.perform_async(attacher.data)
+        #     end
+        def destroy_block(&block)
+          shrine_class.opts[:backgrounding][:destroy_block] = block if block
+          shrine_class.opts[:backgrounding][:destroy_block]
         end
+      end
 
-        # Delegates to `Attacher#dump`.
-        def dump(attacher)
-          attacher.dump
+      module AttacherMethods
+        # Inherits global hooks if defined.
+        def initialize(*args)
+          super
+          @destroy_block = self.class.destroy_block
+          @promote_block = self.class.promote_block
         end
 
-        # Loads the data created by #dump, resolving the record and returning
-        # the attacher.
-        def load(data)
-          record = load_record(data)
-          name = data["name"].to_sym
-
-          if record.respond_to?(:"#{name}_attacher")
-            attacher = record.send(:"#{name}_attacher")
-          elsif data["shrine_class"]
-            shrine_class = Object.const_get(data["shrine_class"])
-            attacher = shrine_class::Attacher.new(record, name)
-          else
-            fail Error, "cannot load anonymous uploader class"
-          end
+        # Registers an instance-level promotion hook.
+        #
+        #     attacher.promote_block do |attacher|
+        #       Attachment::PromoteJob.perform_async(
+        #         attacher.record,
+        #         attacher.name
+        #         attacher.data,
+        #       )
+        #     end
+        def promote_block(&block)
+          @promote_block = block if block
+          @promote_block
+        end
 
-          attacher
+        # Registers an instance-level deletion hook.
+        #
+        #     attacher.destroy_block do |attacher|
+        #       Attachment::DeleteJob.perform_async(attacher.data)
+        #     end
+        def destroy_block(&block)
+          @destroy_block = block if block
+          @destroy_block
         end
 
-        # Resolves the record from backgrounding data. If the record was found,
-        # returns it. If the record wasn't found, returns an instance of the
-        # model with ID assigned for logging. If `find_record` isn't defined,
-        # then it is a PORO model and should be instantiated with the cached
-        # attachment.
-        def load_record(data)
-          record_class, record_id = data["record"]
-          record_class = Object.const_get(record_class)
+        # Signals the #promote method that it should use backgrounding if
+        # registered.
+        def promote_cached(**options)
+          super(background: true, **options)
+        end
 
-          if respond_to?(:find_record)
-            record   = find_record(record_class, record_id)
-            record ||= record_class.new.tap do |instance|
-              # so that the id is always included in file deletion logs
-              instance.singleton_class.send(:define_method, :id) { record_id }
-            end
+        # Calls the promotion hook if registered and called via #promote_cached,
+        # otherwise promotes synchronously.
+        def promote(background: false, **options)
+          if promote_block && background
+            background_block(promote_block, **options)
           else
-            record = record_class.new
-            record.send(:"#{data["name"]}_data=", data["attachment"])
+            super(**options)
           end
-
-          record
         end
-      end
 
-      module AttacherMethods
-        # Calls the promoting block (if registered) with a serializable data
-        # hash.
-        def _promote(uploaded_file = get, phase: nil, action: phase)
-          if background_promote = shrine_class.opts[:backgrounding_promote]
-            data = self.class.dump(self).merge(
-              "attachment" => uploaded_file.to_json,
-              "action"     => (action.to_s if action),
-              "phase"      => (action.to_s if action), # legacy
-            )
-            instance_exec(data, &background_promote)
-          else
-            super
-          end
+        # Signals the #destroy method that it should use backgrounding if
+        # registered.
+        def destroy_attached(**options)
+          super(background: true, **options)
         end
 
-        # Calls the deleting block (if registered) with a serializable data
-        # hash.
-        def _delete(uploaded_file, phase: nil, action: phase)
-          if background_delete = shrine_class.opts[:backgrounding_delete]
-            data = self.class.dump(self).merge(
-              "attachment" => uploaded_file.to_json,
-              "action"     => (action.to_s if action),
-              "phase"      => (action.to_s if action), # legacy
-            )
-            instance_exec(data, &background_delete)
-            uploaded_file
+        # Calls the destroy hook if registered and called via #destroy_attached,
+        # otherwise destroys synchronously.
+        def destroy(background: false, **options)
+          if destroy_block && background
+            background_block(destroy_block, **options)
           else
-            super
+            super(**options)
           end
         end
 
-        # Dumps all the information about the attacher in a serializable hash
-        # suitable for passing as an argument to background jobs.
-        def dump
-          {
-            "attachment"   => (get && get.to_json),
-            "record"       => [record.class.to_s, record.id.to_s],
-            "name"         => name.to_s,
-            "shrine_class" => shrine_class.name,
-          }
-        end
-
-        # Updates with the new file only if the attachment hasn't changed.
-        def swap(new_file)
-          if self.class.respond_to?(:find_record)
-            reloaded = self.class.find_record(record.class, record.id)
-            return if reloaded.nil?
-
-            attacher   = reloaded.send(:"#{name}_attacher") if reloaded.respond_to?(:"#{name}_attacher")
-            attacher ||= self.class.new(reloaded, name) # Shrine::Attachment is not used
+        private
 
-            return if attacher.get != self.get
+        def background_block(block, **options)
+          if block.arity == 1
+            block.call(self, **options)
+          else
+            instance_exec(**options, &block)
           end
-          super
         end
       end
     end

data/lib/shrine/plugins/cached_attachment_data.rb

@@ -7,25 +7,22 @@ class Shrine
     # [doc/plugins/cached_attachment_data.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/cached_attachment_data.md
     module CachedAttachmentData
       module AttachmentMethods
-        def initialize(*)
+        def included(klass)
           super
 
+          return unless options[:type] == :model
+
           name = attachment_name
 
           define_method :"cached_#{name}_data" do
-            send(:"#{name}_attacher").read_cached
-          end
-
-          define_method :"cached_#{name}_data=" do |value|
-            Shrine.deprecation("Calling #cached_#{name}_data= is deprecated and will be removed in Shrine 3. You should use the original field name: `f.hidden_field :#{name}, value: record.cached_#{name}_data`.")
-            send(:"#{name}_attacher").assign(value)
+            send(:"#{name}_attacher").cached_data
           end
         end
       end
 
       module AttacherMethods
-        def read_cached
-          get.to_json if cached? && changed?
+        def cached_data
+          file.to_json if cached? && changed?
         end
       end
     end

data/lib/shrine/plugins/column.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "json"
+
+class Shrine
+  module Plugins
+    # Documentation lives in [doc/plugins/column.md] on GitHub.
+    #
+    # [doc/plugins/column.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/column.md
+    module Column
+      def self.configure(uploader, **opts)
+        uploader.opts[:column] ||= { serializer: JsonSerializer.new(JSON) }
+        uploader.opts[:column].merge!(opts)
+      end
+
+      module AttacherClassMethods
+        # Initializes the attacher from a data hash/string expected to come
+        # from a database record column.
+        #
+        #     Attacher.from_column('{"id":"...","storage":"...","metadata":{...}}')
+        def from_column(data, **options)
+          attacher = new(**options)
+          attacher.load_column(data)
+          attacher
+        end
+      end
+
+      module AttacherMethods
+        # Column serializer object.
+        attr_reader :column_serializer
+
+        # Allows overriding the default column serializer.
+        def initialize(column_serializer: shrine_class.opts[:column][:serializer], **options)
+          super(**options)
+          @column_serializer = column_serializer
+        end
+
+        # Loads attachment from column data.
+        #
+        #     attacher.file #=> nil
+        #     attacher.load_column('{"id":"...","storage":"...","metadata":{...}}')
+        #     attacher.file #=> #<Shrine::UploadedFile>
+        def load_column(data)
+          load_data(deserialize_column(data))
+        end
+
+        # Returns attacher data as a serialized string (JSON by default).
+        #
+        #     attacher.column_data #=> '{"id":"...","storage":"...","metadata":{...}}'
+        def column_data
+          serialize_column(data)
+        end
+
+        private
+
+        # Converts the column data hash into a string (generates JSON by
+        # default).
+        #
+        #     Attacher.serialize_column({ "id" => "...", "storage" => "...", "metadata" => { ... } })
+        #     #=> '{"id":"...","storage":"...","metadata":{...}}'
+        #
+        #     Attacher.serialize_column(nil)
+        #     #=> nil
+        def serialize_column(data)
+          return data unless column_serializer && data
+
+          column_serializer.dump(data)
+        end
+
+        # Converts the column data string into a hash (parses JSON by default).
+        #
+        #     Attacher.deserialize_column('{"id":"...","storage":"...","metadata":{...}}')
+        #     #=> { "id" => "...", "storage" => "...", "metadata" => { ... } }
+        #
+        #     Attacher.deserialize_column(nil)
+        #     #=> nil
+        def deserialize_column(data)
+          return data unless column_serializer && data
+
+          column_serializer.load(data)
+        end
+      end
+
+      # JSON.dump and JSON.load shouldn't be used with untrusted input, so we
+      # create this wrapper class which calls JSON.generate and JSON.parse
+      # instead.
+      class JsonSerializer
+        def initialize(json)
+          @json = json
+        end
+
+        def dump(data)
+          @json.generate(data)
+        end
+
+        def load(data)
+          @json.parse(data)
+        end
+      end
+    end
+
+    register_plugin(:column, Column)
+  end
+end

data/lib/shrine/plugins/data_uri.rb

@@ -26,17 +26,33 @@ class Shrine
         }.inspect}"
       end
 
-      def self.configure(uploader, opts = {})
-        uploader.opts[:data_uri] ||= { log_subscriber: LOG_SUBSCRIBER }
-        uploader.opts[:data_uri].merge!(opts)
+      def self.load_dependencies(uploader, *)
+        uploader.plugin :validation
+      end
 
-        if uploader.opts[:data_uri][:filename]
-          Shrine.deprecation("The :filename option is deprecated for the data_uri plugin, and will be removed in Shrine 3. Use the infer_extension plugin instead.")
-        end
+      def self.configure(uploader, log_subscriber: LOG_SUBSCRIBER, **opts)
+        uploader.opts[:data_uri] ||= {}
+        uploader.opts[:data_uri].merge!(opts)
 
         # instrumentation plugin integration
-        if uploader.respond_to?(:subscribe)
-          uploader.subscribe(:data_uri, &uploader.opts[:data_uri][:log_subscriber])
+        uploader.subscribe(:data_uri, &log_subscriber) if uploader.respond_to?(:subscribe)
+      end
+
+      module AttachmentMethods
+        def included(klass)
+          super
+
+          return unless options[:type] == :model
+
+          name = attachment_name
+
+          define_method :"#{name}_data_uri=" do |uri|
+            send(:"#{name}_attacher").assign_data_uri(uri)
+          end
+
+          define_method :"#{name}_data_uri" do
+            # form builders require the reader method
+          end
         end
       end
 
@@ -57,10 +73,10 @@ class Shrine
 
         private
 
+        # Creates an IO-like object from parsed data URI.
         def create_data_file(info, filename: nil)
           content_type = info[:content_type] || DEFAULT_CONTENT_TYPE
           content      = info[:base64] ? Base64.decode64(info[:data]) : CGI.unescape(info[:data])
-          filename     = opts[:data_uri][:filename].call(content_type) if opts[:data_uri][:filename]
 
           data_file = Shrine::DataFile.new(content, content_type: content_type, filename: filename)
           info[:data].clear
@@ -68,6 +84,7 @@ class Shrine
           data_file
         end
 
+        # Parses the data URI string and returns parts.
         def parse_data_uri(uri)
           scanner = StringScanner.new(uri)
           scanner.scan(DATA_REGEXP) or raise ParseError, "data URI has invalid format"
@@ -87,20 +104,6 @@ class Shrine
         end
       end
 
-      module AttachmentMethods
-        def initialize(name, **options)
-          super
-
-          define_method :"#{name}_data_uri=" do |uri|
-            send(:"#{name}_attacher").data_uri = uri
-          end
-
-          define_method :"#{name}_data_uri" do
-            send(:"#{name}_attacher").data_uri
-          end
-        end
-      end
-
       module AttacherMethods
         # Handles assignment of a data URI. If the regexp matches, it extracts
         # the content type, decodes it, wrappes it in a StringIO and assigns it.
@@ -110,22 +113,19 @@ class Shrine
           return if uri == "" || uri.nil?
 
           data_file = shrine_class.data_uri(uri)
-          assign(data_file, **options)
+          attach_cached(data_file, **options)
         rescue ParseError => error
-          message = shrine_class.opts[:data_uri][:error_message] || error.message
-          message = message.call(uri) if message.respond_to?(:call)
-          errors.replace [message]
-          @data_uri = uri
+          errors.clear << data_uri_error_messsage(uri, error)
+          false
         end
 
-        # Alias for #assign_data_uri.
-        def data_uri=(uri)
-          assign_data_uri(uri)
-        end
+        private
 
-        # Form builders require the reader as well.
-        def data_uri
-          @data_uri
+        # Generates an error message for failed data URI parse.
+        def data_uri_error_messsage(uri, error)
+          message = shrine_class.opts[:data_uri][:error_message]
+          message = message.call(uri) if message.respond_to?(:call)
+          message || error.message
         end
       end
 
@@ -169,7 +169,4 @@ class Shrine
       @io.string.clear # deallocate string
     end
   end
-
-  Plugins::DataUri.const_set(:DataFile, DataFile)
-  Plugins::DataUri.deprecate_constant(:DataFile)
 end