Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Added global sane retry_on defaults to all Spree jobs (#14068)

Damian Legawiecfcf4145259c1
diff --git a/spree/api/app/jobs/spree/webhook_delivery_job.rb b/spree/api/app/jobs/spree/webhook_delivery_job.rb
index da423cebfa..0e69b8fe93 100644
--- a/spree/api/app/jobs/spree/webhook_delivery_job.rb
+++ b/spree/api/app/jobs/spree/webhook_delivery_job.rb
@@ -4,7 +4,12 @@ module Spree
class WebhookDeliveryJob < Spree::BaseJob
queue_as Spree.queues.webhooks
+ # Webhook delivery hits external endpoints; broad retry covers network timeouts,
+ # 5xx, DNS failures, etc.
retry_on StandardError, wait: :polynomially_longer, attempts: 5
+ # Must come after `retry_on StandardError` so DeserializationError lands in discard
+ # (ActiveJob handler lookup is reverse-declaration-order).
+ discard_on ActiveJob::DeserializationError
# Accept optional second argument for backward compatibility with jobs
# enqueued before this change was deployed.
diff --git a/spree/api/spec/jobs/spree/webhook_delivery_job_spec.rb b/spree/api/spec/jobs/spree/webhook_delivery_job_spec.rb
index 1027adf572..61bd5a819d 100644
--- a/spree/api/spec/jobs/spree/webhook_delivery_job_spec.rb
+++ b/spree/api/spec/jobs/spree/webhook_delivery_job_spec.rb
@@ -53,6 +53,19 @@ module Spree
# Verify the job class has retry behavior configured
expect(described_class.ancestors).to include(ActiveJob::Exceptions)
end
+
+ # ActiveJob handler lookup is reverse-declaration-order. Because this job
+ # declares `retry_on StandardError` and `ActiveJob::DeserializationError < StandardError`,
+ # the parent's `discard_on ActiveJob::DeserializationError` would be shadowed
+ # if this job didn't re-declare the discard *after* the retry. Without that
+ # re-declaration, a deserialization failure would retry forever.
+ it 'discards DeserializationError instead of retrying' do
+ last_matching = described_class.rescue_handlers.reverse_each.detect do |class_or_name, _|
+ rescued = class_or_name.is_a?(String) ? class_or_name.constantize : class_or_name
+ rescued >= ActiveJob::DeserializationError
+ end
+ expect(last_matching&.first.to_s).to eq('ActiveJob::DeserializationError')
+ end
end
end
end
diff --git a/spree/core/app/jobs/spree/base_job.rb b/spree/core/app/jobs/spree/base_job.rb
index 642867e1d2..10caa5fb6a 100644
--- a/spree/core/app/jobs/spree/base_job.rb
+++ b/spree/core/app/jobs/spree/base_job.rb
@@ -1,5 +1,23 @@
module Spree
+ # Shared base for every Spree job.
+ #
+ # Retries only transient infrastructure errors. Broad replay is unsafe here because
+ # most jobs have non-idempotent post-work side effects (counters, state transitions,
+ # lifecycle events, external calls); jobs whose work is retry-safe opt in to
+ # `retry_on StandardError` themselves (see `Spree::WebhookDeliveryJob`,
+ # `Spree::Events::SubscriberJob`). RecordNotFound gets its own tighter policy
+ # to absorb the Sidekiq enqueue-vs-DB-commit race (sub-second window) without
+ # holding the queue for genuine deletes.
class BaseJob < ApplicationJob
queue_as Spree.queues.default
+
+ retry_on ActiveRecord::Deadlocked,
+ ActiveRecord::LockWaitTimeout,
+ ActiveRecord::ConnectionNotEstablished,
+ ActiveRecord::ConnectionFailed,
+ wait: :polynomially_longer, attempts: 5
+ retry_on ActiveRecord::RecordNotFound, wait: 2.seconds, attempts: 3
+
+ discard_on ActiveJob::DeserializationError
end
end
diff --git a/spree/core/app/jobs/spree/events/subscriber_job.rb b/spree/core/app/jobs/spree/events/subscriber_job.rb
index d387aa166c..d4ae9d7617 100644
--- a/spree/core/app/jobs/spree/events/subscriber_job.rb
+++ b/spree/core/app/jobs/spree/events/subscriber_job.rb
@@ -16,7 +16,8 @@ module Spree
class SubscriberJob < Spree::BaseJob
queue_as Spree.queues.events
- # Retry configuration
+ # Subscribers run user-defined code that can hit external services; broad retry
+ # is intentional.
retry_on StandardError, wait: :polynomially_longer, attempts: 3
discard_on ActiveJob::DeserializationError do |job, error|
diff --git a/spree/core/app/jobs/spree/exports/generate_job.rb b/spree/core/app/jobs/spree/exports/generate_job.rb
index 9ae56963c6..1dc110d0a6 100644
--- a/spree/core/app/jobs/spree/exports/generate_job.rb
+++ b/spree/core/app/jobs/spree/exports/generate_job.rb
@@ -3,6 +3,17 @@ module Spree
class GenerateJob < Spree::BaseJob
queue_as Spree.queues.exports
+ # `Export#generate` is not retry-safe: each call re-attaches a new ActiveStorage
+ # blob (leaving the prior one orphaned) and re-enqueues the completion email.
+ # Opt out of the parent's retry policy so transient errors fail fast into the
+ # dead queue for operator review rather than producing duplicate side effects.
+ retry_on ActiveRecord::Deadlocked,
+ ActiveRecord::LockWaitTimeout,
+ ActiveRecord::ConnectionNotEstablished,
+ ActiveRecord::ConnectionFailed,
+ ActiveRecord::RecordNotFound,
+ attempts: 1
+
def perform(export_id)
export = Spree::Export.find_by_prefix_id!(export_id)
export.generate
diff --git a/spree/core/app/jobs/spree/imports/base_job.rb b/spree/core/app/jobs/spree/imports/base_job.rb
index 3c742ca394..3ef71d23d7 100644
--- a/spree/core/app/jobs/spree/imports/base_job.rb
+++ b/spree/core/app/jobs/spree/imports/base_job.rb
@@ -2,30 +2,14 @@ module Spree
module Imports
# Shared base for every job in the imports pipeline.
#
- # Retry policy is intentionally narrow: only transient infrastructure errors
- # (DB deadlocks, lock-wait timeouts, dropped connections) are replayed. Broad
- # `retry_on StandardError` would replay jobs whose post-work side effects
- # (counter increments, state transitions, lifecycle events) had already
- # partially fired, breaking idempotency. Per-row business errors are caught
- # inside `Spree::ImportRow#process!` and converted to `row.fail!`, so they
- # never bubble up to the job layer.
- #
- # Subclasses may extend the retry list (e.g. `CreateCategoriesJob` adds
- # `RecordNotUnique` to recover from concurrent-import taxon creation races).
- #
- # We intentionally do NOT `discard_on ActiveRecord::RecordNotFound`: Sidekiq is
- # known to start a job before the enqueuing transaction has committed, so an
- # early `find` can raise `RecordNotFound` for a record that will exist a moment
- # later. Letting the job retry covers that window.
+ # The narrow transient-error retry policy is inherited from `Spree::BaseJob`;
+ # we only override the queue here. Per-row business errors are caught inside
+ # `Spree::ImportRow#process!` and converted to `row.fail!`, so they never
+ # bubble up to the job layer. Subclasses may extend the retry list (e.g.
+ # `CreateCategoriesJob` adds `RecordNotUnique` to recover from concurrent
+ # taxon creation races).
class BaseJob < Spree::BaseJob
queue_as Spree.queues.imports
-
- retry_on ActiveRecord::Deadlocked, ActiveRecord::LockWaitTimeout,
- ActiveRecord::ConnectionNotEstablished, ActiveRecord::ConnectionFailed,
- ActiveRecord::RecordNotFound,
- wait: :polynomially_longer, attempts: 5
-
- discard_on ActiveJob::DeserializationError
end
end
end
diff --git a/spree/core/app/jobs/spree/reports/generate_job.rb b/spree/core/app/jobs/spree/reports/generate_job.rb
index b9ebe7f9e9..5738c4bdc3 100644
--- a/spree/core/app/jobs/spree/reports/generate_job.rb
+++ b/spree/core/app/jobs/spree/reports/generate_job.rb
@@ -3,6 +3,17 @@ module Spree
class GenerateJob < Spree::BaseJob
queue_as Spree.queues.reports
+ # `Report#generate` is not retry-safe: each call re-attaches a new ActiveStorage
+ # blob (leaving the prior one orphaned) and re-enqueues the completion email.
+ # Opt out of the parent's retry policy so transient errors fail fast into the
+ # dead queue for operator review rather than producing duplicate side effects.
+ retry_on ActiveRecord::Deadlocked,
+ ActiveRecord::LockWaitTimeout,
+ ActiveRecord::ConnectionNotEstablished,
+ ActiveRecord::ConnectionFailed,
+ ActiveRecord::RecordNotFound,
+ attempts: 1
+
def perform(report_id)
report = Spree::Report.find_by_prefix_id!(report_id)
report.generate
diff --git a/spree/core/app/jobs/spree/search_provider/index_job.rb b/spree/core/app/jobs/spree/search_provider/index_job.rb
index b4e2e19484..1969834dce 100644
--- a/spree/core/app/jobs/spree/search_provider/index_job.rb
+++ b/spree/core/app/jobs/spree/search_provider/index_job.rb
@@ -3,8 +3,12 @@ module Spree
class IndexJob < Spree::BaseJob
queue_as Spree.queues.search
+ # Search providers are external services (Meilisearch, etc.); a transient 5xx or
+ # network blip should not drop the index update.
retry_on StandardError, wait: :polynomially_longer, attempts: 5
- discard_on ActiveRecord::RecordNotFound
+ # Must come after `retry_on StandardError` so DeserializationError lands in discard
+ # (ActiveJob handler lookup is reverse-declaration-order).
+ discard_on ActiveJob::DeserializationError
# @param resource_class [String] e.g. 'Spree::Product'
# @param resource_id [String] always pass as string for UUID support
diff --git a/spree/core/app/jobs/spree/search_provider/remove_job.rb b/spree/core/app/jobs/spree/search_provider/remove_job.rb
index b4796c9810..3e9ab7ee41 100644
--- a/spree/core/app/jobs/spree/search_provider/remove_job.rb
+++ b/spree/core/app/jobs/spree/search_provider/remove_job.rb
@@ -3,7 +3,11 @@ module Spree
class RemoveJob < Spree::BaseJob
queue_as Spree.queues.search
+ # Search providers are external services; broad retry covers network blips and 5xx.
retry_on StandardError, wait: :polynomially_longer, attempts: 5
+ # Must come after `retry_on StandardError` so DeserializationError lands in discard
+ # (ActiveJob handler lookup is reverse-declaration-order).
+ discard_on ActiveJob::DeserializationError
# @param prefixed_id [String] prefixed ID of the document to remove (e.g. 'prod_abc')
# @param store_id [String] always pass as string for UUID support
diff --git a/spree/core/spec/jobs/spree/base_job_spec.rb b/spree/core/spec/jobs/spree/base_job_spec.rb
new file mode 100644
index 0000000000..94b6323215
--- /dev/null
+++ b/spree/core/spec/jobs/spree/base_job_spec.rb
@@ -0,0 +1,62 @@
+require 'spec_helper'
+
+RSpec.describe Spree::BaseJob, type: :job do
+ # Pins the default retry/discard policy that every Spree job inherits. Anyone
+ # changing this is making a global behavior change — the test failure is the
+ # signal to think about whether that's intentional.
+ describe 'default retry policy' do
+ let(:retry_handler_classes) do
+ described_class.rescue_handlers.map { |class_or_name, _handler| class_or_name }
+ end
+
+ it 'retries on transient DB infrastructure errors' do
+ expect(retry_handler_classes).to include(
+ 'ActiveRecord::Deadlocked',
+ 'ActiveRecord::LockWaitTimeout',
+ 'ActiveRecord::ConnectionNotEstablished',
+ 'ActiveRecord::ConnectionFailed'
+ )
+ end
+
+ it 'retries on RecordNotFound to absorb the Sidekiq enqueue-vs-commit race' do
+ expect(retry_handler_classes).to include('ActiveRecord::RecordNotFound')
+ end
+
+ it 'discards on ActiveJob::DeserializationError' do
+ expect(retry_handler_classes).to include('ActiveJob::DeserializationError')
+ end
+
+ it 'does NOT broadly retry on StandardError (each job opts in explicitly)' do
+ expect(retry_handler_classes).not_to include('StandardError')
+ end
+ end
+
+ # ActiveJob handler lookup is reverse-declaration-order. A subclass that declares
+ # `retry_on StandardError` shadows the parent's `discard_on ActiveJob::DeserializationError`
+ # (since DeserializationError < StandardError) unless the subclass re-declares the
+ # discard *after* its retry. These jobs intentionally do broad retry and must
+ # re-declare the discard to keep deserialization failures from retrying forever.
+ describe 'broad-retry subclasses re-declare discard_on DeserializationError' do
+ # Loading the API gem job from the core spec context: the spec_helper boots the
+ # core dummy app, which doesn't load spree_api, so reference it conditionally.
+ job_classes = [
+ 'Spree::SearchProvider::IndexJob',
+ 'Spree::SearchProvider::RemoveJob',
+ 'Spree::Events::SubscriberJob'
+ ]
+
+ job_classes.each do |class_name|
+ it "#{class_name} discards DeserializationError instead of retrying" do
+ klass = class_name.constantize
+ last_matching = klass.rescue_handlers.reverse_each.detect do |class_or_name, _|
+ rescued = class_or_name.is_a?(String) ? class_or_name.constantize : class_or_name
+ rescued >= ActiveJob::DeserializationError
+ end
+ expect(last_matching&.first.to_s).to eq('ActiveJob::DeserializationError'),
+ "expected #{class_name} to discard DeserializationError, but the most-recently-declared " \
+ "matching handler is for #{last_matching&.first.inspect}. Re-declare " \
+ "`discard_on ActiveJob::DeserializationError` AFTER `retry_on StandardError`."
+ end
+ end
+ end
+end