smart_message 0.0.10 → 0.0.12

data/examples/redis_enhanced/README.md

@@ -0,0 +1,319 @@
+# Redis Enhanced Transport Examples
+
+This directory contains comprehensive examples demonstrating the advanced features of `SmartMessage::Transport::RedisEnhancedTransport`, which extends the basic Redis transport with RabbitMQ-style pattern matching and intelligent routing capabilities.
+
+## 🚀 What is Redis Enhanced Transport?
+
+The Redis Enhanced Transport is a powerful extension of the basic Redis transport that provides:
+
+- **Pattern-based subscriptions** with wildcard support (`*` and `#`)
+- **Fluent API** for building complex subscription patterns
+- **Dual channel publishing** for backwards compatibility
+- **Enhanced routing** with 3-part channel names: `message_type.from.to`
+- **Convenience methods** for common subscription patterns
+
+## 📊 Visual Guide to Key Concepts
+
+### Pattern Matching System
+
+![Enhanced Pattern Matching](../../docs/assets/images/enhanced-pattern-matching.svg)
+
+The enhanced transport uses sophisticated pattern matching to route messages. Unlike basic Redis pub/sub that requires exact channel matches, enhanced transport supports wildcard patterns similar to RabbitMQ:
+
+- **Single Wildcard (`*`)**: Matches exactly one segment
+- **Pattern Examples**: `ordermessage.*.*`, `*.payment_gateway.*`, `alertmessage.*.*`
+- **Smart Routing**: Messages are matched against all active patterns automatically
+
+### Fluent API Architecture
+
+![Enhanced Fluent API](../../docs/assets/images/enhanced-fluent-api.svg)
+
+The fluent API provides a chainable, readable syntax for building complex subscription patterns:
+
+- **Method Chaining**: `transport.where.from('api').to('service').subscribe`
+- **Builder Pattern**: Each method returns a builder for further chaining
+- **Pattern Generation**: Automatically converts fluent calls to optimized patterns
+- **Type Safety**: Validates patterns at build time
+
+### Dual Publishing Strategy
+
+![Enhanced Dual Publishing](../../docs/assets/images/enhanced-dual-publishing.svg)
+
+Enhanced transport maintains backwards compatibility through dual channel publishing:
+
+- **Backwards Compatible**: Basic Redis subscribers continue to work
+- **Gradual Migration**: Upgrade publishers without breaking existing systems  
+- **Dual Channels**: Messages published to both original and enhanced formats
+- **No Performance Penalty**: Efficient Redis handling of multiple channels
+
+### Microservices Routing
+
+![Enhanced Microservices Routing](../../docs/assets/images/enhanced-microservices-routing.svg)
+
+Perfect for complex microservices architectures requiring intelligent routing:
+
+- **Service-to-Service**: Direct routing between specific services
+- **Cross-Service Types**: Subscribe to message types across all services
+- **Alert Aggregation**: Centralized monitoring and alerting patterns
+- **Dynamic Routing**: Pattern-based routing adapts to service topology changes
+
+## 📁 Example Files
+
+### 1. `enhanced_01_basic_patterns.rb` - Pattern Subscriptions Fundamentals
+
+**Focus**: Basic pattern subscription capabilities
+
+**Key Features Demonstrated**:
+- Direct pattern subscriptions with wildcards
+- Convenience subscription methods
+- Enhanced vs. original channel publishing
+- Pattern-based message filtering
+
+**Run Example**:
+```bash
+ruby examples/redis_enhanced/enhanced_01_basic_patterns.rb
+```
+
+**Sample Patterns**:
+- `ordermessage.*.*` - All order messages
+- `*.payment_gateway.*` - All messages from payment gateway
+- `alertmessage.*.*` - All alert messages
+
+### 2. `enhanced_02_fluent_api.rb` - Fluent API for Complex Routing
+
+**Focus**: Fluent API for building readable subscription patterns
+
+**Key Features Demonstrated**:
+- Chainable `.where().from().to().type()` syntax
+- Complex multi-condition subscriptions
+- Microservices communication patterns
+- Pattern building and visualization
+
+**Run Example**:
+```bash
+ruby examples/redis_enhanced/enhanced_02_fluent_api.rb
+```
+
+**Sample Fluent Patterns**:
+```ruby
+transport.where.from('web-app').to('user-service').subscribe
+transport.where.type('AnalyticsEventMessage').from('web-app').subscribe
+transport.where.from('monitoring').to('admin-panel').type('AdminAlertMessage').subscribe
+```
+
+### 3. `enhanced_03_dual_publishing.rb` - Backwards Compatibility Demo
+
+**Focus**: Dual channel publishing and transport compatibility
+
+**Key Features Demonstrated**:
+- Publishing to both original and enhanced channels
+- Backwards compatibility with basic Redis transport
+- Cross-transport message communication
+- Channel naming conventions
+
+**Run Example**:
+```bash
+ruby examples/redis_enhanced/enhanced_03_dual_publishing.rb
+```
+
+**Publishing Behavior**:
+- Enhanced transport → publishes to BOTH channels
+- Basic transport → publishes to original channel only
+- Both can receive messages from each other
+
+### 4. `enhanced_04_advanced_routing.rb` - Complex Microservices Scenarios
+
+**Focus**: Advanced routing patterns for complex architectures
+
+**Key Features Demonstrated**:
+- Dynamic routing based on message content
+- Service-specific pattern matching
+- Log aggregation and metrics collection routing
+- Complex microservices communication
+
+**Run Example**:
+```bash
+ruby examples/redis_enhanced/enhanced_04_advanced_routing.rb
+```
+
+**Advanced Scenarios**:
+- API Gateway routing to multiple services
+- Database query routing from different ORM layers
+- Log level-based filtering and aggregation
+- Metrics collection from monitoring agents
+
+## 🔧 Prerequisites
+
+1. **Redis Server**: Make sure Redis is running
+   ```bash
+   # macOS
+   brew services start redis
+   
+   # Linux
+   sudo service redis start
+   ```
+
+2. **Ruby Dependencies**: Install required gems
+   ```bash
+   bundle install
+   ```
+
+3. **SmartMessage**: Ensure you're in the SmartMessage project root
+
+## 🌟 Key Concepts
+
+### Enhanced Channel Format
+
+Enhanced channels use a 3-part naming scheme:
+```
+message_type.from.to
+```
+
+Examples:
+- `ordermessage.api_gateway.order_service`
+- `paymentmessage.payment_service.bank_gateway`
+- `alertmessage.monitoring.admin_panel`
+
+### Pattern Wildcards
+
+- `*` - Matches exactly one segment
+- `#` - Matches zero or more segments (Redis doesn't support this natively, but Enhanced Transport simulates it)
+
+### Convenience Methods
+
+```ruby
+transport.subscribe_to_recipient('payment-service')     # *.*.payment-service
+transport.subscribe_from_sender('api-gateway')          # *.api-gateway.*
+transport.subscribe_to_type('OrderMessage')             # ordermessage.*.*
+transport.subscribe_to_alerts                           # emergency.*.*, *alert*.*.*, etc.
+transport.subscribe_to_broadcasts                       # *.*.broadcast
+```
+
+### Fluent API Pattern Building
+
+```ruby
+# Basic patterns
+transport.where.from('service-a').subscribe              # *.service-a.*
+transport.where.to('service-b').subscribe                # *.*.service-b
+transport.where.type('MessageType').subscribe            # messagetype.*.*
+
+# Combined patterns  
+transport.where.from('api').to('db').subscribe           # *.api.db
+transport.where.type('Order').from('web').subscribe      # order.web.*
+```
+
+## 🔍 Monitoring and Debugging
+
+### View Active Patterns
+
+Each example shows how to inspect active pattern subscriptions:
+
+```ruby
+pattern_subscriptions = transport.instance_variable_get(:@pattern_subscriptions)
+pattern_subscriptions.each { |pattern| puts pattern }
+```
+
+### Redis Channel Monitoring
+
+You can monitor Redis channels directly:
+
+```bash
+# Monitor all channels
+redis-cli monitor
+
+# List active channels
+redis-cli pubsub channels "*"
+
+# Monitor specific pattern
+redis-cli psubscribe "ordermessage.*"
+```
+
+## 🆚 Enhanced vs Basic vs Queue Transports
+
+| Feature | Basic Redis | Enhanced Redis | Redis Queue |
+|---------|-------------|----------------|-------------|
+| Channel Format | Class name only | `type.from.to` | Stream-based |
+| Pattern Support | None | Wildcard patterns | RabbitMQ-style |
+| Backwards Compatible | N/A | ✅ Yes | ❌ No |
+| Fluent API | ❌ No | ✅ Yes | ✅ Yes |
+| Persistent Messages | ❌ No | ❌ No | ✅ Yes |
+| Load Balancing | ❌ No | ❌ No | ✅ Yes |
+| Latency | ~1ms | ~1.2ms | ~0.5ms |
+| Concurrent Consumers | ~200 | ~250 | ~1000+ |
+| Memory Overhead | Low | Medium | Medium-High |
+| Setup Complexity | Low | Medium | High |
+
+## 🎯 Use Cases
+
+### When to Use Enhanced Transport
+
+- **Microservices Architecture**: Need sophisticated routing between services
+- **Legacy Compatibility**: Must work with existing basic Redis transport
+- **Pattern-Based Routing**: Want RabbitMQ-style patterns without RabbitMQ
+- **Development/Testing**: Need flexible routing for development environments
+- **Gradual Migration**: Moving from basic to more advanced messaging
+
+### When to Use Basic Transport
+
+- **Simple Scenarios**: Basic pub/sub without complex routing
+- **Minimal Overhead**: Want lightest-weight solution
+- **Legacy Systems**: Already using basic transport
+- **High Performance**: Need absolute minimum latency
+
+### When to Use Queue Transport
+
+- **Production Systems**: Need message persistence and reliability
+- **Load Balancing**: Multiple consumers processing messages
+- **Enterprise Features**: Dead letter queues, consumer groups, etc.
+- **High Throughput**: Maximum concurrent consumers and message rates
+
+## 🚀 Getting Started
+
+1. Start with `enhanced_01_basic_patterns.rb` to understand fundamentals
+2. Progress through `enhanced_02_fluent_api.rb` for advanced patterns  
+3. Explore `enhanced_03_dual_publishing.rb` for compatibility
+4. Study `enhanced_04_advanced_routing.rb` for complex scenarios
+
+Each example is self-contained and includes detailed explanations of the concepts being demonstrated.
+
+## 📝 Example Output
+
+When you run the examples, you'll see detailed output showing:
+- ✅ Subscription confirmations
+- 📤 Message publishing notifications  
+- 📦 Message processing with routing details
+- 🔍 Active pattern listings
+- 💡 Key insights and takeaways
+
+The examples use emojis and clear formatting to make the output easy to follow and understand.
+
+## 🔗 Related Documentation
+
+- **[Transport Comparison Guide](../../docs/transports/redis-transport-comparison.md)** - Detailed comparison of all three Redis transports
+- **[Transport Reference](../../docs/reference/transports.md)** - Complete API reference for enhanced transport
+- **[Architecture Overview](../../docs/core-concepts/architecture.md)** - SmartMessage framework architecture
+
+## 💡 Tips and Best Practices
+
+### Performance Optimization
+
+1. **Use Specific Patterns**: More specific patterns reduce CPU overhead
+2. **Limit Wildcard Usage**: Excessive wildcards can impact performance
+3. **Monitor Redis Memory**: Pattern subscriptions consume memory
+4. **Test Pattern Efficiency**: Use Redis monitoring to validate performance
+
+### Pattern Design Guidelines
+
+1. **Consistent Naming**: Use consistent service and message type names
+2. **Hierarchical Structure**: Design patterns with clear hierarchies
+3. **Avoid Over-Engineering**: Start simple, add complexity as needed
+4. **Document Patterns**: Maintain clear documentation of routing patterns
+
+### Migration Strategy
+
+1. **Start with Dual Publishing**: Enable enhanced transport on publishers first
+2. **Gradual Subscriber Migration**: Move subscribers one service at a time
+3. **Monitor Both Channels**: Ensure no message loss during migration
+4. **Performance Testing**: Validate performance before full deployment
+
+Happy messaging! 🎉

data/examples/redis_enhanced/enhanced_01_basic_patterns.rb

@@ -0,0 +1,233 @@
+#!/usr/bin/env ruby
+# examples/redis_queue/enhanced_01_basic_patterns.rb
+# Redis Enhanced Transport - Basic Pattern Subscriptions Demo
+
+require_relative '../../lib/smart_message'
+require 'smart_message/transport/redis_enhanced_transport'
+
+puts "🚀 Redis Enhanced Transport - Basic Pattern Subscriptions Demo"
+puts "=" * 60
+
+# Create enhanced Redis transport instance
+transport = SmartMessage::Transport::RedisEnhancedTransport.new(
+  url: 'redis://localhost:6379',
+  db: 2,  # Use database 2 for enhanced transport examples
+  auto_subscribe: true
+)
+
+#==============================================================================
+# Define Message Classes
+#==============================================================================
+
+class OrderMessage < SmartMessage::Base
+  from 'e-commerce-api'
+  to 'order-processor'
+  
+  transport transport
+  serializer SmartMessage::Serializer::Json.new
+  
+  property :order_id, required: true
+  property :customer_id, required: true
+  property :amount, required: true
+  property :items, default: []
+  
+  def self.process(wrapper)
+    header, payload = wrapper.split
+    data = JSON.parse(payload)
+    
+    puts "📦 [OrderMessage] Processing order #{data['order_id']}"
+    puts "   Customer: #{data['customer_id']}, Amount: $#{data['amount']}"
+    puts "   From: #{header.from} → To: #{header.to}"
+    puts "   Enhanced Channel: ordermessage.#{header.from.gsub('-', '_')}.#{header.to.gsub('-', '_')}"
+    puts
+  end
+end
+
+class PaymentMessage < SmartMessage::Base
+  from 'payment-gateway'
+  to 'bank-service'
+  
+  transport transport
+  serializer SmartMessage::Serializer::Json.new
+  
+  property :payment_id, required: true
+  property :amount, required: true
+  property :currency, default: 'USD'
+  
+  def self.process(wrapper)
+    header, payload = wrapper.split
+    data = JSON.parse(payload)
+    
+    puts "💳 [PaymentMessage] Processing payment #{data['payment_id']}"
+    puts "   Amount: #{data['amount']} #{data['currency']}"
+    puts "   From: #{header.from} → To: #{header.to}"
+    puts "   Enhanced Channel: paymentmessage.#{header.from.gsub('-', '_')}.#{header.to.gsub('-', '_')}"
+    puts
+  end
+end
+
+class AlertMessage < SmartMessage::Base
+  from 'monitoring-service'
+  
+  transport transport
+  serializer SmartMessage::Serializer::Json.new
+  
+  property :alert_type, required: true
+  property :severity, required: true
+  property :message, required: true
+  
+  def self.process(wrapper)
+    header, payload = wrapper.split
+    data = JSON.parse(payload)
+    
+    puts "🚨 [AlertMessage] #{data['severity'].upcase} ALERT: #{data['alert_type']}"
+    puts "   Message: #{data['message']}"
+    puts "   From: #{header.from} → To: #{header.to || 'broadcast'}"
+    puts "   Enhanced Channel: alertmessage.#{header.from.gsub('-', '_')}.#{(header.to || 'broadcast').gsub('-', '_')}"
+    puts
+  end
+end
+
+#==============================================================================
+# Demonstration Functions
+#==============================================================================
+
+def demo_basic_pattern_subscriptions(transport)
+  puts "🔍 Setting up basic pattern subscriptions..."
+  puts
+  
+  # Subscribe to specific message patterns
+  transport.subscribe_pattern("ordermessage.*.*")       # All order messages
+  transport.subscribe_pattern("*.payment_gateway.*")    # All messages from payment gateway
+  transport.subscribe_pattern("*.*.bank_service")       # All messages to bank service
+  transport.subscribe_pattern("alertmessage.*.*")       # All alert messages
+  
+  puts "✅ Subscribed to patterns:"
+  puts "   • ordermessage.*.* (all order messages)"
+  puts "   • *.payment_gateway.* (all from payment gateway)" 
+  puts "   • *.*.bank_service (all to bank service)"
+  puts "   • alertmessage.*.* (all alert messages)"
+  puts
+end
+
+def demo_convenience_subscriptions(transport)
+  puts "🎯 Setting up convenience method subscriptions..."
+  puts
+  
+  # Use convenience methods
+  transport.subscribe_to_recipient('order-processor')
+  transport.subscribe_from_sender('monitoring-service')
+  transport.subscribe_to_type('PaymentMessage')
+  transport.subscribe_to_alerts  # Subscribes to emergency/alert/alarm/critical patterns
+  transport.subscribe_to_broadcasts
+  
+  puts "✅ Convenience subscriptions added:"
+  puts "   • subscribe_to_recipient('order-processor')"
+  puts "   • subscribe_from_sender('monitoring-service')"
+  puts "   • subscribe_to_type('PaymentMessage')"
+  puts "   • subscribe_to_alerts (emergency/alert/alarm/critical patterns)"
+  puts "   • subscribe_to_broadcasts"
+  puts
+end
+
+def publish_sample_messages
+  puts "📤 Publishing sample messages..."
+  puts
+  
+  # Publish order message
+  order = OrderMessage.new(
+    order_id: 'ORD-001',
+    customer_id: 'CUST-123',
+    amount: 99.99,
+    items: ['Widget A', 'Widget B']
+  )
+  order.publish
+  
+  # Publish payment message
+  payment = PaymentMessage.new(
+    payment_id: 'PAY-001',
+    amount: 99.99,
+    currency: 'USD'
+  )
+  payment.publish
+  
+  # Publish alert message (broadcast)
+  alert = AlertMessage.new(
+    alert_type: 'system_overload',
+    severity: 'warning',
+    message: 'CPU usage exceeding 80%'
+  )
+  alert.to(nil)  # Make it a broadcast
+  alert.publish
+  
+  # Publish targeted alert
+  critical_alert = AlertMessage.new(
+    alert_type: 'database_connection_lost',
+    severity: 'critical',
+    message: 'Primary database connection failed'
+  )
+  critical_alert.to('ops-team')
+  critical_alert.publish
+  
+  puts "✅ Published 4 sample messages"
+  puts
+end
+
+#==============================================================================
+# Main Demonstration
+#==============================================================================
+
+begin
+  puts "🔧 Checking Redis connection..."
+  unless transport.connected?
+    puts "❌ Redis not available. Please start Redis server:"
+    puts "   brew services start redis  # macOS"
+    puts "   sudo service redis start   # Linux"
+    exit 1
+  end
+  puts "✅ Connected to Redis"
+  puts
+  
+  # Set up subscriptions
+  demo_basic_pattern_subscriptions(transport)
+  demo_convenience_subscriptions(transport)
+  
+  # Subscribe message classes to their handlers
+  OrderMessage.subscribe
+  PaymentMessage.subscribe
+  AlertMessage.subscribe
+  
+  puts "⏳ Waiting for subscriptions to be established..."
+  sleep 1
+  
+  # Publish sample messages
+  publish_sample_messages
+  
+  puts "⏳ Processing messages (waiting 3 seconds)..."
+  sleep 3
+  
+  puts "📊 Pattern Subscription Status:"
+  pattern_subscriptions = transport.instance_variable_get(:@pattern_subscriptions)
+  if pattern_subscriptions
+    pattern_subscriptions.each do |pattern|
+      puts "   • #{pattern}"
+    end
+  else
+    puts "   No pattern subscriptions found"
+  end
+  puts
+  
+  puts "🎉 Demo completed! Check the output above to see how messages were routed."
+  puts "💡 Notice how messages are published to both original channels (OrderMessage)"
+  puts "   and enhanced channels (ordermessage.e_commerce_api.order_processor)"
+  
+rescue Interrupt
+  puts "\n👋 Demo interrupted by user"
+rescue => e
+  puts "💥 Error: #{e.message}"
+  puts e.backtrace[0..3]
+ensure
+  puts "\n🧹 Cleaning up..."
+  transport&.disconnect
+  puts "✅ Disconnected from Redis"
+end