tasker-rb 0.1.1

data/lib/tasker_core/types/step_handler_call_result.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+require 'dry-types'
+
+module TaskerCore
+  module Types
+    # Standardized result structure for step handler call methods
+    #
+    # This provides a consistent interface for all step handlers to return
+    # structured results with proper metadata for observability.
+    #
+    # Success example:
+    #   StepHandlerCallResult.success(
+    #     result: { validated_items: [...], total: 100.00 },
+    #     metadata: {
+    #       operation: "validate_order",
+    #       item_count: 3,
+    #       processing_time_ms: 125
+    #     }
+    #   )
+    #
+    # Error example (typically raised as exception):
+    #   raise TaskerCore::Errors::PermanentError.new(
+    #     "Invalid order total",
+    #     error_code: "INVALID_TOTAL",
+    #     context: { total: -50, min_allowed: 0 }
+    #   )
+    module StepHandlerCallResult
+      class Success < Dry::Struct
+        # Always true for success results
+        attribute :success, Types::Bool.default(true)
+
+        # The actual result data from the step handler
+        # Can be any JSON-serializable value (Hash, Array, String, Number, etc.)
+        attribute :result, Types::Any
+
+        # Optional metadata for observability
+        attribute(:metadata, Types::Hash.default { {} })
+
+        # Predicate method for checking if result is successful
+        def success?
+          success
+        end
+
+        # TAS-125: Not a checkpoint - this is a final success result
+        def checkpoint?
+          false
+        end
+      end
+
+      class Error < Dry::Struct
+        # Always false for error results
+        attribute :success, Types::Bool.default(false)
+
+        # Error type (matches our error class names)
+        attribute :error_type,
+                  Types::String.enum('PermanentError', 'RetryableError', 'ValidationError', 'UnexpectedError',
+                                     'StepCompletionError')
+
+        # Human-readable error message
+        attribute :message, Types::String
+
+        # Optional error code for categorization
+        attribute :error_code, Types::String.optional
+
+        # Whether this error should trigger a retry
+        attribute :retryable, Types::Bool.default(false)
+
+        # Additional error context and metadata
+        attribute(:metadata, Types::Hash.default { {} })
+
+        # Predicate method for checking if result is successful
+        def success?
+          success
+        end
+
+        # TAS-125: Not a checkpoint - this is a final error result
+        def checkpoint?
+          false
+        end
+      end
+
+      # TAS-125: Checkpoint yield result for batch processing
+      #
+      # This result type signals that a batch processing handler wants to
+      # persist its progress (checkpoint) and be re-dispatched for continued
+      # processing. Unlike Success or Error, this is an intermediate state
+      # that doesn't complete the step.
+      #
+      # Example:
+      #   StepHandlerCallResult.checkpoint_yield(
+      #     cursor: 1000,
+      #     items_processed: 1000,
+      #     accumulated_results: { total_amount: 50000.00 }
+      #   )
+      class CheckpointYield < Dry::Struct
+        # Position to resume from (Integer, String, or Hash)
+        # For offset-based pagination: Integer (row number)
+        # For cursor-based pagination: String or Hash (opaque cursor)
+        attribute :cursor, Types::Any
+
+        # Total number of items processed so far (cumulative across all yields)
+        attribute :items_processed, Types::Integer.constrained(gteq: 0)
+
+        # Optional partial aggregations to carry forward to next iteration
+        # Useful for running totals, counters, or intermediate calculations
+        attribute :accumulated_results, Types::Any.optional
+
+        # This is a checkpoint, not a final result
+        def checkpoint?
+          true
+        end
+
+        # Not successful yet - still in progress
+        def success?
+          false
+        end
+
+        # Convert to hash for FFI transport
+        def to_checkpoint_data(event_id:, step_uuid:)
+          {
+            event_id: event_id,
+            step_uuid: step_uuid,
+            cursor: cursor,
+            items_processed: items_processed,
+            accumulated_results: accumulated_results
+          }
+        end
+      end
+
+      # Factory methods for creating results
+      class << self
+        # Create a success result
+        #
+        # @param result [Object] The result data (must be JSON-serializable)
+        # @param metadata [Hash] Optional metadata for observability
+        # @return [Success] A success result instance
+        def success(result:, metadata: {})
+          Success.new(
+            success: true,
+            result: result,
+            metadata: metadata
+          )
+        end
+
+        # Create an error result
+        #
+        # @param error_type [String] Type of error (PermanentError, RetryableError, etc.)
+        # @param message [String] Human-readable error message
+        # @param error_code [String, nil] Optional error code
+        # @param retryable [Boolean] Whether to retry this error
+        # @param metadata [Hash] Additional error context
+        # @return [Error] An error result instance
+        def error(error_type:, message:, error_code: nil, retryable: false, metadata: {})
+          Error.new(
+            success: false,
+            error_type: error_type,
+            message: message,
+            error_code: error_code,
+            retryable: retryable,
+            metadata: metadata
+          )
+        end
+
+        # TAS-125: Create a checkpoint yield result for batch processing
+        #
+        # Use this when your batch processing handler wants to persist progress
+        # and be re-dispatched for continued processing.
+        #
+        # @param cursor [Integer, String, Hash] Position to resume from
+        # @param items_processed [Integer] Total items processed so far (cumulative)
+        # @param accumulated_results [Hash, nil] Optional partial aggregations
+        # @return [CheckpointYield] A checkpoint yield result instance
+        #
+        # @example Yield checkpoint with offset cursor
+        #   StepHandlerCallResult.checkpoint_yield(
+        #     cursor: 1000,
+        #     items_processed: 1000,
+        #     accumulated_results: { total_amount: 50000.00, row_count: 1000 }
+        #   )
+        #
+        # @example Yield checkpoint with opaque cursor
+        #   StepHandlerCallResult.checkpoint_yield(
+        #     cursor: { page_token: "eyJsYXN0X2lkIjo5OTl9" },
+        #     items_processed: 500
+        #   )
+        def checkpoint_yield(cursor:, items_processed:, accumulated_results: nil)
+          CheckpointYield.new(
+            cursor: cursor,
+            items_processed: items_processed,
+            accumulated_results: accumulated_results
+          )
+        end
+
+        # Convert arbitrary handler output to a StepHandlerCallResult
+        #
+        # @param output [Object] The output from a handler's call method
+        # @return [Success, Error, CheckpointYield] A properly structured result
+        def from_handler_output(output)
+          case output
+          when Success, Error, CheckpointYield
+            # Already a proper result
+            output
+          when Hash
+            # Check if it looks like a result structure
+            if output[:success] == true || output['success'] == true
+              # Looks like a success result
+              Success.new(
+                success: true,
+                result: output[:result] || output['result'] || output,
+                metadata: output[:metadata] || output['metadata'] || {}
+              )
+            elsif output[:success] == false || output['success'] == false
+              # Looks like an error result
+              Error.new(
+                success: false,
+                error_type: output[:error_type] || output['error_type'] || 'UnexpectedError',
+                message: output[:message] || output['message'] || 'Unknown error',
+                error_code: output[:error_code] || output['error_code'],
+                retryable: output[:retryable] || output['retryable'] || false,
+                metadata: output[:metadata] || output['metadata'] || {}
+              )
+            else
+              # Just a hash of results - wrap it as success
+              Success.new(
+                success: true,
+                result: output,
+                metadata: {
+                  wrapped: true,
+                  original_type: 'Hash'
+                }
+              )
+            end
+          else
+            # Any other type - wrap as success
+            Success.new(
+              success: true,
+              result: output,
+              metadata: {
+                wrapped: true,
+                original_type: output.class.name
+              }
+            )
+          end
+        end
+
+        # Create error result from an exception
+        #
+        # @param exception [Exception] The exception that was raised
+        # @return [Error] An error result instance
+        def from_exception(exception)
+          case exception
+          when TaskerCore::Errors::PermanentError
+            Error.new(
+              success: false,
+              error_type: 'PermanentError',
+              message: exception.message,
+              error_code: exception.error_code,
+              retryable: false,
+              metadata: {
+                context: exception.context || {}
+              }.compact
+            )
+          when TaskerCore::Errors::RetryableError
+            Error.new(
+              success: false,
+              error_type: 'RetryableError',
+              message: exception.message,
+              error_code: nil, # RetryableError doesn't have error_code
+              retryable: true,
+              metadata: {
+                context: exception.context || {},
+                retry_after: exception.retry_after
+              }.compact
+            )
+          when TaskerCore::Errors::ValidationError
+            Error.new(
+              success: false,
+              error_type: 'ValidationError',
+              message: exception.message,
+              error_code: exception.error_code,
+              retryable: false,
+              metadata: {
+                context: exception.context || {},
+                field: exception.field
+              }.compact
+            )
+          else
+            # Generic exception
+            Error.new(
+              success: false,
+              error_type: 'UnexpectedError',
+              message: exception.message,
+              error_code: nil,
+              retryable: true,
+              metadata: {
+                exception_class: exception.class.name,
+                stack_trace: exception.backtrace&.first(10)&.join("\n")
+              }.compact
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tasker_core/types/step_message.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+require 'dry-types'
+
+module TaskerCore
+  module Types
+    # Define custom types for the system
+    include Dry.Types()
+
+    # Custom types for TaskerCore - Essential validation types
+    Namespace = Types::String.constrained(filled: true)
+    StepName = Types::String.constrained(filled: true)
+    TaskName = Types::String # Allow empty strings for task names
+    TaskVersion = Types::String.constrained(filled: true)
+    Priority = Types::Integer.constrained(gteq: 1, lteq: 10)
+    RetryCount = Types::Integer.constrained(gteq: 0)
+    TimeoutMs = Types::Integer.constrained(gt: 0)
+
+    # Lightweight struct for execution context (replaces OpenStruct)
+    ExecutionContext = Struct.new(:step, :task, keyword_init: true)
+
+    # Lightweight struct for queue message envelope (replaces OpenStruct)
+    QueueMessageEnvelope = Struct.new(:msg_id, :read_ct, :enqueued_at, :vt, :message, keyword_init: true)
+
+    # Minimal StepMessage stub for registry compatibility only
+    # This is a lightweight replacement for the complex 324-line StepMessage class
+    # Used only for temporary registry lookup objects in queue_worker.rb
+    class StepMessage
+      attr_reader :step_name, :namespace, :task_name, :task_version, :step_id, :task_uuid, :step_uuid
+
+      def initialize(attrs = {})
+        @step_name = attrs[:step_name]
+        @namespace = attrs[:namespace]
+        @task_name = attrs[:task_name]
+        @task_version = attrs[:task_version]
+        @step_id = attrs[:step_id]
+        @task_uuid = attrs[:task_uuid]
+        @step_uuid = attrs[:step_uuid]
+      end
+
+      # Minimal interface for registry compatibility
+      def execution_context
+        ExecutionContext.new(
+          step: {
+            step_name: @step_name,
+            workflow_step_id: @step_id,
+            step_uuid: @step_uuid
+          },
+          task: {
+            task_uuid: @task_uuid,
+            namespace: @namespace,
+            task_name: @task_name,
+            task_version: @task_version
+          }
+        )
+      end
+    end
+
+    # Simple queue message data for new UUID-based architecture
+    # This is the core message structure for the simplified messaging system
+    # Used extensively in pgmq_client.rb and queue_worker.rb
+    class SimpleQueueMessageData < Dry::Struct
+      transform_keys(&:to_sym)
+
+      # pgmq envelope data
+      attribute :msg_id, Types::Integer
+      attribute :read_ct, Types::Integer
+      # Accept either String or Time for timestamps (PostgreSQL may return either)
+      attribute :enqueued_at, Types::String | Types::Instance(Time)
+      attribute :vt, Types::String | Types::Instance(Time)
+
+      # Simple message content (UUID-based)
+      attribute :message, Types::Hash.schema(
+        task_uuid: Types::String,
+        step_uuid: Types::String,
+        ready_dependency_step_uuids: Types::Array.of(Types::String)
+      )
+
+      # Convenience accessor for the simple message
+      def step_message
+        @step_message ||= SimpleStepMessage.new(message)
+      end
+
+      def queue_message
+        @queue_message ||= QueueMessageEnvelope.new(
+          msg_id: msg_id,
+          read_ct: read_ct,
+          enqueued_at: enqueued_at,
+          vt: vt,
+          message: message
+        )
+      end
+
+      # Delegate UUID accessors to the message hash for convenience
+      def task_uuid
+        message[:task_uuid]
+      end
+
+      def step_uuid
+        message[:step_uuid]
+      end
+
+      def ready_dependency_step_uuids
+        message[:ready_dependency_step_uuids]
+      end
+    end
+
+    # SimpleStepMessage is defined in simple_message.rb with full UUID validation
+    # This avoids duplicate class definitions
+  end
+end

data/lib/tasker_core/types/step_types.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+require 'dry-types'
+require 'socket'
+
+module TaskerCore
+  module Types
+    # Step-related type definitions for workflow execution
+    module StepTypes
+      module Types
+        include Dry.Types()
+      end
+
+      # Step execution status enum
+      class StepExecutionStatus < Dry::Struct
+        attribute :status, Types::String.enum('success', 'failed', 'in_progress', 'cancelled', 'timeout')
+
+        def success?
+          status == 'success'
+        end
+
+        def completed?
+          status == 'success'
+        end
+
+        def failed?
+          status == 'failed'
+        end
+
+        def in_progress?
+          status == 'in_progress'
+        end
+      end
+
+      # Step execution error details
+      class StepExecutionError < Dry::Struct
+        attribute :error_type,
+                  Types::String.enum(
+                    'HandlerNotFound',
+                    'HandlerException',
+                    'ProcessingError',
+                    'MaxRetriesExceeded',
+                    'RecordNotFound',
+                    'UnexpectedError',
+                    'PermanentError',
+                    'RetryableError'
+                  )
+        attribute :message, Types::String
+        attribute :retryable, Types::Bool.default(true)
+        attribute? :error_code, Types::String.optional
+        attribute? :stack_trace, Types::String.optional
+
+        def to_h
+          {
+            message: message,
+            error_type: error_type,
+            status_code: nil,
+            context: {
+              error_code: error_code,
+              stack_trace: stack_trace
+            }.compact,
+            retryable: retryable
+          }.compact
+        end
+      end
+
+      # Step execution result from pgmq worker processing
+      class StepResult < Dry::Struct
+        attribute :task_uuid, Types::String
+        attribute :step_uuid, Types::String
+        attribute :status, StepExecutionStatus
+        attribute :execution_time_ms, Types::Integer
+        attribute :completed_at, Types::Constructor(Time) { |value| value.is_a?(Time) ? value : Time.parse(value.to_s) }
+        attribute? :result_data, Types::Any.optional
+        attribute? :error, StepExecutionError.optional
+        attribute? :orchestration_metadata, Types::Hash.optional
+
+        # Factory methods for creating results
+        def self.success(step_uuid:, task_uuid:, result_data: nil, execution_time_ms: 0)
+          new(
+            step_uuid: step_uuid,
+            task_uuid: task_uuid,
+            status: StepExecutionStatus.new(status: 'success'),
+            execution_time_ms: execution_time_ms,
+            completed_at: Time.now,
+            result_data: result_data
+          )
+        end
+
+        def self.in_progress(step_uuid:, task_uuid:, result_data: nil, execution_time_ms: 0)
+          new(
+            step_uuid: step_uuid,
+            task_uuid: task_uuid,
+            status: StepExecutionStatus.new(status: 'in_progress'),
+            execution_time_ms: execution_time_ms,
+            completed_at: Time.now,
+            result_data: result_data
+          )
+        end
+
+        def self.failure(step_uuid:, task_uuid:, error:, execution_time_ms: 0)
+          new(
+            step_uuid: step_uuid,
+            task_uuid: task_uuid,
+            status: StepExecutionStatus.new(status: 'failed'),
+            execution_time_ms: execution_time_ms,
+            completed_at: Time.now,
+            error: error
+          )
+        end
+
+        # Convenience methods
+        def success?
+          status.success?
+        end
+
+        def failed?
+          status.failed?
+        end
+
+        # Convert to hash for message serialization matching Rust StepResultMessage structure
+        def to_h
+          {
+            step_uuid: step_uuid,
+            task_uuid: task_uuid,
+            status: map_status_to_rust_enum(status.status),
+            results: result_data,
+            error: error&.to_h,
+            execution_time_ms: execution_time_ms,
+            orchestration_metadata: orchestration_metadata,
+            metadata: {
+              worker_id: "ruby_worker_#{Process.pid}",
+              worker_hostname: Socket.gethostname,
+              started_at: (completed_at - (execution_time_ms / 1000.0)).utc.iso8601,
+              completed_at: completed_at.utc.iso8601,
+              custom: {}
+            }
+          }.compact
+        end
+
+        private
+
+        # Map Ruby status strings to Rust enum variants
+        def map_status_to_rust_enum(status_string)
+          case status_string
+          when 'success'
+            'Success'
+          when 'failed'
+            'Failed'
+          when 'cancelled'
+            'Cancelled'
+          when 'timeout'
+            'Timeout'
+          when 'in_progress'
+            'InProgress'
+          else # rubocop:disable Lint/DuplicateBranch
+            'Failed' # fallback
+          end
+        end
+      end
+
+      # Step completion struct for workflow step results
+      class StepCompletion < Dry::Struct
+        attribute :step_name, Types::Coercible::String
+        attribute :status, Types::Coercible::String.enum('complete', 'failed', 'pending')
+        attribute :results, Types::Hash.default({}.freeze)
+        attribute :duration_ms, Types::Integer.optional
+        attribute :completed_at, Types::Constructor(Time).optional
+        attribute :error_message, Types::Coercible::String.optional
+
+        # Validation for step completion data
+        def valid?
+          !step_name.empty? &&
+            %w[complete failed pending].include?(status) &&
+            results.is_a?(Hash)
+        end
+
+        # Check if step completed successfully
+        def completed?
+          status == 'complete'
+        end
+
+        # Check if step failed
+        def failed?
+          status == 'failed'
+        end
+
+        # Check if step is still pending
+        def pending?
+          status == 'pending'
+        end
+
+        # Get execution duration in seconds
+        def duration_seconds
+          return nil unless duration_ms
+
+          duration_ms / 1000.0
+        end
+
+        def to_s
+          "#<StepCompletion #{step_name} status=#{status} duration=#{duration_seconds}s>"
+        end
+      end
+    end
+  end
+end