smart_message 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c388c9738746603d14a57d6c4e04fb7d6e48156c4e571cd82dffd461217e111
-  data.tar.gz: 975779de0b52686b8b08baa94070fea52578c86f5fb1a3752aa25cad98a812d7
+  metadata.gz: eac068dc19706e57d2c66a1dfe36981fbac33e6d7b180fe0429f81d874727cd4
+  data.tar.gz: 91585bc79637c4feab1256716519c0c3c7aa36c2b313ed09ebee7788b11d3f1a
 SHA512:
-  metadata.gz: b425fa9d66a2716394a1dc695b8ba82c9acc9c82dc616fc00cf8eeab2639a7833640e71240969614f31836ee0d325ae8980fa4f4d266e6961dfd6a8971172420
-  data.tar.gz: 711381ff80115a8582551fc58f22630c9c103c24d46f04b1edc54b87d41fd181d80a0f730cc6d14a000ec3b5478330062385edb6e5344fe1e541559e82652c97
+  metadata.gz: a0c0ead05e3cb104873e5cfa53cfc182ee06c6fd2f2e56fe02c0d64a4313dc4356b84d3b5be251e5438e6e381812848f6f587b005a315282204d8160f785f87b
+  data.tar.gz: 3a84537cca151b3b8f3efa16b9ad8591811be19ab5547013fe9f33d7df58474e5db2a74e85e669fb95c17e5b375dd2d889b3a3051b6ded765120dd208246c26a

data/CHANGELOG.md

@@ -7,6 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.6] 2025-08-19
+
+### Added
+- **Entity-Aware Message Filtering**: Advanced subscription filtering system enabling precise message routing
+  - New subscription filter parameters: `broadcast:`, `to:`, `from:` for `subscribe` method
+  - Filter by broadcast messages only: `MyMessage.subscribe(broadcast: true)`
+  - Filter by destination entity: `MyMessage.subscribe(to: 'service-name')`
+  - Filter by sender entity: `MyMessage.subscribe(from: 'sender-service')`
+  - Support for array-based filters: `subscribe(from: ['admin', 'system'])`
+  - Combined filters with OR logic: `subscribe(broadcast: true, to: 'my-service')`
+  - String-to-array automatic conversion for convenience: `subscribe(to: 'service')` becomes `['service']`
+  - Full backward compatibility - existing subscriptions work unchanged
+- **Real-Time Header Synchronization**: Message headers now update automatically when addressing fields change
+  - Instance-level `from()`, `to()`, `reply_to()` methods now update both instance variables and message headers
+  - Enables filtering to work correctly when addressing is changed after message creation
+  - Reset methods (`reset_from`, `reset_to`, `reset_reply_to`) also update headers
+  - Critical for entity-aware filtering functionality
+- **Enhanced Example Programs**
+  - New comprehensive filtering example: `examples/08_entity_addressing_with_filtering.rb`
+  - Demonstrates all filtering capabilities with real-world microservice scenarios
+  - Improved timing with sleep statements for better output visualization
+  - Updated basic addressing example: `examples/08_entity_addressing_basic.rb`
+  - Both examples now show clear interleaved publish/receive output flow
+
+### Changed
+- **Message Subscription Architecture**: Subscription storage updated to support filtering
+  - Dispatcher now stores subscription objects with filter criteria instead of simple method strings
+  - Subscription objects contain `{process_method: string, filters: hash}` structure
+  - All transport implementations updated to pass filter options through subscription chain
+  - RedisTransport updated to accept new filter_options parameter
+- **Header Addressing Behavior**: Message headers now reflect real-time addressing changes
+  - **BREAKING**: Headers are no longer immutable after creation - they update when addressing methods are called
+  - This change enables entity-aware filtering to work correctly with dynamic addressing
+  - Previous behavior kept original addressing in headers while instance methods showed new values
+
+### Fixed
+- **Message Filtering Logic**: Resolved critical filtering implementation issues
+  - Fixed message_matches_filters? method to properly evaluate filter criteria
+  - Corrected AND/OR logic for combined broadcast and entity-specific filters
+  - Ensured filtering works with both class-level and instance-level addressing
+- **Test Suite Compatibility**: Updated all tests to work with new subscription structure
+  - Fixed ProcHandlerTest to expect subscription objects instead of string arrays
+  - Updated TransportTest to handle new subscription object format
+  - Fixed AddressingTest to reflect new real-time header update behavior
+  - All existing functionality preserved with full backward compatibility
+
+### Enhanced
+- **Message Processing Performance**: Filtering happens at subscription level, reducing processing overhead
+  - Messages not matching filter criteria are ignored by handlers, improving efficiency
+  - Enables microservices to process only relevant messages
+  - Reduces unnecessary handler invocations and processing cycles
+- **Developer Experience**: Clear examples demonstrate filtering benefits and usage patterns
+  - Examples show both what DOES and DOESN'T get processed
+  - Demonstrates gateway patterns, admin message handling, and microservice communication
+  - Educational value enhanced with comprehensive console output and timing
+
+### Documentation
+- **Entity-Aware Filtering Guide**: Comprehensive examples showing all filtering capabilities
+  - Broadcast vs directed message handling patterns
+  - Admin/monitoring system integration examples
+  - Request-reply routing with filters
+  - Gateway pattern implementations with dynamic routing
+  - Best practices for microservice message filtering
+- **Breaking Change Documentation**: Clear explanation of header behavior changes
+  - Migration guide for applications depending on immutable headers
+  - Benefits of real-time header updates for filtering functionality
+
 ## [0.0.5] 2025-08-18
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    smart_message (0.0.4)
+    smart_message (0.0.6)
       activesupport
       concurrent-ruby
       hashie

data/README.md

@@ -9,6 +9,7 @@ SmartMessage is a message abstraction framework that decouples business logic fr
 
 - **Transport Abstraction**: Plugin architecture supporting multiple message transports (Redis, RabbitMQ, Kafka, etc.)
 - **Serialization Flexibility**: Pluggable serialization formats (JSON, MessagePack, etc.)
+- **Entity-to-Entity Addressing**: Built-in FROM/TO/REPLY_TO addressing for point-to-point and broadcast messaging patterns
 - **Schema Versioning**: Built-in version management with automatic compatibility validation
 - **Comprehensive Validation**: Property validation with custom error messages and automatic validation before publishing
 - **Message Documentation**: Built-in documentation support for message classes and properties with automatic defaults
@@ -47,6 +48,11 @@ class OrderMessage < SmartMessage::Base
   # Add a description for the message class
   description "Represents customer order data for processing and fulfillment"
   
+  # Configure entity addressing
+  from 'order-service'
+  to 'fulfillment-service'  # Point-to-point message
+  reply_to 'order-service'  # Responses come back here
+  
   # Required properties with validation
   property :order_id, 
     required: true,
@@ -153,6 +159,50 @@ end
 OrderMessage.subscribe(audit_handler)
 ```
 
+### 4. Entity Addressing
+
+SmartMessage supports entity-to-entity addressing with FROM/TO/REPLY_TO fields for advanced message routing:
+
+```ruby
+# Point-to-point messaging
+class PaymentMessage < SmartMessage::Base
+  version 1
+  from 'payment-service'     # Required: sender identity
+  to 'bank-gateway'          # Optional: specific recipient
+  reply_to 'payment-service' # Optional: where responses go
+  
+  property :amount, required: true
+  property :account_id, required: true
+end
+
+# Broadcast messaging (no 'to' specified)
+class SystemAnnouncementMessage < SmartMessage::Base
+  version 1
+  from 'admin-service'       # Required: sender identity
+  # No 'to' field = broadcast to all subscribers
+  
+  property :message, required: true
+  property :priority, default: 'normal'
+end
+
+# Instance-level addressing override
+payment = PaymentMessage.new(amount: 100.00, account_id: "ACCT-123")
+payment.to('backup-gateway')  # Override destination for this instance
+payment.publish
+
+# Access addressing information
+puts payment._sm_header.from      # => 'payment-service'
+puts payment._sm_header.to        # => 'backup-gateway'
+puts payment._sm_header.reply_to  # => 'payment-service'
+```
+
+#### Messaging Patterns Supported
+
+- **Point-to-Point**: Set `to` field for direct entity targeting
+- **Broadcast**: Omit `to` field (nil) for message broadcast to all subscribers  
+- **Request-Reply**: Use `reply_to` field to specify response routing
+- **Gateway Patterns**: Override addressing at instance level for message forwarding
+
 ## Architecture
 
 ### Core Components
@@ -323,15 +373,16 @@ end
 ## Message Lifecycle
 
 1. **Definition**: Create message class inheriting from `SmartMessage::Base`
-2. **Configuration**: Set transport, serializer, and logger plugins
-3. **Validation**: Messages are automatically validated before publishing (properties, header, version compatibility)
-4. **Publishing**: Message instance is encoded and sent through transport
+2. **Configuration**: Set transport, serializer, logger plugins, and entity addressing (from/to/reply_to)
+3. **Validation**: Messages are automatically validated before publishing (properties, header, addressing, version compatibility)
+4. **Publishing**: Message instance is encoded with addressing metadata and sent through transport
 5. **Subscription**: Message classes register handlers with dispatcher for processing
    - Default handlers (`self.process` method)
    - Custom method handlers (`"ClassName.method_name"`)
    - Block handlers (`subscribe do |h,p|...end`)
    - Proc/Lambda handlers (`subscribe(proc {...})`)
-6. **Processing**: Received messages are decoded and routed to registered handlers
+6. **Routing**: Dispatcher uses addressing metadata to route messages (point-to-point vs broadcast)
+7. **Processing**: Received messages are decoded and routed to registered handlers
 
 ## Schema Versioning and Validation
 
@@ -588,6 +639,9 @@ puts message._sm_header.uuid
 puts message._sm_header.message_class
 puts message._sm_header.published_at
 puts message._sm_header.publisher_pid
+puts message._sm_header.from
+puts message._sm_header.to
+puts message._sm_header.reply_to
 ```
 
 ## Development

data/docs/README.md

@@ -16,6 +16,7 @@ Welcome to the comprehensive documentation for SmartMessage, a Ruby gem that abs
 ### Components
 - [SmartMessage::Base](base.md)
 - [Property System](properties.md)
+- [Entity Addressing](addressing.md)
 - [Transport Layer](transports.md)
 - [Serializers](serializers.md)
 - [Logging System](logging.md)

data/docs/addressing.md

@@ -0,0 +1,364 @@
+# Entity Addressing
+
+SmartMessage supports entity-to-entity addressing through built-in FROM/TO/REPLY_TO fields in message headers. This enables sophisticated messaging patterns including point-to-point communication, broadcast messaging, and request-reply workflows.
+
+## Overview
+
+Entity addressing in SmartMessage provides:
+
+- **Sender Identification**: Required `from` field identifies the sending entity
+- **Recipient Targeting**: Optional `to` field for point-to-point messaging  
+- **Response Routing**: Optional `reply_to` field for request-reply patterns
+- **Broadcast Support**: Omitting `to` field enables broadcast to all subscribers
+- **Dual-Level Configuration**: Class and instance-level addressing configuration
+
+## Address Fields
+
+### FROM (Required)
+The `from` field identifies the entity sending the message. This is required for all messages.
+
+```ruby
+class MyMessage < SmartMessage::Base
+  from 'order-service'  # Required sender identity
+  
+  property :data
+end
+```
+
+### TO (Optional)
+The `to` field specifies the intended recipient entity. When present, creates point-to-point messaging. When `nil`, the message is broadcast to all subscribers.
+
+```ruby
+# Point-to-point messaging
+class DirectMessage < SmartMessage::Base
+  from 'sender-service'
+  to 'recipient-service'  # Specific target
+  
+  property :content
+end
+
+# Broadcast messaging
+class AnnouncementMessage < SmartMessage::Base
+  from 'admin-service'
+  # No 'to' field = broadcast to all subscribers
+  
+  property :announcement
+end
+```
+
+### REPLY_TO (Optional)
+The `reply_to` field specifies where responses should be sent. Defaults to the `from` entity if not specified.
+
+```ruby
+class RequestMessage < SmartMessage::Base
+  from 'client-service'
+  to 'api-service'
+  reply_to 'client-callback-service'  # Responses go here
+  
+  property :request_data
+end
+```
+
+## Configuration Patterns
+
+### Class-Level Configuration
+
+Set default addressing for all instances of a message class:
+
+```ruby
+class PaymentMessage < SmartMessage::Base
+  version 1
+  
+  # Class-level addressing
+  from 'payment-service'
+  to 'bank-gateway'
+  reply_to 'payment-service'
+  
+  property :amount, required: true
+  property :account_id, required: true
+end
+
+# All instances inherit class addressing
+payment = PaymentMessage.new(amount: 100.00, account_id: "ACCT-123")
+puts payment._sm_header.from     # => 'payment-service'
+puts payment._sm_header.to       # => 'bank-gateway'
+puts payment._sm_header.reply_to # => 'payment-service'
+```
+
+### Instance-Level Overrides
+
+Override addressing for specific message instances:
+
+```ruby
+class FlexibleMessage < SmartMessage::Base
+  from 'service-a'
+  to 'service-b'
+  
+  property :data
+end
+
+# Override addressing for this instance
+message = FlexibleMessage.new(data: "test")
+message.from('different-sender')
+message.to('different-recipient')
+message.reply_to('different-reply-service')
+
+puts message.from     # => 'different-sender'
+puts message.to       # => 'different-recipient' 
+puts message.reply_to # => 'different-reply-service'
+
+# Class defaults remain unchanged
+puts FlexibleMessage.from # => 'service-a'
+puts FlexibleMessage.to   # => 'service-b'
+```
+
+## Messaging Patterns
+
+### Point-to-Point Messaging
+
+Direct communication between two specific entities:
+
+```ruby
+class OrderProcessingMessage < SmartMessage::Base
+  from 'order-service'
+  to 'inventory-service'  # Direct target
+  reply_to 'order-service'
+  
+  property :order_id, required: true
+  property :items, required: true
+end
+
+# Message goes directly to inventory-service
+order = OrderProcessingMessage.new(
+  order_id: "ORD-123", 
+  items: ["widget-1", "widget-2"]
+)
+order.publish  # Only inventory-service receives this
+```
+
+### Broadcast Messaging
+
+Send message to all subscribers by omitting the `to` field:
+
+```ruby
+class SystemMaintenanceMessage < SmartMessage::Base
+  from 'admin-service'
+  # No 'to' field = broadcast
+  
+  property :message, required: true
+  property :scheduled_time, required: true
+end
+
+# Message goes to all subscribers
+maintenance = SystemMaintenanceMessage.new(
+  message: "System maintenance tonight at 2 AM",
+  scheduled_time: Time.parse("2024-01-15 02:00:00")
+)
+maintenance.publish  # All subscribers receive this
+```
+
+### Request-Reply Pattern
+
+Structured request-response communication:
+
+```ruby
+# Request message
+class UserLookupRequest < SmartMessage::Base
+  from 'web-service'
+  to 'user-service'
+  reply_to 'web-service'  # Responses come back here
+  
+  property :user_id, required: true
+  property :request_id, required: true  # For correlation
+end
+
+# Response message  
+class UserLookupResponse < SmartMessage::Base
+  from 'user-service'
+  # 'to' will be set to the original 'reply_to' value
+  
+  property :user_id, required: true
+  property :request_id, required: true  # Correlation ID
+  property :user_data
+  property :success, default: true
+end
+
+# Send request
+request = UserLookupRequest.new(
+  user_id: "USER-123",
+  request_id: SecureRandom.uuid
+)
+request.publish
+
+# In user-service handler:
+class UserLookupRequest
+  def self.process(header, payload)
+    request_data = JSON.parse(payload)
+    
+    # Process lookup...
+    user_data = UserService.find(request_data['user_id'])
+    
+    # Send response back to reply_to address
+    response = UserLookupResponse.new(
+      user_id: request_data['user_id'],
+      request_id: request_data['request_id'],
+      user_data: user_data
+    )
+    response.to(header.reply_to)  # Send to original reply_to
+    response.publish
+  end
+end
+```
+
+### Gateway Pattern
+
+Forward messages between different transports/formats:
+
+```ruby
+class GatewayMessage < SmartMessage::Base
+  from 'gateway-service'
+  
+  property :original_message
+  property :source_format
+  property :target_format
+end
+
+# Receive from one transport/format
+incoming = SomeMessage.new(data: "from system A")
+
+# Forward to different system with different addressing
+gateway_msg = GatewayMessage.new(
+  original_message: incoming.to_h,
+  source_format: 'json',
+  target_format: 'xml'
+)
+
+# Override transport and addressing for forwarding
+gateway_msg.config do
+  transport DifferentTransport.new
+  serializer DifferentSerializer.new
+end
+gateway_msg.to('system-b')
+gateway_msg.publish
+```
+
+## Address Validation
+
+The `from` field is required and validated automatically:
+
+```ruby
+class InvalidMessage < SmartMessage::Base
+  # No 'from' specified - will fail validation
+  property :data
+end
+
+message = InvalidMessage.new(data: "test")
+message.publish  # Raises SmartMessage::Errors::ValidationError
+# => "The property 'from' From entity ID is required for message routing and replies"
+```
+
+## Header Access
+
+Access addressing information from message headers:
+
+```ruby
+class SampleMessage < SmartMessage::Base
+  from 'sample-service'
+  to 'target-service'
+  reply_to 'callback-service'
+  
+  property :content
+end
+
+message = SampleMessage.new(content: "Hello")
+header = message._sm_header
+
+puts header.from      # => 'sample-service'
+puts header.to        # => 'target-service'  
+puts header.reply_to  # => 'callback-service'
+puts header.uuid      # => Generated UUID
+puts header.message_class  # => 'SampleMessage'
+```
+
+## Integration with Dispatcher
+
+The dispatcher can use addressing metadata for advanced routing logic:
+
+```ruby
+# Future enhancement: Dispatcher filtering by recipient
+# dispatcher.route(message_header, payload) do |header|
+#   if header.to.nil?
+#     # Broadcast to all subscribers
+#     route_to_all_subscribers(header.message_class)
+#   else
+#     # Route only to specific recipient
+#     route_to_entity(header.to, header.message_class)
+#   end
+# end
+```
+
+## Best Practices
+
+### Entity Naming
+Use consistent, descriptive entity identifiers:
+
+```ruby
+# Good: Descriptive service names
+from 'order-management-service'
+to 'inventory-tracking-service'
+reply_to 'order-status-service'
+
+# Avoid: Generic or unclear names
+from 'service1'
+to 'app'
+```
+
+### Address Consistency
+Maintain consistent addressing patterns across your application:
+
+```ruby
+# Consistent pattern for microservices
+class OrderMessage < SmartMessage::Base
+  from 'order-service'
+  to 'fulfillment-service'
+  reply_to 'order-service'
+end
+
+class PaymentMessage < SmartMessage::Base  
+  from 'payment-service'
+  to 'billing-service'
+  reply_to 'payment-service'
+end
+```
+
+### Gateway Configuration
+For gateway patterns, use instance-level overrides:
+
+```ruby
+# Class defines default routing
+class APIMessage < SmartMessage::Base
+  from 'api-gateway'
+  to 'internal-service'
+end
+
+# Override for external routing
+message = APIMessage.new(data: "external request")
+message.to('external-partner-service')
+message.config do
+  transport ExternalTransport.new
+  serializer SecureSerializer.new
+end
+message.publish
+```
+
+## Future Enhancements
+
+The addressing system provides the foundation for advanced features:
+
+- **Dispatcher Filtering**: Route messages based on recipient targeting
+- **Security Integration**: Entity-based authentication and authorization
+- **Audit Trails**: Track message flow between entities
+- **Load Balancing**: Distribute messages across entity instances
+- **Circuit Breakers**: Per-entity failure handling
+
+Entity addressing enables sophisticated messaging architectures while maintaining the simplicity and flexibility that makes SmartMessage powerful.

data/docs/getting-started.md

@@ -40,6 +40,11 @@ class WelcomeMessage < SmartMessage::Base
   # Add a description for the message class
   description "Welcomes new users after successful signup"
   
+  # Configure entity addressing
+  from 'user-service'           # Required: identifies sender
+  to 'notification-service'     # Optional: specific recipient
+  reply_to 'user-service'       # Optional: where responses go
+  
   # Define message properties
   property :user_name
   property :email
@@ -153,6 +158,9 @@ puts message._sm_header.uuid          # Unique identifier
 puts message._sm_header.message_class # "WelcomeMessage"
 puts message._sm_header.published_at  # Timestamp when published
 puts message._sm_header.publisher_pid # Process ID of publisher
+puts message._sm_header.from          # 'user-service'
+puts message._sm_header.to            # 'notification-service'
+puts message._sm_header.reply_to      # 'user-service'
 ```
 
 ### Transports
@@ -222,6 +230,36 @@ OrderMessage.subscribe("OrderService.process_order")
 - **Proc**: Reusable handlers that work across multiple message types
 - **Method**: Complex business logic organized in service classes
 
+### Entity Addressing
+
+SmartMessage supports entity-to-entity addressing for sophisticated messaging patterns:
+
+```ruby
+# Point-to-point messaging
+class PaymentMessage < SmartMessage::Base
+  from 'payment-service'    # Required: sender identity
+  to 'bank-gateway'         # Optional: specific recipient
+  reply_to 'payment-service' # Optional: where responses go
+  
+  property :amount, required: true
+end
+
+# Broadcast messaging (no 'to' field)
+class AnnouncementMessage < SmartMessage::Base
+  from 'admin-service'      # Required sender
+  # No 'to' = broadcast to all subscribers
+  
+  property :message, required: true
+end
+
+# Instance-level addressing override
+payment = PaymentMessage.new(amount: 100.00)
+payment.to('backup-gateway')  # Override destination
+payment.publish
+```
+
+For more details, see [Entity Addressing](addressing.md).
+
 ## Next Steps
 
 Now that you have the basics working, explore: