tasker-engine 1.0.0

data/lib/tasker/task_handler/class_methods.rb

@@ -0,0 +1,324 @@
+# typed: false
+# frozen_string_literal: true
+
+require 'json-schema'
+require 'concurrent'
+require_relative '../events/custom_registry'
+
+module Tasker
+  module TaskHandler
+    # Class methods for task handlers
+    #
+    # This module provides class-level functionality for task handlers,
+    # including step template definition and handler registration.
+    module ClassMethods
+      # Helper class for defining step templates in task handlers
+      class StepTemplateDefiner
+        # @return [Array<Tasker::Types::StepTemplate>] The defined step templates
+        attr_reader :step_templates
+
+        # @return [Class] The class where templates are being defined
+        attr_reader :klass
+
+        # @return [Hash<String, String>] Mapping of step names to handler class names
+        attr_reader :step_handler_class_map
+
+        # @return [Hash<String, Object>] Mapping of step names to handler configs
+        attr_reader :step_handler_config_map
+
+        # Create a new step template definer
+        #
+        # @param klass [Class] The class where templates are being defined
+        # @return [StepTemplateDefiner] A new step template definer
+        def initialize(klass)
+          @klass = klass
+          @step_templates = []
+          @step_handler_class_map = {}
+          @step_handler_config_map = {}
+        end
+
+        # Define a new step template
+        #
+        # @param kwargs [Hash] The step template attributes
+        # @option kwargs [String] :dependent_system The system that this step depends on
+        # @option kwargs [String] :name The name identifier for this step
+        # @option kwargs [String] :description A description of what this step does
+        # @option kwargs [Boolean] :default_retryable Whether this step can be retried
+        # @option kwargs [Integer] :default_retry_limit The maximum number of retry attempts
+        # @option kwargs [Boolean] :skippable Whether this step can be skipped
+        # @option kwargs [Class] :handler_class The class that implements the step's logic
+        # @option kwargs [String, nil] :depends_on_step Name of a step this depends on
+        # @option kwargs [Array<String>] :depends_on_steps Names of steps this depends on
+        # @option kwargs [Object, nil] :handler_config Configuration for the step handler
+        # @option kwargs [Array<Hash>] :custom_events Custom events this step can publish
+        # @return [void]
+        def define(**kwargs)
+          dependent_system = kwargs.fetch(:dependent_system, Tasker::Constants::UNKNOWN)
+          name = kwargs.fetch(:name)
+          handler_class = kwargs.fetch(:handler_class)
+          description = kwargs.fetch(:description, name)
+          default_retryable = kwargs.fetch(:default_retryable, true)
+          default_retry_limit = kwargs.fetch(:default_retry_limit, 3)
+          skippable = kwargs.fetch(:skippable, false)
+          depends_on_step = kwargs.fetch(:depends_on_step, nil)
+          depends_on_steps = kwargs.fetch(:depends_on_steps, [])
+          handler_config = kwargs.fetch(:handler_config, nil)
+          custom_events = kwargs.fetch(:custom_events, [])
+
+          # Register custom events (both YAML-based and class-based) when step template is defined
+          register_custom_events_for_handler(custom_events, handler_class)
+
+          @step_templates << Tasker::Types::StepTemplate.new(
+            dependent_system: dependent_system,
+            name: name,
+            description: description,
+            default_retryable: default_retryable,
+            default_retry_limit: default_retry_limit,
+            skippable: skippable,
+            handler_class: handler_class,
+            depends_on_step: depends_on_step,
+            depends_on_steps: depends_on_steps,
+            handler_config: handler_config,
+            custom_events: custom_events
+          )
+        end
+
+        # Register the mapping of step names to handler classes and configs
+        #
+        # @return [void]
+        def register_class_map
+          @step_templates.each do |template|
+            @step_handler_class_map[template.name] = template.handler_class.to_s
+            @step_handler_config_map[template.name] = template.handler_config
+          end
+        end
+
+        private
+
+        # Register both YAML-based and class-based custom events from the step handler
+        #
+        # @param custom_events [Array<Hash>] Array of custom event configurations from YAML
+        # @param handler_class [Class] The handler class that can fire these events
+        # @return [void]
+        def register_custom_events_for_handler(custom_events, handler_class)
+          YamlEventRegistrar.register(custom_events, handler_class)
+          register_class_based_custom_events(handler_class)
+        end
+
+        # Register class-based custom events from a step handler class
+        #
+        # @param handler_class [Class] The step handler class to scan for custom events
+        # @return [void]
+        def register_class_based_custom_events(handler_class)
+          ClassBasedEventRegistrar.register(handler_class)
+        end
+
+        # Service class to register YAML-based custom events
+        # Reduces complexity by organizing YAML event registration logic
+        class YamlEventRegistrar
+          class << self
+            # Register YAML-based custom events
+            #
+            # @param custom_events [Array<Hash>] Array of custom event configurations from YAML
+            # @param handler_class [Class] The handler class that can fire these events
+            # @return [void]
+            def register(custom_events, handler_class)
+              custom_events.each do |event_config|
+                register_single_yaml_event(event_config, handler_class)
+              end
+            end
+
+            private
+
+            # Register a single YAML-based custom event
+            #
+            # @param event_config [Hash] Event configuration
+            # @param handler_class [Class] Handler class
+            # @return [void]
+            def register_single_yaml_event(event_config, handler_class)
+              event_name = extract_event_name(event_config)
+              return unless event_name
+
+              description = extract_event_description(event_config, handler_class)
+              fired_by = [handler_class.name]
+
+              safely_register_event(event_name, description, fired_by, handler_class)
+            end
+
+            # Extract event name from configuration
+            #
+            # @param event_config [Hash] Event configuration
+            # @return [String, nil] Event name
+            def extract_event_name(event_config)
+              event_config[:name] || event_config['name']
+            end
+
+            # Extract event description from configuration
+            #
+            # @param event_config [Hash] Event configuration
+            # @param handler_class [Class] Handler class
+            # @return [String] Event description
+            def extract_event_description(event_config, handler_class)
+              event_config[:description] ||
+                event_config['description'] ||
+                "Custom event from #{handler_class.name}"
+            end
+
+            # Register event - fail fast on configuration errors
+            #
+            # @param event_name [String] Event name
+            # @param description [String] Event description
+            # @param fired_by [Array] Array of handler class names
+            # @param handler_class [Class] Handler class for error context
+            # @return [void]
+            # @raise [StandardError] If event registration fails (fail fast)
+            def safely_register_event(event_name, description, fired_by, _handler_class)
+              Tasker::Events::CustomRegistry.instance.register_event(
+                event_name,
+                description: description,
+                fired_by: fired_by
+              )
+              # Configuration errors should be visible, not silently logged
+            end
+
+            # Log registration failure
+            #
+            # @param event_name [String] Event name that failed
+            # @param handler_class [Class] Handler class
+            # @param error [StandardError] Error that occurred
+            # @return [void]
+            def log_registration_failure(event_name, handler_class, error)
+              return unless defined?(Rails)
+
+              Rails.logger.warn "Failed to register custom event #{event_name} from #{handler_class}: #{error.message}"
+            end
+          end
+        end
+
+        # Service class to register class-based custom events
+        # Reduces complexity by organizing event registration logic
+        class ClassBasedEventRegistrar
+          class << self
+            # Register class-based custom events from a step handler class
+            #
+            # @param handler_class [Class] The step handler class to scan for custom events
+            # @return [void]
+            def register(handler_class)
+              return unless has_custom_event_configuration?(handler_class)
+
+              safely_register_events(handler_class)
+            end
+
+            private
+
+            # Check if handler class has custom event configuration
+            #
+            # @param handler_class [Class] The step handler class
+            # @return [Boolean] True if class has custom event configuration
+            def has_custom_event_configuration?(handler_class)
+              handler_class.respond_to?(:custom_event_configuration)
+            end
+
+            # Register all custom events from handler class - fail fast on configuration errors
+            #
+            # @param handler_class [Class] The step handler class
+            # @return [void]
+            # @raise [StandardError] If custom event configuration fails (fail fast)
+            def safely_register_events(handler_class)
+              class_events = get_class_events(handler_class)
+              class_events.each { |event_config| register_single_event(event_config, handler_class) }
+              # Configuration errors should be visible, not silently logged
+            end
+
+            # Get custom events from handler class configuration
+            #
+            # @param handler_class [Class] The step handler class
+            # @return [Array] Array of event configurations
+            def get_class_events(handler_class)
+              handler_class.custom_event_configuration
+            end
+
+            # Register a single custom event
+            #
+            # @param event_config [Hash] The event configuration
+            # @param handler_class [Class] The step handler class
+            # @return [void]
+            def register_single_event(event_config, handler_class)
+              event_name = extract_event_name(event_config)
+              return unless event_name
+
+              description = extract_event_description(event_config, handler_class)
+              fired_by = [handler_class.name]
+
+              Tasker::Events::CustomRegistry.instance.register_event(
+                event_name,
+                description: description,
+                fired_by: fired_by
+              )
+            end
+
+            # Extract event name from configuration
+            #
+            # @param event_config [Hash] The event configuration
+            # @return [String, nil] The event name
+            def extract_event_name(event_config)
+              event_config[:name] || event_config['name']
+            end
+
+            # Extract event description from configuration
+            #
+            # @param event_config [Hash] The event configuration
+            # @param handler_class [Class] The step handler class
+            # @return [String] The event description
+            def extract_event_description(event_config, handler_class)
+              event_config[:description] ||
+                event_config['description'] ||
+                "Custom event from #{handler_class.name}"
+            end
+
+            # Log registration failure
+            #
+            # @param handler_class [Class] The step handler class
+            # @param error [StandardError] The error that occurred
+            # @return [void]
+            def log_registration_failure(handler_class, error)
+              return unless defined?(Rails)
+
+              Rails.logger.warn "Failed to register class-based custom events from #{handler_class}: #{error.message}"
+            end
+          end
+        end
+      end
+
+      # Define step templates for a task handler
+      #
+      # @yield [StepTemplateDefiner] A block to define step templates
+      # @return [void]
+      def define_step_templates
+        definer = StepTemplateDefiner.new(self)
+        yield(definer)
+        definer.klass.define_method(:step_templates) do
+          definer.step_templates
+        end
+        definer.register_class_map
+        definer.klass.define_method(:step_handler_class_map) do
+          definer.step_handler_class_map
+        end
+        definer.klass.define_method(:step_handler_config_map) do
+          definer.step_handler_config_map
+        end
+      end
+
+      # Register a task handler with the handler factory
+      #
+      # @param name [String, Symbol] The name to register the handler under
+      # @param concurrent [Boolean] Whether to use concurrent processing
+      # @return [void]
+      def register_handler(name, namespace_name: 'default', version: '0.1.0', concurrent: true)
+        # Register the handler with the factory
+        Tasker::HandlerFactory.instance.register(name, self, namespace_name: namespace_name, version: version,
+                                                             replace: true)
+      end
+    end
+  end
+end

data/lib/tasker/task_handler/instance_methods.rb

@@ -0,0 +1,293 @@
+# typed: false
+# frozen_string_literal: true
+
+require 'json-schema'
+require 'tasker/constants'
+require 'tasker/types/step_sequence'
+require 'tasker/events/event_payload_builder'
+require_relative '../concerns/event_publisher'
+require_relative '../orchestration/workflow_coordinator'
+require_relative '../analysis/template_graph_analyzer'
+
+module Tasker
+  module TaskHandler
+    # Instance methods for task handlers
+    #
+    # Provides the core task processing logic including the main execution loop,
+    # step handling, and finalization. Delegates to orchestration components
+    # for implementation details while maintaining proven loop-based approach.
+    #
+    # @author TaskHandler Authors
+    module InstanceMethods
+      include Tasker::Concerns::EventPublisher
+
+      # List of attributes to pass from the task request to the task
+      #
+      # These are the attributes that will be copied from the task request
+      # to the task when initializing a new task.
+      #
+      # @return [Array<Symbol>] List of attribute names
+      TASK_REQUEST_ATTRIBUTES = %i[name context initiator reason source_system].freeze
+
+      # Initialize a task
+      #
+      # Validates input and creates initial workflow steps via orchestration.
+      #
+      # @param task_request [TaskRequest] The task request to initialize
+      # @return [Tasker::Task] The initialized task
+      def initialize_task!(task_request)
+        # Delegate to orchestration system
+        Tasker::Orchestration::TaskInitializer.initialize_task!(task_request, self)
+      end
+
+      # Get the step sequence for a task
+      #
+      # Retrieves all workflow steps for the task and establishes their dependencies.
+      # Delegates to StepSequenceFactory for implementation + observability events.
+      #
+      # @param task [Tasker::Task] The task to get the sequence for
+      # @return [Tasker::Types::StepSequence] The sequence of workflow steps
+      def get_sequence(task)
+        # Delegate to orchestration system for implementation + events
+        Tasker::Orchestration::StepSequenceFactory.get_sequence(task, self)
+      end
+
+      # Start a task's execution
+      #
+      # Updates the task status to IN_PROGRESS and fires the appropriate event.
+      #
+      # @param task [Tasker::Task] The task to start
+      # @return [Boolean] True if the task was started successfully
+      # @raise [Tasker::ProceduralError] If the task is already complete or not pending
+      def start_task(task)
+        # Delegate to orchestration system
+        Tasker::Orchestration::TaskInitializer.start_task!(task)
+      end
+
+      # Handle a task's execution
+      #
+      # This is the main entry point for processing a task. Delegates to
+      # WorkflowCoordinator for the execution loop to enable strategy composition.
+      #
+      # @param task [Tasker::Task] The task to handle
+      # @return [void]
+      def handle(task)
+        start_task(task)
+
+        # DELEGATE: Use WorkflowCoordinator for execution loop
+        # This enables strategy pattern composition for testing
+        workflow_coordinator.execute_workflow(task, self)
+      end
+
+      # Establish step dependencies and defaults
+      #
+      # This is a hook method that can be overridden by implementing classes.
+      # This method is public so that orchestration components can call it.
+      #
+      # @param task [Tasker::Task] The task being processed
+      # @param steps [Array<Tasker::WorkflowStep>] The steps to establish dependencies for
+      # @return [void]
+      def establish_step_dependencies_and_defaults(task, steps); end
+
+      # Update annotations based on processed steps
+      #
+      # This is a hook method that can be overridden by implementing classes.
+      # This method is public so that orchestration components can call it.
+      #
+      # @param task [Tasker::Task] The task being processed
+      # @param sequence [Tasker::Types::StepSequence] The sequence of steps
+      # @param steps [Array<Tasker::WorkflowStep>] The processed steps
+      # @return [void]
+      def update_annotations(task, sequence, steps); end
+
+      # Get a step handler for a specific step
+      #
+      # This method is public so that orchestration components can access step handlers.
+      #
+      # @param step [Tasker::WorkflowStep] The step to get a handler for
+      # @return [Object] The step handler
+      # @raise [Tasker::ProceduralError] If no handler is registered for the step
+      def get_step_handler(step)
+        raise(Tasker::ProceduralError, "No registered class for #{step.name}") unless step_handler_class_map[step.name]
+
+        handler_config = step_handler_config_map[step.name]
+        handler_class = step_handler_class_map[step.name].to_s.camelize.constantize
+
+        return handler_class.new if handler_config.nil?
+
+        handler_class.new(config: handler_config)
+      end
+
+      # Handle execution of a single step
+      #
+      # This is a convenience method for testing that executes a single step.
+      # Delegates to StepExecutor for consistent behavior.
+      #
+      # @param task [Tasker::Task] The task being processed
+      # @param sequence [Tasker::Types::StepSequence] The step sequence
+      # @param step [Tasker::WorkflowStep] The step to execute
+      # @return [Tasker::WorkflowStep] The processed step
+      def handle_one_step(task, sequence, step)
+        step_executor.execute_single_step(task, sequence, step, self)
+      end
+
+      # Get dependency graph analysis for this task handler's step templates
+      #
+      # Provides comprehensive analysis of step dependencies, including cycle detection,
+      # topological ordering, and dependency visualization. Useful for troubleshooting
+      # and understanding workflow structure.
+      #
+      # @return [Hash] Comprehensive dependency analysis containing:
+      #   - :nodes - Array of step information with dependencies
+      #   - :edges - Array of dependency relationships
+      #   - :topology - Topologically sorted step names
+      #   - :cycles - Array of detected circular dependencies
+      #   - :levels - Hash mapping steps to their dependency depth levels
+      #   - :roots - Array of steps with no dependencies
+      #   - :leaves - Array of steps with no dependents
+      def dependency_graph
+        template_analyzer.analyze
+      end
+
+      private
+
+      # Memoized step executor for consistent reuse
+      #
+      # @return [Tasker::Orchestration::StepExecutor] The step executor instance
+      def step_executor
+        @step_executor ||= Tasker::Orchestration::StepExecutor.new
+      end
+
+      # Memoized task finalizer for consistent reuse
+      #
+      # @return [Tasker::Orchestration::TaskFinalizer] The task finalizer instance
+      def task_finalizer
+        @task_finalizer ||= Tasker::Orchestration::TaskFinalizer.new
+      end
+
+      # Memoized workflow coordinator for consistent reuse
+      #
+      # Uses strategy pattern to allow composition of different coordinators
+      # and reenqueuer strategies for testing vs production.
+      #
+      # @return [Tasker::Orchestration::WorkflowCoordinator] The workflow coordinator instance
+      def workflow_coordinator
+        @workflow_coordinator ||= workflow_coordinator_strategy.new(
+          reenqueuer_strategy: reenqueuer_strategy.new
+        )
+      end
+
+      # Get the workflow coordinator strategy class
+      #
+      # Can be overridden for testing to inject TestWorkflowCoordinator
+      #
+      # @return [Class] The workflow coordinator strategy class
+      def workflow_coordinator_strategy
+        @workflow_coordinator_strategy || Tasker::Orchestration::WorkflowCoordinator
+      end
+
+      public
+
+      # Set the workflow coordinator strategy (for testing)
+      #
+      # @param strategy [Class] The workflow coordinator strategy class
+      def workflow_coordinator_strategy=(strategy)
+        @workflow_coordinator_strategy = strategy
+        @workflow_coordinator = nil # Reset memoized instance
+      end
+
+      # Set the reenqueuer strategy (for testing)
+      #
+      # @param strategy [Class] The reenqueuer strategy class
+      def reenqueuer_strategy=(strategy)
+        @reenqueuer_strategy = strategy
+        @workflow_coordinator = nil # Reset memoized instance
+      end
+
+      private
+
+      # Get the reenqueuer strategy class
+      #
+      # Can be overridden for testing to inject TestReenqueuer
+      #
+      # @return [Class] The reenqueuer strategy class
+      def reenqueuer_strategy
+        @reenqueuer_strategy || Tasker::Orchestration::TaskReenqueuer
+      end
+
+      # Find steps that are ready for execution
+      #
+      # This method finds workflow steps that are ready to be executed by checking
+      # their state and dependencies. It's a proven pattern that works reliably.
+      #
+      # @param task [Tasker::Task] The task being processed
+      # @param sequence [Tasker::Types::StepSequence] The step sequence
+      # @return [Array<Tasker::WorkflowStep>] Steps ready for execution
+      def find_viable_steps(task, sequence)
+        Orchestration::ViableStepDiscovery.new.find_viable_steps(task, sequence)
+      end
+
+      # Handle execution of viable steps
+      #
+      # This method executes a collection of viable steps, delegating to the
+      # StepExecutor for implementation details.
+      #
+      # @param task [Tasker::Task] The task being processed
+      # @param sequence [Tasker::Types::StepSequence] The step sequence
+      # @param viable_steps [Array<Tasker::WorkflowStep>] Steps ready for execution
+      # @return [Array<Tasker::WorkflowStep>] Processed steps
+      def handle_viable_steps(task, sequence, viable_steps)
+        step_executor.execute_steps(task, sequence, viable_steps, self)
+      end
+
+      # Check if task is blocked by errors
+      #
+      # @param task [Tasker::Task] The task to check
+      # @param sequence [Tasker::Types::StepSequence] The step sequence
+      # @param processed_steps [Array<Tasker::WorkflowStep>] Recently processed steps
+      # @return [Boolean] True if blocked by errors
+      def blocked_by_errors?(task, sequence, processed_steps)
+        task_finalizer.blocked_by_errors?(task, sequence, processed_steps)
+      end
+
+      # Finalize the task
+      #
+      # @param task [Tasker::Task] The task to finalize
+      # @param sequence [Tasker::Types::StepSequence] The final step sequence
+      # @param processed_steps [Array<Tasker::WorkflowStep>] All processed steps
+      def finalize(task, sequence, processed_steps)
+        # Call update_annotations hook before finalizing
+        update_annotations(task, sequence, processed_steps) if respond_to?(:update_annotations)
+
+        task_finalizer.finalize_task_with_steps(task, sequence, processed_steps)
+      end
+
+      # Get the schema for validating task context
+      #
+      # This is a hook method that can be overridden by implementing classes.
+      #
+      # @return [Hash, nil] The JSON schema for task context validation
+      def schema
+        nil
+      end
+
+      # Validate a task context against the schema
+      #
+      # @param context [Hash] The context to validate
+      # @return [Array<String>] Validation errors, if any
+      def validate_context(context)
+        return [] unless schema
+
+        data = context.to_hash.deep_symbolize_keys
+        JSON::Validator.fully_validate(schema, data, strict: true, insert_defaults: true)
+      end
+
+      # Get the template graph analyzer for this handler
+      #
+      # @return [Tasker::Analysis::TemplateGraphAnalyzer] The template analyzer
+      def template_analyzer
+        @template_analyzer ||= Tasker::Analysis::TemplateGraphAnalyzer.new(step_templates)
+      end
+    end
+  end
+end