activejob 8.0.2.1 → 8.1.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c02e749103c9735fd2df2554980ae11eb1e79fe023f034528f6481f7d7b3bbd
-  data.tar.gz: 4a8b3a0585aa1523ffd7404640ee7562f72ce85c1865c71da599b5c07136bcb6
+  metadata.gz: c9a034077d88450ca67c9f9921d2b9678d506724adeb387742be2be30b30b038
+  data.tar.gz: 6efdff593dfb0f7d0773a6a8419c084919346d1dc15c44619e58f5009886ad3b
 SHA512:
-  metadata.gz: 9a6c0e84aca264905887fce990ba85938abefd87c97f03eabbc821c114b515f0d2eb5b91c30fa5c83b6feafa60977dedd44e9fac11f22494574f4f37d04ebba6
-  data.tar.gz: 03ae4188df409f83db411a67353cfcca270f39642a989ebd044d352ed6207e681f018fee9124aa812022c0e3be114ac749d5db6737f9756d763abd6a08efaa52
+  metadata.gz: 7a6be4dfbb96daba9f49b695a5aa568420a446cb303bf3a9ba6083a1d3d4c3bb7663fb428107a2f0b3f954a2ba4b4c5781dad015f4d56b97201096d75ab4bf35
+  data.tar.gz: 4b01822ccd36668f128a6754b8ad9ea06d7874b2f3584c7fe44e54948df92552c6e93609ab7f2a688a20c23116078b0a84711ac1c851308657e438f0892ceb32

data/CHANGELOG.md

@@ -1,60 +1,93 @@
-## Rails 8.0.2.1 (August 13, 2025) ##
+## Rails 8.1.0.beta1 (September 04, 2025) ##
 
-*   No changes.
+*   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 (March 12, 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
@@ -126,6 +128,6 @@ Bug reports for the Ruby on \Rails project can be filed here:
 
 * https://github.com/rails/rails/issues
 
-Feature requests should be discussed on the rails-core mailing list here:
+Feature requests should be discussed on the rubyonrails-core forum here:
 
 * https://discuss.rubyonrails.org/c/rubyonrails-core

data/lib/active_job/arguments.rb

@@ -31,8 +31,44 @@ module ActiveJob
     # serialized without mutation are returned as-is. Arrays/Hashes are
     # serialized element by element. All other types are serialized using
     # GlobalID.
-    def serialize(arguments)
-      arguments.map { |argument| serialize_argument(argument) }
+    def serialize(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 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(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
@@ -64,49 +100,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
@@ -140,7 +137,7 @@ module ActiveJob
 
       def serialize_hash(argument)
         argument.each_with_object({}) do |(key, value), hash|
-          hash[serialize_hash_key(key)] = serialize_argument(value)
+          hash[serialize_hash_key(key)] = serialize(value)
         end
       end
 
@@ -159,10 +156,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 +169,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

@@ -11,8 +11,7 @@ require "active_job/exceptions"
 require "active_job/log_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
@@ -40,7 +39,7 @@ module ActiveJob # :nodoc:
   #   end
   #
   # Records that are passed in are serialized/deserialized using Global
-  # ID. More information can be found in Arguments.
+  # ID. More information can be found in ActiveJob::Arguments.
   #
   # To enqueue a job to be performed as soon as the queuing system is free:
   #
@@ -50,7 +49,7 @@ module ActiveJob # :nodoc:
   #
   #   ProcessPhotoJob.set(wait_until: Date.tomorrow.noon).perform_later(photo)
   #
-  # More information can be found in ActiveJob::Core::ClassMethods#set
+  # More information can be found in ActiveJob::Core::ClassMethods#set.
   #
   # A job can also be processed immediately without sending to the queue:
   #
@@ -71,8 +70,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,11 +12,12 @@ module ActiveJob
     end
 
     def perform_later(...)
-      @job_class.new(...).enqueue @options
-    end
+      job = @job_class.new(...)
+      enqueue_result = job.enqueue(@options)
+
+      yield job if block_given?
 
-    def perform_all_later(multi_args)
-      @job_class.perform_all_later(multi_args, options: @options)
+      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