smart_message 0.0.4 → 0.0.6

data/lib/smart_message/base.rb

@@ -6,6 +6,7 @@ require 'securerandom'   # STDLIB
 
 require_relative './wrapper.rb'
 require_relative './property_descriptions.rb'
+require_relative './property_validations.rb'
 
 module SmartMessage
   # The foundation class for the smart message
@@ -17,18 +18,43 @@ module SmartMessage
     @@serializer  = nil
     @@logger      = nil
     
+    # Class-level addressing configuration - use a registry for per-class isolation
+    @@addressing_registry = {}
+    
     # Registry for proc-based message handlers
     @@proc_handlers = {}
+    
+    # Class-level version setting
+    class << self
+      attr_accessor :_version
+      
+      def version(v = nil)
+        if v.nil?
+          @_version || 1  # Default to version 1 if not set
+        else
+          @_version = v
+          
+          # Set up version validation for the header
+          # This ensures that the header version matches the expected class version
+          @expected_header_version = v
+        end
+      end
+      
+      def expected_header_version
+        @expected_header_version || 1
+      end
+    end
 
     include Hashie::Extensions::Dash::PropertyTranslation
 
     include SmartMessage::PropertyDescriptions
+    include SmartMessage::PropertyValidations
 
     include Hashie::Extensions::Coercion
     include Hashie::Extensions::DeepMerge
     include Hashie::Extensions::IgnoreUndeclared
     include Hashie::Extensions::IndifferentAccess
-    include Hashie::Extensions::MergeInitializer
+    # MergeInitializer interferes with required property validation - removed
     include Hashie::Extensions::MethodAccess
 
     # Common attrubutes for all messages
@@ -46,14 +72,37 @@ module SmartMessage
       @transport   = nil
       @serializer  = nil
       @logger      = nil
-
+      
+      # instance-level over ride of class addressing
+      @from        = nil
+      @to          = nil
+      @reply_to    = nil
+
+      # Create header with version validation specific to this message class
+      header = SmartMessage::Header.new(
+        uuid:           SecureRandom.uuid,
+        message_class:  self.class.to_s,
+        published_at:   Time.now,
+        publisher_pid:  Process.pid,
+        version:        self.class.version,
+        from:           from,
+        to:             to,
+        reply_to:       reply_to
+      )
+      
+      # Set up version validation to match the expected class version
+      expected_version = self.class.expected_header_version
+      header.singleton_class.class_eval do
+        define_method(:validate_version!) do
+          unless self.version == expected_version
+            raise SmartMessage::Errors::ValidationError, 
+              "Header version must be #{expected_version}, got: #{self.version}"
+          end
+        end
+      end
+      
       attributes = {
-        _sm_header: SmartMessage::Header.new(
-          uuid:           SecureRandom.uuid,
-          message_class:  self.class.to_s,
-          published_at:   2,
-          publisher_pid:  3
-        )
+        _sm_header: header
       }.merge(props)
 
       super(attributes, &block)
@@ -62,6 +111,57 @@ module SmartMessage
 
     ###################################################
     ## Common instance methods
+    
+    # Validate that the header version matches the expected version for this class
+    def validate_header_version!
+      expected = self.class.expected_header_version
+      actual = _sm_header.version
+      unless actual == expected
+        raise SmartMessage::Errors::ValidationError,
+          "#{self.class.name} expects version #{expected}, but header has version #{actual}"
+      end
+    end
+
+    # Override PropertyValidations validate! to include header and version validation
+    def validate!
+      # Validate message properties using PropertyValidations
+      super
+      
+      # Validate header properties
+      _sm_header.validate!
+      
+      # Validate header version matches expected class version  
+      validate_header_version!
+    end
+
+    # Override PropertyValidations validation_errors to include header errors
+    def validation_errors
+      errors = []
+      
+      # Get message property validation errors using PropertyValidations
+      errors.concat(super.map { |err| 
+        err.merge(source: 'message') 
+      })
+      
+      # Get header validation errors
+      errors.concat(_sm_header.validation_errors.map { |err| 
+        err.merge(source: 'header') 
+      })
+      
+      # Check version mismatch
+      expected = self.class.expected_header_version
+      actual = _sm_header.version
+      unless actual == expected
+        errors << {
+          property: :version,
+          value: actual,
+          message: "Expected version #{expected}, got: #{actual}",
+          source: 'version_mismatch'
+        }
+      end
+      
+      errors
+    end
 
     # SMELL: How does the transport know how to decode a message before
     #        it knows the message class?  We need a wrapper around
@@ -82,6 +182,9 @@ module SmartMessage
     # NOTE: you publish instances; but, you subscribe/unsubscribe at
     #       the class-level
     def publish
+      # Validate the complete message before publishing (now uses overridden validate!)
+      validate!
+      
       # TODO: move all of the _sm_ property processes into the wrapper
       _sm_header.published_at   = Time.now
       _sm_header.publisher_pid  = Process.pid
@@ -142,6 +245,61 @@ module SmartMessage
     def reset_serializer;       @serializer = nil;  end
 
 
+    #########################################################
+    ## instance-level addressing configuration
+
+    def from(entity_id = nil)
+      if entity_id.nil?
+        @from || self.class.from
+      else
+        @from = entity_id
+        # Update the header with the new value
+        _sm_header.from = entity_id if _sm_header
+      end
+    end
+    
+    def from_configured?; !from.nil?; end
+    def from_missing?;     from.nil?; end
+    def reset_from;       
+      @from = nil
+      _sm_header.from = nil if _sm_header
+    end
+
+    def to(entity_id = nil)
+      if entity_id.nil?
+        @to || self.class.to
+      else
+        @to = entity_id
+        # Update the header with the new value
+        _sm_header.to = entity_id if _sm_header
+      end
+    end
+    
+    def to_configured?;   !to.nil?; end
+    def to_missing?;       to.nil?; end
+    def reset_to;         
+      @to = nil
+      _sm_header.to = nil if _sm_header
+    end
+
+    def reply_to(entity_id = nil)
+      if entity_id.nil?
+        @reply_to || self.class.reply_to
+      else
+        @reply_to = entity_id
+        # Update the header with the new value
+        _sm_header.reply_to = entity_id if _sm_header
+      end
+    end
+    
+    def reply_to_configured?; !reply_to.nil?; end
+    def reply_to_missing?;     reply_to.nil?; end
+    def reset_reply_to;       
+      @reply_to = nil
+      _sm_header.reply_to = nil if _sm_header
+    end
+
+
     #########################################################
     ## instance-level utility methods
 
@@ -150,6 +308,11 @@ module SmartMessage
       self.class.to_s
     end
 
+    # return this class' description
+    def description
+      self.class.description
+    end
+
 
     # returns a collection of class Set that consists of
     # the symbolized values of the property names of the message
@@ -173,7 +336,7 @@ module SmartMessage
       
       def description(desc = nil)
         if desc.nil?
-          @description
+          @description || "#{self.name} is a SmartMessage"
         else
           @description = desc.to_s
         end
@@ -261,6 +424,113 @@ module SmartMessage
       def reset_serializer;      @@serializer = nil;  end
 
 
+      #########################################################
+      ## class-level addressing configuration
+      
+      # Helper method to normalize filter values (string -> array, nil -> nil)
+      private def normalize_filter_value(value)
+        case value
+        when nil
+          nil
+        when String
+          [value]
+        when Array
+          value
+        else
+          raise ArgumentError, "Filter value must be a String, Array, or nil, got: #{value.class}"
+        end
+      end
+      
+      # Helper method to find addressing values in the inheritance chain
+      private def find_addressing_value(field)
+        # Start with current class
+        current_class = self
+        
+        while current_class && current_class.respond_to?(:name)
+          class_name = current_class.name || current_class.to_s
+          
+          # Check registry for this class
+          result = @@addressing_registry.dig(class_name, field)
+          return result if result
+          
+          # If we have a proper name but no result, also check the to_s version
+          if current_class.name
+            alternative_key = current_class.to_s
+            result = @@addressing_registry.dig(alternative_key, field)
+            return result if result
+          end
+          
+          # Move up the inheritance chain
+          current_class = current_class.superclass
+          
+          # Stop if we reach SmartMessage::Base or above
+          break if current_class == SmartMessage::Base || current_class.nil?
+        end
+        
+        nil
+      end
+
+      def from(entity_id = nil)
+        class_name = self.name || self.to_s
+        if entity_id.nil?
+          # Try to find the value, checking inheritance chain
+          result = find_addressing_value(:from)
+          result
+        else
+          @@addressing_registry[class_name] ||= {}
+          @@addressing_registry[class_name][:from] = entity_id
+        end
+      end
+      
+      def from_configured?; !from.nil?; end
+      def from_missing?;     from.nil?; end
+      def reset_from; 
+        class_name = self.name || self.to_s
+        @@addressing_registry[class_name] ||= {}
+        @@addressing_registry[class_name][:from] = nil
+      end
+
+      def to(entity_id = nil)
+        class_name = self.name || self.to_s
+        if entity_id.nil?
+          # Try to find the value, checking inheritance chain
+          result = find_addressing_value(:to)
+          result
+        else
+          @@addressing_registry[class_name] ||= {}
+          @@addressing_registry[class_name][:to] = entity_id
+        end
+      end
+      
+      def to_configured?;   !to.nil?; end
+      def to_missing?;       to.nil?; end
+      def reset_to; 
+        class_name = self.name || self.to_s
+        @@addressing_registry[class_name] ||= {}
+        @@addressing_registry[class_name][:to] = nil
+      end
+
+      def reply_to(entity_id = nil)
+        class_name = self.name || self.to_s
+        if entity_id.nil?
+          # Try to find the value, checking inheritance chain
+          result = find_addressing_value(:reply_to)
+          result
+        else
+          @@addressing_registry[class_name] ||= {}
+          @@addressing_registry[class_name][:reply_to] = entity_id
+        end
+      end
+      
+      def reply_to_configured?; !reply_to.nil?; end
+      def reply_to_missing?;     reply_to.nil?; end
+      def reset_reply_to; 
+        class_name = self.name || self.to_s
+        @@addressing_registry[class_name] ||= {}
+        @@addressing_registry[class_name][:reply_to] = nil
+      end
+
+
       #########################################################
       ## class-level subscription management via the transport
 
@@ -272,25 +542,30 @@ module SmartMessage
       #   - String: Method name like "MyService.handle_message" 
       #   - Proc: A proc/lambda that accepts (message_header, message_payload)
       #   - nil: Uses default "MessageClass.process" method
+      # @param broadcast [Boolean, nil] Filter for broadcast messages (to: nil)
+      # @param to [String, Array, nil] Filter for messages directed to specific entities
+      # @param from [String, Array, nil] Filter for messages from specific entities
       # @param block [Proc] Alternative way to pass a processing block
       # @return [String] The identifier used for this subscription
       #
-      # @example Using default handler
+      # @example Using default handler (all messages)
       #   MyMessage.subscribe
       #
-      # @example Using custom method name
-      #   MyMessage.subscribe("MyService.handle_message")
+      # @example Using custom method name with filtering
+      #   MyMessage.subscribe("MyService.handle_message", to: 'my-service')
       #
-      # @example Using a block
-      #   MyMessage.subscribe do |header, payload|
+      # @example Using a block with broadcast filtering
+      #   MyMessage.subscribe(broadcast: true) do |header, payload|
       #     data = JSON.parse(payload)
-      #     puts "Received: #{data}"
+      #     puts "Received broadcast: #{data}"
       #   end
       #
-      # @example Using a proc
-      #   handler = proc { |header, payload| puts "Processing..." }
-      #   MyMessage.subscribe(handler)
-      def subscribe(process_method = nil, &block)
+      # @example Entity-specific filtering
+      #   MyMessage.subscribe(to: 'order-service', from: ['payment', 'user'])
+      #
+      # @example Broadcast + directed messages
+      #   MyMessage.subscribe(to: 'my-service', broadcast: true)
+      def subscribe(process_method = nil, broadcast: nil, to: nil, from: nil, &block)
         message_class = whoami
         
         # Handle different parameter types
@@ -308,10 +583,21 @@ module SmartMessage
         end
         # If process_method is a String, use it as-is
 
+        # Normalize string filters to arrays
+        to_filter = normalize_filter_value(to)
+        from_filter = normalize_filter_value(from)
+        
+        # Create filter options
+        filter_options = {
+          broadcast: broadcast,
+          to: to_filter,
+          from: from_filter
+        }
+
         # TODO: Add proper logging here
 
         raise Errors::TransportNotConfigured if transport_missing?
-        transport.subscribe(message_class, process_method)
+        transport.subscribe(message_class, process_method, filter_options)
         
         process_method
       end

data/lib/smart_message/dispatcher.rb

@@ -83,17 +83,30 @@ module SmartMessage
     end
 
 
-    def add(message_class, process_method_as_string)
+    def add(message_class, process_method_as_string, filter_options = {})
       klass = String(message_class)
-      unless @subscribers[klass].include? process_method_as_string
-        @subscribers[klass] += [process_method_as_string]
+      
+      # Create subscription entry with filter options
+      subscription = {
+        process_method: process_method_as_string,
+        filters: filter_options
+      }
+      
+      # Check if this exact subscription already exists
+      existing_subscription = @subscribers[klass].find do |sub|
+        sub[:process_method] == process_method_as_string && sub[:filters] == filter_options
+      end
+      
+      unless existing_subscription
+        @subscribers[klass] += [subscription]
       end
     end
 
 
     # drop a processer from a subscribed message
     def drop(message_class, process_method_as_string)
-      @subscribers[String(message_class)].delete process_method_as_string
+      klass = String(message_class)
+      @subscribers[klass].reject! { |sub| sub[:process_method] == process_method_as_string }
     end
 
 
@@ -115,7 +128,15 @@ module SmartMessage
     def route(message_header, message_payload)
       message_klass = message_header.message_class
       return nil if @subscribers[message_klass].empty?
-      @subscribers[message_klass].each do |message_processor|
+      
+      @subscribers[message_klass].each do |subscription|
+        # Extract subscription details
+        message_processor = subscription[:process_method]
+        filters = subscription[:filters]
+        
+        # Check if message matches filters
+        next unless message_matches_filters?(message_header, filters)
+        
         SS.add(message_klass, message_processor, 'routed' )
         @router_pool.post do
           begin
@@ -144,6 +165,33 @@ module SmartMessage
 
     private
 
+    # Check if a message matches the subscription filters
+    # @param message_header [SmartMessage::Header] The message header
+    # @param filters [Hash] The filter criteria
+    # @return [Boolean] True if the message matches all filters
+    def message_matches_filters?(message_header, filters)
+      # If no filters specified, accept all messages (backward compatibility)
+      return true if filters.nil? || filters.empty? || filters.values.all?(&:nil?)
+      
+      # Check from filter
+      if filters[:from]
+        from_match = filters[:from].include?(message_header.from)
+        return false unless from_match
+      end
+      
+      # Check to/broadcast filters (OR logic between them)
+      if filters[:broadcast] || filters[:to]
+        broadcast_match = filters[:broadcast] && message_header.to.nil?
+        to_match = filters[:to] && filters[:to].include?(message_header.to)
+        
+        # If either broadcast or to filter is specified, at least one must match
+        combined_match = (broadcast_match || to_match)
+        return false unless combined_match
+      end
+      
+      true
+    end
+
     # Check if a message processor is a proc handler
     # @param message_processor [String] The message processor identifier
     # @return [Boolean] True if this is a proc handler

data/lib/smart_message/errors.rb

@@ -25,5 +25,8 @@ module SmartMessage
     # A received message is of an unknown class
     class UnknownMessageClass < RuntimeError; end
 
+    # A property validation failed
+    class ValidationError < RuntimeError; end
+
   end
 end

data/lib/smart_message/header.rb

@@ -2,19 +2,60 @@
 # encoding: utf-8
 # frozen_string_literal: true
 
+require_relative './property_descriptions'
+require_relative './property_validations'
+
 module SmartMessage
   # Every smart message has a common header format that contains
   # information used to support the dispatching of subscribed
   # messages upon receipt from a transport.
   class Header < Hashie::Dash
     include Hashie::Extensions::IndifferentAccess
-    include Hashie::Extensions::MergeInitializer
     include Hashie::Extensions::MethodAccess
+    include SmartMessage::PropertyDescriptions
+    include SmartMessage::PropertyValidations
 
     # Common attributes of the smart message standard header
-    property :uuid
-    property :message_class
-    property :published_at
-    property :publisher_pid
+    property :uuid, 
+      required: true,
+      message: "UUID is required for message tracking and deduplication",
+      description: "Unique identifier for this specific message instance, used for tracking and deduplication"
+    
+    property :message_class, 
+      required: true,
+      message: "Message class is required to identify the message type",
+      description: "Fully qualified class name of the message type (e.g. 'OrderMessage', 'PaymentNotification')"
+    
+    property :published_at, 
+      required: true,
+      message: "Published timestamp is required for message ordering",
+      description: "Timestamp when the message was published by the sender, used for ordering and debugging"
+    
+    property :publisher_pid, 
+      required: true,
+      message: "Publisher process ID is required for debugging and traceability",
+      description: "Process ID of the publishing application, useful for debugging and tracing message origins"
+    
+    property :version, 
+      required: true, 
+      default: 1,
+      message: "Message version is required for schema compatibility",
+      description: "Schema version of the message format, used for schema evolution and compatibility checking",
+      validate: ->(v) { v.is_a?(Integer) && v > 0 },
+      validation_message: "Header version must be a positive integer"
+    
+    # Message addressing properties for entity-to-entity communication
+    property :from,
+      required: true,
+      message: "From entity ID is required for message routing and replies",
+      description: "Unique identifier of the entity sending this message, used for routing responses and audit trails"
+    
+    property :to,
+      required: false,
+      description: "Optional unique identifier of the intended recipient entity. When nil, message is broadcast to all subscribers"
+    
+    property :reply_to,
+      required: false,
+      description: "Optional unique identifier of the entity that should receive replies to this message. Defaults to 'from' entity if not specified"
   end
 end

data/lib/smart_message/property_descriptions.rb

@@ -13,16 +13,17 @@ module SmartMessage
 
     module ClassMethods
       def property(property_name, options = {})
+        # Extract our custom option before passing to parent
         description = options.delete(:description)
         
-        # Store description if provided
+        # Call original property method first
+        super(property_name, options)
+        
+        # Then store description if provided
         if description
           @property_descriptions ||= {}
           @property_descriptions[property_name.to_sym] = description
         end
-        
-        # Call original property method
-        super(property_name, options)
       end
 
       def property_description(property_name)