acidic_job 0.7.5 → 1.0.0.beta.1

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,299 @@
+# 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.idempotency_key
+          )
+        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.encode64(global_id).strip
+
+        [
+          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 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.deserialize(data).first
+      end
+
+      def dump(obj)
+        data = Arguments.serialize [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,35 @@
+# frozen_string_literal: true
+
+require "active_job/serializers/object_serializer"
+
+module AcidicJob
+  module Serializers
+    class JobSerializer < ::ActiveJob::Serializers::ObjectSerializer
+      def serialize(job)
+        super(job.serialize)
+      end
+
+      def deserialize(hash)
+        job = ActiveJob::Base.deserialize(hash)
+        job.send(:deserialize_arguments_if_needed)
+        # this is a shim to ensure we can work with Ruby 2.7 as well as 3.0+
+        # :nocov:
+        if job.arguments.last.is_a?(Hash)
+          *args, kwargs = job.arguments
+        else
+          args = job.arguments
+          kwargs = {}
+        end
+        # :nocov:
+        job.instance_variable_set(:@__acidic_job_args, args)
+        job.instance_variable_set(:@__acidic_job_kwargs, kwargs)
+
+        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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AcidicJob
-  VERSION = "0.7.5"
+  VERSION = "1.0.0.beta.1"
 end

data/lib/acidic_job/workflow.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module AcidicJob
+  class Workflow
+    # { "step 1": { does: "step 1", awaits: [], then: "step 2" }, ...  }
+    def initialize(run, job, step_result = nil)
+      @run = run
+      @job = job
+      @step_result = step_result
+    end
+
+    def execute_current_step
+      rescued_error = false
+
+      begin
+        run_current_step
+      rescue StandardError => e
+        rescued_error = e
+        raise e
+      ensure
+        if rescued_error
+          begin
+            @run.store_error!(rescued_error)
+          rescue StandardError => e
+            # We're already inside an error condition, so swallow any additional
+            # errors from here and just send them to logs.
+            AcidicJob.logger.error("Failed to unlock AcidicJob::Run #{@run.id} because of #{e}.")
+          end
+        end
+      end
+
+      # be sure to return the `step_result`
+      # which is set by `run_current_step`
+      # which runs the (wrapped) current step method
+      @step_result
+    end
+
+    def progress_to_next_step
+      return if @run.current_step_finished?
+      return run_step_result unless @run.next_step_finishes?
+
+      @job.run_callbacks :finish do
+        run_step_result
+      end
+    end
+
+    private
+
+    def run_current_step
+      wrapped_method = WorkflowStep.new(run: @run, job: @job).wrapped
+      current_step = @run.current_step_name
+
+      # can't reproduce yet, but saw a bug in production where
+      # nested awaits workflows had an unsaved `workflow` attribute
+      @run.save! if @run.has_changes_to_save?
+
+      AcidicJob.logger.log_run_event("Executing #{current_step}...", @job, @run)
+      @run.with_lock do
+        @step_result = wrapped_method.call(@run)
+      end
+      AcidicJob.logger.log_run_event("Executed #{current_step}.", @job, @run)
+    end
+
+    def run_step_result
+      next_step = @run.next_step_name
+
+      # can't reproduce yet, but saw a bug in production where
+      # nested awaits workflows had an unsaved `workflow` attribute
+      @run.save! if @run.has_changes_to_save?
+
+      AcidicJob.logger.log_run_event("Progressing to #{next_step}...", @job, @run)
+      @run.with_lock do
+        @step_result.call(run: @run)
+      end
+      AcidicJob.logger.log_run_event("Progressed to #{next_step}.", @job, @run)
+    end
+  end
+end

data/lib/acidic_job/workflow_builder.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module AcidicJob
+  class WorkflowBuilder
+    attr_reader :steps
+
+    def initialize
+      @steps = []
+    end
+
+    def step(method_name, awaits: [], for_each: nil)
+      @steps << {
+        "does" => method_name.to_s,
+        "awaits" => awaits,
+        "for_each" => for_each
+      }
+
+      @steps
+    end
+    alias_method "✅", :step
+
+    def define_workflow
+      # [ { does: "step 1", awaits: [] }, { does: "step 2", awaits: [] }, ... ]
+      @steps << { "does" => Run::FINISHED_RECOVERY_POINT.to_s }
+
+      {}.tap do |workflow|
+        @steps.each_cons(2).map do |enter_step, exit_step|
+          enter_name = enter_step["does"]
+          workflow[enter_name] = enter_step.merge("then" => exit_step["does"])
+        end
+      end
+      # { "step 1": { does: "step 1", awaits: [], then: "step 2" }, ...  }
+    end
+  end
+end