postburner 0.7.2 → 0.9.0.rc.1

data/app/concerns/postburner/callbacks.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require "active_support/callbacks"
+require "active_support/core_ext/object/with_options"
+require "active_support/core_ext/module/attribute_accessors"
+
+module Postburner
+  # = Postburner Job Callbacks
+  #
+  # Postburner Job provides hooks during the life cycle of a job. Callbacks allow you
+  # to trigger logic during this cycle. In called order, available callbacks are:
+  #
+  # * <tt>before_enqueue</tt>
+  # * <tt>after_enqueue</tt>
+  # * <tt>before_attempt</tt>
+  # * <tt>before_processing</tt>
+  # * <tt>after_processing</tt>
+  # * <tt>after_processed</tt>
+  # * <tt>after_attempt</tt>
+  #
+  # Around callbacks are also defined:
+  # * <tt>around_enqueue</tt>
+  # * <tt>around_attempt</tt>
+  # * <tt>around_processing</tt>
+  #
+  # NOTE: Calling the same callback multiple times will overwrite previous callback definitions.
+  #
+  module Callbacks
+    extend  ActiveSupport::Concern
+    include ActiveSupport::Callbacks
+
+    included do
+      cattr_accessor :skip_after_callbacks_if_terminated,
+        instance_accessor: false,
+        default: false
+
+      with_options(skip_after_callbacks_if_terminated: skip_after_callbacks_if_terminated) do
+        define_callbacks :enqueue
+        define_callbacks :attempt
+        define_callbacks :processing
+        define_callbacks :processed
+      end
+    end
+    module ClassMethods
+      def inherited(klass)
+        klass.get_callbacks(:enqueue).
+          config[:skip_after_callbacks_if_terminated] =
+            skip_after_callbacks_if_terminated
+        klass.get_callbacks(:processing).
+          config[:skip_after_callbacks_if_terminated] =
+            skip_after_callbacks_if_terminated
+        klass.get_callbacks(:attempt).
+          config[:skip_after_callbacks_if_terminated] =
+            skip_after_callbacks_if_terminated
+        klass.get_callbacks(:processed).
+          config[:skip_after_callbacks_if_terminated] =
+            skip_after_callbacks_if_terminated
+        super
+      end
+
+      # Defines a callback that will get called right before the
+      # job starts and any metadata is persisted.
+      #
+      #   class VideoProcessJob < Postburner::Base
+      #
+      #     before_attempt do |job|
+      #       $statsd.increment "attempting-video-job.try"
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      def before_attempt(*filters, &blk)
+        set_callback(:attempt, :before, *filters, &blk)
+      end
+
+      # Defines a callback that will get called right after the
+      # job finishes and all metadata is persisted.
+      #
+      # This isn't called unless the attempt finishes without error,
+      # though this is subject to change in the future
+      #
+      #   class VideoProcessJob < Postburner::Base
+      #
+      #     before_attempt do |job|
+      #       $statsd.increment "attempt-complete-video-job.try"
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      def after_attempt(*filters, &blk)
+        set_callback(:attempt, :after, *filters, &blk)
+      end
+
+      # Defines a callback that will get called around the attempt
+      # of the job.
+      #
+      #   class VideoProcessJob < Postburner::Base
+      #
+      #     around_enqueue do |job, block|
+      #       $statsd.time "video-job.process" do
+      #         block.call
+      #       end
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      def around_attempt(*filters, &blk)
+        set_callback(:attempt, :around, *filters, &blk)
+      end
+
+      # Defines a callback that will get called right before the
+      # job's perform method is executed.
+      #
+      #   class VideoProcessJob < Postburner::Base
+      #
+      #     before_processing do |job|
+      #       UserMailer.notify_video_started_processing(job.arguments.first)
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      def before_processing(*filters, &blk)
+        set_callback(:processing, :before, *filters, &blk)
+      end
+
+      # Defines a callback that will get called right after the
+      # job's perform method has finished.
+      #
+      #   class VideoProcessJob < Postburner::Base
+      #
+      #     after_processing do |job|
+      #       UserMailer.notify_video_processed(job.arguments.first)
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      def after_processing(*filters, &blk)
+        set_callback(:processing, :after, *filters, &blk)
+      end
+
+      # Defines a callback that will get called around the job's perform method.
+      #
+      #   class VideoProcessJob < Postburner::Base
+      #
+      #     around_processing do |job, block|
+      #       UserMailer.notify_video_started_processing(job.arguments.first)
+      #       block.call
+      #       UserMailer.notify_video_processed(job.arguments.first)
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      # You can access the return value of the job only if the execution wasn't halted.
+      #
+      #   class VideoProcessJob < Postburner::Base
+      #     around_processing do |job, block|
+      #       value = block.call
+      #       puts value # => "Hello World!"
+      #     end
+      #
+      #     def perform
+      #       "Hello World!"
+      #     end
+      #   end
+      #
+      def around_processing(*filters, &blk)
+        set_callback(:processing, :around, *filters, &blk)
+      end
+
+      # Defines a callback that will get called right after the
+      # job's processed_at timestamp has been persisted, marking the
+      # job as successfully completed, i.e. no errors raised.
+      #
+      # This is rather similar to after_processing but all of the
+      # job's metadata has been set.
+      #
+      #   class VideoProcessJob < Postburner::Base
+      #
+      #     after_processed do |job|
+      #       UserMailer.notify_video_processed(job.arguments.first)
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      def after_processed(*filters, &blk)
+        set_callback(:processed, :after, *filters, &blk)
+      end
+
+      # Defines a callback that will get called right before the
+      # job is enqueued.
+      #
+      #   class VideoProcessJob < Postburner::Base
+      #
+      #     before_enqueue do |job|
+      #       $statsd.increment "enqueue-video-job.try"
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      def before_enqueue(*filters, &blk)
+        set_callback(:enqueue, :before, *filters, &blk)
+      end
+
+      # Defines a callback that will get called right after the
+      # job is enqueued.
+      #
+      #   class VideoProcessJob < Postburner::Base
+      #
+      #     after_enqueue do |job|
+      #       $statsd.increment "enqueue-video-job.success"
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      def after_enqueue(*filters, &blk)
+        set_callback(:enqueue, :after, *filters, &blk)
+      end
+
+      # Defines a callback that will get called around the enqueuing
+      # of the job.
+      #
+      #   class VideoProcessJob < Postburner::Base
+      #
+      #     around_enqueue do |job, block|
+      #       $statsd.time "video-job.process" do
+      #         block.call
+      #       end
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      def around_enqueue(*filters, &blk)
+        set_callback(:enqueue, :around, *filters, &blk)
+      end
+    end
+
+    private
+
+    # NOTE processed / attempt exclueded here -- intentionally
+    #
+    def halted_callback_hook(_filter, name) # :nodoc:
+      return super unless %i(enqueue processing).include?(name.to_sym)
+      callbacks = public_send("_#{name}_callbacks")
+
+      if !self.class.skip_after_callbacks_if_terminated && callbacks.any? { |c| c.kind == :after }
+        ActiveSupport::Deprecation.warn(<<~EOM)
+            In Rails 7.0, `after_enqueue`/`after_work` callbacks no longer run if `before_enqueue`/`before_work` respectively halts with `throw :abort`.
+            To enable this behavior, uncomment the `config.active_job.skip_after_callbacks_if_terminated` config
+            in the new 6.1 framework defaults initializer.
+        EOM
+      end
+
+      super
+    end
+  end
+end