shrine 2.18.1 → 2.19.0

data/lib/shrine/plugins/derivation_endpoint.rb

@@ -12,13 +12,21 @@ class Shrine
     #
     # [doc/plugins/derivation_endpoint.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/derivation_endpoint.md
     module DerivationEndpoint
+      LOG_SUBSCRIBER = -> (event) do
+        Shrine.logger.info "Derivation (#{event.duration}ms) – #{{
+          name:     event[:name],
+          args:     event[:args],
+          uploader: event[:uploader],
+        }.inspect}"
+      end
+
       def self.load_dependencies(uploader, opts = {})
         uploader.plugin :rack_response
         uploader.plugin :_urlsafe_serialization
       end
 
       def self.configure(uploader, opts = {})
-        uploader.opts[:derivation_endpoint_options] ||= {}
+        uploader.opts[:derivation_endpoint_options] ||= { log_subscriber: LOG_SUBSCRIBER }
         uploader.opts[:derivation_endpoint_options].merge!(opts)
 
         uploader.opts[:derivation_endpoint_derivations] ||= {}
@@ -26,6 +34,11 @@ class Shrine
         unless uploader.opts[:derivation_endpoint_options][:secret_key]
           fail Error, "must provide :secret_key option to derivation_endpoint plugin"
         end
+
+        # instrumentation plugin integration
+        if uploader.respond_to?(:subscribe)
+          uploader.subscribe(:derivation, &uploader.opts[:derivation_endpoint_options][:log_subscriber])
+        end
       end
 
       module ClassMethods
@@ -192,7 +205,7 @@ class Shrine
     option :upload_options,              default: -> { {} }
     option :upload_redirect,             default: -> { false }
     option :upload_redirect_url_options, default: -> { {} }
-    option :upload_storage,              default: -> { source.storage_key.to_sym }
+    option :upload_storage,              default: -> { default_upload_storage }
     option :version
 
     # Retrieves the value of a derivation option.
@@ -245,6 +258,11 @@ class Shrine
       [directory, filename].join("/")
     end
 
+    # The source uploaded file storage is the default derivative storage.
+    def default_upload_storage
+      source.storage_key.to_sym
+    end
+
     # Allows caching for 1 year or until the URL expires.
     def default_cache_control
       if option(:expires_in)
@@ -504,7 +522,7 @@ class Shrine
 
         [302, { "Location" => redirect_url }, []]
       else
-        if derivative
+        if derivative && File.exist?(derivative.path)
           file_response(derivative, env)
         else
           uploaded_file.open(**upload_open_options)
@@ -526,7 +544,6 @@ class Shrine
       if Rack.release > "2"
         server.serving(Rack::Request.new(env), path)
       else
-        server = server.dup
         server.path = path
         server.serving(env)
       end
@@ -567,23 +584,43 @@ class Shrine
 
     private
 
-    # Calls the derivation block with the source file and derivation arguments.
-    # If a file object is given, passes that as the source file, otherwise
-    # downloads the source uploaded file.
+    # Determines how to call the derivation block. If a file object is given,
+    # passes that as the source file, otherwise downloads the source uploaded
+    # file.
     def generate(file)
       if download
         with_downloaded(file) do |file|
           if include_uploaded_file
-            uploader.instance_exec(file, source, *args, &derivation_block)
+            derive(file, source, *args)
           else
-            uploader.instance_exec(file, *args, &derivation_block)
+            derive(file, *args)
           end
         end
       else
-        uploader.instance_exec(source, *args, &derivation_block)
+        derive(source, *args)
       end
     end
 
+    # Calls the derivation block.
+    def derive(*args)
+      instrument_derivation do
+        uploader.instance_exec(*args, &derivation_block)
+      end
+    end
+
+    # Sends a `derivation.shrine` event for instrumentation plugin.
+    def instrument_derivation(&block)
+      return yield unless shrine_class.respond_to?(:instrument)
+
+      shrine_class.instrument(
+        :derivation,
+        name:       derivation.name,
+        args:       derivation.args,
+        derivation: derivation,
+        &block
+      )
+    end
+
     # Massages the derivation result, ensuring it's opened in binary mode,
     # rewinded and flushed to disk.
     def normalize(derivative)
@@ -644,9 +681,7 @@ class Shrine
       with_derivative(derivative) do |uploadable|
         uploader.upload uploadable,
           location:       upload_location,
-          upload_options: upload_options,
-          delete:         false, # disable delete_raw plugin
-          move:           false # disable moving plugin
+          upload_options: upload_options
       end
     end
 
@@ -654,9 +689,14 @@ class Shrine
 
     def with_derivative(derivative)
       if derivative
-        # we want to keep the provided file open and rewinded
-        File.open(derivative.path, binmode: true) do |file|
-          yield file
+        begin
+          # we want to keep the provided file open and rewinded
+          File.open(derivative.path, binmode: true) do |file|
+            yield file
+          end
+        ensure
+          # close the file handler if the file was deleted during upload
+          derivative.close if !File.exist?(derivative.path)
         end
       else
         # generate the derivative and delete it afterwards
@@ -681,18 +721,12 @@ class Shrine
     # Returns a Shrine::UploadedFile object pointing to the uploaded derivation
     # result it exists on the storage.
     def call
-      if storage.exists?(upload_location)
-        shrine_class::UploadedFile.new(
-          "storage" => upload_storage.to_s,
-          "id"      => upload_location,
-        )
-      end
-    end
-
-    private
+      uploaded_file = shrine_class::UploadedFile.new(
+        "storage" => upload_storage.to_s,
+        "id"      => upload_location,
+      )
 
-    def storage
-      shrine_class.find_storage(upload_storage)
+      uploaded_file if uploaded_file.exists?
     end
   end
 

data/lib/shrine/plugins/determine_mime_type.rb

@@ -6,34 +6,47 @@ class Shrine
     #
     # [doc/plugins/determine_mime_type.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/determine_mime_type.md
     module DetermineMimeType
+      LOG_SUBSCRIBER = -> (event) do
+        Shrine.logger.info "MIME Type (#{event.duration}ms) – #{{
+          io:       event[:io].class,
+          uploader: event[:uploader],
+        }.inspect}"
+      end
+
       def self.configure(uploader, opts = {})
         if opts[:analyzer] == :default
           Shrine.deprecation("The :default analyzer of the determine_mime_type plugin has been renamed to :content_type. The :default alias will not be supported in Shrine 3.")
           opts = opts.merge(analyzer: :content_type)
         end
 
-        uploader.opts[:mime_type_analyzer] = opts.fetch(:analyzer, uploader.opts.fetch(:mime_type_analyzer, :file))
-        uploader.opts[:mime_type_analyzer_options] = opts.fetch(:analyzer_options, uploader.opts.fetch(:mime_type_analyzer_options, {}))
+        uploader.opts[:determine_mime_type] ||= { analyzer: :file, analyzer_options: {}, log_subscriber: LOG_SUBSCRIBER }
+        uploader.opts[:determine_mime_type].merge!(opts)
+
+        # instrumentation plugin integration
+        if uploader.respond_to?(:subscribe)
+          uploader.subscribe(:mime_type, &uploader.opts[:determine_mime_type][:log_subscriber])
+        end
       end
 
       module ClassMethods
         # Determines the MIME type of the IO object by calling the specified
         # analyzer.
         def determine_mime_type(io)
-          analyzer = opts[:mime_type_analyzer]
+          analyzer = opts[:determine_mime_type][:analyzer]
 
           analyzer = mime_type_analyzer(analyzer) if analyzer.is_a?(Symbol)
           args     = if analyzer.is_a?(Proc)
               [io, mime_type_analyzers].take(analyzer.arity.abs)
             else
-              [io, opts[:mime_type_analyzer_options]]
+              [io, opts[:determine_mime_type][:analyzer_options]]
             end
 
-          mime_type = analyzer.call(*args)
+          mime_type = instrument_mime_type(io) { analyzer.call(*args) }
           io.rewind
 
           mime_type
         end
+        alias mime_type determine_mime_type
 
         # Returns a hash of built-in MIME type analyzers, where keys are
         # analyzer names and values are `#call`-able objects which accepts the
@@ -48,6 +61,15 @@ class Shrine
         def mime_type_analyzer(name)
           MimeTypeAnalyzer.new(name)
         end
+
+        private
+
+        # Sends a `mime_type.shrine` event for instrumentation plugin.
+        def instrument_mime_type(io, &block)
+          return yield unless respond_to?(:instrument)
+
+          instrument(:mime_type, io: io, &block)
+        end
       end
 
       module InstanceMethods

data/lib/shrine/plugins/infer_extension.rb

@@ -6,18 +6,30 @@ class Shrine
     #
     # [doc/plugins/infer_extension.md]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/infer_extension.md
     module InferExtension
+      LOG_SUBSCRIBER = -> (event) do
+        Shrine.logger.info "Extension (#{event.duration}ms) – #{{
+          mime_type: event[:mime_type],
+          uploader:  event[:uploader],
+        }.inspect}"
+      end
+
       def self.configure(uploader, opts = {})
-        uploader.opts[:infer_extension_inferrer] = opts.fetch(:inferrer, uploader.opts.fetch(:infer_extension_inferrer, :mime_types))
-        uploader.opts[:infer_extension_force] = opts.fetch(:force, uploader.opts.fetch(:infer_extension_force, false))
+        uploader.opts[:infer_extension] ||= { inferrer: :mime_types, force: false, log_subscriber: LOG_SUBSCRIBER }
+        uploader.opts[:infer_extension].merge!(opts)
+
+        # instrumentation plugin integration
+        if uploader.respond_to?(:subscribe)
+          uploader.subscribe(:extension, &uploader.opts[:infer_extension][:log_subscriber])
+        end
       end
 
       module ClassMethods
         def infer_extension(mime_type)
-          inferrer = opts[:infer_extension_inferrer]
+          inferrer = opts[:infer_extension][:inferrer]
           inferrer = extension_inferrer(inferrer) if inferrer.is_a?(Symbol)
           args     = [mime_type, extension_inferrers].take(inferrer.arity.abs)
 
-          inferrer.call(*args)
+          instrument_extension(mime_type) { inferrer.call(*args) }
         end
 
         def extension_inferrers
@@ -29,6 +41,15 @@ class Shrine
         def extension_inferrer(name)
           ExtensionInferrer.new(name).method(:call)
         end
+
+        private
+
+        # Sends a `extension.shrine` event for instrumentation plugin.
+        def instrument_extension(mime_type, &block)
+          return yield unless respond_to?(:instrument)
+
+          instrument(:extension, mime_type: mime_type, &block)
+        end
       end
 
       module InstanceMethods
@@ -38,7 +59,7 @@ class Shrine
           location = super
           current_extension = File.extname(location)
 
-          if current_extension.empty? || opts[:infer_extension_force]
+          if current_extension.empty? || opts[:infer_extension][:force]
             inferred_extension = infer_extension(mime_type)
             location = location.chomp(current_extension) << inferred_extension unless inferred_extension.empty?
           end

data/lib/shrine/plugins/instrumentation.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+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
+    module Instrumentation
+      EVENTS = %i[upload download 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 }
+        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])
+        end
+      end
+
+      module ClassMethods
+        # Sends a `*.shrine` event.
+        #
+        #     # sends a `my_event.shrine` event
+        #     Shrine.instrument(:my_event) do
+        #       # work
+        #     end
+        def instrument(event_name, payload = {}, &block)
+          payload[:uploader] = self
+
+          notifications.instrument("#{event_name}.shrine", payload, &block)
+        end
+
+        # Subscribes to a `*.shrine` event. It rejects duplicate subscribers.
+        #
+        #     # subscribes to the `storage_upload.shrine` event
+        #     Shrine.subscribe(:storage_upload) do |event|
+        #       event.name #=> :storage_upload
+        #       event.payload #=> { location: "...", ... }
+        #       event[:location] #=> "..."
+        #       event.duration #=> 50 (in milliseconds)
+        #     end
+        def subscribe(event_name, &subscriber)
+          return if subscriber.nil?
+          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] << subscriber
+        end
+
+        private
+
+        def notifications
+          Notifications.new(opts[:instrumentation][:notifications])
+        end
+
+        def log_subscriber
+          opts[:instrumentation][:log_subscriber]
+        end
+
+        def subscribers
+          opts[:instrumentation_subscribers]
+        end
+      end
+
+      module InstanceMethods
+        private
+
+        # Sends a `upload.shrine` event.
+        def copy(io, context)
+          self.class.instrument(
+            :upload,
+            storage: storage_key,
+            location: context[:location],
+            io: io,
+            upload_options: context[:upload_options] || {},
+            options: context,
+          ) { 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
+
+          self.class.instrument(
+            :metadata,
+            storage: storage_key,
+            io: io,
+            options: context,
+          ) { super }
+        end
+      end
+
+      module FileMethods
+        # Sends a `download.shrine` event.
+        def open(**options)
+          shrine_class.instrument(
+            :download,
+            storage: storage_key.to_sym,
+            location: id,
+            download_options: options,
+          ) { super }
+        end
+
+        # Sends a `exists.shrine` event.
+        def exists?
+          shrine_class.instrument(
+            :exists,
+            storage: storage_key.to_sym,
+            location: id,
+          ) { super }
+        end
+
+        # Sends a `delete.shrine` event.
+        def delete
+          shrine_class.instrument(
+            :delete,
+            storage: storage_key.to_sym,
+            location: id,
+          ) { super }
+        end
+      end
+
+      # Abstracts away different types of notifications objects
+      # (`ActiveSupport::Notifications` and `Dry::Monitor::Notifications`).
+      class Notifications
+        attr_reader :notifications
+
+        def initialize(notifications)
+          @notifications = notifications
+        end
+
+        def subscribe(event_name, &block)
+          library_send(:subscribe, event_name) do |event|
+            yield Event.new(event)
+          end
+        end
+
+        def instrument(event_name, payload, &block)
+          notifications.instrument(event_name, payload, &block)
+        end
+
+        private
+
+        def dry_monitor_subscribe(event_name, &block)
+          notifications.register_event(event_name)
+          notifications.subscribe(event_name, &block)
+        end
+
+        def active_support_subscribe(event_name, &block)
+          notifications.subscribe(event_name) do |*args|
+            yield ActiveSupport::Notifications::Event.new(*args)
+          end
+        end
+
+        def library_send(method_name, *args, &block)
+          case notifications.to_s
+          when /Dry::Monitor::Notifications/
+            send(:"dry_monitor_#{method_name}", *args, &block)
+          when /ActiveSupport::Notifications/
+            send(:"active_support_#{method_name}", *args, &block)
+          else
+            notifications.send(method_name, *args, &block)
+          end
+        end
+      end
+
+      # Abstracts away different kind of event objects
+      # (`ActiveSupport::Notifications::Event` and `Dry::Events::Event`).
+      class Event
+        attr_reader :event
+
+        def initialize(event)
+          @event = event
+        end
+
+        def name
+          library_send(:name).chomp(".shrine").to_sym
+        end
+
+        def payload
+          event.payload
+        end
+
+        def [](name)
+          event.payload.fetch(name)
+        end
+
+        def duration
+          library_send(:duration)
+        end
+
+        private
+
+        def dry_events_name
+          event.id
+        end
+
+        def active_support_name
+          event.name
+        end
+
+        def dry_events_duration
+          event[:time]
+        end
+
+        def active_support_duration
+          event.duration.to_i
+        end
+
+        def library_send(method_name, *args, &block)
+          case event.class.name
+          when "ActiveSupport::Notifications::Event"
+            send(:"active_support_#{method_name}", *args, &block)
+          when "Dry::Events::Event"
+            send(:"dry_events_#{method_name}", *args, &block)
+          else
+            event.send(method_name, *args, &block)
+          end
+        end
+      end
+
+      # Logs received events.
+      class LogSubscriber
+        # Entry point for logging.
+        def self.call(event)
+          new.public_send(:"on_#{event.name}", event)
+        end
+
+        def on_upload(event)
+          log "Upload (#{event.duration}ms) – #{format(
+            storage:        event[:storage],
+            location:       event[:location],
+            io:             event[:io].class,
+            upload_options: event[:upload_options],
+            uploader:       event[:uploader],
+          )}"
+        end
+
+        def on_download(event)
+          log "Download (#{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],
+            location: event[:location],
+            uploader: event[:uploader],
+          )}"
+        end
+
+        def on_delete(event)
+          log "Delete (#{event.duration}ms) – #{format(
+            storage:  event[:storage],
+            location: event[:location],
+            uploader: event[:uploader],
+          )}"
+        end
+
+        def on_metadata(event)
+          log "Metadata (#{event.duration}ms) – #{format(
+            storage:  event[:storage],
+            io:       event[:io].class,
+            uploader: event[:uploader],
+          )}"
+        end
+
+        private
+
+        def format(properties = {})
+          properties.inspect
+        end
+
+        def log(message)
+          logger.info(message)
+        end
+
+        def logger
+          Shrine.logger
+        end
+      end
+    end
+
+    register_plugin(:instrumentation, Instrumentation)
+  end
+end