tasker-rb 0.1.3-arm64-darwin

data/lib/tasker_core/bootstrap.rb

@@ -0,0 +1,394 @@
+# frozen_string_literal: true
+
+module TaskerCore
+  module Worker
+    # Bootstrap orchestrator for Ruby worker
+    #
+    # Manages the complete initialization and lifecycle of the Ruby worker system,
+    # coordinating both Rust foundation layer and Ruby business logic components.
+    # This is the primary entry point for starting a TaskerCore worker process.
+    #
+    # The bootstrap process follows this sequence:
+    # 1. **Initialize Ruby Components**: EventBridge, HandlerRegistry, Subscribers
+    # 2. **Bootstrap Rust Foundation**: Start Rust worker via FFI
+    # 3. **Start Event Processing**: Begin EventPoller for step execution
+    # 4. **Register Shutdown Handlers**: Setup graceful termination on signals
+    #
+    # The Bootstrap class is a singleton, ensuring only one worker instance runs
+    # per process. It handles the complex coordination between Ruby and Rust,
+    # managing lifecycle transitions and providing health monitoring.
+    #
+    # @example Basic worker startup
+    #   # Start with default configuration
+    #   bootstrap = TaskerCore::Worker::Bootstrap.start!
+    #   # => Returns bootstrap instance in :running status
+    #
+    #   # Check if worker is running
+    #   bootstrap.running?
+    #   # => true
+    #
+    # @example Custom configuration
+    #   bootstrap = TaskerCore::Worker::Bootstrap.start!(
+    #     worker_id: "custom-worker-1",
+    #     enable_web_api: false,
+    #     event_driven_enabled: true,
+    #     deployment_mode: "Hybrid",  # PollingOnly, EventDrivenOnly, or Hybrid
+    #     namespaces: ["payments", "fulfillment", "notifications"]
+    #   )
+    #
+    # @example Health checking
+    #   status = TaskerCore::Worker::Bootstrap.instance.health_check
+    #   # => {
+    #   #   healthy: true,
+    #   #   status: :running,
+    #   #   rust: { running: true, worker_core_status: "processing" },
+    #   #   ruby: {
+    #   #     status: :running,
+    #   #     event_bridge_active: true,
+    #   #     handlers_registered: 12,
+    #   #     subscriber_active: true,
+    #   #     event_poller_active: true
+    #   #   }
+    #   # }
+    #
+    # @example Graceful shutdown
+    #   # Shutdown cleanly, completing in-flight work
+    #   TaskerCore::Worker::Bootstrap.instance.shutdown!
+    #   # => Stops Rust worker, Ruby components, runs shutdown handlers
+    #
+    # @example Custom shutdown handlers
+    #   bootstrap = TaskerCore::Worker::Bootstrap.instance
+    #   bootstrap.on_shutdown do
+    #     puts "Cleaning up resources..."
+    #     cleanup_database_connections
+    #     flush_metrics
+    #   end
+    #
+    # @example Getting comprehensive status
+    #   status = bootstrap.status
+    #   # => {
+    #   #   rust: { running: true, ... },
+    #   #   ruby: {
+    #   #     status: :running,
+    #   #     handle_stored: true,
+    #   #     handle_id: "550e8400-e29b-41d4-a716-446655440000",
+    #   #     worker_id: "ruby-worker-123",
+    #   #     event_bridge_active: true,
+    #   #     handler_registry_size: 12,
+    #   #     subscriber_active: true,
+    #   #     event_poller_active: true
+    #   #   }
+    #   # }
+    #
+    # Deployment Modes:
+    # - **PollingOnly**: Traditional polling-based coordination (highest latency, most reliable)
+    # - **EventDrivenOnly**: Pure event-driven using PostgreSQL LISTEN/NOTIFY (lowest latency)
+    # - **Hybrid**: Event-driven with polling fallback (recommended for production)
+    #
+    # Worker States:
+    # - **:initialized**: Created but not started
+    # - **:running**: Fully operational and processing events
+    # - **:shutting_down**: Graceful shutdown in progress
+    # - **:stopped**: Completely shut down
+    #
+    # Signal Handling:
+    # The bootstrap automatically registers signal handlers for:
+    # - **SIGINT** (Ctrl+C): Graceful shutdown
+    # - **SIGTERM**: Graceful shutdown
+    # - **at_exit**: Cleanup on process exit
+    #
+    # @see TaskerCore::Worker::EventPoller For event polling details
+    # @see TaskerCore::EventBridge For event coordination
+    # @see TaskerCore::Registry::HandlerRegistry For handler management
+    # @see TaskerCore::FFI For Rust FFI operations
+    class Bootstrap
+      include Singleton
+
+      attr_reader :logger, :config, :rust_handle
+
+      def initialize
+        @logger = TaskerCore::Logger.instance
+        @status = :initialized
+        @shutdown_handlers = []
+        @rust_handle = nil
+      end
+
+      # Start the worker system with optional configuration
+      def self.start!
+        instance.start!
+      end
+
+      # Main boots
+      def start!
+        logger.info 'Starting Ruby worker bootstrap'
+
+        # Initialize Ruby components first
+        initialize_ruby_components!
+
+        # Bootstrap Rust foundation via FFI
+        bootstrap_rust_foundation!
+
+        # Start event processing
+        start_event_processing!
+
+        # Register shutdown handlers
+        register_shutdown_handlers!
+
+        @status = :running
+        logger.info 'Ruby worker system started successfully'
+
+        self
+      rescue StandardError => e
+        logger.error "Failed to start worker: #{e.message}"
+        logger.error e.backtrace.join("\n")
+        shutdown!
+        raise
+      end
+
+      # Check if worker is running
+      def running?
+        @status == :running && rust_worker_running?
+      end
+
+      # Check if Rust handle is valid and running
+      def rust_handle_running?
+        return false unless @rust_handle.is_a?(Hash) &&
+                            (@rust_handle[:handle_id] || @rust_handle['handle_id'])
+
+        rust_worker_running?
+      end
+
+      # Get comprehensive status
+      def status
+        rust_status = TaskerCore::FFI.worker_status
+        {
+          rust: rust_status,
+          ruby: {
+            status: @status,
+            handle_stored: !@rust_handle.nil?,
+            handle_id: @rust_handle&.dig('handle_id') || @rust_handle&.dig(:handle_id),
+            worker_id: @rust_handle&.dig('worker_id') || @rust_handle&.dig(:worker_id),
+            event_bridge_active: EventBridge.instance.active?,
+            handler_registry_size: Registry::HandlerRegistry.instance.handlers.size,
+            subscriber_active: @step_subscriber&.active? || false,
+            event_poller_active: EventPoller.instance.active?
+          }
+        }
+      rescue StandardError => e
+        logger.error "Failed to get status: #{e.message}"
+        { error: e.message, status: @status }
+      end
+
+      # Execute a block with the Rust handle, bootstrapping if necessary
+      def with_rust_handle(&block)
+        bootstrap_rust_foundation! unless rust_handle_running?
+        block.call
+      end
+
+      # Graceful shutdown
+      def shutdown!
+        return if @status == :stopped
+
+        logger.info 'Initiating graceful shutdown'
+        @status = :shutting_down
+
+        # Transition Rust to graceful shutdown first
+        if @rust_handle
+          begin
+            TaskerCore::FFI.transition_to_graceful_shutdown
+          rescue StandardError => e
+            logger.error "Failed to transition to graceful shutdown: #{e.message}"
+          end
+        end
+
+        # Stop Ruby components
+        @step_subscriber&.stop!
+        EventBridge.instance.stop!
+        EventPoller.instance.stop!
+
+        # TAS-65: Stop domain event components
+        DomainEvents::SubscriberRegistry.instance.stop_all!
+        InProcessDomainEventPoller.instance.stop!
+
+        # Stop Rust worker and clear handle
+        if @rust_handle
+          begin
+            TaskerCore::FFI.stop_worker
+          rescue StandardError => e
+            logger.error "Failed to stop Rust worker: #{e.message}"
+          ensure
+            @rust_handle = nil
+          end
+        end
+
+        # Run custom shutdown handlers
+        @shutdown_handlers.each do |handler|
+          handler.call
+        rescue StandardError
+          nil
+        end
+
+        @status = :stopped
+        logger.info 'Worker shutdown complete'
+      end
+
+      # Register custom shutdown handler
+      def on_shutdown(&block)
+        @shutdown_handlers << block if block_given?
+      end
+
+      # Perform health check on both Ruby and Rust components
+      def health_check
+        return { healthy: false, status: @status, error: 'not_running' } unless running?
+
+        begin
+          # Get Rust worker status
+          rust_status = TaskerCore::FFI.worker_status
+          rust_running = rust_status['running'] || rust_status[:running]
+
+          # Check Ruby components
+          ruby_healthy = @status == :running &&
+                         EventBridge.instance.active? &&
+                         EventPoller.instance.active? &&
+                         Registry::HandlerRegistry.instance.handlers.any?
+
+          overall_healthy = rust_running && ruby_healthy
+
+          {
+            healthy: overall_healthy,
+            status: @status,
+            rust: {
+              running: rust_running,
+              worker_core_status: rust_status['worker_core_status'] || rust_status[:worker_core_status]
+            },
+            ruby: {
+              status: @status,
+              event_bridge_active: EventBridge.instance.active?,
+              handlers_registered: Registry::HandlerRegistry.instance.handlers.size,
+              subscriber_active: @step_subscriber&.active? || false,
+              event_poller_active: EventPoller.instance.active?,
+              # TAS-65: Domain event system status
+              domain_event_poller_active: InProcessDomainEventPoller.instance.active?,
+              domain_event_subscribers: DomainEvents::SubscriberRegistry.instance.stats
+            }
+          }
+        rescue StandardError => e
+          logger.error "Health check failed: #{e.message}"
+          {
+            healthy: false,
+            status: @status,
+            error: e.message
+          }
+        end
+      end
+
+      private
+
+      def detect_namespaces
+        # Auto-detect from registered handlers
+        Registry::HandlerRegistry.instance.registered_handlers.map do |handler_class|
+          handler_class.namespace if handler_class.respond_to?(:namespace)
+        end.compact.uniq
+      end
+
+      def initialize_ruby_components!
+        logger.info 'Initializing Ruby components...'
+
+        # Initialize event bridge
+        EventBridge.instance
+
+        # Initialize handler registry (bootstrap happens automatically)
+        Registry::HandlerRegistry.instance
+
+        # Initialize step execution subscriber
+        @step_subscriber = StepExecutionSubscriber.new
+
+        logger.info 'Ruby components initialized'
+      end
+
+      def bootstrap_rust_foundation!
+        # Check if we already have a running handle
+        if rust_handle_running?
+          logger.debug 'Rust worker foundation already running, reusing handle'
+          return @rust_handle
+        end
+
+        logger.info 'Bootstrapping Rust worker foundation...'
+
+        # Bootstrap the worker and store the handle result
+        result = TaskerCore::FFI.bootstrap_worker
+        logger.info "Rust bootstrap result: #{result.inspect}"
+
+        # Check if it was already running or newly started
+        # Handle both string and symbol keys from Rust FFI
+        status = result['status'] || result[:status]
+        worker_id = result['worker_id'] || result[:worker_id]
+
+        if status == 'already_running'
+          logger.info 'Worker system was already running, reusing existing handle'
+        elsif status == 'started'
+          logger.info "New worker system started with ID: #{worker_id}"
+        else
+          raise "Unexpected bootstrap status: #{status}"
+        end
+
+        # Store the handle information
+        @rust_handle = result
+
+        # Verify it's running
+        status = TaskerCore::FFI.worker_status
+        # Handle both string and symbol keys from Rust FFI
+        running = status['running'] || status[:running]
+        unless running
+          @rust_handle = nil
+          raise "Rust worker failed to start: #{status.inspect}"
+        end
+
+        handle_id = @rust_handle['handle_id'] || @rust_handle[:handle_id]
+        logger.info "Rust foundation bootstrapped with handle: #{handle_id}"
+        @rust_handle
+      end
+
+      def start_event_processing!
+        logger.info 'Starting event processing...'
+
+        # Start the EventPoller to poll for step execution events from Rust
+        EventPoller.instance.start!
+
+        # NOTE: StepExecutionSubscriber already subscribes to step execution events
+        # in its initializer, so we don't need to subscribe again here.
+        # Duplicate subscriptions cause the same event to be processed twice,
+        # leading to double state transitions.
+
+        # TAS-65: Start in-process domain event poller for fast events
+        InProcessDomainEventPoller.instance.start!
+
+        # TAS-65: Start domain event subscribers
+        DomainEvents::SubscriberRegistry.instance.start_all!
+
+        logger.info 'Event processing started (step events + domain events)'
+      end
+
+      def register_shutdown_handlers!
+        # Graceful shutdown on signals
+        %w[INT TERM].each do |signal|
+          Signal.trap(signal) do
+            Thread.new { shutdown! }
+          end
+        end
+
+        # Shutdown on exit
+        at_exit { shutdown! if running? }
+      end
+
+      def rust_worker_running?
+        status = TaskerCore::FFI.worker_status
+        # Handle both string and symbol keys from Rust FFI
+        running = status['running'] || status[:running]
+        running == true
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/tasker_core/client.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module TaskerCore
+  # High-level client wrapper around the TaskerCore FFI client methods.
+  #
+  # The raw FFI exposes `TaskerCore::FFI.client_create_task(hash)` and similar
+  # methods that require callers to construct complete request hashes with all
+  # required fields (initiator, source_system, reason, etc.) and return plain
+  # hashes. This module provides keyword-argument methods with sensible defaults
+  # and wraps responses into typed `ClientTypes::*` Dry::Struct objects.
+  #
+  # @example Creating a task with defaults
+  #   response = TaskerCore::Client.create_task(
+  #     name: 'process_order',
+  #     namespace: 'ecommerce',
+  #     context: { order_id: 123 }
+  #   )
+  #   response.task_uuid  # => "550e8400-..."
+  #   response.status     # => "pending"
+  #
+  # @example Getting a task
+  #   task = TaskerCore::Client.get_task("550e8400-...")
+  #   task.name       # => "process_order"
+  #   task.namespace  # => "ecommerce"
+  #
+  # @example Listing tasks with filters
+  #   list = TaskerCore::Client.list_tasks(namespace: 'ecommerce', limit: 10)
+  #   list.tasks.size  # => 3
+  #   list.pagination  # => { "total_count" => 42, ... }
+  module Client
+    module_function
+
+    # Create a task via the orchestration API.
+    #
+    # @param name [String] Named task template name
+    # @param namespace [String] Task namespace (default: "default")
+    # @param context [Hash] Workflow context passed to step handlers
+    # @param version [String] Template version (default: "1.0.0")
+    # @param initiator [String] Who initiated the request
+    # @param source_system [String] Originating system
+    # @param reason [String] Reason for creating the task
+    # @param options [Hash] Additional TaskRequest fields
+    # @return [ClientTypes::TaskResponse, Hash] Typed response or raw hash on schema mismatch
+    def create_task(name:, namespace: 'default', context: {}, version: '1.0.0',
+                    initiator: 'tasker-core-ruby', source_system: 'tasker-core',
+                    reason: 'Task requested', **options)
+      request = {
+        'name' => name,
+        'namespace' => namespace,
+        'version' => version,
+        'context' => deep_to_hash(context),
+        'initiator' => initiator,
+        'source_system' => source_system,
+        'reason' => reason
+      }
+      options.each { |k, v| request[k.to_s] = v }
+
+      response = TaskerCore::FFI.client_create_task(request)
+      wrap_response(response, Types::ClientTaskResponse)
+    end
+
+    # Get a task by UUID.
+    #
+    # @param task_uuid [String] The task UUID
+    # @return [ClientTypes::TaskResponse, Hash] Typed response or raw hash
+    def get_task(task_uuid)
+      response = TaskerCore::FFI.client_get_task(task_uuid.to_s)
+      wrap_response(response, Types::ClientTaskResponse)
+    end
+
+    # List tasks with optional filtering and pagination.
+    #
+    # @param limit [Integer] Maximum number of results (default: 50)
+    # @param offset [Integer] Pagination offset (default: 0)
+    # @param namespace [String, nil] Filter by namespace
+    # @param status [String, nil] Filter by status
+    # @return [ClientTypes::TaskListResponse, Hash] Typed response or raw hash
+    def list_tasks(limit: 50, offset: 0, namespace: nil, status: nil)
+      response = TaskerCore::FFI.client_list_tasks(limit, offset, namespace, status)
+      wrap_response(response, Types::ClientTaskListResponse)
+    end
+
+    # Cancel a task by UUID.
+    #
+    # @param task_uuid [String] The task UUID
+    # @return [Hash] Cancellation result
+    def cancel_task(task_uuid)
+      TaskerCore::FFI.client_cancel_task(task_uuid.to_s)
+    end
+
+    # List workflow steps for a task.
+    #
+    # @param task_uuid [String] The task UUID
+    # @return [Array<ClientTypes::StepResponse>, Array<Hash>] Typed steps or raw hashes
+    def list_task_steps(task_uuid)
+      response = TaskerCore::FFI.client_list_task_steps(task_uuid.to_s)
+      return response unless response.is_a?(Array)
+
+      response.map { |step| wrap_response(step, Types::ClientStepResponse) }
+    end
+
+    # Get a specific workflow step.
+    #
+    # @param task_uuid [String] The task UUID
+    # @param step_uuid [String] The step UUID
+    # @return [ClientTypes::StepResponse, Hash] Typed response or raw hash
+    def get_step(task_uuid, step_uuid)
+      response = TaskerCore::FFI.client_get_step(task_uuid.to_s, step_uuid.to_s)
+      wrap_response(response, Types::ClientStepResponse)
+    end
+
+    # Get audit history for a workflow step.
+    #
+    # @param task_uuid [String] The task UUID
+    # @param step_uuid [String] The step UUID
+    # @return [Array<ClientTypes::StepAuditResponse>, Array<Hash>] Typed audit entries or raw hashes
+    def get_step_audit_history(task_uuid, step_uuid)
+      response = TaskerCore::FFI.client_get_step_audit_history(task_uuid.to_s, step_uuid.to_s)
+      return response unless response.is_a?(Array)
+
+      response.map { |entry| wrap_response(entry, Types::ClientStepAuditResponse) }
+    end
+
+    # Check orchestration API health.
+    #
+    # @return [ClientTypes::HealthResponse, Hash] Typed response or raw hash
+    def health_check
+      response = TaskerCore::FFI.client_health_check
+      wrap_response(response, Types::ClientHealthResponse)
+    end
+
+    # @api private
+    # Wrap a raw FFI hash response into a Dry::Struct type.
+    # Falls back to the raw hash if the schema doesn't match,
+    # providing forward-compatibility when the API adds new fields.
+    def wrap_response(raw, type_class)
+      return raw unless raw.is_a?(Hash)
+
+      # Dry::Struct requires symbolized keys; raw FFI returns string keys
+      type_class.new(raw.transform_keys(&:to_sym))
+    rescue Dry::Struct::Error, KeyError, Dry::Types::ConstraintError
+      raw
+    end
+
+    # @api private
+    # Recursively convert ActionController::Parameters (and similar) to plain hashes/arrays.
+    def deep_to_hash(obj)
+      case obj
+      when Hash
+        obj.transform_values { |v| deep_to_hash(v) }
+      when Array
+        obj.map { |v| deep_to_hash(v) }
+      else
+        # Handle ActionController::Parameters if available (Rails contexts)
+        if obj.respond_to?(:to_unsafe_h)
+          obj.to_unsafe_h.transform_values { |v| deep_to_hash(v) }
+        else
+          obj
+        end
+      end
+    end
+
+    private_class_method :wrap_response, :deep_to_hash
+  end
+end