tasker-rb 0.1.3-x86_64-linux

data/lib/tasker_core/logger.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require 'singleton'
+require 'json'
+
+module TaskerCore
+  # DEPRECATED: Legacy logger wrapper that delegates to TaskerCore::Tracing
+  #
+  # This class is maintained for backward compatibility but all new code should
+  # use TaskerCore::Tracing directly for unified structured logging via FFI.
+  #
+  # TAS-29 Phase 6: This logger now delegates to the Rust tracing infrastructure
+  # through the FFI bridge, providing unified structured logging across Ruby and Rust.
+  #
+  # Migration Guide:
+  #   # Old:
+  #   logger = TaskerCore::Logger.instance
+  #   logger.info("Message")
+  #
+  #   # New:
+  #   TaskerCore::Tracing.info("Message", { operation: "example" })
+  #
+  # The logger supports two logging approaches:
+  # 1. **Traditional Logging**: Simple string messages (delegates to Tracing)
+  # 2. **Structured Logging**: Component-based logging (converts to Tracing fields)
+  #
+  # Structured logs include:
+  # - Emoji prefix for visual identification
+  # - Component label for categorization
+  # - Operation description
+  # - Structured metadata as JSON
+  # - ISO 8601 timestamps
+  #
+  # @example Traditional logging (backward compatibility)
+  #   logger = TaskerCore::Logger.instance
+  #   logger.info "Worker started successfully"
+  #   logger.error "Failed to process step: #{error.message}"
+  #   logger.debug "Processing step #{step_uuid}"
+  #
+  # @example Structured logging with component context
+  #   logger.log_task(:info, "initialization",
+  #     task_uuid: "550e8400-e29b-41d4-a716-446655440000",
+  #     namespace: "payments",
+  #     step_count: 4,
+  #     priority: "high"
+  #   )
+  #   # Output: [2025-10-02 12:00:00] INFO TaskerCore: 📋 TASK_OPERATION: initialization | {"task_uuid":"...","namespace":"payments",...}
+  #
+  # @example Queue worker logging
+  #   logger.log_queue_worker(:debug, "claiming_step",
+  #     namespace: "payments",
+  #     step_uuid: "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+  #     retry_count: 2,
+  #     queue_depth: 15
+  #   )
+  #   # Output: [2025-10-02 12:00:01] DEBUG TaskerCore: 🔄 QUEUE_WORKER: claiming_step (namespace: payments) | {...}
+  #
+  # @example Step execution logging
+  #   logger.log_step(:info, "handler_execution",
+  #     step_uuid: "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+  #     handler_class: "ProcessPaymentHandler",
+  #     execution_time_ms: 125,
+  #     result_size_bytes: 1024
+  #   )
+  #
+  # @example FFI operation logging
+  #   logger.log_ffi(:info, "bootstrap_worker",
+  #     component: "RubyWorker",
+  #     worker_id: "ruby-worker-123",
+  #     deployment_mode: "Hybrid"
+  #   )
+  #
+  # @example Database operation logging
+  #   logger.log_database(:debug, "step_transition",
+  #     step_uuid: "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+  #     from_state: "in_progress",
+  #     to_state: "complete",
+  #     duration_ms: 15
+  #   )
+  #
+  # @example Configuration logging
+  #   logger.log_config(:info, "environment_loaded",
+  #     environment: "production",
+  #     config_file: "/etc/tasker/config.yml",
+  #     overrides_applied: 3
+  #   )
+  #
+  # @example Handler registry logging
+  #   logger.log_registry(:debug, "handler_registered",
+  #     namespace: "payments",
+  #     name: "ProcessPaymentHandler",
+  #     handler_count: 12
+  #   )
+  #
+  # Component Types and Their Emojis:
+  # - **📋 TASK_OPERATION**: Task-level operations (creation, completion, state changes)
+  # - **🔄 QUEUE_WORKER**: Queue processing and step claiming
+  # - **🚀 ORCHESTRATOR**: Orchestration coordination and workflow management
+  # - **🔧 STEP_OPERATION**: Step execution and handler invocation
+  # - **💾 DATABASE**: Database operations and state persistence
+  # - **🌉 FFI**: Rust FFI bridge operations and cross-language communication
+  # - **⚙️ CONFIG**: Configuration loading and validation
+  # - **📚 REGISTRY**: Handler registry operations and discovery
+  #
+  # Log Levels:
+  # - **:debug**: Detailed diagnostic information
+  # - **:info**: General informational messages
+  # - **:warn**: Warning messages for potential issues
+  # - **:error**: Error messages for failures
+  # - **:fatal**: Critical failures requiring immediate attention
+  #
+  # @see #log_task For task-level operations
+  # @see #log_queue_worker For queue processing
+  # @see #log_orchestrator For orchestration operations
+  # @see #log_step For step execution
+  # @see #log_database For database operations
+  # @see #log_ffi For FFI bridge operations
+  # @see #log_config For configuration operations
+  # @see #log_registry For handler registry operations
+  class Logger
+    include Singleton
+
+    # Traditional string-based logging methods (delegates to Tracing)
+    def info(message, &)
+      Tracing.info(message.to_s, extract_context_fields)
+    end
+
+    def warn(message, &)
+      Tracing.warn(message.to_s, extract_context_fields)
+    end
+
+    def error(message, &)
+      Tracing.error(message.to_s, extract_context_fields)
+    end
+
+    def fatal(message, &)
+      Tracing.error(message.to_s, extract_context_fields.merge(severity: 'fatal'))
+    end
+
+    def debug(message, &)
+      Tracing.debug(message.to_s, extract_context_fields)
+    end
+
+    # Enhanced structured logging methods (delegates to Tracing with appropriate fields)
+
+    def log_task(level, operation, **data)
+      fields = extract_context_fields.merge(
+        operation: operation,
+        component: 'task_operation'
+      ).merge(data)
+      Tracing.send(level, operation, fields)
+    end
+
+    def log_queue_worker(level, operation, namespace: nil, **data)
+      fields = extract_context_fields.merge(
+        operation: operation,
+        component: 'queue_worker'
+      ).merge(data)
+      fields[:namespace] = namespace if namespace
+      Tracing.send(level, operation, fields)
+    end
+
+    def log_orchestrator(level, operation, **data)
+      fields = extract_context_fields.merge(
+        operation: operation,
+        component: 'orchestrator'
+      ).merge(data)
+      Tracing.send(level, operation, fields)
+    end
+
+    def log_step(level, operation, **data)
+      fields = extract_context_fields.merge(
+        operation: operation,
+        component: 'step_operation'
+      ).merge(data)
+      Tracing.send(level, operation, fields)
+    end
+
+    def log_database(level, operation, **data)
+      fields = extract_context_fields.merge(
+        operation: operation,
+        component: 'database'
+      ).merge(data)
+      Tracing.send(level, operation, fields)
+    end
+
+    def log_ffi(level, operation, component: nil, **data)
+      fields = extract_context_fields.merge(
+        operation: operation,
+        component: component || 'ffi'
+      ).merge(data)
+      Tracing.send(level, operation, fields)
+    end
+
+    def log_config(level, operation, **data)
+      fields = extract_context_fields.merge(
+        operation: operation,
+        component: 'config'
+      ).merge(data)
+      Tracing.send(level, operation, fields)
+    end
+
+    def log_registry(level, operation, namespace: nil, name: nil, **data)
+      fields = extract_context_fields.merge(
+        operation: operation,
+        component: 'registry'
+      ).merge(data)
+      fields[:namespace] = namespace if namespace
+      fields[:handler_name] = name if name
+      Tracing.send(level, operation, fields)
+    end
+
+    def initialize
+      # No-op - everything delegates to Tracing now
+    end
+
+    private
+
+    # Extract context fields from thread-local or instance variables if available
+    def extract_context_fields
+      fields = {}
+
+      # Try to extract correlation_id from thread-local storage if available
+      fields[:correlation_id] = Thread.current[:correlation_id] if Thread.current[:correlation_id]
+
+      # Try to extract task/step UUIDs if available
+      fields[:task_uuid] = Thread.current[:task_uuid] if Thread.current[:task_uuid]
+
+      fields[:step_uuid] = Thread.current[:step_uuid] if Thread.current[:step_uuid]
+
+      fields
+    end
+  end
+end

data/lib/tasker_core/models.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+module TaskerCore
+  module Models
+    # Wrapper for TaskSequenceStep data received from Rust FFI.
+    #
+    # This class provides a Ruby-friendly interface to the complete step execution context,
+    # including task metadata, workflow step state, dependency results, and step definition.
+    # The data structure is provided by the Rust orchestration system via FFI when a step
+    # is ready for execution.
+    #
+    # @example Accessing task context in a handler
+    #   def call(context)
+    #     even_number = context.task.context['even_number']
+    #     # or use the convenience method
+    #     even_number = context.get_task_field('even_number')
+    #   end
+    #
+    # @example Accessing dependency results
+    #   def call(context)
+    #     previous_result = context.get_dependency_result('previous_step_name')
+    #   end
+    class TaskSequenceStepWrapper
+      # @return [TaskWrapper] Wrapped task with context and metadata
+      # @return [WorkflowStepWrapper] Wrapped workflow step with execution state
+      # @return [DependencyResultsWrapper] Results from parent steps
+      # @return [StepDefinitionWrapper] Step definition from task template
+      attr_reader :task, :workflow_step, :dependency_results, :step_definition
+
+      # Creates a new TaskSequenceStepWrapper from FFI data
+      #
+      # @param step_data [Hash] The complete step execution data from Rust
+      # @option step_data [Hash] :task Task and namespace metadata
+      # @option step_data [Hash] :workflow_step Step execution state and results
+      # @option step_data [Hash] :dependency_results Results from parent steps
+      # @option step_data [Hash] :step_definition Step configuration from template
+      def initialize(step_data)
+        @task = TaskWrapper.new(step_data[:task])
+        @workflow_step = WorkflowStepWrapper.new(step_data[:workflow_step])
+        @dependency_results = DependencyResultsWrapper.new(step_data[:dependency_results])
+        @step_definition = StepDefinitionWrapper.new(step_data[:step_definition])
+      end
+
+      # Convenience method to access task context fields
+      #
+      # @param field_name [String, Symbol] The field name in task context
+      # @return [Object, nil] The field value or nil if not found
+      #
+      # @example
+      #   sequence.get_task_field('even_number') # => 2
+      def get_task_field(field_name)
+        @task.context[field_name.to_s]
+      end
+
+      # Convenience method to access dependency results
+      #
+      # @param step_name [String, Symbol] The name of the parent step
+      # @return [Object, nil] The result from the parent step or nil
+      #
+      # @example
+      #   result = sequence.get_dependency_result('linear_step_1') # => 36
+      def get_dependency_result(step_name)
+        @dependency_results.get_result(step_name)
+      end
+
+      # Convenience method to access dependency results (alias for compatibility)
+      #
+      # @param step_name [String, Symbol] The name of the parent step
+      # @return [Object, nil] The result from the parent step or nil
+      #
+      # @example
+      #   result = sequence.get_results('linear_step_1') # => 36
+      def get_results(step_name)
+        @dependency_results.get_results(step_name)
+      end
+    end
+
+    # Wrapper for task metadata and context.
+    #
+    # Handles the nested task structure from Rust FFI where the actual task data
+    # is nested under a :task key within the parent task hash.
+    #
+    # @example Accessing task properties
+    #   task.task_uuid        # => "0199a46a-11a8-7d53-83da-0b13513dab49"
+    #   task.context          # => { "even_number" => 2 }
+    #   task.namespace_name   # => "linear_workflow"
+    class TaskWrapper
+      # @return [String] UUID v7 of the task instance
+      # @return [ActiveSupport::HashWithIndifferentAccess] Task context with input data and accumulated state
+      # @return [String] Namespace name from task template
+      # @return [String] Task template name
+      # @return [String] Task template version
+      attr_reader :task_uuid, :context, :namespace_name, :task_name, :task_version
+
+      # Creates a new TaskWrapper from FFI data
+      #
+      # @param task_data [Hash] Task data with nested structure from Rust
+      # @option task_data [Hash] :task Nested task object with context
+      # @option task_data [String] :task_name Template name
+      # @option task_data [String] :namespace_name Namespace from template
+      # @option task_data [String] :task_version Template version
+      def initialize(task_data)
+        # Handle nested task structure from Rust FFI
+        # Data comes as: { task: { task_uuid: ..., context: ... }, task_name: "...", namespace_name: "..." }
+        # The actual task fields are nested under :task key
+        inner_task = task_data[:task] || task_data
+
+        @task_uuid = inner_task[:task_uuid]
+        # Use HashWithIndifferentAccess for developer-friendly context access
+        @context = (inner_task[:context] || {}).with_indifferent_access
+        @namespace_name = task_data[:namespace_name] || inner_task[:namespace_name]
+        @task_name = task_data[:task_name] || inner_task[:task_name]
+        @task_version = task_data[:task_version] || inner_task[:task_version]
+      end
+    end
+
+    # Wrapper for workflow step execution state and metadata.
+    #
+    # Provides access to step execution tracking, retry configuration, and results.
+    #
+    # @example Checking step state
+    #   step.name              # => "linear_step_1"
+    #   step.attempts          # => 1
+    #   step.max_attempts       # => 3
+    #   step.in_process        # => false
+    class WorkflowStepWrapper
+      # @return [String] UUID v7 of the workflow step instance
+      # @return [String] UUID v7 of the task this step belongs to
+      # @return [String] UUID v7 of the named step definition
+      # @return [String] Step name from template
+      # @return [Boolean] Whether step can be retried
+      # @return [Integer] Maximum retry attempts
+      # @return [Boolean] Whether step is currently being processed
+      # @return [Boolean] Whether step has been processed
+      # @return [Time, nil] When step was last processed
+      # @return [Integer] Number of execution attempts
+      # @return [Time, nil] When step was last attempted
+      # @return [Integer] Backoff delay in seconds for retry
+      # @return [ActiveSupport::HashWithIndifferentAccess] Step inputs from template
+      # @return [ActiveSupport::HashWithIndifferentAccess] Step execution results
+
+      # @return [Time] When step was created
+      # @return [Time] When step was last updated
+      # @return [ActiveSupport::HashWithIndifferentAccess, nil] TAS-125: Checkpoint data for batch processing resumption
+      attr_reader :workflow_step_uuid, :task_uuid, :named_step_uuid, :name,
+                  :retryable, :max_attempts, :in_process, :processed, :processed_at,
+                  :attempts, :last_attempted_at, :backoff_request_seconds,
+                  :inputs, :results, :created_at, :updated_at, :checkpoint
+
+      # Creates a new WorkflowStepWrapper from FFI data
+      #
+      # @param step_data [Hash] Workflow step data from Rust
+      def initialize(step_data)
+        @workflow_step_uuid = step_data[:workflow_step_uuid]
+        @task_uuid = step_data[:task_uuid]
+        @named_step_uuid = step_data[:named_step_uuid]
+        @name = step_data[:name]
+        @retryable = step_data[:retryable]
+        @max_attempts = step_data[:max_attempts]
+        @in_process = step_data[:in_process]
+        @processed = step_data[:processed]
+        @processed_at = step_data[:processed_at]
+        @attempts = step_data[:attempts]
+        @last_attempted_at = step_data[:last_attempted_at]
+        @backoff_request_seconds = step_data[:backoff_request_seconds]
+        # Use HashWithIndifferentAccess for nested hashes
+        @inputs = (step_data[:inputs] || {}).with_indifferent_access
+        @results = (step_data[:results] || {}).with_indifferent_access
+
+        @created_at = step_data[:created_at]
+        @updated_at = step_data[:updated_at]
+        # TAS-125: Checkpoint data for batch processing resumption
+        @checkpoint = step_data[:checkpoint]&.with_indifferent_access
+      end
+    end
+
+    # Wrapper for dependency results from parent steps.
+    #
+    # Provides access to results from steps that this step depends on.
+    # Results are keyed by step name.
+    #
+    # @note Two methods for accessing results:
+    #   - `get_result(name)` returns the full result hash with metadata
+    #   - `get_results(name)` returns just the computed value (recommended for handlers)
+    #
+    # @example Accessing dependency results
+    #   deps.get_results('previous_step')  # => 36 (just the value)
+    #   deps.get_result('previous_step')   # => { result: 36, metadata: {...} }
+    #   deps['previous_step']              # => { result: 36, metadata: {...} }
+    class DependencyResultsWrapper
+      # Creates a new DependencyResultsWrapper
+      #
+      # @param results_data [Hash] Hash of step names to their results
+      def initialize(results_data)
+        # Use HashWithIndifferentAccess for developer-friendly key access
+        @results = (results_data || {}).with_indifferent_access
+      end
+
+      # Get result from a parent step (returns full result hash)
+      #
+      # @param step_name [String, Symbol] Name of the parent step
+      # @return [Hash, nil] The full result hash or nil if not found
+      def get_result(step_name)
+        @results[step_name] # HashWithIndifferentAccess handles string/symbol automatically
+      end
+
+      # Get the actual result value from a parent step (extracts 'result' field)
+      #
+      # This is the typical method handlers use to get the actual computed value
+      # from a parent step, rather than the full result metadata hash.
+      #
+      # @param step_name [String, Symbol] Name of the parent step
+      # @return [Object, nil] The result value or nil if not found
+      #
+      # @example
+      #   deps.get_results('linear_step_1')  # => 36 (the actual value)
+      #   deps.get_result('linear_step_1')   # => { result: 36, metadata: {...} }
+      def get_results(step_name)
+        result_hash = @results[step_name]
+        return nil unless result_hash
+
+        # If it's a hash with a 'result' key, extract that value
+        # Otherwise return the whole thing (might be a primitive value)
+        if result_hash.is_a?(Hash) && result_hash.key?('result')
+          result_hash['result']
+        else
+          result_hash
+        end
+      end
+
+      # Array-style access to dependency results
+      #
+      # @param step_name [String, Symbol] Name of the parent step
+      # @return [Hash, nil] The full result hash or nil if not found
+      def [](step_name)
+        get_result(step_name)
+      end
+
+      # Get all dependency result step names
+      #
+      # @return [Array<String>] List of step names that have results
+      def keys
+        @results.keys
+      end
+
+      # Check if a dependency result exists
+      #
+      # @param step_name [String, Symbol] Name of the parent step
+      # @return [Boolean] True if result exists
+      def key?(step_name)
+        @results.key?(step_name) # HashWithIndifferentAccess handles string/symbol automatically
+      end
+
+      def each_key(&)
+        @results.keys.each(&)
+      end
+    end
+
+    # Wrapper for step definition from task template.
+    #
+    # Provides access to step configuration including handler specification,
+    # dependencies, retry policy, and timeout settings.
+    #
+    # @example Accessing step definition
+    #   step_def.name                    # => "linear_step_1"
+    #   step_def.description             # => "Square the initial even number..."
+    #   step_def.handler.callable        # => "LinearWorkflow::StepHandlers::LinearStep1Handler"
+    #   step_def.dependencies            # => ["previous_step"]
+    #   step_def.timeout_seconds         # => 30
+    class StepDefinitionWrapper
+      # @return [String] Step name
+      # @return [String] Human-readable description
+      # @return [HandlerWrapper] Handler configuration
+
+      # @return [Array<String>] Names of parent steps this depends on
+      # @return [ActiveSupport::HashWithIndifferentAccess] Retry configuration
+      # @return [Integer] Timeout in seconds
+      # @return [Array<String>] Events this step publishes
+      attr_reader :name, :description, :handler,
+                  :dependencies, :retry, :timeout_seconds, :publishes_events
+
+      # Creates a new StepDefinitionWrapper from template data
+      #
+      # @param definition_data [Hash] Step definition from task template
+      def initialize(definition_data)
+        @name = definition_data[:name]
+        @description = definition_data[:description]
+        @handler = HandlerWrapper.new(definition_data[:handler])
+
+        @dependencies = definition_data[:dependencies] || []
+        # Use HashWithIndifferentAccess for retry configuration
+        @retry = (definition_data[:retry] || {}).with_indifferent_access
+        @timeout_seconds = definition_data[:timeout_seconds]
+        @publishes_events = definition_data[:publishes_events] || []
+      end
+    end
+
+    # Wrapper for handler configuration.
+    #
+    # Provides access to handler class name, method dispatch, resolver hints,
+    # and initialization parameters from the task template.
+    #
+    # TAS-93: Extended to support method dispatch and resolver hints from
+    # the Rust HandlerDefinition struct.
+    #
+    # @example Accessing handler configuration
+    #   handler.callable       # => "LinearWorkflow::StepHandlers::LinearStep1Handler"
+    #   handler.initialization # => { operation: "square", step_number: 1 }
+    #   handler.handler_method # => "refund" (or nil for default .call())
+    #   handler.resolver       # => "explicit" (or nil for chain traversal)
+    class HandlerWrapper
+      # @return [String] Fully-qualified handler class name
+      # @return [ActiveSupport::HashWithIndifferentAccess] Initialization parameters for the handler
+      # @return [String, nil] TAS-93: Method to invoke instead of default .call()
+      # @return [String, nil] TAS-93: Specific resolver to use (bypasses chain)
+      attr_reader :callable, :initialization, :handler_method, :resolver
+
+      # Creates a new HandlerWrapper from template data
+      #
+      # @param handler_data [Hash] Handler configuration from template
+      # @option handler_data [String] :callable Handler class name
+      # @option handler_data [Hash] :initialization Handler init params
+      # @option handler_data [String] :method TAS-93: Method to invoke (from Rust FFI)
+      # @option handler_data [String] :resolver TAS-93: Resolver hint (from Rust FFI)
+      def initialize(handler_data)
+        @callable = handler_data[:callable]
+        # Use HashWithIndifferentAccess for initialization parameters
+        @initialization = (handler_data[:initialization] || {}).with_indifferent_access
+        # TAS-93: Method dispatch - note Rust field is 'method' but we use 'handler_method'
+        # to avoid conflict with Ruby's Object#method
+        @handler_method = handler_data[:method]
+        # TAS-93: Resolver hint for direct resolver routing
+        @resolver = handler_data[:resolver]
+      end
+    end
+  end
+end