tasker-rb 0.1.1

data/lib/tasker_core/handlers.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module TaskerCore
+  # Clean Handlers Domain API
+  #
+  # This module provides the primary public interface for working with TaskerCore handlers.
+  # It's organized into two main namespaces: Steps and Tasks, mirroring the Rails engine
+  # architecture while providing a clean Ruby interface with enhanced type safety.
+  #
+  # The Handlers namespace serves as the recommended entry point for handler operations,
+  # abstracting the underlying implementation details while preserving method signatures
+  # that developers familiar with the Rails engine will recognize.
+  #
+  # @example Creating and using a step handler
+  #   # Define a handler class
+  #   class ProcessPaymentHandler < TaskerCore::Handlers::Steps::Base
+  #     def call(context)
+  #       # Access task context
+  #       amount = context.get_task_field('amount')
+  #       currency = context.get_task_field('currency')
+  #
+  #       # Process payment logic
+  #       result = charge_payment(amount, currency)
+  #
+  #       # Return results
+  #       success(result: { payment_id: result.id, status: "succeeded" })
+  #     end
+  #   end
+  #
+  #   # Create instance with configuration
+  #   handler = TaskerCore::Handlers::Steps.create(
+  #     ProcessPaymentHandler,
+  #     config: { timeout: 30, max_attempts: 3 }
+  #   )
+  #
+  # @example Validating handler implementation
+  #   validation = TaskerCore::Handlers::Steps.validate(ProcessPaymentHandler)
+  #   # => {
+  #   #   valid: true,
+  #   #   missing_required: [],
+  #   #   optional_implemented: [:process_results],
+  #   #   handler_class: "ProcessPaymentHandler"
+  #   # }
+  #
+  #   if validation[:valid]
+  #     puts "Handler implements all required methods"
+  #   else
+  #     puts "Missing: #{validation[:missing_required].join(', ')}"
+  #   end
+  #
+  # @example Using API handlers for HTTP operations
+  #   class FetchUserHandler < TaskerCore::Handlers::Steps::API
+  #     def call(context)
+  #       user_id = context.get_task_field('user_id')
+  #
+  #       # Automatic error classification and retry logic
+  #       response = get("/users/#{user_id}")
+  #
+  #       success(result: response.body)
+  #     end
+  #   end
+  #
+  # @example Task-level handler for workflow coordination
+  #   # Task handlers coordinate multiple steps
+  #   result = TaskerCore::Handlers::Tasks.handle(task_uuid: "123-456")
+  #   # => Orchestrates all steps for the task
+  #
+  # Architecture:
+  # - **Steps**: Individual business logic units (payment processing, API calls, etc.)
+  # - **Tasks**: Workflow orchestration and step coordination
+  # - **API**: Specialized step handlers for HTTP operations with automatic retry
+  #
+  # Method Signature:
+  # Cross-language standard handler signature (TAS-96):
+  # - `call(context)` - Primary handler execution with unified StepContext
+  # - `context.task` - Task wrapper with context data
+  # - `context.workflow_step` - Workflow step wrapper with execution state
+  # - `context.dependency_results` - Results from parent steps
+  #
+  # @see TaskerCore::Handlers::Steps For step-level business logic
+  # @see TaskerCore::Handlers::Tasks For task-level orchestration
+  # @see TaskerCore::StepHandler::Base For low-level step handler implementation
+  # @see TaskerCore::StepHandler::Api For HTTP-based handlers
+  module Handlers
+    # Step Handler API with preserved method signatures
+    module Steps
+      # Import the existing base step handler with preserved signatures
+      require_relative 'step_handler/base'
+      require_relative 'step_handler/mixins'   # TAS-112: Composition pattern mixins
+      require_relative 'step_handler/api'
+      require_relative 'step_handler/decision' # TAS-53: Decision point handlers
+      require_relative 'step_handler/batchable' # TAS-59: Batch processing handlers
+
+      # Re-export with clean namespace
+      Base = TaskerCore::StepHandler::Base
+
+      # TAS-112: Composition Pattern - Mixin modules (preferred)
+      # Use these with `include` in handlers that inherit from Base
+      Mixins = TaskerCore::StepHandler::Mixins
+
+      # Legacy class aliases (deprecated - use Mixins instead)
+      API = TaskerCore::StepHandler::Api
+      Decision = TaskerCore::StepHandler::Decision
+      Batchable = TaskerCore::StepHandler::Batchable
+
+      class << self
+        # Create a new step handler instance
+        # @param handler_class [Class] Handler class to instantiate
+        # @param config [Hash] Handler configuration
+        # @return [Object] Handler instance
+        def create(handler_class, config: {})
+          handler_class.new(config: config)
+        end
+
+        # Validate step handler implementation
+        # @param handler_class [Class] Handler class to validate
+        # @return [Hash] Validation result
+        def validate(handler_class)
+          required_methods = %i[process]
+          optional_methods = %i[process_results handle]
+
+          missing = required_methods.reject { |method| handler_class.method_defined?(method) }
+          present_optional = optional_methods.select { |method| handler_class.method_defined?(method) }
+
+          {
+            valid: missing.empty?,
+            missing_required: missing,
+            optional_implemented: present_optional,
+            handler_class: handler_class.name
+          }
+        end
+      end
+    end
+
+    # Task Handler API
+    module Tasks
+      require_relative 'task_handler/base'
+
+      # Re-export with clean namespace
+      Base = TaskHandler
+
+      class << self
+        # Handle task with preserved signature
+        # @param task_uuid [Integer] Task ID to handle
+        # @return [Object] Task handle result
+        def handle(task_uuid)
+          Base.new.handle(task_uuid)
+        end
+
+        # Create task handler instance
+        # @param config [Hash] Handler configuration
+        # @return [TaskHandler] Handler instance
+        def create(config: {})
+          Base.new(config: config)
+        end
+      end
+    end
+  end
+end

data/lib/tasker_core/internal.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module TaskerCore
+  module Internal
+    # Simple stub for OrchestrationManager to satisfy StepHandler::Base dependencies
+    # In the FFI worker context, we don't need the full Rails engine infrastructure
+    class OrchestrationManager
+      include Singleton
+
+      def orchestration_system
+        # Return a simple stub that satisfies the interface expected by handlers
+        NullOrchestrationSystem.new
+      end
+    end
+
+    # Minimal orchestration system stub for FFI worker context
+    class NullOrchestrationSystem
+      def method_missing(_method_name, *_args, **_kwargs)
+        # Log that the method was called but return nil
+        # This allows handlers to work without crashing
+        nil
+      end
+
+      def respond_to_missing?(_method_name, _include_private = false)
+        true
+      end
+    end
+  end
+end

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