smart_message 0.0.13 → 0.0.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38b75aa70a9ab79b0fd9ac311d7e5634491789e5813161630ff7e04f17d61373
-  data.tar.gz: 8196665b3a660cfaad1c30753697f020c4a54b50c25d23be6f6c3c6ad9149e38
+  metadata.gz: 31da3cbbad04e7c1c5c6c4957e9cbe19fd2b5ef3b4eb13079f6daa5056cf5f93
+  data.tar.gz: f418df55d5e4e40b8ad942eec2c553ae6f6275a85a1a1fe8063addcee8ddc2f7
 SHA512:
-  metadata.gz: 876f94f732eb022c568a200747438ab6a0938602735f89601fc7c9e48f34bf21791c75608b2d877475d9190a9629974a63448f5ceb6eeb24bf073b0cc1e4ee19
-  data.tar.gz: 310150522f4d6561c40e7322072a75778867b643b5eb6b79364b750a39689e27cbfd7c7022ae0f0c8a44ae9a850549c02e94005930d4b878ba75cb1eb1192a58
+  metadata.gz: 72876daadfbf2d4bc817ceaa0e41d5564e537a4baf71b36fb4042ed217c63802bf1500ff51bdcce9b19c8765ad9be2a7d8e6fbc288e937ec30a64334fa5e3d1f
+  data.tar.gz: e663de462e0221c88ca90352ef11861b99b7ed43b43a941899e67b9dfc584c68a1af9c2b86a5f09188fd2ee528308869eb92a267920bdf8fc52e197e30c1eb91

data/.gitignore

@@ -13,3 +13,4 @@ site
 .aigcm_msg
 /log/
 /logs/
+*.jsonl

data/CHANGELOG.md

@@ -7,6 +7,190 @@ 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
+- **FileTransport Demo Suite**: Comprehensive demonstration programs for FileTransport functionality
+  - **Basic FileTransport Demo** (`examples/file/01_basic_file_transport_demo.rb`): Complete demonstration of core FileTransport features including different output formats (JSON, YAML, raw), append vs overwrite modes, custom serialization, and file rotation examples
+  - **FIFO Transport Demo** (`examples/file/02_fifo_transport_demo.rb`): FIFO (named pipe) demonstrations covering FIFO creation, properties, and concepts with educational content about inter-process communication
+  - **File Watching Demo** (`examples/file/03_file_watching_demo.rb`): File monitoring and change detection examples with polling-based file watching
+  - **Multi-Transport File Demo** (`examples/file/04_multi_transport_file_demo.rb`): Advanced patterns including fan-out to multiple files, conditional routing, multi-transport combinations, archival strategies, and performance monitoring
+  - **Interactive Demo Runner** (`examples/file/00_run_all_file_demos.rb`): Menu-driven demo launcher with comprehensive error handling and user-friendly navigation
+
+### Fixed
+- **Demo Configuration Syntax**: Fixed incorrect `.configure` method usage throughout FileTransport demos
+  - **Issue**: Demos were using non-existent `MessageClass.configure` method causing "undefined method 'configure'" errors
+  - **Solution**: Updated all configuration calls to use `MessageClass.class_eval { transport transport_instance }` pattern consistent with working examples
+  - **Files Updated**: All FileTransport demo files now use correct transport configuration syntax
+- **Message Instantiation Arguments**: Fixed keyword argument errors in message creation
+  - **Issue**: Hash variables being passed to `MessageClass.new(hash_var)` instead of using keyword argument expansion
+  - **Solution**: Updated all message instantiation calls to use `MessageClass.new(**hash_var)` for proper keyword argument passing
+  - **Impact**: Resolves "wrong number of arguments (given 1, expected 0)" errors throughout demo suite
+- **Method Name Consistency**: Updated all demo files to use correct `publish` method instead of deprecated `send`
+  - **Issue**: Some demos were using `.send` method which is not the correct SmartMessage publishing method
+  - **Solution**: Replaced all instances of `.send` with `.publish` across FileTransport demos
+  - **Files Affected**: 02_fifo_transport_demo.rb, 04_multi_transport_file_demo.rb
+- **Missing `from` Property Declarations**: Added required `from` declarations to all message classes
+  - **Issue**: Message classes missing required `from` property causing "The property 'from' From entity ID is required" errors
+  - **Solution**: Added `from 'demo_source'` declarations to all message class definitions including dynamically created classes
+  - **Impact**: Ensures proper message routing and header initialization
+- **FIFO Blocking Issues**: Resolved program hanging when writing to FIFOs without concurrent readers
+  - **Issue**: FIFO operations block indefinitely when no reader process is available
+  - **Solution**: Simplified FIFO examples to demonstrate FIFO concepts and properties without blocking operations, replaced complex multi-process examples with educational demonstrations
+  - **Result**: Demos now complete successfully without hanging while still teaching FIFO fundamentals
+- **Variable Scope Issues**: Fixed transport variable accessibility problems in custom routing logic
+  - **Issue**: Complex custom routing classes couldn't access transport variables from outer scope
+  - **Solution**: Simplified conditional routing examples to use separate message classes for different severity levels instead of dynamic transport switching
+  - **Benefit**: Cleaner, more maintainable code that demonstrates routing concepts without scope complications
+
+### Enhanced
+- **Demo Educational Value**: Improved all FileTransport demos with comprehensive documentation and error handling
+  - **Documentation**: Added detailed comments explaining FileTransport concepts, FIFO characteristics, and usage patterns
+  - **Error Handling**: Enhanced error reporting and graceful degradation in all demo scenarios
+  - **User Experience**: Simplified complex examples to focus on core functionality while maintaining educational value
+  - **Output Clarity**: Improved console output formatting and messaging for better understanding of demo operations
+
+### Documentation
+- **FileTransport Demo README**: Comprehensive documentation for all FileTransport demonstration programs
+  - **Usage Instructions**: Step-by-step guide for running individual demos and the interactive demo runner
+  - **Concept Explanations**: Detailed explanations of FileTransport features, FIFO operations, and advanced patterns
+  - **Troubleshooting**: Common issues and solutions for FileTransport usage
+  - **Example Outputs**: Sample console outputs showing expected demo results
+
+## [0.0.15] 2025-09-10
+
+### Added
+- **Multi-Transport Publishing**: Messages can now be configured to publish to multiple transports simultaneously
+  - **Core Feature**: Configure messages with an array of transports using `transport [transport1, transport2, transport3]` syntax
+  - **Resilient Publishing**: Publishing succeeds if ANY configured transport works; only fails if ALL transports fail
+  - **Error Handling**: Individual transport failures are logged but don't prevent publishing to remaining transports
+  - **Backward Compatibility**: Single transport configuration continues to work unchanged (`transport single_transport`)
+  - **Utility Methods**: Added `transports()`, `single_transport?()`, and `multiple_transports?()` for transport introspection
+  - **Use Cases**: Supports redundancy, integration, migration, and fan-out messaging patterns
+
+### Enhanced
+- **Transport Configuration API**: Extended transport configuration methods to handle both single transports and transport arrays
+  - **Plugins Module**: Updated `transport()` method in `lib/smart_message/plugins.rb` to accept arrays while maintaining backward compatibility
+  - **Internal Storage**: Transport arrays stored internally but `transport()` getter returns first transport for existing code compatibility
+  - **Instance Overrides**: Instance-level transport configuration can override class-level multi-transport settings
+- **Publishing Pipeline**: Enhanced message publishing in `lib/smart_message/messaging.rb` for multi-transport support
+  - **Parallel Publishing**: Iterates through all configured transports and publishes to each
+  - **Comprehensive Logging**: Logs successful and failed transports with detailed error information
+  - **Error Aggregation**: Collects all transport errors and raises `PublishError` only when all transports fail
+  - **Success Tracking**: Continues processing even when individual transports fail
+
+### Added - Error Handling
+- **PublishError**: New error class `SmartMessage::Errors::PublishError` for multi-transport failure scenarios
+  - **Condition**: Only raised when ALL configured transports fail to publish
+  - **Error Detail**: Aggregates error messages from all failed transports for comprehensive debugging
+  - **Added to**: `lib/smart_message/errors.rb`
+
+### Added - Documentation
+- **Comprehensive Guide**: Created `docs/transports/multi-transport.md` with complete multi-transport documentation
+  - **Real-World Examples**: High-availability, development/production dual publishing, monitoring integration, A/B testing
+  - **Best Practices**: Performance considerations, environment-specific configuration, health monitoring
+  - **Troubleshooting**: Common issues, debugging techniques, and solutions
+- **Integration Updates**: Updated main transport documentation and index to reference multi-transport capability
+  - **Transport Layer**: Added multi-transport section to `docs/reference/transports.md`
+  - **Table of Contents**: Added multi-transport link to main documentation index
+
+### Added - Testing
+- **Comprehensive Test Suite**: Created `test/multi_transport_test.rb` with 12 test cases covering all functionality
+  - **Backward Compatibility**: Verified single transport behavior remains unchanged
+  - **Multi-Transport Scenarios**: Tests for successful publishing, partial failures, complete failures
+  - **Configuration Testing**: Class vs instance configuration, transport introspection, method chaining
+  - **Mock Transports**: Added `FailingTransport` and `CountingTransport` for controlled testing
+  - **Integration Tests**: Real transport combinations (Memory + STDOUT)
+
+### Added - Examples
+- **README Integration**: Added multi-transport example to main README.md with practical use case
+  - **Features Section**: Added multi-transport publishing bullet point to feature list
+  - **Transport Implementations**: Complete section with `CriticalOrderMessage` example showing 3 transports
+  - **Key Benefits**: Highlighted redundancy, integration, migration, and resilience benefits
+- **Example File**: Created `examples/multi_transport_example.rb` demonstrating all multi-transport functionality
+  - **Usage Patterns**: Single transport (backward compatibility), multiple transports, instance overrides
+  - **Error Scenarios**: Partial transport failure resilience and complete failure handling
+  - **Utility Demonstrations**: Transport counting, type checking, and configuration inspection
+
+## [0.0.14] 2025-09-10
+
+### Fixed
+- **Configuration Architecture**: Fixed `SmartMessage::Serializer.default` method to properly reflect transport-owned serialization architecture
+  - **Issue**: `SmartMessage::Serializer.default` was trying to access a non-existent `default_serializer` method on global configuration
+  - **Root Cause**: Serialization belongs to transports, not global configuration, but the method was attempting to check global config first
+  - **Solution**: Updated method to return framework default (`SmartMessage::Serializer::Json`) directly without depending on global configuration
+  - **Architecture Clarification**: Each transport owns and configures its own serializer (line 19 in transport/base.rb: `@serializer = options[:serializer] || default_serializer`)
+  - **Demo Fix**: Updated `examples/memory/14_global_configuration_demo.rb` to remove incorrect `config.serializer =` attempts and added architecture comments
+- **Test Method Signatures**: Completed wrapper-to-message architecture transition by fixing remaining method signature issues
+  - **dispatcher_test.rb**: Changed `processer_one` and `processer_two` from instance methods to class methods (`def self.`)
+  - **Message Format**: Updated methods to use flat message structure (`message._sm_header.message_class` and `message.to_json`) instead of old two-tier format (`message_header, encoded_message = message`)
+  - **subscribe_test.rb**: Fixed `business_logic` method to be a class method (`def self.business_logic`) to match subscription call pattern
+  - **Result**: All tests now pass (`176 runs, 578 assertions, 0 failures, 0 errors, 1 skips`) completing the architectural transition
+
 ## [0.0.13] 2025-09-10
 
 ### Changed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    smart_message (0.0.13)
+    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)
@@ -74,7 +74,7 @@ GEM
     json (2.13.2)
     logger (1.7.0)
     lumberjack (1.4.1)
-    metrics (0.14.1)
+    metrics (0.15.0)
     minitest (5.25.5)
     minitest-power_assert (0.3.1)
       minitest
@@ -85,7 +85,7 @@ GEM
     rake (13.3.0)
     redis (5.4.1)
       redis-client (>= 0.22.0)
-    redis-client (0.25.2)
+    redis-client (0.25.3)
       connection_pool
     securerandom (0.4.1)
     shoulda (4.0.0)

data/README.md

@@ -23,6 +23,7 @@ Think of SmartMessage as ActiveRecord for messaging - just as ActiveRecord frees
 ## Features
 
 - **Transport Abstraction**: Plugin architecture supporting multiple message transports (Redis, RabbitMQ, Kafka, etc.)
+- **Multi-Transport Publishing**: Send messages to multiple transports simultaneously for redundancy, integration, and migration scenarios
 - **🌟 Redis Queue Transport**: Advanced transport with RabbitMQ-style routing patterns, persistent FIFO queues, load balancing, and 10x faster performance than traditional message brokers. Built on Ruby's Async framework for fiber-based concurrency supporting thousands of concurrent subscriptions - [see full documentation](docs/transports/redis-queue.md)
 - **Serialization Flexibility**: Pluggable serialization formats (JSON, MessagePack, etc.)
 - **Entity-to-Entity Addressing**: Built-in FROM/TO/REPLY_TO addressing for point-to-point and broadcast messaging patterns
@@ -36,7 +37,7 @@ Think of SmartMessage as ActiveRecord for messaging - just as ActiveRecord frees
 - **Advanced Logging System**: Comprehensive logging with colorized console output, JSON structured logging, and file rolling
 - **Built-in Statistics**: Message processing metrics and monitoring
 - **Message Deduplication**: Handler-scoped deduplication queues (DDQ) with memory or Redis storage for preventing duplicate message processing
-- **Development Tools**: STDOUT and in-memory transports for testing
+- **Development Tools**: STDOUT transport for publish-only scenarios and in-memory transport for testing with local processing
 - **Production Ready**: Redis transport with automatic reconnection and error handling
 - **Dead Letter Queue**: File-based DLQ with JSON Lines format for failed message capture and replay
 - **Circuit Breaker Integration**: Production-grade reliability with BreakerMachines for automatic fallback and recovery
@@ -131,8 +132,8 @@ class OrderMessage < SmartMessage::Base
 
   # Configure transport and serializer at class level
   config do
-    # Option 1: Simple STDOUT for development
-    transport SmartMessage::Transport.create(:stdout, loopback: true)
+    # Option 1: Memory transport for local development with message processing
+    transport SmartMessage::Transport::MemoryTransport.new
 
     # Option 2: Redis Queue for production (10x faster than RabbitMQ!)
     # transport SmartMessage::Transport.create(:redis_queue,
@@ -196,24 +197,19 @@ OrderMessage.subscribe
 OrderMessage.subscribe("PaymentService.process_order")
 
 # 3. Block handler (NEW!)
-OrderMessage.subscribe do |wrapper|
-  header, payload = wrapper.split
-  order_data = JSON.parse(payload)
-  puts "Quick processing: Order #{order_data['order_id']}"
+OrderMessage.subscribe do |message|
+  puts "Quick processing: Order #{message.order_id}"
 end
 
 # 4. Proc handler (NEW!)
-order_processor = proc do |wrapper|
-  header, payload = wrapper.split
-  order_data = JSON.parse(payload)
-  EmailService.send_confirmation(order_data['customer_id'])
+order_processor = proc do |message|
+  EmailService.send_confirmation(message.customer_id)
 end
 OrderMessage.subscribe(order_processor)
 
 # 5. Lambda handler (NEW!)
-audit_handler = lambda do |wrapper|
-  header, payload = wrapper.split
-  AuditLog.record("Order processed at #{header.published_at}")
+audit_handler = lambda do |message|
+  AuditLog.record("Order processed at #{message._sm_header.published_at}")
 end
 OrderMessage.subscribe(audit_handler)
 ```
@@ -542,8 +538,8 @@ The foundation class that all messages inherit from. Built on `Hashie::Dash` wit
 #### Transport Layer
 Pluggable message delivery system with built-in implementations:
 
-- **StdoutTransport**: Development and testing transport
-- **MemoryTransport**: In-memory queuing for testing
+- **StdoutTransport**: Publish-only transport for debugging and external integration
+- **MemoryTransport**: In-memory queuing for testing with local message processing
 - **RedisTransport**: Redis pub/sub transport for production messaging
 - **Custom Transports**: Implement `SmartMessage::Transport::Base`
 
@@ -586,6 +582,38 @@ This enables gateway patterns where messages can be received from one transport/
 
 ## Transport Implementations
 
+### Multi-Transport Messages
+
+SmartMessage supports publishing to multiple transports simultaneously for redundancy, integration, and migration scenarios:
+
+```ruby
+class CriticalOrderMessage < SmartMessage::Base
+  property :order_id, required: true
+  property :amount, required: true
+  
+  # Configure multiple transports - message goes to ALL of them
+  transport [
+    SmartMessage::Transport.create(:redis_queue, url: 'redis://primary:6379'),
+    SmartMessage::Transport.create(:redis, url: 'redis://backup:6379'),
+    SmartMessage::Transport::StdoutTransport.new(format: :json)
+  ]
+end
+
+# Publishes to Redis Queue, Redis Pub/Sub, and STDOUT simultaneously
+message = CriticalOrderMessage.new(order_id: "ORD-123", amount: 99.99)
+message.publish  # ✅ Succeeds if ANY transport works
+
+# Check transport configuration
+puts message.multiple_transports?  # => true
+puts message.transports.length     # => 3
+```
+
+**Key Benefits:**
+- **Redundancy**: Messages reach multiple destinations for reliability
+- **Integration**: Simultaneously log to STDOUT, send to Redis, and webhook external systems  
+- **Migration**: Gradually transition between transport systems
+- **Resilient**: Publishing succeeds as long as ANY transport works
+
 ### Redis Queue Transport (Featured) 🌟
 
 The Redis Queue Transport provides enterprise-grade message routing with exceptional performance:
@@ -637,17 +665,39 @@ OrderMessage.new(
 
 📚 **Full Documentation:** [Redis Queue Transport Guide](docs/transports/redis-queue.md) | [Getting Started](docs/guides/redis-queue-getting-started.md) | [Examples](examples/redis_queue/)
 
-### STDOUT Transport (Development)
+### STDOUT Transport (Publish-Only)
+
+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
-transport = SmartMessage::Transport.create(:stdout)
+# Basic STDOUT output (publish-only)
+transport = SmartMessage::Transport::StdoutTransport.new
+
+# JSON Lines format - one message per line (default)
+transport = SmartMessage::Transport::StdoutTransport.new(format: :jsonl)
 
-# With loopback for testing subscriptions
-transport = SmartMessage::Transport.create(:stdout, loopback: true)
+# Pretty-printed format with amazing_print for human reading
+transport = SmartMessage::Transport::StdoutTransport.new(format: :pretty)
 
-# Output to file
-transport = SmartMessage::Transport.create(:stdout, output: "messages.log")
+# Compact JSON format without newlines
+transport = SmartMessage::Transport::StdoutTransport.new(format: :json)
+
+# Output to file instead of STDOUT
+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
+- **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 '.first_name'`, `./app | fluentd`, development monitoring
+
+**For local message processing, use MemoryTransport instead:**
+```ruby
+# Use Memory transport if you need local message processing
+transport = SmartMessage::Transport::MemoryTransport.new
 ```
 
 ### Memory Transport (Testing)
@@ -952,8 +1002,8 @@ You can also set descriptions within configuration blocks:
 class ConfiguredMessage < SmartMessage::Base
   config do
     description "Set within config block"
-    transport SmartMessage::Transport.create(:stdout)
-    serializer SmartMessage::Serializer::JSON.new
+    transport SmartMessage::Transport::MemoryTransport.new
+    serializer SmartMessage::Serializer::Json.new
   end
 end
 ```