tasker-engine 1.0.0

data/lib/tasker/events/definition_loader.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Tasker
+  module Events
+    # DefinitionLoader handles loading event metadata and state machine mappings from YAML files
+    #
+    # This class provides a clean loader for event metadata (descriptions, schemas, etc.)
+    # and state machine transition mappings. The actual event constants are defined
+    # in constants.rb as the single source of truth.
+    #
+    # Features:
+    # - Event metadata loading for runtime introspection
+    # - State machine transition mappings for declarative configuration
+    # - Support for custom application events and mappings
+    # - Hot reloading in development environments
+    class DefinitionLoader
+      include Singleton
+
+      class << self
+        # Load all event metadata for introspection
+        #
+        # @return [Hash] Event metadata keyed by constant reference
+        def load_event_metadata
+          metadata = {}
+
+          # Load system event metadata first
+          system_metadata = load_system_event_metadata
+          metadata.merge!(system_metadata)
+
+          # Load custom event metadata from applications
+          custom_metadata = load_custom_event_metadata
+          metadata.merge!(custom_metadata)
+
+          metadata
+        end
+
+        # Load state machine mappings from YAML
+        #
+        # @return [Hash] State machine mappings with task and step transitions
+        def load_state_machine_mappings
+          yaml_file = File.join(tasker_config_path, 'system_events.yml')
+
+          if File.exist?(yaml_file)
+            yaml_data = YAML.load_file(yaml_file)
+            yaml_data['state_machine_mappings'] || {}
+          else
+            Rails.logger.warn('Tasker: system_events.yml not found')
+            {}
+          end
+        end
+
+        # Get event metadata for a specific constant
+        #
+        # @param constant_ref [String] The constant reference or actual constant value
+        # @return [Hash, nil] Event metadata or nil if not found
+        def find_event_metadata(constant_ref)
+          metadata = load_event_metadata
+
+          # Try direct lookup first
+          return metadata[constant_ref] if metadata[constant_ref]
+
+          # Try reverse lookup by constant value
+          metadata.find { |_key, data| data['constant_ref'] == constant_ref }&.last
+        end
+
+        # Get all events grouped by category for introspection
+        #
+        # @return [Hash] Events grouped by category (task, step, workflow, etc.)
+        def events_by_category
+          metadata = load_event_metadata
+          grouped = Hash.new { |h, k| h[k] = {} }
+
+          metadata.each do |event_key, event_data|
+            category = extract_category_from_key(event_key)
+            grouped[category][event_key] = event_data
+          end
+
+          grouped
+        end
+
+        private
+
+        # Load system event metadata from Tasker gem
+        #
+        # @return [Hash] System event metadata
+        def load_system_event_metadata
+          system_file = File.join(tasker_config_path, 'system_events.yml')
+
+          if File.exist?(system_file)
+            load_metadata_from_file(system_file)
+          else
+            Rails.logger.warn("Tasker: System events file not found at #{system_file}")
+            {}
+          end
+        end
+
+        # Load custom event metadata from application configuration
+        #
+        # @return [Hash] Custom event metadata
+        def load_custom_event_metadata
+          metadata = {}
+
+          # Load custom events from configured directories if they exist
+          Tasker.configuration.engine.custom_events_directories.each do |directory_path|
+            absolute_path = File.expand_path(directory_path, Rails.root)
+
+            if File.directory?(absolute_path)
+              load_metadata_from_directory(absolute_path, metadata)
+            elsif File.exist?(absolute_path) && absolute_path.end_with?('.yml', '.yaml')
+              file_metadata = load_metadata_from_file(absolute_path)
+              metadata.merge!(file_metadata)
+            end
+          end
+
+          metadata
+        end
+
+        # Load metadata from a single YAML file
+        #
+        # @param file_path [String] Path to the YAML file
+        # @return [Hash] Event metadata from the file
+        def load_metadata_from_file(file_path)
+          Rails.logger.debug { "Tasker: Loading event metadata from #{file_path}" }
+
+          begin
+            yaml_data = YAML.load_file(file_path)
+            return {} if yaml_data.blank?
+
+            # Extract event metadata section
+            event_metadata = yaml_data['event_metadata'] || {}
+            transform_metadata_structure(event_metadata, file_path)
+          rescue StandardError => e
+            Rails.logger.error("Tasker: Failed to load event metadata from #{file_path}: #{e.message}")
+            {}
+          end
+        end
+
+        # Transform nested YAML metadata structure to flat lookup
+        #
+        # @param metadata [Hash] Nested metadata structure from YAML
+        # @param source_file [String] Source file for metadata attribution
+        # @return [Hash] Flattened metadata hash
+        def transform_metadata_structure(metadata, source_file)
+          flattened = {}
+
+          metadata.each do |category, events|
+            events.each do |event_name, event_data|
+              # Create a composite key for easy lookup
+              lookup_key = "#{category}.#{event_name}"
+
+              # Enhance event data with source information
+              enhanced_data = event_data.merge(
+                'category' => category.to_s,
+                'event_name' => event_name.to_s,
+                'source_file' => source_file,
+                'lookup_key' => lookup_key
+              )
+
+              flattened[lookup_key] = enhanced_data
+            end
+          end
+
+          flattened
+        end
+
+        # Extract category from composite event key
+        #
+        # @param event_key [String] The composite event key (e.g., "task.completed")
+        # @return [String] The category portion
+        def extract_category_from_key(event_key)
+          event_key.split('.').first || 'unknown'
+        end
+
+        # Load metadata from a directory
+        #
+        # @param directory_path [String] Absolute path to the directory
+        # @param metadata [Hash] Hash to merge metadata into
+        # @return [void]
+        def load_metadata_from_directory(directory_path, metadata)
+          Rails.logger.debug { "Tasker: Scanning directory for metadata files: #{directory_path}" }
+
+          Dir.glob(File.join(directory_path, '*.{yml,yaml}')).each do |metadata_file|
+            file_metadata = load_metadata_from_file(metadata_file)
+            metadata.merge!(file_metadata)
+          end
+        end
+
+        # Get path to Tasker gem configuration
+        #
+        # @return [String] Path to Tasker config directory
+        def tasker_config_path
+          @tasker_config_path ||= File.join(Tasker::Engine.root, 'config', 'tasker')
+        end
+      end
+    end
+  end
+end

data/lib/tasker/events/event_payload_builder.rb

@@ -0,0 +1,461 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Events
+    # EventPayloadBuilder creates standardized event payloads for consistent telemetry
+    #
+    # This class solves the payload standardization issues identified during factory migration:
+    # - Missing :execution_duration keys in step completion events
+    # - Missing :error_message keys in step failure events
+    # - Missing :attempt_number keys for retry tracking
+    # - Inconsistent payload structure across different event publishers
+    #
+    # Usage:
+    #   payload = EventPayloadBuilder.build_step_payload(step, task, event_type: :completed)
+    #   Tasker::Events::Publisher.instance.publish('step.completed', payload)
+    class EventPayloadBuilder
+      class << self
+        # Build standardized payload for step events
+        #
+        # @param step [WorkflowStep] The step object
+        # @param task [Task] The associated task
+        # @param event_type [Symbol] The type of event (:started, :completed, :failed, :retry, etc.)
+        # @param additional_context [Hash] Additional context to merge in
+        # @return [Hash] Standardized event payload
+        def build_step_payload(step, task = nil, event_type: :completed, additional_context: {})
+          StepPayloadBuilder.build(step, task, event_type, additional_context)
+        end
+
+        # Build standardized payload for task events
+        #
+        # @param task [Task] The task object
+        # @param event_type [Symbol] The type of event (:started, :completed, :failed, etc.)
+        # @param additional_context [Hash] Additional context to merge in
+        # @return [Hash] Standardized event payload
+        def build_task_payload(task, event_type: :completed, additional_context: {})
+          # Get all completion stats in a single optimized query
+          stats = Tasker::WorkflowStep.task_completion_stats(task)
+
+          base_payload = {
+            # Core identifiers
+            task_id: task.task_id,
+            task_name: get_task_name(task),
+
+            # Timing information - only set completed_at for fully completed tasks
+            started_at: task.created_at&.iso8601,
+            completed_at: stats[:all_complete] ? stats[:latest_completion_time]&.iso8601 : nil,
+
+            # Task metadata
+            task_type: task.class.name,
+            event_type: event_type.to_s,
+            timestamp: Time.current.iso8601
+          }
+
+          # Add duration and step statistics to all task events
+          base_payload.merge!(build_task_timing_and_statistics(task, stats))
+
+          # Add event-specific fields
+          case event_type
+          when :completed
+            base_payload.merge!(build_task_completion_specific_payload(task))
+          when :failed
+            base_payload.merge!(build_task_failure_payload(task, additional_context))
+          when :started
+            base_payload.merge!(build_task_start_payload(task))
+          end
+
+          # Merge additional context, allowing overrides
+          base_payload.merge!(additional_context)
+
+          base_payload
+        end
+
+        # Build standardized payload for workflow orchestration events
+        #
+        # @param event_type [Symbol] The orchestration event type
+        # @param context [Hash] The orchestration context
+        # @return [Hash] Standardized orchestration payload
+        def build_orchestration_payload(event_type:, context: {})
+          {
+            # Event metadata
+            event_type: event_type.to_s,
+            orchestration_event: true,
+            timestamp: Time.current.iso8601,
+
+            # Merge provided context
+            **context
+          }
+        end
+
+        private
+
+        # Get task name safely handling the named_task association
+        #
+        # @param task [Task] The task object
+        # @return [String] The task name
+        def get_task_name(task)
+          if task.respond_to?(:named_task) && task.named_task
+            task.named_task.name
+          elsif task.respond_to?(:name)
+            task.name
+          else
+            'unknown_task'
+          end
+        end
+
+        # Build completion-specific payload fields
+        #
+        # @param step [WorkflowStep] The completed step
+        # @return [Hash] Completion payload fields
+        def build_completion_payload(step)
+          payload = {}
+
+          # Calculate execution duration using last_attempted_at and processed_at
+          payload[:execution_duration] = if step.last_attempted_at && step.processed_at
+                                           (step.processed_at - step.last_attempted_at).round(3)
+                                         else
+                                           0.0
+                                         end
+
+          # Include step results if available
+          payload[:step_results] = step.results if step.results.present?
+
+          payload
+        end
+
+        # Build failure-specific payload fields
+        #
+        # @param step [WorkflowStep] The failed step
+        # @param additional_context [Hash] Additional context (may include error details)
+        # @return [Hash] Failure payload fields
+        def build_failure_payload(step, additional_context = {})
+          payload = {}
+
+          # Extract error information using the refactored service
+          error_info = ErrorInfoExtractor.extract(step, additional_context)
+          payload.merge!(error_info)
+
+          # Include step results
+          payload[:step_results] = step.results if step.results.present?
+
+          payload
+        end
+
+        # Build start-specific payload fields
+        #
+        # @param step [WorkflowStep] The starting step
+        # @return [Hash] Start payload fields
+        def build_start_payload(step)
+          {
+            step_inputs: step.inputs,
+            step_dependencies: step.respond_to?(:parents) ? step.parents.map(&:name) : []
+          }
+        end
+
+        # Build retry-specific payload fields
+        #
+        # @param step [WorkflowStep] The step being retried
+        # @return [Hash] Retry payload fields
+        def build_retry_payload(step)
+          {
+            previous_attempts: step.attempts - 1,
+            retry_reason: 'Step execution failed',
+            backoff_strategy: 'exponential' # Could be made configurable
+          }
+        end
+
+        # Build task timing and statistics (shared across all task event types)
+        #
+        # @param task [Task] The task
+        # @param stats [Hash] Pre-calculated task completion statistics from WorkflowStep.task_completion_stats
+        # @return [Hash] Timing and statistics payload fields
+        def build_task_timing_and_statistics(task, stats)
+          payload = {}
+
+          # Distinguish between total duration (all steps complete) and current duration (in progress)
+          if stats[:all_complete] && task.created_at && stats[:latest_completion_time]
+            # True total execution duration - complete workflow
+            payload[:total_execution_duration] = (stats[:latest_completion_time] - task.created_at).round(3)
+            payload[:current_execution_duration] = nil # Not applicable for completed tasks
+          elsif task.created_at
+            # Current execution duration - task still in progress
+            payload[:total_execution_duration] = nil # Not available until completion
+            payload[:current_execution_duration] = (Time.current - task.created_at).round(3)
+          else
+            # No timing information available
+            payload[:total_execution_duration] = nil
+            payload[:current_execution_duration] = nil
+          end
+
+          # Use pre-calculated step statistics (no additional queries needed)
+          payload[:total_steps] = stats[:total_steps]
+          payload[:completed_steps] = stats[:completed_steps]
+          payload[:failed_steps] = stats[:failed_steps]
+          payload[:pending_steps] = stats[:pending_steps]
+
+          payload
+        end
+
+        # Build task completion-specific payload fields (only for completed events)
+        #
+        # @param task [Task] The completed task
+        # @return [Hash] Completion-specific payload fields
+        def build_task_completion_specific_payload(_task)
+          {
+            # Could add completion-specific metadata here if needed
+            # For now, all the important data is in the timing/statistics method
+          }
+        end
+
+        # Build task failure payload fields
+        #
+        # @param task [Task] The failed task
+        # @param additional_context [Hash] Additional context
+        # @return [Hash] Task failure payload fields
+        def build_task_failure_payload(_task, additional_context = {})
+          payload = {}
+
+          # Extract error information
+          if additional_context[:error_steps].present?
+            payload[:error_steps] = additional_context[:error_steps]
+            payload[:error_step_results] = additional_context[:error_step_results]
+          end
+
+          # Default error message if not provided
+          payload[:error_message] = additional_context[:error_message] ||
+                                    additional_context[:error] ||
+                                    'Task execution failed'
+
+          payload
+        end
+
+        # Build task start payload fields
+        #
+        # @param task [Task] The starting task
+        # @return [Hash] Task start payload fields
+        def build_task_start_payload(task)
+          {
+            task_context: task.context,
+            total_steps: task.workflow_steps.count
+          }
+        end
+
+        # Check if a step is complete (reused from various helpers)
+        #
+        # @param step [WorkflowStep] The step to check
+        # @return [Boolean] True if step is complete
+        def step_complete?(step)
+          [
+            Tasker::Constants::WorkflowStepStatuses::COMPLETE,
+            Tasker::Constants::WorkflowStepStatuses::RESOLVED_MANUALLY
+          ].include?(step.status)
+        end
+
+        # Check if a step is in error state
+        #
+        # @param step [WorkflowStep] The step to check
+        # @return [Boolean] True if step is in error
+        def step_in_error?(step)
+          step.status == Tasker::Constants::WorkflowStepStatuses::ERROR
+        end
+
+        # Service class to build step payloads for different event types
+        # Reduces complexity by organizing payload building logic
+        class StepPayloadBuilder
+          class << self
+            # Build complete step payload for specified event type
+            #
+            # @param step [WorkflowStep] The workflow step
+            # @param task [Task] The task (optional, will be retrieved from step if nil)
+            # @param event_type [Symbol] The event type
+            # @param additional_context [Hash] Additional context to merge
+            # @return [Hash] Complete event payload
+            def build(step, task, event_type, additional_context)
+              task ||= step.task
+
+              base_payload = build_base_payload(step, task, event_type)
+              event_specific_payload = build_event_specific_payload(step, event_type, additional_context)
+
+              # Merge additional context, allowing overrides
+              base_payload.merge(event_specific_payload).merge(additional_context)
+            end
+
+            private
+
+            # Build base payload common to all step events
+            #
+            # @param step [WorkflowStep] The workflow step
+            # @param task [Task] The task
+            # @param event_type [Symbol] The event type
+            # @return [Hash] Base payload
+            def build_base_payload(step, task, event_type)
+              {
+                # Core identifiers (always present)
+                task_id: task.task_id,
+                step_id: step.workflow_step_id,
+                step_name: step.name,
+
+                # Timing information - steps use last_attempted_at and processed_at
+                started_at: step.last_attempted_at&.iso8601,
+                completed_at: step.processed_at&.iso8601,
+
+                # Retry and attempt tracking
+                attempt_number: step.attempts || 1,
+                retry_limit: step.retry_limit,
+
+                # Event metadata
+                event_type: event_type.to_s,
+                timestamp: Time.current.iso8601
+              }
+            end
+
+            # Build event-specific payload fields
+            #
+            # @param step [WorkflowStep] The workflow step
+            # @param event_type [Symbol] The event type
+            # @param additional_context [Hash] Additional context
+            # @return [Hash] Event-specific payload
+            def build_event_specific_payload(step, event_type, additional_context)
+              case event_type
+              when :completed
+                build_completion_payload(step)
+              when :failed
+                build_failure_payload(step, additional_context)
+              when :started
+                build_start_payload(step)
+              when :retry
+                build_retry_payload(step)
+              else
+                {}
+              end
+            end
+
+            # Build completion-specific payload fields
+            #
+            # @param step [WorkflowStep] The completed step
+            # @return [Hash] Completion payload fields
+            def build_completion_payload(step)
+              payload = {}
+
+              # Calculate execution duration using last_attempted_at and processed_at
+              payload[:execution_duration] = if step.last_attempted_at && step.processed_at
+                                               (step.processed_at - step.last_attempted_at).round(3)
+                                             else
+                                               0.0
+                                             end
+
+              # Include step results if available
+              payload[:step_results] = step.results if step.results.present?
+
+              payload
+            end
+
+            # Build failure-specific payload fields
+            #
+            # @param step [WorkflowStep] The failed step
+            # @param additional_context [Hash] Additional context (may include error details)
+            # @return [Hash] Failure payload fields
+            def build_failure_payload(step, additional_context = {})
+              payload = {}
+
+              # Extract error information using the refactored service
+              error_info = ErrorInfoExtractor.extract(step, additional_context)
+              payload.merge!(error_info)
+
+              # Include step results
+              payload[:step_results] = step.results if step.results.present?
+
+              payload
+            end
+
+            # Build start-specific payload fields
+            #
+            # @param step [WorkflowStep] The starting step
+            # @return [Hash] Start payload fields
+            def build_start_payload(step)
+              {
+                step_inputs: step.inputs,
+                step_dependencies: step.respond_to?(:parents) ? step.parents.map(&:name) : []
+              }
+            end
+
+            # Build retry-specific payload fields
+            #
+            # @param step [WorkflowStep] The step being retried
+            # @return [Hash] Retry payload fields
+            def build_retry_payload(step)
+              {
+                previous_attempts: step.attempts - 1,
+                retry_reason: 'Step execution failed',
+                backoff_strategy: 'exponential' # Could be made configurable
+              }
+            end
+          end
+        end
+      end
+
+      # Service class to extract error information from step and context
+      # Reduces complexity by organizing error extraction logic
+      class ErrorInfoExtractor
+        class << self
+          # Extract error information from step and context
+          #
+          # @param step [WorkflowStep] The step with error
+          # @param additional_context [Hash] Additional context
+          # @return [Hash] Error information payload
+          def extract(step, additional_context = {})
+            error_payload = {}
+
+            error_payload[:error_message] = extract_error_message(step, additional_context)
+            error_payload[:exception_class] = extract_exception_class(additional_context)
+
+            backtrace = extract_backtrace(step, additional_context)
+            error_payload[:backtrace] = backtrace if backtrace
+
+            error_payload
+          end
+
+          private
+
+          # Extract the primary error message from various sources
+          #
+          # @param step [WorkflowStep] The step with error
+          # @param additional_context [Hash] Additional context
+          # @return [String] The error message
+          def extract_error_message(step, additional_context)
+            additional_context[:error_message] ||
+              additional_context[:error] ||
+              step.results&.dig('error') ||
+              step.results&.dig(:error) ||
+              'Unknown error'
+          end
+
+          # Extract the exception class name
+          #
+          # @param additional_context [Hash] Additional context
+          # @return [String] The exception class name
+          def extract_exception_class(additional_context)
+            if additional_context[:exception_object]
+              additional_context[:exception_object].class.name
+            elsif additional_context[:exception_class]
+              additional_context[:exception_class]
+            else
+              'StandardError'
+            end
+          end
+
+          # Extract backtrace information from various sources
+          #
+          # @param step [WorkflowStep] The step with error
+          # @param additional_context [Hash] Additional context
+          # @return [String, nil] The backtrace or nil if not available
+          def extract_backtrace(step, additional_context)
+            additional_context[:backtrace] ||
+              step.results&.dig('backtrace') ||
+              step.results&.dig(:backtrace)
+          end
+        end
+      end
+    end
+  end
+end