smart_message 0.0.1

data/docs/getting-started.md

@@ -0,0 +1,235 @@
+# Getting Started with SmartMessage
+
+This guide will help you get up and running with SmartMessage quickly.
+
+## Installation
+
+Add SmartMessage to your Gemfile:
+
+```ruby
+gem 'smart_message'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install smart_message
+```
+
+## Requirements
+
+- Ruby >= 3.0.0
+- No additional system dependencies
+
+## Your First Message
+
+Let's create a simple message class and see it in action:
+
+### 1. Define a Message Class
+
+```ruby
+require 'smart_message'
+
+class WelcomeMessage < SmartMessage::Base
+  # Define message properties
+  property :user_name
+  property :email
+  property :signup_date
+
+  # Configure the transport (where messages go)
+  config do
+    transport SmartMessage::Transport.create(:stdout, loopback: true)
+    serializer SmartMessage::Serializer::JSON.new
+  end
+
+  # Define how to process received messages
+  def self.process(message_header, message_payload)
+    # Decode the message
+    data = JSON.parse(message_payload)
+    welcome = new(data)
+    
+    # Process the welcome message
+    puts "🎉 Welcome #{welcome.user_name}!"
+    puts "📧 Email: #{welcome.email}"
+    puts "📅 Signed up: #{welcome.signup_date}"
+  end
+end
+```
+
+### 2. Subscribe to Messages
+
+Before publishing, set up a subscription to receive messages:
+
+```ruby
+# Subscribe to process incoming WelcomeMessage instances
+WelcomeMessage.subscribe
+```
+
+### 3. Create and Publish a Message
+
+```ruby
+# Create a new welcome message
+welcome = WelcomeMessage.new(
+  user_name: "Alice Johnson",
+  email: "alice@example.com", 
+  signup_date: Date.today.to_s
+)
+
+# Publish the message
+welcome.publish
+```
+
+### 4. See It in Action
+
+Run your script and you should see:
+
+```
+===================================================
+== SmartMessage Published via STDOUT Transport
+== Header: #<SmartMessage::Header:0x... @uuid="...", @message_class="WelcomeMessage", ...>
+== Payload: {"user_name":"Alice Johnson","email":"alice@example.com","signup_date":"2025-08-17"}
+===================================================
+
+🎉 Welcome Alice Johnson!
+📧 Email: alice@example.com
+📅 Signed up: 2025-08-17
+```
+
+## Understanding What Happened
+
+1. **Message Definition**: We created a `WelcomeMessage` class with three properties
+2. **Configuration**: We configured it to use STDOUT transport with loopback enabled
+3. **Subscription**: We subscribed to process incoming messages of this type
+4. **Publishing**: We created an instance and published it
+5. **Processing**: Because loopback is enabled, the message was immediately routed back and processed
+
+## Key Concepts
+
+### Properties
+Messages use Hashie::Dash properties for type-safe attributes:
+
+```ruby
+class OrderMessage < SmartMessage::Base
+  property :order_id, required: true
+  property :amount, transform_with: ->(v) { BigDecimal(v.to_s) }
+  property :items, default: []
+  property :created_at, default: -> { Time.now }
+end
+```
+
+### Headers
+Every message automatically gets a header with metadata:
+
+```ruby
+message = WelcomeMessage.new(user_name: "Bob")
+puts message._sm_header.uuid          # Unique identifier
+puts message._sm_header.message_class # "WelcomeMessage"
+puts message._sm_header.published_at  # Timestamp when published
+puts message._sm_header.publisher_pid # Process ID of publisher
+```
+
+### Transports
+Transports handle where messages go. Built-in options include:
+
+```ruby
+# STDOUT - for development/debugging
+transport SmartMessage::Transport.create(:stdout, loopback: true)
+
+# Memory - for testing
+transport SmartMessage::Transport.create(:memory, auto_process: true)
+```
+
+### Serializers
+Serializers handle message encoding/decoding:
+
+```ruby
+# JSON serialization (built-in)
+serializer SmartMessage::Serializer::JSON.new
+```
+
+## Next Steps
+
+Now that you have the basics working, explore:
+
+- [Architecture Overview](architecture.md) - Understand how SmartMessage works
+- [Examples](examples.md) - See more practical use cases
+- [Transports](transports.md) - Learn about different transport options
+- [Custom Transports](custom-transports.md) - Build your own transport
+
+## Common Patterns
+
+### Simple Notification System
+
+```ruby
+class NotificationMessage < SmartMessage::Base
+  property :recipient
+  property :subject
+  property :body
+  property :priority, default: 'normal'
+
+  config do
+    transport SmartMessage::Transport.create(:memory, auto_process: true)
+    serializer SmartMessage::Serializer::JSON.new
+  end
+
+  def self.process(message_header, message_payload)
+    data = JSON.parse(message_payload)
+    notification = new(data)
+    
+    # Send email, SMS, push notification, etc.
+    send_notification(notification)
+  end
+
+  private
+
+  def self.send_notification(notification)
+    puts "Sending #{notification.priority} notification to #{notification.recipient}"
+    puts "Subject: #{notification.subject}"
+  end
+end
+
+# Subscribe and send
+NotificationMessage.subscribe
+
+NotificationMessage.new(
+  recipient: "user@example.com",
+  subject: "Welcome!",
+  body: "Thanks for signing up!",
+  priority: "high"
+).publish
+```
+
+### Event Logging
+
+```ruby
+class EventMessage < SmartMessage::Base
+  property :event_type
+  property :user_id
+  property :data
+  property :timestamp, default: -> { Time.now.iso8601 }
+
+  config do
+    transport SmartMessage::Transport.create(:stdout, output: 'events.log')
+    serializer SmartMessage::Serializer::JSON.new
+  end
+end
+
+# Log events
+EventMessage.new(
+  event_type: 'user_login',
+  user_id: 123,
+  data: { ip: '192.168.1.1', user_agent: 'Chrome' }
+).publish
+```
+
+## Need Help?
+
+- Check the [Troubleshooting Guide](troubleshooting.md)
+- Review the [API Reference](api-reference.md)
+- Look at more [Examples](examples.md)

data/docs/ideas_to_think_about.md

@@ -0,0 +1,329 @@
+# Ideas to Think About
+
+This document analyzes potential enhancements to SmartMessage based on a comparison between the current implementation and an idealized vision of intelligent messaging.
+
+## Current State vs. Vision
+
+A description was provided that envisioned SmartMessage as an advanced, intelligent messaging system. While the current implementation is solid and well-designed, there are significant opportunities for enhancement to move toward that vision.
+
+### What Currently Matches:
+
+✅ **Message abstraction from transport mechanisms** - The gem does abstract messages from their delivery systems
+
+✅ **Pluggable architecture** - Supports different transports and serializers
+
+✅ **Multiple messaging patterns** - Can handle 1-to-1, 1-to-many scenarios through subscription patterns
+
+✅ **Error handling** - Basic error isolation in the dispatcher
+
+### Major Enhancement Opportunities:
+
+The following features were described in the vision but are not currently implemented:
+
+#### 1. Autonomous Self-Publishing
+**Vision:** Messages autonomously publish themselves based on predefined triggers
+**Current:** Messages require explicit `.publish` calls
+**Potential Implementation:**
+```ruby
+class SmartMessage::Base
+  # Add trigger-based publishing
+  def self.publish_on(event_type, condition = nil, &block)
+    @auto_publish_triggers ||= []
+    @auto_publish_triggers << {
+      event: event_type,
+      condition: condition || block,
+      target: self
+    }
+  end
+  
+  # Monitor system events and auto-publish when triggered
+  def self.check_triggers(event_data)
+    @auto_publish_triggers&.each do |trigger|
+      if trigger[:condition].call(event_data)
+        new(event_data).publish
+      end
+    end
+  end
+end
+
+# Usage example:
+class OrderStatusUpdate < SmartMessage::Base
+  property :order_id
+  property :status
+  
+  # Automatically publish when order status changes
+  publish_on(:order_status_changed) do |event|
+    event[:status] == 'shipped'
+  end
+end
+```
+
+#### 2. Dynamic Content Transformation
+**Vision:** On-the-fly format conversion for different subscribers
+**Current:** One serializer per message class
+**Potential Implementation:**
+```ruby
+class SmartMessage::Dispatcher
+  # Route with format transformation
+  def route_with_transformation(message_header, message_payload)
+    @subscribers[message_header.message_class].each do |processor|
+      # Get subscriber's preferred format
+      preferred_format = get_subscriber_format(processor)
+      
+      # Transform if needed
+      if preferred_format != message_header.format
+        transformed_payload = transform_format(
+          message_payload,
+          from: message_header.format,
+          to: preferred_format
+        )
+        route_to_processor(processor, message_header, transformed_payload)
+      else
+        route_to_processor(processor, message_header, message_payload)
+      end
+    end
+  end
+  
+  private
+  
+  def transform_format(payload, from:, to:)
+    # Convert between formats (JSON -> XML, XML -> MessagePack, etc.)
+    case [from, to]
+    when ['json', 'xml']
+      json_to_xml(payload)
+    when ['xml', 'json']
+      xml_to_json(payload)
+    # Add more transformations as needed
+    end
+  end
+end
+```
+
+#### 3. Contextual Awareness and Routing Intelligence
+**Vision:** Intelligent routing based on context and subscriber relevance
+**Current:** Simple class-name-based dispatch
+**Potential Implementation:**
+```ruby
+class SmartMessage::IntelligentDispatcher < SmartMessage::Dispatcher
+  def initialize
+    super
+    @subscriber_profiles = {}
+    @routing_intelligence = RoutingIntelligence.new
+  end
+  
+  def subscribe_with_profile(message_class, processor, profile: {})
+    super(message_class, processor)
+    @subscriber_profiles[processor] = profile
+  end
+  
+  def route(message_header, message_payload)
+    # Analyze message content
+    message_context = analyze_message_context(message_payload)
+    
+    # Find relevant subscribers based on context
+    relevant_subscribers = find_relevant_subscribers(
+      message_header.message_class,
+      message_context
+    )
+    
+    # Route only to relevant subscribers
+    relevant_subscribers.each do |processor|
+      route_to_processor(processor, message_header, message_payload)
+    end
+  end
+  
+  private
+  
+  def find_relevant_subscribers(message_class, context)
+    candidates = @subscribers[message_class] || []
+    
+    candidates.select do |processor|
+      profile = @subscriber_profiles[processor]
+      @routing_intelligence.is_relevant?(context, profile)
+    end
+  end
+end
+
+# Usage:
+dispatcher.subscribe_with_profile(
+  "OrderMessage",
+  "FulfillmentService.process",
+  profile: {
+    interests: ['physical_goods'],
+    regions: ['US', 'CA'],
+    order_value_min: 100
+  }
+)
+```
+
+#### 4. Feedback Mechanisms
+**Vision:** Collect feedback from subscribers for continuous improvement
+**Current:** No feedback system
+**Potential Implementation:**
+```ruby
+class SmartMessage::Base
+  def self.process_with_feedback(message_header, message_payload)
+    start_time = Time.now
+    
+    begin
+      result = process_without_feedback(message_header, message_payload)
+      
+      # Collect success feedback
+      SmartMessage::FeedbackCollector.record_success(
+        processor: "#{self}.process",
+        message_class: message_header.message_class,
+        processing_time: Time.now - start_time,
+        result_quality: evaluate_result_quality(result)
+      )
+      
+      result
+    rescue => e
+      # Collect failure feedback
+      SmartMessage::FeedbackCollector.record_failure(
+        processor: "#{self}.process",
+        message_class: message_header.message_class,
+        error: e,
+        processing_time: Time.now - start_time
+      )
+      raise
+    end
+  end
+  
+  alias_method :process_without_feedback, :process
+  alias_method :process, :process_with_feedback
+end
+
+module SmartMessage::FeedbackCollector
+  def self.record_success(processor:, message_class:, processing_time:, result_quality:)
+    # Store feedback for analysis
+    feedback_store.record({
+      type: 'success',
+      processor: processor,
+      message_class: message_class,
+      processing_time: processing_time,
+      result_quality: result_quality,
+      timestamp: Time.now
+    })
+  end
+  
+  def self.analyze_processor_performance(processor)
+    # Analyze collected feedback to provide insights
+    feedback_store.analyze(processor)
+  end
+end
+```
+
+#### 5. Security Features
+**Vision:** Built-in encryption and authentication
+**Current:** No security features
+**Potential Implementation:**
+```ruby
+class SmartMessage::SecureTransport < SmartMessage::Transport::Base
+  def initialize(options = {})
+    super
+    @encryption_key = options[:encryption_key]
+    @auth_provider = options[:auth_provider]
+  end
+  
+  def publish(message_header, message_payload)
+    # Authenticate sender
+    unless @auth_provider.authenticate(message_header.publisher_pid)
+      raise SmartMessage::Errors::AuthenticationFailed
+    end
+    
+    # Encrypt payload
+    encrypted_payload = encrypt_payload(message_payload)
+    
+    # Add security metadata to header
+    secure_header = message_header.dup
+    secure_header.encrypted = true
+    secure_header.encryption_algorithm = 'AES-256-GCM'
+    
+    super(secure_header, encrypted_payload)
+  end
+  
+  protected
+  
+  def receive(message_header, message_payload)
+    # Decrypt if needed
+    if message_header.encrypted
+      decrypted_payload = decrypt_payload(message_payload)
+      super(message_header, decrypted_payload)
+    else
+      super
+    end
+  end
+  
+  private
+  
+  def encrypt_payload(payload)
+    # Implement encryption logic
+  end
+  
+  def decrypt_payload(encrypted_payload)
+    # Implement decryption logic
+  end
+end
+```
+
+## Implementation Roadmap
+
+### Phase 1: Foundation Enhancements
+1. **Enhanced Statistics System** - More detailed metrics collection
+2. **Message Tracing** - Correlation IDs and message flow tracking
+3. **Improved Error Handling** - Retry mechanisms and dead letter queues
+4. **Configuration Management** - More sophisticated configuration options
+
+### Phase 2: Intelligence Features
+1. **Content Analysis** - Message content classification and tagging
+2. **Routing Intelligence** - Context-aware subscriber matching
+3. **Performance Optimization** - Adaptive processing based on load
+4. **Feedback Collection** - Basic subscriber feedback mechanisms
+
+### Phase 3: Advanced Features
+1. **Dynamic Transformation** - Format conversion between subscribers
+2. **Autonomous Publishing** - Event-driven message creation
+3. **Security Layer** - Encryption and authentication
+4. **Machine Learning Integration** - Predictive routing and optimization
+
+### Phase 4: Enterprise Features
+1. **Distributed Processing** - Multi-node message handling
+2. **Advanced Analytics** - Message flow analysis and optimization
+3. **Integration APIs** - Easy integration with existing systems
+4. **Management Console** - Web-based monitoring and configuration
+
+## Technical Considerations
+
+### Architecture Changes Needed
+1. **Plugin System Enhancement** - More sophisticated plugin architecture
+2. **Event System** - System-wide event broadcasting for triggers
+3. **Metadata Framework** - Rich message and subscriber metadata
+4. **Processing Pipeline** - Configurable message processing stages
+
+### Performance Implications
+1. **Intelligence Overhead** - Balance between smart features and performance
+2. **Memory Usage** - Feedback collection and context storage
+3. **Processing Complexity** - Multiple transformation and routing steps
+4. **Scalability** - Ensure enhancements don't impact horizontal scaling
+
+### Backward Compatibility
+1. **Gradual Migration** - All enhancements should be optional
+2. **API Stability** - Maintain existing API while adding new features
+3. **Configuration Migration** - Smooth upgrade path for existing installations
+4. **Testing Strategy** - Comprehensive testing for both old and new features
+
+## Current Strengths to Preserve
+
+The existing SmartMessage implementation has several strengths that should be maintained:
+
+1. **Simplicity** - Easy to understand and use
+2. **Solid Architecture** - Well-designed plugin system and separation of concerns
+3. **Thread Safety** - Proper concurrent processing
+4. **Flexibility** - Support for custom transports and serializers
+5. **Testing** - Good test coverage and patterns
+
+## Conclusion
+
+While the current SmartMessage implementation is solid and functional, there's significant potential to evolve it toward a more intelligent messaging system. The key is to implement these enhancements gradually while preserving the simplicity and reliability that make the current system valuable.
+
+The vision of autonomous, context-aware messaging is achievable, but it requires careful planning to ensure that added intelligence doesn't compromise the system's core strengths of simplicity and reliability.