tasker-rb 0.1.1

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

data/lib/tasker_core/domain_events/subscriber_registry.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module TaskerCore
+  module DomainEvents
+    # TAS-65: Registry for domain event subscribers
+    #
+    # Manages the lifecycle of domain event subscribers. Subscribers are registered
+    # at bootstrap time and started/stopped together with the worker.
+    #
+    # @example Registering subscribers at bootstrap
+    #   registry = TaskerCore::DomainEvents::SubscriberRegistry.instance
+    #
+    #   # Register subscriber classes (instantiation deferred)
+    #   registry.register(PaymentEventSubscriber)
+    #   registry.register(MetricsSubscriber)
+    #
+    #   # Or register instances directly
+    #   registry.register_instance(CustomSubscriber.new(some_config))
+    #
+    #   # Start all subscribers
+    #   registry.start_all!
+    #
+    # @example Stopping all subscribers
+    #   registry.stop_all!
+    #
+    class SubscriberRegistry
+      include Singleton
+
+      attr_reader :logger, :subscribers
+
+      def initialize
+        @logger = TaskerCore::Logger.instance
+        @subscribers = []
+        @started = false
+      end
+
+      # Register a subscriber class
+      #
+      # The class will be instantiated when start_all! is called.
+      #
+      # @param subscriber_class [Class] A subclass of BaseSubscriber
+      # @return [void]
+      def register(subscriber_class)
+        unless subscriber_class < BaseSubscriber
+          raise ArgumentError, "#{subscriber_class} must be a subclass of BaseSubscriber"
+        end
+
+        logger.info "SubscriberRegistry: Registered #{subscriber_class.name}"
+        @subscriber_classes ||= []
+        @subscriber_classes << subscriber_class
+      end
+
+      # Register a subscriber instance directly
+      #
+      # Use this when your subscriber needs custom initialization.
+      #
+      # @param subscriber [BaseSubscriber] A subscriber instance
+      # @return [void]
+      def register_instance(subscriber)
+        raise ArgumentError, "Expected BaseSubscriber, got #{subscriber.class}" unless subscriber.is_a?(BaseSubscriber)
+
+        logger.info "SubscriberRegistry: Registered instance of #{subscriber.class.name}"
+        @subscribers << subscriber
+      end
+
+      # Start all registered subscribers
+      #
+      # Instantiates registered classes and starts all subscribers.
+      #
+      # @return [void]
+      def start_all!
+        return if @started
+
+        # Instantiate registered classes
+        (@subscriber_classes || []).each do |klass|
+          @subscribers << klass.new
+        end
+
+        # Start all subscribers
+        @subscribers.each do |subscriber|
+          subscriber.start!
+        rescue StandardError => e
+          logger.error "Failed to start #{subscriber.class.name}: #{e.message}"
+        end
+
+        @started = true
+        logger.info "SubscriberRegistry: Started #{@subscribers.size} subscribers"
+      end
+
+      # Stop all subscribers
+      #
+      # @return [void]
+      def stop_all!
+        return unless @started
+
+        @subscribers.each do |subscriber|
+          subscriber.stop!
+        rescue StandardError => e
+          logger.error "Failed to stop #{subscriber.class.name}: #{e.message}"
+        end
+
+        @started = false
+        logger.info 'SubscriberRegistry: Stopped all subscribers'
+      end
+
+      # Check if subscribers have been started
+      #
+      # @return [Boolean]
+      def started?
+        @started
+      end
+
+      # Get count of registered subscribers
+      #
+      # @return [Integer]
+      def count
+        @subscribers.size + (@subscriber_classes&.size || 0)
+      end
+
+      # Get subscriber statistics
+      #
+      # @return [Hash]
+      def stats
+        {
+          started: @started,
+          subscriber_count: @subscribers.size,
+          active_count: @subscribers.count(&:active?),
+          subscribers: @subscribers.map do |s|
+            {
+              class: s.class.name,
+              active: s.active?,
+              patterns: s.class.patterns
+            }
+          end
+        }
+      end
+
+      # Reset the registry (for testing)
+      #
+      # @note This stops all subscribers first
+      def reset!
+        stop_all! if @started
+        @subscribers.clear
+        @subscriber_classes&.clear
+        @started = false
+        logger.info 'SubscriberRegistry: Reset'
+      end
+    end
+  end
+end

data/lib/tasker_core/domain_events.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# TAS-65: Domain Events Module
+#
+# Provides infrastructure for custom domain event publishers.
+# Domain events are business events (e.g., "order.processed", "payment.completed")
+# published after step execution based on YAML declarations.
+#
+# @example Using the domain events infrastructure
+#   # Register custom publishers at bootstrap
+#   require 'tasker_core/domain_events'
+#
+#   class PaymentEventPublisher < TaskerCore::DomainEvents::BasePublisher
+#     def name
+#       'PaymentEventPublisher'
+#     end
+#
+#     def transform_payload(step_result, event_declaration, step_context)
+#       {
+#         payment_id: step_result[:result][:payment_id],
+#         amount: step_result[:result][:amount],
+#         status: step_result[:success] ? 'succeeded' : 'failed'
+#       }
+#     end
+#   end
+#
+#   TaskerCore::DomainEvents::PublisherRegistry.instance.register(
+#     PaymentEventPublisher.new
+#   )
+#
+module TaskerCore
+  module DomainEvents
+    # Load domain events components
+  end
+end
+
+# Publishers
+require_relative 'domain_events/base_publisher'
+require_relative 'domain_events/publisher_registry'
+
+# Subscribers
+require_relative 'domain_events/base_subscriber'
+require_relative 'domain_events/subscriber_registry'

data/lib/tasker_core/errors/CLAUDE.md

@@ -0,0 +1,7 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+*No recent activity*
+</claude-mem-context>