acidic_job 0.7.7 → 1.0.0.beta.1

data/gemfiles/rails_6.1.gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "activemodel", "~> 6.1.0"
+gem "railties", "~> 6.1.0"
+
+gemspec path: "../"

data/gemfiles/rails_7.0.gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "activemodel", "~> 7.0.0"
+gem "railties", "~> 7.0.0"
+
+gemspec path: "../"

data/lib/acidic_job/active_kiq.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "sidekiq"
+require "active_support/callbacks"
+require "active_support/core_ext/module/concerning"
+require_relative "mixin"
+
+module AcidicJob
+  class ActiveKiq
+    include ::Sidekiq::Worker
+    include ::Sidekiq::JobUtil
+    include ::ActiveSupport::Callbacks
+    define_callbacks :perform
+    include Mixin
+
+    concerning :Initializing do
+      included do
+        attr_accessor :arguments
+        attr_accessor :job_id
+        attr_accessor :queue_name
+        attr_accessor :sidekiq_options
+      end
+      ##
+      # Creates a new job instance.
+      # +args+ are the arguments, if any, that will be passed to the perform method
+      # +opts+ are any options to configure the job
+      def initialize(*arguments)
+        @arguments  = arguments
+        @job_id     = SecureRandom.uuid
+        @sidekiq_options = sidekiq_options_hash || Sidekiq.default_job_options
+        @queue_name = @sidekiq_options["queue"]
+      end
+
+      # Sidekiq sets the `jid` when it is processing jobs off of the Redis queue.
+      # We override the job identifier when staging jobs to encode the `Run` record global id.
+      # We also override how "ActiveKiq" instance's expose the job identifier to match ActiveJob.
+      # So, we need to ensure that when `jid=` is called, we set the `job_id` instead.
+      def jid=(value)
+        super
+        @job_id = value
+      end
+    end
+
+    concerning :Performing do
+      class_methods do
+        def perform_now(*args, **kwargs)
+          new.perform(*args, **kwargs)
+        end
+      end
+
+      def perform_now(*args, **kwargs)
+        perform(*args, **kwargs)
+      end
+
+      def enqueue
+        ::Sidekiq::Client.push(
+          "class" => self.class,
+          "args" => @arguments,
+          "jid" => @job_id,
+          "queue" => @queue_name
+        )
+      end
+    end
+
+    concerning :Serializing do
+      class_methods do
+        def deserialize(job_data)
+          job = job_data["job_class"].constantize.new
+          job.deserialize(job_data)
+          job
+        end
+      end
+
+      def serialize
+        return @serialize if defined? @serialize
+
+        item = @sidekiq_options.merge("class" => self.class.name, "args" => @arguments || [])
+        worker_hash = normalize_item(item)
+
+        @serialize = {
+          "job_class" => worker_hash["class"],
+          "job_id" => @job_id,
+          "queue_name" => worker_hash["queue"],
+          "arguments" => worker_hash["args"]
+        }.merge(worker_hash.except("class", "jid", "queue", "args"))
+      end
+
+      def deserialize(job_data)
+        self.job_id = job_data["job_id"]
+        self.queue_name = job_data["queue_name"]
+        self.arguments = job_data["arguments"]
+        self
+      end
+    end
+
+    # Following approach used by ActiveJob
+    # https://github.com/rails/rails/blob/93c9534c9871d4adad4bc33b5edc355672b59c61/activejob/lib/active_job/callbacks.rb
+    concerning :Callbacks do
+      class_methods do
+        def around_perform(*filters, &blk)
+          set_callback(:perform, :around, *filters, &blk)
+        end
+
+        def before_perform(*filters, &blk)
+          set_callback(:perform, :before, *filters, &blk)
+        end
+
+        def after_perform(*filters, &blk)
+          set_callback(:perform, :after, *filters, &blk)
+        end
+      end
+    end
+  end
+end

data/lib/acidic_job/arguments.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "active_job/arguments"
+
+module AcidicJob
+  module Arguments
+    include ActiveJob::Arguments
+    extend self # rubocop:disable Style/ModuleFunction
+
+    # `ActiveJob` will throw an error if it tries to deserialize a GlobalID record.
+    # However, this isn't the behavior that we want for our custom `ActiveRecord` serializer.
+    # Since `ActiveRecord` does _not_ reset instance record state to its pre-transactional state
+    # on a transaction ROLLBACK, we can have GlobalID entries in a serialized column that point to
+    # non-persisted records. This is ok. We should simply return `nil` for that portion of the
+    # serialized field.
+    def deserialize_global_id(hash)
+      GlobalID::Locator.locate hash[GLOBALID_KEY]
+    rescue ActiveRecord::RecordNotFound
+      nil
+    end
+  end
+end

data/lib/acidic_job/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "active_job/queue_adapters"
+require "active_job/base"
+require_relative "mixin"
+
+module AcidicJob
+  class Base < ActiveJob::Base
+    include Mixin
+  end
+end

data/lib/acidic_job/errors.rb

@@ -2,24 +2,17 @@
 
 module AcidicJob
   class Error < StandardError; end
-
-  class MismatchedIdempotencyKeyAndJobArguments < Error; end
-
-  class LockedIdempotencyKey < Error; end
-
+  class MissingWorkflowBlock < Error; end
   class UnknownRecoveryPoint < Error; end
-
-  class UnknownAtomicPhaseType < Error; end
-
-  class SerializedTransactionConflict < Error; end
-
-  class UnknownJobAdapter < Error; end
-
   class NoDefinedSteps < Error; end
-
-  class SidekiqBatchRequired < Error; end
-
+  class RedefiningWorkflow < Error; end
+  class UndefinedStepMethod < Error; end
+  class UnknownForEachCollection < Error; end
+  class UniterableForEachCollection < Error; end
+  class UnknownJobAdapter < Error; end
+  class UnknownAwaitedJob < Error; end
   class TooManyParametersForStepMethod < Error; end
-
-  class TooManyParametersForParallelJob < Error; end
+  class UnserializableValue < Error; end
+  class LockedIdempotencyKey < Error; end
+  class MismatchedIdempotencyKeyAndJobArguments < Error; end
 end

data/lib/acidic_job/{response.rb → finished_point.rb}

@@ -1,16 +1,14 @@
 # frozen_string_literal: true
 
+require_relative "run"
+
 # Represents an action to set a new API response (which will be stored onto an
 # idempotency key). One  possible option for a return from an #atomic_phase
 # block.
 module AcidicJob
-  class Response
-    def call(key:)
-      # Skip AR callbacks as there are none on the model
-      key.update_columns(
-        locked_at: nil,
-        recovery_point: Key::RECOVERY_POINT_FINISHED
-      )
+  class FinishedPoint
+    def call(run:)
+      run.finish!
     end
   end
 end

data/lib/acidic_job/idempotency_key.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module AcidicJob
+  class IdempotencyKey
+    def initialize(job)
+      @job = job
+    end
+
+    def value(acidic_by: :job_id)
+      case acidic_by
+      when Proc
+        proc_result = @job.instance_exec(&acidic_by)
+        Digest::SHA1.hexdigest [@job.class.name, proc_result].flatten.join
+      when :job_arguments
+        Digest::SHA1.hexdigest [@job.class.name, @job.arguments].flatten.join
+      else
+        if @job.job_id.start_with? Run::STAGED_JOB_ID_PREFIX
+          # "STG__#{idempotency_key}__#{encoded_global_id}"
+          _prefix, idempotency_key, _encoded_global_id = @job.job_id.split("__")
+          idempotency_key
+        else
+          @job.job_id
+        end
+      end
+    end
+  end
+end

data/lib/acidic_job/logger.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "logger"
+require "active_support/tagged_logging"
+
+module AcidicJob
+  class Logger < ::Logger
+    def log_run_event(msg, job = nil, run = nil)
+      tags = [
+        run&.idempotency_key,
+        inspect_name(job)
+      ].compact
+
+      tagged(*tags) { debug(msg) }
+    end
+
+    def inspect_name(obj)
+      return if obj.nil?
+
+      obj.inspect.split.first.remove("#<")
+    end
+  end
+
+  def self.logger
+    @logger ||= ActiveSupport::TaggedLogging.new(AcidicJob::Logger.new($stdout, level: :debug))
+  end
+
+  def self.silence_logger!
+    @logger = ActiveSupport::TaggedLogging.new(AcidicJob::Logger.new(IO::NULL, level: :debug))
+  end
+end

data/lib/acidic_job/mixin.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module AcidicJob
+  module Mixin
+    extend ActiveSupport::Concern
+
+    def self.wire_up(other)
+      raise UnknownJobAdapter unless (defined?(::ActiveJob::Base) && other < ::ActiveJob::Base) ||
+                                     (defined?(::Sidekiq::Worker) && other.include?(::Sidekiq::Worker))
+
+      # Ensure our `perform` method always runs first to gather parameters
+      # and run perform callbacks for Sidekiq workers
+      other.prepend PerformWrapper
+
+      # By default, we unique job runs by the `job_id`
+      other.instance_variable_set(:@acidic_identifier, :job_id)
+      # However, you can customize this behavior on a per job class level
+      other.define_singleton_method(:acidic_by_job_identifier) { @acidic_identifier = :job_id }
+      # You could unique job runs by the arguments passed to the job (e.g. memoization)
+      other.define_singleton_method(:acidic_by_job_arguments) { @acidic_identifier = :job_arguments }
+      # Or, you could unique jobs run by any logic you'd like using a block
+      other.define_singleton_method(:acidic_by) { |&block| @acidic_identifier = block }
+
+      # We add a callback to ensure that staged, non-workflow jobs are "finished" after they are "performed".
+      # This allows us to ensure that we can always inspect whether a run is finished and get correct data
+      other.set_callback :perform, :after, :finish_staged_job, if: -> { was_staged_job? && !was_workflow_job? }
+      # We also allow you to write any of your own callbacks keyed to the "finish" event.
+      # The "finish" event is notably different from the "perform" event for acidic jobs,
+      # as any acidic job can have one or more "perform" event (retries or a resume after awaiting jobs),
+      # but will only ever have one "finish" event (when the run successfully completes)
+      other.define_callbacks :finish
+    end
+
+    included do
+      Mixin.wire_up(self)
+    end
+
+    class_methods do
+      def inherited(subclass)
+        Mixin.wire_up(subclass)
+        super
+      end
+
+      # `perform_now` runs a job synchronously and immediately
+      # `perform_later` runs a job asynchronously and queues it immediately
+      # `perform_acidicly` run a job asynchronously and queues it after a successful database commit
+      def perform_acidicly(*args)
+        job = new(*args)
+
+        Run.stage!(job)
+      end
+
+      # Instantiate an instance of a job ready for serialization
+      def with(...)
+        # New delegation syntax (...) was introduced in Ruby 2.7.
+        # https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/
+        job = new(...)
+        # force the job to resolve the `queue_name`, so that we don't try to serialize a Proc into ActiveRecord
+        job.queue_name
+        job
+      end
+    end
+
+    def idempotency_key
+      IdempotencyKey.new(self).value(acidic_by: acidic_identifier)
+    end
+
+    protected
+
+    # Short circuits execution by sending execution right to 'finished'.
+    # So, ends the job "successfully"
+    def safely_finish_acidic_job
+      FinishedPoint.new
+    end
+
+    def with_acidic_workflow(persisting: {}, &block)
+      raise RedefiningWorkflow if defined? @workflow_builder
+
+      @workflow_builder = WorkflowBuilder.new
+
+      raise MissingWorkflowBlock, "A block must be passed to `with_acidic_workflow`" unless block_given?
+
+      if block.arity.zero?
+        @workflow_builder.instance_exec(&block)
+      else
+        yield @workflow_builder
+      end
+
+      raise NoDefinedSteps if @workflow_builder.steps.empty?
+
+      # convert the array of steps into a hash of recovery_points and next steps
+      workflow = @workflow_builder.define_workflow
+
+      ensure_run_record_and_process(workflow, persisting)
+    rescue LocalJumpError
+      raise MissingWorkflowBlock, "A block must be passed to `with_acidic_workflow`"
+    end
+
+    # DEPRECATED
+    # second attempt at the DSL, but `providing` suggested you needed to serialize
+    # any data that would be used in step methods, but simply instance variables work.
+    def with_acidity(providing: {}, &block)
+      ::ActiveSupport::Deprecation.new("1.0", "AcidicJob").deprecation_warning(:with_acidity)
+
+      @workflow_builder = WorkflowBuilder.new
+      @workflow_builder.instance_exec(&block)
+
+      raise NoDefinedSteps if @workflow_builder.steps.empty?
+
+      # convert the array of steps into a hash of recovery_points and next steps
+      workflow = @workflow_builder.define_workflow
+
+      ensure_run_record_and_process(workflow, providing)
+    rescue LocalJumpError
+      raise MissingWorkflowBlock, "A block must be passed to `with_acidity`"
+    end
+
+    # DEPRECATED
+    # first attempt at the DSL, but `idempotently` and `with` are too distant from the gem name.
+    def idempotently(with: {}, &block)
+      ::ActiveSupport::Deprecation.new("1.0", "AcidicJob").deprecation_warning(:idempotently)
+
+      @workflow_builder = WorkflowBuilder.new
+      @workflow_builder.instance_exec(&block)
+
+      raise NoDefinedSteps if @workflow_builder.steps.empty?
+
+      # convert the array of steps into a hash of recovery_points and next steps
+      workflow = @workflow_builder.define_workflow
+
+      ensure_run_record_and_process(workflow, with)
+    rescue LocalJumpError
+      raise MissingWorkflowBlock, "A block must be passed to `idempotently`"
+    end
+
+    private
+
+    # You can always retrieve the unique identifier from within the job instance itself
+    def acidic_identifier
+      self.class.instance_variable_get(:@acidic_identifier)
+    end
+
+    def ensure_run_record_and_process(workflow, persisting)
+      ::AcidicJob.logger.log_run_event("Initializing run...", self, nil)
+      @acidic_job_run = ::ActiveRecord::Base.transaction(isolation: acidic_isolation_level) do
+        run = Run.find_by(idempotency_key: idempotency_key)
+        serialized_job = serialize
+
+        if run.present?
+          # Programs enqueuing multiple jobs with different parameters but the
+          # same idempotency key is a bug.
+          if run.serialized_job["arguments"] != serialized_job["arguments"]
+            raise MismatchedIdempotencyKeyAndJobArguments
+          end
+
+          # Only acquire a lock if the key is unlocked or its lock has expired
+          # because the original job was long enough ago.
+          raise LockedIdempotencyKey if run.lock_active?
+
+          run.update!(
+            last_run_at: Time.current,
+            locked_at: Time.current,
+            # staged workflow jobs won't have the `workflow` or `recovery_point` stored when staged,
+            # so we need to persist both here.
+            workflow: workflow,
+            recovery_point: run.recovery_point || workflow.keys.first
+          )
+        else
+          run = Run.create!(
+            staged: false,
+            idempotency_key: idempotency_key,
+            job_class: self.class.name,
+            locked_at: Time.current,
+            last_run_at: Time.current,
+            workflow: workflow,
+            recovery_point: workflow.keys.first,
+            serialized_job: serialize
+          )
+        end
+
+        # persist `persisting` values and set accessors for each
+        # first, get the current state of all accessors for both previously persisted and initialized values
+        current_accessors = persisting.stringify_keys.merge(run.attr_accessors)
+
+        # next, ensure that `Run#attr_accessors` is populated with initial values
+        # skip validations for this call to ensure a write
+        run.update_column(:attr_accessors, current_accessors) if current_accessors != run.attr_accessors
+
+        # finally, set reader and writer methods
+        current_accessors.each do |accessor, value|
+          # the reader method may already be defined
+          self.class.attr_reader accessor unless respond_to?(accessor)
+          # but we should always update the value to match the current value
+          instance_variable_set("@#{accessor}", value)
+          # and we overwrite the setter to ensure any updates to an accessor update the `Run` stored value
+          # Note: we must define the singleton method on the instance to avoid overwriting setters on other
+          # instances of the same class
+          define_singleton_method("#{accessor}=") do |updated_value|
+            instance_variable_set("@#{accessor}", updated_value)
+            run.attr_accessors[accessor] = updated_value
+            run.save!(validate: false)
+            updated_value
+          end
+        end
+
+        # ensure that we return the `run` record so that the result of this block is the record
+        run
+      end
+      ::AcidicJob.logger.log_run_event("Initialized run.", self, @acidic_job_run)
+
+      Processor.new(@acidic_job_run, self).process_run
+    end
+
+    def was_staged_job?
+      job_id.start_with? Run::STAGED_JOB_ID_PREFIX
+    end
+
+    def was_workflow_job?
+      return false unless defined? @acidic_job_run
+
+      @acidic_job_run.present?
+    end
+
+    def staged_job_run
+      return unless was_staged_job?
+      # memoize so we don't have to make unnecessary database calls
+      return @staged_job_run if defined? @staged_job_run
+
+      # "STG__#{idempotency_key}__#{encoded_global_id}"
+      _prefix, _idempotency_key, encoded_global_id = job_id.split("__")
+      staged_job_gid = "gid://#{::Base64.decode64(encoded_global_id)}"
+
+      @staged_job_run = ::GlobalID::Locator.locate(staged_job_gid)
+    end
+
+    def finish_staged_job
+      staged_job_run.finish!
+    end
+
+    def acidic_isolation_level
+      case ::ActiveRecord::Base.connection.adapter_name.downcase.to_sym
+      # SQLite doesn't support `serializable` transactions,
+      # so we use the strictest isolation_level is does support
+      when :sqlite
+        :read_uncommitted
+      else
+        :serializable
+      end
+    end
+  end
+end

data/lib/acidic_job/perform_wrapper.rb

@@ -1,35 +1,22 @@
 # frozen_string_literal: true
 
 module AcidicJob
+  # NOTE: it is essential that this be a bare module and not an ActiveSupport::Concern
+  # WHY?
   module PerformWrapper
     def perform(*args, **kwargs)
-      # extract the `staged_job_gid` if present
-      # so that we can later delete the record in an `after_perform` callback
-      final_arg = args.last
-      if final_arg.is_a?(Hash) && final_arg.key?("staged_job_gid")
-        args = args[0..-2]
-        @staged_job_gid = final_arg["staged_job_gid"]
-      end
-
-      set_arguments_for_perform(*args, **kwargs)
-
-      super(*args, **kwargs)
-    end
-
-    private
+      @arguments = args
 
-    def set_arguments_for_perform(*args, **kwargs)
-      # store arguments passed into `perform` so that we can later persist
-      # them to `AcidicJob::Key#job_args` for both ActiveJob and Sidekiq::Worker
-      @arguments_for_perform = if args.any? && kwargs.any?
-                                 args + [kwargs]
-                               elsif args.any? && kwargs.none?
-                                 args
-                               elsif args.none? && kwargs.any?
-                                 [kwargs]
-                               else
-                                 []
-                               end
+      # we don't want to run the `perform` callbacks twice, since ActiveJob already handles that for us
+      if defined?(ActiveJob) && self.class < ActiveJob::Base
+        super(*args, **kwargs)
+      elsif defined?(Sidekiq) && self.class.include?(Sidekiq::Worker)
+        run_callbacks :perform do
+          super(*args, **kwargs)
+        end
+      else
+        raise UnknownJobAdapter
+      end
     end
   end
 end

data/lib/acidic_job/processor.rb

@@ -0,0 +1,96 @@
+# 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 !Array(awaited_jobs = @run.current_step_hash.fetch("awaits", [])).compact.empty?
+          # 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(jobs_or_jobs_getter, step_result)
+      awaited_jobs = jobs_from(jobs_or_jobs_getter)
+
+      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_args_and_kwargs(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
+      when Symbol, String
+        if @job.respond_to?(jobs_or_jobs_getter)
+          @job.method(jobs_or_jobs_getter).call
+        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_args_and_kwargs(job)
+      case job
+      when Class
+        [job, []]
+      else
+        [
+          job.class,
+          job.arguments
+        ]
+      end
+    end
+  end
+end