tasker-rb 0.1.3-arm64-darwin

data/lib/tasker_core/domain_events/base_publisher.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module TaskerCore
+  module DomainEvents
+    # TAS-65: Base class for custom domain event publishers
+    #
+    # Domain event publishers transform step execution results into business events.
+    # They are declared in task template YAML via the `publisher:` field and registered
+    # at bootstrap time.
+    #
+    # @example Creating a custom publisher
+    #   class PaymentEventPublisher < TaskerCore::DomainEvents::BasePublisher
+    #     def name
+    #       'PaymentEventPublisher'
+    #     end
+    #
+    #     def transform_payload(step_result, event_declaration)
+    #       # Extract business-specific payload from step result
+    #       {
+    #         payment_id: step_result[:result][:payment_id],
+    #         amount: step_result[:result][:amount],
+    #         currency: step_result[:result][:currency],
+    #         status: step_result[:success] ? 'succeeded' : 'failed'
+    #       }
+    #     end
+    #
+    #     def should_publish?(step_result, event_declaration)
+    #       # Only publish for successful payments
+    #       step_result[:success] && step_result[:result][:payment_id].present?
+    #     end
+    #   end
+    #
+    # @example Registering a custom publisher
+    #   TaskerCore::DomainEvents::PublisherRegistry.instance.register(
+    #     PaymentEventPublisher.new
+    #   )
+    #
+    # @example YAML declaration
+    #   steps:
+    #     - name: process_payment
+    #       publishes_events:
+    #         - name: payment.processed
+    #           publisher: PaymentEventPublisher
+    #           delivery_mode: durable
+    #           condition: success
+    #
+    class BasePublisher
+      attr_reader :logger
+
+      def initialize
+        @logger = TaskerCore::Logger.instance
+      end
+
+      # The publisher name used for registry lookup
+      # Must match the `publisher:` field in YAML
+      #
+      # @return [String] The publisher name
+      def name
+        raise NotImplementedError, "#{self.class} must implement #name"
+      end
+
+      # Transform step result into business event payload
+      #
+      # Override this to customize the event payload for your domain.
+      # The default implementation returns the step result as-is.
+      #
+      # @param step_result [Hash] The step execution result
+      #   - :success [Boolean] Whether the step succeeded
+      #   - :result [Hash] The step handler's return value
+      #   - :metadata [Hash] Execution metadata
+      # @param event_declaration [Hash] The event declaration from YAML
+      #   - :name [String] The event name (e.g., "order.processed")
+      #   - :delivery_mode [String] "durable" or "fast"
+      #   - :condition [String] "success", "failure", or "always"
+      # @param step_context [Hash] The step execution context
+      #   - :task [Hash] Task information
+      #   - :workflow_step [Hash] Workflow step information
+      #   - :step_definition [Hash] Step definition from YAML
+      #
+      # @return [Hash] The business event payload to publish
+      def transform_payload(step_result, _event_declaration, _step_context = nil)
+        step_result[:result] || {}
+      end
+
+      # Determine if this event should be published
+      #
+      # Override this to add custom publishing conditions beyond the
+      # YAML `condition:` field. The YAML condition is evaluated first,
+      # then this method is called.
+      #
+      # @param step_result [Hash] The step execution result
+      # @param event_declaration [Hash] The event declaration from YAML
+      # @param step_context [Hash] The step execution context
+      #
+      # @return [Boolean] true if the event should be published
+      def should_publish?(_step_result, _event_declaration, _step_context = nil)
+        true
+      end
+
+      # Add additional metadata to the event
+      #
+      # Override this to add custom metadata fields to the event.
+      # Default returns empty hash.
+      #
+      # @param step_result [Hash] The step execution result
+      # @param event_declaration [Hash] The event declaration from YAML
+      # @param step_context [Hash] The step execution context
+      #
+      # @return [Hash] Additional metadata to merge into event metadata
+      def additional_metadata(_step_result, _event_declaration, _step_context = nil)
+        {}
+      end
+
+      # Hook called before publishing
+      #
+      # Override for pre-publish validation, logging, or metrics.
+      # Raise an exception to prevent publishing.
+      #
+      # @param event_name [String] The event name
+      # @param payload [Hash] The transformed payload
+      # @param metadata [Hash] The event metadata
+      def before_publish(event_name, _payload, _metadata)
+        logger.debug "Publishing event: #{event_name}"
+      end
+
+      # Hook called after successful publishing
+      #
+      # Override for post-publish logging, metrics, or cleanup.
+      #
+      # @param event_name [String] The event name
+      # @param payload [Hash] The transformed payload
+      # @param metadata [Hash] The event metadata
+      def after_publish(event_name, _payload, _metadata)
+        logger.debug "Event published: #{event_name}"
+      end
+
+      # Hook called if publishing fails
+      #
+      # Override for error handling, logging, or fallback behavior.
+      # Default logs the error but does not re-raise.
+      #
+      # @param event_name [String] The event name
+      # @param error [Exception] The error that occurred
+      # @param payload [Hash] The transformed payload
+      def on_publish_error(event_name, error, _payload)
+        logger.error "Failed to publish event #{event_name}: #{error.message}"
+      end
+
+      # ========================================================================
+      # CROSS-LANGUAGE STANDARD API (TAS-96)
+      # ========================================================================
+
+      # Cross-language standard: Publish an event with unified context
+      #
+      # This method coordinates the existing hooks (should_publish?, transform_payload,
+      # additional_metadata, before_publish, after_publish) into a single publish call.
+      #
+      # @param ctx [Hash] Step event context containing:
+      #   - :event_name [String] The event name (e.g., "payment.processed")
+      #   - :step_result [Hash] The step execution result
+      #   - :event_declaration [Hash] The event declaration from YAML
+      #   - :step_context [Hash, TaskerCore::Types::StepContext] Step execution context
+      # @return [Boolean] true if event was published, false if skipped
+      #
+      # @example Publishing with context
+      #   ctx = {
+      #     event_name: 'payment.processed',
+      #     step_result: { success: true, result: { payment_id: '123' } },
+      #     event_declaration: { name: 'payment.processed', delivery_mode: 'durable' },
+      #     step_context: step_context
+      #   }
+      #   publisher.publish(ctx)
+      def publish(ctx)
+        event_name = ctx[:event_name]
+        step_result = ctx[:step_result]
+        event_declaration = ctx[:event_declaration] || {}
+        step_context = ctx[:step_context]
+
+        # Check publishing conditions
+        return false unless should_publish?(step_result, event_declaration, step_context)
+
+        # Transform payload
+        payload = transform_payload(step_result, event_declaration, step_context)
+
+        # Build metadata
+        base_metadata = {
+          publisher: name,
+          published_at: Time.now.utc.iso8601
+        }
+
+        # Add step context info if available
+        if step_context.respond_to?(:task_uuid)
+          base_metadata[:task_uuid] = step_context.task_uuid
+          base_metadata[:step_uuid] = step_context.step_uuid
+          base_metadata[:step_name] = step_context.step_name if step_context.respond_to?(:step_name)
+          base_metadata[:namespace] = step_context.namespace_name if step_context.respond_to?(:namespace_name)
+        end
+
+        metadata = base_metadata.merge(additional_metadata(step_result, event_declaration, step_context))
+
+        begin
+          # Pre-publish hook
+          before_publish(event_name, payload, metadata)
+
+          # Actual publishing is handled by the event router/bridge
+          # This method just prepares and validates the event
+          # Subclasses can override to perform actual publishing
+
+          # Post-publish hook
+          after_publish(event_name, payload, metadata)
+
+          true
+        rescue StandardError => e
+          on_publish_error(event_name, e, payload)
+          false
+        end
+      end
+    end
+  end
+end

data/lib/tasker_core/domain_events/base_subscriber.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module TaskerCore
+  module DomainEvents
+    # TAS-65: Base class for domain event subscribers
+    #
+    # Domain event subscribers handle business events published by steps.
+    # They subscribe to event patterns and receive events via the in-process
+    # event bus (for fast events) or can poll PGMQ (for durable events).
+    #
+    # @example Creating a subscriber for payment events
+    #   class PaymentEventSubscriber < TaskerCore::DomainEvents::BaseSubscriber
+    #     # Match all payment.* events
+    #     subscribes_to 'payment.*'
+    #
+    #     def handle(event)
+    #       case event[:event_name]
+    #       when 'payment.processed'
+    #         notify_accounting(event[:business_payload])
+    #       when 'payment.failed'
+    #         alert_support(event[:business_payload])
+    #       end
+    #     end
+    #
+    #     private
+    #
+    #     def notify_accounting(payload)
+    #       # Send to accounting system
+    #     end
+    #
+    #     def alert_support(payload)
+    #       # Alert support team
+    #     end
+    #   end
+    #
+    # @example Creating a subscriber for metrics collection
+    #   class MetricsSubscriber < TaskerCore::DomainEvents::BaseSubscriber
+    #     # Match all events
+    #     subscribes_to '*'
+    #
+    #     def handle(event)
+    #       StatsD.increment("domain_events.#{event[:event_name].gsub('.', '_')}")
+    #     end
+    #   end
+    #
+    # @example Registering and starting subscribers
+    #   # In bootstrap
+    #   subscribers = [
+    #     PaymentEventSubscriber.new,
+    #     MetricsSubscriber.new
+    #   ]
+    #
+    #   subscribers.each(&:start!)
+    #
+    class BaseSubscriber
+      class << self
+        # DSL method to declare event pattern subscriptions
+        #
+        # @param patterns [Array<String>] Event patterns to subscribe to
+        def subscribes_to(*patterns)
+          @patterns = patterns.flatten
+        end
+
+        # Get declared patterns
+        #
+        # @return [Array<String>]
+        def patterns
+          @patterns || ['*']
+        end
+      end
+
+      attr_reader :logger, :active
+
+      def initialize
+        @logger = TaskerCore::Logger.instance
+        @active = false
+        @subscriptions = []
+      end
+
+      # Start listening for events
+      def start!
+        return if @active
+
+        @active = true
+        poller = TaskerCore::Worker::InProcessDomainEventPoller.instance
+
+        self.class.patterns.each do |pattern|
+          # Subscribe to the poller with this subscriber's handler
+          poller.subscribe(pattern) do |event|
+            handle_event_safely(event)
+          end
+          @subscriptions << pattern
+          logger.info "#{self.class.name}: Subscribed to pattern '#{pattern}'"
+        end
+
+        logger.info "#{self.class.name}: Started with #{@subscriptions.size} subscriptions"
+      end
+
+      # Stop listening for events
+      def stop!
+        return unless @active
+
+        @active = false
+        poller = TaskerCore::Worker::InProcessDomainEventPoller.instance
+
+        @subscriptions.each do |pattern|
+          poller.unsubscribe(pattern)
+        end
+        @subscriptions.clear
+
+        logger.info "#{self.class.name}: Stopped"
+      end
+
+      # Check if subscriber is active
+      def active?
+        @active
+      end
+
+      # Handle a domain event
+      #
+      # Subclasses MUST implement this method.
+      #
+      # @param event [Hash] The domain event
+      #   - :event_name [String] The event name (e.g., "order.processed")
+      #   - :business_payload [Hash] The business data from the step
+      #   - :metadata [Hash] Event metadata (task_uuid, step_uuid, correlation_id, etc.)
+      #   - :execution_result [Hash] The step execution result
+      def handle(event)
+        raise NotImplementedError, "#{self.class} must implement #handle"
+      end
+
+      # Hook called before handling an event
+      #
+      # Override for pre-processing, validation, or filtering.
+      # Return false to skip handling this event.
+      #
+      # @param event [Hash] The domain event
+      # @return [Boolean] true to continue handling, false to skip
+      def before_handle(event) # rubocop:disable Lint/UnusedMethodArgument
+        true
+      end
+
+      # Hook called after successful handling
+      #
+      # Override for post-processing, metrics, or cleanup.
+      #
+      # @param event [Hash] The domain event
+      def after_handle(event)
+        # Default: no-op
+      end
+
+      # Hook called if handling fails
+      #
+      # Override for custom error handling, alerts, or retry logic.
+      # Note: Domain event handling uses fire-and-forget semantics - errors
+      # are logged but not propagated.
+      #
+      # @param event [Hash] The domain event
+      # @param error [Exception] The error that occurred
+      def on_handle_error(event, error)
+        logger.error "#{self.class.name}: Failed to handle #{event[:event_name]}: #{error.message}"
+      end
+
+      private
+
+      # Safely handle an event with error capture
+      def handle_event_safely(event)
+        return unless @active
+        return unless before_handle(event)
+
+        handle(event)
+        after_handle(event)
+      rescue StandardError => e
+        on_handle_error(event, e)
+      end
+    end
+  end
+end

data/lib/tasker_core/domain_events/publisher_registry.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module TaskerCore
+  module DomainEvents
+    # TAS-65: Registry for custom domain event publishers
+    #
+    # Maps publisher names (from YAML configuration) to their Ruby implementations.
+    # Publishers are registered at bootstrap time and validated against task templates.
+    #
+    # @example Registering publishers at bootstrap
+    #   registry = TaskerCore::DomainEvents::PublisherRegistry.instance
+    #
+    #   # Register custom publishers
+    #   registry.register(PaymentEventPublisher.new)
+    #   registry.register(InventoryEventPublisher.new)
+    #
+    #   # Validate against loaded templates
+    #   required = ['PaymentEventPublisher', 'InventoryEventPublisher', 'MissingPublisher']
+    #   registry.validate_required!(required)
+    #   # => raises ValidationError: Missing publishers: MissingPublisher
+    #
+    # @example Looking up publishers
+    #   publisher = registry.get('PaymentEventPublisher')
+    #   publisher.transform_payload(step_result, event_declaration)
+    #
+    # @example Using default publisher
+    #   # Returns DefaultPublisher for unregistered names
+    #   publisher = registry.get_or_default('UnknownPublisher')
+    #
+    class PublisherRegistry
+      include Singleton
+
+      # Error classes nested in PublisherRegistry for cleaner namespacing
+      class ValidationError < StandardError
+        attr_reader :missing_publishers, :registered_publishers
+
+        def initialize(missing, registered)
+          @missing_publishers = missing
+          @registered_publishers = registered
+          super("Missing publishers: #{missing.join(', ')}. Registered: #{registered.join(', ')}")
+        end
+      end
+
+      class PublisherNotFoundError < StandardError
+        attr_reader :publisher_name, :registered_publishers
+
+        def initialize(name, registered)
+          @publisher_name = name
+          @registered_publishers = registered
+          super("Publisher '#{name}' not found. Registered: #{registered.join(', ')}")
+        end
+      end
+
+      class RegistryFrozenError < StandardError; end
+
+      class DuplicatePublisherError < StandardError
+        attr_reader :publisher_name
+
+        def initialize(name)
+          @publisher_name = name
+          super("Publisher '#{name}' is already registered")
+        end
+      end
+
+      # Default publisher that passes step result through unchanged
+      class DefaultPublisher < BasePublisher
+        def name
+          'default'
+        end
+
+        def transform_payload(step_result, _event_declaration, _step_context = nil)
+          step_result[:result] || {}
+        end
+      end
+
+      attr_reader :logger, :publishers, :default_publisher
+
+      def initialize
+        @logger = TaskerCore::Logger.instance
+        @publishers = {}
+        @default_publisher = DefaultPublisher.new
+        @frozen = false
+      end
+
+      # Register a custom publisher
+      #
+      # @param publisher [BasePublisher] The publisher instance to register
+      # @return [BasePublisher, nil] The previous publisher with the same name, if any
+      # @raise [ArgumentError] If publisher does not inherit from BasePublisher
+      # @raise [DuplicatePublisherError] If a publisher with the same name is already registered
+      # @raise [RegistryFrozenError] If the registry has been frozen
+      def register(publisher)
+        # Type validation first
+        raise ArgumentError, "Expected BasePublisher, got #{publisher.class}" unless publisher.is_a?(BasePublisher)
+
+        raise RegistryFrozenError, 'Registry is frozen after validation' if @frozen
+
+        name = publisher.name
+
+        # Check for duplicates
+        raise DuplicatePublisherError, name if @publishers.key?(name)
+
+        logger.info "Registering domain event publisher: #{name}"
+        @publishers[name] = publisher
+        nil # No previous since we now disallow duplicates
+      end
+
+      # Get a publisher by name
+      #
+      # @param name [String] The publisher name
+      # @return [BasePublisher, nil] The publisher, or nil if not found
+      def get(name)
+        @publishers[name]
+      end
+
+      # Get a publisher by name, or return the default if not found
+      #
+      # @param name [String, nil] The publisher name
+      # @return [BasePublisher] The publisher or default
+      def get_or_default(name)
+        return @default_publisher if name.nil? || name == 'default'
+
+        @publishers[name] || begin
+          logger.warn "Publisher #{name} not found, using default"
+          @default_publisher
+        end
+      end
+
+      # Get a publisher by name with strict mode (no fallback)
+      #
+      # @param name [String] The publisher name
+      # @return [BasePublisher] The publisher
+      # @raise [PublisherNotFoundError] If the publisher is not registered
+      def get_strict(name)
+        return @default_publisher if name == 'default'
+
+        @publishers[name] || raise(
+          PublisherNotFoundError.new(name, registered_names)
+        )
+      end
+
+      # Check if a publisher is registered
+      #
+      # @param name [String] The publisher name
+      # @return [Boolean]
+      def registered?(name)
+        @publishers.key?(name) || name == 'default'
+      end
+
+      # Get all registered publisher names
+      #
+      # @return [Array<String>]
+      def registered_names
+        @publishers.keys
+      end
+
+      # Get count of registered publishers
+      #
+      # @return [Integer]
+      def count
+        @publishers.size
+      end
+
+      # Check if registry has no custom publishers
+      #
+      # @return [Boolean]
+      def empty?
+        @publishers.empty?
+      end
+
+      # Unregister a publisher by name
+      #
+      # @param name [String] The publisher name
+      # @return [BasePublisher, nil] The removed publisher, if any
+      # @raise [RegistryFrozenError] If the registry has been frozen
+      def unregister(name)
+        raise RegistryFrozenError, 'Registry is frozen after validation' if @frozen
+
+        logger.info "Unregistering domain event publisher: #{name}"
+        @publishers.delete(name)
+      end
+
+      # Clear all registered publishers
+      #
+      # @raise [RegistryFrozenError] If the registry has been frozen
+      def clear
+        raise RegistryFrozenError, 'Registry is frozen after validation' if @frozen
+
+        logger.info 'Clearing all domain event publishers'
+        @publishers.clear
+      end
+
+      # TAS-65: Validate that all required publishers are registered
+      #
+      # Implements "loud failure validation" - validates at init time that all
+      # publisher names referenced in task templates exist in the registry.
+      # After validation, the registry is frozen to prevent changes.
+      #
+      # @param required_publishers [Array<String>] Publisher names from YAML configs
+      # @return [true] If all required publishers are registered
+      # @raise [ValidationError] If some publishers are missing
+      def validate_required!(required_publishers)
+        missing = []
+
+        required_publishers.each do |name|
+          next if name == 'default'
+          next if registered?(name)
+
+          missing << name
+        end
+
+        raise ValidationError.new(missing, registered_names) if missing.any?
+
+        @frozen = true
+        logger.info "Publisher validation passed. Registered: #{registered_names.join(', ')}"
+        true
+      end
+
+      # Check if the registry is frozen
+      #
+      # @return [Boolean]
+      def frozen?
+        @frozen
+      end
+
+      # Freeze the registry to prevent further changes
+      #
+      # @return [void]
+      def freeze!
+        @frozen = true
+        logger.info 'Publisher registry frozen'
+      end
+
+      # Reset the registry (for testing)
+      #
+      # @note This unfreezes the registry - use only in tests
+      def reset!
+        @publishers.clear
+        @frozen = false
+        logger.info 'Publisher registry reset'
+      end
+    end
+
+    # Backwards-compatible aliases for classes that were moved into PublisherRegistry
+    # These allow existing code to use the old namespace while we transition
+    DefaultPublisher = PublisherRegistry::DefaultPublisher
+    ValidationError = PublisherRegistry::ValidationError
+    PublisherNotFoundError = PublisherRegistry::PublisherNotFoundError
+    RegistryFrozenError = PublisherRegistry::RegistryFrozenError
+  end
+end