diff --git a/activejob/lib/active_job/base.rb b/activejob/lib/active_job/base.rb
index ff5c69ddc6f..94a1faba3f3 100644
--- a/activejob/lib/active_job/base.rb
+++ b/activejob/lib/active_job/base.rb
@@ -5,6 +5,7 @@ require 'active_job/queue_priority'
require 'active_job/enqueuing'
require 'active_job/execution'
require 'active_job/callbacks'
+require 'active_job/exceptions'
require 'active_job/logging'
require 'active_job/translation'
@@ -62,6 +63,7 @@ module ActiveJob #:nodoc:
include Enqueuing
include Execution
include Callbacks
+ include Exceptions
include Logging
include Translation
diff --git a/activejob/lib/active_job/core.rb b/activejob/lib/active_job/core.rb
index f0606b3834d..a9ddd029a83 100644
--- a/activejob/lib/active_job/core.rb
+++ b/activejob/lib/active_job/core.rb
@@ -24,6 +24,9 @@ module ActiveJob
# 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
@@ -68,6 +71,7 @@ module ActiveJob
@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
@@ -79,6 +83,7 @@ module ActiveJob
'queue_name' => queue_name,
'priority' => priority,
'arguments' => serialize_arguments(arguments),
+ 'executions' => executions + 1,
'locale' => I18n.locale.to_s
}
end
@@ -109,6 +114,7 @@ module ActiveJob
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
diff --git a/activejob/lib/active_job/enqueuing.rb b/activejob/lib/active_job/enqueuing.rb
index 9dc3c0fa576..7bc0fe6c3a0 100644
--- a/activejob/lib/active_job/enqueuing.rb
+++ b/activejob/lib/active_job/enqueuing.rb
@@ -1,7 +1,7 @@
require 'active_job/arguments'
module ActiveJob
- # Provides behavior for enqueuing and retrying jobs.
+ # Provides behavior for enqueuing jobs.
module Enqueuing
extend ActiveSupport::Concern
@@ -24,31 +24,6 @@ module ActiveJob
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
- # * :wait - Enqueues the job with the specified delay
- # * :wait_until - Enqueues the job at the time specified
- # * :queue - Enqueues the job on the specified queue
- # * :priority - 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
-
# Enqueues the job to be performed by the queue adapter.
#
# ==== Options
diff --git a/activejob/lib/active_job/exceptions.rb b/activejob/lib/active_job/exceptions.rb
new file mode 100644
index 00000000000..4217b5dc652
--- /dev/null
+++ b/activejob/lib/active_job/exceptions.rb
@@ -0,0 +1,78 @@
+require 'active_job/arguments'
+
+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.
+ #
+ # ==== Options
+ # * :wait - Re-enqueues the job with the specified delay in seconds
+ # * :attempts - Re-enqueues the job the specified number of times
+ #
+ # ==== Examples
+ #
+ # class RemoteServiceJob < ActiveJob::Base
+ # retry_on Net::OpenTimeout, wait: 30.seconds, attempts: 10
+ #
+ # def perform(*args)
+ # # Might raise Net::OpenTimeout when the remote service is down
+ # end
+ # end
+ def retry_on(exception, wait: 3.seconds, attempts: 5)
+ rescue_from exception do |error|
+ logger.error "Retrying #{self.class} in #{wait} seconds, due to a #{exception}. The original exception was #{error.cause.inspect}."
+ retry_job wait: wait if executions < attempts
+ 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.
+ #
+ # ==== Example
+ #
+ # class SearchIndexingJob < ActiveJob::Base
+ # discard_on ActiveJob::DeserializationError
+ #
+ # def perform(record)
+ # # Will raise ActiveJob::DeserializationError if the record can't be deserialized
+ # end
+ # end
+ def discard_on(exception)
+ rescue_from exception do |error|
+ logger.error "Discarded #{self.class} due to a #{exception}. The original exception was #{error.cause.inspect}."
+ 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
+ # * :wait - Enqueues the job with the specified delay in seconds
+ # * :wait_until - Enqueues the job at the time specified
+ # * :queue - Enqueues the job on the specified queue
+ # * :priority - 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
+ end
+end
diff --git a/activejob/test/cases/exceptions_test.rb b/activejob/test/cases/exceptions_test.rb
new file mode 100644
index 00000000000..42d4dd78a59
--- /dev/null
+++ b/activejob/test/cases/exceptions_test.rb
@@ -0,0 +1,47 @@
+require 'helper'
+require 'jobs/retry_job'
+
+class ExceptionsTest < ActiveSupport::TestCase
+ setup do
+ JobBuffer.clear
+ end
+
+ test "successfully retry job throwing exception against defaults" do
+ RetryJob.perform_later 'SeriousError', 5
+
+ assert_equal [
+ "Raised SeriousError for the 1st time",
+ "Raised SeriousError for the 2nd time",
+ "Raised SeriousError for the 3rd time",
+ "Raised SeriousError for the 4th time",
+ "Successfully completed job" ], JobBuffer.values
+ end
+
+ test "successfully retry job throwing exception against higher limit" do
+ RetryJob.perform_later 'VerySeriousError', 9
+ assert_equal 9, JobBuffer.values.count
+ end
+
+ test "failed retry job when exception kept occurring against defaults" do
+ begin
+ RetryJob.perform_later 'SeriousError', 6
+ assert_equal "Raised SeriousError for the 5th time", JobBuffer.last_value
+ rescue SeriousError
+ pass
+ end
+ end
+
+ test "failed retry job when exception kept occurring against higher limit" do
+ begin
+ RetryJob.perform_later 'VerySeriousError', 11
+ assert_equal "Raised VerySeriousError for the 10th time", JobBuffer.last_value
+ rescue SeriousError
+ pass
+ end
+ end
+
+ test "discard job" do
+ RetryJob.perform_later 'NotSeriousError', 2
+ assert_equal "Raised NotSeriousError for the 1st time", JobBuffer.last_value
+ end
+end
diff --git a/activejob/test/jobs/retry_job.rb b/activejob/test/jobs/retry_job.rb
new file mode 100644
index 00000000000..2e05f95bf6a
--- /dev/null
+++ b/activejob/test/jobs/retry_job.rb
@@ -0,0 +1,21 @@
+require_relative '../support/job_buffer'
+require 'active_support/core_ext/integer/inflections'
+
+class SeriousError < StandardError; end
+class VerySeriousError < StandardError; end
+class NotSeriousError < StandardError; end
+
+class RetryJob < ActiveJob::Base
+ retry_on SeriousError
+ retry_on VerySeriousError, wait: 1.second, attempts: 10
+ discard_on NotSeriousError
+
+ def perform(raising, attempts)
+ if executions < attempts
+ JobBuffer.add("Raised #{raising} for the #{executions.ordinalize} time")
+ raise raising.constantize
+ else
+ JobBuffer.add("Successfully completed job")
+ end
+ end
+end