activejob 7.0.8.4 → 7.1.3.4

data/lib/active_job/core.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module ActiveJob
+  # = Active Job \Core
+  #
   # Provides general behavior that will be included into every Active Job
   # object that inherits from ActiveJob::Base.
   module Core
@@ -10,8 +12,10 @@ module ActiveJob
     attr_accessor :arguments
     attr_writer :serialized_arguments
 
-    # Timestamp when the job should be performed
-    attr_accessor :scheduled_at
+    # Time when the job should be performed
+    attr_reader :scheduled_at
+
+    attr_reader :_scheduled_at_time # :nodoc:
 
     # Job Identifier
     attr_accessor :job_id
@@ -92,6 +96,8 @@ module ActiveJob
       @arguments  = arguments
       @job_id     = SecureRandom.uuid
       @queue_name = self.class.queue_name
+      @scheduled_at = nil
+      @_scheduled_at_time = nil
       @priority   = self.class.priority
       @executions = 0
       @exception_executions = {}
@@ -113,7 +119,8 @@ module ActiveJob
         "exception_executions" => exception_executions,
         "locale"     => I18n.locale.to_s,
         "timezone"   => timezone,
-        "enqueued_at" => Time.now.utc.iso8601
+        "enqueued_at" => Time.now.utc.iso8601(9),
+        "scheduled_at" => _scheduled_at_time ? _scheduled_at_time.utc.iso8601(9) : nil,
       }
     end
 
@@ -153,19 +160,32 @@ module ActiveJob
       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"]
+      self.enqueued_at          = Time.iso8601(job_data["enqueued_at"]) if job_data["enqueued_at"]
+      self.scheduled_at         = Time.iso8601(job_data["scheduled_at"]) if job_data["scheduled_at"]
     end
 
     # Configures the job with the given options.
     def set(options = {}) # :nodoc:
-      self.scheduled_at = options[:wait].seconds.from_now.to_f if options[:wait]
-      self.scheduled_at = options[:wait_until].to_f if options[:wait_until]
+      self.scheduled_at = options[:wait].seconds.from_now if options[:wait]
+      self.scheduled_at = options[:wait_until] 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]
 
       self
     end
 
+    def scheduled_at=(value)
+      @_scheduled_at_time = if value&.is_a?(Numeric)
+        ActiveJob.deprecator.warn(<<~MSG.squish)
+          Assigning a numeric/epoch value to scheduled_at is deprecated. Use a Time object instead.
+        MSG
+        Time.at(value)
+      else
+        value
+      end
+      @scheduled_at = value
+    end
+
     private
       def serialize_arguments_if_needed(arguments)
         if arguments_serialized?

data/lib/active_job/deprecator.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  def self.deprecator # :nodoc:
+    @deprecator ||= ActiveSupport::Deprecation.new
+  end
+end

data/lib/active_job/enqueuing.rb

@@ -9,6 +9,36 @@ module ActiveJob
   # why the adapter was unexpectedly unable to enqueue a job.
   class EnqueueError < StandardError; end
 
+  class << self
+    # Push many jobs onto the queue at once without running enqueue callbacks.
+    # Queue adapters may communicate the enqueue status of each job by setting
+    # successfully_enqueued and/or enqueue_error on the passed-in job instances.
+    def perform_all_later(*jobs)
+      jobs.flatten!
+      jobs.group_by(&:queue_adapter).each do |queue_adapter, adapter_jobs|
+        instrument_enqueue_all(queue_adapter, adapter_jobs) do
+          if queue_adapter.respond_to?(:enqueue_all)
+            queue_adapter.enqueue_all(adapter_jobs)
+          else
+            adapter_jobs.each do |job|
+              job.successfully_enqueued = false
+              if job.scheduled_at
+                queue_adapter.enqueue_at(job, job._scheduled_at_time.to_f)
+              else
+                queue_adapter.enqueue(job)
+              end
+              job.successfully_enqueued = true
+            rescue EnqueueError => e
+              job.enqueue_error = e
+            end
+            adapter_jobs.count(&:successfully_enqueued?)
+          end
+        end
+      end
+      nil
+    end
+  end
+
   module Enqueuing
     extend ActiveSupport::Concern
 
@@ -62,7 +92,7 @@ module ActiveJob
 
       run_callbacks :enqueue do
         if scheduled_at
-          queue_adapter.enqueue_at self, scheduled_at
+          queue_adapter.enqueue_at self, _scheduled_at_time.to_f
         else
           queue_adapter.enqueue self
         end

data/lib/active_job/exceptions.rb

@@ -9,6 +9,7 @@ module ActiveJob
 
     included do
       class_attribute :retry_jitter, instance_accessor: false, instance_predicate: false, default: 0.0
+      class_attribute :after_discard_procs, default: []
     end
 
     module ClassMethods
@@ -20,10 +21,13 @@ module ActiveJob
       # You can also pass a block that'll be invoked if the retry attempts fail for custom logic rather than letting
       # the exception bubble up. This block is yielded with the job instance as the first and the error instance as the second parameter.
       #
+      # `retry_on` and `discard_on` handlers are searched from bottom to top, and up the class hierarchy. The handler of the first class for
+      # which <tt>exception.is_a?(klass)</tt> holds true is the one invoked, if any.
+      #
       # ==== Options
       # * <tt>:wait</tt> - Re-enqueues the job with a delay specified either in seconds (default: 3 seconds),
       #   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>
+      #   <tt>:polynomially_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) or a symbol reference of <tt>:unlimited</tt>
       #   to retry the job until it succeeds
@@ -39,11 +43,11 @@ module ActiveJob
       #    retry_on CustomInfrastructureException, wait: 5.minutes, attempts: :unlimited
       #
       #    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
+      #    retry_on Net::OpenTimeout, Timeout::Error, wait: :polynomially_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::OpenTimeout, wait: :polynomially_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 Timeout::Error, wait: :polynomially_longer, attempts: 10
       #
       #    retry_on(YetAnotherCustomAppException) do |job, error|
       #      ExceptionNotifier.caught(error)
@@ -56,6 +60,12 @@ module ActiveJob
       #    end
       #  end
       def retry_on(*exceptions, wait: 3.seconds, attempts: 5, queue: nil, priority: nil, jitter: JITTER_DEFAULT)
+        if wait == :exponentially_longer
+          ActiveJob.deprecator.warn(<<~MSG.squish)
+            `wait: :exponentially_longer` will actually wait polynomially longer and is therefore deprecated.
+            Prefer `wait: :polynomially_longer` to avoid confusion and keep the same behavior.
+          MSG
+        end
         rescue_from(*exceptions) do |error|
           executions = executions_for(exceptions)
           if attempts == :unlimited || executions < attempts
@@ -65,8 +75,10 @@ module ActiveJob
               instrument :retry_stopped, error: error do
                 yield self, error
               end
+              run_after_discard_procs(error)
             else
               instrument :retry_stopped, error: error
+              run_after_discard_procs(error)
               raise error
             end
           end
@@ -78,6 +90,9 @@ module ActiveJob
       #
       # You can also pass a block that'll be invoked. This block is yielded with the job instance as the first and the error instance as the second parameter.
       #
+      # `retry_on` and `discard_on` handlers are searched from bottom to top, and up the class hierarchy. The handler of the first class for
+      # which <tt>exception.is_a?(klass)</tt> holds true is the one invoked, if any.
+      #
       # ==== Example
       #
       #  class SearchIndexingJob < ActiveJob::Base
@@ -95,9 +110,26 @@ module ActiveJob
         rescue_from(*exceptions) do |error|
           instrument :discard, error: error do
             yield self, error if block_given?
+            run_after_discard_procs(error)
           end
         end
       end
+
+      # A block to run when a job is about to be discarded for any reason.
+      #
+      # ==== Example
+      #
+      #  class WorkJob < ActiveJob::Base
+      #    after_discard do |job, exception|
+      #      ExceptionNotifier.report(exception)
+      #    end
+      #
+      #    ...
+      #
+      #  end
+      def after_discard(&blk)
+        self.after_discard_procs += [blk]
+      end
     end
 
     # Reschedules the job to be re-executed. This is useful in combination with
@@ -136,7 +168,8 @@ module ActiveJob
         jitter = jitter == JITTER_DEFAULT ? self.class.retry_jitter : (jitter || 0.0)
 
         case seconds_or_duration_or_algorithm
-        when :exponentially_longer
+        when :exponentially_longer, :polynomially_longer
+          # This delay uses a polynomial backoff strategy, which was previously misnamed as exponential
           delay = executions**4
           delay_jitter = determine_jitter_for_delay(delay, jitter)
           delay + delay_jitter + 2
@@ -165,5 +198,15 @@ module ActiveJob
           executions
         end
       end
+
+      def run_after_discard_procs(exception)
+        exceptions = []
+        after_discard_procs.each do |blk|
+          instance_exec(self, exception, &blk)
+        rescue StandardError => e
+          exceptions << e
+        end
+        raise exceptions.last unless exceptions.empty?
+      end
   end
 end

data/lib/active_job/execution.rb

@@ -51,7 +51,11 @@ module ActiveJob
 
       _perform_job
     rescue Exception => exception
-      rescue_with_handler(exception) || raise
+      handled = rescue_with_handler(exception)
+      return handled if handled
+
+      run_after_discard_procs(exception)
+      raise
     end
 
     def perform(*)

data/lib/active_job/gem_version.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
 module ActiveJob
-  # Returns the currently loaded version of Active Job as a <tt>Gem::Version</tt>.
+  # Returns the currently loaded version of Active Job as a +Gem::Version+.
   def self.gem_version
     Gem::Version.new VERSION::STRING
   end
 
   module VERSION
     MAJOR = 7
-    MINOR = 0
-    TINY  = 8
+    MINOR = 1
+    TINY  = 3
     PRE   = "4"
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")

data/lib/active_job/instrumentation.rb

@@ -1,6 +1,18 @@
 # frozen_string_literal: true
 
 module ActiveJob
+  class << self
+    private
+      def instrument_enqueue_all(queue_adapter, jobs)
+        payload = { adapter: queue_adapter, jobs: jobs }
+        ActiveSupport::Notifications.instrument("enqueue_all.active_job", payload) do
+          result = yield payload
+          payload[:enqueued_count] = result
+          result
+        end
+      end
+  end
+
   module Instrumentation # :nodoc:
     extend ActiveSupport::Concern
 
@@ -21,19 +33,15 @@ module ActiveJob
       end
 
       def instrument(operation, payload = {}, &block)
-        enhanced_block = ->(event_payload) do
-          value = block.call if block
-
-          if defined?(@_halted_callback_hook_called) && @_halted_callback_hook_called
-            event_payload[:aborted] = true
-            @_halted_callback_hook_called = nil
-          end
+        payload[:job] = self
+        payload[:adapter] = queue_adapter
 
+        ActiveSupport::Notifications.instrument("#{operation}.active_job", payload) do
+          value = block.call if block
+          payload[:aborted] = @_halted_callback_hook_called if defined?(@_halted_callback_hook_called)
+          @_halted_callback_hook_called = nil
           value
         end
-
-        ActiveSupport::Notifications.instrument \
-          "#{operation}.active_job", payload.merge(adapter: queue_adapter, job: self), &enhanced_block
       end
 
       def halted_callback_hook(*)

data/lib/active_job/log_subscriber.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
-require "active_support/core_ext/string/filters"
 require "active_support/log_subscriber"
 
 module ActiveJob
   class LogSubscriber < ActiveSupport::LogSubscriber # :nodoc:
+    class_attribute :backtrace_cleaner, default: ActiveSupport::BacktraceCleaner.new
+
     def enqueue(event)
       job = event.payload[:job]
       ex = event.payload[:exception_object] || job.enqueue_error
@@ -23,6 +24,7 @@ module ActiveJob
         end
       end
     end
+    subscribe_log_level :enqueue, :info
 
     def enqueue_at(event)
       job = event.payload[:job]
@@ -38,17 +40,48 @@ module ActiveJob
         end
       else
         info do
-          "Enqueued #{job.class.name} (Job ID: #{job.job_id}) to #{queue_name(event)} at #{scheduled_at(event).to_default_s}" + args_info(job)
+          "Enqueued #{job.class.name} (Job ID: #{job.job_id}) to #{queue_name(event)} at #{scheduled_at(event)}" + args_info(job)
+        end
+      end
+    end
+    subscribe_log_level :enqueue_at, :info
+
+    def enqueue_all(event)
+      info do
+        jobs = event.payload[:jobs]
+        adapter = event.payload[:adapter]
+        enqueued_count = event.payload[:enqueued_count]
+
+        if enqueued_count == jobs.size
+          enqueued_jobs_message(adapter, jobs)
+        elsif jobs.any?(&:successfully_enqueued?)
+          enqueued_jobs = jobs.select(&:successfully_enqueued?)
+
+          failed_enqueue_count = jobs.size - enqueued_count
+          if failed_enqueue_count == 0
+            enqueued_jobs_message(adapter, enqueued_jobs)
+          else
+            "#{enqueued_jobs_message(adapter, enqueued_jobs)}. "\
+              "Failed enqueuing #{failed_enqueue_count} #{'job'.pluralize(failed_enqueue_count)}"
+          end
+        else
+          failed_enqueue_count = jobs.size - enqueued_count
+          "Failed enqueuing #{failed_enqueue_count} #{'job'.pluralize(failed_enqueue_count)} "\
+            "to #{ActiveJob.adapter_name(adapter)}"
         end
       end
     end
+    subscribe_log_level :enqueue_all, :info
 
     def perform_start(event)
       info do
         job = event.payload[:job]
-        "Performing #{job.class.name} (Job ID: #{job.job_id}) from #{queue_name(event)} enqueued at #{job.enqueued_at}" + args_info(job)
+        enqueue_info = job.enqueued_at.present? ? " enqueued at #{job.enqueued_at.utc.iso8601(9)}" : ""
+
+        "Performing #{job.class.name} (Job ID: #{job.job_id}) from #{queue_name(event)}" + enqueue_info + args_info(job)
       end
     end
+    subscribe_log_level :perform_start, :info
 
     def perform(event)
       job = event.payload[:job]
@@ -67,6 +100,7 @@ module ActiveJob
         end
       end
     end
+    subscribe_log_level :perform, :info
 
     def enqueue_retry(event)
       job = event.payload[:job]
@@ -75,34 +109,37 @@ module ActiveJob
 
       info do
         if ex
-          "Retrying #{job.class} in #{wait.to_i} seconds, due to a #{ex.class}."
+          "Retrying #{job.class} (Job ID: #{job.job_id}) after #{job.executions} attempts in #{wait.to_i} seconds, due to a #{ex.class} (#{ex.message})."
         else
-          "Retrying #{job.class} in #{wait.to_i} seconds."
+          "Retrying #{job.class} (Job ID: #{job.job_id}) after #{job.executions} attempts in #{wait.to_i} seconds."
         end
       end
     end
+    subscribe_log_level :enqueue_retry, :info
 
     def retry_stopped(event)
       job = event.payload[:job]
       ex = event.payload[:error]
 
       error do
-        "Stopped retrying #{job.class} due to a #{ex.class}, which reoccurred on #{job.executions} attempts."
+        "Stopped retrying #{job.class} (Job ID: #{job.job_id}) due to a #{ex.class} (#{ex.message}), which reoccurred on #{job.executions} attempts."
       end
     end
+    subscribe_log_level :enqueue_retry, :error
 
     def discard(event)
       job = event.payload[:job]
       ex = event.payload[:error]
 
       error do
-        "Discarded #{job.class} due to a #{ex.class}."
+        "Discarded #{job.class} (Job ID: #{job.job_id}) due to a #{ex.class} (#{ex.message})."
       end
     end
+    subscribe_log_level :discard, :error
 
     private
       def queue_name(event)
-        event.payload[:adapter].class.name.demodulize.remove("Adapter") + "(#{event.payload[:job].queue_name})"
+        ActiveJob.adapter_name(event.payload[:adapter]) + "(#{event.payload[:job].queue_name})"
       end
 
       def args_info(job)
@@ -134,6 +171,41 @@ module ActiveJob
       def logger
         ActiveJob::Base.logger
       end
+
+      def info(progname = nil, &block)
+        return unless super
+
+        if ActiveJob.verbose_enqueue_logs
+          log_enqueue_source
+        end
+      end
+
+      def error(progname = nil, &block)
+        return unless super
+
+        if ActiveJob.verbose_enqueue_logs
+          log_enqueue_source
+        end
+      end
+
+      def log_enqueue_source
+        source = extract_enqueue_source_location(caller)
+
+        if source
+          logger.info("↳ #{source}")
+        end
+      end
+
+      def extract_enqueue_source_location(locations)
+        backtrace_cleaner.clean(locations.lazy).first
+      end
+
+      def enqueued_jobs_message(adapter, enqueued_jobs)
+        enqueued_count = enqueued_jobs.size
+        job_classes_counts = enqueued_jobs.map(&:class).tally.sort_by { |_k, v| -v }
+        "Enqueued #{enqueued_count} #{'job'.pluralize(enqueued_count)} to #{ActiveJob.adapter_name(adapter)}"\
+          " (#{job_classes_counts.map { |klass, count| "#{count} #{klass}" }.join(', ')})"
+      end
   end
 end
 

data/lib/active_job/queue_adapter.rb

@@ -3,7 +3,18 @@
 require "active_support/core_ext/string/inflections"
 
 module ActiveJob
-  # The <tt>ActiveJob::QueueAdapter</tt> module is used to load the
+  class << self
+    def adapter_name(adapter) # :nodoc:
+      return adapter.queue_adapter_name if adapter.respond_to?(:queue_adapter_name)
+
+      adapter_class = adapter.is_a?(Module) ? adapter : adapter.class
+      "#{adapter_class.name.demodulize.delete_suffix('Adapter')}"
+    end
+  end
+
+  # = Active Job Queue adapter
+  #
+  # The +ActiveJob::QueueAdapter+ module is used to load the
   # correct adapter. The default queue adapter is the +:async+ queue.
   module QueueAdapter # :nodoc:
     extend ActiveSupport::Concern
@@ -41,7 +52,7 @@ module ActiveJob
           assign_adapter(name_or_adapter.to_s, queue_adapter)
         else
           if queue_adapter?(name_or_adapter)
-            adapter_name = "#{name_or_adapter.class.name.demodulize.remove('Adapter').underscore}"
+            adapter_name = ActiveJob.adapter_name(name_or_adapter).underscore
             assign_adapter(adapter_name, name_or_adapter)
           else
             raise ArgumentError

data/lib/active_job/queue_adapters/async_adapter.rb

@@ -7,7 +7,7 @@ require "concurrent/utility/processor_counter"
 
 module ActiveJob
   module QueueAdapters
-    # == Active Job Async adapter
+    # = Active Job Async adapter
     #
     # The Async adapter runs jobs with an in-process thread pool.
     #
@@ -95,7 +95,7 @@ module ActiveJob
 
         def enqueue_at(job, timestamp, queue_name:)
           delay = timestamp - Time.current.to_f
-          if delay > 0
+          if !immediate && delay > 0
             Concurrent::ScheduledTask.execute(delay, args: [job], executor: executor, &:perform)
           else
             enqueue(job, queue_name: queue_name)

data/lib/active_job/queue_adapters/backburner_adapter.rb

@@ -4,7 +4,7 @@ require "backburner"
 
 module ActiveJob
   module QueueAdapters
-    # == Backburner adapter for Active Job
+    # = Backburner adapter for Active Job
     #
     # Backburner is a beanstalkd-powered job queue that can handle a very
     # high volume of jobs. You create background jobs and place them on
@@ -16,12 +16,16 @@ module ActiveJob
     #   Rails.application.config.active_job.queue_adapter = :backburner
     class BackburnerAdapter
       def enqueue(job) # :nodoc:
-        Backburner::Worker.enqueue(JobWrapper, [job.serialize], queue: job.queue_name, pri: job.priority)
+        response = Backburner::Worker.enqueue(JobWrapper, [job.serialize], queue: job.queue_name, pri: job.priority)
+        job.provider_job_id = response[:id] if response.is_a?(Hash)
+        response
       end
 
       def enqueue_at(job, timestamp) # :nodoc:
         delay = timestamp - Time.current.to_f
-        Backburner::Worker.enqueue(JobWrapper, [job.serialize], queue: job.queue_name, pri: job.priority, delay: delay)
+        response = Backburner::Worker.enqueue(JobWrapper, [job.serialize], queue: job.queue_name, pri: job.priority, delay: delay)
+        job.provider_job_id = response[:id] if response.is_a?(Hash)
+        response
       end
 
       class JobWrapper # :nodoc:

data/lib/active_job/queue_adapters/delayed_job_adapter.rb

@@ -5,7 +5,7 @@ require "active_support/core_ext/string/inflections"
 
 module ActiveJob
   module QueueAdapters
-    # == Delayed Job adapter for Active Job
+    # = Delayed Job adapter for Active Job
     #
     # Delayed::Job (or DJ) encapsulates the common pattern of asynchronously
     # executing longer tasks in the background. Although DJ can have many

data/lib/active_job/queue_adapters/inline_adapter.rb

@@ -2,7 +2,7 @@
 
 module ActiveJob
   module QueueAdapters
-    # == Active Job Inline adapter
+    # = Active Job Inline adapter
     #
     # When enqueuing jobs with the Inline adapter the job will be executed
     # immediately.

data/lib/active_job/queue_adapters/queue_classic_adapter.rb

@@ -4,7 +4,7 @@ require "queue_classic"
 
 module ActiveJob
   module QueueAdapters
-    # == queue_classic adapter for Active Job
+    # = queue_classic adapter for Active Job
     #
     # queue_classic provides a simple interface to a PostgreSQL-backed message
     # queue. queue_classic specializes in concurrent locking and minimizing
@@ -37,10 +37,10 @@ module ActiveJob
         qc_job
       end
 
-      # Builds a <tt>QC::Queue</tt> object to schedule jobs on.
+      # Builds a +QC::Queue+ object to schedule jobs on.
       #
-      # If you have a custom <tt>QC::Queue</tt> subclass you'll need to subclass
-      # <tt>ActiveJob::QueueAdapters::QueueClassicAdapter</tt> and override the
+      # If you have a custom +QC::Queue+ subclass you'll need to subclass
+      # +ActiveJob::QueueAdapters::QueueClassicAdapter+ and override the
       # <tt>build_queue</tt> method.
       def build_queue(queue_name)
         QC::Queue.new(queue_name)

data/lib/active_job/queue_adapters/resque_adapter.rb

@@ -16,7 +16,7 @@ end
 
 module ActiveJob
   module QueueAdapters
-    # == Resque adapter for Active Job
+    # = Resque adapter for Active Job
     #
     # Resque (pronounced like "rescue") is a Redis-backed library for creating
     # background jobs, placing those jobs on multiple queues, and processing