smart_message 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a7c214ec62b411d8f3bbf0925d6547fa135233684ac22483e028ffc76cc6cbe
-  data.tar.gz: f80ce67e2ea59172a36a8c7b675864c93573bf1f2b94e294124bdf2bbb28ae73
+  metadata.gz: 6c388c9738746603d14a57d6c4e04fb7d6e48156c4e571cd82dffd461217e111
+  data.tar.gz: 975779de0b52686b8b08baa94070fea52578c86f5fb1a3752aa25cad98a812d7
 SHA512:
-  metadata.gz: da70af3b299ef64e94d8cefd87b3bb25b0a50dd3b835d4765a6f26231c65d0fa69b2ccf3d204d8de666aca2e241dcb37e396dcd064aaeae895881885e8c1ea21
-  data.tar.gz: fd2da658b323102bcb93e73f9b5d0ae843bd6afc7a8f031be7ebc206d89231f3304092d83de79524d7fd337f09a0bafad7b7bfc782e9f7a9820d32568c65e252
+  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/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    smart_message (0.0.3)
+    smart_message (0.0.4)
       activesupport
       concurrent-ruby
       hashie

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/README.md

@@ -18,6 +18,7 @@ Welcome to the comprehensive documentation for SmartMessage, a Ruby gem that abs
 - [Property System](properties.md)
 - [Transport Layer](transports.md)
 - [Serializers](serializers.md)
+- [Logging System](logging.md)
 - [Dispatcher & Routing](dispatcher.md)
 - [Message Headers](headers.md)
 

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