smart_message 0.0.1

data/examples/README.md

@@ -0,0 +1,335 @@
+# SmartMessage Examples
+
+This directory contains example applications that demonstrate different messaging patterns and topologies using the SmartMessage Ruby gem. Each example is a complete, runnable program that showcases real-world usage scenarios.
+
+## Quick Start
+
+To run any example:
+
+```bash
+cd examples
+ruby 01_point_to_point_orders.rb
+ruby 02_publish_subscribe_events.rb  
+ruby 03_many_to_many_chat.rb
+```
+
+## Examples Overview
+
+### 1. Point-to-Point Messaging (1-to-1)
+**File:** `01_point_to_point_orders.rb`
+
+**Scenario:** E-commerce order processing system with bidirectional communication between OrderService and PaymentService.
+
+**Key Features:**
+- Request-response messaging pattern
+- Error handling and payment validation
+- JSON serialization of complex business objects
+- Service-to-service communication
+
+**Messages Used:**
+- `OrderMessage` - Represents customer orders
+- `PaymentResponseMessage` - Payment processing results
+
+**Services:**
+- `OrderService` - Creates and publishes orders
+- `PaymentService` - Processes payments and sends responses
+
+**What You'll Learn:**
+- How to implement point-to-point messaging
+- Bidirectional communication patterns
+- Message properties and validation
+- Service decoupling with SmartMessage
+
+---
+
+### 2. Publish-Subscribe Messaging (1-to-Many)
+**File:** `02_publish_subscribe_events.rb`
+
+**Scenario:** User management system that broadcasts events to multiple interested services (email, SMS, audit logging).
+
+**Key Features:**
+- Event-driven architecture
+- Multiple subscribers to single event stream
+- Different services handling events differently
+- Audit logging and compliance
+
+**Messages Used:**
+- `UserEventMessage` - User lifecycle events (registration, login, password change)
+
+**Services:**
+- `UserManager` - Event publisher for user activities
+- `EmailService` - Sends email notifications
+- `SMSService` - Sends SMS alerts for security events
+- `AuditService` - Logs all events for compliance
+
+**What You'll Learn:**
+- Event-driven system design
+- Publish-subscribe patterns
+- Service autonomy and specialization
+- Audit and monitoring capabilities
+
+---
+
+### 3. Many-to-Many Messaging (Service Mesh)
+**File:** `03_many_to_many_chat.rb`
+
+**Scenario:** Distributed chat system where multiple agents (humans and bots) communicate in multiple rooms with dynamic routing.
+
+**Key Features:**
+- Complex multi-agent communication
+- Dynamic subscription management
+- Multiple message types and routing
+- Service discovery and capabilities
+
+**Messages Used:**
+- `ChatMessage` - User and bot chat messages
+- `BotCommandMessage` - Commands directed to bots
+- `SystemNotificationMessage` - System events and notifications
+
+**Services:**
+- `HumanChatAgent` - Represents human users
+- `BotAgent` - Automated agents with capabilities
+- `RoomManager` - Manages chat rooms and membership
+
+**What You'll Learn:**
+- Many-to-many communication patterns
+- Dynamic message routing
+- Service capabilities and discovery
+- Complex subscription management
+
+## Message Patterns Demonstrated
+
+### Request-Response Pattern
+```ruby
+# Publisher sends request
+order = OrderMessage.new(customer_id: "123", amount: 99.99)
+order.publish
+
+# Subscriber processes and responds
+PaymentResponseMessage.new(order_id: order.order_id, status: "success").publish
+```
+
+### Event Broadcasting Pattern
+```ruby
+# Single event publisher
+UserEventMessage.new(event_type: "user_registered", user_id: "123").publish
+
+# Multiple subscribers process the same event
+EmailService.handle_user_event     # Sends welcome email
+SMSService.handle_user_event       # No action for registration
+AuditService.handle_user_event     # Logs the event
+```
+
+### Dynamic Subscription Pattern
+```ruby
+# Agents can join/leave message streams dynamically
+alice.join_room('general')         # Start receiving messages
+alice.leave_room('general')        # Stop receiving messages
+```
+
+## Transport Configurations
+
+All examples use `StdoutTransport` with loopback enabled for demonstration purposes:
+
+```ruby
+config do
+  transport SmartMessage::Transport::StdoutTransport.new(loopback: true)
+  serializer SmartMessage::Serializer::JSON.new
+end
+```
+
+**For Production Use:**
+- Replace `StdoutTransport` with production transports (Redis, RabbitMQ, Kafka)
+- Configure appropriate serializers for your data needs
+- Add proper error handling and logging
+- Implement monitoring and metrics
+
+## Advanced Features Shown
+
+### Message Properties and Headers
+```ruby
+property :order_id
+property :amount
+property :currency, default: 'USD'
+property :items
+```
+
+### Custom Message Processing
+```ruby
+def self.process(message_header, message_payload)
+  # Custom business logic here
+  data = JSON.parse(message_payload)
+  handle_business_logic(data)
+end
+```
+
+### Service-Specific Subscriptions
+```ruby
+# Subscribe with custom processor method
+OrderMessage.subscribe('PaymentService.process_order')
+```
+
+### Message Metadata and Context
+```ruby
+metadata: { 
+  source: 'web_registration',
+  ip_address: request.ip,
+  user_agent: request.user_agent
+}
+```
+
+## Common Patterns
+
+### Service Registration Pattern
+```ruby
+class MyService
+  def initialize
+    MessageType.subscribe('MyService.handle_message')
+  end
+  
+  def self.handle_message(header, payload)
+    service = new
+    service.process_message(header, payload)
+  end
+end
+```
+
+### Message Filtering Pattern
+```ruby
+def handle_message(header, payload)
+  data = JSON.parse(payload)
+  
+  # Only process messages for rooms we're in
+  return unless @active_rooms.include?(data['room_id'])
+  
+  # Process the message
+  process_filtered_message(data)
+end
+```
+
+### Response Pattern
+```ruby
+def process_request(request_data)
+  # Process the request
+  result = perform_business_logic(request_data)
+  
+  # Send response
+  ResponseMessage.new(
+    request_id: request_data['id'],
+    status: result.success? ? 'success' : 'error',
+    data: result.data
+  ).publish
+end
+```
+
+## Testing the Examples
+
+Each example includes:
+- Comprehensive output showing message flow
+- Error scenarios and handling
+- Multiple service interactions
+- Clear demonstration of the messaging pattern
+
+### Running Examples
+
+1. **Install dependencies:**
+   ```bash
+   bundle install
+   ```
+
+2. **Run individual examples:**
+   ```bash
+   ruby examples/01_point_to_point_orders.rb
+   ruby examples/02_publish_subscribe_events.rb
+   ruby examples/03_many_to_many_chat.rb
+   ```
+
+3. **Expected output:**
+   Each example produces verbose output showing:
+   - Service startup messages
+   - Message publishing and receiving
+   - Business logic execution
+   - System notifications and responses
+
+## Extending the Examples
+
+### Adding New Services
+```ruby
+class MyNewService
+  def initialize
+    MyMessageType.subscribe('MyNewService.handle_message')
+  end
+  
+  def self.handle_message(header, payload)
+    # Process messages here
+  end
+end
+```
+
+### Creating New Message Types
+```ruby
+class MyCustomMessage < SmartMessage::Base
+  property :custom_field
+  property :another_field
+  
+  config do
+    transport SmartMessage::Transport::StdoutTransport.new(loopback: true)
+    serializer SmartMessage::Serializer::JSON.new
+  end
+end
+```
+
+### Implementing New Transports
+```ruby
+class MyCustomTransport < SmartMessage::Transport::Base
+  def publish(message_header, message_payload)
+    # Custom transport logic
+  end
+end
+```
+
+## Production Considerations
+
+When adapting these examples for production:
+
+1. **Transport Selection:**
+   - Use production message brokers (Redis, RabbitMQ, Kafka)
+   - Configure connection pooling and failover
+   - Implement proper error handling
+
+2. **Serialization:**
+   - Choose appropriate serializers for your data
+   - Consider performance and compatibility requirements
+   - Handle schema evolution
+
+3. **Monitoring:**
+   - Add logging and metrics
+   - Implement health checks
+   - Monitor message throughput and latency
+
+4. **Security:**
+   - Implement message encryption if needed
+   - Add authentication and authorization
+   - Validate message integrity
+
+5. **Scaling:**
+   - Configure multiple service instances
+   - Implement load balancing
+   - Plan for horizontal scaling
+
+## Additional Resources
+
+- [SmartMessage Documentation](../docs/README.md)
+- [Transport Layer Guide](../docs/transports.md)
+- [Serialization Guide](../docs/serializers.md)
+- [Architecture Overview](../docs/architecture.md)
+
+## Questions and Contributions
+
+If you have questions about these examples or want to contribute additional examples:
+
+1. Check the main project documentation
+2. Look at the test files for more usage patterns
+3. Submit issues or pull requests to the main repository
+
+These examples are designed to be educational and demonstrate best practices. Feel free to use them as starting points for your own SmartMessage-based applications!

data/examples/tmux_chat/README.md

@@ -0,0 +1,283 @@
+# SmartMessage Tmux Chat Visualization
+
+This is an enhanced version of the many-to-many chat example that uses tmux to provide a clear, visual representation of the messaging interactions between different agents across multiple chat rooms.
+
+## Overview
+
+Instead of having all output mixed together in a single terminal, this tmux version separates:
+
+- **Room Monitors**: Visual displays showing activity in each chat room
+- **Human Agents**: Interactive chat clients for simulated users
+- **Bot Agents**: Automated responders with various capabilities
+
+## Layout
+
+The tmux session creates three windows:
+
+### Window 0: Chat Control Center (2x2 grid)
+```
+┌─────────────────┬─────────────────┐
+│   General Room  │    Tech Room    │
+│     Monitor     │     Monitor     │
+├─────────────────┼─────────────────┤
+│   Random Room   │  System Info &  │
+│     Monitor     │   Instructions  │
+└─────────────────┴─────────────────┘
+```
+
+### Window 1: Human Agents (3 panes)
+```
+┌─────────────────┬─────────────────┐
+│                 │      Bob        │
+│     Alice       ├─────────────────┤
+│                 │     Carol       │
+└─────────────────┴─────────────────┘
+```
+
+### Window 2: Bot Agents (2 panes)
+```
+┌─────────────────┬─────────────────┐
+│    HelpBot      │    FunBot       │
+│                 │                 │
+└─────────────────┴─────────────────┘
+```
+
+## Features
+
+### Room Monitors
+Each room monitor shows:
+- Real-time message activity for that specific room
+- User join/leave notifications
+- Command detections
+- Activity status (active/quiet/inactive)
+- Message count and participant statistics
+
+### Human Agents
+Interactive chat clients with:
+- Command support (`/join`, `/leave`, `/list`, `/help`, `/quit`)
+- Multi-room messaging
+- Auto-response to mentions
+- Real-time message display
+
+### Bot Agents
+Automated agents with capabilities like:
+- **HelpBot**: `/help`, `/stats`, `/time`
+- **FunBot**: `/joke`, `/weather`, `/echo`
+- Keyword responses (hello, help, thank you)
+- Command processing with visual feedback
+
+## Quick Start
+
+### Prerequisites
+- tmux installed (`brew install tmux` on macOS)
+- Ruby with SmartMessage gem
+- Terminal with decent size (recommended: 120x40 or larger)
+
+### Running the Demo
+
+```bash
+# Start the entire chat system
+cd examples/tmux_chat
+./start_chat_demo.sh
+```
+
+### Navigation
+
+Once in tmux:
+
+**Switch Between Windows:**
+- **Ctrl+b then 0**: Switch to Control Center (room monitors)
+- **Ctrl+b then 1**: Switch to Human Agents (Alice, Bob, Carol)
+- **Ctrl+b then 2**: Switch to Bot Agents (HelpBot, FunBot)
+
+**Move Between Panes (within a window):**
+- **Ctrl+b then o**: Cycle through all panes in current window
+- **Ctrl+b then arrow keys**: Move directly to pane in that direction (↑↓←→)
+- **Ctrl+b then ;**: Toggle between current and last pane
+
+**Other Useful Commands:**
+- **Ctrl+b then z**: Zoom current pane (toggle fullscreen)
+- **Ctrl+b then d**: Detach from session (keeps it running)
+- **Ctrl+b then ?**: Show all tmux commands
+
+### Getting Started Workflow
+
+1. **After starting the demo**, you'll be in the Human Agents window (window 1)
+2. **Look for the active pane** (has colored border) - usually Alice's pane
+3. **Start typing immediately** - you're in the chat interface, not bash
+4. **Try these first commands:**
+   ```
+   /join general
+   Hello everyone!
+   /help
+   ```
+5. **Switch to other agents** using `Ctrl+b then o` to see different perspectives
+6. **Watch room activity** by switching to Control Center: `Ctrl+b then 0`
+
+### Interacting with Agents
+
+In any human agent pane (Alice, Bob, Carol):
+```bash
+# Join rooms
+/join general
+/join tech
+/join random
+
+# Send messages (goes to all your active rooms)
+Hello everyone!
+
+# Use bot commands
+/help
+/joke
+/weather Tokyo
+/stats
+
+# Mention other users
+@alice how are you?
+
+# Leave rooms
+/leave tech
+
+# Exit
+/quit
+```
+
+### Stopping the Demo
+
+```bash
+# From outside tmux
+./stop_chat_demo.sh
+
+# Or from inside tmux
+Ctrl+b then d  # Detach
+./stop_chat_demo.sh
+```
+
+## Architecture
+
+### File-Based Transport
+
+This example uses a custom `FileTransport` that:
+- Writes messages to room-specific queue files in `/tmp/smart_message_chat/`
+- Polls files for new messages
+- Enables inter-process communication between tmux panes
+- Cleans up automatically on shutdown
+
+### Message Types
+
+Three types of messages flow through the system:
+
+1. **ChatMessage**: Regular chat messages
+2. **BotCommandMessage**: Commands directed to bots
+3. **SystemNotificationMessage**: Join/leave/system events
+
+### Agent Types
+
+- **BaseAgent**: Common functionality for all agents
+- **HumanChatAgent**: Interactive user simulation
+- **BotChatAgent**: Automated response agents
+- **RoomMonitor**: Display-only room activity monitors
+
+## Advantages Over Single-Terminal Version
+
+### Visual Clarity
+- **Room Separation**: See each room's activity independently
+- **Agent Separation**: Each agent has its own display space
+- **Real-time Updates**: Monitors show live activity as it happens
+
+### Better Understanding
+- **Message Flow**: Clearly see how messages route between rooms
+- **Agent Behavior**: Watch how different agents respond to events
+- **System Dynamics**: Observe the many-to-many messaging patterns
+
+### Interactive Experience
+- **Multiple Perspectives**: Switch between different agent viewpoints
+- **Live Interaction**: Type and send messages in real-time
+- **System Monitoring**: Watch room activity while participating
+
+## Example Workflow
+
+1. **Start the demo**: `./start_chat_demo.sh`
+2. **Watch the Control Center**: See rooms come online and initial messages
+3. **Switch to Human Agents**: Navigate to Alice, Bob, or Carol
+4. **Join rooms**: Use `/join general` to participate
+5. **Send messages**: Type anything to chat in your active rooms
+6. **Try bot commands**: Use `/joke`, `/weather`, `/help`
+7. **Watch interactions**: Switch back to Control Center to see message flow
+8. **Monitor bots**: Check Bot Agents window to see bot responses
+
+## Customization
+
+### Adding New Rooms
+Edit `start_chat_demo.sh` to add more room monitors:
+```bash
+tmux new-window -t $SESSION_NAME -n "New-Room"
+tmux send-keys "ruby room_monitor.rb newroom" C-m
+```
+
+### Adding New Agents
+Create additional panes:
+```bash
+tmux split-window -t $SESSION_NAME:1 -v
+tmux send-keys "ruby human_agent.rb david David" C-m
+```
+
+### Custom Bot Capabilities
+Modify `bot_agent.rb` or create new bots:
+```bash
+ruby bot_agent.rb mybot MyBot "custom,commands,here"
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Tmux not found**:
+```bash
+# macOS
+brew install tmux
+
+# Ubuntu/Debian
+sudo apt-get install tmux
+```
+
+**Messages not appearing**:
+- Check that `/tmp/smart_message_chat/` directory exists
+- Verify agents have joined the same rooms
+- Try stopping and restarting the demo
+
+**Pane too small**:
+- Resize terminal window to at least 120x40
+- Use `Ctrl+b then z` to zoom a pane temporarily
+
+**Agents not responding**:
+- Check that agents are in the same rooms (`/list` command)
+- Verify bot capabilities match the commands being used
+
+**Agents crash with console errors**:
+- Fixed in latest version - agents now handle missing IO.console gracefully
+- If issues persist, check Ruby version and terminal compatibility
+
+### Manual Cleanup
+
+If the automatic cleanup doesn't work:
+```bash
+# Kill tmux session
+tmux kill-session -t smart_message_chat
+
+# Remove message queues
+rm -rf /tmp/smart_message_chat
+```
+
+## Educational Value
+
+This visualization helps understand:
+
+- **Many-to-many messaging patterns**
+- **Room-based routing and filtering** 
+- **Agent coordination and communication**
+- **Event-driven architecture**
+- **Real-time system monitoring**
+- **Service discovery and capabilities**
+
+Perfect for demonstrating SmartMessage's power in complex, distributed scenarios!