delayed 3.1.0 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40ac1d14d7043c15029a5e563ad4e278315f50cd99d947b97ecb5205cde483fa
-  data.tar.gz: 0e4d7ffd516267c28a2b2ab6468cfe383a5c486aaf4875ffeb92b72797af9e29
+  metadata.gz: a2b90a867a985a3bf32841f0cadac600d9d9f076d30bb04c85845c65b0e97ba9
+  data.tar.gz: 7b527829bd45c8f4bff4b6c62ea15ecc62aeca4461e74e2ff0b6f0c5a1800243
 SHA512:
-  metadata.gz: bfa5833f65f57e02447e6ace001d8cd0be205399ab5a108f1cc2d7ef13ce749b99b557f3bd36a79a9e4cb6e0ef37bd6c11746318013c9f084626a96b2fd4b1a4
-  data.tar.gz: 8aa12f59cbf61b68881853351cb19af8ff8b391014e3eacafe8f78e556dcf98bbde2a918fdb0b24386ea95d72d14ec43ec4a1af98db60ee297c4d31db071139a
+  metadata.gz: bbce505c6b79c92df2c69e56e288af6437304b8de87227058e03f31fbb9c20b6f86869c48936b170806e96469e744813e9674178d965ebdb8a4a69542da496ed
+  data.tar.gz: e6a9976ea79803f45875cddbe96639a9d2d760374ce82b8ddd3d61b7bc594abe9fcae8f2610c4e4952c026dfaf7e613db7fabed19c3bb499d3f98c0bbc6c4a93

data/README.md

@@ -54,6 +54,7 @@ migration paths where possible.
   * [Priority-based Alerting Threshholds](#priority-based-alerting-threshholds)
   * [Continuous Monitoring](#continuous-monitoring)
 * [Configuration](#configuration)
+* [Rate Limiting Jobs](#rate-limiting-jobs)
 * [Migrating from other ActiveJob backends](#migrating-from-other-activejob-backends)
   * [Migrating from DelayedJob](#migrating-from-delayedjob)
 * [How to Contribute](#how-to-contribute)
@@ -211,6 +212,28 @@ ActiveJob also supports the following lifecycle hooks:
 **Read more about ActiveJob usage on the [Active Job
 Basics](https://guides.rubyonrails.org/active_job_basics.html) documentation page.**
 
+#### Retries: `retry_on` vs. `max_attempts`
+
+ActiveJob and `delayed` each provide their own retry mechanisms, which can be used
+together or independently:
+
+- **`retry_on`** is ActiveJob's retry policy. Matching errors are caught by the job
+  itself and re-enqueued as new jobs, without triggering any of `delayed`'s backstop
+  behaviors (such as incrementing `attempts` or marking the job as failed). This is
+  useful for handling transient/expected errors and can be monitored via the
+  `enqueue_retry.active_job` ActiveSupport::Notification event. (See [ActiveJob's
+  documentation](https://guides.rubyonrails.org/v6.1/active_support_instrumentation.html#active-job)
+  for more details.)
+- **`max_attempts`** (25 by default) is `delayed`'s backstop. Any error that escapes
+  the ActiveJob layer without explicit handling will be caught by `delayed`,
+  incrementing the job's `attempts` counter and triggering all other
+  `delayed`-specific behaviors (like exponential backoff, metrics/alerting, and
+  eventual failure). These errors should be treated as unexpected/unhandled, and may
+  indicate a code bug or data issue that needs to be resolved before the job can
+  succeed.
+
+Importantly, `retry_on` always takes precedence over `max_attempts`, and when a
+`retry_on` policy is exhausted, the job will be failed permanently (i.e. `failed_at`).
 
 ## Operational Considerations
 
@@ -270,6 +293,9 @@ corner cases more gracefully (perhaps by no-opping). When you're ready to re-run
 Delayed::Job.find(failing_job_id).update!(failed_at: nil, attempts: 0, run_at: Time.zone.now)
 ```
 
+For ActiveJob-based jobs, resetting `attempts` to 0 will also restore the job's original
+`retry_on` budgets, allowing any exhausted retries to start over.
+
 ## Monitoring Jobs & Workers
 
 `Delayed` will emit `ActiveSupport::Notification`s at various points during job and worker
@@ -531,6 +557,138 @@ Delayed.logger = Rails.logger
 Delayed.default_log_level = 'info'
 ```
 
+## Rate Limiting Jobs
+
+The `Delayed::Limit` class provides a database-backed **concurrency limiter/optimizer** for jobs
+(via a [Generic Cell Rate Algorithm](https://en.wikipedia.org/wiki/Generic_cell_rate_algorithm)
+implemented in SQL+Ruby). Use it to (e.g.) stay under a third-party API's published rate limit, or
+to keep from overwhelming a downstream datastore.
+
+The recommended interface is `with_limit`, provided via the `Delayed::Limitable` module (which is
+included in all `ActiveJob` classes by default):
+
+```ruby
+class TouchesThirdPartyApiJob < ApplicationJob
+  with_limit :third_party_api, max: 100, per: 1.minute
+
+  def perform
+    # ...
+  end
+end
+```
+
+The limiter will then attempt to maximize throughput without exceeding the limit. If the limit would
+be exceeded within a configurable timeout, the job will immediately end and enqueue a retry attempt
+with polynomial backoff. Because its state lives in the database, the limit applies across every
+worker and process at once.
+
+Plain (non-ActiveJob) classes may `include Delayed::Limitable` to use `with_limit`, but they must
+define their own rescheduling/lifecycle behavior for `Delayed::Limit::LimitExceededError` errors.
+
+#### Setup
+
+To use this feature, make sure you have a `delayed_limits` table, or run `rake
+delayed:install:migrations` to add it (see [Database Setup](#database-setup)).
+
+As of now, **only PostgreSQL and SQLite (3.35+) are supported.** The primary SQL query relies on an
+upserting `RETURNING` clause and database-native timestamp arithmetic. You can check the current
+connection at runtime with `Delayed::Limit.supported?`. (Attempting to use the limiter on an
+unsupported database will raise `Delayed::Limit::UnsupportedDatabaseError`.)
+
+#### Traffic Shaping vs Traffic Enforcement
+
+By default, the limiter will `sleep` up to 5 seconds (or a specified `wait_timeout`) before
+yielding to the limited work. (This behavior is subject to the usual GIL and OS scheduling, so
+treat the configured rate as a best-effort target rather than a hard guarantee.)
+
+Use a longer `wait_timeout` for even better throughput smoothing (at the cost of blocking threads):
+
+```ruby
+# A longer wait timeout is best for shaping outbound traffic in asynchronous contexts.
+with_limit :outbound_traffic, max: 100, per: 1.minute, wait_timeout: 30.seconds
+```
+
+Or set it to `0` to fail fast, so that the job never blocks a worker thread:
+
+```ruby
+# A zero wait timeout is best for enforcing inbound limits and shedding excess traffic.
+with_limit :inbound_traffic, max: 5, per: 1.second, wait_timeout: 0
+```
+
+#### Customizing `with_limit`
+
+The purpose defaults to the job's underscored class name, so it may be omitted entirely if the
+limit is not shared with any other class:
+
+```ruby
+with_limit max: 100, per: 1.minute
+```
+
+Use `on:` to wrap one or more other instance methods instead of `perform` (e.g. if only a portion
+of the job's work is subject to the limit):
+
+```ruby
+with_limit :third_party_api, on: :deliver!
+```
+
+**For ActiveJob classes only**, use `retry_attempts:`, `retry_wait:`, and `retry_jitter:` to
+customize the retry behavior. (By default, jobs retry indefinitely with a polynomial backoff, with
+the `wait_timeout` acting as a floor on the computed wait.) If `with_limit` is declared multiple
+times on the same class (e.g. to apply different limits to different methods), only the first
+declaration defines the job's retry behavior.
+
+#### Manually Limiting a Block of Code
+
+To rate limit code that doesn't belong to a job class, call `Delayed::Limit.within_limit`
+directly. It accepts the same `purpose`, `max:`, `per:`, and `wait_timeout:` arguments as
+`with_limit`, and wraps the limited work in a block:
+
+```ruby
+Delayed::Limit.within_limit(:widgets_api, max: 100, per: 1.minute) do
+  WidgetsApi.create_widget!(...)
+end
+```
+
+The key difference is that there is no built-in retry behavior: if the limit would be exceeded
+within the `wait_timeout`, the call raises `Delayed::Limit::LimitExceededError` immediately, and
+it is up to the caller to rescue and/or retry.
+
+#### Shared Limits
+
+To avoid repeating the same purpose's `max` and `per` across multiple call sites, register a
+limit in advance (e.g. in an initializer):
+
+```ruby
+Delayed::Limit.register!(:widgets_api, max: 100, per: 1.minute)
+```
+
+Then, reference it by just its name at each declaration:
+
+```ruby
+with_limit :widgets_api
+
+# or:
+Delayed::Limit.within_limit(:widgets_api) { ... }
+```
+
+Registered limits are cached indefinitely in memory and are not thread-safe on write, so avoid
+registering them dynamically or at runtime!
+
+#### Handling "Burst" Throughput
+
+As of now, **there is no "burst" capacity.** The limiter allows one call per "drain interval" (`per
+/ max`), so a limit of 60-per-minute behaves identically to 1-per-second (and will not allow
+more than 1 call in the first second).
+
+This is generally acceptable for background job processing (and for traffic shaping in general), but
+may be revisited in the future in order to support use cases like API traffic enforcement.
+
+#### Monitoring Limit Usage
+
+Each call emits an `ActiveSupport::Notification` (`delayed.limit.within_limit` or
+`delayed.limit.exceeded`), so you can monitor limiting activity the same way you would any other
+event (see [Monitoring Jobs & Workers](#monitoring-jobs--workers)).
+
 ## Migrating from other ActiveJob backends
 
 For the most part, standard ActiveJob APIs should be fully compatible. However, when migrating from

data/app/models/delayed/limit.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Delayed
+  # A database-backed concurrency limiter/optimizer designed for use with
+  # `Delayed::Job`. Given a 'purpose' (stringy identifier), a limit, and a time
+  # interval, it will attempt to maximize throughput without exceeding the limit
+  # ("traffic shaping"). The `wait_timeout` parameter can also be lowered (from
+  # its default of `5.seconds`) in order to shed load more proactively ("traffic
+  # enforcement").
+  #
+  # Because the algorithm relies on database-specific timestamp arithmetic and
+  # an upserting `RETURNING` clause, only PostgreSQL and SQLite (3.35+) are
+  # supported. (See `.supported?`.)
+  #
+  # Wrap the work you want to limit in a block, and the limiter will either
+  # yield to the block (within the configured `wait_timeout`) or raise
+  # `LimitExceededError` immediately (if the `wait_timeout` would be exceeded):
+  #
+  #   Delayed::Limit.within_limit(:emails, max: 100, per: 1.minute) do
+  #     deliver_email!
+  #   end
+  #
+  # Currently, the limiter does not support "burst" capacity. A limit of 60
+  # req/minute will behave identically to a limit of 1 req/second, because the
+  # limiter only allows a single call per "drain interval" (`per / max`). When
+  # combined with the `wait_timeout`, this degree of smoothing is acceptable for
+  # background job processing (and traffic shaping in general), but may be
+  # revisited in the future to support more types of workloads.
+  #
+  # To share a limit across multiple calls, register a named 'purpose' in
+  # advance (e.g. in an initializer) and then reference it by name later:
+  #
+  #   Delayed::Limit.register!(:emails, max: 100, per: 1.minute)
+  #
+  #   Delayed::Limit.within_limit(:emails, wait_timeout: 10.seconds) do
+  #     deliver_email!
+  #   end
+  #
+  # It is **not** recommended to register limits dynamically at runtime, because
+  # registered limits are cached indefinitely in memory and are not thread-safe.
+  class Limit < ActiveRecord::Base
+    self.table_name = 'delayed_limits'
+
+    # SQLite gained support for the `RETURNING` clause in version 3.35.
+    MINIMUM_SQLITE_VERSION = Gem::Version.new('3.35.0')
+    SECONDS_PER_DAY = 86_400.0
+
+    # Raised when limit adherence would require exceeding the `wait_timeout`.
+    class LimitExceededError < StandardError; end
+
+    # Raised when the database adapter/version does not support the limiter
+    # (see `.supported?`).
+    class UnsupportedDatabaseError < StandardError; end
+
+    class << self
+      # Used only for limits registered in advance (via `.register!`):
+      def limits
+        @limits ||= {}.freeze
+      end
+
+      # The algorithm requires an upserting `RETURNING` clause and timestamp
+      # arithmetic, so only certain database adapters/versions are supported:
+      def supported?
+        case connection.adapter_name
+        when 'PostgreSQL', 'PostGIS'
+          true
+        when 'SQLite'
+          Gem::Version.new(connection.select_value('SELECT sqlite_version()')) >= MINIMUM_SQLITE_VERSION
+        else
+          false
+        end
+      end
+
+      # Register a limit policy for a given 'purpose' (stringy/symbol
+      # identifier). This is optional and should not be used for dynamic purpose
+      # names or limits, for memory and thread-safety reasons.
+      #
+      # Re-registering a purpose is a no-op if the config matches exactly, and
+      # raises ArgumentError otherwise.
+      def register!(purpose, max:, per:)
+        config = { max: max, per: per }.freeze
+
+        if limits.key?(purpose.to_sym) && limits.fetch(purpose.to_sym) != config
+          raise ArgumentError, "Limit policy '#{purpose}' is already registered and does not match #{config.inspect}"
+        end
+
+        @limits = limits.merge(purpose.to_sym => config).freeze
+      end
+
+      # This method implements a leaky bucket algorithm (or, more specifically,
+      # a Generic Cell Rate Algorithm) to enforce a per-'purpose' work limit.
+      #
+      # It will wait up to `wait_timeout` for the caller to come within the
+      # configured limit before yielding to the caller, and will raise
+      # `LimitExceededError` if the wait time would exceed that timeout (shedding
+      # the caller proactively rather than sleeping).
+      #
+      # In Generic Cell Rate Algorithm (GCRA) terms:
+      # - TAT (theoretical arrival time) -> drained_at
+      # - T (emission interval)          -> drain_interval
+      # - t0 (time of request)           -> the database's current time
+      # - τ (bucket capacity)            -> 1 call (implicitly)
+      def within_limit(purpose, max: nil, per: nil, wait_timeout: 5.seconds)
+        config = limits[purpose.to_sym]
+        if config && (max || per)
+          raise ArgumentError, "Limit policy '#{purpose}' is already registered (overriding 'max'/'per' is not supported)"
+        end
+
+        config ||= { max: max, per: per }.compact
+
+        # The drain_interval reflects the per-call rate at which the bucket
+        # empties, calculated as the overall interval (per) divided by the
+        # maximum number of calls allowed in that interval (max).
+        #
+        # e.g. for a target of 100 req/min, the drain_interval would be 0.6 sec/req.
+        drain_interval = config.fetch(:per).seconds / config.fetch(:max).to_d
+
+        # Attempt to reserve capacity via an uncached database query:
+        limit = connection.uncached do
+          find_by_sql(reserve_sql(purpose, drain_interval, wait_timeout.seconds)).first
+        end
+
+        # If 'limit' is nil, it means the WHERE clause prevented us from
+        # reserving capacity in the bucket. (This happens if the configured
+        # `wait_timeout` would be exceeded.) We assume the caller will back off
+        # and retry later, so we avoid wasting bucket capacity on a no-op.
+        if limit.nil?
+          ActiveSupport::Notifications.instrument('delayed.limit.exceeded', purpose: purpose)
+          raise LimitExceededError, "Concurrency limit exceeded for '#{purpose}'"
+        end
+
+        # If we successfully reserved capacity within the `wait_timeout`, it
+        # means that we've been told by the query how long to sleep in order to
+        # comply with the configured rate.
+        #
+        # (For best results, we MUST make a best attempt to sleep for the
+        # returned 'wait' duration before proceeding.)
+        wait = limit.wait.to_f
+        sleep(wait) if wait.positive?
+
+        ActiveSupport::Notifications.instrument('delayed.limit.within_limit', purpose: purpose)
+        yield
+      end
+
+      private
+
+      # We reserve capacity by pushing a 'drained_at' timestamp forward by the
+      # drain_interval, returning how long the caller must wait to avoid filling
+      # the bucket beyond its capacity. (The WHERE clause significantly reduces
+      # contention on the row when the bucket is full.)
+      def reserve_sql(purpose, drain_interval, max_wait)
+        case connection.adapter_name
+        when 'PostgreSQL', 'PostGIS'
+          # Postgres has native `interval` arithmetic and a statement-stable
+          # clock (`statement_timestamp()`), so we bind the intervals as ISO8601
+          # strings and let the database do the math.
+          binds = { purpose: purpose, drain_interval: drain_interval.iso8601, max_wait: max_wait.iso8601 }
+          [<<~SQL.squish, binds]
+            INSERT INTO delayed_limits (purpose, drained_at)
+            VALUES (:purpose, statement_timestamp() + :drain_interval)
+            ON CONFLICT (purpose) DO UPDATE SET
+              drained_at = GREATEST(statement_timestamp(), delayed_limits.drained_at) + :drain_interval
+            WHERE delayed_limits.drained_at - statement_timestamp() <= :max_wait
+            RETURNING EXTRACT(EPOCH FROM (drained_at - statement_timestamp() - :drain_interval)) AS wait
+          SQL
+        when 'SQLite'
+          raise UnsupportedDatabaseError, "Delayed::Limit requires SQLite #{MINIMUM_SQLITE_VERSION} or newer" unless supported?
+
+          # SQLite has no interval type. Instead, `julianday` yields a
+          # sub-second-precise number of days, and we bind the intervals as a
+          # fraction of a day. (The `wait` is then scaled back to seconds.)
+          binds = { purpose: purpose, drain_interval: drain_interval.to_f / SECONDS_PER_DAY, max_wait: max_wait.to_f / SECONDS_PER_DAY }
+          [<<~SQL.squish, binds]
+            INSERT INTO delayed_limits (purpose, drained_at)
+            VALUES (:purpose, strftime('%Y-%m-%d %H:%M:%f', julianday('now') + :drain_interval))
+            ON CONFLICT (purpose) DO UPDATE SET
+              drained_at = strftime('%Y-%m-%d %H:%M:%f',
+                MAX(julianday('now'), julianday(delayed_limits.drained_at)) + :drain_interval)
+            WHERE julianday(delayed_limits.drained_at) - julianday('now') <= :max_wait
+            RETURNING (julianday(drained_at) - julianday('now') - :drain_interval) * #{SECONDS_PER_DAY} AS wait
+          SQL
+        else
+          raise UnsupportedDatabaseError, "Delayed::Limit is not supported on #{connection.adapter_name.inspect}"
+        end
+      end
+    end
+  end
+end

data/db/migrate/10_create_delayed_limits.rb

@@ -0,0 +1,30 @@
+class CreateDelayedLimits < ActiveRecord::Migration[6.0]
+  # The `delayed_limits` table backs the `Delayed::Limit` concurrency limiter.
+  # (See `Delayed::Limit` for details.)
+  #
+  # You can delete this migration if you do not intend to use `Delayed::Limit`,
+  # but it is safe to leave the table in place.
+  def up
+    create_table :delayed_limits, primary_key: :purpose, id: :string do |t|
+      t.datetime :drained_at, null: false
+    end
+
+    return unless connection.adapter_name == 'PostgreSQL'
+
+    # As this is a small, extremely high-churn table, we make it UNLOGGED (the
+    # limiter state need not survive a crash) and tune fillfactor/autovacuum to
+    # favor in-page [HOT updates](https://www.postgresql.org/docs/current/storage-hot.html).
+    execute <<~SQL
+      ALTER TABLE delayed_limits SET UNLOGGED;
+      ALTER TABLE delayed_limits SET (
+        fillfactor = 33,
+        autovacuum_vacuum_scale_factor = 0,
+        autovacuum_vacuum_threshold = 30
+      );
+    SQL
+  end
+
+  def down
+    drop_table :delayed_limits
+  end
+end

data/lib/delayed/active_job_adapter.rb

@@ -78,7 +78,7 @@ module Delayed
           raise "`:run_at` is not supported. Use `:wait_until` instead." if opts.key?(:run_at)
 
           self.provider_attributes = opts.except(:wait, :wait_until, :queue, :priority)
-          opts[:priority] = Delayed::Priority.new(opts[:priority]) if opts.key?(:priority)
+          opts[:priority] = Delayed::Priority.new(opts[:priority]) if opts[:priority]
           super(opts)
         end
       end

data/lib/delayed/backend/base.rb

@@ -1,6 +1,8 @@
 module Delayed
   module Backend
     module Base
+      HOOKS = %i(before success error after failure).freeze
+
       def self.included(base)
         base.extend ClassMethods
       end
@@ -76,10 +78,13 @@ module Delayed
 
         def bulk_insert_all(jobs)
           now = db_time_now
-          jobs.each { |job| job.created_at = job.updated_at = now }
+          jobs.each do |job|
+            job.created_at ||= now
+            job.updated_at ||= now
+          end
           rows = jobs.map { |job| job.attributes.compact }
           result = insert_all(rows) # rubocop:disable Rails/SkipsModelValidations
-          return unless connection.supports_insert_returning?
+          return unless connection_pool.with_connection(&:supports_insert_returning?)
 
           ids = result.rows.map(&:first)
           jobs.zip(ids) { |job, id| job.id = id }
@@ -162,15 +167,9 @@ module Delayed
       end
 
       def hook(name, *args)
-        if payload_object.respond_to?(name)
-          if name == :enqueue
-            raise ':enqueue hook is no longer supported'
-          end
-
-          if payload_object.is_a?(Delayed::JobWrapper)
-            warn '[DEPRECATION] Job hook methods (`before`, `after`, `success`, etc) are deprecated. Use ActiveJob callbacks instead.'
-          end
+        raise ArgumentError, "Unknown hook: #{name.inspect}" unless HOOKS.include?(name)
 
+        if payload_object.respond_to?(name)
           method = payload_object.method(name)
           method.arity.zero? ? method.call : method.call(self, *args)
         end

data/lib/delayed/backend/job_preparer.rb

@@ -13,6 +13,7 @@ module Delayed
         set_queue_name
         set_priority
         set_run_at
+        set_created_at
         set_name
         handle_dst
         reject_stale_run_at
@@ -37,9 +38,14 @@ module Delayed
       end
 
       def set_run_at
+        options[:run_at] ||= options[:payload_object].scheduled_at if options[:payload_object].respond_to?(:scheduled_at)
         options[:run_at] ||= Job.db_time_now
       end
 
+      def set_created_at
+        options[:created_at] ||= options[:payload_object].enqueued_at if options[:payload_object].respond_to?(:enqueued_at)
+      end
+
       def set_name
         return if options[:name] || !Job.name_assignable?
 

data/lib/delayed/helpers/migration.rb

@@ -33,18 +33,20 @@ module Delayed
         end
       end
 
-      RETRY_EXCEPTIONS = [
-        ActiveRecord::LockWaitTimeout,
-        ActiveRecord::StatementTimeout,
-        (PG::LockNotAvailable if defined?(PG::LockNotAvailable)),
-      ].compact.freeze
+      def self.retry_exceptions
+        @retry_exceptions ||= [
+          ActiveRecord::LockWaitTimeout,
+          ActiveRecord::StatementTimeout,
+          (PG::LockNotAvailable if defined?(PG::LockNotAvailable)),
+        ].compact.freeze
+      end
 
       def with_retry_loop(wait_timeout: 5.minutes, **opts)
         with_timeouts(**opts) do
           loop do
             yield
             break
-          rescue *RETRY_EXCEPTIONS => e
+          rescue *Migration.retry_exceptions => e
             raise if Delayed::Job.db_time_now - @migration_start > wait_timeout
 
             Delayed.logger.warn("Index creation failed for #{opts[:name]}: #{e.message}. Retrying...")

data/lib/delayed/job_wrapper.rb

@@ -1,5 +1,17 @@
 module Delayed
   class JobWrapper # rubocop:disable Betterment/ActiveJobPerformable
+    module HookDeprecation
+      Delayed::Backend::Base::HOOKS.each do |hook|
+        define_method(hook) do |*args|
+          if respond_to_missing?(hook, false)
+            warn "[DEPRECATION] Job hook methods (`#{hook}`) are deprecated. Use ActiveJob callbacks instead."
+            super(*args)
+          end
+        end
+      end
+    end
+    include HookDeprecation
+
     attr_accessor :job_data
 
     delegate_missing_to :job
@@ -22,20 +34,38 @@ module Delayed
 
     # If job failed to deserialize, we can't respond to delegated methods.
     # Returning false here prevents instance method checks from blocking job cleanup.
-    # There is a (currently) unreleased Rails PR that changes the exception class in this case:
-    # https://github.com/rails/rails/pull/53770
-    if defined?(ActiveJob::UnknownJobClassError)
-      def respond_to?(*, **)
-        super
-      rescue ActiveJob::UnknownJobClassError
-        false
-      end
-    else
-      def respond_to?(*, **)
-        super
-      rescue NameError
-        false
-      end
+    # Rails 8.1+ raises ActiveJob::UnknownJobClassError (rails/rails#53770).
+    def respond_to?(*, **)
+      super
+    rescue NameError => e
+      raise if defined?(ActiveJob::UnknownJobClassError) && !e.is_a?(ActiveJob::UnknownJobClassError)
+
+      false
+    end
+
+    def before(record)
+      # ActiveJob retries should use the row's current priority (it may have changed since enqueue):
+      self.priority = record.priority.to_i if respond_to?(:priority=)
+      # If a job is manually reset, we reset ActiveJob's execution log as well:
+      reset_execution_log! if job_data.delete('terminated_at') && record.attempts.zero?
+      super
+    end
+
+    def error(record, error)
+      # The error escaped retry_on (if any), so ActiveJob considers the job terminated.
+      job_data['terminated_at'] = record.class.db_time_now.utc.iso8601(9)
+      record.payload_object = self # re-serialize the handler
+
+      # If the error escaped ActiveJob's retry_on policy, we stop the Delayed::Job retries as well.
+      @_aj_retry_terminated = rescue_handlers.any? { |name, _| error.is_a?(name.constantize) }
+
+      super
+    end
+
+    def max_attempts
+      return 1 if @_aj_retry_terminated
+
+      super if respond_to_missing?(:max_attempts)
     end
 
     def perform
@@ -50,6 +80,13 @@ module Delayed
 
     private
 
+    def reset_execution_log!
+      job_data['executions'] = 0
+      job_data['exception_executions'] = {}
+      self.executions = job_data['executions'] if respond_to?(:executions=)
+      self.exception_executions = job_data['exception_executions'] if respond_to?(:exception_executions=)
+    end
+
     def job
       @job ||= ActiveJob::Base.deserialize(job_data) if job_data
     end