smart_message 0.0.1 → 0.0.3

data/examples/05_proc_handlers.rb

@@ -0,0 +1,181 @@
+#!/usr/bin/env ruby
+# examples/05_proc_handlers.rb
+#
+# Proc and Block Handler Example
+#
+# This example demonstrates the new proc and block handler functionality
+# in SmartMessage, showing different ways to subscribe to messages beyond
+# the traditional self.process method.
+
+require_relative '../lib/smart_message'
+
+puts "=== SmartMessage Proc and Block Handler Example ==="
+puts
+
+# Define a simple notification message
+class NotificationMessage < SmartMessage::Base
+  property :type         # 'info', 'warning', 'error'
+  property :title
+  property :message
+  property :user_id
+  property :timestamp
+
+  config do
+    transport SmartMessage::Transport::StdoutTransport.new(loopback: true)
+    serializer SmartMessage::Serializer::JSON.new
+  end
+
+  # Default handler
+  def self.process(message_header, message_payload)
+    data = JSON.parse(message_payload)
+    icon = case data['type']
+           when 'info' then 'ℹ️'
+           when 'warning' then '⚠️'
+           when 'error' then '🚨'
+           else '📢'
+           end
+    puts "#{icon} [DEFAULT] #{data['title']}: #{data['message']}"
+  end
+end
+
+puts "🚀 Setting up different types of message handlers"
+puts
+
+# 1. Default handler (traditional way)
+puts "1️⃣ Default handler subscription:"
+default_id = NotificationMessage.subscribe
+puts "   Subscribed with ID: #{default_id}"
+puts
+
+# 2. Block handler
+puts "2️⃣ Block handler subscription:"
+block_id = NotificationMessage.subscribe do |header, payload|
+  data = JSON.parse(payload)
+  if data['type'] == 'error'
+    puts "🔥 [BLOCK] Critical error logged: #{data['title']}"
+    # Could send to error tracking service here
+  end
+end
+puts "   Subscribed with ID: #{block_id}"
+puts
+
+# 3. Proc handler
+puts "3️⃣ Proc handler subscription:"
+audit_logger = proc do |header, payload|
+  data = JSON.parse(payload)
+  timestamp = header.published_at.strftime('%Y-%m-%d %H:%M:%S')
+  puts "📝 [AUDIT] #{timestamp} - User #{data['user_id']}: #{data['type'].upcase}"
+end
+
+proc_id = NotificationMessage.subscribe(audit_logger)
+puts "   Subscribed with ID: #{proc_id}"
+puts
+
+# 4. Lambda handler
+puts "4️⃣ Lambda handler subscription:"
+warning_filter = lambda do |header, payload|
+  data = JSON.parse(payload)
+  if data['type'] == 'warning'
+    puts "⚡ [LAMBDA] Warning for user #{data['user_id']}: #{data['message']}"
+  end
+end
+
+lambda_id = NotificationMessage.subscribe(warning_filter)
+puts "   Subscribed with ID: #{lambda_id}"
+puts
+
+# 5. Method handler (traditional, but shown for comparison)
+puts "5️⃣ Method handler subscription:"
+class NotificationService
+  def self.handle_notifications(header, payload)
+    data = JSON.parse(payload)
+    puts "🏢 [SERVICE] Processing #{data['type']} notification for user #{data['user_id']}"
+  end
+end
+
+method_id = NotificationMessage.subscribe("NotificationService.handle_notifications")
+puts "   Subscribed with ID: #{method_id}"
+puts
+
+puts "=" * 60
+puts "📡 Publishing test notifications (watch the different handlers respond!)"
+puts "=" * 60
+puts
+
+# Test the handlers with different notification types
+notifications = [
+  {
+    type: 'info',
+    title: 'Welcome',
+    message: 'Welcome to the system!',
+    user_id: 'user123',
+    timestamp: Time.now.iso8601
+  },
+  {
+    type: 'warning',
+    title: 'Low Disk Space',
+    message: 'Your disk space is running low',
+    user_id: 'user456',
+    timestamp: Time.now.iso8601
+  },
+  {
+    type: 'error',
+    title: 'Database Connection Failed',
+    message: 'Unable to connect to the database',
+    user_id: 'system',
+    timestamp: Time.now.iso8601
+  }
+]
+
+notifications.each_with_index do |notification_data, index|
+  puts "\n📤 Publishing notification #{index + 1}: #{notification_data[:title]}"
+
+  notification = NotificationMessage.new(**notification_data)
+  notification.publish
+
+  # Give time for all handlers to process
+  sleep(0.5)
+
+  puts "   ✅ All handlers processed the #{notification_data[:type]} notification"
+end
+
+puts "\n" + "=" * 60
+puts "🔧 Demonstrating handler management"
+puts "=" * 60
+
+# Show how to unsubscribe handlers
+puts "\n🗑️  Unsubscribing the block handler..."
+NotificationMessage.unsubscribe(block_id)
+puts "   Block handler removed"
+
+puts "\n📤 Publishing another error notification (block handler won't respond):"
+error_notification = NotificationMessage.new(
+  type: 'error',
+  title: 'Another Error',
+  message: 'This error won\'t trigger the block handler',
+  user_id: 'test_user',
+  timestamp: Time.now.iso8601
+)
+
+error_notification.publish
+sleep(0.5)
+
+puts "\n" + "=" * 60
+puts "✨ Example completed!"
+puts "=" * 60
+
+puts "\nThis example demonstrated:"
+puts "• ✅ Default self.process method (traditional)"
+puts "• ✅ Block handlers with subscribe { |h,p| ... } (NEW!)"
+puts "• ✅ Proc handlers with subscribe(proc { ... }) (NEW!)"
+puts "• ✅ Lambda handlers with subscribe(lambda { ... }) (NEW!)"
+puts "• ✅ Method handlers with subscribe('Class.method') (traditional)"
+puts "• ✅ Handler unsubscription and management"
+puts "\nEach handler type has its own use cases:"
+puts "• 🎯 Default: Simple built-in processing"
+puts "• 🔧 Blocks: Inline logic for specific subscriptions"
+puts "• 🔄 Procs: Reusable handlers across message types"
+puts "• ⚡ Lambdas: Strict argument checking and functional style"
+puts "• 🏢 Methods: Organized, testable business logic"
+
+puts "\n🎉 Choose the handler type that best fits your needs!"

data/examples/README.md

@@ -11,6 +11,8 @@ cd examples
 ruby 01_point_to_point_orders.rb
 ruby 02_publish_subscribe_events.rb  
 ruby 03_many_to_many_chat.rb
+ruby 04_redis_smart_home_iot.rb
+ruby 05_proc_handlers.rb
 ```
 
 ## Examples Overview
@@ -97,6 +99,105 @@ ruby 03_many_to_many_chat.rb
 - Service capabilities and discovery
 - Complex subscription management
 
+---
+
+### 4. Redis Transport IoT Example (Production Messaging)
+**File:** `04_redis_smart_home_iot.rb`
+
+**Scenario:** Smart home IoT dashboard with multiple device types communicating through Redis pub/sub channels, demonstrating production-ready messaging patterns.
+
+**Key Features:**
+- Real Redis pub/sub transport (falls back to memory if Redis unavailable)
+- Multiple device types with realistic sensor data
+- Automatic Redis channel routing using message class names
+- Real-time monitoring and alerting system
+- Production-ready error handling and reconnection
+
+**Messages Used:**
+- `SensorDataMessage` - IoT device sensor readings and status
+- `DeviceCommandMessage` - Commands sent to control devices
+- `AlertMessage` - Critical notifications and warnings
+- `DashboardStatusMessage` - System-wide status updates
+
+**Services:**
+- `SmartThermostat` - Temperature monitoring and control
+- `SecurityCamera` - Motion detection and recording
+- `SmartDoorLock` - Access control and status monitoring
+- `IoTDashboard` - Centralized monitoring and status aggregation
+
+**What You'll Learn:**
+- Production Redis transport configuration and usage
+- Automatic Redis channel routing (each message type → separate channel)
+- IoT device simulation and real-time data streaming
+- Event-driven alert systems
+- Scalable pub/sub architecture for distributed systems
+- Error handling and graceful fallbacks
+
+**Redis Channels Created:**
+- `SensorDataMessage` - Device sensor readings
+- `DeviceCommandMessage` - Device control commands  
+- `AlertMessage` - System alerts and notifications
+- `DashboardStatusMessage` - Dashboard status updates
+
+---
+
+### 5. Proc and Block Handler Example (Flexible Message Processing)
+**File:** `05_proc_handlers.rb`
+
+**Scenario:** Notification system demonstrating all available message handler types in SmartMessage, showcasing the flexibility of the new proc and block subscription patterns.
+
+**Key Features:**
+- Multiple handler types in a single application
+- Default method handlers alongside new proc/block handlers
+- Dynamic handler management (subscription and unsubscription)
+- Practical comparison of different handler approaches
+
+**Messages Used:**
+- `NotificationMessage` - System notifications with type, title, message, and user info
+
+**Handler Types Demonstrated:**
+- `Default Handler` - Traditional `self.process` method
+- `Block Handler` - Inline logic using `subscribe do |h,p|...end`
+- `Proc Handler` - Reusable proc objects for cross-cutting concerns
+- `Lambda Handler` - Strict parameter validation with functional style
+- `Method Handler` - Organized service class methods
+
+**What You'll Learn:**
+- How to choose the right handler type for different use cases
+- Block handlers for simple, subscription-specific logic
+- Proc handlers for reusable cross-message functionality
+- Lambda handlers for strict functional programming patterns
+- Handler lifecycle management and cleanup
+- Performance characteristics of different handler types
+
+**Handler Patterns Shown:**
+```ruby
+# Default handler
+class NotificationMessage < SmartMessage::Base
+  def self.process(header, payload)
+    # Built-in processing
+  end
+end
+
+# Block handler - inline logic
+NotificationMessage.subscribe do |header, payload|
+  # Simple, specific processing
+end
+
+# Proc handler - reusable across message types
+audit_logger = proc { |header, payload| log_audit(payload) }
+NotificationMessage.subscribe(audit_logger)
+
+# Method handler - organized service logic
+NotificationMessage.subscribe("NotificationService.handle")
+```
+
+**Benefits Demonstrated:**
+- **Flexibility**: Multiple ways to handle the same message type
+- **Reusability**: Proc handlers can be shared across message classes
+- **Maintainability**: Choose the right abstraction level for each need
+- **Performance**: Understand overhead of different handler approaches
+
 ## Message Patterns Demonstrated
 
 ### Request-Response Pattern
@@ -129,7 +230,7 @@ alice.leave_room('general')        # Stop receiving messages
 
 ## Transport Configurations
 
-All examples use `StdoutTransport` with loopback enabled for demonstration purposes:
+Most examples use `StdoutTransport` with loopback enabled for demonstration purposes:
 
 ```ruby
 config do
@@ -138,8 +239,21 @@ config do
 end
 ```
 
+**Exception:** The IoT example (`04_redis_smart_home_iot.rb`) uses real Redis transport:
+
+```ruby
+config do
+  transport SmartMessage::Transport.create(:redis,
+    url: 'redis://localhost:6379',
+    db: 1,
+    auto_subscribe: true
+  )
+  serializer SmartMessage::Serializer::JSON.new
+end
+```
+
 **For Production Use:**
-- Replace `StdoutTransport` with production transports (Redis, RabbitMQ, Kafka)
+- Use production transports like Redis (see example #4), RabbitMQ, or Kafka
 - Configure appropriate serializers for your data needs
 - Add proper error handling and logging
 - Implement monitoring and metrics
@@ -242,6 +356,7 @@ Each example includes:
    ruby examples/01_point_to_point_orders.rb
    ruby examples/02_publish_subscribe_events.rb
    ruby examples/03_many_to_many_chat.rb
+   ruby examples/04_redis_smart_home_iot.rb  # Requires Redis server
    ```
 
 3. **Expected output:**
@@ -293,7 +408,7 @@ end
 When adapting these examples for production:
 
 1. **Transport Selection:**
-   - Use production message brokers (Redis, RabbitMQ, Kafka)
+   - Use production message brokers (Redis is built-in - see example #4, RabbitMQ, Kafka)
    - Configure connection pooling and failover
    - Implement proper error handling
 

data/examples/smart_home_iot_dataflow.md

@@ -0,0 +1,257 @@
+# Smart Home IoT Data Flow - Redis Pub/Sub Transport
+
+This document describes the data flow architecture for the Smart Home IoT example using SmartMessage's Redis transport. The system demonstrates how multiple IoT devices communicate through Redis pub/sub channels with targeted message routing.
+
+## System Architecture Overview
+
+The smart home system consists of three types of IoT devices and a central dashboard, all communicating through Redis pub/sub channels. Each message type uses its own Redis channel for efficient routing and scaling.
+
+```mermaid
+graph TB
+    %% IoT Devices
+    THERM["🌡️ Smart Thermostat<br/>THERM-001<br/>Living Room"]
+    CAM["📹 Security Camera<br/>CAM-001<br/>Front Door"]
+    LOCK["🚪 Smart Door Lock<br/>LOCK-001<br/>Main Entrance"]
+    DASH["📊 IoT Dashboard<br/>System Monitor"]
+
+    %% Redis Channels
+    subgraph REDIS ["Redis Pub/Sub Channels"]
+        SENSOR["SensorDataMessage<br/>Temperature, Motion, Status<br/>Battery Levels"]
+        COMMAND["DeviceCommandMessage<br/>set_temperature, start_recording<br/>lock/unlock, get_status"]
+        ALERT["AlertMessage<br/>Motion Detected, Battery Low<br/>High Temperature"]
+        STATUS["DashboardStatusMessage<br/>System Status, Device Counts<br/>Alert Summaries"]
+    end
+
+    %% Device Publishing
+    THERM -.->|"Temperature Data"| SENSOR
+    CAM -.->|"Motion Data"| SENSOR
+    LOCK -.->|"Lock Status"| SENSOR
+    CAM -.->|"Motion Alerts"| ALERT
+    THERM -.->|"High Temp Alerts"| ALERT
+    LOCK -.->|"Battery Low Alerts"| ALERT
+    DASH -.->|"System Status"| STATUS
+    DASH -.->|"Device Commands"| COMMAND
+
+    %% Device Subscribing
+    COMMAND -->|"set_temperature"| THERM
+    COMMAND -->|"start/stop recording"| CAM
+    COMMAND -->|"lock/unlock"| LOCK
+    SENSOR -->|"All sensor data"| DASH
+    COMMAND -->|"Command logging"| DASH
+    ALERT -->|"All alerts"| DASH
+    STATUS -->|"Status updates"| DASH
+
+    %% Styling
+    classDef deviceStyle fill:#ff6b6b,stroke:#c0392b,stroke-width:2px,color:#fff
+    classDef cameraStyle fill:#4ecdc4,stroke:#16a085,stroke-width:2px,color:#fff
+    classDef lockStyle fill:#ffe66d,stroke:#f39c12,stroke-width:2px,color:#333
+    classDef dashStyle fill:#a8e6cf,stroke:#27ae60,stroke-width:2px,color:#333
+    classDef redisStyle fill:#dc143c,stroke:#a00,stroke-width:2px,color:#fff
+
+    class THERM deviceStyle
+    class CAM cameraStyle
+    class LOCK lockStyle
+    class DASH dashStyle
+    class SENSOR,COMMAND,ALERT,STATUS redisStyle
+```
+
+## Message Flow Details
+
+### 1. Sensor Data Flow
+All IoT devices continuously publish sensor readings to the `SensorDataMessage` Redis channel:
+
+- **🌡️ Thermostat**: Temperature readings, battery level
+- **📹 Camera**: Motion detection status, battery level  
+- **🚪 Door Lock**: Lock/unlock status, battery level
+
+**Example SensorDataMessage:**
+```json
+{
+  "device_id": "THERM-001",
+  "device_type": "thermostat", 
+  "location": "living_room",
+  "sensor_type": "temperature",
+  "value": 22.5,
+  "unit": "celsius",
+  "timestamp": "2025-08-18T10:30:00Z",
+  "battery_level": 85.2
+}
+```
+
+### 2. Device Command Flow
+The dashboard and external systems send commands to specific devices via the `DeviceCommandMessage` channel:
+
+```mermaid
+sequenceDiagram
+    participant App as Mobile App
+    participant Redis as Redis Channel
+    participant Therm as Thermostat
+    participant Cam as Camera
+    participant Lock as Door Lock
+
+    App->>Redis: DeviceCommandMessage<br/>device_id THERM-001 set_temperature
+    Redis->>Therm: ✅ Processes THERM prefix match
+    Redis->>Cam: ❌ Ignores not CAM prefix
+    Redis->>Lock: ❌ Ignores not LOCK prefix
+    
+    App->>Redis: DeviceCommandMessage<br/>device_id CAM-001 start_recording
+    Redis->>Therm: ❌ Ignores not THERM prefix
+    Redis->>Cam: ✅ Processes CAM prefix match
+    Redis->>Lock: ❌ Ignores not LOCK prefix
+```
+
+**Device Command Filtering Rules:**
+- **THERM-*** devices: Accept `set_temperature`, `get_status`
+- **CAM-*** devices: Accept `start_recording`, `stop_recording`, `get_status`
+- **LOCK-*** devices: Accept `lock`, `unlock`, `get_status`
+
+### 3. Alert System Flow
+Devices publish critical notifications to the `AlertMessage` channel when conditions are detected:
+
+```mermaid
+flowchart LR
+    subgraph Triggers
+        T1[High Temperature > 28°C]
+        T2[Motion Detected]
+        T3[Battery < 20%]
+        T4[Device Offline > 30s]
+    end
+    
+    subgraph Devices
+        THERM2[🌡️ Thermostat]
+        CAM2[📹 Camera]
+        LOCK2[🚪 Door Lock]
+    end
+    
+    subgraph AlertChannel [AlertMessage Channel]
+        A1[Motion Alert]
+        A2[High Temp Alert]
+        A3[Battery Low Alert]
+        A4[Device Offline Alert]
+    end
+    
+    T1 --> THERM2 --> A2
+    T2 --> CAM2 --> A1
+    T3 --> LOCK2 --> A3
+    T4 --> A4
+    
+    AlertChannel --> DASH2[📊 Dashboard]
+```
+
+### 4. Dashboard Status Flow
+The dashboard aggregates all system data and publishes periodic status updates:
+
+```mermaid
+graph LR
+    subgraph DataCollection [Data Collection]
+        D1[Device Last Seen Times]
+        D2[Alert Counts]
+        D3[Battery Levels]
+        D4[System Health]
+    end
+    
+    subgraph Processing [Status Processing]
+        P1[Count Active Devices<br/>last_seen < 30s]
+        P2[Count Recent Alerts<br/>last 5 minutes]
+        P3[Calculate Averages]
+    end
+    
+    subgraph Output [Status Output]
+        O1[DashboardStatusMessage<br/>Every 10 seconds]
+    end
+    
+    DataCollection --> Processing --> Output
+```
+
+## Channel-Based Architecture Benefits
+
+### 1. **Efficient Message Routing**
+Each message type uses its own Redis channel, preventing unnecessary message processing:
+
+| Channel | Publishers | Subscribers | Purpose |
+|---------|------------|-------------|---------|
+| `SensorDataMessage` | All Devices | Dashboard | Real-time sensor readings |
+| `DeviceCommandMessage` | Dashboard, Apps | All Devices | Device control commands |
+| `AlertMessage` | All Devices | Dashboard | Critical notifications |
+| `DashboardStatusMessage` | Dashboard | Dashboard, Apps | System status updates |
+
+### 2. **Device-Specific Command Filtering**
+Devices use prefix-based filtering to process only relevant commands:
+
+```ruby
+# Example: Thermostat command filtering
+def self.handle_command(message_header, message_payload)
+  command_data = JSON.parse(message_payload)
+  
+  # Only process commands for thermostats
+  return unless command_data['device_id']&.start_with?('THERM-')
+  return unless ['set_temperature', 'get_status'].include?(command_data['command'])
+  
+  # Process the command...
+end
+```
+
+### 3. **Scalable Pub/Sub Pattern**
+The architecture supports easy scaling:
+
+- ✅ **Add new device types**: Just define new device ID prefixes
+- ✅ **Add new message types**: Create new Redis channels as needed  
+- ✅ **Multiple instances**: Each device can have multiple instances
+- ✅ **Load balancing**: Redis handles distribution automatically
+
+## Running the Example
+
+To see this data flow in action:
+
+```bash
+# Ensure Redis is running
+redis-server
+
+# Run the IoT example
+cd examples
+ruby 04_redis_smart_home_iot.rb
+```
+
+**What you'll observe:**
+1. **Device initialization** and Redis connection setup
+2. **Sensor data publishing** every 3-5 seconds per device
+3. **Command routing** with device-specific responses
+4. **Alert generation** when motion is detected or conditions change
+5. **Dashboard status updates** every 10 seconds showing active device counts
+
+## Redis Channel Monitoring
+
+You can monitor the Redis channels directly:
+
+```bash
+# View active channels
+redis-cli PUBSUB CHANNELS
+
+# Monitor all channel activity
+redis-cli MONITOR
+
+# Subscribe to specific channels
+redis-cli SUBSCRIBE SensorDataMessage
+redis-cli SUBSCRIBE DeviceCommandMessage
+redis-cli SUBSCRIBE AlertMessage
+redis-cli SUBSCRIBE DashboardStatusMessage
+```
+
+## Key Design Patterns Demonstrated
+
+### 1. **Message Class as Channel Name**
+SmartMessage automatically uses the message class name as the Redis channel name, providing clean separation.
+
+### 2. **Device ID-Based Routing**
+Commands are filtered by device ID prefixes, ensuring only intended devices process commands.
+
+### 3. **Centralized Monitoring**
+The dashboard subscribes to all channels, providing comprehensive system visibility.
+
+### 4. **Event-Driven Alerts**
+Devices autonomously generate alerts based on sensor readings and conditions.
+
+### 5. **Graceful Degradation**
+System falls back to memory transport if Redis is unavailable, ensuring development continues.
+
+This architecture demonstrates production-ready IoT messaging patterns using Redis pub/sub for efficient, scalable device communication.