shrine 2.19.4 → 3.0.0.alpha

data/lib/shrine/plugins/sequel.rb

@@ -8,9 +8,14 @@ class Shrine
     #
     # [doc/plugins/sequel.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/sequel.md
     module Sequel
-      def self.configure(uploader, opts = {})
-        uploader.opts[:sequel_callbacks] = opts.fetch(:callbacks, uploader.opts.fetch(:sequel_callbacks, true))
-        uploader.opts[:sequel_validations] = opts.fetch(:validations, uploader.opts.fetch(:sequel_validations, true))
+      def self.load_dependencies(uploader, **)
+        uploader.plugin :model
+        uploader.plugin :atomic_helpers
+      end
+
+      def self.configure(uploader, **opts)
+        uploader.opts[:sequel] ||= { callbacks: true, validations: true }
+        uploader.opts[:sequel].merge!(opts)
       end
 
       module AttachmentMethods
@@ -21,64 +26,147 @@ class Shrine
 
           name = attachment_name
 
-          if shrine_class.opts[:sequel_validations]
+          if shrine_class.opts[:sequel][:validations]
             define_method :validate do
               super()
-              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[:sequel_callbacks]
+          if shrine_class.opts[:sequel][:callbacks]
             define_method :before_save do
               super()
-              attacher = send(:"#{name}_attacher")
-              attacher.save if attacher.changed?
+              if send(:"#{name}_attacher").changed?
+                send(:"#{name}_attacher").save
+              end
             end
 
             define_method :after_save do
               super()
-              attacher = send(:"#{name}_attacher")
-              db.after_commit { attacher.finalize } if attacher.changed?
+              if send(:"#{name}_attacher").changed?
+                db.after_commit do
+                  send(:"#{name}_attacher").finalize
+                  send(:"#{name}_attacher").sequel_persist
+                end
+              end
             end
 
             define_method :after_destroy do
               super()
-              attacher = send(:"#{name}_attacher")
-              db.after_commit { attacher.destroy } if attacher.read
+              if send(:"#{name}_attacher").attached?
+                db.after_commit do
+                  send(:"#{name}_attacher").destroy_attached
+                end
+              end
             end
           end
-        end
-      end
 
-      module AttacherClassMethods
-        # Needed by the `backgrounding` plugin.
-        def find_record(record_class, record_id)
-          record_class.with_pk(record_id)
+          # reload the attacher on record reload
+          define_method :_refresh do |*args|
+            result = super(*args)
+            instance_variable_set(:"@#{name}_attacher", nil)
+            result
+          end
+          private :_refresh
         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 sequel_atomic_promote(**options, &block)
+          abstract_atomic_promote(sequel_strategies(**options), &block)
+        end
+        alias atomic_promote sequel_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 sequel_atomic_persist(*args, **options, &block)
+          abstract_atomic_persist(*args, sequel_strategies(**options), &block)
+        end
+        alias atomic_persist sequel_atomic_persist
+
+        # Called in the `after_commit` callback after finalization.
+        def sequel_persist
+          sequel_save
+        end
+        alias persist sequel_persist
+
         private
 
-        # Saves the record after assignment, skipping validations.
-        def update(uploaded_file)
-          super
+        # Resolves strategies for atomic promotion and persistence.
+        def sequel_strategies(reload: :lock, persist: :save, **options)
+          reload  = method(:"sequel_#{reload}")  if reload.is_a?(Symbol)
+          persist = method(:"sequel_#{persist}") if persist.is_a?(Symbol)
+
+          { reload: reload, persist: persist, **options }
+        end
+
+        # Implements the "fetch" reload strategy for #sequel_promote.
+        def sequel_fetch
+          yield record.dup.refresh
+        end
+
+        # Implements the "lock" reload strategy for #sequel_promote.
+        def sequel_lock
+          record.db.transaction { yield record.dup.lock! }
+        end
+
+        # Implements the "save" persist strategy for #sequel_promote.
+        def sequel_save
           record.save_changes(validate: false)
         end
 
-        # If the data represents a JSON column with `pg_json` Sequel extension
-        # loaded, a `Sequel::Postgres::JSONHashBase` object will be returned,
+        # Sequel JSON column attribute with `pg_json` Sequel extension loaded
+        # returns a `Sequel::Postgres::JSONHashBase` object will be returned,
         # which we convert into a Hash.
-        def convert_after_read(value)
-          sequel_json_column? ? value.to_hash : super
+        def deserialize_column(data)
+          sequel_json_column? ? data&.to_hash : super
+        end
+
+        # Sequel JSON column attribute with `pg_json` Sequel extension loaded
+        # can receive a Hash object, so there is no need to generate a JSON
+        # string.
+        def serialize_column(data)
+          sequel_json_column? ? data : super
         end
 
         # Returns true if the data attribute represents a JSON or JSONB column.
         def sequel_json_column?
           return false unless record.is_a?(::Sequel::Model)
-          return false unless column = record.class.db_schema[data_attribute]
+          return false unless column = record.class.db_schema[attribute]
 
           [:json, :jsonb].include?(column[:type])
         end

data/lib/shrine/plugins/signature.rb

@@ -15,14 +15,9 @@ class Shrine
         }.inspect}"
       end
 
-      def self.configure(uploader, opts = {})
-        uploader.opts[:signature] ||= { log_subscriber: LOG_SUBSCRIBER }
-        uploader.opts[:signature].merge!(opts)
-
+      def self.configure(uploader, log_subscriber: LOG_SUBSCRIBER)
         # instrumentation plugin integration
-        if uploader.respond_to?(:subscribe)
-          uploader.subscribe(:signature, &uploader.opts[:signature][:log_subscriber])
-        end
+        uploader.subscribe(:signature, &log_subscriber) if uploader.respond_to?(:subscribe)
       end
 
       module ClassMethods

data/lib/shrine/plugins/store_dimensions.rb

@@ -13,24 +13,22 @@ class Shrine
         }.inspect}"
       end
 
-      def self.configure(uploader, opts = {})
-        uploader.opts[:store_dimensions] ||= { analyzer: :fastimage, on_error: :ignore, log_subscriber: LOG_SUBSCRIBER }
+      def self.configure(uploader, log_subscriber: LOG_SUBSCRIBER, **opts)
+        uploader.opts[:store_dimensions] ||= { analyzer: :fastimage, on_error: :warn }
         uploader.opts[:store_dimensions].merge!(opts)
 
         # resolve error strategy
-        case uploader.opts[:store_dimensions][:on_error]
-        when :fail
-          uploader.opts[:store_dimensions][:on_error] = -> (error) { fail error }
-        when :warn
-          uploader.opts[:store_dimensions][:on_error] = -> (error) { Shrine.warn "Error occurred when attempting to extract image dimensions: #{error.inspect}" }
-        when :ignore
-          uploader.opts[:store_dimensions][:on_error] = -> (error) { }
-        end
+        uploader.opts[:store_dimensions][:on_error] =
+          case uploader.opts[:store_dimensions][:on_error]
+          when :fail   then -> (error) { fail error }
+          when :warn   then -> (error) { Shrine.warn "Error occurred when attempting to extract image dimensions: #{error.inspect}" }
+          when :ignore then -> (error) { }
+          else
+            uploader.opts[:store_dimensions][:on_error]
+          end
 
         # instrumentation plugin integration
-        if uploader.respond_to?(:subscribe)
-          uploader.subscribe(:image_dimensions, &uploader.opts[:store_dimensions][:log_subscriber])
-        end
+        uploader.subscribe(:image_dimensions, &log_subscriber) if uploader.respond_to?(:subscribe)
       end
 
       module ClassMethods
@@ -76,23 +74,11 @@ class Shrine
 
       module InstanceMethods
         # We update the metadata with "width" and "height".
-        def extract_metadata(io, context = {})
-          width, height = extract_dimensions(io)
+        def extract_metadata(io, **options)
+          width, height = self.class.extract_dimensions(io)
 
           super.merge!("width" => width, "height" => height)
         end
-
-        private
-
-        # Extracts dimensions using the specified analyzer.
-        def extract_dimensions(io)
-          self.class.extract_dimensions(io)
-        end
-
-        # Returns a hash of built-in dimensions analyzers.
-        def dimensions_analyzers
-          self.class.dimensions_analyzers
-        end
       end
 
       module FileMethods

data/lib/shrine/plugins/upload_endpoint.rb

@@ -146,7 +146,7 @@ class Shrine
     # keys, which is to be passed to `Shrine#upload`. Calls
     # `:upload_context` option if given.
     def get_context(request)
-      context = { action: :upload, phase: :upload, request: request }
+      context = { action: :upload }
       context.merge! @upload_context.call(request) if @upload_context
       context
     end
@@ -166,26 +166,29 @@ class Shrine
     # a Rack response triple - an array consisting of a status number, hash
     # of headers, and a body enumerable. If a `:rack_response` option is
     # given, calls that instead.
-    def make_response(object, request)
+    def make_response(uploaded_file, request)
       if @rack_response
-        @rack_response.call(object, request)
+        @rack_response.call(uploaded_file, request)
       else
         if @url
-          url = case @url
-                when true then object.url
-                when Hash then object.url(**@url)
-                else           @url.call(object, request)
-                end
-
-          body = { data: object, url: url }.to_json
+          url  = resolve_url(uploaded_file, request)
+          body = { data: uploaded_file, url: url }.to_json
         else
-          body = object.to_json
+          body = uploaded_file.to_json
         end
 
         [200, { "Content-Type" => CONTENT_TYPE_JSON }, [body]]
       end
     end
 
+    def resolve_url(uploaded_file, request)
+      case @url
+      when true then uploaded_file.url
+      when Hash then uploaded_file.url(**@url)
+      else           @url.call(uploaded_file, request)
+      end
+    end
+
     def verify_size!(file, request)
       error!(413, "Upload Too Large") if @max_size && file.size > @max_size
     end
@@ -212,8 +215,4 @@ class Shrine
       @shrine_class.new(@storage_key)
     end
   end
-
-  # backwards compatibility
-  Plugins::UploadEndpoint.const_set(:App, UploadEndpoint)
-  Plugins::UploadEndpoint.deprecate_constant(:App)
 end

data/lib/shrine/plugins/upload_options.rb

@@ -12,18 +12,19 @@ class Shrine
       end
 
       module InstanceMethods
-        def put(io, context)
-          upload_options = get_upload_options(io, context)
-          context = { upload_options: upload_options }.merge(context)
-          super
+        def _upload(io, **options)
+          upload_options = get_upload_options(io, options)
+
+          super(io, **options, upload_options: upload_options)
         end
 
         private
 
-        def get_upload_options(io, context)
-          options = opts[:upload_options][storage_key]
-          options = options.call(io, context) if options.respond_to?(:call)
-          options
+        def get_upload_options(io, options)
+          upload_options = opts[:upload_options][storage_key] || {}
+          upload_options = upload_options.call(io, options) if upload_options.respond_to?(:call)
+          upload_options = upload_options.merge(options[:upload_options]) if options[:upload_options]
+          upload_options
         end
       end
     end

data/lib/shrine/plugins/url_options.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class Shrine
+  module Plugins
+    # Documentation lives in [doc/plugins/url_options.md] on GitHub.
+    #
+    # [doc/plugins/url_options.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/url_options.md
+    module UrlOptions
+      def self.configure(uploader, **options)
+        uploader.opts[:url_options] ||= {}
+        uploader.opts[:url_options].merge!(options)
+      end
+
+      module FileMethods
+        def url(**options)
+          default_options = url_options(options)
+
+          super(**default_options, **options)
+        end
+
+        private
+
+        def url_options(options)
+          default_options = shrine_class.opts[:url_options][storage_key]
+          default_options = default_options.call(self, options) if default_options.respond_to?(:call)
+          default_options || {}
+        end
+      end
+    end
+
+    register_plugin(:url_options, UrlOptions)
+  end
+end

data/lib/shrine/plugins/validation.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+class Shrine
+  module Plugins
+    module Validation
+      module AttacherClassMethods
+        # Block that is executed in context of Shrine::Attacher during
+        # validation. Example:
+        #
+        #     Shrine::Attacher.validate do
+        #       if file.size > 5*1024*1024
+        #         errors << "is too big (max is 5 MB)"
+        #       end
+        #     end
+        def validate(&block)
+          private define_method(:validate_block, &block)
+        end
+      end
+
+      module AttacherMethods
+        # Returns an array of validation errors created on file assignment in
+        # the `Attacher.validate` block.
+        attr_reader :errors
+
+        # Initializes validation errors to an empty array.
+        def initialize(**options)
+          super
+          @errors = []
+        end
+
+        # Registers options that will be passed to validation.
+        def validate_options(options = nil)
+          if options
+            @validate_options ||= {}
+            @validate_options.merge!(options)
+          else
+            defined?(@validate_options) ? @validate_options : {}
+          end
+        end
+
+        # Leaves out :validate option when calling `Shrine.upload`.
+        def upload(*args, validate: nil, **options)
+          super(*args, **options)
+        end
+
+        # Performs validations after changing the file.
+        def change(file, validate: nil, **)
+          result = super
+          validation(validate)
+          result
+        end
+
+        # Runs the validation defined by `Attacher.validate`.
+        def validate(**options)
+          errors.clear
+          _validate(**options) if attached?
+        end
+
+        private
+
+        # Calls validation appropriately based on the :validate value.
+        def validation(argument)
+          case argument
+          when Hash  then validate(argument)
+          when false then errors.clear # skip validation
+          else            validate
+          end
+        end
+
+        # Calls #validate_block, passing it accepted parameters.
+        def _validate(**options)
+          if method(:validate_block).arity.zero?
+            validate_block
+          else
+            validate_block(**validate_options, **options)
+          end
+        end
+
+        # Overridden by the `Attacher.validate` block.
+        def validate_block(**options)
+        end
+      end
+    end
+
+    register_plugin(:validation, Validation)
+  end
+end