tasker-rb 0.1.3-x86_64-linux

data/lib/tasker_core/event_bridge.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require_relative 'models'
+
+module TaskerCore
+  module Worker
+    # Event bridge between Rust and Ruby using dry-events
+    #
+    # Handles bidirectional event communication between the Rust orchestration
+    # layer and Ruby business logic handlers. The bridge uses dry-events for
+    # Ruby-side pub/sub and FFI for cross-language communication.
+    #
+    # Event Flow:
+    # 1. **Rust → Ruby**: StepExecutionEvent indicates step is ready for processing
+    # 2. **Ruby Processing**: Handler executes business logic
+    # 3. **Ruby → Rust**: StepExecutionCompletionEvent returns results
+    #
+    # The EventBridge automatically wraps raw FFI data in accessor objects for
+    # developer convenience and maintains event schema validation.
+    #
+    # @example Publishing step execution (from Rust FFI)
+    #   # This is called automatically by Rust via FFI when a step is ready
+    #   bridge = TaskerCore::Worker::EventBridge.instance
+    #   bridge.publish_step_execution({
+    #     event_id: "550e8400-e29b-41d4-a716-446655440000",
+    #     task_uuid: "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+    #     step_uuid: "123e4567-e89b-12d3-a456-426614174000",
+    #     task_sequence_step: {
+    #       task: { context: { amount: 100.00, currency: "USD" } },
+    #       step: { name: "process_payment", handler_class: "ProcessPaymentHandler" },
+    #       workflow_step: { state: "in_progress", attempts: 1 }
+    #     }
+    #   })
+    #   # => Publishes 'step.execution.received' event to Ruby subscribers
+    #
+    # @example Subscribing to step execution events
+    #   # This is typically done in StepExecutionSubscriber
+    #   bridge.subscribe_to_step_execution do |event|
+    #     # Resolve handler
+    #     handler_class = event[:task_sequence_step].handler_class
+    #     handler = registry.resolve_handler(handler_class)
+    #
+    #     # Create context and execute handler
+    #     context = TaskerCore::Types::StepContext.new(event[:task_sequence_step])
+    #     result = handler.call(context)
+    #
+    #     # Send completion back to Rust
+    #     bridge.publish_step_completion({
+    #       event_id: event[:event_id],
+    #       task_uuid: event[:task_uuid],
+    #       step_uuid: event[:step_uuid],
+    #       success: true,
+    #       result: result
+    #     })
+    #   end
+    #
+    # @example Sending completion back to Rust
+    #   bridge.publish_step_completion({
+    #     event_id: "550e8400-e29b-41d4-a716-446655440000",
+    #     task_uuid: "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+    #     step_uuid: "123e4567-e89b-12d3-a456-426614174000",
+    #     success: true,
+    #     result: { payment_id: "pay_123", status: "succeeded" },
+    #     metadata: {
+    #       handler_class: "ProcessPaymentHandler",
+    #       execution_time_ms: 125
+    #     }
+    #   })
+    #   # => Sends completion to Rust via FFI and publishes 'step.completion.sent'
+    #
+    # @example Handling errors in step execution
+    #   begin
+    #     result = handler.call(context)
+    #     bridge.publish_step_completion({
+    #       event_id: event_id,
+    #       task_uuid: task_uuid,
+    #       step_uuid: step_uuid,
+    #       success: true,
+    #       result: result
+    #     })
+    #   rescue TaskerCore::Errors::RetryableError => e
+    #     bridge.publish_step_completion({
+    #       event_id: event_id,
+    #       task_uuid: task_uuid,
+    #       step_uuid: step_uuid,
+    #       success: false,
+    #       error_message: e.message,
+    #       error_class: e.class.name,
+    #       retryable: true,
+    #       retry_after: e.retry_after
+    #     })
+    #   rescue TaskerCore::Errors::PermanentError => e
+    #     bridge.publish_step_completion({
+    #       event_id: event_id,
+    #       task_uuid: task_uuid,
+    #       step_uuid: step_uuid,
+    #       success: false,
+    #       error_message: e.message,
+    #       error_class: e.class.name,
+    #       retryable: false
+    #     })
+    #   end
+    #
+    # Event Flow Diagram:
+    #
+    # ```
+    # Rust Orchestration                EventBridge                 Ruby Handler
+    # -----------------                -----------                 ------------
+    #       |                                |                           |
+    #       | 1. Step ready for execution    |                           |
+    #       |------------------------------->|                           |
+    #       |    publish_step_execution      |                           |
+    #       |                                | 2. Publish event          |
+    #       |                                |-------------------------->|
+    #       |                                |    step.execution.received|
+    #       |                                |                           |
+    #       |                                |                  3. Execute handler
+    #       |                                |                           |
+    #       |                                | 4. Completion             |
+    #       |                                |<--------------------------|
+    #       | 5. FFI completion              |    publish_step_completion|
+    #       |<-------------------------------|                           |
+    #       |    send_step_completion_event  |                           |
+    # ```
+    #
+    # Registered Events:
+    # - **step.execution.received**: Step ready for execution (Rust → Ruby)
+    # - **step.completion.sent**: Step execution completed (Ruby → Rust)
+    # - **bridge.error**: Error in event processing
+    #
+    # Completion Data Validation:
+    # The bridge validates completion data before sending to Rust:
+    # - **event_id**: Required, UUID of the original execution event
+    # - **task_uuid**: Required, UUID of the task
+    # - **step_uuid**: Required, UUID of the step
+    # - **success**: Required, boolean indicating success/failure
+    # - **metadata**: Optional, hash with additional context
+    # - **completed_at**: Optional, ISO 8601 timestamp (auto-generated if missing)
+    #
+    # @see TaskerCore::Subscriber For event subscription implementation
+    # @see TaskerCore::Worker::EventPoller For polling mechanism
+    # @see TaskerCore::FFI For Rust FFI operations
+    # @see TaskerCore::Models::TaskSequenceStepWrapper For data wrappers
+    class EventBridge
+      include Singleton
+      include Dry::Events::Publisher[:tasker_core]
+
+      attr_reader :logger, :active
+
+      def initialize
+        @logger = TaskerCore::Logger.instance
+        @active = true
+
+        setup_event_schema!
+      end
+
+      # Check if bridge is active
+      def active?
+        @active
+      end
+
+      # Stop the event bridge
+      def stop!
+        @active = false
+        logger.info 'Event bridge stopped'
+      end
+
+      # Called by Rust FFI when StepExecutionEvent is received
+      # This is the entry point for events from Rust
+      def publish_step_execution(event_data)
+        return unless active?
+
+        event_data = event_data.to_h.deep_symbolize_keys
+        logger.debug "Publishing step execution event: #{event_data[:event_id]}"
+
+        # Wrap the raw data in accessor objects for easier use
+        wrapped_event = wrap_step_execution_event(event_data)
+
+        # Publish to dry-events subscribers (Ruby handlers)
+        publish('step.execution.received', wrapped_event)
+
+        logger.debug 'Step execution event published successfully'
+        true
+      rescue StandardError => e
+        logger.error "Failed to publish step execution: #{e.message}"
+        logger.error e.backtrace.join("\n")
+        raise
+      end
+
+      # Subscribe to step execution events (used by StepExecutionSubscriber)
+      def subscribe_to_step_execution(&)
+        subscribe('step.execution.received', &)
+      end
+
+      # Send completion event back to Rust
+      # Called by StepExecutionSubscriber after handler execution
+      def publish_step_completion(completion_data)
+        return unless active?
+
+        logger.debug "Sending step completion to Rust: #{completion_data[:event_id]}"
+
+        # Validate completion data
+        validate_completion!(completion_data)
+
+        # Send to Rust via FFI (TAS-67: complete_step_event takes event_id and completion_data)
+        TaskerCore::FFI.complete_step_event(completion_data[:event_id].to_s, completion_data)
+
+        # Also publish locally for monitoring/debugging
+        publish('step.completion.sent', completion_data)
+
+        logger.debug 'Step completion sent to Rust'
+      rescue StandardError => e
+        logger.error "Failed to send step completion: #{e.message}"
+        logger.error e.backtrace.join("\n")
+        raise
+      end
+
+      # TAS-125: Send checkpoint yield back to Rust for batch processing
+      #
+      # Called by batch processing handlers when they want to persist progress
+      # and be re-dispatched for continuation. Unlike publish_step_completion,
+      # this does NOT complete the step - instead it persists checkpoint data
+      # and causes the step to be re-dispatched for continued processing.
+      #
+      # @param checkpoint_data [Hash] Checkpoint data to persist:
+      #   - :event_id [String] Required, UUID of the original execution event
+      #   - :step_uuid [String] Required, UUID of the step
+      #   - :cursor [Object] Required, position to resume from (Integer, String, or Hash)
+      #   - :items_processed [Integer] Required, count of items processed so far
+      #   - :accumulated_results [Hash] Optional, partial results to carry forward
+      # @return [Boolean] true if checkpoint was persisted and step re-dispatched
+      #
+      # @example Yield checkpoint in batch processing
+      #   bridge.publish_step_checkpoint_yield({
+      #     event_id: "550e8400-e29b-41d4-a716-446655440000",
+      #     step_uuid: "123e4567-e89b-12d3-a456-426614174000",
+      #     cursor: 1000,
+      #     items_processed: 1000,
+      #     accumulated_results: { total_amount: 50000.00, processed_count: 1000 }
+      #   })
+      def publish_step_checkpoint_yield(checkpoint_data)
+        return false unless active?
+
+        logger.debug "Sending checkpoint yield to Rust: #{checkpoint_data[:event_id]}"
+
+        # Validate checkpoint data
+        validate_checkpoint_yield!(checkpoint_data)
+
+        # Send to Rust via FFI (TAS-125)
+        success = TaskerCore::FFI.checkpoint_yield_step_event(
+          checkpoint_data[:event_id].to_s,
+          checkpoint_data
+        )
+
+        if success
+          # Publish locally for monitoring/debugging
+          publish('step.checkpoint_yield.sent', checkpoint_data)
+          logger.debug 'Checkpoint yield sent to Rust - step will be re-dispatched'
+        else
+          logger.warn 'Checkpoint yield failed - checkpoint support may not be configured'
+        end
+
+        success
+      rescue StandardError => e
+        logger.error "Failed to send checkpoint yield: #{e.message}"
+        logger.error e.backtrace.join("\n")
+        raise
+      end
+
+      private
+
+      def setup_event_schema!
+        # Register event types
+        register_event('step.execution.received')
+        register_event('step.completion.sent')
+        register_event('step.checkpoint_yield.sent') # TAS-125
+        register_event('bridge.error')
+      end
+
+      def wrap_step_execution_event(event_data)
+        wrapped = {
+          event_id: event_data[:event_id],
+          task_uuid: event_data[:task_uuid],
+          step_uuid: event_data[:step_uuid],
+          task_sequence_step: TaskerCore::Models::TaskSequenceStepWrapper.new(event_data[:task_sequence_step])
+        }
+
+        # TAS-29: Expose correlation_id at top level for easy access
+        wrapped[:correlation_id] = event_data[:correlation_id] if event_data[:correlation_id]
+        wrapped[:parent_correlation_id] = event_data[:parent_correlation_id] if event_data[:parent_correlation_id]
+
+        # TAS-65 Phase 1.5b: Expose trace_id and span_id for distributed tracing
+        wrapped[:trace_id] = event_data[:trace_id] if event_data[:trace_id]
+        wrapped[:span_id] = event_data[:span_id] if event_data[:span_id]
+
+        wrapped
+      end
+
+      def validate_completion!(completion_data)
+        required_fields = %i[event_id task_uuid step_uuid success]
+        missing_fields = required_fields - completion_data.keys
+
+        if missing_fields.any?
+          raise ArgumentError, "Missing required fields in completion: #{missing_fields.join(', ')}"
+        end
+
+        # Ensure metadata is a hash
+        completion_data[:metadata] ||= {}
+
+        # Ensure timestamps
+        completion_data[:completed_at] ||= Time.now.utc.iso8601
+      end
+
+      # TAS-125: Validate checkpoint yield data before sending to Rust
+      def validate_checkpoint_yield!(checkpoint_data)
+        required_fields = %i[event_id step_uuid cursor items_processed]
+        missing_fields = required_fields - checkpoint_data.keys
+
+        if missing_fields.any?
+          raise ArgumentError, "Missing required fields in checkpoint yield: #{missing_fields.join(', ')}"
+        end
+
+        # Validate items_processed is a non-negative integer
+        return if checkpoint_data[:items_processed].is_a?(Integer) && checkpoint_data[:items_processed] >= 0
+
+        raise ArgumentError, 'items_processed must be a non-negative integer'
+      end
+    end
+  end
+end

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