activejob 5.2.4.4 → 6.1.1

data/lib/active_job/base.rb

@@ -8,7 +8,10 @@ require "active_job/enqueuing"
 require "active_job/execution"
 require "active_job/callbacks"
 require "active_job/exceptions"
+require "active_job/log_subscriber"
 require "active_job/logging"
+require "active_job/instrumentation"
+require "active_job/timezones"
 require "active_job/translation"
 
 module ActiveJob #:nodoc:
@@ -39,7 +42,7 @@ module ActiveJob #:nodoc:
   # Records that are passed in are serialized/deserialized using Global
   # ID. More information can be found in Arguments.
   #
-  # To enqueue a job to be performed as soon as the queueing system is free:
+  # To enqueue a job to be performed as soon as the queuing system is free:
   #
   #   ProcessPhotoJob.perform_later(photo)
   #
@@ -67,6 +70,8 @@ module ActiveJob #:nodoc:
     include Callbacks
     include Exceptions
     include Logging
+    include Instrumentation
+    include Timezones
     include Translation
 
     ActiveSupport.run_load_hooks(:active_job, self)

data/lib/active_job/callbacks.rb

@@ -1,6 +1,8 @@
 # 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 ActiveJob
   # = Active Job Callbacks
@@ -27,13 +29,25 @@ module ActiveJob
     end
 
     included do
-      define_callbacks :perform
-      define_callbacks :enqueue
+      class_attribute :return_false_on_aborted_enqueue, instance_accessor: false, instance_predicate: false, default: false
+      singleton_class.deprecate :return_false_on_aborted_enqueue, :return_false_on_aborted_enqueue=
+      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 :perform
+        define_callbacks :enqueue
+      end
     end
 
     # These methods will be included into any Active Job object, adding
     # callbacks for +perform+ and +enqueue+ methods.
     module ClassMethods
+      def inherited(klass)
+        klass.get_callbacks(:enqueue).config[:skip_after_callbacks_if_terminated] = skip_after_callbacks_if_terminated
+        klass.get_callbacks(:perform).config[:skip_after_callbacks_if_terminated] = skip_after_callbacks_if_terminated
+        super
+      end
+
       # Defines a callback that will get called right before the
       # job's perform method is executed.
       #
@@ -88,6 +102,19 @@ module ActiveJob
       #     end
       #   end
       #
+      # You can access the return value of the job only if the execution wasn't halted.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     around_perform do |job, block|
+      #       value = block.call
+      #       puts value # => "Hello World!"
+      #     end
+      #
+      #     def perform
+      #       "Hello World!"
+      #     end
+      #   end
+      #
       def around_perform(*filters, &blk)
         set_callback(:perform, :around, *filters, &blk)
       end
@@ -130,7 +157,7 @@ module ActiveJob
         set_callback(:enqueue, :after, *filters, &blk)
       end
 
-      # Defines a callback that will get called around the enqueueing
+      # Defines a callback that will get called around the enqueuing
       # of the job.
       #
       #   class VideoProcessJob < ActiveJob::Base
@@ -151,5 +178,21 @@ module ActiveJob
         set_callback(:enqueue, :around, *filters, &blk)
       end
     end
+
+    private
+      def halted_callback_hook(_filter, name) # :nodoc:
+        return super unless %i(enqueue perform).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 6.2, `after_enqueue`/`after_perform` callbacks no longer run if `before_enqueue`/`before_perform` 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

data/lib/active_job/configured_job.rb

@@ -10,9 +10,11 @@ module ActiveJob
     def perform_now(*args)
       @job_class.new(*args).perform_now
     end
+    ruby2_keywords(:perform_now) if respond_to?(:ruby2_keywords, true)
 
     def perform_later(*args)
       @job_class.new(*args).enqueue @options
     end
+    ruby2_keywords(:perform_later) if respond_to?(:ruby2_keywords, true)
   end
 end

data/lib/active_job/core.rb

@@ -6,32 +6,42 @@ module ActiveJob
   module Core
     extend ActiveSupport::Concern
 
-    included do
-      # Job arguments
-      attr_accessor :arguments
-      attr_writer :serialized_arguments
+    # Job arguments
+    attr_accessor :arguments
+    attr_writer :serialized_arguments
 
-      # Timestamp when the job should be performed
-      attr_accessor :scheduled_at
+    # Timestamp when the job should be performed
+    attr_accessor :scheduled_at
 
-      # Job Identifier
-      attr_accessor :job_id
+    # Job Identifier
+    attr_accessor :job_id
 
-      # Queue in which the job will reside.
-      attr_writer :queue_name
+    # Queue in which the job will reside.
+    attr_writer :queue_name
 
-      # Priority that the job will have (lower is more priority).
-      attr_writer :priority
+    # Priority that the job will have (lower is more priority).
+    attr_writer :priority
 
-      # ID optionally provided by adapter
-      attr_accessor :provider_job_id
+    # ID optionally provided by adapter
+    attr_accessor :provider_job_id
 
-      # Number of times this job has been executed (which increments on every retry, like after an exception).
-      attr_accessor :executions
+    # Number of times this job has been executed (which increments on every retry, like after an exception).
+    attr_accessor :executions
 
-      # I18n.locale to be used during the job.
-      attr_accessor :locale
-    end
+    # Hash that contains the number of times this job handled errors for each specific retry_on declaration.
+    # Keys are the string representation of the exceptions listed in the retry_on declaration,
+    # while its associated value holds the number of executions where the corresponding retry_on
+    # declaration handled one of its listed exceptions.
+    attr_accessor :exception_executions
+
+    # I18n.locale to be used during the job.
+    attr_accessor :locale
+
+    # Timezone to be used during the job.
+    attr_accessor :timezone
+
+    # Track when a job was enqueued
+    attr_accessor :enqueued_at
 
     # These methods will be included into any Active Job object, adding
     # helpers for de/serialization and creation of job instances.
@@ -74,10 +84,13 @@ module ActiveJob
       @queue_name = self.class.queue_name
       @priority   = self.class.priority
       @executions = 0
+      @exception_executions = {}
+      @timezone   = Time.zone&.name
     end
+    ruby2_keywords(:initialize) if respond_to?(:ruby2_keywords, true)
 
     # Returns a hash with the job data that can safely be passed to the
-    # queueing adapter.
+    # queuing adapter.
     def serialize
       {
         "job_class"  => self.class.name,
@@ -87,7 +100,10 @@ module ActiveJob
         "priority"   => priority,
         "arguments"  => serialize_arguments_if_needed(arguments),
         "executions" => executions,
-        "locale"     => I18n.locale.to_s
+        "exception_executions" => exception_executions,
+        "locale"     => I18n.locale.to_s,
+        "timezone"   => timezone,
+        "enqueued_at" => Time.now.utc.iso8601
       }
     end
 
@@ -124,7 +140,10 @@ module ActiveJob
       self.priority             = job_data["priority"]
       self.serialized_arguments = job_data["arguments"]
       self.executions           = job_data["executions"]
+      self.exception_executions = job_data["exception_executions"]
       self.locale               = job_data["locale"] || I18n.locale.to_s
+      self.timezone             = job_data["timezone"] || Time.zone&.name
+      self.enqueued_at          = job_data["enqueued_at"]
     end
 
     private

data/lib/active_job/enqueuing.rb

@@ -9,21 +9,25 @@ module ActiveJob
 
     # Includes the +perform_later+ method for job initialization.
     module ClassMethods
-      # Push a job onto the queue. The arguments must be legal JSON types
-      # (+string+, +int+, +float+, +nil+, +true+, +false+, +hash+ or +array+) or
-      # GlobalID::Identification instances. Arbitrary Ruby objects
-      # are not supported.
+      # Push a job onto the queue. By default the arguments must be either String,
+      # Integer, Float, NilClass, TrueClass, FalseClass, BigDecimal, Symbol, Date,
+      # Time, DateTime, ActiveSupport::TimeWithZone, ActiveSupport::Duration,
+      # Hash, ActiveSupport::HashWithIndifferentAccess, Array or
+      # GlobalID::Identification instances, although this can be extended by adding
+      # custom serializers.
       #
       # Returns an instance of the job class queued with arguments available in
       # Job#arguments.
       def perform_later(*args)
         job_or_instantiate(*args).enqueue
       end
+      ruby2_keywords(:perform_later) if respond_to?(:ruby2_keywords, true)
 
       private
         def job_or_instantiate(*args) # :doc:
           args.first.is_a?(self) ? args.first : new(*args)
         end
+        ruby2_keywords(:job_or_instantiate) if respond_to?(:ruby2_keywords, true)
     end
 
     # Enqueues the job to be performed by the queue adapter.
@@ -46,14 +50,23 @@ module ActiveJob
       self.scheduled_at = options[:wait_until].to_f if options[:wait_until]
       self.queue_name   = self.class.queue_name_from_part(options[:queue]) if options[:queue]
       self.priority     = options[:priority].to_i if options[:priority]
+      successfully_enqueued = false
+
       run_callbacks :enqueue do
         if scheduled_at
-          self.class.queue_adapter.enqueue_at self, scheduled_at
+          queue_adapter.enqueue_at self, scheduled_at
         else
-          self.class.queue_adapter.enqueue self
+          queue_adapter.enqueue self
         end
+
+        successfully_enqueued = true
+      end
+
+      if successfully_enqueued
+        self
+      else
+        false
       end
-      self
     end
   end
 end

data/lib/active_job/exceptions.rb

@@ -7,6 +7,10 @@ module ActiveJob
   module Exceptions
     extend ActiveSupport::Concern
 
+    included do
+      class_attribute :retry_jitter, instance_accessor: false, instance_predicate: false, default: 0.0
+    end
+
     module ClassMethods
       # Catch the exception and reschedule job for re-execution after so many seconds, for a specific number of attempts.
       # If the exception keeps getting raised beyond the specified number of attempts, the exception is allowed to
@@ -18,40 +22,49 @@ module ActiveJob
       #
       # ==== Options
       # * <tt>:wait</tt> - Re-enqueues the job with a delay specified either in seconds (default: 3 seconds),
-      #   as a computing proc that the number of executions so far as an argument, or as a symbol reference of
-      #   <tt>:exponentially_longer</tt>, which applies the wait algorithm of <tt>(executions ** 4) + 2</tt>
-      #   (first wait 3s, then 18s, then 83s, etc)
+      #   as a computing proc that takes the number of executions so far as an argument, or as a symbol reference of
+      #   <tt>:exponentially_longer</tt>, which applies the wait algorithm of <tt>((executions**4) + (Kernel.rand * (executions**4) * jitter)) + 2</tt>
+      #   (first wait ~3s, then ~18s, then ~83s, etc)
       # * <tt>:attempts</tt> - Re-enqueues the job the specified number of times (default: 5 attempts)
       # * <tt>:queue</tt> - Re-enqueues the job on a different queue
       # * <tt>:priority</tt> - Re-enqueues the job with a different priority
+      # * <tt>:jitter</tt> - A random delay of wait time used when calculating backoff. The default is 15% (0.15) which represents the upper bound of possible wait time (expressed as a percentage)
       #
       # ==== Examples
       #
       #  class RemoteServiceJob < ActiveJob::Base
-      #    retry_on CustomAppException # defaults to 3s wait, 5 attempts
+      #    retry_on CustomAppException # defaults to ~3s wait, 5 attempts
       #    retry_on AnotherCustomAppException, wait: ->(executions) { executions * 2 }
+      #
+      #    retry_on ActiveRecord::Deadlocked, wait: 5.seconds, attempts: 3
+      #    retry_on Net::OpenTimeout, Timeout::Error, wait: :exponentially_longer, attempts: 10 # retries at most 10 times for Net::OpenTimeout and Timeout::Error combined
+      #    # To retry at most 10 times for each individual exception:
+      #    # retry_on Net::OpenTimeout, wait: :exponentially_longer, attempts: 10
+      #    # retry_on Net::ReadTimeout, wait: 5.seconds, jitter: 0.30, attempts: 10
+      #    # retry_on Timeout::Error, wait: :exponentially_longer, attempts: 10
+      #
       #    retry_on(YetAnotherCustomAppException) do |job, error|
       #      ExceptionNotifier.caught(error)
       #    end
-      #    retry_on ActiveRecord::Deadlocked, wait: 5.seconds, attempts: 3
-      #    retry_on Net::OpenTimeout, wait: :exponentially_longer, attempts: 10
       #
       #    def perform(*args)
       #      # Might raise CustomAppException, AnotherCustomAppException, or YetAnotherCustomAppException for something domain specific
       #      # Might raise ActiveRecord::Deadlocked when a local db deadlock is detected
-      #      # Might raise Net::OpenTimeout when the remote service is down
+      #      # Might raise Net::OpenTimeout or Timeout::Error when the remote service is down
       #    end
       #  end
-      def retry_on(exception, wait: 3.seconds, attempts: 5, queue: nil, priority: nil)
-        rescue_from exception do |error|
+      def retry_on(*exceptions, wait: 3.seconds, attempts: 5, queue: nil, priority: nil, jitter: JITTER_DEFAULT)
+        rescue_from(*exceptions) do |error|
+          executions = executions_for(exceptions)
           if executions < attempts
-            logger.error "Retrying #{self.class} in #{wait} seconds, due to a #{exception}. The original exception was #{error.cause.inspect}."
-            retry_job wait: determine_delay(wait), queue: queue, priority: priority
+            retry_job wait: determine_delay(seconds_or_duration_or_algorithm: wait, executions: executions, jitter: jitter), queue: queue, priority: priority, error: error
           else
             if block_given?
-              yield self, error
+              instrument :retry_stopped, error: error do
+                yield self, error
+              end
             else
-              logger.error "Stopped retrying #{self.class} due to a #{exception}, which reoccurred on #{executions} attempts. The original exception was #{error.cause.inspect}."
+              instrument :retry_stopped, error: error
               raise error
             end
           end
@@ -76,12 +89,10 @@ module ActiveJob
       #      # Might raise CustomAppException for something domain specific
       #    end
       #  end
-      def discard_on(exception)
-        rescue_from exception do |error|
-          if block_given?
-            yield self, error
-          else
-            logger.error "Discarded #{self.class} due to a #{exception}. The original exception was #{error.cause.inspect}."
+      def discard_on(*exceptions)
+        rescue_from(*exceptions) do |error|
+          instrument :discard, error: error do
+            yield self, error if block_given?
           end
         end
       end
@@ -109,20 +120,27 @@ module ActiveJob
     #    end
     #  end
     def retry_job(options = {})
-      enqueue options
+      instrument :enqueue_retry, options.slice(:error, :wait) do
+        enqueue options
+      end
     end
 
     private
-      def determine_delay(seconds_or_duration_or_algorithm)
+      JITTER_DEFAULT = Object.new
+      private_constant :JITTER_DEFAULT
+
+      def determine_delay(seconds_or_duration_or_algorithm:, executions:, jitter: JITTER_DEFAULT)
+        jitter = jitter == JITTER_DEFAULT ? self.class.retry_jitter : (jitter || 0.0)
+
         case seconds_or_duration_or_algorithm
         when :exponentially_longer
-          (executions**4) + 2
-        when ActiveSupport::Duration
-          duration = seconds_or_duration_or_algorithm
-          duration.to_i
-        when Integer
-          seconds = seconds_or_duration_or_algorithm
-          seconds
+          delay = executions**4
+          delay_jitter = determine_jitter_for_delay(delay, jitter)
+          delay + delay_jitter + 2
+        when ActiveSupport::Duration, Integer
+          delay = seconds_or_duration_or_algorithm.to_i
+          delay_jitter = determine_jitter_for_delay(delay, jitter)
+          delay + delay_jitter
         when Proc
           algorithm = seconds_or_duration_or_algorithm
           algorithm.call(executions)
@@ -130,5 +148,19 @@ module ActiveJob
           raise "Couldn't determine a delay based on #{seconds_or_duration_or_algorithm.inspect}"
         end
       end
+
+      def determine_jitter_for_delay(delay, jitter)
+        return 0.0 if jitter.zero?
+        Kernel.rand * delay * jitter
+      end
+
+      def executions_for(exceptions)
+        if exception_executions
+          exception_executions[exceptions.to_s] = (exception_executions[exceptions.to_s] || 0) + 1
+        else
+          # Guard against jobs that were persisted before we started having individual executions counters per retry_on
+          executions
+        end
+      end
   end
 end

data/lib/active_job/execution.rb

@@ -17,6 +17,7 @@ module ActiveJob
       def perform_now(*args)
         job_or_instantiate(*args).perform_now
       end
+      ruby2_keywords(:perform_now) if respond_to?(:ruby2_keywords, true)
 
       def execute(job_data) #:nodoc:
         ActiveJob::Callbacks.run_callbacks(:execute) do
@@ -26,15 +27,23 @@ module ActiveJob
       end
     end
 
-    # Performs the job immediately. The job is not sent to the queueing adapter
+    # Performs the job immediately. The job is not sent to the queuing adapter
     # but directly executed by blocking the execution of others until it's finished.
+    # `perform_now` returns the value of your job's `perform` method.
     #
-    #   MyJob.new(*args).perform_now
+    #   class MyJob < ActiveJob::Base
+    #     def perform
+    #       "Hello World!"
+    #     end
+    #   end
+    #
+    #   puts MyJob.new(*args).perform_now # => "Hello World!"
     def perform_now
       # Guard against jobs that were persisted before we started counting executions by zeroing out nil counters
       self.executions = (executions || 0) + 1
 
       deserialize_arguments_if_needed
+
       run_callbacks :perform do
         perform(*arguments)
       end