smart_message 0.0.16 → 0.0.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0f06621d7e381b6069aba0fad1c329b941349e95488bdf5d8d39fd66e1d0fd2
-  data.tar.gz: d1ef64216d07f3e6005db87194590984004bf68f923c09bec93aadb889909cb1
+  metadata.gz: 31da3cbbad04e7c1c5c6c4957e9cbe19fd2b5ef3b4eb13079f6daa5056cf5f93
+  data.tar.gz: f418df55d5e4e40b8ad942eec2c553ae6f6275a85a1a1fe8063addcee8ddc2f7
 SHA512:
-  metadata.gz: f06e42c967e586521659b24e132001a64e51d64541214b06c7d5fa7bf6bfc48782a13bec11ace183ae50ff93b3840a5344ea2c59f3b44f0227fe8162b5452c44
-  data.tar.gz: bd2b874f6574600002a5b1cf845ca37076aef74f53fde34b7bae183af5c8978c5dd7c7fdb4d9f442014d7fb146371655e4f3092216e285fc7b0f5fba65dd254f
+  metadata.gz: 72876daadfbf2d4bc817ceaa0e41d5564e537a4baf71b36fb4042ed217c63802bf1500ff51bdcce9b19c8765ad9be2a7d8e6fbc288e937ec30a64334fa5e3d1f
+  data.tar.gz: e663de462e0221c88ca90352ef11861b99b7ed43b43a941899e67b9dfc584c68a1af9c2b86a5f09188fd2ee528308869eb92a267920bdf8fc52e197e30c1eb91

data/CHANGELOG.md

@@ -7,6 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.17] 2025-09-11
+
+### Enhanced
+- **FileTransport Message Handling**: Simplified FileTransport publish method to only handle message objects
+  - **Architecture Clarification**: FileTransport now exclusively accepts SmartMessage objects with `_sm_header`
+  - **Message Processing**: Proper extraction of message class from `message._sm_header.message_class`
+  - **Serialization Flow**: Clean serialization pipeline using `encode_message(message)` before file operations
+  - **Code Quality**: Eliminated unnecessary backward compatibility code for raw string payloads
+- **Demo Program Simplification**: Streamlined 06 demo with minimal message properties
+  - **Property Reduction**: DemoMessage now uses only `first_name` and `last_name` properties for clarity
+  - **Format Examples**: Three clear format demonstrations (Alice Johnson in :pretty, Bob Smith & Carol Williams in :jsonl, David Brown, Emma Davis & Frank Miller in :json)
+  - **Educational Value**: Simplified output makes format differences more apparent and easier to understand
+  - **Documentation Updates**: Updated usage examples and JQ query patterns to reflect simple property structure
+
+### Fixed
+- **FileTransport Test Compatibility**: Removed invalid compatibility test for raw string publishing
+  - **Issue**: Test `test_publish_compatibility_method` was passing raw strings to FileTransport.publish
+  - **Architecture Decision**: FileTransport should only handle SmartMessage objects, not raw strings
+  - **Solution**: Removed the invalid test that conflicted with proper message object architecture
+  - **Impact**: Test suite now properly validates FileTransport's message-only publishing contract
+- **StdoutTransport Architecture**: Simplified StdoutTransport to minimal subclass of FileTransport
+  - **Inheritance**: StdoutTransport now inherits all functionality from FileTransport with minimal 6-line implementation
+  - **Option Merging**: Fixed critical bug where `file_path: $stdout` always overwrote user-provided options
+  - **Solution**: Changed from `options.merge(defaults)` to `defaults.merge(options)` for proper option precedence
+  - **Flexibility**: StdoutTransport can now write to files when `file_path` option is provided, while defaulting to STDOUT
+- **FileTransport Format Support**: Added comprehensive output formatting capabilities to FileTransport
+  - **Format Options**: Implemented `:json` (raw), `:jsonl` (JSON with newline), and `:pretty` (amazing_print formatting)
+  - **Pretty Printing**: Added amazing_print integration for `:pretty` format using serializer's `decode` method
+  - **Serializer Integration**: Pretty format uses transport's serializer to deserialize messages back to Ruby objects
+  - **Fallback Handling**: Graceful fallback to raw output when amazing_print is unavailable or deserialization fails
+- **FileTransport IO Object Support**: Enhanced FileTransport to handle IO objects properly
+  - **IO Detection**: Added `respond_to?(:write)` checks to distinguish IO objects from file paths
+  - **Directory Operations**: Skip directory creation for IO objects in `ensure_directory_exists`
+  - **File Operations**: Return IO objects directly in `open_file_handle` instead of trying to open them
+  - **Compatibility**: Maintains full backward compatibility with string file paths
+
+### Fixed
+- **StdoutTransport Option Precedence**: Fixed critical configuration bug preventing file output
+  - **Issue**: `super(options.merge(file_path: $stdout))` caused defaults to always override user options
+  - **Impact**: StdoutTransport could not write to files when `file_path` was provided
+  - **Fix**: Reversed merge order to `defaults.merge(options)` for proper option precedence
+  - **Result**: StdoutTransport now correctly respects user-provided file paths while defaulting to STDOUT
+- **FileOperations Type Safety**: Enhanced type checking for file vs IO operations
+  - **Issue**: `File.dirname` called on IO objects caused "no implicit conversion" errors
+  - **Solution**: Added `respond_to?(:write)` checks throughout FileOperations module
+  - **Methods Fixed**: `ensure_directory_exists`, `open_file_handle`, and related file operations
+  - **Robustness**: FileTransport now handles both file paths and IO objects seamlessly
+
+### Added
+- **Pretty Format Demo**: Enhanced STDOUT transport demo with comprehensive format examples
+  - **Demo Update**: `examples/memory/06_stdout_publish_only.rb` now demonstrates all three formats
+  - **Format Examples**: LogMessage (jsonl), MetricsMessage (json), and DebugMessage (pretty)
+  - **Complex Data**: DebugMessage showcases pretty formatting with nested data structures
+  - **Educational Value**: Clear documentation of format differences and use cases
+
+### Tests
+- **Complete Test Suite**: All transport tests now pass without errors
+  - **Test Results**: 313 runs, 930 assertions, 0 failures, 0 errors, 27 skips
+  - **StdoutTransport Tests**: Fixed all TypeError issues related to IO object handling
+  - **FileTransport Integration**: Verified format support and IO object compatibility
+  - **Test Cleanup**: Removed invalid test that attempted to publish raw strings to FileTransport
+  - **Architecture Validation**: Test suite now properly validates message-only publishing contract
+  - **Regression Prevention**: Test coverage ensures option merging bug cannot reoccur
+
 ## [0.0.16] 2025-09-10
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    smart_message (0.0.16)
+    smart_message (0.0.17)
       activesupport
       async
       async-redis
@@ -30,7 +30,7 @@ GEM
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
     amazing_print (1.8.1)
-    async (2.31.0)
+    async (2.32.0)
       console (~> 1.29)
       fiber-annotation
       io-event (~> 1.11)
@@ -47,10 +47,10 @@ GEM
     base64 (0.3.0)
     benchmark (0.4.1)
     bigdecimal (3.2.3)
-    breaker_machines (0.4.0)
+    breaker_machines (0.5.0)
       activesupport (>= 7.2)
       concurrent-ruby (~> 1.3)
-      state_machines (>= 0.50.0)
+      state_machines (>= 0.100.0)
       zeitwerk (~> 2.7)
     colorize (1.1.0)
     concurrent-ruby (1.3.5)

data/README.md

@@ -667,28 +667,32 @@ OrderMessage.new(
 
 ### STDOUT Transport (Publish-Only)
 
-The STDOUT transport is designed for publish-only scenarios - perfect for debugging, logging, or integration with external systems.
+The STDOUT transport is designed for publish-only scenarios - perfect for debugging, logging, or integration with external systems. Built as a minimal subclass of FileTransport, it inherits comprehensive formatting capabilities.
 
 ```ruby
 # Basic STDOUT output (publish-only)
 transport = SmartMessage::Transport::StdoutTransport.new
 
-# Pretty-printed format for human reading (default)
+# JSON Lines format - one message per line (default)
+transport = SmartMessage::Transport::StdoutTransport.new(format: :jsonl)
+
+# Pretty-printed format with amazing_print for human reading
 transport = SmartMessage::Transport::StdoutTransport.new(format: :pretty)
 
-# JSON format for machine processing
+# Compact JSON format without newlines
 transport = SmartMessage::Transport::StdoutTransport.new(format: :json)
 
 # Output to file instead of STDOUT
-transport = SmartMessage::Transport::StdoutTransport.new(output: "messages.log")
+transport = SmartMessage::Transport::StdoutTransport.new(file_path: "messages.log")
 ```
 
 **Key Features:**
 - **Publish-only**: No message processing or loopback
 - **Subscription attempts are ignored** with warning logs
-- **Two formats**: `:pretty` for debugging, `:json` for integration
+- **Three formats**: `:jsonl` (default), `:pretty` for debugging, `:json` for compact output
+- **Flexible Output**: Defaults to STDOUT but can write to files when `file_path` specified
 - **Perfect for**: debugging, logging, piping to external tools
-- **Use cases**: `./app | jq`, `./app | fluentd`, development monitoring
+- **Use cases**: `./app | jq '.first_name'`, `./app | fluentd`, development monitoring
 
 **For local message processing, use MemoryTransport instead:**
 ```ruby

data/docs/guides/transport-selection.md

@@ -0,0 +1,361 @@
+# Transport Selection Guide
+
+Choosing the right transport for your SmartMessage application is crucial for performance, reliability, and maintainability. This guide provides comprehensive information about each available transport and decision matrices to help you select the optimal transport configuration.
+
+## Available Transports
+
+### Memory Transport
+**In-memory message storage for development and testing**
+
+- **Type**: In-memory queue with optional auto-processing
+- **Best For**: Unit testing, development, rapid prototyping, message inspection
+- **Key Features**: 
+  - No external dependencies
+  - Thread-safe operations
+  - Message inspection capabilities
+  - Configurable memory limits
+  - Fastest performance (~0.01ms latency)
+- **Limitations**: Single-process only, no persistence, memory usage grows with volume
+- **Use Cases**: Unit tests, development debugging, in-memory message queuing
+
+### Redis Transport
+**Production-ready Redis pub/sub for distributed messaging**
+
+- **Type**: Redis pub/sub with broadcast delivery
+- **Best For**: Production messaging, microservices communication, real-time applications
+- **Key Features**:
+  - Distributed messaging support
+  - Automatic reconnection handling
+  - High throughput (80K+ messages/second)
+  - Low latency (~1ms)
+  - Thread-based subscriber model
+- **Limitations**: No message persistence, no pattern matching, all subscribers receive all messages
+- **Use Cases**: Production systems, scalable architectures, service-to-service messaging
+
+### STDOUT Transport
+**Console and file output with multiple formatting options**
+
+- **Type**: Output-only transport with formatting capabilities
+- **Best For**: Development debugging, application logging, message tracing, integration testing
+- **Key Features**:
+  - Three output formats (`:pretty`, `:jsonl`, `:json`)
+  - Console or file output
+  - Optional loopback processing
+  - Human-readable pretty printing
+  - Thread-safe file operations
+- **Limitations**: Not suitable for production messaging, single output destination
+- **Use Cases**: Development debugging, structured logging, message flow tracing
+
+### File Transport
+**Base class for file-based messaging**
+
+- **Type**: Abstract base class for file-based transports
+- **Best For**: Custom file-based transport implementations, message archiving
+- **Key Features**:
+  - Automatic directory creation
+  - Thread-safe file operations
+  - Message serialization handling
+  - Extensible architecture for custom transports
+- **Limitations**: Rarely used directly, requires custom implementation
+- **Use Cases**: Custom transport development, message persistence, audit trails
+
+### Multi-Transport Publishing
+**Simultaneous publishing to multiple transports**
+
+- **Type**: Configuration pattern for publishing to multiple destinations
+- **Best For**: High availability, migration scenarios, monitoring integration, redundancy
+- **Key Features**:
+  - Publish to multiple transports with single `publish()` call
+  - Resilient to partial failures
+  - Sequential processing with error isolation
+  - Transport introspection methods
+- **Limitations**: Sequential processing can impact performance, memory usage scales with transport count
+- **Use Cases**: Critical message redundancy, gradual migration, operational monitoring
+
+## Transport Selection Matrix
+
+### By Development Phase
+
+| Phase | Primary Transport | Secondary Transport | Use Case |
+|-------|------------------|-------------------|----------|
+| **Unit Testing** | Memory | - | Fast, isolated, inspectable |
+| **Development** | STDOUT (pretty) | Memory (loopback) | Human-readable debugging |
+| **Integration Testing** | STDOUT (jsonl) | Memory | Structured output, verification |
+| **Staging** | Redis | STDOUT (file) | Production-like with logging |
+| **Production** | Redis | Multi-transport | Scalable with redundancy |
+
+### By Use Case
+
+| Use Case | Recommended Transport | Configuration | Rationale |
+|----------|----------------------|---------------|-----------|
+| **Unit Tests** | Memory | `auto_process: true` | No dependencies, fast, inspectable |
+| **Development Debugging** | STDOUT | `format: :pretty, loopback: true` | Human-readable with local processing |
+| **Application Logging** | STDOUT | `format: :jsonl, file_path: 'app.log'` | Structured logs for analysis |
+| **Message Tracing** | STDOUT | `format: :json, file_path: '/tmp/trace.log'` | Compact format for debugging |
+| **Production Messaging** | Redis | `url: ENV['REDIS_URL']` | Distributed, reliable, scalable |
+| **Critical Messages** | Multi-transport | `[Redis, STDOUT(file), Redis(backup)]` | Redundancy and audit trail |
+| **Migration Scenarios** | Multi-transport | `[OldTransport, NewTransport]` | Gradual transition |
+| **Development→Production** | Environment-based | Switch based on `Rails.env` | Appropriate for each environment |
+
+### By Architecture Pattern
+
+#### Single Application (Monolith)
+```ruby
+# Development
+transport: SmartMessage::Transport::StdoutTransport.new(format: :pretty)
+
+# Production  
+transport: SmartMessage::Transport::RedisTransport.new(url: ENV['REDIS_URL'])
+```
+
+#### Microservices Architecture
+```ruby
+# High-availability critical messages
+transport: [
+  SmartMessage::Transport::RedisTransport.new(url: primary_redis),
+  SmartMessage::Transport::RedisTransport.new(url: backup_redis),
+  SmartMessage::Transport::StdoutTransport.new(file_path: '/var/log/audit.log')
+]
+```
+
+#### Event-Driven System
+```ruby
+# Events with monitoring
+transport: [
+  SmartMessage::Transport::RedisTransport.new(url: event_redis),
+  SmartMessage::Transport::StdoutTransport.new(
+    format: :jsonl, 
+    file_path: '/var/log/events.log'
+  )
+]
+```
+
+## Decision Tree
+
+### Step 1: Environment Classification
+```
+Are you in...?
+├── Unit Testing → Memory Transport
+├── Development → STDOUT Transport (pretty format)  
+├── Integration Testing → STDOUT Transport (jsonl format)
+└── Production → Continue to Step 2
+```
+
+### Step 2: Message Criticality (Production)
+```
+How critical are your messages?
+├── Low criticality → Redis Transport (single)
+├── Medium criticality → Redis + STDOUT file logging
+└── High criticality → Multi-transport (Redis primary + backup + audit)
+```
+
+### Step 3: Scale Requirements
+```
+Expected message volume?
+├── Low (<1K/day) → Any transport suitable
+├── Medium (1K-100K/day) → Redis Transport recommended
+└── High (>100K/day) → Redis Transport + performance tuning
+```
+
+### Step 4: Integration Requirements
+```
+Need external integration?
+├── Log aggregation → STDOUT Transport (jsonl to file)
+├── Monitoring systems → Multi-transport (Redis + STDOUT)
+├── Audit requirements → Multi-transport with file logging
+└── None → Single transport sufficient
+```
+
+## Configuration Examples
+
+### Environment-Based Configuration
+```ruby
+class ApplicationMessage < SmartMessage::Base
+  transport case Rails.env
+            when 'test'
+              SmartMessage::Transport::MemoryTransport.new(auto_process: true)
+            when 'development'
+              SmartMessage::Transport::StdoutTransport.new(
+                format: :pretty,
+                loopback: true
+              )
+            when 'staging'
+              [
+                SmartMessage::Transport::RedisTransport.new(url: ENV['REDIS_URL']),
+                SmartMessage::Transport::StdoutTransport.new(
+                  format: :jsonl,
+                  file_path: '/var/log/staging.log'
+                )
+              ]
+            when 'production'
+              [
+                SmartMessage::Transport::RedisTransport.new(url: ENV['PRIMARY_REDIS_URL']),
+                SmartMessage::Transport::RedisTransport.new(url: ENV['BACKUP_REDIS_URL']),
+                SmartMessage::Transport::StdoutTransport.new(
+                  format: :jsonl,
+                  file_path: '/var/log/production.log'
+                )
+              ]
+            end
+end
+```
+
+### Message-Type Based Selection
+```ruby
+# High-volume, low-criticality events
+class UserActivityMessage < SmartMessage::Base
+  transport SmartMessage::Transport::RedisTransport.new(url: ENV['REDIS_URL'])
+end
+
+# Critical business events
+class PaymentProcessedMessage < SmartMessage::Base
+  transport [
+    SmartMessage::Transport::RedisTransport.new(url: ENV['PRIMARY_REDIS_URL']),
+    SmartMessage::Transport::RedisTransport.new(url: ENV['BACKUP_REDIS_URL']),
+    SmartMessage::Transport::StdoutTransport.new(
+      format: :jsonl,
+      file_path: '/var/log/payments.log'
+    )
+  ]
+end
+
+# Development/debugging messages
+class DebugMessage < SmartMessage::Base
+  transport SmartMessage::Transport::StdoutTransport.new(
+    format: :pretty,
+    loopback: true
+  )
+end
+```
+
+## Performance Considerations
+
+### Latency Comparison
+| Transport | Typical Latency | Best Use |
+|-----------|----------------|----------|
+| Memory | ~0.01ms | Unit tests, development |
+| STDOUT | ~1ms | Logging, debugging |
+| Redis | ~1ms | Production messaging |
+| Multi-transport | Sum of individual transports | Critical messages |
+
+### Throughput Comparison
+| Transport | Throughput | Limiting Factor |
+|-----------|------------|----------------|
+| Memory | Highest | CPU and memory |
+| STDOUT | Medium | I/O operations |
+| Redis | High | Network and Redis performance |
+| Multi-transport | Lowest individual transport | Sequential processing |
+
+### Resource Usage
+| Transport | Memory Usage | External Dependencies | Setup Complexity |
+|-----------|--------------|----------------------|------------------|
+| Memory | Grows with volume | None | Minimal |
+| STDOUT | Minimal | None | Minimal |
+| Redis | Low | Redis server | Medium |
+| File | Minimal | None | Minimal |
+
+## Migration Strategies
+
+### Development to Production
+```ruby
+# Phase 1: Development (Memory/STDOUT)
+transport: SmartMessage::Transport::MemoryTransport.new
+
+# Phase 2: Integration Testing (STDOUT with file)
+transport: SmartMessage::Transport::StdoutTransport.new(
+  format: :jsonl,
+  file_path: '/tmp/integration.log'
+)
+
+# Phase 3: Staging (Redis + logging)
+transport: [
+  SmartMessage::Transport::RedisTransport.new(url: staging_redis),
+  SmartMessage::Transport::StdoutTransport.new(file_path: '/var/log/staging.log')
+]
+
+# Phase 4: Production (Multi-transport)
+transport: [
+  SmartMessage::Transport::RedisTransport.new(url: primary_redis),
+  SmartMessage::Transport::RedisTransport.new(url: backup_redis)
+]
+```
+
+### Transport Evolution
+```ruby
+# Start simple
+class MyMessage < SmartMessage::Base
+  transport SmartMessage::Transport::MemoryTransport.new
+end
+
+# Add logging
+class MyMessage < SmartMessage::Base
+  transport SmartMessage::Transport::StdoutTransport.new(format: :jsonl)
+end
+
+# Scale to production
+class MyMessage < SmartMessage::Base
+  transport SmartMessage::Transport::RedisTransport.new(url: ENV['REDIS_URL'])
+end
+
+# Add redundancy
+class MyMessage < SmartMessage::Base
+  transport [
+    SmartMessage::Transport::RedisTransport.new(url: ENV['PRIMARY_REDIS']),
+    SmartMessage::Transport::RedisTransport.new(url: ENV['BACKUP_REDIS'])
+  ]
+end
+```
+
+## Best Practices
+
+### General Guidelines
+1. **Start Simple**: Begin with Memory/STDOUT transports in development
+2. **Match Environment**: Use appropriate transports for each environment
+3. **Consider Criticality**: More critical messages need more redundant transports
+4. **Monitor Performance**: Track latency and throughput in production
+5. **Plan Migration**: Design transport evolution from development to production
+
+### Transport-Specific
+- **Memory**: Use in tests and development only, set reasonable message limits
+- **STDOUT**: Use `:pretty` for development, `:jsonl` for structured logging
+- **Redis**: Configure proper connection pooling and reconnection settings
+- **Multi-transport**: Limit to 2-4 transports, order by speed/criticality
+
+### Environment Configuration
+- **Development**: Readable formats, loopback enabled for testing
+- **Testing**: Fast, isolated transports with deterministic behavior
+- **Staging**: Production-like configuration with additional logging
+- **Production**: Redundant, monitored, with proper error handling
+
+## Troubleshooting
+
+### Common Issues
+
+**Slow message publishing**
+- Check multi-transport ordering (put fastest first)
+- Verify Redis connection health
+- Monitor file I/O performance
+
+**Messages not appearing**
+- Verify transport configuration matches environment
+- Check Redis connectivity and permissions
+- Ensure file paths are writable
+
+**Memory issues**
+- Set limits on Memory transport
+- Monitor multi-transport memory usage
+- Check for message accumulation in development
+
+**Test failures**
+- Use Memory transport for predictable test behavior
+- Clear messages between tests
+- Mock external transport dependencies
+
+## Related Documentation
+
+- [Multi-Transport Publishing](../transports/multi-transport.md) - Detailed multi-transport patterns
+- [Memory Transport](../transports/memory-transport.md) - Development and testing transport
+- [Redis Transport](../transports/redis-transport.md) - Production messaging transport
+- [STDOUT Transport](../transports/stdout-transport.md) - Output and logging transport
+- [File Transport](../transports/file-transport.md) - Base class for file-based transports
+- [Transport Overview](../reference/transports.md) - Technical transport reference

data/docs/reference/transports.md

@@ -33,29 +33,36 @@ message.publish  # ✅ Publishes to all three transports
 
 ### STDOUT Transport
 
-**Publish-only transport** perfect for debugging, logging, and integration with external systems.
+**Publish-only transport** perfect for debugging, logging, and integration with external systems. Built as a minimal subclass of FileTransport, inheriting comprehensive formatting and IO handling capabilities.
 
 **Features:**
 - **Publish-only**: No message processing or loopback capability
-- Outputs messages to console or file in pretty-print or JSON formats
+- **Three output formats**: `:jsonl` (default), `:pretty` (amazing_print), `:json` (compact)
+- **Flexible output**: Defaults to STDOUT but can write to files
+- **Smart IO handling**: Automatically handles both IO objects and file paths
 - Subscription attempts are ignored with warning logs
 - Perfect for piping to external tools and log aggregators
 - No external dependencies
 
+**📚 See [STDOUT Transport Documentation](../transports/stdout-transport.md) for comprehensive usage examples.**
+
 **Usage:**
 
 ```ruby
-# Basic STDOUT output (publish-only)
+# Basic STDOUT output with default JSONL format
 transport = SmartMessage::Transport::StdoutTransport.new
 
-# Pretty-printed format for human reading (default)
+# JSON Lines format - one message per line (default)
+transport = SmartMessage::Transport::StdoutTransport.new(format: :jsonl)
+
+# Pretty-printed format with amazing_print for debugging
 transport = SmartMessage::Transport::StdoutTransport.new(format: :pretty)
 
-# JSON format for machine processing
+# Compact JSON format without newlines
 transport = SmartMessage::Transport::StdoutTransport.new(format: :json)
 
-# Output to file instead of console
-transport = SmartMessage::Transport::StdoutTransport.new(output: "messages.log")
+# Output to file instead of STDOUT
+transport = SmartMessage::Transport::StdoutTransport.new(file_path: "messages.log")
 
 # Configure in message class
 class LogMessage < SmartMessage::Base
@@ -65,25 +72,42 @@ class LogMessage < SmartMessage::Base
   config do
     transport SmartMessage::Transport::StdoutTransport.new(
       format: :json,
-      output: "app.log"
+      file_path: "app.log"
     )
   end
 end
 ```
 
 **Options:**
-- `format` (Symbol): Output format - `:pretty` for debugging, `:json` for integration (default: `:pretty`)
-- `output` (String|IO): Output destination - filename string or IO object (default: `$stdout`)
+- `format` (Symbol): Output format - `:jsonl` (default), `:pretty`, `:json`
+- `file_path` (String|IO): Output destination - filename string or IO object (default: `$stdout`)
+- All FileTransport options are inherited and available
 
 **Important:** For local message processing during development, use **MemoryTransport** instead.
 
-**Example Output:**
+**Format Examples:**
+
+**JSONL Format (default):**
+```json
+{"_sm_header":{"uuid":"abc-123","message_class":"DemoMessage"},"first_name":"Alice","last_name":"Johnson"}
+{"_sm_header":{"uuid":"def-456","message_class":"DemoMessage"},"first_name":"Bob","last_name":"Smith"}
 ```
-===================================================
-== SmartMessage Published via STDOUT Transport
-== Header: #<SmartMessage::Header:0x... @uuid="abc-123", @message_class="MyMessage", ...>
-== Payload: {"user_id":123,"action":"login","timestamp":"2025-08-17T10:30:00Z"}
-===================================================
+
+**Pretty Format:**
+```ruby
+{
+    "_sm_header" => {
+                 "uuid" => "abc-123",
+        "message_class" => "DemoMessage"
+    },
+    "first_name" => "Alice",
+     "last_name" => "Johnson"
+}
+```
+
+**JSON Format:**
+```json
+{"_sm_header":{"uuid":"abc-123"},"first_name":"Alice"}{"_sm_header":{"uuid":"def-456"},"first_name":"Bob"}
 ```
 
 ### Memory Transport
@@ -517,8 +541,8 @@ Each transport may have specific options:
 ```ruby
 # STDOUT specific (publish-only)
 SmartMessage::Transport::StdoutTransport.new(
-  format: :json,
-  output: "/var/log/messages.log"
+  format: :jsonl,              # :jsonl (default), :pretty, :json
+  file_path: "/var/log/messages.log"
 )
 
 # Memory specific