tasker-rb 0.1.1

data/lib/tasker_core/step_handler/mixins/decision.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module TaskerCore
+  module StepHandler
+    module Mixins
+      # Decision mixin for TAS-53 Dynamic Workflow Decision Points
+      #
+      # ## TAS-112: Composition Pattern
+      #
+      # This module follows the composition-over-inheritance pattern. Instead of
+      # inheriting from a specialized Decision handler class, include this mixin
+      # in your Base handler.
+      #
+      # ## Usage
+      #
+      # ```ruby
+      # class MyDecisionHandler < TaskerCore::StepHandler::Base
+      #   include TaskerCore::StepHandler::Mixins::Decision
+      #
+      #   def call(context)
+      #     amount = context.get_task_field('amount')
+      #
+      #     if amount < 1000
+      #       decision_success(
+      #         steps: ['auto_approve'],
+      #         result_data: { route_type: 'auto', amount: amount }
+      #       )
+      #     else
+      #       decision_success(
+      #         steps: ['manager_approval', 'finance_review'],
+      #         result_data: { route_type: 'dual', amount: amount }
+      #       )
+      #     end
+      #   end
+      # end
+      # ```
+      #
+      # ## No-Branch Pattern
+      #
+      # ```ruby
+      # def call(context)
+      #   if context.get_task_field('skip_approval')
+      #     decision_no_branches(result_data: { reason: 'skipped' })
+      #   else
+      #     decision_success(steps: ['standard_approval'])
+      #   end
+      # end
+      # ```
+      module Decision
+        # Hook called when module is included
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        # Class methods added to including class
+        module ClassMethods
+          # No class methods needed for now
+        end
+
+        # Override capabilities to include decision-specific features
+        def capabilities
+          super + %w[decision_point dynamic_workflow step_creation]
+        end
+
+        # Enhanced configuration schema for decision handlers
+        def config_schema
+          super.merge({
+                        properties: super[:properties].merge(
+                          decision_thresholds: {
+                            type: 'object',
+                            description: 'Thresholds for decision routing logic'
+                          },
+                          decision_metadata: {
+                            type: 'object',
+                            description: 'Additional metadata for decision logging'
+                          }
+                        )
+                      })
+        end
+
+        # ========================================================================
+        # DECISION OUTCOME HELPER METHODS
+        # ========================================================================
+
+        # Return a successful decision outcome that creates specified steps
+        #
+        # @param steps [Array<String>, String] Step name(s) to create dynamically
+        # @param result_data [Hash] Additional result data (route_type, amounts, etc.)
+        # @param metadata [Hash] Optional metadata for observability
+        # @return [TaskerCore::Types::StepHandlerCallResult] Success result with decision outcome
+        #
+        # @example Single step
+        #   decision_success(
+        #     steps: 'approval_required',
+        #     result_data: { route_type: 'standard' }
+        #   )
+        #
+        # @example Multiple steps
+        #   decision_success(
+        #     steps: ['manager_approval', 'finance_review'],
+        #     result_data: { route_type: 'dual_approval', amount: 10000 }
+        #   )
+        def decision_success(steps:, result_data: {}, metadata: {})
+          # Normalize steps to array
+          step_names = Array(steps)
+
+          # Validate step names
+          validate_step_names!(step_names)
+
+          # Create decision outcome using type-safe factory
+          outcome = TaskerCore::Types::DecisionPointOutcome.create_steps(step_names)
+
+          # Build result with decision outcome embedded
+          result = result_data.merge(
+            decision_point_outcome: outcome.to_h
+          )
+
+          # Create success result
+          TaskerCore::Types::StepHandlerCallResult.success(
+            result: result,
+            metadata: build_decision_metadata(metadata, outcome)
+          )
+        end
+
+        # Return a decision outcome indicating no additional steps needed
+        #
+        # Use this when the decision point determines that workflow can proceed
+        # without creating any dynamic steps.
+        #
+        # @param result_data [Hash] Result data explaining why no branches needed
+        # @param metadata [Hash] Optional metadata for observability
+        # @return [TaskerCore::Types::StepHandlerCallResult] Success result with no-branches outcome
+        #
+        # @example
+        #   decision_no_branches(
+        #     result_data: { reason: 'amount_below_threshold', amount: 50 }
+        #   )
+        def decision_no_branches(result_data: {}, metadata: {})
+          # Create no-branches outcome
+          outcome = TaskerCore::Types::DecisionPointOutcome.no_branches
+
+          # Build result with outcome embedded
+          result = result_data.merge(
+            decision_point_outcome: outcome.to_h
+          )
+
+          # Create success result
+          TaskerCore::Types::StepHandlerCallResult.success(
+            result: result,
+            metadata: build_decision_metadata(metadata, outcome)
+          )
+        end
+
+        # Alias for decision_no_branches for cross-language consistency
+        alias skip_branches decision_no_branches
+
+        # Validate that a decision point outcome is properly structured
+        #
+        # @param outcome [Hash, DecisionPointOutcome] Outcome to validate
+        # @raise [TaskerCore::PermanentError] if outcome is invalid
+        def validate_decision_outcome!(outcome)
+          # Convert to hash if it's a DecisionPointOutcome type
+          outcome_hash = if outcome.respond_to?(:to_h)
+                           outcome.to_h
+                         elsif outcome.is_a?(Hash)
+                           outcome
+                         else
+                           raise_invalid_outcome!('Outcome must be Hash or DecisionPointOutcome')
+                         end
+
+          # Validate type field exists
+          outcome_type = outcome_hash[:type] || outcome_hash['type'] ||
+                         outcome_hash[:outcome_type] || outcome_hash['outcome_type']
+          unless %w[NoBranches CreateSteps no_branches create_steps].include?(outcome_type)
+            raise_invalid_outcome!("Invalid outcome_type: #{outcome_type}")
+          end
+
+          # Validate CreateSteps has step_names
+          normalized_type = outcome_type.downcase.gsub('_', '')
+          if normalized_type == 'createsteps'
+            step_names = outcome_hash[:step_names] || outcome_hash['step_names']
+            validate_step_names!(step_names)
+          end
+
+          outcome_hash
+        end
+
+        # Build a decision result with a custom outcome
+        #
+        # Use this for advanced scenarios where you need full control over the outcome
+        # structure. Most handlers should use decision_success or decision_no_branches.
+        #
+        # @param outcome [DecisionPointOutcome, Hash] The decision outcome
+        # @param result_data [Hash] Additional result data
+        # @param metadata [Hash] Optional metadata
+        # @return [TaskerCore::Types::StepHandlerCallResult] Success result
+        def decision_with_custom_outcome(outcome:, result_data: {}, metadata: {})
+          # Validate outcome structure
+          validated_outcome = validate_decision_outcome!(outcome)
+
+          # Build result
+          result = result_data.merge(
+            decision_point_outcome: validated_outcome
+          )
+
+          # Create success result
+          TaskerCore::Types::StepHandlerCallResult.success(
+            result: result,
+            metadata: build_decision_metadata(metadata, outcome)
+          )
+        end
+
+        private
+
+        # Validate step names for decision outcomes
+        def validate_step_names!(step_names)
+          unless step_names.is_a?(Array) && !step_names.empty?
+            raise_invalid_outcome!('step_names must be non-empty array')
+          end
+
+          unless step_names.all? { |name| name.is_a?(String) && !name.empty? }
+            raise_invalid_outcome!('All step names must be non-empty strings')
+          end
+
+          true
+        end
+
+        # Build metadata for decision outcomes
+        def build_decision_metadata(custom_metadata, outcome)
+          base_metadata = {
+            decision_point: true,
+            outcome_type: outcome.type,
+            branches_created: outcome.step_names.size,
+            processed_at: Time.now.utc.iso8601,
+            processed_by: handler_name
+          }
+
+          base_metadata.merge(custom_metadata)
+        end
+
+        # Raise a permanent error for invalid decision outcomes
+        def raise_invalid_outcome!(message)
+          raise TaskerCore::Errors::PermanentError.new(
+            "Invalid decision point outcome: #{message}",
+            error_code: 'INVALID_DECISION_OUTCOME',
+            context: { error_category: 'validation' }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/tasker_core/step_handler/mixins.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# TAS-112: Composition Pattern - Mixin Modules
+#
+# This file exports all step handler mixins. Mixins follow the composition-over-inheritance
+# pattern where specialized functionality is added via `include` rather than subclassing.
+#
+# ## Usage
+#
+# ```ruby
+# class MyApiHandler < TaskerCore::StepHandler::Base
+#   include TaskerCore::StepHandler::Mixins::API
+#
+#   def call(context)
+#     response = get('/users')
+#     success(result: response.body)
+#   end
+# end
+#
+# class MyDecisionHandler < TaskerCore::StepHandler::Base
+#   include TaskerCore::StepHandler::Mixins::Decision
+#
+#   def call(context)
+#     decision_success(steps: ['next_step'])
+#   end
+# end
+#
+# class MyBatchHandler < TaskerCore::StepHandler::Base
+#   include TaskerCore::StepHandler::Mixins::Batchable
+#
+#   def call(context)
+#     configs = create_cursor_configs(1000, 5)
+#     create_batches_outcome(worker_template_name: 'worker', cursor_configs: configs, total_items: 1000)
+#   end
+# end
+# ```
+#
+# ## Combining Mixins
+#
+# Mixins can be combined when a handler needs multiple capabilities:
+#
+# ```ruby
+# class ApiBatchHandler < TaskerCore::StepHandler::Base
+#   include TaskerCore::StepHandler::Mixins::API
+#   include TaskerCore::StepHandler::Mixins::Batchable
+#
+#   def call(context)
+#     # Can use both API and Batchable helpers
+#   end
+# end
+# ```
+
+require_relative 'mixins/api'
+require_relative 'mixins/decision'
+require_relative 'mixins/batchable'
+
+module TaskerCore
+  module StepHandler
+    module Mixins
+      # Re-export for convenient access
+      # API = TaskerCore::StepHandler::Mixins::API
+      # Decision = TaskerCore::StepHandler::Mixins::Decision
+      # Batchable = TaskerCore::StepHandler::Mixins::Batchable
+    end
+  end
+end

data/lib/tasker_core/subscriber.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module TaskerCore
+  module Worker
+    # Subscribes to step execution events and routes to handlers
+    class StepExecutionSubscriber
+      attr_reader :logger, :handler_registry, :stats
+
+      def initialize
+        @logger = TaskerCore::Logger.instance
+        @handler_registry = TaskerCore::Registry::HandlerRegistry.instance
+        @stats = { processed: 0, succeeded: 0, failed: 0 }
+        @active = true
+        @subscribed = false
+
+        subscribe_to_events
+        logger.info 'Step execution subscriber initialized'
+      end
+
+      # Check if subscriber is active
+      def active?
+        @active
+      end
+
+      # Stop the subscriber
+      def stop!
+        @active = false
+        logger.info 'Step execution subscriber stopped'
+      end
+
+      # Called by dry-events when step execution is requested
+      def call(event)
+        event_data = event.payload
+        step_data = event_data[:task_sequence_step]
+
+        logger.info 'Processing step execution request'
+        logger.info("Event ID: #{event_data[:event_id]}")
+        logger.info("Step: #{step_data.workflow_step.name}")
+        logger.info("Handler: #{step_data.step_definition.handler.callable}")
+
+        @stats[:processed] += 1
+
+        begin
+          # TAS-93: Resolve step handler from registry using full handler definition
+          # This enables method dispatch (handler_method) and resolver hints (resolver)
+          handler = @handler_registry.resolve_handler(step_data.step_definition.handler)
+
+          unless handler
+            raise Errors::ConfigurationError,
+                  "No handler found for #{step_data.step_definition.handler.callable}"
+          end
+
+          # Execute handler with unified context (TAS-96: cross-language standard)
+          context = TaskerCore::Types::StepContext.new(step_data)
+          result = handler.call(context)
+
+          # Convert handler output to standardized result
+          standardized_result = TaskerCore::Types::StepHandlerCallResult.from_handler_output(result)
+
+          # TAS-125: Check for checkpoint yield - this is a special case where
+          # we persist progress and re-dispatch instead of completing the step
+          if standardized_result.checkpoint?
+            publish_checkpoint_yield(
+              event_data: event_data,
+              checkpoint_result: standardized_result
+            )
+            @stats[:succeeded] += 1
+            logger.info('✅ Checkpoint yield submitted - step will be re-dispatched')
+            return
+          end
+
+          # Handle handler-returned error results directly (preserves retryable field)
+          # TAS-125: Handlers like inject_failure return StepHandlerCallResult.error()
+          # with explicit retryable: false for permanent failures. We must preserve this.
+          unless standardized_result.success?
+            logger.error("💥 Handler returned failure: #{standardized_result.message}")
+            logger.error("💥 Error type: #{standardized_result.error_type}, retryable: #{standardized_result.retryable}")
+
+            publish_step_completion(
+              event_data: event_data,
+              success: false,
+              result: nil,
+              error_message: standardized_result.message,
+              metadata: {
+                execution_time_ms: standardized_result.metadata&.dig('duration_ms') || 0,
+                handler_version: nil,
+                retryable: standardized_result.retryable, # CRITICAL: Preserve handler's retryable setting
+                completed_at: Time.now.utc.iso8601,
+                worker_id: 'ruby_worker',
+                worker_hostname: nil,
+                started_at: Time.now.utc.iso8601,
+                custom: {
+                  failed_at: Time.now.utc.iso8601,
+                  failed_by: 'ruby_worker',
+                  error_type: standardized_result.error_type,
+                  error_code: standardized_result.error_code,
+                  handler_class: step_data.step_definition.handler.callable,
+                  retryable: standardized_result.retryable
+                }.merge(standardized_result.metadata || {})
+              }
+            )
+
+            @stats[:failed] += 1
+            return
+          end
+
+          # Publish successful completion with properly structured metadata
+          # Match StepExecutionMetadata struct from Rust
+          publish_step_completion(
+            event_data: event_data,
+            success: true,
+            result: standardized_result.result,
+            metadata: {
+              # StepExecutionMetadata required fields
+              execution_time_ms: standardized_result.metadata&.dig('duration_ms') || 0,
+              handler_version: nil,
+              retryable: true, # Success is always retryable if it fails later
+              completed_at: Time.now.utc.iso8601,
+              worker_id: 'ruby_worker',
+              worker_hostname: nil,
+              started_at: Time.now.utc.iso8601,
+              # Additional metadata in custom field
+              custom: {
+                processed_at: Time.now.utc.iso8601,
+                processed_by: 'ruby_worker',
+                handler_class: step_data.step_definition.handler.callable
+              }.merge(standardized_result.metadata || {})
+            }
+          )
+
+          @stats[:succeeded] += 1
+          logger.info('✅ Step execution completed successfully')
+        rescue StandardError => e
+          logger.error("💥 Step execution failed: #{e.message}")
+          logger.error("💥 #{e.backtrace.first(5).join("\n💥 ")}")
+
+          # Classify error retryability using systematic classifier
+          retryable = Errors::ErrorClassifier.retryable?(e)
+
+          # Publish failure completion with properly structured metadata
+          # Match StepExecutionMetadata struct from Rust - retryable field is critical
+          publish_step_completion(
+            event_data: event_data,
+            success: false,
+            result: nil,
+            error_message: e.message,
+            metadata: {
+              # StepExecutionMetadata required fields
+              execution_time_ms: 0,
+              handler_version: nil,
+              retryable: retryable, # CRITICAL: This is what Rust reads at metadata.retryable
+              completed_at: Time.now.utc.iso8601,
+              worker_id: 'ruby_worker',
+              worker_hostname: nil,
+              started_at: Time.now.utc.iso8601,
+              # Additional error context in custom field
+              custom: {
+                failed_at: Time.now.utc.iso8601,
+                failed_by: 'ruby_worker',
+                error_class: e.class.name,
+                handler_class: step_data.step_definition.handler.callable,
+                retryable: retryable # Also in custom for debugging/redundancy
+              }
+            }
+          )
+
+          @stats[:failed] += 1
+        end
+      end
+
+      private
+
+      def subscribe_to_events
+        return if @subscribed # Guard against double subscription
+
+        TaskerCore::Worker::EventBridge.instance.subscribe_to_step_execution do |event|
+          call(event)
+        end
+        @subscribed = true
+        logger.info 'Subscribed to step execution events'
+      end
+
+      def publish_step_completion(event_data:, success:, result: nil, error_message: nil, metadata: nil)
+        completion_payload = {
+          event_id: event_data[:event_id],
+          task_uuid: event_data[:task_uuid],
+          step_uuid: event_data[:step_uuid],
+          success: success,
+          result: result,
+          metadata: metadata,
+          error_message: error_message
+        }
+
+        # TAS-65 Phase 1.5b: Propagate trace context back to Rust for distributed tracing
+        completion_payload[:trace_id] = event_data[:trace_id] if event_data[:trace_id]
+        completion_payload[:span_id] = event_data[:span_id] if event_data[:span_id]
+
+        TaskerCore::Worker::EventBridge.instance.publish_step_completion(completion_payload)
+      end
+
+      # TAS-125: Publish checkpoint yield to persist progress and trigger re-dispatch
+      def publish_checkpoint_yield(event_data:, checkpoint_result:)
+        checkpoint_data = checkpoint_result.to_checkpoint_data(
+          event_id: event_data[:event_id],
+          step_uuid: event_data[:step_uuid]
+        )
+
+        TaskerCore::Worker::EventBridge.instance.publish_step_checkpoint_yield(checkpoint_data)
+      end
+    end
+  end
+end