smart_message 0.0.4 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de5fce8e9cb793850301df5fdb9ad8a6954cf3a481cadc2deb625c373706723a
-  data.tar.gz: 0cc8067011377f0d574bc7f9bf1168ac2176fad7c7981cbd43f708e622a98fa0
+  metadata.gz: eac068dc19706e57d2c66a1dfe36981fbac33e6d7b180fe0429f81d874727cd4
+  data.tar.gz: 91585bc79637c4feab1256716519c0c3c7aa36c2b313ed09ebee7788b11d3f1a
 SHA512:
-  metadata.gz: bf7d1fc90d41bdbd3a8661f1f3e294915d29f267a68c13869926a4f829a00338f3878b03e14f26a7ccc9b248dc55b566e9988cb67aca7f6de596b94a51b5e885
-  data.tar.gz: 51c784d4183fe12862ff9250389a57233718604442e50303cdb941265971978e291fe7c3c1fec92509e6fa32bcc67b6b2fe8813b3cc1d06fa9d1f16645b181f3
+  metadata.gz: a0c0ead05e3cb104873e5cfa53cfc182ee06c6fd2f2e56fe02c0d64a4313dc4356b84d3b5be251e5438e6e381812848f6f587b005a315282204d8160f785f87b
+  data.tar.gz: 3a84537cca151b3b8f3efa16b9ad8591811be19ab5547013fe9f33d7df58474e5db2a74e85e669fb95c17e5b375dd2d889b3a3051b6ded765120dd208246c26a

data/CHANGELOG.md

@@ -7,6 +7,124 @@ 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
+- **Enhanced Description DSL**: Extended class-level `description` method with automatic defaults
+  - Classes without explicit descriptions now automatically get `"ClassName is a SmartMessage"` default
+  - Instance method `message.description` provides access to class description
+  - Backward compatible with existing description implementations
+  - Improves developer experience by eliminating nil description values
+- **Comprehensive Error Handling Example** (`examples/07_error_handling_scenarios.rb`)
+  - Demonstrates missing required property validation with detailed error messages
+  - Shows custom property validation failures with multiple validation types (regex, range, enum, proc)
+  - Illustrates version mismatch detection between message classes and headers
+  - **NEW**: Documents Hashie::Dash limitation where only first missing required property is reported
+  - Provides educational content about SmartMessage's robust validation framework
+  - Includes suggestions for potential improvements to multi-property validation
+- **Complete Property Documentation**: All examples now include comprehensive descriptions
+  - Message class descriptions added to all example programs (01-06 + tmux_chat)
+  - Individual property descriptions added with detailed explanations of purpose and format
+  - Enhanced readability and educational value of all demonstration code
+  - Consistent documentation patterns across all messaging scenarios
+
+### Fixed
+- **Critical: Infinite Loop Bug in Chat Examples**
+  - Fixed infinite message loops in `examples/03_many_to_many_chat.rb` and `examples/tmux_chat/bot_agent.rb`
+  - **Root Cause**: Bots responding to other bots' messages containing trigger keywords ("hello", "hi")
+  - **Solution**: Added `return if chat_data['message_type'] == 'bot'` to prevent bot-to-bot responses
+  - Examples now terminate properly without requiring manual intervention
+  - Maintains proper bot functionality for human interactions and explicit commands
+- **Example Termination**: Chat examples now shutdown cleanly without hanging indefinitely
+
+### Changed
+- **Enhanced Documentation Coverage**
+  - Updated README.md with comprehensive description DSL documentation
+  - Enhanced `docs/properties.md` with updated class description behavior and default handling
+  - Updated `docs/getting-started.md`, `docs/architecture.md`, and `docs/examples.md` with description examples
+  - All documentation now demonstrates proper message and property description usage
+- **Improved Example Educational Value**
+  - All example programs enhanced with descriptive class and property documentation
+  - Better demonstration of SmartMessage's self-documenting capabilities
+  - Examples serve as both functional demonstrations and documentation references
+
+### Documentation
+- **Hashie::Dash Limitation Discovery**: Documented important framework limitation in error handling example
+  - Only first missing required property reported during validation failures
+  - Provides clear explanation of incremental error discovery behavior
+  - Suggests potential solutions for improved multi-property validation
+- **Comprehensive Description System**: Complete documentation of message documentation capabilities
+  - Class-level description DSL with automatic defaults
+  - Property-level descriptions with usage patterns
+  - Integration with existing SmartMessage validation and introspection systems
+
 ## [0.0.2] - 2025-08-17
 
 ### 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,10 @@ 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
 - **Flexible Message Handlers**: Multiple subscription patterns - default methods, custom methods, blocks, procs, and lambdas
 - **Dual-Level Configuration**: Class and instance-level plugin overrides for gateway patterns
 - **Concurrent Processing**: Thread-safe message routing using `Concurrent::CachedThreadPool`
@@ -38,10 +42,40 @@ Or install it yourself as:
 
 ```ruby
 class OrderMessage < SmartMessage::Base
-  property :order_id, description: "Unique order identifier"
-  property :customer_id, description: "Customer's unique ID"
-  property :amount, description: "Total order amount in dollars"
-  property :items, description: "Array of ordered items"
+  # Declare schema version for compatibility tracking
+  version 2
+  
+  # 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,
+    message: "Order ID is required",
+    validate: ->(v) { v.is_a?(String) && v.length > 0 },
+    validation_message: "Order ID must be a non-empty string",
+    description: "Unique order identifier"
+    
+  property :customer_id, 
+    required: true,
+    message: "Customer ID is required",
+    description: "Customer's unique ID"
+    
+  property :amount, 
+    required: true,
+    message: "Amount is required",
+    validate: ->(v) { v.is_a?(Numeric) && v > 0 },
+    validation_message: "Amount must be a positive number",
+    description: "Total order amount in dollars"
+    
+  property :items, 
+    default: [],
+    description: "Array of ordered items"
 
   # Configure transport and serializer at class level
   config do
@@ -74,7 +108,7 @@ end
 ### 2. Publish Messages
 
 ```ruby
-# Create and publish a message
+# Create and publish a message (automatically validated before publishing)
 order = OrderMessage.new(
   order_id: "ORD-123",
   customer_id: "CUST-456", 
@@ -82,7 +116,16 @@ order = OrderMessage.new(
   items: ["Widget A", "Widget B"]
 )
 
-order.publish
+# Message is automatically validated before publishing
+order.publish  # Validates all properties, header, and version compatibility
+
+# Or validate manually
+if order.valid?
+  order.publish
+else
+  errors = order.validation_errors
+  errors.each { |err| puts "#{err[:property]}: #{err[:message]}" }
+end
 ```
 
 ### 3. Subscribe to Messages
@@ -116,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
@@ -286,14 +373,213 @@ end
 ## Message Lifecycle
 
 1. **Definition**: Create message class inheriting from `SmartMessage::Base`
-2. **Configuration**: Set transport, serializer, and logger plugins
-3. **Publishing**: Message instance is encoded and sent through transport
-4. **Subscription**: Message classes register handlers with dispatcher for processing
+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 {...})`)
-5. **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
+
+SmartMessage includes comprehensive validation and versioning capabilities to ensure message integrity and schema evolution support.
+
+### Version Declaration
+
+Declare your message schema version using the `version` class method:
+
+```ruby
+class OrderMessage < SmartMessage::Base
+  version 2  # Schema version 2
+  
+  property :order_id, required: true
+  property :customer_email  # Added in version 2
+end
+```
+
+### Property Validation
+
+Properties support multiple validation types with custom error messages:
+
+```ruby
+class UserMessage < SmartMessage::Base
+  version 1
+  
+  # Required field validation (Hashie built-in)
+  property :user_id, 
+    required: true,
+    message: "User ID is required and cannot be blank"
+  
+  # Custom validation with lambda
+  property :age,
+    validate: ->(v) { v.is_a?(Integer) && v.between?(1, 120) },
+    validation_message: "Age must be an integer between 1 and 120"
+  
+  # Email validation with regex
+  property :email,
+    validate: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i,
+    validation_message: "Must be a valid email address"
+  
+  # Inclusion validation with array
+  property :status,
+    validate: ['active', 'inactive', 'pending'],
+    validation_message: "Status must be active, inactive, or pending"
+end
+```
+
+### Validation Methods
+
+All message instances include validation methods:
+
+```ruby
+user = UserMessage.new(user_id: "123", age: 25)
+
+# Validate entire message (properties + header + version)
+user.validate!           # Raises SmartMessage::Errors::ValidationError on failure
+user.valid?              # Returns true/false
+
+# Get detailed validation errors
+errors = user.validation_errors
+errors.each do |error|
+  puts "#{error[:source]}.#{error[:property]}: #{error[:message]}"
+  # Example output:
+  # message.age: Age must be an integer between 1 and 120
+  # header.version: Header version must be a positive integer
+  # version_mismatch.version: Expected version 1, got: 2
+end
+```
+
+### Automatic Validation
+
+Messages are automatically validated during publishing:
+
+```ruby
+# This will raise ValidationError if invalid
+message = UserMessage.new(user_id: "", age: 150)
+message.publish  # Automatically validates before publishing
+```
+
+### Version Compatibility
+
+The framework automatically validates version compatibility:
+
+```ruby
+class V2Message < SmartMessage::Base
+  version 2
+  property :data
+end
+
+message = V2Message.new(data: "test")
+# Header automatically gets version: 2
+
+# Simulate version mismatch (e.g., from older message)
+message._sm_header.version = 1
+message.validate!  # Raises: "V2Message expects version 2, but header has version 1"
+```
+
+### Supported Validation Types
+
+- **Proc/Lambda**: `validate: ->(v) { v.length > 5 }`
+- **Regexp**: `validate: /\A[a-z]+\z/`
+- **Class**: `validate: String` (type checking)
+- **Array**: `validate: ['red', 'green', 'blue']` (inclusion)
+- **Range**: `validate: (1..100)` (range checking)
+- **Symbol**: `validate: :custom_validator_method`
+
+## Message Documentation
+
+SmartMessage provides built-in documentation capabilities for both message classes and their properties.
+
+### Class-Level Descriptions
+
+Use the `description` DSL method to document what your message class represents:
+
+```ruby
+class OrderMessage < SmartMessage::Base
+  description "Represents customer order data for processing and fulfillment"
+  
+  property :order_id, required: true
+  property :amount, required: true
+end
+
+class UserMessage < SmartMessage::Base  
+  description "Handles user management operations including registration and updates"
+  
+  property :user_id, required: true
+  property :email, required: true
+end
+
+# Access descriptions
+puts OrderMessage.description  
+# => "Represents customer order data for processing and fulfillment"
+
+puts UserMessage.description
+# => "Handles user management operations including registration and updates"
+
+# Instance access to class description
+order = OrderMessage.new(order_id: "123", amount: 99.99)
+puts order.description
+# => "Represents customer order data for processing and fulfillment"
+```
+
+### Default Descriptions
+
+Classes without explicit descriptions automatically get a default description:
+
+```ruby
+class MyMessage < SmartMessage::Base
+  property :data
+end
+
+puts MyMessage.description  
+# => "MyMessage is a SmartMessage"
+```
+
+### Property Documentation
+
+Combine class descriptions with property descriptions for comprehensive documentation:
+
+```ruby
+class FullyDocumented < SmartMessage::Base
+  description "A fully documented message class for demonstration purposes"
+  
+  property :id, 
+    description: "Unique identifier for the record"
+  property :name, 
+    description: "Display name for the entity"
+  property :status,
+    description: "Current processing status",
+    validate: ['active', 'inactive', 'pending']
+end
+
+# Access all documentation
+puts FullyDocumented.description
+# => "A fully documented message class for demonstration purposes"
+
+puts FullyDocumented.property_description(:id)
+# => "Unique identifier for the record"
+
+puts FullyDocumented.property_descriptions
+# => {:id=>"Unique identifier for the record", :name=>"Display name for the entity", ...}
+```
+
+### Documentation in Config Blocks
+
+You can also set descriptions within configuration blocks:
+
+```ruby
+class ConfiguredMessage < SmartMessage::Base
+  config do
+    description "Set within config block"
+    transport SmartMessage::Transport.create(:stdout)
+    serializer SmartMessage::Serializer::JSON.new
+  end
+end
+```
 
 ## Advanced Usage
 
@@ -353,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)