tasker-engine 1.0.0

data/lib/tasker/health/status_checker.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Health
+    # StatusChecker provides comprehensive system status information
+    #
+    # Gathers detailed metrics about tasks, workflow steps, and system health.
+    # Uses Rails caching to avoid expensive database queries on frequent requests.
+    #
+    # @example Basic usage
+    #   checker = Tasker::Health::StatusChecker.new
+    #   status = checker.check
+    #   puts status[:healthy]
+    #
+    # @example Force refresh (bypass cache)
+    #   status = checker.check(force_refresh: true)
+    class StatusChecker
+      # @return [Integer] Cache duration in seconds
+      attr_reader :cache_duration
+
+      # Cache key for status data
+      CACHE_KEY = 'tasker:health:status'
+
+      # Initialize status checker
+      #
+      # @param cache_duration [Integer] Cache duration in seconds (default from config)
+      def initialize(cache_duration: nil)
+        @cache_duration = cache_duration || Tasker.configuration.health.cache_duration_seconds
+      end
+
+      # Class method for status check
+      #
+      # @return [Hash] Comprehensive status information
+      def self.status
+        new.check
+      end
+
+      # Perform comprehensive status check
+      #
+      # @param force_refresh [Boolean] Whether to bypass cache and force fresh data
+      # @return [Hash] Comprehensive status information
+      #   - :healthy [Boolean] Overall system health
+      #   - :status [String] Status description
+      #   - :data [Hash] Detailed metrics
+      #   - :cached [Boolean] Whether data came from cache
+      #   - :timestamp [Time] When data was generated
+      def check(force_refresh: false)
+        if force_refresh
+          result = generate_status_data
+          result[:cached] = false
+          result
+        else
+          begin
+            # Check if we have cached data first
+            cached_data = Rails.cache.read(CACHE_KEY)
+            if cached_data.nil?
+              # No cached data, generate fresh and cache it
+              result = generate_status_data
+              # Create a copy for caching (without the cached flag)
+              cache_data = result.dup
+              cache_data.delete(:cached)
+              Rails.cache.write(CACHE_KEY, cache_data, expires_in: @cache_duration.seconds)
+              result[:cached] = false
+            else
+              # Return cached data with cached flag set
+              result = cached_data.dup
+              result[:cached] = true
+            end
+            result
+          rescue StandardError => e
+            # If cache fails, generate fresh data
+            result = generate_status_data
+            result[:cached] = false
+            result[:cache_error] = "Cache error: #{e.message}"
+            result
+          end
+        end
+      end
+
+      private
+
+      # Generate fresh status data
+      #
+      # @return [Hash] Fresh status information
+      def generate_status_data
+        start_time = Time.current
+
+        begin
+          # Get health metrics from SQL function
+          health_data = Tasker::Functions::FunctionBasedSystemHealthCounts.call
+
+          # Determine overall health status
+          healthy = assess_system_health(health_data)
+
+          formatted_data = format_health_data(health_data)
+
+          {
+            healthy: healthy,
+            status: healthy ? 'healthy' : 'unhealthy',
+            metrics: formatted_data[:metrics],
+            database: formatted_data[:database],
+            cached: false,
+            timestamp: start_time,
+            generation_duration: Time.current - start_time
+          }
+        rescue StandardError => e
+          {
+            healthy: false,
+            status: 'error',
+            error: e.message,
+            error_class: e.class.name,
+            cached: false,
+            timestamp: start_time,
+            generation_duration: Time.current - start_time
+          }
+        end
+      end
+
+      # Assess overall system health based on metrics
+      #
+      # @param health_data [FunctionBasedSystemHealthCounts::HealthMetrics] Health metrics from SQL function
+      # @return [Boolean] Whether system is healthy
+      def assess_system_health(health_data)
+        # System is healthy if:
+        # 1. Database is responding (we got data)
+        # 2. Connection utilization is reasonable (< 90%)
+        # 3. No excessive error accumulation (< 50% error rate)
+
+        return false if health_data.nil?
+
+        # Check database connection utilization
+        if health_data.max_connections.positive?
+          connection_utilization = (health_data.active_connections.to_f / health_data.max_connections) * 100
+          return false if connection_utilization > 90.0
+        end
+
+        # Check task error rate (only if we have tasks)
+        if health_data.total_tasks.positive?
+          task_error_rate = (health_data.error_tasks.to_f / health_data.total_tasks) * 100
+          return false if task_error_rate > 50.0
+        end
+
+        # Check step error rate (only if we have steps)
+        if health_data.total_steps.positive?
+          step_error_rate = (health_data.error_steps.to_f / health_data.total_steps) * 100
+          return false if step_error_rate > 50.0
+        end
+
+        true
+      end
+
+      # Format health data for API response
+      #
+      # @param health_data [FunctionBasedSystemHealthCounts::HealthMetrics] Raw health metrics
+      # @return [Hash] Formatted health data with :metrics and :database keys
+      def format_health_data(health_data)
+        {
+          metrics: {
+            tasks: {
+              total: health_data.total_tasks,
+              pending: health_data.pending_tasks,
+              in_progress: health_data.in_progress_tasks,
+              complete: health_data.complete_tasks,
+              error: health_data.error_tasks,
+              cancelled: health_data.cancelled_tasks
+            },
+            steps: {
+              total: health_data.total_steps,
+              pending: health_data.pending_steps,
+              in_progress: health_data.in_progress_steps,
+              complete: health_data.complete_steps,
+              error: health_data.error_steps
+            },
+            retries: {
+              retryable_errors: health_data.retryable_error_steps,
+              exhausted_retries: health_data.exhausted_retry_steps,
+              in_backoff: health_data.in_backoff_steps
+            }
+          },
+          database: {
+            active_connections: health_data.active_connections,
+            max_connections: health_data.max_connections,
+            connection_utilization: calculate_utilization_percentage(
+              health_data.active_connections,
+              health_data.max_connections
+            ) # Return as percentage (e.g., 5.0 for 5%)
+          }
+        }
+      end
+
+      # Calculate connection utilization percentage
+      #
+      # @param active [Integer] Active connections
+      # @param max [Integer] Maximum connections
+      # @return [Float] Utilization percentage
+      def calculate_utilization_percentage(active, max)
+        return 0.0 if max.zero?
+
+        ((active.to_f / max) * 100).round(2)
+      end
+    end
+  end
+end

data/lib/tasker/identity_strategy.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'digest'
+
+module Tasker
+  # Base identity strategy class that generates a GUID by default
+  #
+  # Identity strategies are used to generate unique identifiers for tasks.
+  # This allows for customizing how task identity is determined and tracked.
+  class IdentityStrategy
+    # Generate a unique identity hash for a task
+    #
+    # The default implementation generates a random UUID.
+    #
+    # @param _task [Tasker::Task] The task to generate an identity for
+    # @param _task_options [Hash] Additional options for identity generation
+    # @return [String] A unique identity hash
+    def generate_identity_hash(_task, _task_options)
+      SecureRandom.uuid
+    end
+  end
+
+  # Strategy that uses SHA256 hash of task identity options
+  #
+  # This strategy is useful when you want identical tasks (with the same
+  # options/parameters) to have the same identity hash.
+  class HashIdentityStrategy < IdentityStrategy
+    # Generate a deterministic identity hash based on task options
+    #
+    # @param _task [Tasker::Task] The task to generate an identity for
+    # @param task_options [Hash] Task options to hash for identity
+    # @return [String] A SHA256 hash of the task options
+    def generate_identity_hash(_task, task_options)
+      Digest::SHA256.hexdigest(task_options.to_json)
+    end
+  end
+end

data/lib/tasker/logging/correlation_id_generator.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Logging
+    # CorrelationIdGenerator creates unique correlation IDs for distributed tracing
+    #
+    # Generates correlation IDs that are:
+    # - Unique across distributed systems
+    # - URL-safe and log-friendly
+    # - Sortable by generation time
+    # - Human-readable length
+    #
+    # Format: tsk_[timestamp_base36][random_suffix]
+    # Example: tsk_l7k9m2p4_a8x3f9
+    class CorrelationIdGenerator
+      # Prefix for all Tasker correlation IDs
+      PREFIX = 'tsk'
+
+      # Length of random suffix
+      RANDOM_SUFFIX_LENGTH = 6
+
+      class << self
+        # Generate a new correlation ID
+        #
+        # @return [String] A unique correlation ID
+        #
+        # @example
+        #   id = Tasker::Logging::CorrelationIdGenerator.generate
+        #   # => "tsk_l7k9m2p4_a8x3f9"
+        def generate
+          timestamp_part = generate_timestamp_component
+          random_part = generate_random_component
+
+          "#{PREFIX}_#{timestamp_part}_#{random_part}"
+        end
+
+        # Generate correlation ID from an existing ID (for HTTP propagation)
+        #
+        # @param existing_id [String, nil] Existing correlation ID from headers
+        # @return [String] Valid correlation ID (existing or newly generated)
+        #
+        # @example
+        #   # With existing valid ID
+        #   id = from_existing("req_abc123")
+        #   # => "req_abc123"
+        #
+        #   # With invalid/missing ID
+        #   id = from_existing(nil)
+        #   # => "tsk_l7k9m2p4_a8x3f9"
+        def from_existing(existing_id)
+          return generate if existing_id.blank?
+          return existing_id if valid_correlation_id?(existing_id)
+
+          # If existing ID is invalid, create a new one but log the attempt
+          Rails.logger.debug { "Invalid correlation ID received: #{existing_id}. Generating new ID." }
+          generate
+        end
+
+        # Extract correlation ID from HTTP headers
+        #
+        # @param headers [Hash] HTTP headers hash
+        # @param header_name [String] Header name to check (defaults to config)
+        # @return [String, nil] Correlation ID if found and valid
+        #
+        # @example
+        #   id = from_headers(request.headers)
+        #   id = from_headers(env, 'X-Request-ID')
+        def from_headers(headers, header_name = nil)
+          header_name ||= Tasker.configuration.telemetry.correlation_id_header
+
+          # Handle different header formats (rack vs rails)
+          header_value = headers[header_name] ||
+                         headers["HTTP_#{header_name.upcase.tr('-', '_')}"] ||
+                         headers[header_name.downcase]
+
+          from_existing(header_value)
+        end
+
+        # Validate if a string is a valid correlation ID format
+        #
+        # @param id [String] The ID to validate
+        # @return [Boolean] Whether the ID is valid
+        #
+        # @example
+        #   valid_correlation_id?("tsk_l7k9m2p4_a8x3f9")  # => true
+        #   valid_correlation_id?("invalid")              # => false
+        #   valid_correlation_id?("")                     # => false
+        def valid_correlation_id?(id)
+          return false if id.blank?
+          return false if id.length > 100 # Reasonable max length
+
+          # Allow various prefixes for external system compatibility
+          # But ensure it's alphanumeric with underscores/hyphens only
+          id.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_\-]*\z/)
+        end
+
+        private
+
+        # Generate timestamp component in base36 for compactness
+        #
+        # @return [String] Timestamp component
+        def generate_timestamp_component
+          # Use millisecond precision timestamp
+          timestamp_ms = (Time.current.to_f * 1000).to_i
+          timestamp_ms.to_s(36)
+        end
+
+        # Generate random component using secure random
+        #
+        # @return [String] Random component
+        def generate_random_component
+          # Use URL-safe base64 character set: A-Z, a-z, 0-9
+          chars = ('A'..'Z').to_a + ('a'..'z').to_a + ('0'..'9').to_a
+
+          Array.new(RANDOM_SUFFIX_LENGTH) { chars.sample }.join
+        end
+      end
+    end
+  end
+end

data/lib/tasker/orchestration/backoff_calculator.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require_relative '../concerns/event_publisher'
+require_relative 'retry_header_parser'
+
+module Tasker
+  module Orchestration
+    # BackoffCalculator handles all backoff logic for API retries
+    #
+    # This component provides unified handling of both server-requested backoff
+    # (via Retry-After headers) and exponential backoff calculations.
+    # It publishes appropriate events for observability.
+    class BackoffCalculator
+      include Tasker::Concerns::EventPublisher
+
+      # Initialize the backoff calculator
+      #
+      # @param config [Object] Configuration object with backoff settings
+      # @param retry_parser [RetryHeaderParser] Parser for Retry-After headers (injectable for testing)
+      def initialize(config: nil, retry_parser: RetryHeaderParser.new)
+        @config = config
+        @retry_parser = retry_parser
+      end
+
+      # Calculate and apply backoff for a step based on response context
+      #
+      # This method determines whether to use server-requested backoff or
+      # exponential backoff, calculates the appropriate delay, and updates
+      # the step with backoff information.
+      #
+      # @param step [Tasker::WorkflowStep] The step requiring backoff
+      # @param context [Hash] Response context containing headers and metadata
+      def calculate_and_apply_backoff(step, context)
+        retry_after = extract_retry_after_header(context)
+
+        if retry_after.present?
+          apply_server_requested_backoff(step, retry_after)
+        elsif backoff_enabled?
+          apply_exponential_backoff(step, context)
+        else
+          Rails.logger.warn(
+            "BackoffCalculator: No backoff strategy available for step #{step.name} (#{step.workflow_step_id})"
+          )
+        end
+      end
+
+      private
+
+      # Get backoff configuration with memoization
+      #
+      # @return [Tasker::Types::BackoffConfig] The backoff configuration
+      def backoff_config
+        @backoff_config ||= Tasker.configuration.backoff
+      end
+
+      # Extract Retry-After header from response context
+      #
+      # @param context [Hash] Response context
+      # @return [String, nil] Retry-After header value if present
+      def extract_retry_after_header(context)
+        headers = context[:headers] || {}
+        headers['Retry-After'] || headers['retry-after']
+      end
+
+      # Apply server-requested backoff using Retry-After header
+      #
+      # @param step [Tasker::WorkflowStep] The step to apply backoff to
+      # @param retry_after [String] The Retry-After header value
+      def apply_server_requested_backoff(step, retry_after)
+        backoff_seconds = @retry_parser.parse_retry_after(retry_after)
+
+        # Apply configurable cap for server-requested backoff
+        max_server_backoff = backoff_config.max_backoff_seconds
+        backoff_seconds = [backoff_seconds, max_server_backoff].min
+
+        # Update step with backoff information
+        step.backoff_request_seconds = backoff_seconds
+
+        # Publish backoff event for observability
+        publish_step_backoff(
+          step,
+          backoff_seconds: backoff_seconds,
+          backoff_type: 'server_requested',
+          retry_after: retry_after
+        )
+
+        Rails.logger.info(
+          "BackoffCalculator: Applied server-requested backoff of #{backoff_seconds} seconds " \
+          "for step #{step.name} (#{step.workflow_step_id})"
+        )
+      end
+
+      # Apply exponential backoff calculation
+      #
+      # @param step [Tasker::WorkflowStep] The step to apply backoff to
+      # @param context [Hash] Response context for event publishing
+      def apply_exponential_backoff(step, context)
+        # Ensure attempts is properly initialized
+        step.attempts ||= 0
+
+        # Convert 0-based attempts to 1-based for backoff calculation
+        # (step.attempts = 0 means first attempt, should get backoff[0])
+        attempt_for_calculation = step.attempts + 1
+        backoff_seconds = calculate_exponential_delay(attempt_for_calculation)
+
+        # Update step with backoff information
+        step.backoff_request_seconds = backoff_seconds
+        step.last_attempted_at = Time.zone.now
+
+        # Publish backoff event for observability
+        publish_exponential_backoff_event(step, backoff_seconds, context, attempt_for_calculation)
+
+        Rails.logger.info(
+          "BackoffCalculator: Applied exponential backoff of #{backoff_seconds} seconds " \
+          "for step #{step.name} (#{step.workflow_step_id}), attempt #{step.attempts}"
+        )
+      end
+
+      # Calculate exponential delay with jitter
+      #
+      # @param attempt_number [Integer] The 1-based attempt number
+      # @return [Float] Calculated backoff delay in seconds
+      def calculate_exponential_delay(attempt_number)
+        # Use BackoffConfig's calculate_backoff_seconds method
+        backoff_seconds = backoff_config.calculate_backoff_seconds(attempt_number)
+
+        # Ensure minimum delay of at least half the first backoff value
+        min_delay = backoff_config.default_backoff_seconds.first * 0.5
+        [backoff_seconds, min_delay].max
+      end
+
+      # Publish exponential backoff event with detailed information
+      #
+      # @param step [Tasker::WorkflowStep] The step being backed off
+      # @param backoff_seconds [Float] Calculated backoff delay
+      # @param context [Hash] Response context
+      # @param attempt_number [Integer] The 1-based attempt number
+      def publish_exponential_backoff_event(step, backoff_seconds, _context, attempt_number)
+        publish_step_backoff(
+          step,
+          backoff_seconds: backoff_seconds,
+          backoff_type: 'exponential',
+          attempt: step.attempts,
+          calculated_attempt: attempt_number,
+          base_delay: backoff_config.default_backoff_seconds.first,
+          multiplier: backoff_config.backoff_multiplier,
+          jitter_enabled: backoff_config.jitter_enabled,
+          jitter_max_percentage: backoff_config.jitter_max_percentage
+        )
+      end
+
+      # Check if exponential backoff is enabled
+      #
+      # @return [Boolean] True if exponential backoff should be used
+      def backoff_enabled?
+        return true unless @config # Default to enabled if no config
+
+        if @config.respond_to?(:enable_exponential_backoff)
+          @config.enable_exponential_backoff
+        else
+          true
+        end
+      end
+
+      # Get retry delay from configuration
+      #
+      # @return [Float] Base retry delay in seconds
+      def retry_delay
+        return backoff_config.default_backoff_seconds.first.to_f unless @config.respond_to?(:retry_delay)
+
+        @config.retry_delay || backoff_config.default_backoff_seconds.first.to_f
+      end
+
+      # Get jitter factor from configuration
+      #
+      # @return [Float] Jitter factor for randomness (0.0-1.0)
+      def jitter_factor_value
+        return rand unless @config.respond_to?(:jitter_factor)
+
+        @config.jitter_factor || rand
+      end
+    end
+  end
+end

data/lib/tasker/orchestration/connection_builder.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module Tasker
+  module Orchestration
+    # ConnectionBuilder handles Faraday connection configuration and building
+    #
+    # This component provides focused responsibility for building and configuring
+    # Faraday connections based on API handler configuration, with support for
+    # custom connection block configuration.
+    class ConnectionBuilder
+      # Build a Faraday connection from configuration
+      #
+      # @param config [Object] Configuration object with connection settings
+      # @yield [Faraday::Connection] Optional block for custom connection configuration
+      # @return [Faraday::Connection] Configured Faraday connection
+      def build_connection(config, &connection_block)
+        validate_config(config)
+
+        Rails.logger.debug do
+          "ConnectionBuilder: Building connection to #{config.url} " \
+            "with #{config.params.keys.size} params and #{config.headers.keys.size} headers"
+        end
+
+        connection = Faraday.new(
+          url: config.url,
+          params: config.params || {},
+          headers: config.headers || {},
+          ssl: config.ssl
+        )
+
+        # Apply custom configuration block if provided
+        if connection_block
+          Rails.logger.debug('ConnectionBuilder: Applying custom connection configuration')
+          yield(connection)
+        end
+
+        connection
+      rescue StandardError => e
+        Rails.logger.error(
+          "ConnectionBuilder: Failed to build connection to #{config&.url}: #{e.message}"
+        )
+        raise
+      end
+
+      # Validate configuration has required fields
+      #
+      # @param config [Object] Configuration to validate
+      # @raise [ArgumentError] If configuration is invalid
+      def validate_config(config)
+        ConfigValidator.validate(config)
+      end
+
+      # Service class to validate connection configuration
+      # Reduces complexity by organizing validation logic
+      class ConfigValidator
+        class << self
+          # Validate configuration object
+          #
+          # @param config [Object] Configuration to validate
+          # @raise [ArgumentError] If configuration is invalid
+          def validate(config)
+            validate_config_presence(config)
+            validate_config_interface(config)
+            validate_url_presence(config)
+            validate_url_format(config)
+          end
+
+          private
+
+          # Validate configuration is present
+          #
+          # @param config [Object] Configuration to validate
+          # @raise [ArgumentError] If configuration is nil
+          def validate_config_presence(config)
+            raise ArgumentError, 'Configuration cannot be nil' if config.nil?
+          end
+
+          # Validate configuration has required interface
+          #
+          # @param config [Object] Configuration to validate
+          # @raise [ArgumentError] If configuration doesn't respond to :url
+          def validate_config_interface(config)
+            raise ArgumentError, 'Configuration must respond to :url' unless config.respond_to?(:url)
+          end
+
+          # Validate URL is present and non-empty
+          #
+          # @param config [Object] Configuration to validate
+          # @raise [ArgumentError] If URL is nil or empty
+          def validate_url_presence(config)
+            return unless config.url.nil? || config.url.strip.empty?
+
+            raise ArgumentError, 'Configuration URL cannot be nil or empty'
+          end
+
+          # Validate URL format using URI parsing
+          #
+          # @param config [Object] Configuration to validate
+          # @raise [ArgumentError] If URL format is invalid
+          def validate_url_format(config)
+            uri = URI.parse(config.url)
+            validate_uri_components(uri)
+          rescue URI::InvalidURIError => e
+            raise ArgumentError, "Configuration URL is not a valid URI: #{e.message}"
+          end
+
+          # Validate URI has required components
+          #
+          # @param uri [URI] Parsed URI to validate
+          # @raise [ArgumentError] If URI lacks scheme or host
+          def validate_uri_components(uri)
+            return if uri.scheme && uri.host
+
+            raise ArgumentError, 'Configuration URL must be a valid URI with scheme and host'
+          end
+        end
+      end
+    end
+  end
+end