tasker-engine 1.0.0

data/lib/tasker/constants.rb

@@ -0,0 +1,417 @@
+# typed: false
+# frozen_string_literal: true
+
+require_relative 'events/definition_loader'
+require_relative 'constants/event_definitions'
+
+module Tasker
+  # Constants used throughout the Tasker gem
+  #
+  # This module contains constants for workflow step and task statuses,
+  # validation states, and configuration schemas.
+  #
+  # Event constants are generated from YAML definitions in config/tasker/system_events.yml
+  # Run `rake tasker:generate_constants` to regenerate after YAML changes.
+  module Constants
+    # Status values for workflow steps
+    module WorkflowStepStatuses
+      # Step is waiting to be processed
+      PENDING = 'pending'
+      # Step is currently being processed
+      IN_PROGRESS = 'in_progress'
+      # Step encountered an error during processing
+      ERROR = 'error'
+      # Step completed successfully
+      COMPLETE = 'complete'
+      # Step was manually marked as resolved
+      RESOLVED_MANUALLY = 'resolved_manually'
+      # Step was cancelled
+      CANCELLED = 'cancelled'
+    end
+
+    # Status values for tasks
+    module TaskStatuses
+      # Task is waiting to be processed
+      PENDING = 'pending'
+      # Task is currently being processed
+      IN_PROGRESS = 'in_progress'
+      # Task encountered an error during processing
+      ERROR = 'error'
+      # Task completed successfully
+      COMPLETE = 'complete'
+      # Task was manually marked as resolved
+      RESOLVED_MANUALLY = 'resolved_manually'
+      # Task was cancelled
+      CANCELLED = 'cancelled'
+    end
+
+    # Task execution context status values from TaskExecutionContext view
+    module TaskExecution
+      # Execution status values - indicate current workflow execution state
+      module ExecutionStatus
+        # Task has steps ready for immediate execution
+        HAS_READY_STEPS = 'has_ready_steps'
+        # Task has steps currently being processed
+        PROCESSING = 'processing'
+        # Task is blocked by failed steps with no ready steps
+        BLOCKED_BY_FAILURES = 'blocked_by_failures'
+        # All task steps have completed successfully
+        ALL_COMPLETE = 'all_complete'
+        # Task is waiting for step dependencies to be satisfied
+        WAITING_FOR_DEPENDENCIES = 'waiting_for_dependencies'
+      end
+
+      # Recommended action values - indicate what should happen next
+      module RecommendedAction
+        # Execute the steps that are ready for processing
+        EXECUTE_READY_STEPS = 'execute_ready_steps'
+        # Wait for currently processing steps to complete
+        WAIT_FOR_COMPLETION = 'wait_for_completion'
+        # Handle failed steps that are blocking progress
+        HANDLE_FAILURES = 'handle_failures'
+        # Finalize the task as all steps are complete
+        FINALIZE_TASK = 'finalize_task'
+        # Wait for dependencies to be satisfied
+        WAIT_FOR_DEPENDENCIES = 'wait_for_dependencies'
+      end
+
+      # Health status values - indicate overall workflow health
+      module HealthStatus
+        # No failed steps, workflow is healthy
+        HEALTHY = 'healthy'
+        # Has failed steps but also has ready steps (can make progress)
+        RECOVERING = 'recovering'
+        # Has failed steps and no ready steps (intervention needed)
+        BLOCKED = 'blocked'
+        # Health status cannot be determined
+        UNKNOWN = 'unknown'
+      end
+    end
+
+    # All valid status values for workflow steps
+    VALID_WORKFLOW_STEP_STATUSES = [
+      WorkflowStepStatuses::PENDING,
+      WorkflowStepStatuses::IN_PROGRESS,
+      WorkflowStepStatuses::ERROR,
+      WorkflowStepStatuses::COMPLETE,
+      WorkflowStepStatuses::CANCELLED,
+      WorkflowStepStatuses::RESOLVED_MANUALLY
+    ].freeze
+
+    # Status values for steps that are not ready to be processed
+    UNREADY_WORKFLOW_STEP_STATUSES = [
+      WorkflowStepStatuses::IN_PROGRESS,
+      WorkflowStepStatuses::COMPLETE,
+      WorkflowStepStatuses::CANCELLED,
+      WorkflowStepStatuses::RESOLVED_MANUALLY
+    ].freeze
+
+    # All valid status values for tasks
+    VALID_TASK_STATUSES = [
+      TaskStatuses::PENDING,
+      TaskStatuses::IN_PROGRESS,
+      TaskStatuses::ERROR,
+      TaskStatuses::COMPLETE,
+      TaskStatuses::CANCELLED,
+      TaskStatuses::RESOLVED_MANUALLY
+    ].freeze
+
+    # Step status values that indicate completion (success or otherwise)
+    VALID_STEP_COMPLETION_STATES = [
+      WorkflowStepStatuses::COMPLETE,
+      WorkflowStepStatuses::RESOLVED_MANUALLY,
+      WorkflowStepStatuses::CANCELLED
+    ].freeze
+
+    # Step status values that indicate the step is still in a working state
+    VALID_STEP_STILL_WORKING_STATES = [WorkflowStepStatuses::PENDING, WorkflowStepStatuses::IN_PROGRESS].freeze
+
+    # All valid execution status values from TaskExecutionContext view
+    VALID_TASK_EXECUTION_STATUSES = [
+      TaskExecution::ExecutionStatus::HAS_READY_STEPS,
+      TaskExecution::ExecutionStatus::PROCESSING,
+      TaskExecution::ExecutionStatus::BLOCKED_BY_FAILURES,
+      TaskExecution::ExecutionStatus::ALL_COMPLETE,
+      TaskExecution::ExecutionStatus::WAITING_FOR_DEPENDENCIES
+    ].freeze
+
+    # All valid recommended action values from TaskExecutionContext view
+    VALID_TASK_RECOMMENDED_ACTIONS = [
+      TaskExecution::RecommendedAction::EXECUTE_READY_STEPS,
+      TaskExecution::RecommendedAction::WAIT_FOR_COMPLETION,
+      TaskExecution::RecommendedAction::HANDLE_FAILURES,
+      TaskExecution::RecommendedAction::FINALIZE_TASK,
+      TaskExecution::RecommendedAction::WAIT_FOR_DEPENDENCIES
+    ].freeze
+
+    # All valid health status values from TaskExecutionContext view
+    VALID_TASK_HEALTH_STATUSES = [
+      TaskExecution::HealthStatus::HEALTHY,
+      TaskExecution::HealthStatus::RECOVERING,
+      TaskExecution::HealthStatus::BLOCKED,
+      TaskExecution::HealthStatus::UNKNOWN
+    ].freeze
+
+    # Execution statuses that indicate the task can make immediate progress
+    ACTIONABLE_TASK_EXECUTION_STATUSES = [
+      TaskExecution::ExecutionStatus::HAS_READY_STEPS
+    ].freeze
+
+    # Execution statuses that indicate the task should be re-enqueued for later
+    REENQUEUE_TASK_EXECUTION_STATUSES = [
+      TaskExecution::ExecutionStatus::PROCESSING,
+      TaskExecution::ExecutionStatus::WAITING_FOR_DEPENDENCIES
+    ].freeze
+
+    # Execution statuses that indicate the task needs intervention
+    INTERVENTION_TASK_EXECUTION_STATUSES = [
+      TaskExecution::ExecutionStatus::BLOCKED_BY_FAILURES
+    ].freeze
+
+    # Default value for unknown identifiers
+    UNKNOWN = 'unknown'
+
+    # JSON schema for validating task handler YAML configurations
+    YAML_SCHEMA = {
+      type: 'object',
+      required: %w[name task_handler_class step_templates],
+      properties: {
+        name: { type: 'string' },
+        module_namespace: { type: 'string', default: nil },
+        task_handler_class: { type: 'string' },
+        concurrent: { type: 'boolean', default: true },
+        default_dependent_system: { type: 'string' },
+        named_steps: {
+          type: 'array',
+          items: { type: 'string' }
+        },
+        schema: { type: 'object' },
+        step_templates: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: %w[name handler_class],
+            properties: {
+              dependent_system: { type: 'string' },
+              name: { type: 'string' },
+              description: { type: 'string' },
+              default_retryable: { type: 'boolean' },
+              default_retry_limit: { type: 'integer' },
+              skippable: { type: 'boolean' },
+              handler_class: { type: 'string' },
+              depends_on_step: { type: 'string' },
+              depends_on_steps: {
+                type: 'array',
+                items: { type: 'string' }
+              },
+              handler_config: { type: 'object' },
+              custom_events: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  required: %w[name],
+                  properties: {
+                    name: { type: 'string' },
+                    description: { type: 'string' }
+                  }
+                }
+              }
+            }
+          }
+        },
+        environments: {
+          type: 'object',
+          additionalProperties: {
+            type: 'object',
+            properties: {
+              step_templates: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  required: %w[name],
+                  properties: {
+                    name: { type: 'string' },
+                    handler_config: { type: 'object' }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }.freeze
+
+    # Task lifecycle event constants
+    module TaskEvents
+      INITIALIZE_REQUESTED = 'task.initialize_requested'
+      START_REQUESTED = 'task.start_requested'
+      COMPLETED = 'task.completed'
+      FAILED = 'task.failed'
+      RETRY_REQUESTED = 'task.retry_requested'
+      CANCELLED = 'task.cancelled'
+      RESOLVED_MANUALLY = 'task.resolved_manually'
+      BEFORE_TRANSITION = 'task.before_transition'
+    end
+
+    # Step lifecycle event constants
+    module StepEvents
+      INITIALIZE_REQUESTED = 'step.initialize_requested'
+      EXECUTION_REQUESTED = 'step.execution_requested'
+      BEFORE_HANDLE = 'step.before_handle'
+      HANDLE = 'step.handle'
+      COMPLETED = 'step.completed'
+      FAILED = 'step.failed'
+      RETRY_REQUESTED = 'step.retry_requested'
+      CANCELLED = 'step.cancelled'
+      RESOLVED_MANUALLY = 'step.resolved_manually'
+      BEFORE_TRANSITION = 'step.before_transition'
+    end
+
+    # Workflow orchestration event constants
+    module WorkflowEvents
+      TASK_STARTED = 'workflow.task_started'
+      TASK_COMPLETED = 'workflow.task_completed'
+      TASK_FAILED = 'workflow.task_failed'
+      STEP_COMPLETED = 'workflow.step_completed'
+      STEP_FAILED = 'workflow.step_failed'
+      VIABLE_STEPS_DISCOVERED = 'workflow.viable_steps_discovered'
+      NO_VIABLE_STEPS = 'workflow.no_viable_steps'
+      ORCHESTRATION_REQUESTED = 'workflow.orchestration_requested'
+      TASK_FINALIZATION_STARTED = 'workflow.task_finalization_started'
+      TASK_FINALIZATION_COMPLETED = 'workflow.task_finalization_completed'
+      TASK_REENQUEUE_STARTED = 'workflow.task_reenqueue_started'
+      TASK_REENQUEUE_REQUESTED = 'workflow.task_reenqueue_requested'
+      TASK_REENQUEUE_FAILED = 'workflow.task_reenqueue_failed'
+      TASK_REENQUEUE_DELAYED = 'workflow.task_reenqueue_delayed'
+      TASK_STATE_UNCLEAR = 'workflow.task_state_unclear'
+      STEP_EXECUTION_FAILED = 'workflow.step_execution_failed'
+      VIABLE_STEPS_BATCH_READY = 'workflow.viable_steps_batch_ready'
+      STEPS_EXECUTION_STARTED = 'workflow.steps_execution_started'
+      STEPS_EXECUTION_COMPLETED = 'workflow.steps_execution_completed'
+    end
+
+    # Observability and telemetry event constants
+    module ObservabilityEvents
+      # Task-level observability events
+      module Task
+        HANDLE = 'observability.task.handle'
+        ENQUEUE = 'observability.task.enqueue'
+        FINALIZE = 'observability.task.finalize'
+      end
+
+      # Step-level observability events
+      module Step
+        HANDLE = 'observability.step.handle'
+        FIND_VIABLE = 'observability.step.find_viable'
+        BACKOFF = 'observability.step.backoff'
+        SKIP = 'observability.step.skip'
+        MAX_RETRIES_REACHED = 'observability.step.max_retries_reached'
+      end
+    end
+
+    # Test event constants
+    module TestEvents
+      BASIC_EVENT = 'test.event'
+      SLOW_EVENT = 'slow.event'
+      TEST_EVENT = 'test.event'
+      CUSTOM_EVENT = 'custom.event'
+      # Alternative casing event for testing
+      TEST_DOT_EVENT = 'Test.Event'
+    end
+
+    # Task finalization reason constants
+    module TaskFinalization
+      # Error messages for task failure scenarios
+      module ErrorMessages
+        STEPS_IN_ERROR_STATE = 'steps_in_error_state'
+      end
+
+      # Reasons for re-enqueueing tasks (asynchronous processing)
+      module ReenqueueReasons
+        # Unable to determine context
+        CONTEXT_UNAVAILABLE = 'context_unavailable'
+        # Steps are currently in progress
+        STEPS_IN_PROGRESS = 'steps_in_progress'
+        # Waiting for dependency completion
+        AWAITING_DEPENDENCIES = 'awaiting_dependencies'
+        # Ready steps are available for processing
+        READY_STEPS_AVAILABLE = 'ready_steps_available'
+        # General workflow continuation
+        CONTINUING_WORKFLOW = 'continuing_workflow'
+        # Default reason for pending steps (from TaskReenqueuer)
+        PENDING_STEPS_REMAINING = 'pending_steps_remaining'
+        # Default reason for retry backoff (from TaskReenqueuer)
+        RETRY_BACKOFF = 'retry_backoff'
+      end
+
+      # Reasons for setting tasks to pending (synchronous processing)
+      module PendingReasons
+        # Unable to determine context
+        CONTEXT_UNAVAILABLE = 'context_unavailable'
+        # Waiting for current steps to complete
+        WAITING_FOR_STEP_COMPLETION = 'waiting_for_step_completion'
+        # Waiting for dependencies to be satisfied
+        WAITING_FOR_DEPENDENCIES = 'waiting_for_dependencies'
+        # Ready for immediate processing
+        READY_FOR_PROCESSING = 'ready_for_processing'
+        # Workflow temporarily paused
+        WORKFLOW_PAUSED = 'workflow_paused'
+      end
+    end
+
+    # All valid re-enqueue reason values for task finalization
+    VALID_TASK_REENQUEUE_REASONS = [
+      TaskFinalization::ReenqueueReasons::CONTEXT_UNAVAILABLE,
+      TaskFinalization::ReenqueueReasons::STEPS_IN_PROGRESS,
+      TaskFinalization::ReenqueueReasons::AWAITING_DEPENDENCIES,
+      TaskFinalization::ReenqueueReasons::READY_STEPS_AVAILABLE,
+      TaskFinalization::ReenqueueReasons::CONTINUING_WORKFLOW,
+      TaskFinalization::ReenqueueReasons::PENDING_STEPS_REMAINING,
+      TaskFinalization::ReenqueueReasons::RETRY_BACKOFF
+    ].freeze
+
+    # All valid pending reason values for task finalization
+    VALID_TASK_PENDING_REASONS = [
+      TaskFinalization::PendingReasons::CONTEXT_UNAVAILABLE,
+      TaskFinalization::PendingReasons::WAITING_FOR_STEP_COMPLETION,
+      TaskFinalization::PendingReasons::WAITING_FOR_DEPENDENCIES,
+      TaskFinalization::PendingReasons::READY_FOR_PROCESSING,
+      TaskFinalization::PendingReasons::WORKFLOW_PAUSED
+    ].freeze
+
+    # Task Transition Event Map
+    TASK_TRANSITION_EVENT_MAP = {
+      # Initial state transitions (from nil/initial)
+      [nil, TaskStatuses::PENDING] => TaskEvents::INITIALIZE_REQUESTED,
+      [nil, TaskStatuses::IN_PROGRESS] => TaskEvents::START_REQUESTED,
+      [nil, TaskStatuses::COMPLETE] => TaskEvents::COMPLETED,
+      [nil, TaskStatuses::ERROR] => TaskEvents::FAILED,
+      [nil, TaskStatuses::CANCELLED] => TaskEvents::CANCELLED,
+      [nil, TaskStatuses::RESOLVED_MANUALLY] => TaskEvents::RESOLVED_MANUALLY,
+
+      # Normal state transitions
+      [TaskStatuses::PENDING,
+       TaskStatuses::IN_PROGRESS] => TaskEvents::START_REQUESTED,
+      [TaskStatuses::PENDING, TaskStatuses::CANCELLED] => TaskEvents::CANCELLED,
+      [TaskStatuses::PENDING, TaskStatuses::ERROR] => TaskEvents::FAILED,
+
+      [TaskStatuses::IN_PROGRESS,
+       TaskStatuses::PENDING] => TaskEvents::INITIALIZE_REQUESTED,
+      [TaskStatuses::IN_PROGRESS,
+       TaskStatuses::COMPLETE] => TaskEvents::COMPLETED,
+      [TaskStatuses::IN_PROGRESS, TaskStatuses::ERROR] => TaskEvents::FAILED,
+      [TaskStatuses::IN_PROGRESS,
+       TaskStatuses::CANCELLED] => TaskEvents::CANCELLED,
+
+      [TaskStatuses::ERROR,
+       TaskStatuses::PENDING] => TaskEvents::RETRY_REQUESTED,
+      [TaskStatuses::ERROR,
+       TaskStatuses::RESOLVED_MANUALLY] => TaskEvents::RESOLVED_MANUALLY,
+
+      # New transitions for admin override scenarios
+      [TaskStatuses::COMPLETE, TaskStatuses::CANCELLED] => TaskEvents::CANCELLED,
+      [TaskStatuses::RESOLVED_MANUALLY,
+       TaskStatuses::CANCELLED] => TaskEvents::CANCELLED
+    }.freeze
+  end
+end

data/lib/tasker/engine.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# Rails engine for Tasker gem
+#
+# This engine handles Rails-specific setup, autoloading configuration,
+# and loading of production runtime components. Development/test-only
+# dependencies are handled by the Gemfile and should not be loaded here.
+
+# Required Rails framework
+require 'rails'
+
+# Runtime dependencies from gemspec that need explicit loading
+require 'active_model_serializers'
+require 'graphql'
+require 'json-schema'
+require 'pg'
+require 'faraday'
+require 'scenic'
+
+module Tasker
+  class Engine < ::Rails::Engine
+    isolate_namespace Tasker
+
+    # Configure paths before initialization to let Zeitwerk handle autoloading
+    config.before_configuration do |app|
+      app.config.autoload_paths << root.join('lib')
+      app.config.eager_load_paths << root.join('lib')
+    end
+
+    # Validate required configuration files
+    initializer 'tasker.validate_configuration', before: :load_config_initializers do |_app|
+      # Check for required system configuration files
+      system_events_yaml = root.join('config', 'tasker', 'system_events.yml')
+
+      unless File.exist?(system_events_yaml)
+        raise Tasker::ConfigurationError,
+              "Required configuration file missing: #{system_events_yaml}. " \
+              'This file contains essential state machine mappings for Tasker. ' \
+              'Please ensure it exists or reinstall the gem.'
+      end
+    end
+
+    # Initialize essential components before app initialization
+    initializer 'tasker.setup', before: :load_config_initializers do |_app|
+      # Load core components that need explicit initialization
+      require 'tasker/constants'
+      require 'tasker/configuration'
+      require 'tasker/types'
+      require 'tasker/handler_factory'
+      require 'tasker/identity_strategy'
+      require 'tasker/task_handler'
+      require 'tasker/task_builder'
+      require 'tasker/state_machine'
+      require 'tasker/orchestration'
+      require 'tasker/events'
+      require 'tasker/events/publisher'
+      require 'tasker/events/catalog'
+      require 'tasker/events/subscribers/base_subscriber'
+      require 'tasker/events/subscribers/telemetry_subscriber'
+      require 'tasker/functions'
+
+      # Configure Statesman for state machine support
+      Tasker::StateMachine.configure_statesman
+
+      # Configure generators for Rails integration
+      config.generators.api_only = true
+      config.generators.test_framework = :rspec
+      config.application_controller = 'ActionController::API'
+    end
+
+    # Initialize orchestration system after Rails is fully loaded
+    initializer 'tasker.orchestration', after: :load_config_initializers do |_app|
+      # Initialize the orchestration system in all environments
+      # This ensures consistent behavior between test, development, and production
+      Tasker::Orchestration::Coordinator.initialize!
+    end
+
+    config.generators do |g|
+      g.test_framework :rspec
+      g.fixture_replacement :factory_bot
+      g.factory_bot dir: 'spec/factories'
+    end
+
+    class << self
+      def configure(&)
+        yield(Engine.config)
+      end
+    end
+  end
+end

data/lib/tasker/errors.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Tasker
+  # Base error class for all Tasker-related errors
+  class Error < StandardError; end
+
+  # Raised when there are configuration-related issues in Tasker
+  class ConfigurationError < Error; end
+
+  # Base class for all Tasker-specific errors that occur during workflow execution
+  class ProceduralError < Error; end
+
+  # Error indicating a step failed but should be retried with backoff
+  #
+  # Use this error when an operation fails due to temporary conditions like:
+  # - Network timeouts
+  # - Rate limiting (429 status)
+  # - Server errors (5xx status)
+  # - Temporary service unavailability
+  #
+  # @example Basic retryable error
+  #   raise Tasker::RetryableError, "Payment service timeout"
+  #
+  # @example With retry delay
+  #   raise Tasker::RetryableError.new("Rate limited", retry_after: 60)
+  #
+  # @example With context for monitoring
+  #   raise Tasker::RetryableError.new(
+  #     "External API unavailable",
+  #     retry_after: 30,
+  #     context: { service: 'billing_api', error_code: 503 }
+  #   )
+  class RetryableError < ProceduralError
+    # @return [Integer, nil] Suggested retry delay in seconds
+    attr_reader :retry_after
+
+    # @return [Hash] Additional context for error monitoring and debugging
+    attr_reader :context
+
+    # @param message [String] Error message
+    # @param retry_after [Integer, nil] Suggested retry delay in seconds
+    # @param context [Hash] Additional context for monitoring
+    def initialize(message, retry_after: nil, context: {})
+      super(message)
+      @retry_after = retry_after
+      @context = context
+    end
+  end
+
+  # Error indicating a step failed permanently and should not be retried
+  #
+  # Use this error when an operation fails due to permanent conditions like:
+  # - Invalid request data (400 status)
+  # - Authentication/authorization failures (401/403 status)
+  # - Validation errors (422 status)
+  # - Resource not found when it should exist (404 status in some contexts)
+  # - Business logic violations
+  #
+  # @example Basic permanent error
+  #   raise Tasker::PermanentError, "Invalid user ID format"
+  #
+  # @example With error code for categorization
+  #   raise Tasker::PermanentError.new(
+  #     "Insufficient funds for transaction",
+  #     error_code: 'INSUFFICIENT_FUNDS'
+  #   )
+  #
+  # @example With context for monitoring
+  #   raise Tasker::PermanentError.new(
+  #     "User not authorized for this operation",
+  #     error_code: 'AUTHORIZATION_FAILED',
+  #     context: { user_id: 123, operation: 'admin_access' }
+  #   )
+  class PermanentError < ProceduralError
+    # @return [String, nil] Machine-readable error code for categorization
+    attr_reader :error_code
+
+    # @return [Hash] Additional context for error monitoring and debugging
+    attr_reader :context
+
+    # @param message [String] Error message
+    # @param error_code [String, nil] Machine-readable error code
+    # @param context [Hash] Additional context for monitoring
+    def initialize(message, error_code: nil, context: {})
+      super(message)
+      @error_code = error_code
+      @context = context
+    end
+  end
+end