activejob 7.2.2.1 → 8.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3b47492def92c2f9d51610a3b8ca696cbb32ff69fe45107ebaf478a69abc65f
-  data.tar.gz: f05813374e5dec3e6b9e138585ef9ef23c87640187a42ea03e7db9d50d1e2362
+  metadata.gz: b3a578cc3f9f7edc22dc86fba167b809a884264b4dd3a1191a9134f7b2620f84
+  data.tar.gz: 3d2f8faf8490ccaeb1b12f150b7c2f863b071451020ed79bbb4ae4dcd4f635e8
 SHA512:
-  metadata.gz: 58e96af8f140d46c83bc3d9231ee6e8c330d71e724def12d20844d5af4280b12a4de63ba3c7e58157d32295193c55405fb292071c6f0494416f66ea46ad658a6
-  data.tar.gz: a5f662c33aa37b48aa7643299cddaf5f76559feb7820468862b71aae7c0f725cf25ad098b0df2d951c810d76abaa10e49e24bdac3589b4c6bd9b683335856424
+  metadata.gz: 56ab511d1418ff2d13a4fe6fb19336899006ebc0f07f56c1bcc2de83bb27425974804fc63d95db64988638d0401455f28e183b537af19a8ed741fdb05253c584
+  data.tar.gz: ce679bda3a7b4ba95a12c0555a0334d4db859ccd57821468d49c148d6231165d7c100b5d6ae951cb02c9812f2ccc0a521eb7547217a1b2aefd6a77394c6f79d4

data/CHANGELOG.md

@@ -1,92 +1,132 @@
-## Rails 7.2.2.1 (December 10, 2024) ##
+## Rails 8.1.2 (January 08, 2026) ##
 
-*   No changes.
+*   Fix `ActiveJob.perform_all_later` to respect `job_class.enqueue_after_transaction_commit`.
 
+    Previously, `perform_all_later` would enqueue all jobs immediately, even if
+    they had `enqueue_after_transaction_commit = true`. Now it correctly defers
+    jobs with this setting until after transaction commits, matching the behavior
+    of `perform_later`.
 
-## Rails 7.2.2 (October 30, 2024) ##
+    *OuYangJinTing*
 
-*   No changes.
+*   Fix using custom serializers with `ActiveJob::Arguments.serialize` when
+    `ActiveJob::Base` hasn't been loaded.
 
+    *Hartley McGuire*
 
-## Rails 7.2.1.2 (October 23, 2024) ##
+## Rails 8.1.1 (October 28, 2025) ##
 
-*   No changes.
+*   Only index new serializers.
 
+    *Jesse Sharps*
 
-## Rails 7.2.1.1 (October 15, 2024) ##
 
-*   No changes.
+## Rails 8.1.0 (October 22, 2025) ##
 
+*   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`
 
-## Rails 7.2.1 (August 22, 2024) ##
+    *Adrianna Chang*
 
-*   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 7.2.0 (August 09, 2024) ##
+    *fatkodima*
 
-*   All tests now respect the `active_job.queue_adapter` config.
+*   Remove deprecated internal `SuckerPunch` adapter in favor of the adapter included with the `sucker_punch` gem.
 
-    Previously if you had set `config.active_job.queue_adapter` in your `config/application.rb`
-    or `config/environments/test.rb` file, the adapter you selected was previously not used consistently
-    across all tests. In some tests your adapter would be used, but other tests would use the `TestAdapter`.
+    *Rafael Mendonça França*
 
-    In Rails 7.2, all tests will respect the `queue_adapter` config if provided. If no config is provided,
-    the `TestAdapter` will continue to be used.
+*   Remove support to set `ActiveJob::Base.enqueue_after_transaction_commit` to `:never`, `:always` and `:default`.
 
-    See [#48585](https://github.com/rails/rails/pull/48585) for more details.
+    *Rafael Mendonça França*
 
-    *Alex Ghiculescu*
+*   Remove deprecated `Rails.application.config.active_job.enqueue_after_transaction_commit`.
 
-*   Make Active Job transaction aware when used conjointly with Active Record.
+    *Rafael Mendonça França*
 
-    A common mistake with Active Job is to enqueue jobs from inside a transaction,
-    causing them to potentially be picked and ran by another process, before the
-    transaction is committed, which may result in various errors.
+*   `ActiveJob::Serializers::ObjectSerializers#klass` method is now public.
 
-    ```ruby
-    Topic.transaction do
-      topic = Topic.create(...)
-      NewTopicNotificationJob.perform_later(topic)
-    end
-    ```
+    Custom Active Job serializers must have a public `#klass` method too.
+    The returned class will be index allowing for faster serialization.
 
-    Now Active Job will automatically defer the enqueuing to after the transaction is committed,
-    and drop the job if the transaction is rolled back.
+    *Jean Boussier*
 
-    Various queue implementations can choose to disable this behavior, and users can disable it,
-    or force it on a per job basis:
+*   Allow jobs to the interrupted and resumed with Continuations
+
+    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.
 
     ```ruby
-    class NewTopicNotificationJob < ApplicationJob
-      self.enqueue_after_transaction_commit = :never # or `:always` or `:default`
+    class ProcessImportJob
+      include ActiveJob::Continuable
+
+      def perform(import_id)
+        @import = Import.find(import_id)
+
+        # block format
+        step :initialize do
+          @import.initialize
+        end
+
+        # 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
+
+        private
+          def finalize
+            @import.finalize
+          end
+      end
     end
     ```
 
-    *Jean Boussier*, *Cristian Bica*
-
-*   Do not trigger immediate loading of `ActiveJob::Base` when loading `ActiveJob::TestHelper`.
+    *Donal McBreen*
 
-    *Maxime Réty*
+*   Defer invocation of ActiveJob enqueue callbacks until after commit when
+    `enqueue_after_transaction_commit` is enabled.
 
-*   Preserve the serialized timezone when deserializing `ActiveSupport::TimeWithZone` arguments.
+    *Will Roever*
 
-    *Joshua Young*
+*   Add `report:` option to `ActiveJob::Base#retry_on` and `#discard_on`
 
-*   Remove deprecated `:exponentially_longer` value for the `:wait` in `retry_on`.
+    When the `report:` option is passed, errors will be reported to the error reporter
+    before being retried / discarded.
 
-    *Rafael Mendonça França*
+    *Andrew Novoselac*
 
-*   Remove deprecated support to set numeric values to `scheduled_at` attribute.
+*   Accept a block for `ActiveJob::ConfiguredJob#perform_later`.
 
-    *Rafael Mendonça França*
+    This was inconsistent with a regular `ActiveJob::Base#perform_later`.
 
-*   Deprecate `Rails.application.config.active_job.use_big_decimal_serialize`.
+    *fatkodima*
 
-    *Rafael Mendonça França*
+*   Raise a more specific error during deserialization when a previously serialized job class is now unknown.
 
-*   Remove deprecated primitive serializer for `BigDecimal` arguments.
+    `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.
 
-    *Rafael Mendonça França*
+    *Earlopain*
 
-Please check [7-1-stable](https://github.com/rails/rails/blob/7-1-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

@@ -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
+        { Serializers::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
@@ -54,59 +94,18 @@ module ActiveJob
       RUBY2_KEYWORDS_KEY = "_aj_ruby2_keywords"
       # :nodoc:
       WITH_INDIFFERENT_ACCESS_KEY = "_aj_hash_with_indifferent_access"
-      # :nodoc:
-      OBJECT_SERIALIZER_KEY = "_aj_serialized"
 
       # :nodoc:
       RESERVED_KEYS = [
         GLOBALID_KEY, GLOBALID_KEY.to_sym,
         SYMBOL_KEYS_KEY, SYMBOL_KEYS_KEY.to_sym,
         RUBY2_KEYWORDS_KEY, RUBY2_KEYWORDS_KEY.to_sym,
-        OBJECT_SERIALIZER_KEY, OBJECT_SERIALIZER_KEY.to_sym,
+        Serializers::OBJECT_SERIALIZER_KEY, Serializers::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
@@ -135,7 +134,7 @@ module ActiveJob
       end
 
       def custom_serialized?(hash)
-        hash.key?(OBJECT_SERIALIZER_KEY)
+        hash.key?(Serializers::OBJECT_SERIALIZER_KEY)
       end
 
       def serialize_hash(argument)
@@ -159,10 +158,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 +171,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
 
@@ -194,4 +195,6 @@ module ActiveJob
           "without an id. (Maybe you forgot to call save?)"
       end
   end
+
+  ActiveSupport.run_load_hooks(:active_job_arguments, Arguments)
 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
@@ -40,7 +40,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 +50,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 +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,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