acidic_job 0.7.7 → 0.8.0

data/lib/acidic_job/processor.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module AcidicJob
+  class Processor
+    def initialize(run, job)
+      @run = run
+      @job = job
+      @workflow = Workflow.new(run, job)
+    end
+
+    def process_run
+      # if the run record is already marked as finished, immediately return its result
+      return @run.succeeded? if @run.finished?
+
+      AcidicJob.logger.log_run_event("Processing #{@run.current_step_name}...", @job, @run)
+      loop do
+        break if @run.finished?
+
+        if !@run.known_recovery_point?
+          raise UnknownRecoveryPoint,
+                "Defined workflow does not reference this step: #{@run.current_step_name.inspect}"
+        elsif (awaited_jobs = jobs_from(@run.current_step_awaits)).any?
+          # We only execute the current step, without progressing to the next step.
+          # This ensures that any failures in parallel jobs will have this step retried in the main workflow
+          step_result = @workflow.execute_current_step
+          # We allow the `#step_done` method to manage progressing the recovery_point to the next step,
+          # and then calling `process_run` to restart the main workflow on the next step.
+          # We pass the `step_result` so that the async callback called after the step-parallel-jobs complete
+          # can move on to the appropriate next stage in the workflow.
+          enqueue_awaited_jobs(awaited_jobs, step_result)
+          # after processing the current step, break the processing loop
+          # and stop this method from blocking in the primary worker
+          # as it will continue once the background workers all succeed
+          # so we want to keep the primary worker queue free to process new work
+          # this CANNOT ever be `break` as that wouldn't exit the parent job,
+          # only this step in the workflow, blocking as it awaits the next step
+          return true
+        else
+          @workflow.execute_current_step
+          @workflow.progress_to_next_step
+        end
+      end
+      AcidicJob.logger.log_run_event("Processed #{@run.current_step_name}.", @job, @run)
+
+      @run.succeeded?
+    end
+
+    private
+
+    def enqueue_awaited_jobs(awaited_jobs, step_result)
+      AcidicJob.logger.log_run_event("Enqueuing #{awaited_jobs.count} awaited jobs...", @job, @run)
+      # All jobs created in the block are pushed atomically at the end of the block.
+      AcidicJob::Run.transaction do
+        awaited_jobs.each do |awaited_job|
+          worker_class, args = job_and_args(awaited_job)
+
+          job = worker_class.new(*args)
+
+          AcidicJob::Run.await!(job, by: @run, return_to: step_result)
+        end
+      end
+      AcidicJob.logger.log_run_event("Enqueued #{awaited_jobs.count} awaited jobs.", @job, @run)
+    end
+
+    def jobs_from(jobs_or_jobs_getter)
+      case jobs_or_jobs_getter
+      when Array
+        jobs_or_jobs_getter.compact
+      when Symbol, String
+        if @job.respond_to?(jobs_or_jobs_getter, _include_private = true)
+          jobs = @job.method(jobs_or_jobs_getter).call
+          Array(jobs).compact
+        else
+          raise UnknownAwaitedJob,
+                "Invalid `awaits`; unknown method `#{jobs_or_jobs_getter}` for this job"
+        end
+      else
+        raise UnknownAwaitedJob,
+              "Invalid `awaits`; must be either an jobs Array or method name, was: #{jobs_or_jobs_getter.class.name}"
+      end
+    end
+
+    def job_and_args(job)
+      case job
+      when Class
+        [job, []]
+      else
+        [
+          job.class,
+          job.arguments
+        ]
+      end
+    end
+  end
+end

data/lib/acidic_job/rails.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module AcidicJob
+  class Rails < ::Rails::Railtie
+    initializer "acidic_job.action_mailer_extension" do
+      ::ActiveSupport.on_load(:action_mailer) do
+        # Add `deliver_acidicly` to ActionMailer
+        ::ActionMailer::Parameterized::MessageDelivery.include(Extensions::ActionMailer)
+        ::ActionMailer::MessageDelivery.include(Extensions::ActionMailer)
+      end
+    end
+
+    initializer "acidic_job.active_job_serializers" do
+      ::ActiveSupport.on_load(:active_job) do
+        ::ActiveJob::Serializers.add_serializers(
+          Serializers::ExceptionSerializer,
+          Serializers::FinishedPointSerializer,
+          Serializers::JobSerializer,
+          Serializers::RangeSerializer,
+          Serializers::RecoveryPointSerializer,
+          Serializers::WorkerSerializer
+        )
+      end
+    end
+
+    generators do
+      require "generators/acidic_job/install_generator"
+    end
+
+    # This hook happens after all initializers are run, just before returning
+    config.after_initialize do
+      if defined?(::Noticed)
+        # Add `deliver_acidicly` to Noticed
+        ::Noticed::Base.include(Extensions::Noticed)
+      end
+    end
+  end
+end

data/lib/acidic_job/recovery_point.rb

@@ -4,15 +4,14 @@
 # return from an #atomic_phase block.
 module AcidicJob
   class RecoveryPoint
-    attr_accessor :name
+    attr_reader :name
 
     def initialize(name)
-      self.name = name
+      @name = name
     end
 
-    def call(key:)
-      # Skip AR callbacks as there are none on the model
-      key.update_column(:recovery_point, name)
+    def call(run:)
+      run.recover_to!(@name)
     end
   end
 end

data/lib/acidic_job/run.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "global_id"
+require "base64"
+require "active_support/core_ext/object/with_options"
+require "active_support/core_ext/module/concerning"
+require "active_support/concern"
+
+module AcidicJob
+  class Run < ActiveRecord::Base
+    include GlobalID::Identification
+
+    FINISHED_RECOVERY_POINT = "FINISHED"
+    STAGED_JOB_ID_PREFIX = "STG"
+    STAGED_JOB_ID_DELIMITER = "__"
+    IDEMPOTENCY_KEY_LOCK_TIMEOUT_SECONDS = 2
+
+    self.table_name = "acidic_job_runs"
+
+    validates :idempotency_key, presence: true
+    validate :not_awaited_but_unstaged
+
+    def self.clear_finished
+      # over-write any pre-existing relation queries on `recovery_point` and/or `error_object`
+      to_purge = finished
+
+      count = to_purge.count
+
+      return 0 if count.zero?
+
+      AcidicJob.logger.info("Deleting #{count} finished AcidicJob runs")
+      to_purge.delete_all
+    end
+
+    def succeeded?
+      finished? && !errored?
+    end
+
+    concerning :Awaitable do
+      included do
+        belongs_to :awaited_by, class_name: "AcidicJob::Run", optional: true
+        has_many :batched_runs, class_name: "AcidicJob::Run", foreign_key: "awaited_by_id"
+
+        scope :awaited, -> { where.not(awaited_by: nil) }
+        scope :unawaited, -> { where(awaited_by: nil) }
+
+        after_update_commit :proceed_with_parent, if: :finished?
+
+        serialize :returning_to, AcidicJob::Serializer
+      end
+
+      class_methods do
+        def await!(job, by:, return_to:)
+          create!(
+            staged: true,
+            awaited_by: by,
+            job_class: job.class.name,
+            serialized_job: job.serialize,
+            idempotency_key: job.idempotency_key
+          )
+          by.update(returning_to: return_to)
+        end
+      end
+
+      def awaited?
+        awaited_by.present?
+      end
+
+      private
+
+      def proceed_with_parent
+        return unless finished?
+        return unless awaited_by.present?
+        return if awaited_by.batched_runs.outstanding.any?
+
+        AcidicJob.logger.log_run_event("Proceeding with parent job...", job, self)
+        awaited_by.unlock!
+        awaited_by.proceed
+        AcidicJob.logger.log_run_event("Proceeded with parent job.", job, self)
+      end
+
+      protected
+
+      def proceed
+        # this needs to be explicitly set so that `was_workflow_job?` appropriately returns `true`
+        # TODO: replace this with some way to check the type of the job directly
+        # either via class method or explicit module inclusion
+        job.instance_variable_set(:@acidic_job_run, self)
+
+        workflow = Workflow.new(self, job, returning_to)
+        # TODO: WRITE REGRESSION TESTS FOR PARALLEL JOB FAILING AND RETRYING THE ORIGINAL STEP
+        workflow.progress_to_next_step
+
+        # when a batch of jobs for a step succeeds, we begin processing the `AcidicJob::Run` record again
+        return if finished?
+
+        AcidicJob.logger.log_run_event("Re-enqueuing parent job...", job, self)
+        enqueue_job
+        AcidicJob.logger.log_run_event("Re-enqueued parent job.", job, self)
+      end
+    end
+
+    concerning :Stageable do
+      included do
+        after_create_commit :enqueue_job, if: :staged?
+
+        validates :staged, inclusion: { in: [true, false] } # uses database default
+
+        scope :staged, -> { where(staged: true) }
+        scope :unstaged, -> { where(staged: false) }
+      end
+
+      class_methods do
+        def stage!(job)
+          create!(
+            staged: true,
+            job_class: job.class.name,
+            serialized_job: job.serialize,
+            idempotency_key: job.try(:idempotency_key) || job.job_id
+          )
+        end
+      end
+
+      private
+
+      def job_id
+        return idempotency_key unless staged?
+
+        # encode the identifier for this record in the job ID
+        global_id = to_global_id.to_s.remove("gid://")
+        # base64 encoding for minimal security
+        encoded_global_id = Base64.urlsafe_encode64(global_id, padding: false)
+
+        [
+          STAGED_JOB_ID_PREFIX,
+          idempotency_key,
+          encoded_global_id
+        ].join(STAGED_JOB_ID_DELIMITER)
+      end
+    end
+
+    concerning :Workflowable do
+      included do
+        serialize :workflow, AcidicJob::Serializer
+        serialize :error_object, AcidicJob::Serializer
+        store :attr_accessors, coder: AcidicJob::Serializer
+
+        with_options unless: :staged? do
+          validates :last_run_at, presence: true
+          validates :recovery_point, presence: true
+          validates :workflow, presence: true
+        end
+      end
+
+      def workflow?
+        self[:workflow].present?
+      end
+
+      def attr_accessors
+        self[:attr_accessors] || {}
+      end
+
+      def current_step_name
+        recovery_point
+      end
+
+      def current_step_hash
+        workflow[current_step_name]
+      end
+
+      def next_step_name
+        current_step_hash.fetch("then")
+      end
+
+      def current_step_awaits
+        current_step_hash["awaits"]
+      end
+
+      def next_step_finishes?
+        next_step_name.to_s == FINISHED_RECOVERY_POINT
+      end
+
+      def current_step_finished?
+        current_step_name.to_s == FINISHED_RECOVERY_POINT
+      end
+    end
+
+    concerning :Jobbable do
+      included do
+        serialize :serialized_job, JSON
+
+        validates :serialized_job, presence: true
+        validates :job_class, presence: true
+      end
+
+      def job
+        return @job if defined? @job
+
+        serialized_job_for_run = serialized_job.merge("job_id" => job_id)
+        job_class_for_run = job_class.constantize
+
+        @job = job_class_for_run.deserialize(serialized_job_for_run)
+      end
+
+      def enqueue_job
+        job.enqueue
+
+        # NOTE: record will be deleted after the job has successfully been performed
+        true
+      end
+    end
+
+    concerning :Finishable do
+      included do
+        scope :finished, -> { where(recovery_point: FINISHED_RECOVERY_POINT) }
+        scope :outstanding, lambda {
+                              where.not(recovery_point: FINISHED_RECOVERY_POINT).or(where(recovery_point: [nil, ""]))
+                            }
+      end
+
+      def finish!
+        finish and unlock and save!
+      end
+
+      def finish
+        self.recovery_point = FINISHED_RECOVERY_POINT
+        self
+      end
+
+      def finished?
+        recovery_point.to_s == FINISHED_RECOVERY_POINT
+      end
+    end
+
+    concerning :Unlockable do
+      included do
+        scope :unlocked, -> { where(locked_at: nil) }
+        scope :locked, -> { where.not(locked_at: nil) }
+      end
+
+      def unlock!
+        unlock and save!
+      end
+
+      def unlock
+        self.locked_at = nil
+        self
+      end
+
+      def locked?
+        locked_at.present?
+      end
+
+      def lock_active?
+        return false if locked_at.nil?
+
+        locked_at > Time.current - IDEMPOTENCY_KEY_LOCK_TIMEOUT_SECONDS
+      end
+    end
+
+    concerning :ErrorStoreable do
+      included do
+        scope :unerrored, -> { where(error_object: nil) }
+        scope :errored, -> { where.not(error_object: nil) }
+      end
+
+      def store_error!(error)
+        reload and unlock and store_error(error) and save!
+      end
+
+      def store_error(error)
+        self.error_object = error
+        self
+      end
+
+      def errored?
+        error_object.present?
+      end
+    end
+
+    concerning :Recoverable do
+      def recover_to!(point)
+        recover_to(point) and save!
+      end
+
+      def recover_to(point)
+        self.recovery_point = point
+        self
+      end
+
+      def known_recovery_point?
+        workflow.key?(recovery_point)
+      end
+    end
+
+    def not_awaited_but_unstaged
+      return true unless awaited? && !staged?
+
+      errors.add(:base, "cannot be awaited by another job but not staged")
+    end
+  end
+end

data/lib/acidic_job/serializer.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "json"
+
+module AcidicJob
+  class Serializer
+    # Used for `serialize` method in ActiveRecord
+    class << self
+      def load(json)
+        return if json.nil? || json.empty?
+
+        data = JSON.parse(json)
+        Arguments.send :deserialize_argument, data
+      end
+
+      def dump(obj)
+        data = Arguments.send :serialize_argument, obj
+        data.to_json
+      rescue ActiveJob::SerializationError
+        raise UnserializableValue
+      end
+    end
+  end
+end

data/lib/acidic_job/serializers/exception_serializer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "active_job/serializers/object_serializer"
+
+module AcidicJob
+  module Serializers
+    class ExceptionSerializer < ::ActiveJob::Serializers::ObjectSerializer
+      def serialize(exception)
+        hash = {
+          "class" => exception.class.name,
+          "message" => exception.message,
+          "cause" => exception.cause,
+          "backtrace" => {}
+        }
+
+        exception.backtrace.map do |trace|
+          path, _, location = trace.rpartition("/")
+
+          next if hash["backtrace"].key?(path)
+
+          hash["backtrace"][path] = location
+        end
+
+        super(hash)
+      end
+
+      def deserialize(hash)
+        exception_class = hash["class"].constantize
+        exception = exception_class.new(hash["message"])
+        exception.set_backtrace(hash["backtrace"].map do |path, location|
+          [path, location].join("/")
+        end)
+        exception
+      end
+
+      def serialize?(argument)
+        defined?(Exception) && argument.is_a?(Exception)
+      end
+    end
+  end
+end

data/lib/acidic_job/serializers/finished_point_serializer.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "active_job/serializers/object_serializer"
+
+module AcidicJob
+  module Serializers
+    class FinishedPointSerializer < ::ActiveJob::Serializers::ObjectSerializer
+      def serialize(finished_point)
+        super(
+          "class" => finished_point.class.name
+        )
+      end
+
+      def deserialize(hash)
+        finished_point_class = hash["class"].constantize
+        finished_point_class.new
+      end
+
+      def serialize?(argument)
+        defined?(::AcidicJob::FinishedPoint) && argument.is_a?(::AcidicJob::FinishedPoint)
+      end
+    end
+  end
+end

data/lib/acidic_job/serializers/job_serializer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "active_job/serializers/object_serializer"
+
+module AcidicJob
+  module Serializers
+    class JobSerializer < ::ActiveJob::Serializers::ObjectSerializer
+      def serialize(job)
+        # don't serialize the `enqueued_at` value, as ActiveRecord will check if the Run record has changed
+        # by comparing the deserialized database value with a temporary in-memory generated value.
+        # That temporary in-memory generated value can sometimes have an `enqueued_at` value that is 1 second off
+        # from the original. In this case, ActiveRecord will think the record has unsaved changes and block the lock.
+        super(job.as_json.merge("job_class" => job.class.name))
+      end
+
+      def deserialize(hash)
+        job = ::ActiveJob::Base.deserialize(hash)
+        job.send(:deserialize_arguments_if_needed)
+        job
+      end
+
+      def serialize?(argument)
+        defined?(::ActiveJob::Base) && argument.class < ::ActiveJob::Base
+      end
+    end
+  end
+end

data/lib/acidic_job/serializers/range_serializer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "active_job/serializers/object_serializer"
+
+# :nocov:
+module AcidicJob
+  module Serializers
+    class RangeSerializer < ::ActiveJob::Serializers::ObjectSerializer
+      KEYS = %w[begin end exclude_end].freeze
+
+      def serialize(range)
+        args = Arguments.serialize([range.begin, range.end, range.exclude_end?])
+        super(KEYS.zip(args).to_h)
+      end
+
+      def deserialize(hash)
+        klass.new(*Arguments.deserialize(hash.values_at(*KEYS)))
+      end
+
+      private
+
+      def klass
+        ::Range
+      end
+    end
+  end
+end
+# :nocov:

data/lib/acidic_job/serializers/recovery_point_serializer.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "active_job/serializers/object_serializer"
+
+module AcidicJob
+  module Serializers
+    class RecoveryPointSerializer < ::ActiveJob::Serializers::ObjectSerializer
+      def serialize(recovery_point)
+        super(
+          "class" => recovery_point.class.name,
+          "name" => recovery_point.name
+        )
+      end
+
+      def deserialize(hash)
+        recovery_point_class = hash["class"].constantize
+        recovery_point_class.new(hash["name"])
+      end
+
+      def serialize?(argument)
+        defined?(::AcidicJob::RecoveryPoint) && argument.is_a?(::AcidicJob::RecoveryPoint)
+      end
+    end
+  end
+end

data/lib/acidic_job/serializers/worker_serializer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "active_job/serializers/object_serializer"
+
+# :nocov:
+module AcidicJob
+  module Serializers
+    class WorkerSerializer < ::ActiveJob::Serializers::ObjectSerializer
+      def serialize(worker)
+        super(
+          "job_class" => worker.class.name,
+          "arguments" => worker.arguments,
+        )
+      end
+
+      def deserialize(hash)
+        worker_class = hash["job_class"].constantize
+        worker_class.new(*hash["arguments"])
+      end
+
+      def serialize?(argument)
+        defined?(::Sidekiq) && argument.class.include?(::Sidekiq::Worker)
+      end
+    end
+  end
+end
+# :nocov:

data/lib/acidic_job/test_case.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "./testing"
+
+module AcidicJob
+  class TestCase < ::ActiveJob::TestCase
+    include ::AcidicJob::Testing
+  end
+end