shrine 2.19.4 → 3.4.0

data/lib/shrine/plugins/included.rb

@@ -2,18 +2,18 @@
 
 class Shrine
   module Plugins
-    # Documentation lives in [doc/plugins/included.md] on GitHub.
-    #
-    # [doc/plugins/included.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/included.md
+    # Documentation can be found on https://shrinerb.com/docs/plugins/included
     module Included
       def self.configure(uploader, &block)
-        uploader.opts[:included_block] = block
+        uploader.opts[:included] ||= {}
+        uploader.opts[:included][:block] = block
       end
 
       module AttachmentMethods
-        def included(model)
+        def included(klass)
           super
-          model.instance_exec(@name, &shrine_class.opts[:included_block])
+
+          klass.instance_exec(@name, &shrine_class.opts[:included][:block])
         end
       end
     end

data/lib/shrine/plugins/infer_extension.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
+require "pathname"
+
 class Shrine
   module Plugins
-    # Documentation lives in [doc/plugins/infer_extension.md] on GitHub.
-    #
-    # [doc/plugins/infer_extension.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/infer_extension.md
+    # Documentation can be found on https://shrinerb.com/docs/plugins/infer_extension
     module InferExtension
       LOG_SUBSCRIBER = -> (event) do
         Shrine.logger.info "Extension (#{event.duration}ms) – #{{
@@ -13,14 +13,12 @@ class Shrine
         }.inspect}"
       end
 
-      def self.configure(uploader, opts = {})
-        uploader.opts[:infer_extension] ||= { inferrer: :mime_types, force: false, log_subscriber: LOG_SUBSCRIBER }
+      def self.configure(uploader, log_subscriber: LOG_SUBSCRIBER, **opts)
+        uploader.opts[:infer_extension] ||= { inferrer: :mini_mime }
         uploader.opts[:infer_extension].merge!(opts)
 
         # instrumentation plugin integration
-        if uploader.respond_to?(:subscribe)
-          uploader.subscribe(:extension, &uploader.opts[:infer_extension][:log_subscriber])
-        end
+        uploader.subscribe(:extension, &log_subscriber) if uploader.respond_to?(:subscribe)
       end
 
       module ClassMethods
@@ -53,22 +51,17 @@ class Shrine
       end
 
       module InstanceMethods
+        private
+
         def basic_location(io, metadata:)
-          location = super
-          current_extension = File.extname(location)
+          location = Pathname(super)
 
-          if current_extension.empty? || opts[:infer_extension][:force]
-            inferred_extension = infer_extension(metadata["mime_type"])
-            location = location.chomp(current_extension) << inferred_extension unless inferred_extension.empty?
+          if location.extname.empty? || opts[:infer_extension][:force]
+            inferred_extension = self.class.infer_extension(metadata["mime_type"])
+            location = location.sub_ext(inferred_extension) if inferred_extension
           end
 
-          location
-        end
-
-        private
-
-        def infer_extension(mime_type)
-          self.class.infer_extension(mime_type).to_s
+          location.to_s
         end
       end
 

data/lib/shrine/plugins/instrumentation.rb

@@ -2,25 +2,20 @@
 
 class Shrine
   module Plugins
-    # Documentation lives in [doc/plugins/instrumentation.md] on GitHub.
-    #
-    # [doc/plugins/instrumentation.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/instrumentation.md
+    # Documentation can be found on https://shrinerb.com/docs/plugins/instrumentation
     module Instrumentation
-      EVENTS = %i[upload download exists delete metadata].freeze
+      EVENTS = %i[upload download open exists delete metadata].freeze
 
       # We use a proc in order to be able identify listeners.
       LOG_SUBSCRIBER = -> (event) { LogSubscriber.call(event) }
 
-      def self.configure(uploader, opts = {})
-        uploader.opts[:instrumentation] ||= { log_subscriber: LOG_SUBSCRIBER, log_events: EVENTS }
+      def self.configure(uploader, log_subscriber: LOG_SUBSCRIBER, **opts)
+        uploader.opts[:instrumentation] ||= { log_events: EVENTS, subscribers: {} }
         uploader.opts[:instrumentation].merge!(opts)
         uploader.opts[:instrumentation][:notifications] ||= ::ActiveSupport::Notifications
 
-        # we assign it to the top-level so that it's duplicated on subclassing
-        uploader.opts[:instrumentation_subscribers] ||= Hash.new { |h, k| h[k] = [] }
-
         uploader.opts[:instrumentation][:log_events].each do |event_name|
-          uploader.subscribe(event_name, &uploader.opts[:instrumentation][:log_subscriber])
+          uploader.subscribe(event_name, &log_subscriber)
         end
       end
 
@@ -48,12 +43,13 @@ class Shrine
         #     end
         def subscribe(event_name, &subscriber)
           return if subscriber.nil?
-          return if subscribers[event_name].include?(subscriber)
+          return if subscribers[event_name]&.include?(subscriber)
 
           notifications.subscribe("#{event_name}.shrine") do |event|
             subscriber.call(event) if event[:uploader] <= self
           end
 
+          subscribers[event_name] ||= []
           subscribers[event_name] << subscriber
         end
 
@@ -63,12 +59,8 @@ class Shrine
           Notifications.new(opts[:instrumentation][:notifications])
         end
 
-        def log_subscriber
-          opts[:instrumentation][:log_subscriber]
-        end
-
         def subscribers
-          opts[:instrumentation_subscribers]
+          opts[:instrumentation][:subscribers]
         end
       end
 
@@ -76,57 +68,68 @@ class Shrine
         private
 
         # Sends a `upload.shrine` event.
-        def copy(io, context)
-          self.class.instrument(
-            :upload,
+        def _upload(io, location:, metadata:, upload_options: {}, **options)
+          self.class.instrument(:upload, {
             storage: storage_key,
-            location: context[:location],
+            location: location,
             io: io,
-            upload_options: context[:upload_options] || {},
-            options: context,
-          ) { super }
+            upload_options: upload_options,
+            metadata: metadata,
+            options: options,
+          }) { super }
         end
 
         # Sends a `metadata.shrine` event.
-        def get_metadata(io, context)
-          return super if io.is_a?(UploadedFile) && context[:metadata] != true || context[:metadata] == false
+        def get_metadata(io, metadata: nil, **options)
+          return super if io.is_a?(UploadedFile) && metadata != true || metadata == false
 
-          self.class.instrument(
-            :metadata,
+          self.class.instrument(:metadata, {
             storage: storage_key,
             io: io,
-            options: context,
-          ) { super }
+            options: options,
+          }) { super }
         end
       end
 
       module FileMethods
         # Sends a `download.shrine` event.
-        def open(**options)
-          shrine_class.instrument(
-            :download,
-            storage: storage_key.to_sym,
+        def stream(destination, **options)
+          return super if opened?
+
+          shrine_class.instrument(:download, {
+            storage: storage_key,
             location: id,
             download_options: options,
-          ) { super }
+          }) { super(destination, **options, instrument: false) }
         end
 
         # Sends a `exists.shrine` event.
         def exists?
-          shrine_class.instrument(
-            :exists,
-            storage: storage_key.to_sym,
+          shrine_class.instrument(:exists, {
+            storage: storage_key,
             location: id,
-          ) { super }
+          }) { super }
         end
 
         # Sends a `delete.shrine` event.
         def delete
-          shrine_class.instrument(
-            :delete,
-            storage: storage_key.to_sym,
+          shrine_class.instrument(:delete, {
+            storage: storage_key,
+            location: id,
+          }) { super }
+        end
+
+        private
+
+        # Sends an `open.shrine` event.
+        def _open(instrument: true, **options)
+          return super(**options) unless instrument
+
+          shrine_class.instrument(:open, {
+            storage: storage_key,
             location: id,
-          ) { super }
+            download_options: options,
+          }) { super(**options) }
         end
       end
 
@@ -255,6 +258,15 @@ class Shrine
           )}"
         end
 
+        def on_open(event)
+          log "Open (#{event.duration}ms) – #{format(
+            storage:          event[:storage],
+            location:         event[:location],
+            download_options: event[:download_options],
+            uploader:         event[:uploader],
+          )}"
+        end
+
         def on_exists(event)
           log "Exists (#{event.duration}ms) – #{format(
             storage:  event[:storage],

data/lib/shrine/plugins/keep_files.rb

@@ -2,23 +2,11 @@
 
 class Shrine
   module Plugins
-    # Documentation lives in [doc/plugins/keep_files.md] on GitHub.
-    #
-    # [doc/plugins/keep_files.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/keep_files.md
+    # Documentation can be found on https://shrinerb.com/docs/plugins/keep_files
     module KeepFiles
-      def self.configure(uploader, opts = {})
-        keep_files = (uploader.opts[:keep_files] ||= [])
-        opts[:destroyed] ? keep_files << :destroyed : keep_files.delete(:destroyed) if opts.key?(:destroyed)
-        opts[:replaced] ? keep_files << :replaced : keep_files.delete(:replaced) if opts.key?(:replaced)
-      end
-
       module AttacherMethods
-        def replace
-          super unless shrine_class.opts[:keep_files].include?(:replaced)
-        end
-
-        def destroy
-          super unless shrine_class.opts[:keep_files].include?(:destroyed)
+        def destroy?
+          false
         end
       end
     end

data/lib/shrine/plugins/metadata_attributes.rb

@@ -2,37 +2,46 @@
 
 class Shrine
   module Plugins
-    # Documentation lives in [doc/plugins/metadata_attributes.md] on GitHub.
-    #
-    # [doc/plugins/metadata_attributes.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/metadata_attributes.md
+    # Documentation can be found on https://shrinerb.com/docs/plugins/metadata_attributes
     module MetadataAttributes
-      def self.configure(uploader, mappings = {})
-        uploader.opts[:metadata_attributes_mappings] ||= {}
-        uploader.opts[:metadata_attributes_mappings].merge!(mappings)
+      def self.load_dependencies(uploader, *)
+        uploader.plugin :entity
+      end
+
+      def self.configure(uploader, **opts)
+        uploader.opts[:metadata_attributes] ||= {}
+        uploader.opts[:metadata_attributes].merge!(opts)
       end
 
       module AttacherClassMethods
-        def metadata_attributes(mappings)
-          shrine_class.opts[:metadata_attributes_mappings].merge!(mappings)
+        def metadata_attributes(mappings = nil)
+          if mappings
+            shrine_class.opts[:metadata_attributes].merge!(mappings)
+          else
+            shrine_class.opts[:metadata_attributes]
+          end
         end
       end
 
       module AttacherMethods
-        def assign(value, **options)
-          super
-          cached_file = get
+        def column_values
+          super.merge(metadata_attributes)
+        end
 
-          shrine_class.opts[:metadata_attributes_mappings].each do |source, destination|
-            attribute_name = destination.is_a?(Symbol) ? :"#{name}_#{destination}" : :"#{destination}"
+        private
 
-            next unless record.respond_to?(:"#{attribute_name}=")
+        def metadata_attributes
+          values = {}
 
-            if cached_file
-              record.send(:"#{attribute_name}=", cached_file.metadata[source.to_s])
-            else
-              record.send(:"#{attribute_name}=", nil)
-            end
+          self.class.metadata_attributes.each do |source, destination|
+            metadata_attribute = destination.is_a?(Symbol) ? :"#{name}_#{destination}" : :"#{destination}"
+
+            next unless record.respond_to?(metadata_attribute)
+
+            values[metadata_attribute] = file && file.metadata[source.to_s]
           end
+
+          values
         end
       end
     end

data/lib/shrine/plugins/mirroring.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+class Shrine
+  module Plugins
+    # Documentation can be found on https://shrinerb.com/docs/plugins/mirroring
+    module Mirroring
+      def self.configure(uploader, **opts)
+        uploader.opts[:mirroring] ||= { upload: true, delete: true }
+        uploader.opts[:mirroring].merge!(opts)
+
+        fail Error, ":mirror option is required for mirroring plugin" unless uploader.opts[:mirroring][:mirror]
+      end
+
+      module ClassMethods
+        def mirrors(storage_key = nil)
+          if storage_key
+            mirrors = opts[:mirroring][:mirror][storage_key]
+
+            fail Error, "no mirrors registered for storage #{storage_key.inspect}" unless mirrors
+
+            Array(mirrors)
+          else
+            opts[:mirroring][:mirror]
+          end
+        end
+
+        def mirror_upload_block(&block)
+          if block
+            opts[:mirroring][:upload_block] = block
+          else
+            opts[:mirroring][:upload_block]
+          end
+        end
+
+        def mirror_delete_block(&block)
+          if block
+            opts[:mirroring][:delete_block] = block
+          else
+            opts[:mirroring][:delete_block]
+          end
+        end
+
+        def mirror_upload?
+          opts[:mirroring][:upload]
+        end
+
+        def mirror_delete?
+          opts[:mirroring][:delete]
+        end
+      end
+
+      module InstanceMethods
+        # Mirrors upload to other mirror storages.
+        def upload(io, mirror: true, **options)
+          file = super(io, **options)
+          file.trigger_mirror_upload(**options) if mirror
+          file
+        end
+      end
+
+      module FileMethods
+        # Mirrors upload if mirrors are defined. Calls mirror block if
+        # registered, otherwise mirrors synchronously.
+        def trigger_mirror_upload(**options)
+          return unless shrine_class.mirrors[storage_key] && shrine_class.mirror_upload?
+
+          if shrine_class.mirror_upload_block
+            mirror_upload_background(**options)
+          else
+            mirror_upload(**options)
+          end
+        end
+
+        # Calls mirror upload block.
+        def mirror_upload_background(**options)
+          fail Error, "mirror upload block is not registered" unless shrine_class.mirror_upload_block
+
+          shrine_class.mirror_upload_block.call(self, **options)
+        end
+
+        # Uploads the file to each mirror storage.
+        def mirror_upload(**options)
+          previously_opened = opened?
+
+          each_mirror do |mirror|
+            rewind if opened?
+
+            shrine_class.upload(self, mirror, **options, location: id, close: false, action: :mirror)
+          end
+        ensure
+          if opened? && !previously_opened
+            close
+            @io = nil
+          end
+        end
+
+        # Mirrors delete to other mirror storages.
+        def delete(mirror: true)
+          result = super()
+          trigger_mirror_delete if mirror
+          result
+        end
+
+        # Mirrors delete if mirrors are defined. Calls mirror block if
+        # registered, otherwise mirrors synchronously.
+        def trigger_mirror_delete
+          return unless shrine_class.mirrors[storage_key] && shrine_class.mirror_delete?
+
+          if shrine_class.mirror_delete_block
+            mirror_delete_background
+          else
+            mirror_delete
+          end
+        end
+
+        # Calls mirror delete block.
+        def mirror_delete_background
+          fail Error, "mirror delete block is not registered" unless shrine_class.mirror_delete_block
+
+          shrine_class.mirror_delete_block.call(self)
+        end
+
+        # Deletes the file from each mirror storage.
+        def mirror_delete
+          each_mirror do |mirror|
+            self.class.new(id: id, storage: mirror).delete
+          end
+        end
+
+        private
+
+        # Iterates over mirror storages.
+        def each_mirror(&block)
+          mirrors = shrine_class.mirrors(storage_key)
+          mirrors.map(&block)
+        end
+      end
+    end
+
+    register_plugin(:mirroring, Mirroring)
+  end
+end

data/lib/shrine/plugins/model.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+class Shrine
+  module Plugins
+    # Documentation can be found on https://shrinerb.com/docs/plugins/model
+    module Model
+      def self.load_dependencies(uploader, **)
+        uploader.plugin :entity
+      end
+
+      def self.configure(uploader, **opts)
+        uploader.opts[:model] ||= { cache: true }
+        uploader.opts[:model].merge!(opts)
+      end
+
+      module AttachmentMethods
+        # Allows disabling model behaviour:
+        #
+        #     Shrine::Attachment(:image)               # model (default)
+        #     Shrine::Attachment(:image, model: false) # entity
+        def initialize(name, model: true, **options)
+          super(name, **options)
+          @model = model
+        end
+
+        # We define model methods only on inclusion. This gives other plugins
+        # the ability to disable model behaviour for entity classes. In this
+        # case we want to skip defining model methods as well.
+        def included(klass)
+          super
+          define_model_methods(@name) if model?
+        end
+
+        private
+
+        # Defines attachment setter and enhances the copy constructor.
+        def define_model_methods(name)
+          super if defined?(super)
+
+          define_method :"#{name}=" do |value|
+            send(:"#{name}_attacher").model_assign(value)
+          end
+
+          define_method :"#{name}_changed?" do
+            send(:"#{name}_attacher").changed?
+          end
+
+          # The copy constructor that's called on #dup and #clone.
+          define_method :initialize_copy do |other|
+            super(other)
+            instance_variable_set(:"@#{name}_attacher", instance_variable_get(:"@#{name}_attacher")&.dup)
+            self
+          end
+          private :initialize_copy
+        end
+
+        # Memoizes the attacher instance into an instance variable.
+        def attacher(record, **options)
+          return super unless model?
+
+          if !record.instance_variable_get(:"@#{@name}_attacher") || options.any?
+            attacher = class_attacher(**options)
+            attacher.load_model(record, @name)
+
+            record.instance_variable_set(:"@#{@name}_attacher", attacher)
+          else
+            record.instance_variable_get(:"@#{@name}_attacher")
+          end
+        end
+
+        def model?
+          @model
+        end
+      end
+
+      module AttacherClassMethods
+        # Initializes itself from a model instance and attachment name.
+        #
+        #     photo.image_data #=> "{...}" # a file is attached
+        #
+        #     attacher = Attacher.from_model(photo, :image)
+        #     attacher.file #=> #<Shrine::UploadedFile>
+        def from_model(record, name, **options)
+          attacher = new(**options)
+          attacher.load_model(record, name)
+          attacher
+        end
+      end
+
+      module AttacherMethods
+        def initialize(model_cache: shrine_class.opts[:model][:cache], **options)
+          super(**options)
+          @model_cache = model_cache
+          @model       = nil
+        end
+
+        # Saves record and name and initializes attachment from the model
+        # attribute. Called from `Attacher.from_model`.
+        def load_model(record, name)
+          set_model(record, name)
+          read
+        end
+
+        # Saves record and name without loading attachment from the model
+        # attribute.
+        def set_model(record, name)
+          set_entity(record, name)
+          @model = true
+        end
+
+        # Called by the attachment attribute setter on the model.
+        def model_assign(value, **options)
+          if model_cache?
+            assign(value, **options)
+          else
+            attach(value, **options)
+          end
+        end
+
+        # Writes uploaded file data into the model.
+        def set(*)
+          result = super
+          write if model?
+          result
+        end
+
+        # Writes the attachment data into the model attribute.
+        def write
+          column_values.each do |name, value|
+            write_attribute(name, value)
+          end
+        end
+
+        private
+
+        # Writes given value into the model attribute.
+        def write_attribute(name = attribute, value)
+          record.public_send(:"#{name}=", value)
+        end
+
+        # Returns whether assigned files should be uploaded to/loaded from
+        # temporary storage.
+        def model_cache?
+          @model_cache
+        end
+
+        # Returns whether the attacher is being backed by a model instance.
+        # This allows users to still use the attacher with an entity instance
+        # or without any record instance.
+        def model?
+          @model
+        end
+      end
+    end
+
+    register_plugin(:model, Model)
+  end
+end

data/lib/shrine/plugins/module_include.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
+Shrine.deprecation("The module_include plugin is deprecated and will be removed in Shrine 4. Override core classes directly instead.")
+
 class Shrine
   module Plugins
-    # Documentation lives in [doc/plugins/module_include.md] on GitHub.
-    #
-    # [doc/plugins/module_include.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/module_include.md
+    # Documentation can be found on https://shrinerb.com/docs/plugins/module_include
     module ModuleInclude
       module ClassMethods
         def attachment_module(mod = nil, &block)