smart_message 0.0.4 → 0.0.6

data/docs/properties.md

@@ -4,6 +4,7 @@ The SmartMessage property system builds on Hashie::Dash to provide a robust, dec
 
 ## Table of Contents
 - [Basic Property Definition](#basic-property-definition)
+- [Schema Versioning](#schema-versioning)
 - [Class-Level Description](#class-level-description)
 - [Property Options](#property-options)
 - [Accessing Property Information](#accessing-property-information)
@@ -20,9 +21,115 @@ class MyMessage < SmartMessage::Base
 end
 ```
 
+## Schema Versioning
+
+SmartMessage supports schema versioning to enable message evolution while maintaining compatibility:
+
+```ruby
+class OrderMessage < SmartMessage::Base
+  version 2  # Declare schema version
+  
+  property :order_id, required: true
+  property :customer_email  # Added in version 2
+end
+```
+
+### Version Management
+
+```ruby
+# Version 1 message
+class V1OrderMessage < SmartMessage::Base
+  version 1  # or omit for default version 1
+  
+  property :order_id, required: true
+  property :amount, required: true
+end
+
+# Version 2 message with additional field
+class V2OrderMessage < SmartMessage::Base
+  version 2
+  
+  property :order_id, required: true
+  property :amount, required: true
+  property :customer_email  # New in version 2
+end
+
+# Version 3 message with validation
+class V3OrderMessage < SmartMessage::Base
+  version 3
+  
+  property :order_id, 
+    required: true,
+    validate: ->(v) { v.is_a?(String) && v.length > 0 }
+    
+  property :amount, 
+    required: true,
+    validate: ->(v) { v.is_a?(Numeric) && v > 0 }
+    
+  property :customer_email,
+    validate: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
+end
+```
+
+### Version Validation
+
+The framework automatically validates version compatibility:
+
+```ruby
+message = V2OrderMessage.new(order_id: "123", amount: 99.99)
+# Header automatically gets version: 2
+
+# Version validation happens automatically
+message.validate!  # Validates message + header + version compatibility
+
+# Manual version validation
+message.validate_header_version!  # Checks header version matches class version
+
+# Check version information
+V2OrderMessage.version                    # => 2
+V2OrderMessage.expected_header_version    # => 2
+message._sm_header.version               # => 2
+```
+
+### Version Evolution Patterns
+
+```ruby
+# Pattern 1: Additive changes (safe)
+class UserMessageV1 < SmartMessage::Base
+  version 1
+  property :user_id, required: true
+  property :name, required: true
+end
+
+class UserMessageV2 < SmartMessage::Base
+  version 2
+  property :user_id, required: true
+  property :name, required: true
+  property :email  # Optional addition - backward compatible
+end
+
+# Pattern 2: Field validation evolution
+class ProductMessageV1 < SmartMessage::Base
+  version 1
+  property :product_id, required: true
+  property :price, required: true
+end
+
+class ProductMessageV2 < SmartMessage::Base
+  version 2
+  property :product_id, 
+    required: true,
+    validate: ->(v) { v.is_a?(String) && v.match?(/\APROD-\d+\z/) }
+    
+  property :price, 
+    required: true,
+    validate: ->(v) { v.is_a?(Numeric) && v > 0 }
+end
+```
+
 ## Class-Level Description
 
-In addition to property-level descriptions, you can add a description for the entire message class:
+In addition to property-level descriptions, you can add a description for the entire message class using the `description` DSL method:
 
 ```ruby
 class OrderMessage < SmartMessage::Base
@@ -35,15 +142,29 @@ end
 # Access the class description
 OrderMessage.description  # => "Handles order processing and fulfillment workflow"
 
-# Class descriptions can also be set after class definition
+# Instance access to class description
+order = OrderMessage.new(order_id: "123", amount: 9999)
+order.description  # => "Handles order processing and fulfillment workflow"
+```
+
+### Setting Descriptions
+
+Class descriptions can be set in multiple ways:
+
+```ruby
+# 1. During class definition
 class PaymentMessage < SmartMessage::Base
+  description "Processes payment transactions"
   property :payment_id
 end
 
-PaymentMessage.description "Processes payment transactions"
-PaymentMessage.description  # => "Processes payment transactions"
+# 2. After class definition
+class RefundMessage < SmartMessage::Base
+  property :refund_id
+end
+RefundMessage.description "Handles payment refunds and reversals"
 
-# Can be set within config block
+# 3. Within config block
 class NotificationMessage < SmartMessage::Base
   config do
     description "Sends notifications to users"
@@ -53,13 +174,41 @@ class NotificationMessage < SmartMessage::Base
 end
 ```
 
+### Default Descriptions
+
+Classes without explicit descriptions automatically receive a default description:
+
+```ruby
+class MyMessage < SmartMessage::Base
+  property :data
+end
+
+MyMessage.description  # => "MyMessage is a SmartMessage"
+
+# This applies to all unnamed message classes
+class SomeModule::ComplexMessage < SmartMessage::Base
+  property :info
+end
+
+SomeModule::ComplexMessage.description  
+# => "SomeModule::ComplexMessage is a SmartMessage"
+```
+
+### Use Cases
+
 Class descriptions are useful for:
 - Documenting the overall purpose of a message class
 - Providing context for code generation tools
 - Integration with documentation systems
 - API documentation generation
+- Dynamic message introspection in gateway applications
 
-Note: Class descriptions are not inherited by subclasses. Each class maintains its own description.
+### Important Notes
+
+- Class descriptions are not inherited by subclasses - each class maintains its own description
+- Setting a description to `nil` will revert to the default description
+- Descriptions are stored as strings and can include multiline content
+- Both class and instance methods are available to access descriptions
 
 ## Property Options
 
@@ -181,7 +330,64 @@ msg.tags     # => ['important'] (Array)
 msg.metadata # => {} (Hash)
 ```
 
-### 6. Property Descriptions (SmartMessage Enhancement)
+### 6. Property Validation (SmartMessage Enhancement)
+
+Add custom validation logic to ensure data integrity:
+
+```ruby
+class ValidatedMessage < SmartMessage::Base
+  # Lambda validation
+  property :age,
+           validate: ->(v) { v.is_a?(Integer) && v.between?(1, 120) },
+           validation_message: "Age must be an integer between 1 and 120"
+
+  # Regex validation for email
+  property :email,
+           validate: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i,
+           validation_message: "Must be a valid email address"
+
+  # Array inclusion validation
+  property :status,
+           validate: ['active', 'inactive', 'pending'],
+           validation_message: "Status must be active, inactive, or pending"
+
+  # Range validation
+  property :score,
+           validate: (0..100),
+           validation_message: "Score must be between 0 and 100"
+
+  # Class type validation
+  property :created_at,
+           validate: Time,
+           validation_message: "Must be a Time object"
+
+  # Symbol method validation
+  property :username,
+           validate: :valid_username?,
+           validation_message: "Username contains invalid characters"
+
+  private
+
+  def valid_username?(value)
+    value.to_s.match?(/\A[a-zA-Z0-9_]+\z/)
+  end
+end
+
+# Validation usage
+message = ValidatedMessage.new(age: 25, email: "test@example.com")
+
+# Validate entire message
+message.validate!           # Raises SmartMessage::Errors::ValidationError on failure
+message.valid?              # Returns true/false
+
+# Get validation errors
+errors = message.validation_errors
+errors.each do |error|
+  puts "#{error[:property]}: #{error[:message]}"
+end
+```
+
+### 7. Property Descriptions (SmartMessage Enhancement)
 
 Add human-readable descriptions to document your properties for dynamic LLM integration:
 

data/examples/01_point_to_point_orders.rb

@@ -13,12 +13,21 @@ puts
 
 # Define the Order Message
 class OrderMessage < SmartMessage::Base
-  property :order_id
-  property :customer_id
-  property :amount
-  property :currency, default: 'USD'
-  property :payment_method
-  property :items
+  description "Represents customer orders for processing through the payment system"
+  
+  property :order_id, 
+    description: "Unique identifier for the order (e.g., ORD-1001)"
+  property :customer_id, 
+    description: "Unique identifier for the customer placing the order"
+  property :amount, 
+    description: "Total order amount in decimal format (e.g., 99.99)"
+  property :currency, 
+    default: 'USD',
+    description: "ISO currency code for the order (defaults to USD)"
+  property :payment_method, 
+    description: "Payment method selected by customer (credit_card, debit_card, paypal, etc.)"
+  property :items, 
+    description: "Array of item names or descriptions included in the order"
 
   # Configure to use memory transport for this example
   config do
@@ -35,11 +44,18 @@ end
 
 # Define the Payment Response Message  
 class PaymentResponseMessage < SmartMessage::Base
-  property :order_id
-  property :payment_id
-  property :status  # 'success', 'failed', 'pending'
-  property :message
-  property :processed_at
+  description "Contains payment processing results sent back to the order system"
+  
+  property :order_id, 
+    description: "Reference to the original order being processed"
+  property :payment_id, 
+    description: "Unique identifier for the payment transaction (e.g., PAY-5001)"
+  property :status, 
+    description: "Payment processing status: 'success', 'failed', or 'pending'"
+  property :message, 
+    description: "Human-readable description of the payment result"
+  property :processed_at, 
+    description: "ISO8601 timestamp when the payment was processed"
 
   config do
     transport SmartMessage::Transport::StdoutTransport.new(loopback: true)

data/examples/02_publish_subscribe_events.rb

@@ -13,13 +13,22 @@ puts
 
 # Define the User Event Message
 class UserEventMessage < SmartMessage::Base
-  property :event_id
-  property :event_type  # 'user_registered', 'user_login', 'password_changed', etc.
-  property :user_id
-  property :user_email
-  property :user_name
-  property :timestamp
-  property :metadata  # Additional event-specific data
+  description "Broadcasts user activity events to multiple notification services"
+  
+  property :event_id, 
+    description: "Unique identifier for this event (e.g., EVT-1001)"
+  property :event_type, 
+    description: "Type of user event: 'user_registered', 'user_login', 'password_changed', etc."
+  property :user_id, 
+    description: "Unique identifier for the user performing the action"
+  property :user_email, 
+    description: "Email address of the user for notification purposes"
+  property :user_name, 
+    description: "Display name of the user"
+  property :timestamp, 
+    description: "ISO8601 timestamp when the event occurred"
+  property :metadata, 
+    description: "Additional event-specific data (source, location, IP, etc.)"
 
   config do
     transport SmartMessage::Transport::StdoutTransport.new(loopback: true)

data/examples/03_many_to_many_chat.rb

@@ -14,15 +14,26 @@ puts
 
 # Define the Chat Message
 class ChatMessage < SmartMessage::Base
-  property :message_id
-  property :room_id
-  property :sender_id
-  property :sender_name
-  property :content
-  property :message_type  # 'user', 'bot', 'system'
-  property :timestamp
-  property :mentions      # Array of user IDs mentioned
-  property :metadata
+  description "Represents chat messages exchanged between users in chat rooms"
+  
+  property :message_id, 
+    description: "Unique identifier for this chat message"
+  property :room_id, 
+    description: "Identifier of the chat room where message was sent"
+  property :sender_id, 
+    description: "Unique identifier of the user or bot sending the message"
+  property :sender_name, 
+    description: "Display name of the message sender"
+  property :content, 
+    description: "The actual text content of the chat message"
+  property :message_type, 
+    description: "Type of message: 'user', 'bot', or 'system'"
+  property :timestamp, 
+    description: "ISO8601 timestamp when message was sent"
+  property :mentions, 
+    description: "Array of user IDs mentioned in the message (@username)"
+  property :metadata, 
+    description: "Additional message data (reactions, edit history, etc.)"
 
   config do
     transport SmartMessage::Transport::StdoutTransport.new(loopback: true)
@@ -37,12 +48,20 @@ end
 
 # Define Bot Command Message
 class BotCommandMessage < SmartMessage::Base
-  property :command_id
-  property :room_id
-  property :user_id
-  property :command
-  property :parameters
-  property :timestamp
+  description "Represents commands sent to chat bots for processing"
+  
+  property :command_id, 
+    description: "Unique identifier for this bot command"
+  property :room_id, 
+    description: "Chat room where the command was issued"
+  property :user_id, 
+    description: "User who issued the bot command"
+  property :command, 
+    description: "The bot command name (e.g., 'weather', 'help', 'joke')"
+  property :parameters, 
+    description: "Array of parameters passed to the bot command"
+  property :timestamp, 
+    description: "ISO8601 timestamp when command was issued"
 
   config do
     transport SmartMessage::Transport::StdoutTransport.new(loopback: true)
@@ -57,12 +76,20 @@ end
 
 # Define System Notification Message
 class SystemNotificationMessage < SmartMessage::Base
-  property :notification_id
-  property :room_id
-  property :notification_type  # 'user_joined', 'user_left', 'room_created'
-  property :content
-  property :timestamp
-  property :metadata
+  description "System-generated notifications about chat room events and status changes"
+  
+  property :notification_id, 
+    description: "Unique identifier for this system notification"
+  property :room_id, 
+    description: "Chat room affected by this notification"
+  property :notification_type, 
+    description: "Type of notification: 'user_joined', 'user_left', 'room_created', etc."
+  property :content, 
+    description: "Human-readable description of the system event"
+  property :timestamp, 
+    description: "ISO8601 timestamp when the system event occurred"
+  property :metadata, 
+    description: "Additional system event data and context"
 
   config do
     transport SmartMessage::Transport::StdoutTransport.new(loopback: true)
@@ -329,7 +356,11 @@ class BotAgent
   end
 
   def process_chat_message(chat_data)
-    # Bot can respond to certain keywords or patterns
+    # Don't respond to other bots to avoid infinite loops
+    return if chat_data['message_type'] == 'bot'
+    return if chat_data['sender_id'] == @bot_id  # Don't respond to our own messages
+    
+    # Bot can respond to certain keywords or patterns from human users only
     content = chat_data['content'].downcase
     
     if content.include?('hello') || content.include?('hi')
@@ -598,6 +629,9 @@ class DistributedChatDemo
     puts "• Dynamic subscription and unsubscription"
     puts "• Event-driven responses and interactions"
     puts "• Service discovery and capability advertisement"
+    
+    puts "\n🛑 Shutting down demo..."
+    sleep(1) # Give any pending messages time to process
   end
 end
 

data/examples/04_redis_smart_home_iot.rb

@@ -58,14 +58,24 @@ SHARED_TRANSPORT = create_transport
 
 # Sensor Data Message - Published by IoT devices
 class SensorDataMessage < SmartMessage::Base
-  property :device_id
-  property :device_type      # 'thermostat', 'security_camera', 'door_lock', 'smoke_detector'
-  property :location         # 'living_room', 'kitchen', 'bedroom', 'garage'
-  property :sensor_type      # 'temperature', 'humidity', 'motion', 'status'
-  property :value
-  property :unit             # 'celsius', 'percent', 'boolean', 'lux'
-  property :timestamp
-  property :battery_level    # For battery-powered devices
+  description "Real-time sensor data from smart home IoT devices"
+  
+  property :device_id, 
+    description: "Unique identifier for the IoT device (e.g., THERM-001)"
+  property :device_type, 
+    description: "Type of device: 'thermostat', 'security_camera', 'door_lock', 'smoke_detector'"
+  property :location, 
+    description: "Physical location of device: 'living_room', 'kitchen', 'bedroom', 'garage'"
+  property :sensor_type, 
+    description: "Type of sensor reading: 'temperature', 'humidity', 'motion', 'status'"
+  property :value, 
+    description: "Numeric or boolean sensor reading value"
+  property :unit, 
+    description: "Unit of measurement: 'celsius', 'percent', 'boolean', 'lux'"
+  property :timestamp, 
+    description: "ISO8601 timestamp when sensor reading was taken"
+  property :battery_level, 
+    description: "Battery percentage for battery-powered devices (0-100)"
 
   config do
     transport SHARED_TRANSPORT
@@ -88,11 +98,18 @@ end
 
 # Device Command Message - Sent to control IoT devices
 class DeviceCommandMessage < SmartMessage::Base
-  property :device_id
-  property :command          # 'set_temperature', 'lock_door', 'start_recording', 'test_alarm'
-  property :parameters       # Command-specific parameters
-  property :requested_by     # Who/what requested this command
-  property :timestamp
+  description "Commands sent to control and configure smart home IoT devices"
+  
+  property :device_id, 
+    description: "Target device identifier to receive the command"
+  property :command, 
+    description: "Command to execute: 'set_temperature', 'lock_door', 'start_recording', 'test_alarm'"
+  property :parameters, 
+    description: "Hash of command-specific parameters and values"
+  property :requested_by, 
+    description: "Identifier of user, system, or automation that requested this command"
+  property :timestamp, 
+    description: "ISO8601 timestamp when command was issued"
 
   config do
     transport SHARED_TRANSPORT
@@ -107,14 +124,24 @@ end
 
 # Alert Message - For critical notifications
 class AlertMessage < SmartMessage::Base
-  property :alert_id
-  property :severity         # 'low', 'medium', 'high', 'critical'
-  property :alert_type       # 'security_breach', 'fire_detected', 'device_offline', 'battery_low'
-  property :device_id
-  property :location
-  property :message
-  property :timestamp
-  property :requires_action  # Boolean indicating if immediate action needed
+  description "Critical alerts and notifications from smart home monitoring systems"
+  
+  property :alert_id, 
+    description: "Unique identifier for this alert event"
+  property :severity, 
+    description: "Alert severity level: 'low', 'medium', 'high', 'critical'"
+  property :alert_type, 
+    description: "Type of alert: 'security_breach', 'fire_detected', 'device_offline', 'battery_low'"
+  property :device_id, 
+    description: "Device that triggered the alert (if applicable)"
+  property :location, 
+    description: "Physical location where alert was triggered"
+  property :message, 
+    description: "Human-readable description of the alert condition"
+  property :timestamp, 
+    description: "ISO8601 timestamp when alert was generated"
+  property :requires_action, 
+    description: "Boolean indicating if immediate human action is required"
 
   config do
     transport SHARED_TRANSPORT

data/examples/05_proc_handlers.rb

@@ -14,11 +14,18 @@ puts
 
 # Define a simple notification message
 class NotificationMessage < SmartMessage::Base
-  property :type         # 'info', 'warning', 'error'
-  property :title
-  property :message
-  property :user_id
-  property :timestamp
+  description "System notifications processed by different types of handlers"
+  
+  property :type, 
+    description: "Notification type: 'info', 'warning', 'error'"
+  property :title, 
+    description: "Short title or subject of the notification"
+  property :message, 
+    description: "Detailed notification message content"
+  property :user_id, 
+    description: "Target user ID for the notification (optional)"
+  property :timestamp, 
+    description: "ISO8601 timestamp when notification was created"
 
   config do
     transport SmartMessage::Transport::StdoutTransport.new(loopback: true)

data/examples/06_custom_logger_example.rb

@@ -285,11 +285,18 @@ end
 
 # Sample message class with comprehensive logging
 class OrderProcessingMessage < SmartMessage::Base
-  property :order_id
-  property :customer_id
-  property :amount
-  property :status
-  property :items
+  description "Order processing messages with comprehensive multi-logger configuration"
+  
+  property :order_id, 
+    description: "Unique identifier for the customer order"
+  property :customer_id, 
+    description: "Identifier of the customer placing the order"
+  property :amount, 
+    description: "Total monetary amount of the order"
+  property :status, 
+    description: "Current processing status of the order"
+  property :items, 
+    description: "Array of items included in the order"
   
   config do
     transport SmartMessage::Transport::StdoutTransport.new(loopback: true)
@@ -350,10 +357,16 @@ end
 
 # Notification message with different logger configuration
 class NotificationMessage < SmartMessage::Base
-  property :recipient
-  property :subject
-  property :body
-  property :priority
+  description "User notifications with file-based logging configuration"
+  
+  property :recipient, 
+    description: "Target recipient for the notification"
+  property :subject, 
+    description: "Subject line or title of the notification"
+  property :body, 
+    description: "Main content body of the notification"
+  property :priority, 
+    description: "Priority level of the notification (low, normal, high, urgent)"
   
   config do
     transport SmartMessage::Transport::StdoutTransport.new(loopback: true)
@@ -384,8 +397,12 @@ end
 # Example: Message class using standard Ruby logger
 # This demonstrates how to use Ruby's standard Logger in production code
 class StandardLoggerMessage < SmartMessage::Base
-  property :content
-  property :level
+  description "Demonstrates integration with standard Ruby Logger for production logging"
+  
+  property :content, 
+    description: "Main content of the message to be logged"
+  property :level, 
+    description: "Logging level for the message (debug, info, warn, error)"
   
   config do
     transport SmartMessage::Transport::StdoutTransport.new(loopback: true)
@@ -417,8 +434,12 @@ end
 
 # Example: Message using the built-in Default Logger
 class DefaultLoggerMessage < SmartMessage::Base
-  property :message
-  property :level
+  description "Demonstrates SmartMessage's built-in default logger with auto-detection"
+  
+  property :message, 
+    description: "The message content to be logged using default logger"
+  property :level, 
+    description: "Log level (debug, info, warn, error, fatal)"
   
   config do
     transport SmartMessage::Transport::StdoutTransport.new(loopback: true)