tasker-engine 1.0.0

data/lib/tasker/concerns/idempotent_state_transitions.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Concerns
+    # IdempotentStateTransitions provides helper methods for safely transitioning
+    # state machine objects without throwing errors on same-state transitions.
+    #
+    # This concern extracts the common pattern of checking current state before
+    # attempting transitions to handle Statesman's restriction on same-state transitions.
+    module IdempotentStateTransitions
+      extend ActiveSupport::Concern
+
+      # Safely transition a state machine object to a target state
+      #
+      # Checks the current state first and only attempts transition if different.
+      # This prevents Statesman's "Cannot transition from X to X" errors.
+      #
+      # @param state_machine_object [Object] Object with a state_machine method
+      # @param target_state [String] The desired target state
+      # @param metadata [Hash] Optional metadata for the transition
+      # @return [Boolean] True if transition occurred, false if already in target state
+      def safe_transition_to(state_machine_object, target_state, metadata = {})
+        current_state = state_machine_object.state_machine.current_state
+
+        if current_state == target_state
+          Rails.logger.debug do
+            "#{self.class.name}: #{state_machine_object.class.name} #{state_machine_object.id} " \
+              "already in #{target_state}, skipping transition"
+          end
+          return false
+        end
+
+        Rails.logger.debug do
+          "#{self.class.name}: Transitioning #{state_machine_object.class.name} #{state_machine_object.id} " \
+            "from #{current_state} to #{target_state}"
+        end
+
+        state_machine_object.state_machine.transition_to!(target_state, metadata)
+        true
+      rescue Statesman::GuardFailedError => e
+        Rails.logger.debug do
+          "#{self.class.name}: Guard clause prevented transition of #{state_machine_object.class.name} " \
+            "#{state_machine_object.id} from '#{current_state}' to '#{target_state}': #{e.message}"
+        end
+        false
+      rescue Statesman::TransitionFailedError => e
+        Rails.logger.warn do
+          "#{self.class.name}: Invalid transition for #{state_machine_object.class.name} " \
+            "#{state_machine_object.id} from '#{current_state}' to '#{target_state}': #{e.message}"
+        end
+        false
+      rescue StandardError => e
+        Rails.logger.error do
+          "#{self.class.name}: Failed to transition #{state_machine_object.class.name} #{state_machine_object.id} " \
+            "to #{target_state}: #{e.message}"
+        end
+        raise
+      end
+
+      # Safely transition to target state only if current state matches one of the allowed from states
+      #
+      # @param state_machine_object [Object] Object with a state_machine method
+      # @param target_state [String] The desired target state
+      # @param allowed_from_states [Array<String>] States from which transition is allowed
+      # @param metadata [Hash] Optional metadata for the transition
+      # @return [Symbol] :transitioned, :already_target, :invalid_from_state
+      def conditional_transition_to(state_machine_object, target_state, allowed_from_states, metadata = {})
+        current_state = state_machine_object.state_machine.current_state
+
+        # Already in target state - idempotent
+        return :already_target if current_state == target_state
+
+        # Check if current state allows this transition
+        unless allowed_from_states.include?(current_state)
+          allowed_states_list = allowed_from_states.join(', ')
+          Rails.logger.debug do
+            "#{self.class.name}: Cannot transition #{state_machine_object.class.name} #{state_machine_object.id} " \
+              "from #{current_state} to #{target_state}. Allowed from states: #{allowed_states_list}"
+          end
+          return :invalid_from_state
+        end
+
+        # Perform the transition
+        state_machine_object.state_machine.transition_to!(target_state, metadata)
+        Rails.logger.debug do
+          "#{self.class.name}: Successfully transitioned" \
+            "#{state_machine_object.class.name} #{state_machine_object.id} " \
+            "from #{current_state} to #{target_state}"
+        end
+        :transitioned
+      rescue StandardError => e
+        Rails.logger.error do
+          "#{self.class.name}: Failed to transition #{state_machine_object.class.name} #{state_machine_object.id} " \
+            "to #{target_state}: #{e.message}"
+        end
+        raise
+      end
+
+      # Get current state safely, handling cases where state machine might not exist
+      #
+      # @param state_machine_object [Object] Object with a state_machine method
+      # @return [String, nil] Current state or nil if no state machine
+      def safe_current_state(state_machine_object)
+        return nil unless state_machine_object.respond_to?(:state_machine)
+
+        state_machine_object.state_machine.current_state
+      rescue StandardError => e
+        Rails.logger.warn do
+          "#{self.class.name}: Could not get current state for #{state_machine_object.class.name} " \
+            "#{state_machine_object.id}: #{e.message}"
+        end
+        nil
+      end
+
+      # Check if an object is in any of the specified states
+      #
+      # @param state_machine_object [Object] Object with a state_machine method
+      # @param states [Array<String>] States to check against
+      # @return [Boolean] True if current state is in the provided states
+      def in_any_state?(state_machine_object, states)
+        current_state = safe_current_state(state_machine_object)
+        return false if current_state.nil?
+
+        states.include?(current_state)
+      end
+    end
+  end
+end

data/lib/tasker/concerns/state_machine_base.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require_relative 'event_publisher'
+
+module Tasker
+  module Concerns
+    # StateMachineBase provides shared functionality for all Tasker state machines
+    #
+    # This concern consolidates common patterns used by TaskStateMachine and StepStateMachine:
+    # - Idempotent transition handling
+    # - Event publishing through unified publisher
+    # - Consistent transition logging
+    # - Helper methods for state checking
+    #
+    # It replaces the legacy LifecycleEvents system with direct integration to Events::Publisher
+    module StateMachineBase
+      extend ActiveSupport::Concern
+      include EventPublisher
+
+      included do
+        # Common before_transition callback for idempotent handling
+        before_transition do |object, transition|
+          # Handle idempotent transitions using unified helper
+          if StateMachineBase.idempotent_transition?(object, transition.to_state)
+            raise Statesman::GuardFailedError, "Already in target state #{transition.to_state}"
+          end
+
+          # Log the transition for debugging
+          effective_current_state = StateMachineBase.effective_current_state(object)
+          object_id = StateMachineBase.object_id(object)
+          Rails.logger.debug do
+            "#{object.class.name} #{object_id} transitioning from #{effective_current_state} to #{transition.to_state}"
+          end
+        end
+
+        # Common after_transition callback for event publishing
+        after_transition do |object, transition|
+          # Determine the appropriate event name based on the transition
+          event_name = determine_transition_event_name(transition.from_state, transition.to_state)
+
+          # Only fire the event if we have a valid event name
+          if event_name
+            # Build context appropriate for the object type
+            context = StateMachineBase.build_event_context(object, transition)
+
+            # Fire the event through unified publisher
+            StateMachineBase.publish_event(event_name, context)
+          end
+        end
+      end
+
+      module ClassMethods
+        # Check if a transition is idempotent (current state == target state)
+        #
+        # @param object [Object] The object with state_machine
+        # @param target_state [String] The target state
+        # @return [Boolean] True if this is an idempotent transition
+        def idempotent_transition?(object, target_state)
+          effective_state = effective_current_state(object)
+          is_idempotent = effective_state == target_state
+
+          if is_idempotent
+            Rails.logger.debug do
+              "#{object.class.name}: Detected idempotent transition to #{target_state} for #{object_id(object)}"
+            end
+          end
+
+          is_idempotent
+        end
+
+        # Get the effective current state, handling blank/empty states
+        #
+        # @param object [Object] The object to check
+        # @return [String] The effective current state (blank states become default)
+        def effective_current_state(object)
+          current_state = object.state_machine.current_state
+
+          current_state.presence || case object.class.name
+                                    when /Task/
+                                      Constants::TaskStatuses::PENDING
+                                    when /WorkflowStep/
+                                      Constants::WorkflowStepStatuses::PENDING
+                                    else
+                                      current_state
+                                    end
+        end
+
+        # Get a consistent object identifier for logging
+        #
+        # @param object [Object] The object
+        # @return [String] The object identifier
+        def object_id(object)
+          case object.class.name
+          when /Task/
+            object.task_id
+          when /WorkflowStep/
+            object.workflow_step_id
+          else
+            object.id
+          end
+        end
+
+        # Build event context appropriate for the object type
+        #
+        # @param object [Object] The object being transitioned
+        # @param transition [Statesman::Transition] The transition
+        # @return [Hash] Event context
+        def build_event_context(object, transition)
+          base_context = {
+            from_state: transition.from_state,
+            to_state: transition.to_state,
+            transitioned_at: Time.zone.now
+          }
+
+          case object.class.name
+          when /Task/
+            base_context.merge(
+              task_id: object.task_id,
+              task_name: object.name,
+              task_context: object.respond_to?(:context) ? object.context : nil
+            )
+          when /WorkflowStep/
+            base_context.merge(
+              task_id: object.task_id,
+              step_id: object.workflow_step_id,
+              step_name: object.name
+            )
+          else
+            base_context.merge(
+              object_id: object.id,
+              object_type: object.class.name
+            )
+          end
+        end
+
+        # Publish event through unified Events::Publisher system
+        # Uses the EventPublisher concern for consistent implementation
+        #
+        # @param event_name [String] The event name
+        # @param context [Hash] The event context
+        # @return [void]
+        # Note: This method is provided by the EventPublisher concern
+
+        # Log an invalid from-state transition
+        #
+        # @param object [Object] The object
+        # @param current_state [String] The current state
+        # @param target_state [String] The target state
+        # @param reason [String] The reason for the restriction
+        def log_invalid_from_state(object, current_state, target_state, reason)
+          Rails.logger.debug do
+            "#{name}: Cannot transition to #{target_state} from '#{current_state}' " \
+              "(#{object.class.name} #{object_id(object)}). #{reason}."
+          end
+        end
+
+        # Log when dependencies/conditions are not met
+        #
+        # @param object [Object] The object
+        # @param target_state [String] The target state
+        # @param reason [String] The specific reason
+        def log_condition_not_met(object, target_state, reason)
+          Rails.logger.debug do
+            "#{name}: Cannot transition #{object.class.name} #{object_id(object)} to #{target_state} - #{reason}"
+          end
+        end
+
+        # Log the result of a transition check
+        #
+        # @param object [Object] The object
+        # @param target_state [String] The target state
+        # @param result [Boolean] Whether the transition is allowed
+        # @param reason [String] The reason for the result
+        def log_transition_result(object, target_state, result, reason)
+          object_identifier = "#{object.class.name} #{object_id(object)}"
+          if result
+            Rails.logger.debug do
+              "#{name}: Allowing transition to #{target_state} for #{object_identifier} (#{reason})"
+            end
+          else
+            Rails.logger.debug do
+              "#{name}: Blocking transition to #{target_state} for #{object_identifier} (#{reason} failed)"
+            end
+          end
+        end
+      end
+
+      # Access to class methods from instance methods
+      module StateMachineBase
+        module ClassMethods
+          delegate :idempotent_transition?, to: :StateMachineBase
+
+          delegate :effective_current_state, to: :StateMachineBase
+
+          delegate :object_id, to: :StateMachineBase
+
+          # Use EventPublisher for consistent event publishing
+          def publish_event(event_name, context = {})
+            # Create a temporary object to access the concern method
+            publisher = Object.new.extend(EventPublisher)
+            publisher.send(:publish_event, event_name, context)
+          end
+        end
+      end
+
+      private
+
+      # Instance method is provided by EventPublisher concern
+      # No need to override here
+
+      # Instance method wrapper for determining transition event name
+      # (To be implemented by including classes)
+      def determine_transition_event_name(from_state, to_state)
+        self.class.determine_transition_event_name(from_state, to_state)
+      end
+    end
+  end
+end