tasker-engine 1.0.0

data/lib/tasker/telemetry/trace_backend.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'concurrent-ruby'
+require 'singleton'
+
+module Tasker
+  module Telemetry
+    # TraceBackend provides thread-safe trace event collection and routing
+    #
+    # This class implements Tasker's core tracing system with thread-safe operations,
+    # automatic EventRouter integration, and support for distributed tracing backends
+    # like Jaeger, Zipkin, or OpenTelemetry.
+    #
+    # The backend follows the same singleton pattern as MetricsBackend for consistency
+    # and provides structured trace data collection with span hierarchy support.
+    #
+    # @example Basic usage
+    #   backend = TraceBackend.instance
+    #   backend.start_span('task.execution', { task_id: '123' })
+    #   backend.finish_span('task.execution', { status: 'success' })
+    #
+    # @example EventRouter integration
+    #   # Automatic trace collection based on event routing
+    #   backend.handle_event('task.started', { task_id: '123', context: { user_id: 456 } })
+    #
+    class TraceBackend
+      include Singleton
+
+      # Core trace storage for active spans
+      # Using ConcurrentHash for thread-safe operations without locks
+      # @return [Concurrent::Hash] Thread-safe trace storage
+      attr_reader :traces
+
+      # Backend creation timestamp for monitoring
+      # @return [Time] When this backend was initialized
+      attr_reader :created_at
+
+      def initialize
+        @traces = Concurrent::Hash.new
+        @created_at = Time.current
+        @instance_id = Socket.gethostname
+      end
+
+      # Handle an event from EventRouter and collect appropriate trace data
+      #
+      # This method is called by EventRouter when an event should be routed to
+      # the trace backend. It automatically creates trace spans based on event
+      # type and payload.
+      #
+      # @param event_name [String] The lifecycle event name
+      # @param payload [Hash] Event payload with trace data
+      # @return [Boolean] True if trace data was collected successfully
+      #
+      # @example Automatic usage via EventRouter
+      #   # EventRouter calls this automatically:
+      #   backend.handle_event('task.started', {
+      #     task_id: '123',
+      #     operation: 'process_payment',
+      #     context: { user_id: 456, session_id: 'abc' }
+      #   })
+      #
+      def handle_event(event_name, payload = {})
+        return false unless payload.is_a?(Hash)
+
+        trace_data = {
+          event_name: event_name,
+          timestamp: Time.current.iso8601,
+          payload: payload,
+          instance_id: @instance_id
+        }
+
+        case event_name
+        when /\.started$/
+          handle_start_event(trace_data)
+        when /\.completed$/, /\.failed$/
+          handle_finish_event(trace_data)
+        when /\.before_/, /\.after_/
+          handle_span_event(trace_data)
+        else
+          handle_generic_event(trace_data)
+        end
+
+        true
+      rescue StandardError => e
+        # Log error but don't raise to prevent breaking the event flow
+        Rails.logger&.error("TraceBackend error handling #{event_name}: #{e.message}")
+        false
+      end
+
+      # Export all collected trace data
+      #
+      # @return [Hash] All trace data with metadata
+      def export
+        {
+          traces: @traces.transform_values(&:dup),
+          metadata: {
+            backend: 'trace',
+            instance_id: @instance_id,
+            created_at: @created_at.iso8601,
+            exported_at: Time.current.iso8601,
+            trace_count: @traces.size
+          }
+        }
+      end
+
+      # Clear all trace data (primarily for testing)
+      #
+      # @return [void]
+      def reset!
+        @traces.clear
+      end
+
+      # Get trace statistics
+      #
+      # @return [Hash] Statistics about collected traces
+      def stats
+        {
+          active_traces: @traces.size,
+          backend_uptime: Time.current - @created_at,
+          instance_id: @instance_id
+        }
+      end
+
+      private
+
+      def handle_start_event(trace_data)
+        trace_key = extract_trace_key(trace_data[:payload])
+        @traces[trace_key] = {
+          start_time: trace_data[:timestamp],
+          event_name: trace_data[:event_name],
+          payload: trace_data[:payload],
+          spans: []
+        }
+      end
+
+      def handle_finish_event(trace_data)
+        trace_key = extract_trace_key(trace_data[:payload])
+        if (trace = @traces[trace_key])
+          trace[:end_time] = trace_data[:timestamp]
+          trace[:duration] = calculate_duration(trace[:start_time], trace_data[:timestamp])
+          trace[:status] = trace_data[:event_name].include?('failed') ? 'error' : 'success'
+        end
+      end
+
+      def handle_span_event(trace_data)
+        trace_key = extract_trace_key(trace_data[:payload])
+        if (trace = @traces[trace_key])
+          trace[:spans] << {
+            timestamp: trace_data[:timestamp],
+            event_name: trace_data[:event_name],
+            payload: trace_data[:payload]
+          }
+        end
+      end
+
+      def handle_generic_event(trace_data)
+        # Store generic events in a special traces collection
+        @traces["generic_#{Time.current.to_f}"] = {
+          timestamp: trace_data[:timestamp],
+          event_name: trace_data[:event_name],
+          payload: trace_data[:payload],
+          type: 'generic'
+        }
+      end
+
+      def extract_trace_key(payload)
+        # Create a trace key from task_id, workflow_step_id, or other identifiers
+        return "task_#{payload[:task_id]}" if payload[:task_id]
+        return "step_#{payload[:workflow_step_id]}" if payload[:workflow_step_id]
+        return "operation_#{payload[:operation]}" if payload[:operation]
+
+        "trace_#{Time.current.to_f}"
+      end
+
+      def calculate_duration(start_time, end_time)
+        return nil unless start_time && end_time
+
+        start_parsed = Time.zone.parse(start_time)
+        end_parsed = Time.zone.parse(end_time)
+        (end_parsed - start_parsed).round(6)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/tasker/telemetry.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Tasker::Telemetry namespace for intelligent event-driven telemetry routing
+#
+# This module provides the strategic evolution of Tasker's telemetry architecture,
+# transforming the existing solid TelemetrySubscriber foundation into a comprehensive,
+# event-driven observability system that leverages our robust 40+ event pub/sub model.
+#
+# Components:
+# - EventRouter: Intelligent routing core for event→telemetry mapping
+# - EventMapping: Declarative configuration for routing decisions
+# - MetricTypes: Counter, Gauge, Histogram with atomic thread-safe operations
+# - MetricsBackend: Thread-safe native metrics collection with EventRouter integration
+# - SubscriberEnhancer: Evolution wrapper for existing TelemetrySubscriber (Phase 4.2.3)
+#
+# Core Philosophy: PRESERVE all existing TelemetrySubscriber functionality while
+# dramatically expanding observability through intelligent event routing.
+#
+# Usage:
+#   # Configure intelligent event routing
+#   Tasker::Telemetry::EventRouter.configure do |router|
+#     router.map 'task.completed' => [:trace, :metrics]
+#     router.map 'workflow.viable_steps_discovered' => [:trace, :metrics]
+#     router.map 'observability.task.enqueue' => [:metrics]
+#   end
+#
+#   # Direct metrics collection with thread-safe operations
+#   backend = Tasker::Telemetry::MetricsBackend.instance
+#   backend.counter('api_requests_total', endpoint: '/tasks').increment
+#   backend.gauge('active_connections').set(42)
+#   backend.histogram('request_duration_seconds').observe(0.125)
+#
+#   # Automatic event-driven metrics via EventRouter integration
+#   router.route_event('task.completed', { task_id: '123', duration: 2.5 })
+#
+#   # Evolution of existing TelemetrySubscriber (zero breaking changes)
+#   enhanced_subscriber = Tasker::Telemetry::SubscriberEnhancer.new  # Phase 4.2.3
+#   enhanced_subscriber.subscribe_to_publisher(publisher)
+
+# Explicitly require telemetry components for predictable loading
+require_relative 'telemetry/metric_types'
+require_relative 'telemetry/event_mapping'
+require_relative 'telemetry/event_router'
+require_relative 'telemetry/metrics_backend'
+require_relative 'telemetry/trace_backend'
+require_relative 'telemetry/log_backend'
+require_relative 'telemetry/prometheus_exporter'
+require_relative 'telemetry/export_coordinator'
+require_relative 'telemetry/plugin_registry'
+
+# Require the MetricsSubscriber for automatic event-to-metrics bridging
+require_relative 'events/subscribers/metrics_subscriber'
+
+module Tasker
+  module Telemetry
+    # All telemetry components are now explicitly loaded above
+    # This provides predictable loading order and avoids autoload complexity
+  end
+end

data/lib/tasker/types/auth_config.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Types
+    # Configuration type for authentication and authorization settings
+    #
+    # This configuration handles all authentication and authorization settings for Tasker.
+    # It provides the same functionality as the original AuthConfiguration but with
+    # dry-struct type safety and immutability.
+    #
+    # @example Basic authentication setup
+    #   config = AuthConfig.new(
+    #     authentication_enabled: true,
+    #     authenticator_class: 'MyAuthenticator',
+    #     strategy: :custom
+    #   )
+    #
+    # @example Full configuration
+    #   config = AuthConfig.new(
+    #     authentication_enabled: true,
+    #     authenticator_class: 'JwtAuthenticator',
+    #     current_user_method: :current_user,
+    #     authenticate_user_method: :authenticate_user!,
+    #     authorization_enabled: true,
+    #     authorization_coordinator_class: 'MyAuthorizationCoordinator',
+    #     user_class: 'User',
+    #     strategy: :custom
+    #   )
+    class AuthConfig < BaseConfig
+      transform_keys(&:to_sym)
+
+      # Whether authentication is enabled
+      #
+      # @!attribute [r] authentication_enabled
+      #   @return [Boolean] Whether authentication is enabled
+      attribute :authentication_enabled, Types::Bool.default(false)
+
+      # Class name for the authenticator (nil means no authentication)
+      #
+      # @!attribute [r] authenticator_class
+      #   @return [String, nil] Class name for the authenticator
+      attribute? :authenticator_class, Types::String.optional.default(nil)
+
+      # Method name to get the current user
+      #
+      # @!attribute [r] current_user_method
+      #   @return [Symbol] Method name to get the current user
+      attribute :current_user_method, Types::Symbol.default(:current_user)
+
+      # Method name to authenticate the user
+      #
+      # @!attribute [r] authenticate_user_method
+      #   @return [Symbol] Method name to authenticate the user
+      attribute :authenticate_user_method, Types::Symbol.default(:authenticate_user!)
+
+      # Whether authorization is enabled
+      #
+      # @!attribute [r] authorization_enabled
+      #   @return [Boolean] Whether authorization is enabled
+      attribute :authorization_enabled, Types::Bool.default(false)
+
+      # Class name for the authorization coordinator
+      #
+      # @!attribute [r] authorization_coordinator_class
+      #   @return [String] Class name for the authorization coordinator
+      attribute :authorization_coordinator_class, Types::String.default('Tasker::Authorization::BaseCoordinator')
+
+      # Class name for the authorizable user class
+      #
+      # @!attribute [r] user_class
+      #   @return [String, nil] Class name for the authorizable user class
+      attribute? :user_class, Types::String.optional.default(nil)
+
+      # Authentication strategy (:none, :test, :custom, etc.)
+      #
+      # @!attribute [r] strategy
+      #   @return [Symbol] Authentication strategy
+      attribute :strategy, Types::Symbol.default(:none)
+    end
+  end
+end

data/lib/tasker/types/backoff_config.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Types
+    # Configuration type for retry backoff calculation settings
+    #
+    # This configuration exposes previously hardcoded backoff timing constants
+    # used in retry logic and exponential backoff calculations.
+    #
+    # @example Basic usage
+    #   config = BackoffConfig.new(
+    #     max_backoff_seconds: 120
+    #   )
+    #
+    # @example With custom backoff progression
+    #   config = BackoffConfig.new(
+    #     default_backoff_seconds: [1, 2, 5, 10, 20, 60],
+    #     max_backoff_seconds: 300,
+    #     backoff_multiplier: 2.5,
+    #     jitter_enabled: true,
+    #     jitter_max_percentage: 0.15
+    #   )
+    class BackoffConfig < BaseConfig
+      transform_keys(&:to_sym)
+
+      # Default backoff progression in seconds
+      #
+      # This array defines the backoff progression for retries.
+      # Each element represents the backoff time for that attempt number.
+      # If more attempts are made than elements in this array,
+      # the exponential backoff calculation takes over.
+      #
+      # @!attribute [r] default_backoff_seconds
+      #   @return [Array<Integer>] Backoff progression in seconds
+      attribute :default_backoff_seconds, Types::Array.of(Types::Integer)
+                                                      .default([1, 2, 4, 8, 16, 32].freeze)
+
+      # Maximum backoff time in seconds
+      #
+      # This value caps the exponential backoff calculation to prevent
+      # excessively long delays between retry attempts.
+      #
+      # @!attribute [r] max_backoff_seconds
+      #   @return [Integer] Maximum backoff time in seconds
+      attribute :max_backoff_seconds, Types::Integer.default(300)
+
+      # Multiplier for exponential backoff calculation
+      #
+      # This value is used in the exponential backoff formula:
+      # backoff_time = attempt_number ^ backoff_multiplier * base_seconds
+      #
+      # @!attribute [r] backoff_multiplier
+      #   @return [Float] Exponential backoff multiplier
+      attribute :backoff_multiplier, Types::Float.default(2.0)
+
+      # Whether to apply jitter to backoff calculations
+      #
+      # Jitter helps prevent the "thundering herd" problem where
+      # many failed steps retry at exactly the same time.
+      #
+      # @!attribute [r] jitter_enabled
+      #   @return [Boolean] Whether jitter is enabled
+      attribute :jitter_enabled, Types::Bool.default(true)
+
+      # Maximum jitter percentage
+      #
+      # When jitter is enabled, the actual backoff time will be
+      # randomly adjusted by up to this percentage.
+      # E.g., 0.1 means ±10% variation.
+      #
+      # @!attribute [r] jitter_max_percentage
+      #   @return [Float] Maximum jitter as a decimal percentage
+      attribute :jitter_max_percentage, Types::Float.default(0.1)
+
+      # Task reenqueue delay configuration hash
+      #
+      # This hash defines delays for different task execution states
+      # when reenqueuing tasks for further processing.
+      # Keys correspond to TaskExecution::ExecutionStatus constants.
+      #
+      # @!attribute [r] reenqueue_delays
+      #   @return [Hash] Mapping of execution status to delay seconds
+      attribute :reenqueue_delays, Types::Hash.schema(
+        has_ready_steps: Types::Integer.default { 0 },              # Steps ready - immediate processing
+        waiting_for_dependencies: Types::Integer.default { 45 },    # Waiting for deps - moderate delay
+        processing: Types::Integer.default { 10 }                   # Processing - short delay
+      ).constructor { |value|
+        value.respond_to?(:deep_symbolize_keys) ? value.deep_symbolize_keys : value
+      }.default({
+        has_ready_steps: 0,
+        waiting_for_dependencies: 45,
+        processing: 10
+      }.freeze)
+
+      # Default reenqueue delay for unclear states
+      #
+      # This value is used when the task execution status doesn't match
+      # any of the predefined states in reenqueue_delays.
+      #
+      # @!attribute [r] default_reenqueue_delay
+      #   @return [Integer] Default reenqueue delay in seconds
+      attribute :default_reenqueue_delay, Types::Integer.default(30)
+
+      # Buffer time for optimal backoff calculations
+      #
+      # This buffer is added to calculated backoff times to ensure
+      # steps are definitely ready for retry when tasks are reenqueued.
+      #
+      # @!attribute [r] buffer_seconds
+      #   @return [Integer] Buffer time in seconds
+      attribute :buffer_seconds, Types::Integer.default(5)
+
+      # Calculate backoff time for a given attempt
+      #
+      # @param attempt_number [Integer] The retry attempt number (1-based)
+      # @return [Integer] Backoff time in seconds
+      def calculate_backoff_seconds(attempt_number)
+        return 0 if attempt_number <= 0
+
+        # Use predefined progression if available
+        base_backoff = if attempt_number <= default_backoff_seconds.length
+                         default_backoff_seconds[attempt_number - 1]
+                       else
+                         # Use exponential backoff for attempts beyond predefined progression
+                         (attempt_number**backoff_multiplier).to_i
+                       end
+
+        # Apply maximum limit
+        backoff_time = [base_backoff, max_backoff_seconds].min
+
+        # Apply jitter if enabled
+        if jitter_enabled
+          jitter_range = (backoff_time * jitter_max_percentage).round
+          jitter = Random.rand(-jitter_range..jitter_range)
+          backoff_time = [backoff_time + jitter, 1].max # Ensure minimum 1 second
+        end
+
+        backoff_time
+      end
+    end
+  end
+end