tasker-rb 0.1.1

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

data/lib/tasker_core/observability/types.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+require 'dry-types'
+
+module TaskerCore
+  module Observability
+    # Type definitions for observability data structures
+    #
+    # These types use dry-struct for automatic validation and provide
+    # structured access to health, metrics, and configuration data.
+    module Types
+      include Dry.Types()
+
+      # ==========================================================================
+      # Health Types
+      # ==========================================================================
+
+      # Basic health check response
+      class BasicHealth < Dry::Struct
+        attribute :status, Types::Strict::String
+        attribute :worker_id, Types::Strict::String
+        attribute :timestamp, Types::Strict::String
+      end
+
+      # Individual health check result
+      class HealthCheck < Dry::Struct
+        attribute :status, Types::Strict::String
+        attribute :message, Types::Strict::String.optional
+        attribute :duration_ms, Types::Strict::Integer
+        attribute :last_checked, Types::Strict::String
+      end
+
+      # Worker system information
+      class WorkerSystemInfo < Dry::Struct
+        attribute :version, Types::Strict::String
+        attribute :environment, Types::Strict::String
+        attribute :uptime_seconds, Types::Strict::Integer
+        attribute :worker_type, Types::Strict::String
+        attribute :database_pool_size, Types::Strict::Integer
+        attribute :command_processor_active, Types::Strict::Bool
+        attribute :supported_namespaces, Types::Strict::Array.of(Types::Strict::String)
+      end
+
+      # Detailed health check response
+      class DetailedHealth < Dry::Struct
+        attribute :status, Types::Strict::String
+        attribute :timestamp, Types::Strict::String
+        attribute :worker_id, Types::Strict::String
+        attribute :checks, Types::Strict::Hash.map(Types::Strict::String, HealthCheck)
+        attribute :system_info, WorkerSystemInfo
+      end
+
+      # ==========================================================================
+      # Metrics Types
+      # ==========================================================================
+
+      # Event router statistics
+      class EventRouterStats < Dry::Struct
+        attribute :total_routed, Types::Strict::Integer
+        attribute :durable_routed, Types::Strict::Integer
+        attribute :fast_routed, Types::Strict::Integer
+        attribute :broadcast_routed, Types::Strict::Integer
+        attribute :fast_delivery_errors, Types::Strict::Integer
+        attribute :routing_errors, Types::Strict::Integer
+      end
+
+      # In-process event bus statistics
+      class InProcessEventBusStats < Dry::Struct
+        attribute :total_events_dispatched, Types::Strict::Integer
+        attribute :rust_handler_dispatches, Types::Strict::Integer
+        attribute :ffi_channel_dispatches, Types::Strict::Integer
+        attribute :rust_handler_errors, Types::Strict::Integer
+        attribute :ffi_channel_drops, Types::Strict::Integer
+        attribute :rust_subscriber_patterns, Types::Strict::Integer
+        attribute :rust_handler_count, Types::Strict::Integer
+        attribute :ffi_subscriber_count, Types::Strict::Integer
+      end
+
+      # Domain event statistics
+      class DomainEventStats < Dry::Struct
+        attribute :router, EventRouterStats
+        attribute :in_process_bus, InProcessEventBusStats
+        attribute :captured_at, Types::Strict::String
+        attribute :worker_id, Types::Strict::String
+      end
+
+      # ==========================================================================
+      # Template Types
+      # ==========================================================================
+
+      # Template cache statistics
+      class CacheStats < Dry::Struct
+        attribute :total_entries, Types::Strict::Integer
+        attribute :hits, Types::Strict::Integer
+        attribute :misses, Types::Strict::Integer
+        attribute :evictions, Types::Strict::Integer
+        attribute :last_maintenance, Types::Strict::String.optional
+      end
+
+      # Cache operation result
+      class CacheOperationResult < Dry::Struct
+        attribute :success, Types::Strict::Bool
+        attribute :message, Types::Strict::String
+        attribute :timestamp, Types::Strict::String
+      end
+
+      # Template validation result
+      class TemplateValidation < Dry::Struct
+        attribute :valid, Types::Strict::Bool
+        attribute :namespace, Types::Strict::String
+        attribute :name, Types::Strict::String
+        attribute :version, Types::Strict::String
+        attribute :handler_count, Types::Strict::Integer
+        attribute :issues, Types::Strict::Array.of(Types::Strict::String)
+        attribute :handler_metadata, Types::Strict::Hash.optional
+      end
+
+      # ==========================================================================
+      # Config Types (TAS-150: whitelist-only safe config exposure)
+      # ==========================================================================
+
+      # Configuration metadata (non-sensitive system info)
+      class ConfigMetadata < Dry::Struct
+        attribute :timestamp, Types::Strict::String
+        attribute :environment, Types::Strict::String
+        attribute :version, Types::Strict::String
+      end
+
+      # Non-sensitive auth configuration summary
+      class SafeAuthConfig < Dry::Struct
+        attribute :enabled, Types::Strict::Bool
+        attribute :verification_method, Types::Strict::String
+        attribute :jwt_issuer, Types::Strict::String
+        attribute :jwt_audience, Types::Strict::String
+        attribute :api_key_header, Types::Strict::String
+        attribute :api_key_count, Types::Strict::Integer
+        attribute :strict_validation, Types::Strict::Bool
+        attribute :allowed_algorithms, Types::Strict::Array.of(Types::Strict::String)
+      end
+
+      # Non-sensitive messaging configuration
+      class SafeMessagingConfig < Dry::Struct
+        attribute :backend, Types::Strict::String
+        attribute :queues, Types::Strict::Array.of(Types::Strict::String)
+      end
+
+      # Worker configuration response (safe fields only)
+      class RuntimeConfig < Dry::Struct
+        attribute :metadata, ConfigMetadata
+        attribute :worker_id, Types::Strict::String
+        attribute :worker_type, Types::Strict::String
+        attribute :auth, SafeAuthConfig
+        attribute :messaging, SafeMessagingConfig
+      end
+    end
+  end
+end