smart_message 0.0.10 → 0.0.12

data/docs/index.md

@@ -0,0 +1,64 @@
+# SmartMessage Documentation
+
+<table border="0">
+<tr>
+<td width="30%" valign="top">
+  <img src="assets/images/smart_message.jpg" alt="SmartMessage Logo" width="200" />
+</td>
+<td width="70%" valign="top">
+
+<string>SmartMessage</strong> is a powerful Ruby framework that transforms ordinary messages into intelligent, self-aware entities capable of routing themselves, validating their contents, and executing business logic. By abstracting away the complexities of transport mechanisms (Redis, RabbitMQ, Kafka) and serialization formats (JSON, MessagePack), SmartMessage lets you focus on what matters: your business logic.
+<br/><br/>
+Think of SmartMessage as ActiveRecord for messaging - just as ActiveRecord frees you from database-specific SQL, SmartMessage liberates your messages from transport-specific implementations. Each message knows how to validate itself, where it came from, where it's going, and what to do when it arrives. With built-in support for filtering, versioning, deduplication, and concurrent processing, SmartMessage provides enterprise-grade messaging capabilities with the simplicity Ruby developers love.
+
+</td>
+</tr>
+</table>
+
+## Table of Contents
+
+### Getting Started
+- [Quick Start](getting-started/quick-start.md)
+- [Basic Usage Examples](getting-started/examples.md)
+
+### Core Concepts
+- [Architecture Overview](core-concepts/architecture.md)
+- [Property System](core-concepts/properties.md)
+- [Entity Addressing](core-concepts/addressing.md)
+- [Message Filtering](core-concepts/message-filtering.md)
+- [Message Processing](core-concepts/message-processing.md)
+- [Dispatcher & Routing](core-concepts/dispatcher.md)
+
+### Transports
+- [Transport Layer](reference/transports.md)
+- [Redis Queue Transport](transports/redis-queue-transport.md) ⭐ **Featured**
+- [Redis Transport Comparison](transports/redis-transport-comparison.md)
+
+### Guides
+- [Redis Queue Getting Started](guides/redis-queue-getting-started.md)
+- [Advanced Routing Patterns](guides/redis-queue-patterns.md)
+- [Production Deployment](guides/redis-queue-production.md)
+
+### Reference
+- [Serializers](reference/serializers.md)
+- [Logging System](reference/logging.md)
+- [Dead Letter Queue](reference/dead-letter-queue.md)
+- [Message Deduplication](reference/message-deduplication.md)
+- [Proc Handlers](reference/proc-handlers.md)
+
+### Development
+- [Troubleshooting](development/troubleshooting.md)
+- [Ideas & Roadmap](development/ideas.md)
+
+## Quick Navigation
+
+- **New to SmartMessage?** Start with [Quick Start](getting-started/quick-start.md)
+- **Need examples?** Check out [Examples](getting-started/examples.md)
+- **Understanding the architecture?** Read [Architecture Overview](core-concepts/architecture.md)
+- **Having issues?** Visit [Troubleshooting](development/troubleshooting.md)
+
+## Version
+
+This documentation is for SmartMessage v0.0.8.
+
+For older versions, please check the git tags and corresponding documentation.

data/docs/{dead_letter_queue.md → reference/dead-letter-queue.md}

@@ -93,10 +93,9 @@ The DLQ operates as a First-In-First-Out queue:
 ```ruby
 dlq = SmartMessage::DeadLetterQueue.default
 
-# Add a failed message
+# Add a failed message (accepts decoded message instance)
 entry = dlq.enqueue(
-  message_header,      # SmartMessage::Header object
-  message_payload,     # Serialized message string
+  decoded_message,     # SmartMessage::Base instance
   error: "Connection timeout",
   retry_count: 0,
   transport: "Redis",

data/docs/{logging.md → reference/logging.md}

@@ -505,4 +505,4 @@ logger.info("Test message")
 assert_includes log_output.string, "Test message"
 ```
 
-For more information, see the comprehensive logging example at `examples/show_logger.rb`.
+For more information, see the comprehensive logging examples at `examples/memory/15_logger_demo.rb` and `examples/memory/08_custom_logger_demo.rb`.

data/docs/{message_deduplication.md → reference/message-deduplication.md}

@@ -1,3 +1,4 @@
+
 # Message Deduplication
 
 SmartMessage provides a comprehensive message deduplication system using Deduplication Queues (DDQ) to prevent duplicate processing of messages with the same UUID. The system is designed with handler-scoped isolation, ensuring that different message handlers maintain independent deduplication state.

data/docs/{proc_handlers_summary.md → reference/proc-handlers.md}

@@ -92,7 +92,7 @@ MyMessage.unsubscribe(block_id)
 
 - Default handler compatibility
 - Block handler functionality
-- Proc parameter handler functionality  
+- Proc parameter handler functionality
 - Lambda handler functionality
 - Multiple handlers for same message type
 - Mixed handler types (method + proc)
@@ -114,7 +114,7 @@ MyMessage.unsubscribe(block_id)
 ### Test Results
 
 - **55 total tests** (10 new proc handler tests + existing tests)
-- **276 assertions** 
+- **276 assertions**
 - **All tests passing**
 - **Full backward compatibility** maintained
 
@@ -153,17 +153,17 @@ MyMessage.unsubscribe(block_id)
 
 ## Examples
 
-### 1. New Working Example (`examples/05_proc_handlers.rb`)
+### 1. New Working Example (`examples/memory/07_proc_handlers_demo.rb`)
 
 Complete demonstration of all handler types:
 - Default handler (self.process)
-- Block handlers (inline logic)  
+- Block handlers (inline logic)
 - Proc handlers (reusable logic)
 - Lambda handlers (functional style)
 - Method handlers (service classes)
 - Handler management and unsubscription
 
-### 2. Enhanced IoT Example (`examples/04_redis_smart_home_iot.rb`)
+### 2. Enhanced IoT Example (`examples/redis/01_smart_home_iot_demo.rb`)
 
 Production-ready Redis transport example showing real-world usage patterns.
 
@@ -234,6 +234,7 @@ Production-ready Redis transport example showing real-world usage patterns.
 ## Future Enhancements
 
 Potential areas for future development:
+
 - Handler priority/ordering
 - Conditional handler execution
 - Handler metrics and monitoring
@@ -244,4 +245,4 @@ Potential areas for future development:
 
 The enhanced subscription functionality provides SmartMessage users with powerful, flexible options for message processing while maintaining the simplicity and elegance of the original design. The implementation is production-ready, thoroughly tested, and fully documented.
 
-This enhancement positions SmartMessage as a more versatile and developer-friendly messaging framework suitable for both simple prototypes and complex enterprise applications.
+This enhancement positions SmartMessage as a more versatile and developer-friendly messaging framework suitable for both simple prototypes and complex enterprise applications.

data/docs/{serializers.md → reference/serializers.md}

@@ -26,7 +26,7 @@ The default serializer that converts messages to/from JSON format.
 
 ```ruby
 # Basic usage
-serializer = SmartMessage::Serializer::JSON.new
+serializer = SmartMessage::Serializer::Json.new
 
 # Configure in message class
 class UserMessage < SmartMessage::Base
@@ -35,7 +35,7 @@ class UserMessage < SmartMessage::Base
   property :preferences
   
   config do
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 end
 
@@ -569,7 +569,5 @@ end
 
 ## Next Steps
 
-- [Custom Serializers](custom-serializers.md) - Build your own serializer
 - [Transports](transports.md) - How serializers work with transports
-- [Message Headers](headers.md) - Understanding message metadata
-- [Examples](examples.md) - Real-world serialization patterns
+- [Examples](../getting-started/examples.md) - Real-world serialization patterns

data/docs/{transports.md → reference/transports.md}

@@ -137,6 +137,13 @@ Production-ready Redis pub/sub transport for distributed messaging.
 - Configurable connection parameters
 - Background message subscription threads
 
+> **💡 Redis Transport Options:** SmartMessage provides three Redis-based transports:
+> - **Redis (Basic)** - Simple pub/sub for basic scenarios
+> - **Redis Enhanced** - Pattern-based routing with backwards compatibility
+> - **Redis Queue** - Persistent queues with load balancing
+>
+> See the [Redis Transport Comparison](../transports/redis-transport-comparison.md) for detailed differences and usage guidance.
+
 **Usage:**
 
 ```ruby
@@ -166,12 +173,12 @@ class OrderMessage < SmartMessage::Base
       url: 'redis://localhost:6379',
       db: 1
     )
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
   
-  def self.process(message_header, message_payload)
-    order_data = JSON.parse(message_payload)
-    order = new(order_data)
+  def self.process(decoded_message)
+    # decoded_message is already a message instance
+    order = decoded_message
     puts "Processing order #{order.order_id} for $#{order.amount}"
     # Your business logic here
   end
@@ -243,7 +250,7 @@ redis_transport = SmartMessage::Transport.create(:redis,
 [OrderMessage, PaymentMessage, ShippingMessage].each do |msg_class|
   msg_class.config do
     transport redis_transport
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
   
   # Subscribe to each message type (creates separate Redis subscriptions)
@@ -285,7 +292,7 @@ class ProductionMessage < SmartMessage::Base
       reconnect_attempts: 10,
       reconnect_delay: 5
     )
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
     logger Logger.new(STDOUT)
   end
 end
@@ -302,7 +309,7 @@ class TestMessage < SmartMessage::Base
       db: 15,  # Use separate database for tests
       auto_subscribe: true
     )
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 end
 
@@ -313,6 +320,121 @@ def setup
 end
 ```
 
+### Redis Enhanced Transport
+
+Advanced Redis transport with intelligent pattern-based routing and RabbitMQ-style capabilities.
+
+**Features:**
+- Pattern-based subscriptions with wildcard support (`*` matching)
+- Dual channel publishing for backwards compatibility
+- Fluent API for building complex subscription patterns
+- Enhanced routing with 3-part channel names: `message_type.from.to`
+- Convenience methods for common routing patterns
+- Service-oriented messaging patterns
+
+![Redis Enhanced Architecture](../assets/images/redis-enhanced-architecture.svg)
+
+**Usage:**
+
+```ruby
+# Create enhanced transport
+transport = SmartMessage::Transport::RedisEnhancedTransport.new(
+  url: 'redis://localhost:6379',
+  db: 0,
+  auto_subscribe: true
+)
+
+# Configure message with enhanced transport
+class OrderMessage < SmartMessage::Base
+  from 'e-commerce-api'
+  to 'order-processor'
+  
+  transport transport
+  serializer SmartMessage::Serializer::Json.new
+  
+  property :order_id, required: true
+  property :amount, required: true
+end
+
+# Pattern-based subscriptions
+transport.subscribe_pattern("ordermessage.*.*")         # All order messages
+transport.subscribe_pattern("*.payment_gateway.*")      # All from payment gateway
+transport.subscribe_to_recipient('order-processor')     # Convenience method
+transport.subscribe_to_alerts                           # Emergency patterns
+
+# Fluent API subscriptions
+transport.where.from('web-app').to('user-service').subscribe
+transport.where.type('OrderMessage').from('api').subscribe
+transport.where.from('monitoring').subscribe
+
+# Publishing (goes to BOTH channels for compatibility)
+order = OrderMessage.new(order_id: 'ORD-123', amount: 99.99)
+order.publish
+# Publishes to:
+# - "OrderMessage" (original format)
+# - "ordermessage.e_commerce_api.order_processor" (enhanced format)
+```
+
+**Pattern Wildcards:**
+- `*` - Matches exactly one segment
+- `ordermessage.*.*` - All order messages regardless of from/to
+- `*.payment_service.*` - All messages from payment service
+- `*.*.order_processor` - All messages to order processor
+
+**Convenience Methods:**
+```ruby
+transport.subscribe_to_recipient('service-name')  # *.*.service-name
+transport.subscribe_from_sender('api-gateway')    # *.api-gateway.*
+transport.subscribe_to_type('OrderMessage')       # ordermessage.*.*
+transport.subscribe_to_alerts                     # Multiple alert patterns
+transport.subscribe_to_broadcasts                 # *.*.broadcast
+```
+
+**Fluent API:**
+```ruby
+# Single conditions
+transport.where.from('api').subscribe              # *.api.*
+transport.where.to('database').subscribe           # *.*.database
+transport.where.type('LogMessage').subscribe       # logmessage.*.*
+
+# Combined conditions  
+transport.where.from('web').to('api').subscribe    # *.web.api
+transport.where.type('Order').from('shop').subscribe # order.shop.*
+```
+
+**Options:**
+- `url` (String): Redis connection URL (default: 'redis://localhost:6379')
+- `db` (Integer): Redis database number (default: 0)
+- `auto_subscribe` (Boolean): Automatically start subscriber threads (default: true)
+- `reconnect_attempts` (Integer): Connection retry attempts (default: 5)
+- `reconnect_delay` (Integer): Delay between retries in seconds (default: 1)
+
+**Backwards Compatibility:**
+
+The Enhanced Transport maintains full backwards compatibility with the basic Redis transport by publishing to both channel formats:
+
+```ruby
+# Enhanced transport publishes to BOTH:
+# 1. "OrderMessage" (basic format - for backwards compatibility)
+# 2. "ordermessage.from_service.to_service" (enhanced format - for pattern matching)
+
+# Basic Redis transport can still subscribe to "OrderMessage" 
+# Enhanced transport can use patterns on the enhanced format
+```
+
+**Use Cases:**
+- Microservices architectures requiring sophisticated routing
+- Migration from basic Redis transport (maintains compatibility)
+- Development environments needing flexible message routing
+- Applications requiring RabbitMQ-style patterns without RabbitMQ setup
+- Service-to-service communication with intelligent filtering
+
+**Performance:**
+- Minimal overhead over basic Redis transport
+- Client-side pattern matching (slightly higher CPU usage)
+- Dual publishing increases Redis network traffic by ~2x
+- Excellent performance for most production scenarios
+
 ## Transport Interface
 
 All transports must implement the `SmartMessage::Transport::Base` interface:
@@ -411,7 +533,7 @@ class OrderMessage < SmartMessage::Base
   # All instances use this transport by default
   config do
     transport SmartMessage::Transport.create(:memory, auto_process: true)
-    serializer SmartMessage::Serializer::JSON.new
+    serializer SmartMessage::Serializer::Json.new
   end
 end
 ```
@@ -689,7 +811,7 @@ end
 
 ## Next Steps
 
-- [Custom Transports](custom-transports.md) - Build your own transport
+- [Redis Transport Comparison](../transports/redis-transport-comparison.md) - Detailed comparison of Redis, Enhanced, and Queue transports
 - [Serializers](serializers.md) - Understanding message serialization
-- [Dispatcher](dispatcher.md) - Message routing and processing
-- [Examples](examples.md) - Real-world transport usage patterns
+- [Dispatcher](../core-concepts/dispatcher.md) - Message routing and processing  
+- [Examples](../getting-started/examples.md) - Real-world transport usage patterns