smart_message 0.0.5 → 0.0.6

data/lib/smart_message/base.rb

@@ -18,6 +18,9 @@ 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 = {}
     
@@ -69,6 +72,11 @@ 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(
@@ -76,7 +84,10 @@ module SmartMessage
         message_class:  self.class.to_s,
         published_at:   Time.now,
         publisher_pid:  Process.pid,
-        version:        self.class.version
+        version:        self.class.version,
+        from:           from,
+        to:             to,
+        reply_to:       reply_to
       )
       
       # Set up version validation to match the expected class version
@@ -234,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
 
@@ -358,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
 
@@ -369,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
@@ -405,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/header.rb

@@ -43,5 +43,19 @@ module SmartMessage
       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/transport/base.rb

@@ -35,8 +35,9 @@ module SmartMessage
       # Subscribe to a message class
       # @param message_class [String] The message class name
       # @param process_method [String] The processing method identifier
-      def subscribe(message_class, process_method)
-        @dispatcher.add(message_class, process_method)
+      # @param filter_options [Hash] Optional filtering criteria
+      def subscribe(message_class, process_method, filter_options = {})
+        @dispatcher.add(message_class, process_method, filter_options)
       end
 
       # Unsubscribe from a specific message class and process method

data/lib/smart_message/transport/redis_transport.rb

@@ -46,8 +46,8 @@ module SmartMessage
       end
 
       # Subscribe to a message class (Redis channel)
-      def subscribe(message_class, process_method)
-        super(message_class, process_method)
+      def subscribe(message_class, process_method, filter_options = {})
+        super(message_class, process_method, filter_options)
         
         @mutex.synchronize do
           @subscribed_channels.add(message_class)

data/lib/smart_message/version.rb

@@ -3,5 +3,5 @@
 # frozen_string_literal: true
 
 module SmartMessage
-  VERSION = '0.0.5'
+  VERSION = '0.0.6'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smart_message
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -199,6 +199,7 @@ files:
 - bin/console
 - bin/setup
 - docs/README.md
+- docs/addressing.md
 - docs/architecture.md
 - docs/dispatcher.md
 - docs/examples.md
@@ -219,6 +220,8 @@ files:
 - examples/05_proc_handlers.rb
 - examples/06_custom_logger_example.rb
 - examples/07_error_handling_scenarios.rb
+- examples/08_entity_addressing_basic.rb
+- examples/08_entity_addressing_with_filtering.rb
 - examples/README.md
 - examples/smart_home_iot_dataflow.md
 - examples/tmux_chat/README.md