omg-activejob 8.0.0.alpha1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 802ba9cb0255881dee3342c6c3f02acfff2cbcf17cb34b2c252377808e433d6b
+  data.tar.gz: b055d444e0fff0513ee33b289d4e600269ea3b994c5100d546b6e2c11091327b
+SHA512:
+  metadata.gz: 99e08ad43087e35807d581c7906b1bacf2bdbd73e270175fd29b4df4fc6c18ffb32fd5360ed89b15313f4f9c2261ceb21a808de4a0e853c149e5d7e08fc42d3d
+  data.tar.gz: 855ef48da4071c96bbce3510e9820cc51bac73aa86f0d3f653dd4e3ea3392b451eab27d6547bad47ac68e9b13fc9fcc52847eb5e628bd8ddccb5863437b3953b

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+*   Remove `sucker_punch` as an adapter option [since author himself recommends using AJ's own AsyncAdapter](https://github.com/brandonhilkert/sucker_punch?tab=readme-ov-file#faq).
+    If you're using this adapter, change to `adapter: async` for the same functionality.
+
+    *Dino Maric*
+
+*   Use `RAILS_MAX_THREADS` in `ActiveJob::AsyncAdapter`. If it is not set, use 5 as default.
+
+    *heka1024*
+
+Please check [7-2-stable](https://github.com/rails/rails/blob/7-2-stable/activejob/CHANGELOG.md) for previous changes.

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) David Heinemeier Hansson
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/README.md

@@ -0,0 +1,131 @@
+# Active Job – Make work happen later
+
+Active Job is a framework for declaring jobs and making them run on a variety
+of queuing backends. These jobs can be everything from regularly scheduled
+clean-ups, to billing charges, to mailings — anything that can be chopped up into
+small units of work and run in parallel.
+
+It also serves as the backend for Action Mailer's #deliver_later functionality
+that makes it easy to turn any mailing into a job for running later. That's
+one of the most common jobs in a modern web application: sending emails outside
+the request-response cycle, so the user doesn't have to wait on it.
+
+The main point is to ensure that all \Rails apps will have a job infrastructure
+in place, even if it's in the form of an "immediate runner". We can then have
+framework features and other gems build on top of that, without having to worry
+about API differences between Delayed Job and Resque. Picking your queuing
+backend becomes more of an operational concern, then. And you'll be able to
+switch between them without having to rewrite your jobs.
+
+You can read more about Active Job in the [Active Job Basics](https://guides.rubyonrails.org/active_job_basics.html) guide.
+
+## Usage
+
+To learn how to use your preferred queuing backend see its adapter
+documentation at
+[ActiveJob::QueueAdapters](https://api.rubyonrails.org/classes/ActiveJob/QueueAdapters.html).
+
+Declare a job like so:
+
+```ruby
+class MyJob < ActiveJob::Base
+  queue_as :my_jobs
+
+  def perform(record)
+    record.do_work
+  end
+end
+```
+
+Enqueue a job like so:
+
+```ruby
+MyJob.perform_later record  # Enqueue a job to be performed as soon as the queuing system is free.
+```
+
+```ruby
+MyJob.set(wait_until: Date.tomorrow.noon).perform_later(record)  # Enqueue a job to be performed tomorrow at noon.
+```
+
+```ruby
+MyJob.set(wait: 1.week).perform_later(record) # Enqueue a job to be performed 1 week from now.
+```
+
+That's it!
+
+
+## GlobalID support
+
+Active Job supports [GlobalID serialization](https://github.com/rails/globalid/) for parameters. This makes it possible
+to pass live Active Record objects to your job instead of class/id pairs, which
+you then have to manually deserialize. Before, jobs would look like this:
+
+```ruby
+class TrashableCleanupJob
+  def perform(trashable_class, trashable_id, depth)
+    trashable = trashable_class.constantize.find(trashable_id)
+    trashable.cleanup(depth)
+  end
+end
+```
+
+Now you can simply do:
+
+```ruby
+class TrashableCleanupJob
+  def perform(trashable, depth)
+    trashable.cleanup(depth)
+  end
+end
+```
+
+This works with any class that mixes in GlobalID::Identification, which
+by default has been mixed into Active Record classes.
+
+
+## Supported queuing systems
+
+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).
+
+
+## Download and installation
+
+The latest version of Active Job can be installed with RubyGems:
+
+```
+  $ gem install activejob
+```
+
+Source code can be downloaded as part of the \Rails project on GitHub:
+
+* https://github.com/rails/rails/tree/main/activejob
+
+
+## License
+
+Active Job is released under the MIT license:
+
+* https://opensource.org/licenses/MIT
+
+
+## Support
+
+API documentation is at:
+
+* https://api.rubyonrails.org
+
+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:
+
+* https://discuss.rubyonrails.org/c/rubyonrails-core

data/lib/active_job/arguments.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "active_support/core_ext/hash"
+
+module ActiveJob
+  # Raised when an exception is raised during job arguments deserialization.
+  #
+  # Wraps the original exception raised as +cause+.
+  class DeserializationError < StandardError
+    def initialize # :nodoc:
+      super("Error while trying to deserialize arguments: #{$!.message}")
+      set_backtrace $!.backtrace
+    end
+  end
+
+  # Raised when an unsupported argument type is set as a job argument. We
+  # currently support String, Integer, Float, NilClass, TrueClass, FalseClass,
+  # BigDecimal, Symbol, Date, Time, DateTime, ActiveSupport::TimeWithZone,
+  # ActiveSupport::Duration, Hash, ActiveSupport::HashWithIndifferentAccess,
+  # Array, Range, or GlobalID::Identification instances, although this can be
+  # extended by adding custom serializers.
+  # Raised if you set the key for a Hash something else than a string or
+  # a symbol. Also raised when trying to serialize an object which can't be
+  # identified with a GlobalID - such as an unpersisted Active Record model.
+  class SerializationError < ArgumentError; end
+
+  module Arguments
+    extend self
+    # Serializes a set of arguments. Intrinsic types that can safely be
+    # 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) }
+    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
+    # GlobalID.
+    def deserialize(arguments)
+      arguments.map { |argument| deserialize_argument(argument) }
+    rescue
+      raise DeserializationError
+    end
+
+    private
+      # :nodoc:
+      GLOBALID_KEY = "_aj_globalid"
+      # :nodoc:
+      SYMBOL_KEYS_KEY = "_aj_symbol_keys"
+      # :nodoc:
+      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,
+        WITH_INDIFFERENT_ACCESS_KEY, WITH_INDIFFERENT_ACCESS_KEY.to_sym,
+      ]
+      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
+          argument
+        when Array
+          argument.map { |arg| deserialize_argument(arg) }
+        when Hash
+          if serialized_global_id?(argument)
+            deserialize_global_id argument
+          elsif custom_serialized?(argument)
+            Serializers.deserialize(argument)
+          else
+            deserialize_hash(argument)
+          end
+        else
+          raise ArgumentError, "Can only deserialize primitive arguments: #{argument.inspect}"
+        end
+      end
+
+      def serialized_global_id?(hash)
+        hash.size == 1 && hash.include?(GLOBALID_KEY)
+      end
+
+      def deserialize_global_id(hash)
+        GlobalID::Locator.locate hash[GLOBALID_KEY]
+      end
+
+      def custom_serialized?(hash)
+        hash.key?(OBJECT_SERIALIZER_KEY)
+      end
+
+      def serialize_hash(argument)
+        argument.each_with_object({}) do |(key, value), hash|
+          hash[serialize_hash_key(key)] = serialize_argument(value)
+        end
+      end
+
+      def deserialize_hash(serialized_hash)
+        result = serialized_hash.transform_values { |v| deserialize_argument(v) }
+        if result.delete(WITH_INDIFFERENT_ACCESS_KEY)
+          result = result.with_indifferent_access
+        elsif symbol_keys = result.delete(SYMBOL_KEYS_KEY)
+          result = transform_symbol_keys(result, symbol_keys)
+        elsif symbol_keys = result.delete(RUBY2_KEYWORDS_KEY)
+          result = transform_symbol_keys(result, symbol_keys)
+          result = Hash.ruby2_keywords_hash(result)
+        end
+        result
+      end
+
+      def serialize_hash_key(key)
+        case key
+        when *RESERVED_KEYS
+          raise SerializationError.new("Can't serialize a Hash with reserved key #{key.inspect}")
+        when String, Symbol
+          key.to_s
+        else
+          raise SerializationError.new("Only string and symbol hash keys may be serialized as job arguments, but #{key.inspect} is a #{key.class}")
+        end
+      end
+
+      def serialize_indifferent_hash(indifferent_hash)
+        result = serialize_hash(indifferent_hash)
+        result[WITH_INDIFFERENT_ACCESS_KEY] = serialize_argument(true)
+        result
+      end
+
+      def transform_symbol_keys(hash, symbol_keys)
+        # NOTE: HashWithIndifferentAccess#transform_keys always
+        # returns stringified keys with indifferent access
+        # so we call #to_h here to ensure keys are symbolized.
+        hash.to_h.transform_keys do |key|
+          if symbol_keys.include?(key)
+            key.to_sym
+          else
+            key
+          end
+        end
+      end
+
+      def convert_to_global_id_hash(argument)
+        { GLOBALID_KEY => argument.to_global_id.to_s }
+      rescue URI::GID::MissingModelIdError
+        raise SerializationError, "Unable to serialize #{argument.class} " \
+          "without an id. (Maybe you forgot to call save?)"
+      end
+  end
+end

data/lib/active_job/base.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "active_job/core"
+require "active_job/queue_adapter"
+require "active_job/queue_name"
+require "active_job/queue_priority"
+require "active_job/enqueuing"
+require "active_job/execution"
+require "active_job/callbacks"
+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"
+
+module ActiveJob # :nodoc:
+  # = Active Job \Base
+  #
+  # Active Job objects can be configured to work with different backend
+  # queuing frameworks. To specify a queue adapter to use:
+  #
+  #   ActiveJob::Base.queue_adapter = :inline
+  #
+  # A list of supported adapters can be found in QueueAdapters.
+  #
+  # Active Job objects can be defined by creating a class that inherits
+  # from the ActiveJob::Base class. The only necessary method to
+  # implement is the "perform" method.
+  #
+  # To define an Active Job object:
+  #
+  #   class ProcessPhotoJob < ActiveJob::Base
+  #     def perform(photo)
+  #       photo.watermark!('Rails')
+  #       photo.rotate!(90.degrees)
+  #       photo.resize_to_fit!(300, 300)
+  #       photo.upload!
+  #     end
+  #   end
+  #
+  # Records that are passed in are serialized/deserialized using Global
+  # ID. More information can be found in Arguments.
+  #
+  # To enqueue a job to be performed as soon as the queuing system is free:
+  #
+  #   ProcessPhotoJob.perform_later(photo)
+  #
+  # To enqueue a job to be processed at some point in the future:
+  #
+  #   ProcessPhotoJob.set(wait_until: Date.tomorrow.noon).perform_later(photo)
+  #
+  # More information can be found in ActiveJob::Core::ClassMethods#set
+  #
+  # A job can also be processed immediately without sending to the queue:
+  #
+  #  ProcessPhotoJob.perform_now(photo)
+  #
+  # == Exceptions
+  #
+  # * DeserializationError - Error class for deserialization errors.
+  # * SerializationError - Error class for serialization errors.
+  class Base
+    include Core
+    include QueueAdapter
+    include QueueName
+    include QueuePriority
+    include Enqueuing
+    include Execution
+    include Callbacks
+    include Exceptions
+    include Instrumentation
+    include Logging
+    include Timezones
+    include Translation
+
+    ActiveSupport.run_load_hooks(:active_job, self)
+  end
+end

data/lib/active_job/callbacks.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "active_support/callbacks"
+require "active_support/core_ext/module/attribute_accessors"
+
+module ActiveJob
+  # = Active Job \Callbacks
+  #
+  # Active Job provides hooks during the life cycle of a job. Callbacks allow you
+  # to trigger logic during this cycle. Available callbacks are:
+  #
+  # * <tt>before_enqueue</tt>
+  # * <tt>around_enqueue</tt>
+  # * <tt>after_enqueue</tt>
+  # * <tt>before_perform</tt>
+  # * <tt>around_perform</tt>
+  # * <tt>after_perform</tt>
+  module Callbacks
+    extend  ActiveSupport::Concern
+    include ActiveSupport::Callbacks
+
+    class << self
+      include ActiveSupport::Callbacks
+      define_callbacks :execute
+    end
+
+    included do
+      define_callbacks :perform, skip_after_callbacks_if_terminated: true
+      define_callbacks :enqueue, skip_after_callbacks_if_terminated: true
+    end
+
+    # These methods will be included into any Active Job object, adding
+    # callbacks for +perform+ and +enqueue+ methods.
+    module ClassMethods
+      # Defines a callback that will get called right before the
+      # job's perform method is executed.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     before_perform do |job|
+      #       UserMailer.notify_video_started_processing(job.arguments.first)
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      def before_perform(*filters, &blk)
+        set_callback(:perform, :before, *filters, &blk)
+      end
+
+      # Defines a callback that will get called right after the
+      # job's perform method has finished.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     after_perform do |job|
+      #       UserMailer.notify_video_processed(job.arguments.first)
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      def after_perform(*filters, &blk)
+        set_callback(:perform, :after, *filters, &blk)
+      end
+
+      # Defines a callback that will get called around the job's perform method.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     around_perform do |job, block|
+      #       UserMailer.notify_video_started_processing(job.arguments.first)
+      #       block.call
+      #       UserMailer.notify_video_processed(job.arguments.first)
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      # You can access the return value of the job only if the execution wasn't halted.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     around_perform do |job, block|
+      #       value = block.call
+      #       puts value # => "Hello World!"
+      #     end
+      #
+      #     def perform
+      #       "Hello World!"
+      #     end
+      #   end
+      #
+      def around_perform(*filters, &blk)
+        set_callback(:perform, :around, *filters, &blk)
+      end
+
+      # Defines a callback that will get called right before the
+      # job is enqueued.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     before_enqueue do |job|
+      #       $statsd.increment "enqueue-video-job.try"
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      def before_enqueue(*filters, &blk)
+        set_callback(:enqueue, :before, *filters, &blk)
+      end
+
+      # Defines a callback that will get called right after the
+      # job is enqueued.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     after_enqueue do |job|
+      #       result = job.successfully_enqueued? ? "success" : "failure"
+      #       $statsd.increment "enqueue-video-job.#{result}"
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      def after_enqueue(*filters, &blk)
+        set_callback(:enqueue, :after, *filters, &blk)
+      end
+
+      # Defines a callback that will get called around the enqueuing
+      # of the job.
+      #
+      #   class VideoProcessJob < ActiveJob::Base
+      #     queue_as :default
+      #
+      #     around_enqueue do |job, block|
+      #       $statsd.time "video-job.process" do
+      #         block.call
+      #       end
+      #     end
+      #
+      #     def perform(video_id)
+      #       Video.find(video_id).process
+      #     end
+      #   end
+      #
+      def around_enqueue(*filters, &blk)
+        set_callback(:enqueue, :around, *filters, &blk)
+      end
+    end
+  end
+end

data/lib/active_job/configured_job.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  class ConfiguredJob # :nodoc:
+    def initialize(job_class, options = {})
+      @options = options
+      @job_class = job_class
+    end
+
+    def perform_now(...)
+      @job_class.new(...).set(@options).perform_now
+    end
+
+    def perform_later(...)
+      @job_class.new(...).enqueue @options
+    end
+
+    def perform_all_later(multi_args)
+      @job_class.perform_all_later(multi_args, options: @options)
+    end
+  end
+end