smart_message 0.0.3 → 0.0.5

data/docs/logging.md

@@ -0,0 +1,452 @@
+# Logging in SmartMessage
+
+SmartMessage provides flexible logging capabilities through its plugin architecture. This document covers the built-in default logger as well as how to create custom loggers.
+
+## Table of Contents
+
+- [Default Logger](#default-logger)
+- [Configuration Options](#configuration-options)
+- [Output Destinations](#output-destinations)
+- [Log Levels](#log-levels)
+- [Message Lifecycle Logging](#message-lifecycle-logging)
+- [Rails Integration](#rails-integration)
+- [Custom Loggers](#custom-loggers)
+- [Examples](#examples)
+
+## Default Logger
+
+SmartMessage includes a built-in `SmartMessage::Logger::Default` class that automatically detects your environment and chooses the best logging approach:
+
+- **Rails Applications**: Uses `Rails.logger` with tagged logging
+- **Standalone Ruby**: Uses Ruby's standard `Logger` class with file output
+
+### Quick Start
+
+```ruby
+class MyMessage < SmartMessage::Base
+  property :content
+  
+  config do
+    transport SmartMessage::Transport::StdoutTransport.new
+    serializer SmartMessage::Serializer::JSON.new
+    logger SmartMessage::Logger::Default.new  # Zero configuration!
+  end
+end
+```
+
+## Configuration Options
+
+The default logger accepts several configuration options:
+
+### Basic Configuration
+
+```ruby
+# Use defaults (Rails.logger or log/smart_message.log)
+logger SmartMessage::Logger::Default.new
+
+# Custom log file path
+logger SmartMessage::Logger::Default.new(
+  log_file: '/var/log/my_app/messages.log'
+)
+
+# Custom log level
+logger SmartMessage::Logger::Default.new(
+  level: Logger::DEBUG
+)
+
+# Both custom file and level
+logger SmartMessage::Logger::Default.new(
+  log_file: 'logs/custom.log',
+  level: Logger::WARN
+)
+```
+
+## Output Destinations
+
+The default logger supports multiple output destinations:
+
+### File Logging (Default)
+
+```ruby
+# Default file location (Rails convention)
+logger SmartMessage::Logger::Default.new
+# → log/smart_message.log
+
+# Custom file path
+logger SmartMessage::Logger::Default.new(
+  log_file: '/var/log/application/messages.log'
+)
+```
+
+**Features:**
+- Automatic log rotation (10 files, 10MB each)
+- Directory creation if needed
+- Timestamped entries with clean formatting
+
+### STDOUT Logging
+
+Perfect for containerized applications (Docker, Kubernetes):
+
+```ruby
+logger SmartMessage::Logger::Default.new(
+  log_file: STDOUT,
+  level: Logger::INFO
+)
+```
+
+### STDERR Logging
+
+For error-focused logging:
+
+```ruby
+logger SmartMessage::Logger::Default.new(
+  log_file: STDERR,
+  level: Logger::WARN
+)
+```
+
+### In-Memory Logging (Testing)
+
+```ruby
+require 'stringio'
+
+logger SmartMessage::Logger::Default.new(
+  log_file: StringIO.new,
+  level: Logger::DEBUG
+)
+```
+
+## Log Levels
+
+The default logger supports all standard Ruby log levels:
+
+| Level | Numeric Value | Description |
+|-------|--------------|-------------|
+| `Logger::DEBUG` | 0 | Detailed debugging information |
+| `Logger::INFO` | 1 | General information messages |
+| `Logger::WARN` | 2 | Warning messages |
+| `Logger::ERROR` | 3 | Error messages |
+| `Logger::FATAL` | 4 | Fatal error messages |
+
+### Environment-Based Defaults
+
+The default logger automatically sets appropriate log levels based on your environment:
+
+- **Rails Production**: `Logger::INFO`
+- **Rails Test**: `Logger::ERROR`
+- **Rails Development**: `Logger::DEBUG`
+- **Non-Rails**: `Logger::INFO`
+
+## Message Lifecycle Logging
+
+The default logger automatically logs key events in the message lifecycle:
+
+### Message Creation
+
+```ruby
+# Logged at DEBUG level
+message = MyMessage.new(content: "Hello")
+# → [DEBUG] [SmartMessage] Created: MyMessage - {content: "Hello"}
+```
+
+### Message Publishing
+
+```ruby
+# Logged at INFO level
+message.publish
+# → [INFO] [SmartMessage] Published: MyMessage via StdoutTransport
+```
+
+### Message Reception
+
+```ruby
+# Logged at INFO level when message is received
+# → [INFO] [SmartMessage] Received: MyMessage (45 bytes)
+```
+
+### Message Processing
+
+```ruby
+# Logged at INFO level after processing
+# → [INFO] [SmartMessage] Processed: MyMessage - Success
+```
+
+### Subscription Management
+
+```ruby
+# Logged at INFO level
+MyMessage.subscribe
+# → [INFO] [SmartMessage] Subscribed: MyMessage
+
+MyMessage.unsubscribe
+# → [INFO] [SmartMessage] Unsubscribed: MyMessage
+```
+
+### Error Logging
+
+```ruby
+# Logged at ERROR level with full stack trace (DEBUG level)
+# → [ERROR] [SmartMessage] Error in message processing: RuntimeError - Something went wrong
+# → [DEBUG] [SmartMessage] Backtrace: ...
+```
+
+## Rails Integration
+
+When running in a Rails application, the default logger provides enhanced integration:
+
+### Automatic Detection
+
+```ruby
+# Automatically uses Rails.logger when available
+logger SmartMessage::Logger::Default.new
+```
+
+### Tagged Logging
+
+```ruby
+# In Rails, all SmartMessage logs are tagged
+Rails.logger.tagged('SmartMessage') do
+  # All SmartMessage logging happens here
+end
+```
+
+### Rails Log File Location
+
+```ruby
+# Uses Rails.root/log/smart_message.log when Rails is detected
+logger SmartMessage::Logger::Default.new
+# → Rails.root.join('log', 'smart_message.log')
+```
+
+### Rails Environment Handling
+
+The logger respects Rails environment settings:
+
+- **Production**: INFO level, structured logging
+- **Development**: DEBUG level, verbose output  
+- **Test**: ERROR level, minimal output
+
+## Custom Loggers
+
+You can create custom loggers by inheriting from `SmartMessage::Logger::Base`:
+
+### Basic Custom Logger
+
+```ruby
+class SmartMessage::Logger::MyCustomLogger < SmartMessage::Logger::Base
+  def initialize(external_logger)
+    @logger = external_logger
+  end
+  
+  def log_message_created(message)
+    @logger.debug "Created message: #{message.class.name}"
+  end
+  
+  def log_message_published(message, transport)
+    @logger.info "Published #{message.class.name} via #{transport.class.name}"
+  end
+  
+  # Implement other lifecycle methods as needed...
+end
+```
+
+### Wrapper for Third-Party Loggers
+
+```ruby
+# Semantic Logger example
+class SmartMessage::Logger::SemanticLogger < SmartMessage::Logger::Base
+  def initialize(semantic_logger = nil)
+    @logger = semantic_logger || SemanticLogger['SmartMessage']
+  end
+  
+  def log_message_created(message)
+    @logger.debug "Message created", message_class: message.class.name
+  end
+  
+  def log_error(context, error)
+    @logger.error "Error in #{context}", exception: error
+  end
+end
+```
+
+### Multi-Logger (Broadcast)
+
+```ruby
+class SmartMessage::Logger::MultiLogger < SmartMessage::Logger::Base
+  def initialize(*loggers)
+    @loggers = loggers
+  end
+  
+  def log_message_created(message)
+    @loggers.each { |logger| logger.log_message_created(message) }
+  end
+  
+  # Other methods follow same pattern...
+end
+
+# Usage
+logger SmartMessage::Logger::MultiLogger.new(
+  SmartMessage::Logger::Default.new(log_file: 'app.log'),
+  SmartMessage::Logger::Default.new(log_file: STDOUT),
+  SmartMessage::Logger::MyCustomLogger.new(external_system)
+)
+```
+
+## Examples
+
+### Development Setup
+
+```ruby
+class OrderMessage < SmartMessage::Base
+  property :order_id, String, required: true
+  property :customer_id, String, required: true
+  property :amount, Float, required: true
+  
+  config do
+    transport SmartMessage::Transport::StdoutTransport.new(loopback: true)
+    serializer SmartMessage::Serializer::JSON.new
+    
+    # Verbose logging for development
+    logger SmartMessage::Logger::Default.new(
+      log_file: STDOUT,
+      level: Logger::DEBUG
+    )
+  end
+  
+  def self.process(message_header, message_payload)
+    data = JSON.parse(message_payload)
+    
+    # Logger is available in process method
+    logger.info "Processing order #{data['order_id']}"
+    
+    # Business logic here
+    result = process_order(data)
+    
+    logger.info "Order #{data['order_id']} completed: #{result}"
+    result
+  end
+end
+```
+
+### Production Setup
+
+```ruby
+class NotificationMessage < SmartMessage::Base
+  property :recipient, String, required: true
+  property :subject, String, required: true
+  property :body, String, required: true
+  
+  config do
+    transport SmartMessage::Transport::RedisTransport.new
+    serializer SmartMessage::Serializer::JSON.new
+    
+    # Production logging with file rotation
+    logger SmartMessage::Logger::Default.new(
+      log_file: '/var/log/app/notifications.log',
+      level: Logger::INFO
+    )
+  end
+end
+```
+
+### Docker/Kubernetes Setup
+
+```ruby
+class EventMessage < SmartMessage::Base
+  property :event_type, String, required: true
+  property :data, Hash, required: true
+  
+  config do
+    transport SmartMessage::Transport::RedisTransport.new(
+      redis_url: ENV['REDIS_URL']
+    )
+    serializer SmartMessage::Serializer::JSON.new
+    
+    # Container-friendly STDOUT logging
+    logger SmartMessage::Logger::Default.new(
+      log_file: STDOUT,
+      level: ENV['LOG_LEVEL']&.upcase&.to_sym || Logger::INFO
+    )
+  end
+end
+```
+
+### Testing Setup
+
+```ruby
+# In test_helper.rb or similar
+class TestMessage < SmartMessage::Base
+  property :test_data, Hash
+  
+  config do
+    transport SmartMessage::Transport::MemoryTransport.new
+    serializer SmartMessage::Serializer::JSON.new
+    
+    # Minimal logging for tests
+    logger SmartMessage::Logger::Default.new(
+      log_file: StringIO.new,
+      level: Logger::FATAL  # Only fatal errors in tests
+    )
+  end
+end
+```
+
+### Instance-Level Logger Override
+
+```ruby
+# Different logger for specific instances
+class PriorityMessage < SmartMessage::Base
+  property :priority, String
+  property :data, Hash
+  
+  config do
+    transport SmartMessage::Transport::RedisTransport.new
+    serializer SmartMessage::Serializer::JSON.new
+    logger SmartMessage::Logger::Default.new  # Default logger
+  end
+end
+
+# Override logger for high-priority messages
+priority_logger = SmartMessage::Logger::Default.new(
+  log_file: '/var/log/priority.log',
+  level: Logger::DEBUG
+)
+
+urgent_message = PriorityMessage.new(priority: 'urgent', data: {...})
+urgent_message.logger(priority_logger)  # Override for this instance
+urgent_message.publish
+```
+
+## Best Practices
+
+1. **Use the default logger** unless you have specific requirements
+2. **Log to STDOUT** in containerized environments
+3. **Use appropriate log levels** - avoid DEBUG in production
+4. **Tag your logs** for better searchability
+5. **Consider structured logging** for production systems
+6. **Test your logging** - ensure logs are helpful for debugging
+7. **Monitor log volume** - excessive logging can impact performance
+8. **Rotate log files** to prevent disk space issues (default logger handles this)
+
+## Troubleshooting
+
+### No logs appearing
+- Check log level settings
+- Verify file permissions
+- Ensure logger is configured
+
+### Too much logging
+- Increase log level (DEBUG → INFO → WARN → ERROR)
+- Consider filtering in production
+
+### Performance issues
+- Lower log level in production
+- Use asynchronous logging for high-volume systems
+- Consider structured logging formats
+
+### Rails integration not working
+- Ensure Rails is loaded before SmartMessage
+- Check that `Rails.logger` is available
+- Verify Rails environment is set correctly
+
+For more troubleshooting tips, see the [Troubleshooting Guide](troubleshooting.md).

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/.gitignore

@@ -0,0 +1,2 @@
+/log/
+*.log