activejob 5.2.3

data/lib/active_job/callbacks.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "active_support/callbacks"
+
+module ActiveJob
+  # = Active Job Callbacks
+  #
+  # Active Job provides hooks during the life cycle of a job. Callbacks allow you
+  # to trigger logic during this cycle. Available callbacks are:
+  #
+  # * <tt>before_enqueue</tt>
+  # * <tt>around_enqueue</tt>
+  # * <tt>after_enqueue</tt>
+  # * <tt>before_perform</tt>
+  # * <tt>around_perform</tt>
+  # * <tt>after_perform</tt>
+  #
+  # NOTE: Calling the same callback multiple times will overwrite previous callback definitions.
+  #
+  module Callbacks
+    extend  ActiveSupport::Concern
+    include ActiveSupport::Callbacks
+
+    class << self
+      include ActiveSupport::Callbacks
+      define_callbacks :execute
+    end
+
+    included do
+      define_callbacks :perform
+      define_callbacks :enqueue
+    end
+
+    # These methods will be included into any Active Job object, adding
+    # callbacks for +perform+ and +enqueue+ methods.
+    module ClassMethods
+      # Defines a callback that will get called right before the
+      # job's perform method is executed.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     before_perform do |job|
+      #       UserMailer.notify_video_started_processing(job.arguments.first)
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      def before_perform(*filters, &blk)
+        set_callback(:perform, :before, *filters, &blk)
+      end
+
+      # Defines a callback that will get called right after the
+      # job's perform method has finished.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     after_perform do |job|
+      #       UserMailer.notify_video_processed(job.arguments.first)
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      def after_perform(*filters, &blk)
+        set_callback(:perform, :after, *filters, &blk)
+      end
+
+      # Defines a callback that will get called around the job's perform method.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     around_perform 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
+      #
+      def around_perform(*filters, &blk)
+        set_callback(:perform, :around, *filters, &blk)
+      end
+
+      # Defines a callback that will get called right before the
+      # job is enqueued.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     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 < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     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 enqueueing
+      # of the job.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     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
+  end
+end

data/lib/active_job/configured_job.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  class ConfiguredJob #:nodoc:
+    def initialize(job_class, options = {})
+      @options = options
+      @job_class = job_class
+    end
+
+    def perform_now(*args)
+      @job_class.new(*args).perform_now
+    end
+
+    def perform_later(*args)
+      @job_class.new(*args).enqueue @options
+    end
+  end
+end

data/lib/active_job/core.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  # Provides general behavior that will be included into every Active Job
+  # object that inherits from ActiveJob::Base.
+  module Core
+    extend ActiveSupport::Concern
+
+    included do
+      # Job arguments
+      attr_accessor :arguments
+      attr_writer :serialized_arguments
+
+      # Timestamp when the job should be performed
+      attr_accessor :scheduled_at
+
+      # Job Identifier
+      attr_accessor :job_id
+
+      # Queue in which the job will reside.
+      attr_writer :queue_name
+
+      # Priority that the job will have (lower is more priority).
+      attr_writer :priority
+
+      # 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
+
+      # I18n.locale to be used during the job.
+      attr_accessor :locale
+    end
+
+    # These methods will be included into any Active Job object, adding
+    # helpers for de/serialization and creation of job instances.
+    module ClassMethods
+      # Creates a new job instance from a hash created with +serialize+
+      def deserialize(job_data)
+        job = job_data["job_class"].constantize.new
+        job.deserialize(job_data)
+        job
+      end
+
+      # Creates a job preconfigured with the given options. You can call
+      # perform_later with the job arguments to enqueue the job with the
+      # preconfigured options
+      #
+      # ==== Options
+      # * <tt>:wait</tt> - Enqueues the job with the specified delay
+      # * <tt>:wait_until</tt> - Enqueues the job at the time specified
+      # * <tt>:queue</tt> - Enqueues the job on the specified queue
+      # * <tt>:priority</tt> - Enqueues the job with the specified priority
+      #
+      # ==== Examples
+      #
+      #    VideoJob.set(queue: :some_queue).perform_later(Video.last)
+      #    VideoJob.set(wait: 5.minutes).perform_later(Video.last)
+      #    VideoJob.set(wait_until: Time.now.tomorrow).perform_later(Video.last)
+      #    VideoJob.set(queue: :some_queue, wait: 5.minutes).perform_later(Video.last)
+      #    VideoJob.set(queue: :some_queue, wait_until: Time.now.tomorrow).perform_later(Video.last)
+      #    VideoJob.set(queue: :some_queue, wait: 5.minutes, priority: 10).perform_later(Video.last)
+      def set(options = {})
+        ConfiguredJob.new(self, options)
+      end
+    end
+
+    # Creates a new job instance. Takes the arguments that will be
+    # passed to the perform method.
+    def initialize(*arguments)
+      @arguments  = arguments
+      @job_id     = SecureRandom.uuid
+      @queue_name = self.class.queue_name
+      @priority   = self.class.priority
+      @executions = 0
+    end
+
+    # Returns a hash with the job data that can safely be passed to the
+    # queueing adapter.
+    def serialize
+      {
+        "job_class"  => self.class.name,
+        "job_id"     => job_id,
+        "provider_job_id" => provider_job_id,
+        "queue_name" => queue_name,
+        "priority"   => priority,
+        "arguments"  => serialize_arguments_if_needed(arguments),
+        "executions" => executions,
+        "locale"     => I18n.locale.to_s
+      }
+    end
+
+    # Attaches the stored job data to the current instance. Receives a hash
+    # returned from +serialize+
+    #
+    # ==== Examples
+    #
+    #    class DeliverWebhookJob < ActiveJob::Base
+    #      attr_writer :attempt_number
+    #
+    #      def attempt_number
+    #        @attempt_number ||= 0
+    #      end
+    #
+    #      def serialize
+    #        super.merge('attempt_number' => attempt_number + 1)
+    #      end
+    #
+    #      def deserialize(job_data)
+    #        super
+    #        self.attempt_number = job_data['attempt_number']
+    #      end
+    #
+    #      rescue_from(Timeout::Error) do |exception|
+    #        raise exception if attempt_number > 5
+    #        retry_job(wait: 10)
+    #      end
+    #    end
+    def deserialize(job_data)
+      self.job_id               = job_data["job_id"]
+      self.provider_job_id      = job_data["provider_job_id"]
+      self.queue_name           = job_data["queue_name"]
+      self.priority             = job_data["priority"]
+      self.serialized_arguments = job_data["arguments"]
+      self.executions           = job_data["executions"]
+      self.locale               = job_data["locale"] || I18n.locale.to_s
+    end
+
+    private
+      def serialize_arguments_if_needed(arguments)
+        if arguments_serialized?
+          @serialized_arguments
+        else
+          serialize_arguments(arguments)
+        end
+      end
+
+      def deserialize_arguments_if_needed
+        if arguments_serialized?
+          @arguments = deserialize_arguments(@serialized_arguments)
+          @serialized_arguments = nil
+        end
+      end
+
+      def serialize_arguments(arguments)
+        Arguments.serialize(arguments)
+      end
+
+      def deserialize_arguments(serialized_args)
+        Arguments.deserialize(serialized_args)
+      end
+
+      def arguments_serialized?
+        defined?(@serialized_arguments) && @serialized_arguments
+      end
+  end
+end

data/lib/active_job/enqueuing.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "active_job/arguments"
+
+module ActiveJob
+  # Provides behavior for enqueuing jobs.
+  module Enqueuing
+    extend ActiveSupport::Concern
+
+    # 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.
+      #
+      # Returns an instance of the job class queued with arguments available in
+      # Job#arguments.
+      def perform_later(*args)
+        job_or_instantiate(*args).enqueue
+      end
+
+      private
+        def job_or_instantiate(*args) # :doc:
+          args.first.is_a?(self) ? args.first : new(*args)
+        end
+    end
+
+    # Enqueues the job to be performed by the queue adapter.
+    #
+    # ==== Options
+    # * <tt>:wait</tt> - Enqueues the job with the specified delay
+    # * <tt>:wait_until</tt> - Enqueues the job at the time specified
+    # * <tt>:queue</tt> - Enqueues the job on the specified queue
+    # * <tt>:priority</tt> - Enqueues the job with the specified priority
+    #
+    # ==== Examples
+    #
+    #    my_job_instance.enqueue
+    #    my_job_instance.enqueue wait: 5.minutes
+    #    my_job_instance.enqueue queue: :important
+    #    my_job_instance.enqueue wait_until: Date.tomorrow.midnight
+    #    my_job_instance.enqueue priority: 10
+    def enqueue(options = {})
+      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.queue_name   = self.class.queue_name_from_part(options[:queue]) if options[:queue]
+      self.priority     = options[:priority].to_i if options[:priority]
+      run_callbacks :enqueue do
+        if scheduled_at
+          self.class.queue_adapter.enqueue_at self, scheduled_at
+        else
+          self.class.queue_adapter.enqueue self
+        end
+      end
+      self
+    end
+  end
+end

data/lib/active_job/exceptions.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/numeric/time"
+
+module ActiveJob
+  # Provides behavior for retrying and discarding jobs on exceptions.
+  module Exceptions
+    extend ActiveSupport::Concern
+
+    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
+      # bubble up to the underlying queuing system, which may have its own retry mechanism or place it in a
+      # holding queue for inspection.
+      #
+      # 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.
+      #
+      # ==== 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)
+      # * <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
+      #
+      # ==== Examples
+      #
+      #  class RemoteServiceJob < ActiveJob::Base
+      #    retry_on CustomAppException # defaults to 3s wait, 5 attempts
+      #    retry_on AnotherCustomAppException, wait: ->(executions) { executions * 2 }
+      #    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
+      #    end
+      #  end
+      def retry_on(exception, wait: 3.seconds, attempts: 5, queue: nil, priority: nil)
+        rescue_from exception do |error|
+          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
+          else
+            if block_given?
+              yield self, error
+            else
+              logger.error "Stopped retrying #{self.class} due to a #{exception}, which reoccurred on #{executions} attempts. The original exception was #{error.cause.inspect}."
+              raise error
+            end
+          end
+        end
+      end
+
+      # Discard the job with no attempts to retry, if the exception is raised. This is useful when the subject of the job,
+      # like an Active Record, is no longer available, and the job is thus no longer relevant.
+      #
+      # 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.
+      #
+      # ==== Example
+      #
+      #  class SearchIndexingJob < ActiveJob::Base
+      #    discard_on ActiveJob::DeserializationError
+      #    discard_on(CustomAppException) do |job, error|
+      #      ExceptionNotifier.caught(error)
+      #    end
+      #
+      #    def perform(record)
+      #      # Will raise ActiveJob::DeserializationError if the record can't be deserialized
+      #      # 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}."
+          end
+        end
+      end
+    end
+
+    # Reschedules the job to be re-executed. This is useful in combination
+    # with the +rescue_from+ option. When you rescue an exception from your job
+    # you can ask Active Job to retry performing your job.
+    #
+    # ==== Options
+    # * <tt>:wait</tt> - Enqueues the job with the specified delay in seconds
+    # * <tt>:wait_until</tt> - Enqueues the job at the time specified
+    # * <tt>:queue</tt> - Enqueues the job on the specified queue
+    # * <tt>:priority</tt> - Enqueues the job with the specified priority
+    #
+    # ==== Examples
+    #
+    #  class SiteScraperJob < ActiveJob::Base
+    #    rescue_from(ErrorLoadingSite) do
+    #      retry_job queue: :low_priority
+    #    end
+    #
+    #    def perform(*args)
+    #      # raise ErrorLoadingSite if cannot scrape
+    #    end
+    #  end
+    def retry_job(options = {})
+      enqueue options
+    end
+
+    private
+      def determine_delay(seconds_or_duration_or_algorithm)
+        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
+        when Proc
+          algorithm = seconds_or_duration_or_algorithm
+          algorithm.call(executions)
+        else
+          raise "Couldn't determine a delay based on #{seconds_or_duration_or_algorithm.inspect}"
+        end
+      end
+  end
+end