stepped 0.1.0 → 1.0.0

data/app/models/stepped/action.rb

@@ -0,0 +1,293 @@
+class Stepped::Action < ActiveRecord::Base
+  self.filter_attributes = []
+
+  STATUSES = %w[
+    pending
+    performing
+    succeeded
+    superseded
+    cancelled
+    failed
+    timed_out
+    deadlocked
+  ].freeze
+
+  enum :status, STATUSES.index_by(&:itself)
+
+  serialize :arguments, coder: Stepped::Arguments
+
+  belongs_to :actor, polymorphic: true
+  belongs_to :performance, optional: true
+
+  has_many :steps, -> { order(id: :asc) }, dependent: :destroy
+
+  has_and_belongs_to_many :parent_steps, class_name: "Stepped::Step",
+    join_table: :stepped_actions_steps, foreign_key: :step_id, association_foreign_key: :action_id,
+    inverse_of: :actions
+
+  scope :roots, -> { where(root: true) }
+  scope :outbounds, -> { where(outbound: true) }
+  scope :incomplete, -> { where(status: %i[ pending performing ]) }
+
+  KEYS_JOINER = "/"
+
+  def obtain_lock_and_perform
+    apply_definition
+    run_before_chain
+
+    if completed?
+      propagate_completion_to_parent_steps
+      return self
+    end
+
+    set_checksum
+
+    Stepped::Achievement.raise_if_exists_for?(self)
+    Stepped::Performance.obtain_for(self)
+  rescue Stepped::Achievement::ExistsError
+    self.status = :succeeded
+    propagate_completion_to_parent_steps
+    self
+  end
+
+  def update_performance(performance)
+    self.performance = performance
+    perform if pending? && (performance.action == self)
+    save!
+  end
+
+  def perform
+    update! status: :performing, started_at: Time.zone.now
+
+    Stepped::Achievement.erase_of self
+
+    ActiveRecord.after_all_transactions_commit do
+      perform_current_step
+      Stepped::TimeoutJob.set(wait: timeout).perform_later(self) if timeout?
+    end
+  end
+
+  def definition
+    @definition = Stepped::Registry.find_or_add actor.class, name
+  end
+
+  def cancel
+    self.status = :cancelled
+  end
+
+  def complete
+    self.status = :succeeded
+  end
+
+  def supersede_with(action)
+    update! completed_at: Time.zone.now, status: :superseded
+    copy_parent_steps_to action
+  end
+
+  def achieves?(action)
+    checksum_key == action.checksum_key && checksum == action.checksum
+  end
+
+  def copy_parent_steps_to(action)
+    raise ArgumentError, "Can't copy_parent_steps_to self" if action == self
+
+    parent_steps.each do |step|
+      transaction(requires_new: true) do
+        action.parent_steps << step
+      end
+    rescue ActiveRecord::RecordNotUnique
+      action.reload
+    end
+  end
+
+  def perform_current_step
+    steps.create!(
+      definition_index: current_step_index,
+      started_at: Time.zone.now,
+      status: :performing
+    ).perform
+  end
+
+  def compute_concurrency_key
+    run_definition_block :concurrency_key_block
+  end
+
+  def compute_checksum_key
+    run_definition_block :checksum_key_block
+  end
+
+  def outbound_complete_key
+    outbound? ? tenancy_key : nil
+  end
+
+  def accomplished(step)
+    if step.failed?
+      complete! :failed
+    elsif more_steps_to_do?
+      increment :current_step_index
+      save!
+      perform_current_step
+    elsif !outbound?
+      complete!
+    end
+  end
+
+  def safe_actor
+    actor
+  rescue ActiveRecord::SubclassNotFound
+  end
+
+  def actor_becomes_base
+    safe_actor&.becomes actor_type.constantize
+  end
+
+  def short_checksum
+    checksum.to_s[0..7]
+  end
+
+  def timeout?
+    timeout_seconds.present?
+  end
+
+  def compute_timeout
+    if definition.timeout.is_a?(Symbol)
+      actor.send(definition.timeout)
+    else
+      definition.timeout
+    end
+  end
+
+  def cancellable?
+    pending? || performing?
+  end
+
+  def complete!(status = :succeeded)
+    Stepped::Performance.complete_action self, status
+  end
+
+  def finalize_complete(status)
+    self.status = status
+    execute_after_complete_callbacks
+    update!(completed_at: Time.zone.now, performance: nil)
+    Stepped::Achievement.grand_to(self) if succeeded_including_callbacks? && checksum.present?
+
+    propagate_completion_to_parent_steps
+  end
+
+  def deadlock!
+    e = Deadlock.new "#{name} on #{actor.class.name}/#{actor.id}"
+    handled = Stepped.handled_exception_classes.any? { e.class <= _1 }
+    raise e unless handled
+
+    Rails.error.report(e, handled:)
+    self.status = :deadlocked
+    propagate_completion_to_parent_steps
+  end
+
+  def descendant_of?(action)
+    parent_steps.any? do |step|
+      return true if step.action_id == action.id
+      step.action.descendant_of?(action)
+    end
+  end
+
+  def completed?
+    cancelled? || succeeded? || superseded? || failed? || timed_out? || deadlocked?
+  end
+
+  def propagated_touch
+    touch
+    parent_steps.each { _1.action.propagated_touch }
+  end
+
+  def apply_definition
+    return if definition.nil?
+    self.outbound = definition.outbound
+    self.concurrency_key = compute_concurrency_key
+    self.checksum_key = compute_checksum_key
+    self.job = definition.job
+    self.timeout_seconds = compute_timeout
+  end
+
+  def timeout
+    timeout_seconds.seconds
+  end
+
+  def propagate_completion_to_parent_steps
+    ActiveRecord.after_all_transactions_commit do
+      parent_steps.each do |step|
+        step.conclude_job(succeeded_including_callbacks?)
+      end
+    end
+  end
+
+  def succeeded_including_callbacks?
+    succeeded? && after_callbacks_failed_count.nil?
+  end
+
+  class Deadlock < StandardError; end
+
+  private
+    def tenancy_key
+      actor.stepped_action_tenancy_key name
+    end
+
+    def run_before_chain
+      return if failed?
+
+      if before_block = definition.before_block
+        fail_on_exception do
+          actor.instance_exec self, *arguments, &before_block
+        end
+      end
+    end
+
+    def fail_on_exception(&block)
+      unless Stepped.handle_exception(context: { block: }, &block)
+        self.status = :failed
+      end
+    end
+
+    def run_definition_block(method)
+      if block = definition.public_send(method)
+        result = actor.instance_exec(*arguments, &block)
+
+        return tenancy_key if result.blank?
+
+        result.is_a?(Array) ? result.join(KEYS_JOINER) : result.to_s
+      else
+        tenancy_key
+      end
+    end
+
+    def set_checksum
+      if block = definition.checksum_block
+        value = actor.instance_exec(*arguments, &block)
+        self.checksum = Stepped.checksum value
+      end
+    end
+
+    def execute_after_complete_callbacks
+      return true if definition.nil?
+
+      definition.after_callbacks.each do |callback|
+        next true unless callback.fetch(:name).in?([ status.to_sym, :all ])
+
+        context = { action: to_global_id, callback: callback.inspect }
+
+        succeeded = Stepped.handle_exception(context:) do
+          actor.instance_exec self, *arguments, &callback.fetch(:block)
+        end
+
+        if succeeded
+          increment :after_callbacks_succeeded_count
+        else
+          increment :after_callbacks_failed_count
+        end
+      end
+    end
+
+    def more_steps_to_do?
+      definition.steps.size > (current_step_index + 1)
+    end
+end

data/app/models/stepped/arguments.rb

@@ -0,0 +1,15 @@
+require "active_job/arguments"
+
+class Stepped::Arguments
+  class << self
+    def load(serialized_arguments)
+      return if serialized_arguments.nil?
+
+      ActiveJob::Arguments.deserialize serialized_arguments
+    end
+
+    def dump(arguments)
+      ActiveJob::Arguments.serialize arguments
+    end
+  end
+end

data/app/models/stepped/definition.rb

@@ -0,0 +1,109 @@
+class Stepped::Definition
+  attr_reader :actor_class, :action_name, :block,
+              :outbound, :timeout, :job,
+              :concurrency_key_block, :before_block,
+              :checksum_block, :checksum_key_block,
+              :steps, :after_callbacks
+
+  AFTER_CALLBACKS = %i[
+    cancelled
+    timed_out
+    succeeded
+    failed
+  ]
+
+  def initialize(actor_class:, action_name:, outbound: false, timeout: nil, job: nil, block: nil)
+    @actor_class = actor_class
+    @action_name = action_name.to_s
+    @outbound = outbound || job.present?
+    @timeout = timeout
+    @job = job
+    @after_callbacks = []
+    @steps = []
+    @block = block
+
+    instance_exec &block if block
+
+    if @steps.empty?
+      @steps.append generate_step
+    end
+  end
+
+  def duplicate_as(actor_class)
+    self.class.new(actor_class:, action_name:, outbound:, timeout:, job:, block:)
+  end
+
+  def before(&block)
+    @before_block = block
+  end
+
+  def concurrency_key(method = nil, &block)
+    @concurrency_key_block = procify method, &block
+  end
+
+  def checksum(method = nil, &block)
+    @checksum_block = procify method, &block
+  end
+
+  def checksum_key(method = nil, &block)
+    @checksum_key_block = procify method, &block
+  end
+
+  def step(&block)
+    @steps.append block
+  end
+
+  def prepend_step(&block)
+    @steps.prepend block
+  end
+
+  AFTER_CALLBACKS.each do |name|
+    define_method name do |&block|
+      after_callbacks << { name:, block: }
+    end
+  end
+
+  def after(*statuses, &block)
+    statuses = [ :all ] if statuses.empty?
+    statuses.each do |status|
+      status = status.to_sym
+      unless status == :all || AFTER_CALLBACKS.include?(status)
+        raise ArgumentError, "'#{status}' must be one of #{AFTER_CALLBACKS}"
+      end
+      after_callbacks << { name: status, block: }
+    end
+  end
+
+  private
+    def procify(method, &block)
+      if method.is_a?(Symbol)
+        proc do
+          send method
+        end
+      elsif block_given?
+        block
+      else
+        raise ArgumentError, "Symbol referring to a method to call or a block required"
+      end
+    end
+
+    def method_call_step_block(method_name)
+      proc do |step|
+        send method_name, *step.action.arguments
+      end
+    end
+
+    def job_step_block(job)
+      proc do |step|
+        job.perform_later step.action
+      end
+    end
+
+    def generate_step
+      if job
+        job_step_block job
+      else
+        method_call_step_block action_name
+      end
+    end
+end

data/app/models/stepped/performance.rb

@@ -0,0 +1,76 @@
+class Stepped::Performance < ActiveRecord::Base
+  self.filter_attributes = []
+
+  belongs_to :action
+  has_many :actions, -> { order(:id) }, dependent: :nullify
+
+  scope :outbounds, -> { joins(:action).where(action: { outbound: true }) }
+
+  before_save -> { self.outbound_complete_key = action.outbound_complete_key }
+
+  class << self
+    def obtain_for(action)
+      transaction(requires_new: true) do
+        lock.
+          create_with(action:).
+          find_or_create_by!(concurrency_key: action.concurrency_key).
+          share_with(action)
+      end
+    end
+
+    def outbound_complete(actor, name, status = :succeeded)
+      outbound_complete_key = actor.stepped_action_tenancy_key name
+
+      transaction(requires_new: true) do
+        lock.find_by(outbound_complete_key:)&.forward(status:)
+      end
+    end
+
+    def complete_action(action, status)
+      transaction(requires_new: true) do
+        lock.find_by(concurrency_key: action.concurrency_key)&.forward(action, status:)
+      end
+    end
+  end
+
+  def forward(completing_action = self.action, status: :succeeded)
+    completing_action.finalize_complete status
+
+    return unless completing_action == action
+
+    if next_action = actions.incomplete.first
+      update!(action: next_action)
+      next_action.perform if next_action.pending?
+    else
+      destroy!
+    end
+  end
+
+  def share_with(candidate)
+    # Secondary check of this kind here within a performance lock
+    # prevents race conditions between the first check and obtaining the lock,
+    # while the first check in Action#obtain_lock_and_perform speeds things up.
+    Stepped::Achievement.raise_if_exists_for?(candidate)
+
+    if candidate.descendant_of?(action)
+      return candidate.tap(&:deadlock!)
+    end
+
+    if candidate.checksum.present?
+      actions.excluding(candidate).each do |action|
+        if action.achieves?(candidate)
+          candidate.copy_parent_steps_to action
+          return action
+        end
+      end
+    end
+
+    other_pending_actions.each { _1.supersede_with(candidate) }
+    candidate.tap { _1.update_performance(self) }
+  end
+
+  private
+    def other_pending_actions
+      actions.pending.excluding(action)
+    end
+end

data/app/models/stepped/registry.rb

@@ -0,0 +1,66 @@
+class Stepped::Registry
+  @job_classes = Concurrent::Array.new
+  @definitions = Concurrent::Hash.new
+
+  class << self
+    attr_reader :job_classes, :definitions
+
+    def key(klass)
+      "#{klass.name}/#{klass.object_id}"
+    end
+
+    def add(actor_class, action_name, outbound: false, timeout: nil, job: nil, &block)
+      if job && @job_classes.exclude?(job)
+        @job_classes.push job
+      end
+
+      add_definition actor_class, action_name, Stepped::Definition.new(
+        actor_class:,
+        action_name:,
+        outbound:,
+        timeout:,
+        job:,
+        block:
+      )
+    end
+
+    def add_definition(actor_class, action_name, definition)
+      class_key = key actor_class
+      @definitions[class_key] ||= Concurrent::Hash.new
+      @definitions[class_key][action_name.to_s] = definition
+    end
+
+    def prepend_step(actor_class, action_name, &step_block)
+      definition = find_or_add actor_class, action_name
+
+      unless definition.actor_class == actor_class
+        definition = add_definition actor_class, action_name, definition.duplicate_as(actor_class)
+      end
+
+      definition.prepend_step(&step_block)
+    end
+
+    def append_after_callback(actor_class, action_name, *statuses, &block)
+      definition = find_or_add actor_class, action_name
+
+      unless definition.actor_class == actor_class
+        definition = add_definition actor_class, action_name, definition.duplicate_as(actor_class)
+      end
+
+      definition.after(*statuses, &block)
+    end
+
+    def find(actor_class, action_name)
+      actor_class.ancestors.each do |ancestor|
+        definition = @definitions.dig key(ancestor), action_name.to_s
+        return definition if definition
+      end
+
+      nil
+    end
+
+    def find_or_add(actor_class, action_name)
+      find(actor_class, action_name) || add(actor_class, action_name)
+    end
+  end
+end

data/app/models/stepped/step.rb

@@ -0,0 +1,98 @@
+class Stepped::Step < ActiveRecord::Base
+  STATUSES = %w[
+    pending
+    performing
+    succeeded
+    failed
+  ].freeze
+
+  enum :status, STATUSES.index_by(&:itself)
+
+  belongs_to :action
+
+  has_and_belongs_to_many :actions, -> { order(id: :asc) }, class_name: "Stepped::Action",
+    join_table: :stepped_actions_steps, foreign_key: :action_id, association_foreign_key: :step_id,
+    inverse_of: :parent_steps
+
+  scope :incomplete, -> { where(status: %i[ pending performing ]) }
+
+  def perform
+    @jobs = []
+    if execute_block
+      ActiveJob.perform_all_later @jobs
+    else
+      self.pending_actions_count = 0
+      self.status = :failed
+    end
+
+    complete! if pending_actions_count.zero?
+  end
+
+  def do(action_name, *args)
+    on action.actor, action_name, *args
+  end
+
+  def on(actors, action_name, *args)
+    Array(actors).compact.each do |actor|
+      increment :pending_actions_count
+      @jobs << Stepped::ActionJob.new(actor, action_name, *args, parent_step: self)
+    end
+
+    save!
+  end
+
+  def wait(duration)
+    increment! :pending_actions_count
+    @jobs << Stepped::WaitJob.new(self).set(wait: duration)
+  end
+
+  def conclude_job(succeeded = true)
+    with_lock do
+      raise NoPendingActionsError unless pending_actions_count > 0
+
+      decrement :pending_actions_count
+      increment :unsuccessful_actions_count unless succeeded
+
+      if pending_actions_count.zero?
+        assign_attributes(completed_at: Time.zone.now, status: determine_status)
+      end
+
+      save!
+    end
+
+    action.accomplished(self) if pending_actions_count.zero?
+  end
+
+  def display_position
+    definition_index + 1
+  end
+
+  private
+    def complete!(status = determine_status)
+      update!(completed_at: Time.zone.now, status:)
+      action.accomplished self
+    end
+
+    def block
+      action.definition.steps.fetch(definition_index)
+    end
+
+    def execute_block
+      context = {
+        step_id: id,
+        parent_action_id: action_id,
+        step_no: definition_index,
+        block:
+      }
+      Stepped.handle_exception(context:) do
+        action.actor.instance_exec self, *action.arguments, &block
+      end
+    end
+
+    def determine_status
+      return status unless performing?
+      unsuccessful_actions_count > 0 ? :failed : :succeeded
+    end
+
+  class NoPendingActionsError < StandardError; end
+end

data/config/routes.rb

@@ -0,0 +1,2 @@
+Rails.application.routes.draw do
+end