smart_message 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de5fce8e9cb793850301df5fdb9ad8a6954cf3a481cadc2deb625c373706723a
-  data.tar.gz: 0cc8067011377f0d574bc7f9bf1168ac2176fad7c7981cbd43f708e622a98fa0
+  metadata.gz: 6c388c9738746603d14a57d6c4e04fb7d6e48156c4e571cd82dffd461217e111
+  data.tar.gz: 975779de0b52686b8b08baa94070fea52578c86f5fb1a3752aa25cad98a812d7
 SHA512:
-  metadata.gz: bf7d1fc90d41bdbd3a8661f1f3e294915d29f267a68c13869926a4f829a00338f3878b03e14f26a7ccc9b248dc55b566e9988cb67aca7f6de596b94a51b5e885
-  data.tar.gz: 51c784d4183fe12862ff9250389a57233718604442e50303cdb941265971978e291fe7c3c1fec92509e6fa32bcc67b6b2fe8813b3cc1d06fa9d1f16645b181f3
+  metadata.gz: b425fa9d66a2716394a1dc695b8ba82c9acc9c82dc616fc00cf8eeab2639a7833640e71240969614f31836ee0d325ae8980fa4f4d266e6961dfd6a8971172420
+  data.tar.gz: 711381ff80115a8582551fc58f22630c9c103c24d46f04b1edc54b87d41fd181d80a0f730cc6d14a000ec3b5478330062385edb6e5344fe1e541559e82652c97

data/CHANGELOG.md

@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.5] 2025-08-18
+
+### Added
+- **Enhanced Description DSL**: Extended class-level `description` method with automatic defaults
+  - Classes without explicit descriptions now automatically get `"ClassName is a SmartMessage"` default
+  - Instance method `message.description` provides access to class description
+  - Backward compatible with existing description implementations
+  - Improves developer experience by eliminating nil description values
+- **Comprehensive Error Handling Example** (`examples/07_error_handling_scenarios.rb`)
+  - Demonstrates missing required property validation with detailed error messages
+  - Shows custom property validation failures with multiple validation types (regex, range, enum, proc)
+  - Illustrates version mismatch detection between message classes and headers
+  - **NEW**: Documents Hashie::Dash limitation where only first missing required property is reported
+  - Provides educational content about SmartMessage's robust validation framework
+  - Includes suggestions for potential improvements to multi-property validation
+- **Complete Property Documentation**: All examples now include comprehensive descriptions
+  - Message class descriptions added to all example programs (01-06 + tmux_chat)
+  - Individual property descriptions added with detailed explanations of purpose and format
+  - Enhanced readability and educational value of all demonstration code
+  - Consistent documentation patterns across all messaging scenarios
+
+### Fixed
+- **Critical: Infinite Loop Bug in Chat Examples**
+  - Fixed infinite message loops in `examples/03_many_to_many_chat.rb` and `examples/tmux_chat/bot_agent.rb`
+  - **Root Cause**: Bots responding to other bots' messages containing trigger keywords ("hello", "hi")
+  - **Solution**: Added `return if chat_data['message_type'] == 'bot'` to prevent bot-to-bot responses
+  - Examples now terminate properly without requiring manual intervention
+  - Maintains proper bot functionality for human interactions and explicit commands
+- **Example Termination**: Chat examples now shutdown cleanly without hanging indefinitely
+
+### Changed
+- **Enhanced Documentation Coverage**
+  - Updated README.md with comprehensive description DSL documentation
+  - Enhanced `docs/properties.md` with updated class description behavior and default handling
+  - Updated `docs/getting-started.md`, `docs/architecture.md`, and `docs/examples.md` with description examples
+  - All documentation now demonstrates proper message and property description usage
+- **Improved Example Educational Value**
+  - All example programs enhanced with descriptive class and property documentation
+  - Better demonstration of SmartMessage's self-documenting capabilities
+  - Examples serve as both functional demonstrations and documentation references
+
+### Documentation
+- **Hashie::Dash Limitation Discovery**: Documented important framework limitation in error handling example
+  - Only first missing required property reported during validation failures
+  - Provides clear explanation of incremental error discovery behavior
+  - Suggests potential solutions for improved multi-property validation
+- **Comprehensive Description System**: Complete documentation of message documentation capabilities
+  - Class-level description DSL with automatic defaults
+  - Property-level descriptions with usage patterns
+  - Integration with existing SmartMessage validation and introspection systems
+
 ## [0.0.2] - 2025-08-17
 
 ### Added

data/README.md

@@ -9,6 +9,9 @@ SmartMessage is a message abstraction framework that decouples business logic fr
 
 - **Transport Abstraction**: Plugin architecture supporting multiple message transports (Redis, RabbitMQ, Kafka, etc.)
 - **Serialization Flexibility**: Pluggable serialization formats (JSON, MessagePack, etc.)
+- **Schema Versioning**: Built-in version management with automatic compatibility validation
+- **Comprehensive Validation**: Property validation with custom error messages and automatic validation before publishing
+- **Message Documentation**: Built-in documentation support for message classes and properties with automatic defaults
 - **Flexible Message Handlers**: Multiple subscription patterns - default methods, custom methods, blocks, procs, and lambdas
 - **Dual-Level Configuration**: Class and instance-level plugin overrides for gateway patterns
 - **Concurrent Processing**: Thread-safe message routing using `Concurrent::CachedThreadPool`
@@ -38,10 +41,35 @@ Or install it yourself as:
 
 ```ruby
 class OrderMessage < SmartMessage::Base
-  property :order_id, description: "Unique order identifier"
-  property :customer_id, description: "Customer's unique ID"
-  property :amount, description: "Total order amount in dollars"
-  property :items, description: "Array of ordered items"
+  # Declare schema version for compatibility tracking
+  version 2
+  
+  # Add a description for the message class
+  description "Represents customer order data for processing and fulfillment"
+  
+  # Required properties with validation
+  property :order_id, 
+    required: true,
+    message: "Order ID is required",
+    validate: ->(v) { v.is_a?(String) && v.length > 0 },
+    validation_message: "Order ID must be a non-empty string",
+    description: "Unique order identifier"
+    
+  property :customer_id, 
+    required: true,
+    message: "Customer ID is required",
+    description: "Customer's unique ID"
+    
+  property :amount, 
+    required: true,
+    message: "Amount is required",
+    validate: ->(v) { v.is_a?(Numeric) && v > 0 },
+    validation_message: "Amount must be a positive number",
+    description: "Total order amount in dollars"
+    
+  property :items, 
+    default: [],
+    description: "Array of ordered items"
 
   # Configure transport and serializer at class level
   config do
@@ -74,7 +102,7 @@ end
 ### 2. Publish Messages
 
 ```ruby
-# Create and publish a message
+# Create and publish a message (automatically validated before publishing)
 order = OrderMessage.new(
   order_id: "ORD-123",
   customer_id: "CUST-456", 
@@ -82,7 +110,16 @@ order = OrderMessage.new(
   items: ["Widget A", "Widget B"]
 )
 
-order.publish
+# Message is automatically validated before publishing
+order.publish  # Validates all properties, header, and version compatibility
+
+# Or validate manually
+if order.valid?
+  order.publish
+else
+  errors = order.validation_errors
+  errors.each { |err| puts "#{err[:property]}: #{err[:message]}" }
+end
 ```
 
 ### 3. Subscribe to Messages
@@ -287,13 +324,211 @@ end
 
 1. **Definition**: Create message class inheriting from `SmartMessage::Base`
 2. **Configuration**: Set transport, serializer, and logger plugins
-3. **Publishing**: Message instance is encoded and sent through transport
-4. **Subscription**: Message classes register handlers with dispatcher for processing
+3. **Validation**: Messages are automatically validated before publishing (properties, header, version compatibility)
+4. **Publishing**: Message instance is encoded and sent through transport
+5. **Subscription**: Message classes register handlers with dispatcher for processing
    - Default handlers (`self.process` method)
    - Custom method handlers (`"ClassName.method_name"`)
    - Block handlers (`subscribe do |h,p|...end`)
    - Proc/Lambda handlers (`subscribe(proc {...})`)
-5. **Processing**: Received messages are decoded and routed to registered handlers
+6. **Processing**: Received messages are decoded and routed to registered handlers
+
+## Schema Versioning and Validation
+
+SmartMessage includes comprehensive validation and versioning capabilities to ensure message integrity and schema evolution support.
+
+### Version Declaration
+
+Declare your message schema version using the `version` class method:
+
+```ruby
+class OrderMessage < SmartMessage::Base
+  version 2  # Schema version 2
+  
+  property :order_id, required: true
+  property :customer_email  # Added in version 2
+end
+```
+
+### Property Validation
+
+Properties support multiple validation types with custom error messages:
+
+```ruby
+class UserMessage < SmartMessage::Base
+  version 1
+  
+  # Required field validation (Hashie built-in)
+  property :user_id, 
+    required: true,
+    message: "User ID is required and cannot be blank"
+  
+  # Custom validation with lambda
+  property :age,
+    validate: ->(v) { v.is_a?(Integer) && v.between?(1, 120) },
+    validation_message: "Age must be an integer between 1 and 120"
+  
+  # Email validation with regex
+  property :email,
+    validate: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i,
+    validation_message: "Must be a valid email address"
+  
+  # Inclusion validation with array
+  property :status,
+    validate: ['active', 'inactive', 'pending'],
+    validation_message: "Status must be active, inactive, or pending"
+end
+```
+
+### Validation Methods
+
+All message instances include validation methods:
+
+```ruby
+user = UserMessage.new(user_id: "123", age: 25)
+
+# Validate entire message (properties + header + version)
+user.validate!           # Raises SmartMessage::Errors::ValidationError on failure
+user.valid?              # Returns true/false
+
+# Get detailed validation errors
+errors = user.validation_errors
+errors.each do |error|
+  puts "#{error[:source]}.#{error[:property]}: #{error[:message]}"
+  # Example output:
+  # message.age: Age must be an integer between 1 and 120
+  # header.version: Header version must be a positive integer
+  # version_mismatch.version: Expected version 1, got: 2
+end
+```
+
+### Automatic Validation
+
+Messages are automatically validated during publishing:
+
+```ruby
+# This will raise ValidationError if invalid
+message = UserMessage.new(user_id: "", age: 150)
+message.publish  # Automatically validates before publishing
+```
+
+### Version Compatibility
+
+The framework automatically validates version compatibility:
+
+```ruby
+class V2Message < SmartMessage::Base
+  version 2
+  property :data
+end
+
+message = V2Message.new(data: "test")
+# Header automatically gets version: 2
+
+# Simulate version mismatch (e.g., from older message)
+message._sm_header.version = 1
+message.validate!  # Raises: "V2Message expects version 2, but header has version 1"
+```
+
+### Supported Validation Types
+
+- **Proc/Lambda**: `validate: ->(v) { v.length > 5 }`
+- **Regexp**: `validate: /\A[a-z]+\z/`
+- **Class**: `validate: String` (type checking)
+- **Array**: `validate: ['red', 'green', 'blue']` (inclusion)
+- **Range**: `validate: (1..100)` (range checking)
+- **Symbol**: `validate: :custom_validator_method`
+
+## Message Documentation
+
+SmartMessage provides built-in documentation capabilities for both message classes and their properties.
+
+### Class-Level Descriptions
+
+Use the `description` DSL method to document what your message class represents:
+
+```ruby
+class OrderMessage < SmartMessage::Base
+  description "Represents customer order data for processing and fulfillment"
+  
+  property :order_id, required: true
+  property :amount, required: true
+end
+
+class UserMessage < SmartMessage::Base  
+  description "Handles user management operations including registration and updates"
+  
+  property :user_id, required: true
+  property :email, required: true
+end
+
+# Access descriptions
+puts OrderMessage.description  
+# => "Represents customer order data for processing and fulfillment"
+
+puts UserMessage.description
+# => "Handles user management operations including registration and updates"
+
+# Instance access to class description
+order = OrderMessage.new(order_id: "123", amount: 99.99)
+puts order.description
+# => "Represents customer order data for processing and fulfillment"
+```
+
+### Default Descriptions
+
+Classes without explicit descriptions automatically get a default description:
+
+```ruby
+class MyMessage < SmartMessage::Base
+  property :data
+end
+
+puts MyMessage.description  
+# => "MyMessage is a SmartMessage"
+```
+
+### Property Documentation
+
+Combine class descriptions with property descriptions for comprehensive documentation:
+
+```ruby
+class FullyDocumented < SmartMessage::Base
+  description "A fully documented message class for demonstration purposes"
+  
+  property :id, 
+    description: "Unique identifier for the record"
+  property :name, 
+    description: "Display name for the entity"
+  property :status,
+    description: "Current processing status",
+    validate: ['active', 'inactive', 'pending']
+end
+
+# Access all documentation
+puts FullyDocumented.description
+# => "A fully documented message class for demonstration purposes"
+
+puts FullyDocumented.property_description(:id)
+# => "Unique identifier for the record"
+
+puts FullyDocumented.property_descriptions
+# => {:id=>"Unique identifier for the record", :name=>"Display name for the entity", ...}
+```
+
+### Documentation in Config Blocks
+
+You can also set descriptions within configuration blocks:
+
+```ruby
+class ConfiguredMessage < SmartMessage::Base
+  config do
+    description "Set within config block"
+    transport SmartMessage::Transport.create(:stdout)
+    serializer SmartMessage::Serializer::JSON.new
+  end
+end
+```
 
 ## Advanced Usage
 

data/docs/architecture.md

@@ -65,6 +65,8 @@ The foundation class that all messages inherit from, built on `Hashie::Dash`.
 
 ```ruby
 class MyMessage < SmartMessage::Base
+  description "Handles custom message processing for my application"
+  
   property :data
   
   config do

data/docs/examples.md

@@ -10,6 +10,8 @@ This document provides practical examples of using SmartMessage in real-world sc
 require 'smart_message'
 
 class NotificationMessage < SmartMessage::Base
+  description "Sends notifications to users via multiple channels"
+  
   property :recipient
   property :subject
   property :body

data/docs/getting-started.md

@@ -37,6 +37,9 @@ Let's create a simple message class and see it in action:
 require 'smart_message'
 
 class WelcomeMessage < SmartMessage::Base
+  # Add a description for the message class
+  description "Welcomes new users after successful signup"
+  
   # Define message properties
   property :user_name
   property :email
@@ -132,6 +135,8 @@ Messages use Hashie::Dash properties for type-safe attributes:
 
 ```ruby
 class OrderMessage < SmartMessage::Base
+  description "Represents customer orders for processing and fulfillment"
+  
   property :order_id, required: true
   property :amount, transform_with: ->(v) { BigDecimal(v.to_s) }
   property :items, default: []
@@ -175,6 +180,8 @@ SmartMessage supports four types of message handlers to give you flexibility in
 
 ```ruby
 class OrderMessage < SmartMessage::Base
+  description "Handles customer order processing and fulfillment"
+  
   # Define your message properties
   property :order_id
   property :amount
@@ -230,6 +237,8 @@ Now that you have the basics working, explore:
 
 ```ruby
 class NotificationMessage < SmartMessage::Base
+  description "Sends notifications to users via email, SMS, or push"
+  
   property :recipient
   property :subject
   property :body
@@ -271,6 +280,8 @@ NotificationMessage.new(
 
 ```ruby
 class EventMessage < SmartMessage::Base
+  description "Logs application events for monitoring and analytics"
+  
   property :event_type
   property :user_id
   property :data

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: