activejob 8.0.3 → 8.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd83b074127046f406525380f3021fae2cd3ddb36ce9ae8ef44768e63a315b39
-  data.tar.gz: 6df6eb7459e16314d5819aac1966f9ecf596ed17c5590d4229b92de444f70d4c
+  metadata.gz: bc270930c258d16e62b3f01ee4ed3591e91b680ddea4c43ddba1870206bda41f
+  data.tar.gz: 6bc1d66fb46babd36a3959754021ddbc6d115fbeef7e78d025b4880e48c63db1
 SHA512:
-  metadata.gz: d59029dbd69e9b803af9319161888de3569574b6105e0550bda39f0632b7686f97fbac1c0f4694c00b7e9d76bc17f70570a88e7262ae1c5a6864d810fbce02e8
-  data.tar.gz: c7ac883680b1cbe1f7da6b6aa9243ae33dbed2c296ebdaba279349af6f87fe6b9fbf148923f849e578deb76fe4804d401c632bbaac2860f0cbd6bbe458fc90c4
+  metadata.gz: aed3444d15f38a03c9df4321d898958c8c4611c427dd4ad6ada5d14804db2dced96aa035d98e3d777c0280d1c7c0433a1888cb930ff55692882eb1dbecfb729e
+  data.tar.gz: 47396127fb20f53dc5ec782619913145fa911128b04ab3e8f80dc52d4b3071634653f49c6271f86a1fe1ccf58595d1dd6a7fc0453d37eb2a3a9a250fa601ded8

data/CHANGELOG.md

@@ -1,66 +1,109 @@
-## Rails 8.0.3 (September 22, 2025) ##
+## Rails 8.1.0 (October 22, 2025) ##
 
-*   Include the actual Active Job locale when serializing rather than I18n locale.
+*   Add structured events for Active Job:
+    - `active_job.enqueued`
+    - `active_job.bulk_enqueued`
+    - `active_job.started`
+    - `active_job.completed`
+    - `active_job.retry_scheduled`
+    - `active_job.retry_stopped`
+    - `active_job.discarded`
+    - `active_job.interrupt`
+    - `active_job.resume`
+    - `active_job.step_skipped`
+    - `active_job.step_started`
+    - `active_job.step`
 
-    *Adrien S*
+    *Adrianna Chang*
 
-*   Fix `retry_job` instrumentation when using `:test` adapter for Active Job.
-
-    *fatkodima*
+*   Deprecate built-in `sidekiq` adapter.
 
+    If you're using this adapter, upgrade to `sidekiq` 7.3.3 or later to use the `sidekiq` gem's adapter.
 
-## Rails 8.0.2.1 (August 13, 2025) ##
+    *fatkodima*
 
-*   No changes.
+*   Remove deprecated internal `SuckerPunch` adapter in favor of the adapter included with the `sucker_punch` gem.
 
+    *Rafael Mendonça França*
 
-## Rails 8.0.2 (March 12, 2025) ##
+*   Remove support to set `ActiveJob::Base.enqueue_after_transaction_commit` to `:never`, `:always` and `:default`.
 
-*   No changes.
+    *Rafael Mendonça França*
 
+*   Remove deprecated `Rails.application.config.active_job.enqueue_after_transaction_commit`.
 
-## Rails 8.0.1 (December 13, 2024) ##
+    *Rafael Mendonça França*
 
-*   Avoid crashing in Active Job logger when logging enqueueing errors
+*   `ActiveJob::Serializers::ObjectSerializers#klass` method is now public.
 
-    `ActiveJob.perform_all_later` could fail with a `TypeError` when all
-    provided jobs failed to be enqueueed.
+    Custom Active Job serializers must have a public `#klass` method too.
+    The returned class will be index allowing for faster serialization.
 
-    *Efstathios Stivaros*
+    *Jean Boussier*
 
+*   Allow jobs to the interrupted and resumed with Continuations
 
-## Rails 8.0.0.1 (December 10, 2024) ##
+    A job can use Continuations by including the `ActiveJob::Continuable`
+    concern. Continuations split jobs into steps. When the queuing system
+    is shutting down jobs can be interrupted and their progress saved.
 
-*   No changes.
+    ```ruby
+    class ProcessImportJob
+      include ActiveJob::Continuable
 
+      def perform(import_id)
+        @import = Import.find(import_id)
 
-## Rails 8.0.0 (November 07, 2024) ##
+        # block format
+        step :initialize do
+          @import.initialize
+        end
 
-*   No changes.
+        # step with cursor, the cursor is saved when the job is interrupted
+        step :process do |step|
+          @import.records.find_each(start: step.cursor) do |record|
+            record.process
+            step.advance! from: record.id
+          end
+        end
 
+        # method format
+        step :finalize
 
-## Rails 8.0.0.rc2 (October 30, 2024) ##
+        private
+          def finalize
+            @import.finalize
+          end
+      end
+    end
+    ```
 
-*   No changes.
+    *Donal McBreen*
 
+*   Defer invocation of ActiveJob enqueue callbacks until after commit when
+    `enqueue_after_transaction_commit` is enabled.
 
-## Rails 8.0.0.rc1 (October 19, 2024) ##
+    *Will Roever*
 
-*   Remove deprecated `config.active_job.use_big_decimal_serializer`.
+*   Add `report:` option to `ActiveJob::Base#retry_on` and `#discard_on`
 
-    *Rafael Mendonça França*
+    When the `report:` option is passed, errors will be reported to the error reporter
+    before being retried / discarded.
 
+    *Andrew Novoselac*
 
-## Rails 8.0.0.beta1 (September 26, 2024) ##
+*   Accept a block for `ActiveJob::ConfiguredJob#perform_later`.
 
-*   Deprecate `sucker_punch` as an adapter option.
+    This was inconsistent with a regular `ActiveJob::Base#perform_later`.
 
-    If you're using this adapter, change to `adapter: async` for the same functionality.
+    *fatkodima*
 
-    *Dino Maric, zzak*
+*   Raise a more specific error during deserialization when a previously serialized job class is now unknown.
 
-*   Use `RAILS_MAX_THREADS` in `ActiveJob::AsyncAdapter`. If it is not set, use 5 as default.
+    `ActiveJob::UnknownJobClassError` will be raised instead of a more generic
+    `NameError` to make it easily possible for adapters to tell if the `NameError`
+    was raised during job execution or deserialization.
 
-    *heka1024*
+    *Earlopain*
 
-Please check [7-2-stable](https://github.com/rails/rails/blob/7-2-stable/activejob/CHANGELOG.md) for previous changes.
+Please check [8-0-stable](https://github.com/rails/rails/blob/8-0-stable/activejob/CHANGELOG.md) for previous changes.

data/README.md

@@ -89,11 +89,13 @@ Active Job has built-in adapters for multiple queuing backends (Sidekiq,
 Resque, Delayed Job and others). To get an up-to-date list of the adapters
 see the API Documentation for [ActiveJob::QueueAdapters](https://api.rubyonrails.org/classes/ActiveJob/QueueAdapters.html).
 
-**Please note:** We are not accepting pull requests for new adapters. We
-encourage library authors to provide an ActiveJob adapter as part of
-their gem, or as a stand-alone gem. For discussion about this see the
-following PRs: [23311](https://github.com/rails/rails/issues/23311#issuecomment-176275718),
-[21406](https://github.com/rails/rails/pull/21406#issuecomment-138813484), and [#32285](https://github.com/rails/rails/pull/32285).
+**Please note:** We are not accepting pull requests for new adapters, and we are
+actively extracting the current adapters. We encourage library authors to provide
+an Active Job adapter as part of their gem, or as a stand-alone gem.
+
+## Continuations
+
+Continuations allow jobs to be interrupted and resumed. See more at ActiveJob::Continuation.
 
 
 ## Download and installation

data/lib/active_job/arguments.rb

@@ -35,6 +35,46 @@ module ActiveJob
       arguments.map { |argument| serialize_argument(argument) }
     end
 
+    def serialize_argument(argument) # :nodoc:
+      case argument
+      when nil, true, false, Integer, Float # Types that can hardly be subclassed
+        argument
+      when String
+        if argument.class == String
+          argument
+        else
+          begin
+            Serializers.serialize(argument)
+          rescue SerializationError
+            argument
+          end
+        end
+      when Symbol
+        { OBJECT_SERIALIZER_KEY => "ActiveJob::Serializers::SymbolSerializer", "value" => argument.name }
+      when GlobalID::Identification
+        convert_to_global_id_hash(argument)
+      when Array
+        argument.map { |arg| serialize_argument(arg) }
+      when ActiveSupport::HashWithIndifferentAccess
+        serialize_indifferent_hash(argument)
+      when Hash
+        symbol_keys = argument.keys
+        symbol_keys.select! { |k| k.is_a?(Symbol) }
+        symbol_keys.map!(&:name)
+
+        aj_hash_key = if Hash.ruby2_keywords_hash?(argument)
+          RUBY2_KEYWORDS_KEY
+        else
+          SYMBOL_KEYS_KEY
+        end
+        result = serialize_hash(argument)
+        result[aj_hash_key] = symbol_keys
+        result
+      else
+        Serializers.serialize(argument)
+      end
+    end
+
     # Deserializes a set of arguments. Intrinsic types that can safely be
     # deserialized without mutation are returned as-is. Arrays/Hashes are
     # deserialized element by element. All other types are deserialized using
@@ -64,49 +104,10 @@ module ActiveJob
         RUBY2_KEYWORDS_KEY, RUBY2_KEYWORDS_KEY.to_sym,
         OBJECT_SERIALIZER_KEY, OBJECT_SERIALIZER_KEY.to_sym,
         WITH_INDIFFERENT_ACCESS_KEY, WITH_INDIFFERENT_ACCESS_KEY.to_sym,
-      ]
+      ].to_set
       private_constant :RESERVED_KEYS, :GLOBALID_KEY,
         :SYMBOL_KEYS_KEY, :RUBY2_KEYWORDS_KEY, :WITH_INDIFFERENT_ACCESS_KEY
 
-      def serialize_argument(argument)
-        case argument
-        when nil, true, false, Integer, Float # Types that can hardly be subclassed
-          argument
-        when String
-          if argument.class == String
-            argument
-          else
-            begin
-              Serializers.serialize(argument)
-            rescue SerializationError
-              argument
-            end
-          end
-        when GlobalID::Identification
-          convert_to_global_id_hash(argument)
-        when Array
-          argument.map { |arg| serialize_argument(arg) }
-        when ActiveSupport::HashWithIndifferentAccess
-          serialize_indifferent_hash(argument)
-        when Hash
-          symbol_keys = argument.each_key.grep(Symbol).map!(&:to_s)
-          aj_hash_key = if Hash.ruby2_keywords_hash?(argument)
-            RUBY2_KEYWORDS_KEY
-          else
-            SYMBOL_KEYS_KEY
-          end
-          result = serialize_hash(argument)
-          result[aj_hash_key] = symbol_keys
-          result
-        else
-          if argument.respond_to?(:permitted?) && argument.respond_to?(:to_h)
-            serialize_indifferent_hash(argument.to_h)
-          else
-            Serializers.serialize(argument)
-          end
-        end
-      end
-
       def deserialize_argument(argument)
         case argument
         when nil, true, false, String, Integer, Float
@@ -159,10 +160,12 @@ module ActiveJob
 
       def serialize_hash_key(key)
         case key
-        when *RESERVED_KEYS
+        when RESERVED_KEYS
           raise SerializationError.new("Can't serialize a Hash with reserved key #{key.inspect}")
-        when String, Symbol
-          key.to_s
+        when String
+          key
+        when Symbol
+          key.name
         else
           raise SerializationError.new("Only string and symbol hash keys may be serialized as job arguments, but #{key.inspect} is a #{key.class}")
         end
@@ -170,7 +173,7 @@ module ActiveJob
 
       def serialize_indifferent_hash(indifferent_hash)
         result = serialize_hash(indifferent_hash)
-        result[WITH_INDIFFERENT_ACCESS_KEY] = serialize_argument(true)
+        result[WITH_INDIFFERENT_ACCESS_KEY] = true
         result
       end
 

data/lib/active_job/base.rb

@@ -9,10 +9,10 @@ require "active_job/execution"
 require "active_job/callbacks"
 require "active_job/exceptions"
 require "active_job/log_subscriber"
+require "active_job/structured_event_subscriber"
 require "active_job/logging"
 require "active_job/instrumentation"
-require "active_job/timezones"
-require "active_job/translation"
+require "active_job/execution_state"
 
 module ActiveJob # :nodoc:
   # = Active Job \Base
@@ -71,8 +71,7 @@ module ActiveJob # :nodoc:
     include Exceptions
     include Instrumentation
     include Logging
-    include Timezones
-    include Translation
+    include ExecutionState
 
     ActiveSupport.run_load_hooks(:active_job, self)
   end

data/lib/active_job/configured_job.rb

@@ -12,7 +12,12 @@ module ActiveJob
     end
 
     def perform_later(...)
-      @job_class.new(...).enqueue @options
+      job = @job_class.new(...)
+      enqueue_result = job.enqueue(@options)
+
+      yield job if block_given?
+
+      enqueue_result
     end
   end
 end

data/lib/active_job/continuable.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  # = Active Job Continuable
+  #
+  # The Continuable module provides the ability to track the progress of your
+  # jobs, and continue from where they left off if interrupted.
+  #
+  # Mix ActiveJob::Continuable into your job to enable continuations.
+  #
+  # See {ActiveJob::Continuation}[rdoc-ref:ActiveJob::Continuation] for usage.
+  #
+  module Continuable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :max_resumptions, instance_writer: false
+      class_attribute :resume_options, instance_writer: false, default: { wait: 5.seconds }
+      class_attribute :resume_errors_after_advancing, instance_writer: false, default: true
+
+      around_perform :continue
+
+      def initialize(...)
+        super(...)
+        self.resumptions = 0
+        self.continuation = Continuation.new(self, {})
+      end
+    end
+
+    # The number of times the job has been resumed.
+    attr_accessor :resumptions
+
+    attr_accessor :continuation # :nodoc:
+
+    # Start a new continuation step
+    def step(step_name, start: nil, isolated: false, &block)
+      unless block_given?
+        step_method = method(step_name)
+
+        raise ArgumentError, "Step method '#{step_name}' must accept 0 or 1 arguments" if step_method.arity > 1
+
+        if step_method.parameters.any? { |type, name| type == :key || type == :keyreq }
+          raise ArgumentError, "Step method '#{step_name}' must not accept keyword arguments"
+        end
+
+        block = step_method.arity == 0 ? -> (_) { step_method.call } : step_method
+      end
+      checkpoint! if continuation.advanced?
+      continuation.step(step_name, start: start, isolated: isolated, &block)
+    end
+
+    def serialize # :nodoc:
+      super.merge("continuation" => continuation.to_h, "resumptions" => resumptions)
+    end
+
+    def deserialize(job_data) # :nodoc:
+      super
+      self.continuation = Continuation.new(self, job_data.fetch("continuation", {}))
+      self.resumptions = job_data.fetch("resumptions", 0)
+    end
+
+    def checkpoint! # :nodoc:
+      interrupt!(reason: :stopping) if queue_adapter.stopping?
+    end
+
+    def interrupt!(reason:) # :nodoc:
+      instrument :interrupt, reason: reason, **continuation.instrumentation
+      raise Continuation::Interrupt, "Interrupted #{continuation.description} (#{reason})"
+    end
+
+    private
+      def continue(&block)
+        if continuation.started?
+          self.resumptions += 1
+          instrument :resume, **continuation.instrumentation
+        end
+
+        block.call
+      rescue Continuation::Interrupt => e
+        resume_job(e)
+      rescue Continuation::Error
+        raise
+      rescue StandardError => e
+        if resume_errors_after_advancing? && continuation.advanced?
+          resume_job(exception: e)
+        else
+          raise
+        end
+      end
+
+      def resume_job(exception) # :nodoc:
+        executions_for(exception)
+        if max_resumptions.nil? || resumptions < max_resumptions
+          retry_job(**self.resume_options)
+        else
+          raise Continuation::ResumeLimitError, "Job was resumed a maximum of #{max_resumptions} times"
+        end
+      end
+  end
+
+  ActiveSupport.run_load_hooks(:active_job_continuable, Continuable)
+end

data/lib/active_job/continuation/step.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  class Continuation
+    # = Active Job Continuation Step
+    #
+    # Represents a step within a continuable job.
+    #
+    # When a step is completed, it is recorded in the job's continuation state.
+    # If the job is interrupted, it will be resumed from after the last completed step.
+    #
+    # Steps also have an optional cursor that can be used to track progress within the step.
+    # If a job is interrupted during a step, the cursor will be saved and passed back when
+    # the job is resumed.
+    #
+    # It is the responsibility of the code in the step to use the cursor correctly to resume
+    # from where it left off.
+    class Step
+      # The name of the step.
+      attr_reader :name
+
+      # The cursor for the step.
+      attr_reader :cursor
+
+      def initialize(name, cursor, job:, resumed:)
+        @name = name.to_sym
+        @initial_cursor = cursor
+        @cursor = cursor
+        @resumed = resumed
+        @job = job
+      end
+
+      # Check if the job should be interrupted, and if so raise an Interrupt exception.
+      # The job will be requeued for retry.
+      def checkpoint!
+        job.checkpoint!
+      end
+
+      # Set the cursor and interrupt the job if necessary.
+      def set!(cursor)
+        @cursor = cursor
+        checkpoint!
+      end
+
+      # Advance the cursor from the current or supplied value
+      #
+      # The cursor will be advanced by calling the +succ+ method on the cursor.
+      # An UnadvanceableCursorError error will be raised if the cursor does not implement +succ+.
+      def advance!(from: nil)
+        from = cursor if from.nil?
+
+        begin
+          to = from.succ
+        rescue NoMethodError
+          raise UnadvanceableCursorError, "Cursor class '#{from.class}' does not implement 'succ'"
+        end
+
+        set! to
+      end
+
+      # Has this step been resumed from a previous job execution?
+      def resumed?
+        @resumed
+      end
+
+      # Has the cursor been advanced during this job execution?
+      def advanced?
+        initial_cursor != cursor
+      end
+
+      def to_a
+        [ name.to_s, cursor ]
+      end
+
+      def description
+        "at '#{name}', cursor '#{cursor.inspect}'"
+      end
+
+      private
+        attr_reader :initial_cursor, :job
+    end
+  end
+end

data/lib/active_job/continuation/test_helper.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "active_job/test_helper"
+require "active_job/continuation"
+
+module ActiveJob
+  class Continuation
+    # Test helper for ActiveJob::Continuable jobs.
+    #
+    module TestHelper
+      include ::ActiveJob::TestHelper
+
+      # Interrupt a job during a step.
+      #
+      #  class MyJob < ApplicationJob
+      #    include ActiveJob::Continuable
+      #
+      #    cattr_accessor :items, default: []
+      #    def perform
+      #      step :my_step, start: 1 do |step|
+      #        (step.cursor..10).each do |i|
+      #          items << i
+      #          step.advance!
+      #        end
+      #      end
+      #    end
+      #  end
+      #
+      #  test "interrupt job during step" do
+      #    MyJob.perform_later
+      #    interrupt_job_during_step(MyJob, :my_step, cursor: 6) { perform_enqueued_jobs }
+      #    assert_equal [1, 2, 3, 4, 5], MyJob.items
+      #    perform_enqueued_jobs
+      #    assert_equal [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], MyJob.items
+      #  end
+      def interrupt_job_during_step(job, step, cursor: nil, &block)
+        require_active_job_test_adapter!("interrupt_job_during_step")
+        queue_adapter.with(stopping: ->() { during_step?(job, step, cursor: cursor) }, &block)
+      end
+
+      # Interrupt a job after a step.
+      #
+      # Note that there's no checkpoint after the final step so it won't be interrupted.
+      #
+      #  class MyJob < ApplicationJob
+      #    include ActiveJob::Continuable
+      #
+      #    cattr_accessor :items, default: []
+      #
+      #    def perform
+      #      step :step_one { items << 1 }
+      #      step :step_two { items << 2 }
+      #      step :step_three { items << 3 }
+      #      step :step_four { items << 4 }
+      #    end
+      #  end
+      #
+      #  test "interrupt job after step" do
+      #    MyJob.perform_later
+      #    interrupt_job_after_step(MyJob, :step_two) { perform_enqueued_jobs }
+      #    assert_equal [1, 2], MyJob.items
+      #    perform_enqueued_jobs
+      #    assert_equal [1, 2, 3, 4], MyJob.items
+      #  end
+      def interrupt_job_after_step(job, step, &block)
+        require_active_job_test_adapter!("interrupt_job_after_step")
+        queue_adapter.with(stopping: ->() { after_step?(job, step) }, &block)
+      end
+
+      private
+        def continuation_for(klass)
+          job = ActiveSupport::ExecutionContext.to_h[:job]
+          job.send(:continuation)&.to_h if job && job.is_a?(klass)
+        end
+
+        def during_step?(job, step, cursor: nil)
+          if (continuation = continuation_for(job))
+            continuation["current"] == [ step.to_s, cursor ]
+          end
+        end
+
+        def after_step?(job, step)
+          if (continuation = continuation_for(job))
+            continuation["completed"].last == step.to_s && continuation["current"].nil?
+          end
+        end
+    end
+  end
+end

data/lib/active_job/continuation/validation.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  class Continuation
+    module Validation # :nodoc:
+      private
+        def validate_step!(name)
+          validate_step_symbol!(name)
+          validate_step_not_encountered!(name)
+          validate_step_not_nested!(name)
+          validate_step_resume_expected!(name)
+          validate_step_expected_order!(name)
+        end
+
+        def validate_step_symbol!(name)
+          unless name.is_a?(Symbol)
+            raise_step_error! "Step '#{name}' must be a Symbol, found '#{name.class}'"
+          end
+        end
+
+        def validate_step_not_encountered!(name)
+          if encountered.include?(name)
+            raise_step_error! "Step '#{name}' has already been encountered"
+          end
+        end
+
+        def validate_step_not_nested!(name)
+          if running_step?
+            raise_step_error! "Step '#{name}' is nested inside step '#{current.name}'"
+          end
+        end
+
+        def validate_step_resume_expected!(name)
+          if current && current.name != name && !completed?(name)
+            raise_step_error! "Step '#{name}' found, expected to resume from '#{current.name}'"
+          end
+        end
+
+        def validate_step_expected_order!(name)
+          if completed.size > encountered.size && completed[encountered.size] != name
+            raise_step_error! "Step '#{name}' found, expected to see '#{completed[encountered.size]}'"
+          end
+        end
+
+        def raise_step_error!(message)
+          raise InvalidStepError, message
+        end
+    end
+  end
+end