smart_message 0.0.2 → 0.0.4

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.

data/lib/smart_message/base.rb

@@ -16,6 +16,9 @@ module SmartMessage
     @@transport   = nil
     @@serializer  = nil
     @@logger      = nil
+    
+    # Registry for proc-based message handlers
+    @@proc_handlers = {}
 
     include Hashie::Extensions::Dash::PropertyTranslation
 
@@ -184,6 +187,44 @@ module SmartMessage
       end
 
 
+      #########################################################
+      ## proc handler management
+
+      # Register a proc handler and return a unique identifier for it
+      # @param message_class [String] The message class name
+      # @param handler_proc [Proc] The proc to register
+      # @return [String] Unique identifier for this handler
+      def register_proc_handler(message_class, handler_proc)
+        handler_id = "#{message_class}.proc_#{SecureRandom.hex(8)}"
+        @@proc_handlers[handler_id] = handler_proc
+        handler_id
+      end
+
+      # Call a registered proc handler
+      # @param handler_id [String] The handler identifier
+      # @param message_header [SmartMessage::Header] The message header
+      # @param message_payload [String] The message payload
+      def call_proc_handler(handler_id, message_header, message_payload)
+        handler_proc = @@proc_handlers[handler_id]
+        return unless handler_proc
+
+        handler_proc.call(message_header, message_payload)
+      end
+
+      # Remove a proc handler from the registry
+      # @param handler_id [String] The handler identifier to remove
+      def unregister_proc_handler(handler_id)
+        @@proc_handlers.delete(handler_id)
+      end
+
+      # Check if a handler ID refers to a proc handler
+      # @param handler_id [String] The handler identifier
+      # @return [Boolean] True if this is a proc handler
+      def proc_handler?(handler_id)
+        @@proc_handlers.key?(handler_id)
+      end
+
+
       #########################################################
       ## class-level transport configuration
 
@@ -226,25 +267,74 @@ module SmartMessage
       # Add this message class to the transport's catalog of
       # subscribed messages.  If the transport is missing, raise
       # an exception.
-      def subscribe(process_method = nil)
-        message_class   = whoami
-        process_method  = message_class + '.process' if process_method.nil?
+      #
+      # @param process_method [String, Proc, nil] The processing method:
+      #   - String: Method name like "MyService.handle_message" 
+      #   - Proc: A proc/lambda that accepts (message_header, message_payload)
+      #   - nil: Uses default "MessageClass.process" method
+      # @param block [Proc] Alternative way to pass a processing block
+      # @return [String] The identifier used for this subscription
+      #
+      # @example Using default handler
+      #   MyMessage.subscribe
+      #
+      # @example Using custom method name
+      #   MyMessage.subscribe("MyService.handle_message")
+      #
+      # @example Using a block
+      #   MyMessage.subscribe do |header, payload|
+      #     data = JSON.parse(payload)
+      #     puts "Received: #{data}"
+      #   end
+      #
+      # @example Using a proc
+      #   handler = proc { |header, payload| puts "Processing..." }
+      #   MyMessage.subscribe(handler)
+      def subscribe(process_method = nil, &block)
+        message_class = whoami
+        
+        # Handle different parameter types
+        if block_given?
+          # Block was passed - use it as the handler
+          handler_proc = block
+          process_method = register_proc_handler(message_class, handler_proc)
+        elsif process_method.respond_to?(:call)
+          # Proc/lambda was passed as first parameter
+          handler_proc = process_method
+          process_method = register_proc_handler(message_class, handler_proc)
+        elsif process_method.nil?
+          # Use default handler
+          process_method = message_class + '.process'
+        end
+        # If process_method is a String, use it as-is
 
         # TODO: Add proper logging here
 
         raise Errors::TransportNotConfigured if transport_missing?
         transport.subscribe(message_class, process_method)
+        
+        process_method
       end
 
 
       # Remove this process_method for this message class from the
       # subscribers list.
+      # @param process_method [String, nil] The processing method identifier to remove
+      #   - String: Method name like "MyService.handle_message" or proc handler ID
+      #   - nil: Uses default "MessageClass.process" method
       def unsubscribe(process_method = nil)
         message_class   = whoami
         process_method  = message_class + '.process' if process_method.nil?
         # TODO: Add proper logging here
 
-        transport.unsubscribe(message_class, process_method) if transport_configured?
+        if transport_configured?
+          transport.unsubscribe(message_class, process_method)
+          
+          # If this was a proc handler, clean it up from the registry
+          if proc_handler?(process_method)
+            unregister_proc_handler(process_method)
+          end
+        end
       end
 
 

data/lib/smart_message/dispatcher.rb

@@ -118,13 +118,20 @@ module SmartMessage
       @subscribers[message_klass].each do |message_processor|
         SS.add(message_klass, message_processor, 'routed' )
         @router_pool.post do
-          parts         = message_processor.split('.')
-          target_klass  = parts[0]
-          class_method  = parts[1]
           begin
-            target_klass.constantize
-                        .method(class_method)
-                        .call(message_header, message_payload)
+            # Check if this is a proc handler or a regular method call
+            if proc_handler?(message_processor)
+              # Call the proc handler via SmartMessage::Base
+              SmartMessage::Base.call_proc_handler(message_processor, message_header, message_payload)
+            else
+              # Original method call logic
+              parts         = message_processor.split('.')
+              target_klass  = parts[0]
+              class_method  = parts[1]
+              target_klass.constantize
+                          .method(class_method)
+                          .call(message_header, message_payload)
+            end
           rescue Exception => e
             # TODO: Add proper exception logging
             # Exception details: #{e.message}
@@ -135,6 +142,15 @@ module SmartMessage
       end
     end
 
+    private
+
+    # Check if a message processor is a proc handler
+    # @param message_processor [String] The message processor identifier
+    # @return [Boolean] True if this is a proc handler
+    def proc_handler?(message_processor)
+      SmartMessage::Base.proc_handler?(message_processor)
+    end
+
 
     #######################################################
     ## Class methods