smart_message 0.0.7 → 0.0.9

data/docs/dispatcher.md

@@ -61,6 +61,93 @@ MyMessage.subscribe { |h,p| puts "Quick log" }
 # All handlers will receive the message
 ```
 
+### Message Filtering (NEW!)
+
+SmartMessage supports advanced message filtering using exact strings, regular expressions, or arrays for precise message routing:
+
+```ruby
+# Basic string filtering (exact match)
+MyMessage.subscribe(from: 'payment-service')
+MyMessage.subscribe(to: 'order-processor')
+
+# Regular expression filtering
+MyMessage.subscribe(from: /^payment-.*/)        # All payment services
+MyMessage.subscribe(to: /^(dev|staging)-.*/)    # Development environments
+
+# Array filtering (multiple options)
+MyMessage.subscribe(from: ['admin', 'system', 'monitoring'])
+
+# Mixed exact and pattern matching
+MyMessage.subscribe(from: ['admin', /^system-.*/, 'legacy-service'])
+
+# Combined filtering
+MyMessage.subscribe(
+  from: /^admin-.*/, 
+  to: ['order-service', /^fulfillment-.*/]
+)
+
+# Broadcast + directed filtering
+MyMessage.subscribe(broadcast: true, to: 'api-service')
+```
+
+#### Filter Types
+
+**String Filters (Exact Match)**
+```ruby
+# Subscribe only to messages from specific sender
+OrderMessage.subscribe(from: 'payment-service')
+
+# Subscribe only to messages directed to specific recipient
+OrderMessage.subscribe(to: 'order-processor')
+```
+
+**Regular Expression Filters (Pattern Match)**
+```ruby
+# Environment-based routing
+DevService.subscribe(to: /^(dev|staging)-.*/)
+ProdService.subscribe(to: /^prod-.*/)
+
+# Service pattern routing
+PaymentProcessor.subscribe(from: /^payment-.*/)
+ApiService.subscribe(from: /^(web|mobile|api)-.*/)
+```
+
+**Array Filters (Multiple Options)**
+```ruby
+# Multiple specific services
+AdminService.subscribe(from: ['admin', 'system', 'monitoring'])
+
+# Mixed patterns and exact matches
+AlertService.subscribe(from: ['admin', /^system-.*/, 'security'])
+```
+
+**Combined Filters**
+```ruby
+# Complex multi-criteria filtering
+OrderMessage.subscribe(
+  from: /^(admin|system)-.*/, 
+  to: ['order-service', /^fulfillment-.*/]
+)
+
+# Admin services to production only
+AdminMessage.subscribe(from: /^admin-.*/, to: /^prod-.*/)
+```
+
+#### Filter Validation
+
+Filters are validated at subscription time:
+
+```ruby
+# Valid filters
+MyMessage.subscribe(from: 'service')           # String
+MyMessage.subscribe(from: /^service-.*/)       # Regexp  
+MyMessage.subscribe(from: ['a', /^b-.*/])      # Array of String/Regexp
+
+# Invalid filters (raise ArgumentError)
+MyMessage.subscribe(from: 123)                 # Invalid type
+MyMessage.subscribe(from: ['valid', 123])      # Invalid array element
+```
+
 ### Removing Subscriptions
 
 ```ruby

data/docs/examples.md

@@ -807,4 +807,62 @@ end
 test_message_processing
 ```
 
-These examples demonstrate the flexibility and power of SmartMessage for building robust, scalable messaging systems. Each pattern can be adapted to your specific needs and combined with other patterns for more complex workflows.
+These examples demonstrate the flexibility and power of SmartMessage for building robust, scalable messaging systems. Each pattern can be adapted to your specific needs and combined with other patterns for more complex workflows.
+
+## Executable Example Programs
+
+The `examples/` directory contains complete, runnable programs that demonstrate various SmartMessage features:
+
+### Core Messaging Patterns
+- **`01_point_to_point_orders.rb`** - Point-to-point order processing with payment integration
+- **`02_publish_subscribe_events.rb`** - Event broadcasting to multiple services (email, SMS, audit)
+- **`03_many_to_many_chat.rb`** - Interactive chat system with rooms, bots, and human agents
+
+### Advanced Features
+- **`04_redis_smart_home_iot.rb`** - Redis-based IoT sensor monitoring with real-time data flow
+- **`05_proc_handlers.rb`** - Flexible message handlers (blocks, procs, lambdas, methods)
+- **`06_custom_logger_example.rb`** - Advanced logging with SmartMessage::Logger::Default
+- **`07_error_handling_scenarios.rb`** - Comprehensive validation, version mismatch, and error handling
+- **`08_entity_addressing_basic.rb`** - Basic FROM/TO/REPLY_TO message addressing
+- **`08_entity_addressing_with_filtering.rb`** - Advanced entity-aware message filtering
+- **`09_dead_letter_queue_demo.rb`** - Complete Dead Letter Queue system demonstration
+
+### Interactive Demos
+- **`tmux_chat/`** - Multi-pane terminal visualization of many-to-many messaging with file-based transport
+
+### Running Examples
+
+```bash
+# Navigate to the SmartMessage directory
+cd smart_message
+
+# Run any example directly
+ruby examples/01_point_to_point_orders.rb
+ruby examples/09_dead_letter_queue_demo.rb
+
+# For tmux chat demo
+cd examples/tmux_chat && ./run_demo.sh
+```
+
+Each example is self-contained and includes:
+- Clear educational comments
+- Multiple message classes
+- Complete setup and teardown
+- Real-world scenarios
+- Best practices demonstration
+
+### Example Features Demonstrated
+
+| Example | Transports | Features | Use Case |
+|---------|------------|----------|----------|
+| 01 | STDOUT | Point-to-point, validation | Order processing |
+| 02 | STDOUT | Pub-sub, multiple handlers | Event broadcasting |
+| 03 | Memory | Many-to-many, bots | Chat systems |
+| 04 | Redis | IoT, real-time, addressing | Smart home monitoring |
+| 05 | Memory | Proc handlers, flexibility | Dynamic message handling |
+| 06 | STDOUT | Custom logging, lifecycle | Production logging |
+| 07 | STDOUT | Error handling, validation | Robust message systems |
+| 08 | STDOUT | Entity addressing, filtering | Microservice communication |
+| 09 | Memory | DLQ, circuit breakers, replay | Production reliability |
+
+These examples provide practical, working code that you can use as a starting point for your own SmartMessage implementations.

data/docs/getting-started.md

@@ -40,11 +40,18 @@ class WelcomeMessage < SmartMessage::Base
   # Add a description for the message class
   description "Welcomes new users after successful signup"
   
-  # Configure entity addressing
+  # Configure entity addressing (Method 1: Direct methods)
   from 'user-service'           # Required: identifies sender
   to 'notification-service'     # Optional: specific recipient
   reply_to 'user-service'       # Optional: where responses go
   
+  # Alternative Method 2: Using header block
+  # header do
+  #   from 'user-service'
+  #   to 'notification-service'
+  #   reply_to 'user-service'
+  # end
+  
   # Define message properties
   property :user_name
   property :email