rigid_workflow 1.0.0

data/lib/rigid_workflow/id_generator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "uuid7"
+
+module RigidWorkflow
+  # Generates and validates UUIDv7 identifiers.
+  # UUIDv7 provides time-ordered IDs for efficient database indexing.
+  class IdGenerator
+    def self.uuid_v7
+      UUID7.generate
+    end
+
+    def self.valid_uuid?(value)
+      return false if value.nil? || value.to_s.empty?
+
+      value.to_s.match?(
+        /\A[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i
+      )
+    end
+  end
+end

data/lib/rigid_workflow/orchestrator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module RigidWorkflow
+  # Orchestrates workflow execution.
+  # Manages workflow starting, scheduling, and state advancement.
+  class Orchestrator
+    class << self
+      def start(workflow_class, params = {})
+        RigidWorkflow.instrument(
+          "workflow.start",
+          workflow_class: workflow_class.name
+        ) do
+          run =
+            RigidWorkflow::Run.create!(
+              workflow_class: workflow_class.name,
+              version: workflow_class.workflow_version,
+              params: params
+            )
+          schedule(run)
+          run
+        end
+      end
+
+      def schedule(run, options = {})
+        RigidWorkflow::WorkflowJob.set(
+          wait: options[:wait],
+          wait_until: options[:wait_until],
+          priority: options[:priority]
+        ).perform_later(run.id)
+      end
+
+      def advance!(run)
+        run.increment(:iterations)
+        return if run.finished?
+
+        raise "Cannot advance a compensating workflow" if run.compensating?
+
+        run.start! if run.pending?
+
+        # brakeman:ignore UnsafeReflection
+        # This is intentional - workflow_class is a validated string from the workflow definition
+        workflow_class = run.workflow_class.constantize
+        unless workflow_class && workflow_class < RigidWorkflow::Workflow
+          raise ArgumentError, "#{run.workflow_class} is not a valid Workflow"
+        end
+
+        workflow = workflow_class.new(run)
+
+        catch(:suspend) do
+          if run.running?
+            workflow.run
+            run.finish!
+          end
+        end
+
+        run.save! if run.changed?
+      rescue ActivityFailedError => error
+        # A step failed after exhausting all retries
+        if run.running? && !run.compensating?
+          failed_step = run.steps.where(status: :failed).last
+          if failed_step && step_exhausted_retries?(failed_step)
+            # Attempt compensation - if it raises, let it propagate
+            run.compensate!
+            # If compensate! succeeds, don't re-raise ActivityFailedError
+            return
+          end
+        end
+
+        # If we get here, no compensation was performed
+        run.fail! unless run.compensating?
+        raise error
+      rescue => error
+        # Handle non-ActivityFailedError exceptions
+        run.fail! unless run.compensating?
+        raise error
+      end
+
+      def step_exhausted_retries?(step)
+        step.attempts.count >= step.max_attempts
+      end
+    end
+  end
+end

data/lib/rigid_workflow/step_result.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RigidWorkflow
+  # Represents the result of a workflow step execution.
+  class StepResult
+    # @api private
+    def initialize(status, output = {})
+      @status = status.to_s
+      @output = (output || {}).with_indifferent_access
+    end
+
+    # Returns true if the step completed successfully.
+    # @return [Boolean]
+    def success?
+      @status == "completed"
+    end
+
+    # Returns true if the step failed all retry attempts.
+    # @return [Boolean]
+    def failure?
+      @status == "failed"
+    end
+
+    delegate :[], to: :@output
+
+    # Returns the output as a hash.
+    # @return [Hash]
+    def to_h
+      @output.to_h
+    end
+  end
+
+  # Exception raised when an activity fails after all retry attempts.
+  class ActivityFailedError < StandardError
+    def initialize(step)
+      @step = step
+      super(
+        "Activity #{step.activity_class} (step: #{step.step_name}) failed after #{step.attempt_count} attempts"
+      )
+    end
+  end
+
+  # Exception raised when parallel or race blocks are nested.
+  class NestedBlockError < StandardError
+  end
+
+  # Exception raised when an activity has a duplicate name.
+  class DuplicateNameError < StandardError
+  end
+end

data/lib/rigid_workflow/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RigidWorkflow
+  VERSION = "1.0.0"
+end

data/lib/rigid_workflow/workflow.rb

@@ -0,0 +1,59 @@
+require "forwardable"
+
+module RigidWorkflow
+  # Base class for all workflow definitions.
+  # Subclasses must implement the #run method.
+  class Workflow
+    extend Forwardable
+
+    class_attribute :workflow_version, default: 1
+
+    # Sets the version for this workflow class.
+    # @param value [Integer] The version number
+    # @return [Integer]
+    def self.version(value)
+      self.workflow_version = value
+    end
+
+    # Starts a workflow run for this class
+    # @param params [Hash] Initial parameters
+    # @return [RigidWorkflow::Run] The created workflow run
+    def self.start!(params = {})
+      RigidWorkflow::Orchestrator.start(self, params)
+    end
+
+    # @api private
+    def initialize(workflow_run)
+      @workflow_run = workflow_run
+      @run_version = workflow_run.version
+      @runner = WorkflowRunner.new(workflow_run)
+      @params = workflow_run.params.with_indifferent_access
+    end
+
+    # The main workflow logic. Must be implemented by subclasses.
+    def run
+      raise NotImplementedError, "Subclass must implement #run"
+    end
+
+    # Logs a message that is persisted and associated with the workflow run.
+    # @param message [String] The message to log
+    def log(message, severity: Logger::INFO)
+      return if !RigidWorkflow.config.logging? && Rails.env.test?
+
+      @log_index ||= 0
+      @log_index += 1
+
+      memo "log_#{@log_index}" do
+        puts message unless Rails.env.test?
+        log_to_rails(severity, message)
+      end
+    end
+
+    def log_to_rails(severity, message)
+      Rails.logger.log(severity, "[#{@workflow_run.id.to_s[0..12]}] #{message}")
+    end
+
+    # Delegate these methods to the @runner object
+    def_delegators :@runner, :step, :memo, :loop, :wait, :parallel, :race
+  end
+end

data/lib/rigid_workflow/workflow_runner.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+module RigidWorkflow
+  # Executes workflow definitions.
+  # Handles step execution, signal waiting, loops, parallel and race blocks.
+  class WorkflowRunner
+    def initialize(workflow_run)
+      @workflow_run = workflow_run
+      @params = workflow_run.params.with_indifferent_access
+      @activity_cache = workflow_run.steps.reload.index_by(&:step_name)
+      @signal_cache = workflow_run.signals.reload.index_by(&:name)
+      @activity_names_seen = Set.new
+      @parallel_mode = false
+      @race_mode = false
+      @loop_stack = []
+      @loop_index_stack = []
+      @suspensions = []
+      @parallel_results = nil
+      @race_winner = nil
+    end
+
+    def run(&block)
+      instance_eval(&block)
+    end
+
+    def step(name, activity_class, **options)
+      full_name = build_step_name(name)
+      if @activity_names_seen.include?(full_name)
+        raise DuplicateNameError.new(
+                "Activity '#{full_name}' cannot be called more than once"
+              )
+      end
+
+      @activity_names_seen << full_name
+      step = @activity_cache[full_name]
+
+      if step&.completed?
+        result = StepResult.new(step.status, step.current_attempt&.output)
+        handle_completed(name, result)
+        return result
+      end
+
+      if step&.failed?
+        unless step.attempt_count < step.max_attempts
+          raise ActivityFailedError.new(step)
+        end
+
+        schedule_retry(step)
+        handle_suspension
+      end
+
+      if step&.pending?
+        schedule_step(step.id, options)
+        handle_suspension
+      end
+
+      force_async =
+        activity_class.respond_to?(:force_async?) && activity_class.force_async?
+      should_async =
+        force_async || options[:async] || options[:wait] || options[:wait_until]
+
+      if !@parallel_mode && !@race_mode && !should_async && step.nil?
+        step = create_workflow_step(full_name, activity_class, options)
+
+        step.start!
+        activity = activity_class.new(step)
+        input_hash = step.input.deep_symbolize_keys
+
+        begin
+          result = activity.perform(**input_hash)
+          step.complete!(result)
+        rescue StandardError => error
+          handle_activity_error(step, error)
+        end
+
+        @activity_cache[full_name] = step
+        handle_completed(
+          name,
+          StepResult.new(step.status, step.current_attempt&.output)
+        )
+        return StepResult.new(step.status, step.current_attempt&.output)
+      end
+
+      if step.nil?
+        step = create_workflow_step(full_name, activity_class, options)
+        schedule_step(step.id, options)
+
+        if should_async && !@parallel_mode && !@race_mode
+          @suspensions << :suspend
+          throw :suspend
+        end
+      end
+
+      handle_suspension
+    end
+
+    def memo(name)
+      full_name = "memo_#{name}"
+      @memory ||= (@workflow_run.memory || {}).to_h.with_indifferent_access
+
+      return @memory[full_name] if @memory.key?(full_name)
+
+      value = yield
+      @memory[full_name] = value
+      @workflow_run.memory = @memory
+      value
+    end
+
+    def loop(name, collection, &block)
+      @memory ||= (@workflow_run.memory || {}).to_h.with_indifferent_access
+
+      full_name = name.to_s
+      full_name = "#{@loop_stack.last}_" + full_name if @loop_stack.any?
+
+      memory_key = "loop_#{full_name}"
+      index = @memory[memory_key] || 0
+      return if index >= collection.size
+
+      @loop_stack.push(name)
+      @loop_index_stack.push(index)
+
+      @workflow_run.memory = @memory
+      collection.each_with_index do |item, current_index|
+        next if current_index < index
+
+        @memory[memory_key] = current_index
+        @loop_index_stack[-1] = current_index
+        yield(item, current_index)
+      end
+
+      @memory.delete(memory_key)
+    ensure
+      @loop_stack.pop
+      @loop_index_stack.pop
+    end
+
+    def wait(name, timeout: nil, **options)
+      full_name = name.to_s
+      full_name =
+        "#{@loop_stack.last}_#{@loop_index_stack.last}_" +
+          full_name if @loop_stack.any?
+
+      signal = @signal_cache[full_name]
+
+      if signal&.received?
+        @signal_cache[full_name] = signal
+        result = signal.payload
+        handle_completed(name, result)
+        return result
+      end
+
+      if signal&.expired?
+        signal.update!(received_at: Time.current) unless signal.received?
+        @signal_cache[full_name] = signal
+        handle_completed(name, nil)
+        return nil
+      end
+
+      if signal.nil?
+        is_timer =
+          timeout.is_a?(ActiveSupport::Duration) || timeout.is_a?(Numeric)
+
+        if is_timer
+          signal =
+            @workflow_run.signals.create!(
+              name: full_name,
+              expires_at: Time.current + timeout,
+              payload: options[:payload] || {}
+            )
+          schedule_timer(signal.id, wait: timeout)
+        else
+          signal = @workflow_run.signals.create!(name: full_name)
+        end
+      end
+
+      @signal_cache[full_name] = signal
+
+      return handle_suspension if @race_mode
+
+      throw :suspend unless @parallel_mode
+      handle_suspension
+      nil
+    end
+
+    def parallel(name)
+      if @parallel_mode || @race_mode
+        raise NestedBlockError,
+              "Nesting parallel or race blocks is not supported"
+      end
+
+      @parallel_results = {}
+      old_mode = @parallel_mode
+      @parallel_mode = true
+      yield
+      @parallel_mode = old_mode
+
+      if @suspensions.any?
+        throw :suspend
+      else
+        @parallel_results.dup.tap { @parallel_results = nil }
+      end
+    ensure
+      @parallel_mode = old_mode
+    end
+
+    def race(name)
+      if @parallel_mode || @race_mode
+        raise NestedBlockError,
+              "Nesting parallel or race blocks is not supported"
+      end
+
+      @race_winner = nil
+      old_mode = @race_mode
+      @race_mode = true
+      yield
+      @race_mode = old_mode
+
+      if @race_winner
+        @race_winner.dup.tap { @race_winner = nil }
+      elsif @suspensions.any?
+        throw :suspend
+      end
+    ensure
+      @race_mode = old_mode
+    end
+
+    private
+
+    def create_workflow_step(full_name, activity_class, options)
+      @workflow_run.steps.create!(
+        step_name: full_name,
+        activity_class: activity_class.to_s,
+        status: :enqueued,
+        input: options[:input] || @params,
+        max_attempts:
+          options[:max_attempts] || RigidWorkflow.config.max_attempts
+      )
+    end
+
+    def handle_activity_error(step, error)
+      error_details = {
+        error: error.class.to_s,
+        message: error.message,
+        backtrace: error.backtrace&.first(5)
+      }
+
+      # Mark current attempt as failed (Bug 1 fix)
+      step.current_attempt&.update!(
+        status: :failed,
+        failed_at: Time.current,
+        error_details: error_details
+      )
+
+      if step.attempt_count >= step.max_attempts
+        step.update!(status: :failed)
+        raise ActivityFailedError.new(step)
+      else
+        schedule_retry(step, error_details)
+
+        @suspensions << :suspend
+        throw :suspend
+      end
+    end
+
+    def build_step_name(name)
+      full_name = name.to_s
+      if @loop_stack.any?
+        @loop_stack.reverse_each.with_index do |n, i|
+          full_name = "#{n}_#{@loop_index_stack[i]}_" + full_name
+        end
+      end
+      full_name
+    end
+
+    def schedule_step(step_id, options = {})
+      RigidWorkflow::ActivityJob.set(
+        wait: options[:wait],
+        wait_until: options[:wait_until],
+        priority: options[:priority] || @workflow_run.created_at.to_i
+      ).perform_later(step_id)
+    end
+
+    def schedule_timer(signal_id, options = {})
+      RigidWorkflow::TimerJob.set(
+        wait: options[:wait],
+        wait_until: options[:wait_until],
+        priority: options[:priority]
+      ).perform_later(signal_id)
+    end
+
+    def handle_completed(name, result)
+      if @parallel_mode
+        @parallel_results[name] = result
+      elsif @race_mode && @race_winner.nil?
+        @race_winner = { name: name, result: result }
+      end
+    end
+
+    def handle_suspension
+      @suspensions << :suspend
+      throw :suspend unless @parallel_mode || @race_mode
+    end
+
+    def schedule_retry(step, error_details = nil, retry_options = {})
+      retry_delay =
+        retry_options[:retry_delay] || RigidWorkflow.config.retry_delay
+      max_exponent = 10
+      exponent = [step.attempt_count, max_exponent].min
+      base_delay = retry_delay * (2**exponent)
+
+      # ±20% jitter
+      jitter = base_delay * 0.2 * (rand * 2 - 1)
+      delay = [base_delay + jitter, 1.second].max
+
+      step.attempts.create!(
+        attempt_number: step.attempt_count + 1,
+        status: :pending,
+        input: step.input
+      )
+
+      step.update!(status: :enqueued, scheduled_at: Time.current + delay)
+
+      RigidWorkflow.instrument(
+        "step.retry",
+        run_id: step.rigid_workflow_run_id,
+        step_id: step.id,
+        attempt: step.attempt_count,
+        delay: delay
+      )
+
+      schedule_step(step.id, wait: delay)
+    end
+  end
+end

data/lib/rigid_workflow.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "active_job"
+require "active_record"
+require "action_view"
+require "action_controller"
+require "rails"
+
+require "rigid_workflow/engine"
+
+# RigidWorkflow provides a durable workflow orchestration engine for Rails.
+# It allows you to define complex business processes as code that are
+# persistent, observable, and resilient to failures.
+module RigidWorkflow
+  #
+  # Configuration for RigidWorkflow
+  #
+  Configuration =
+    Struct.new(:admin_controller, :max_attempts, :retry_delay, :logging) do
+      def logging?
+        logging || false
+      end
+    end
+
+  # Returns the current configuration
+  # @return [Configuration]
+  def self.config
+    @config ||= Configuration.new(nil, 3, 15.seconds)
+  end
+
+  # @yield [config] The current configuration
+  def self.configure
+    yield config
+  end
+
+  #
+  # Base exception class for RigidWorkflow errors.
+  #
+  class Error < StandardError
+  end
+
+  #
+  # Subscribe to RigidWorkflow events
+  #
+  # @param event_name [String] The name of the event
+  # @yield [payload] The event payload
+  def self.on(event_name, &block)
+    ActiveSupport::Notifications.subscribe(
+      "#{event_name}.rigid_workflow"
+    ) do |*args|
+      block.call(ActiveSupport::Notifications::Event.new(*args).payload)
+    end
+  end
+
+  # Instrument a RigidWorkflow event
+  # @param event_name [String] The name of the event
+  # @param payload [Hash] The event payload
+  def self.instrument(event_name, payload = {}, &block)
+    ActiveSupport::Notifications.instrument(
+      "#{event_name}.rigid_workflow",
+      payload,
+      &block
+    )
+  end
+end