tasker-engine 1.0.0

data/lib/tasker/types/engine_config.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Types
+    # Configuration type for core engine settings
+    #
+    # This configuration handles core Tasker engine settings including task handler
+    # directories, identity strategies, and custom event configurations.
+    # It provides the same functionality as the original EngineConfiguration but with
+    # dry-struct type safety and immutability.
+    #
+    # @example Basic usage
+    #   config = EngineConfig.new(
+    #     task_handler_directory: 'app/tasks',
+    #     identity_strategy: :hash
+    #   )
+    #
+    # @example Full configuration
+    #   config = EngineConfig.new(
+    #     task_handler_directory: 'app/tasks',
+    #     task_config_directory: 'config/tasks',
+    #     default_module_namespace: 'MyApp::Tasks',
+    #     identity_strategy: :custom,
+    #     identity_strategy_class: 'MyApp::CustomIdentityStrategy',
+    #     custom_events_directories: ['config/events', 'lib/events']
+    #   )
+    class EngineConfig < BaseConfig
+      transform_keys(&:to_sym)
+
+      # Directory where task handlers are located
+      #
+      # @!attribute [r] task_handler_directory
+      #   @return [String] Task handler directory path
+      attribute :task_handler_directory, Types::String.default('tasks')
+
+      # Directory where task configuration files are located
+      #
+      # @!attribute [r] task_config_directory
+      #   @return [String] Task configuration directory path
+      attribute :task_config_directory, Types::String.default('tasker/tasks')
+
+      # Default module namespace for task handlers
+      #
+      # @!attribute [r] default_module_namespace
+      #   @return [String, nil] Default module namespace for generated handlers
+      attribute? :default_module_namespace, Types::String.optional.default(nil)
+
+      # The strategy to use for generating task identities
+      #
+      # @!attribute [r] identity_strategy
+      #   @return [Symbol] Identity strategy (:default, :hash, :custom)
+      attribute :identity_strategy, Types::Symbol.default(:default)
+
+      # The class name to use for custom identity strategy
+      #
+      # @!attribute [r] identity_strategy_class
+      #   @return [String, nil] Custom identity strategy class name
+      attribute? :identity_strategy_class, Types::String.optional.default(nil)
+
+      # Directories to search for custom event YAML files
+      #
+      # @!attribute [r] custom_events_directories
+      #   @return [Array<String>] Custom event directories
+      attribute :custom_events_directories, Types::Array.of(Types::String).default(proc {
+        default_custom_events_directories
+      }.freeze, shared: true)
+
+      # Get default custom events directories
+      #
+      # @return [Array<String>] Default directories to search for custom events
+      def self.default_custom_events_directories
+        [
+          'config/tasker/events'
+        ].freeze
+      end
+
+      # Creates and returns an appropriate identity strategy instance
+      #
+      # @return [Tasker::IdentityStrategy] The identity strategy instance
+      # @raise [ArgumentError] If an invalid strategy is specified
+      def identity_strategy_instance
+        case identity_strategy
+        when :default
+          Tasker::IdentityStrategy.new
+        when :hash
+          Tasker::HashIdentityStrategy.new
+        when :custom
+          if identity_strategy_class.nil?
+            raise ArgumentError, 'Custom identity strategy selected but no identity_strategy_class provided'
+          end
+
+          begin
+            identity_strategy_class.constantize.new
+          rescue NameError => e
+            raise ArgumentError, "Invalid identity_strategy_class: #{e.message}"
+          end
+        else
+          raise ArgumentError, "Unknown identity_strategy: #{identity_strategy}"
+        end
+      end
+
+      # Add custom event directories to the existing configuration
+      #
+      # Since dry-struct types are immutable, this returns a new instance.
+      #
+      # @param directories [Array<String>] Additional directories to search for events
+      # @return [EngineConfig] New instance with updated directories
+      def add_custom_events_directories(*directories)
+        new_directories = (custom_events_directories + directories.flatten).uniq
+        self.class.new(to_h.merge(custom_events_directories: new_directories))
+      end
+
+      # Set custom event directories (replaces the default list)
+      #
+      # Since dry-struct types are immutable, this returns a new instance.
+      #
+      # @param directories [Array<String>] Directories to search for events
+      # @return [EngineConfig] New instance with updated directories
+      def set_custom_events_directories(directories)
+        self.class.new(to_h.merge(custom_events_directories: directories.flatten))
+      end
+
+      private
+
+      # Use class method for default custom events directories
+      def default_custom_events_directories
+        self.class.default_custom_events_directories
+      end
+    end
+  end
+end

data/lib/tasker/types/execution_config.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Types
+    # Configuration type for step execution and concurrency settings
+    #
+    # This configuration exposes previously hardcoded execution constants
+    # used in concurrent step processing, timeout handling, and memory management.
+    #
+    # Strategic Design:
+    # - CONFIGURABLE: Performance characteristics that vary by deployment environment
+    # - ARCHITECTURAL: Carefully chosen constants based on Ruby/Rails characteristics
+    #
+    # @example Basic usage
+    #   config = ExecutionConfig.new(
+    #     max_concurrent_steps_limit: 20,  # High-performance system
+    #     batch_timeout_base_seconds: 60   # API-heavy workflows
+    #   )
+    #
+    # @example Environment-specific tuning
+    #   # Development environment
+    #   config = ExecutionConfig.new(
+    #     min_concurrent_steps: 2,
+    #     max_concurrent_steps_limit: 6,
+    #     concurrency_cache_duration: 60
+    #   )
+    #
+    #   # Production environment
+    #   config = ExecutionConfig.new(
+    #     min_concurrent_steps: 5,
+    #     max_concurrent_steps_limit: 25,
+    #     batch_timeout_base_seconds: 45,
+    #     max_batch_timeout_seconds: 300
+    #   )
+    class ExecutionConfig < BaseConfig
+      transform_keys(&:to_sym)
+
+      # ====================
+      # CONFIGURABLE SETTINGS
+      # ====================
+      # These affect performance characteristics and should vary by deployment
+
+      # Minimum concurrent steps allowed
+      #
+      # Conservative bound to ensure system stability even under extreme load.
+      # Small systems might prefer 2, large systems might prefer 5+.
+      #
+      # @!attribute [r] min_concurrent_steps
+      #   @return [Integer] Minimum concurrent steps (default: 3)
+      attribute :min_concurrent_steps, Types::Integer.default(3)
+
+      # Maximum concurrent steps limit
+      #
+      # Upper bound for dynamic concurrency calculation.
+      # High-performance systems with large connection pools can handle 20-30+.
+      # Standard deployments typically use 8-15.
+      #
+      # @!attribute [r] max_concurrent_steps_limit
+      #   @return [Integer] Maximum concurrent steps limit (default: 12)
+      attribute :max_concurrent_steps_limit, Types::Integer.default(12)
+
+      # Cache duration for concurrency calculation
+      #
+      # How long to cache the calculated optimal concurrency before recalculating.
+      # Busy systems might want shorter cache (15s), stable systems longer (60s).
+      #
+      # @!attribute [r] concurrency_cache_duration
+      #   @return [Integer] Cache duration in seconds (default: 30)
+      attribute :concurrency_cache_duration, Types::Integer.default(30)
+
+      # Base timeout for batch execution
+      #
+      # Starting timeout before per-step adjustments.
+      # API-heavy workflows might need 60s+, simple workflows can use 15-20s.
+      #
+      # @!attribute [r] batch_timeout_base_seconds
+      #   @return [Integer] Base timeout in seconds (default: 30)
+      attribute :batch_timeout_base_seconds, Types::Integer.default(30)
+
+      # Per-step timeout addition
+      #
+      # Additional timeout per step in a batch.
+      # Complex steps might need 10s+, simple steps can use 2-3s.
+      #
+      # @!attribute [r] batch_timeout_per_step_seconds
+      #   @return [Integer] Per-step timeout in seconds (default: 5)
+      attribute :batch_timeout_per_step_seconds, Types::Integer.default(5)
+
+      # Maximum batch timeout ceiling
+      #
+      # Absolute maximum timeout regardless of batch size.
+      # Long-running workflows might need 300-600s, fast workflows 60-120s.
+      #
+      # @!attribute [r] max_batch_timeout_seconds
+      #   @return [Integer] Maximum timeout in seconds (default: 120)
+      attribute :max_batch_timeout_seconds, Types::Integer.default(120)
+
+      # Connection pressure response factors
+      #
+      # Configurable factors that determine how connection pressure affects
+      # concurrency recommendations. Higher values are more aggressive,
+      # lower values are more conservative.
+      #
+      # @!attribute [r] connection_pressure_factors
+      #   @return [Hash] Pressure response factors by pressure level
+      attribute :connection_pressure_factors, Types::Hash.default(proc {
+        {
+          low: 0.8,      # Use 80% of available when pressure is low
+          moderate: 0.6, # Use 60% of available when pressure is moderate
+          high: 0.4,     # Use 40% of available when pressure is high
+          critical: 0.2  # Use 20% of available when pressure is critical
+        }
+      }.freeze)
+
+      # Health assessment cache duration
+      #
+      # How long to cache connection health assessments before recalculating.
+      # Frequent assessments provide better responsiveness but add overhead.
+      #
+      # @!attribute [r] health_assessment_cache_duration
+      #   @return [Integer] Cache duration in seconds (default: 30)
+      attribute :health_assessment_cache_duration, Types::Integer.default(30)
+
+      # Connection health log level
+      #
+      # Log level for connection health assessment messages.
+      # Production systems typically use 'info' or 'warn'.
+      #
+      # @!attribute [r] connection_health_log_level
+      #   @return [String] Log level (default: 'debug')
+      attribute :connection_health_log_level, Types::String.default('debug')
+
+      # ====================
+      # ARCHITECTURAL CONSTANTS
+      # ====================
+      # These are carefully chosen based on Ruby/Rails characteristics
+      # and should NOT be exposed as configuration options
+
+      # Future cleanup wait time
+      #
+      # Time to wait for executing futures during cleanup.
+      # Based on Ruby Concurrent::Future characteristics - 1 second is optimal
+      # for most Ruby applications and provides good balance of responsiveness
+      # vs resource cleanup.
+      #
+      # @return [Integer] Wait time in seconds
+      def future_cleanup_wait_seconds
+        1
+      end
+
+      # GC trigger batch size threshold
+      #
+      # Batch size that triggers intelligent garbage collection.
+      # Based on Ruby memory management patterns - 6 concurrent operations
+      # is typically where memory pressure becomes noticeable in Ruby.
+      #
+      # @return [Integer] Batch size threshold
+      def gc_trigger_batch_size_threshold
+        6
+      end
+
+      # GC trigger duration threshold
+      #
+      # Batch duration that triggers intelligent garbage collection.
+      # Based on Ruby GC timing characteristics - 30 seconds is typically
+      # when Ruby benefits from explicit GC triggering.
+      #
+      # @return [Integer] Duration threshold in seconds
+      def gc_trigger_duration_threshold
+        30
+      end
+
+      # ====================
+      # CALCULATED VALUES
+      # ====================
+
+      # Calculate batch timeout for a given batch size
+      #
+      # @param batch_size [Integer] Number of steps in the batch
+      # @return [Integer] Calculated timeout in seconds
+      def calculate_batch_timeout(batch_size)
+        calculated_timeout = batch_timeout_base_seconds + (batch_size * batch_timeout_per_step_seconds)
+        [calculated_timeout, max_batch_timeout_seconds].min
+      end
+
+      # Check if batch should trigger garbage collection
+      #
+      # @param batch_size [Integer] Size of the batch
+      # @param batch_duration [Float] Duration of batch execution in seconds
+      # @return [Boolean] Whether to trigger GC
+      def should_trigger_gc?(batch_size, batch_duration)
+        batch_size >= gc_trigger_batch_size_threshold ||
+          batch_duration >= gc_trigger_duration_threshold
+      end
+
+      # Validate concurrency bounds
+      #
+      # Ensures min <= max and both are positive
+      # @return [Array<String>] Validation errors (empty if valid)
+      def validate_concurrency_bounds
+        errors = []
+
+        errors << "min_concurrent_steps must be positive (got: #{min_concurrent_steps})" if min_concurrent_steps <= 0
+
+        if max_concurrent_steps_limit <= 0
+          errors << "max_concurrent_steps_limit must be positive (got: #{max_concurrent_steps_limit})"
+        end
+
+        if min_concurrent_steps > max_concurrent_steps_limit
+          errors << "min_concurrent_steps (#{min_concurrent_steps}) cannot exceed " \
+                    "max_concurrent_steps_limit (#{max_concurrent_steps_limit})"
+        end
+
+        errors
+      end
+
+      # Validate timeout configuration
+      #
+      # Ensures timeouts are positive and logical
+      # @return [Array<String>] Validation errors (empty if valid)
+      def validate_timeout_configuration
+        errors = []
+
+        if batch_timeout_base_seconds <= 0
+          errors << "batch_timeout_base_seconds must be positive (got: #{batch_timeout_base_seconds})"
+        end
+
+        if batch_timeout_per_step_seconds <= 0
+          errors << "batch_timeout_per_step_seconds must be positive (got: #{batch_timeout_per_step_seconds})"
+        end
+
+        if max_batch_timeout_seconds <= batch_timeout_base_seconds
+          errors << "max_batch_timeout_seconds (#{max_batch_timeout_seconds}) must be greater than " \
+                    "batch_timeout_base_seconds (#{batch_timeout_base_seconds})"
+        end
+
+        errors
+      end
+
+      # Validate connection configuration
+      #
+      # Ensures connection pressure factors and health settings are valid
+      # @return [Array<String>] Validation errors (empty if valid)
+      def validate_connection_configuration
+        errors = []
+
+        if health_assessment_cache_duration <= 0
+          errors << "health_assessment_cache_duration must be positive (got: #{health_assessment_cache_duration})"
+        end
+
+        # Validate connection pressure factors
+        required_pressure_levels = %i[low moderate high critical]
+        missing_levels = required_pressure_levels - connection_pressure_factors.keys
+        unless missing_levels.empty?
+          errors << "connection_pressure_factors missing required levels: #{missing_levels.join(', ')}"
+        end
+
+        connection_pressure_factors.each do |level, factor|
+          unless factor.is_a?(Numeric) && factor >= 0.0 && factor <= 1.0
+            errors << "connection_pressure_factors[#{level}] must be between 0.0 and 1.0 (got: #{factor})"
+          end
+        end
+
+        # Validate log level
+        valid_log_levels = %w[debug info warn error fatal]
+        unless valid_log_levels.include?(connection_health_log_level)
+          errors << "connection_health_log_level must be one of: #{valid_log_levels.join(', ')} " \
+                    "(got: #{connection_health_log_level})"
+        end
+
+        errors
+      end
+
+      # Comprehensive validation
+      #
+      # @return [Boolean] True if valid, raises exception if invalid
+      # @raise [Dry::Struct::Error] If validation fails
+      # rubocop:disable Naming/PredicateMethod
+      def validate!
+        errors = validate_concurrency_bounds + validate_timeout_configuration + validate_connection_configuration
+
+        raise Dry::Struct::Error, "ExecutionConfig validation failed: #{errors.join(', ')}" unless errors.empty?
+
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+    end
+  end
+end

data/lib/tasker/types/health_config.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Types
+    # Configuration type for health check settings
+    #
+    # This configuration handles health check endpoint behavior and authentication requirements.
+    # It provides the same functionality as the original HealthConfiguration but with
+    # dry-struct type safety and immutability.
+    #
+    # @example Basic usage
+    #   config = HealthConfig.new(
+    #     status_requires_authentication: false,
+    #     readiness_timeout_seconds: 10.0
+    #   )
+    #
+    # @example Full configuration
+    #   config = HealthConfig.new(
+    #     status_endpoint_requires_auth: true,
+    #     ready_requires_authentication: false,
+    #     status_requires_authentication: true,
+    #     readiness_timeout_seconds: 5.0,
+    #     cache_duration_seconds: 15
+    #   )
+    class HealthConfig < BaseConfig
+      transform_keys(&:to_sym)
+
+      # Custom boolean type that accepts various truthy/falsy values
+      BooleanType = Types::Bool.constructor do |value|
+        case value
+        when true, 'true', 'yes', '1', 1
+          true
+        when false, 'false', 'no', '0', 0, nil, ''
+          false
+        else
+          !value.nil? # Convert any other truthy value to true, falsy to false
+        end
+      end
+
+      # Whether status endpoint requires authentication (backward compatibility)
+      #
+      # @!attribute [r] status_endpoint_requires_auth
+      #   @return [Boolean] Whether status endpoint requires auth
+      attribute :status_endpoint_requires_auth, BooleanType.default(true)
+
+      # Whether ready endpoint requires authentication (K8s compatibility)
+      #
+      # @!attribute [r] ready_requires_authentication
+      #   @return [Boolean] Whether ready endpoint requires authentication
+      attribute :ready_requires_authentication, BooleanType.default(false)
+
+      # Whether status endpoint requires authentication
+      #
+      # @!attribute [r] status_requires_authentication
+      #   @return [Boolean] Whether status endpoint requires authentication
+      attribute :status_requires_authentication, BooleanType.default(true)
+
+      # Timeout for readiness checks in seconds
+      #
+      # @!attribute [r] readiness_timeout_seconds
+      #   @return [Float] Readiness check timeout in seconds
+      attribute :readiness_timeout_seconds, Types::Float.constrained(gt: 0).default(5.0)
+
+      # Cache duration for status data in seconds
+      #
+      # @!attribute [r] cache_duration_seconds
+      #   @return [Integer] Cache duration in seconds
+      attribute :cache_duration_seconds, Types::Integer.constrained(gt: 0).default(15)
+
+      # Validate health configuration settings
+      #
+      # This method maintains compatibility with the original HealthConfiguration
+      # but is largely redundant since dry-struct handles validation automatically.
+      #
+      # @return [true] if valid
+      # @raise [StandardError] if invalid configuration found
+      def validate!
+        # dry-struct automatically validates types and constraints
+        # This method is kept for backward compatibility
+        true
+      end
+    end
+  end
+end

data/lib/tasker/types/step_sequence.rb

@@ -0,0 +1,24 @@
+# typed: false
+# frozen_string_literal: true
+
+module Tasker
+  module Types
+    # StepSequence represents a sequence of workflow steps to be executed.
+    #
+    # It provides a container for an array of WorkflowStep instances and
+    # utility methods for working with the step sequence.
+    class StepSequence < Dry::Struct
+      # @!attribute [r] steps
+      #   @return [Array<Tasker::WorkflowStep>] List of workflow steps in this sequence
+      attribute :steps, Types::Array.default([].freeze)
+
+      # Finds a step in the sequence by its name
+      #
+      # @param name [String] The name of the step to find
+      # @return [Tasker::WorkflowStep, nil] The matching step or nil if not found
+      def find_step_by_name(name)
+        Tasker::WorkflowStep.find_step_by_name(steps, name)
+      end
+    end
+  end
+end

data/lib/tasker/types/step_template.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Types
+    # StepTemplate defines the structure for workflow step templates
+    #
+    # A step template provides the blueprint for creating specific workflow steps
+    # in a task's sequence. It defines the behavior, dependencies, and configuration
+    # for steps of a particular type.
+    class StepTemplate < Dry::Struct
+      # @!attribute [r] dependent_system
+      #   @return [String] The system that this step depends on for execution
+      attribute :dependent_system, Types::Strict::String
+
+      # @!attribute [r] name
+      #   @return [String] The name identifier for this step template
+      attribute :name, Types::Strict::String
+
+      # @!attribute [r] description
+      #   @return [String] A human-readable description of what this step does
+      attribute :description, Types::String
+
+      # @!attribute [r] default_retryable
+      #   @return [Boolean] Whether this step can be retried by default
+      attribute :default_retryable, Types::Bool.default(true)
+
+      # @!attribute [r] default_retry_limit
+      #   @return [Integer] The default maximum number of retry attempts
+      attribute :default_retry_limit, Types::Integer.default(3)
+
+      # @!attribute [r] skippable
+      #   @return [Boolean] Whether this step can be skipped in the workflow
+      attribute :skippable, Types::Bool.default(false)
+
+      # @!attribute [r] handler_class
+      #   @return [Class] The class that implements the step's logic
+      attribute :handler_class, Types::Class
+
+      # @!attribute [r] handler_config
+      #   @return [Object, nil] Optional configuration for the step handler
+      attribute :handler_config, Types::Any.optional.default(nil)
+
+      # @!attribute [r] depends_on_step
+      #   @return [String, nil] Optional name of a step that must be completed before this one
+      attribute :depends_on_step, Types::String.optional.default(nil)
+
+      # @!attribute [r] depends_on_steps
+      #   @return [Array<String>] Names of steps that must be completed before this one
+      attribute :depends_on_steps, Types.Array(Types::String).default([].freeze)
+
+      # @!attribute [r] custom_events
+      #   @return [Array<Hash>] Custom events that this step handler can publish
+      attribute :custom_events, Types.Array(Types::Hash).optional.default([].freeze)
+
+      # Returns all dependency step names as a single array
+      #
+      # @return [Array<String>] All step dependencies
+      def all_dependencies
+        [depends_on_step, *depends_on_steps].compact.uniq
+      end
+    end
+  end
+end

data/lib/tasker/types/task_request.rb

@@ -0,0 +1,60 @@
+# typed: false
+# frozen_string_literal: true
+
+module Tasker
+  module Types
+    # TaskRequest represents a request to perform a task within the system
+    #
+    # It contains all the necessary information to identify, track, and execute a task
+    # including context data, metadata, and configuration for the task execution.
+    class TaskRequest < Dry::Struct
+      # @!attribute [r] name
+      #   @return [String] The name of the task to be performed
+      attribute :name, Types::Strict::String
+
+      # @!attribute [r] namespace
+      #   @return [String] The namespace of the task to be performed
+      attribute :namespace, Types::Strict::String.default('default')
+
+      # @!attribute [r] version
+      #   @return [String] The version of the task to be performed
+      attribute :version, Types::Strict::String.default('0.1.0')
+
+      # @!attribute [r] context
+      #   @return [Hash] Context data required for task execution, containing task-specific information
+      attribute :context, Types::Hash
+
+      # @!attribute [r] status
+      #   @return [String] Current status of the task (e.g., PENDING, IN_PROGRESS, COMPLETED, FAILED)
+      attribute :status, Types::String.default(Constants::TaskStatuses::PENDING)
+
+      # @!attribute [r] initiator
+      #   @return [String] The entity or system that initiated this task request
+      attribute :initiator, Types::String.default(Constants::UNKNOWN)
+
+      # @!attribute [r] source_system
+      #   @return [String] The system from which this task originated
+      attribute :source_system, Types::String.default(Constants::UNKNOWN)
+
+      # @!attribute [r] reason
+      #   @return [String] The reason why this task was requested
+      attribute :reason, Types::String.default(Constants::UNKNOWN)
+
+      # @!attribute [r] complete
+      #   @return [Boolean] Indicates whether the task has been completed
+      attribute :complete, Types::Bool.default(false)
+
+      # @!attribute [r] tags
+      #   @return [Array<String>] Tags associated with this task for categorization or filtering
+      attribute :tags, Types::Array.of(Types::String).default([].freeze)
+
+      # @!attribute [r] bypass_steps
+      #   @return [Array<String>] List of step names that should be bypassed during task execution
+      attribute :bypass_steps, Types::Array.of(Types::String).default([].freeze)
+
+      # @!attribute [r] requested_at
+      #   @return [Time] Timestamp when the task was initially requested
+      attribute(:requested_at, Types::JSON::Time.default { Time.zone.now })
+    end
+  end
+end