smart_message 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efdcf78330a702d97c6c59ec11495c04a42ef746fbe6ed12011711ba127a792c
-  data.tar.gz: 395ae151a03376eab42036932e6ebbb437ddd0a42659a8ce8aca64fb80af45e7
+  metadata.gz: 8a7c214ec62b411d8f3bbf0925d6547fa135233684ac22483e028ffc76cc6cbe
+  data.tar.gz: f80ce67e2ea59172a36a8c7b675864c93573bf1f2b94e294124bdf2bbb28ae73
 SHA512:
-  metadata.gz: d307903f836b3f1252bc8e6723c09112c4a89ace6dcb1fbf07581e1782b4ab92899ebaa4d00b74e1c615dd75b7e34a754c2adc84c9c1c894c1e5a679862742a7
-  data.tar.gz: 966a81e21c5348b5c922f068a5edeb5709e73d6ae871eb0c653c76850b7f89ce4d1fde78ff5cd89df03e16cf8558fc6ce40c1949df179ba2f44f977ffe46b718
+  metadata.gz: da70af3b299ef64e94d8cefd87b3bb25b0a50dd3b835d4765a6f26231c65d0fa69b2ccf3d204d8de666aca2e241dcb37e396dcd064aaeae895881885e8c1ea21
+  data.tar.gz: fd2da658b323102bcb93e73f9b5d0ae843bd6afc7a8f031be7ebc206d89231f3304092d83de79524d7fd337f09a0bafad7b7bfc782e9f7a9820d32568c65e252

data/.gitignore

@@ -1,3 +1,4 @@
+/*.log
 /.bundle/
 /.yardoc
 /_yardoc/

data/CHANGELOG.md

@@ -7,7 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.0.1] 2025-08-17
+## [0.0.2] - 2025-08-17
+
+### Added
+- **Property Descriptions**: New property-level description system for message documentation
+  - Add descriptions to individual properties using `property :name, description: "text"`
+  - Access descriptions programmatically via `property_description(:name)` method
+  - Get all property descriptions with `property_descriptions` method
+  - List properties with descriptions using `described_properties` method
+  - Implemented via new `SmartMessage::PropertyDescriptions` module
+- **Class-Level Descriptions**: New message class documentation system
+  - Set class descriptions using `description "text"` class method
+  - Retrieve descriptions with `MyMessage.description`
+  - Can be set within config blocks or after class definition
+  - Useful for API documentation and code generation tools
+- **Enhanced Documentation**
+  - Added comprehensive property system documentation (`docs/properties.md`)
+  - Documents all Hashie::Dash options and SmartMessage enhancements
+  - Includes examples of property transformations, coercions, and translations
+  - Added to documentation table of contents
+
+### Changed
+- Updated README.md with property and class description examples
+- Enhanced SmartMessage::Base with property introspection capabilities
+
+### Tests
+- Added comprehensive test suite for property descriptions (`test/property_descriptions_test.rb`)
+- Added test suite for class-level descriptions (`test/description_test.rb`)
+- Updated base_test.rb with class description test cases
+- All tests passing with full backward compatibility
+
+## [0.0.1] - 2025-08-17
 
 ### Added
 - Comprehensive example applications demonstrating different messaging patterns

data/Gemfile.lock

@@ -1,10 +1,11 @@
 PATH
   remote: .
   specs:
-    smart_message (0.0.1)
+    smart_message (0.0.3)
       activesupport
       concurrent-ruby
       hashie
+      redis
 
 GEM
   remote: https://rubygems.org/
@@ -41,6 +42,10 @@ GEM
     mutex_m (0.3.0)
     power_assert (2.0.5)
     rake (13.3.0)
+    redis (5.4.1)
+      redis-client (>= 0.22.0)
+    redis-client (0.25.2)
+      connection_pool
     securerandom (0.4.1)
     shoulda (4.0.0)
       shoulda-context (~> 2.0)

data/README.md

@@ -7,12 +7,14 @@ SmartMessage is a message abstraction framework that decouples business logic fr
 
 ## Features
 
-- **Transport Abstraction**: Plugin architecture supporting multiple message transports (RabbitMQ, Kafka, etc.)
+- **Transport Abstraction**: Plugin architecture supporting multiple message transports (Redis, RabbitMQ, Kafka, etc.)
 - **Serialization Flexibility**: Pluggable serialization formats (JSON, MessagePack, etc.)
+- **Flexible Message Handlers**: Multiple subscription patterns - default methods, custom methods, blocks, procs, and lambdas
 - **Dual-Level Configuration**: Class and instance-level plugin overrides for gateway patterns
 - **Concurrent Processing**: Thread-safe message routing using `Concurrent::CachedThreadPool`
 - **Built-in Statistics**: Message processing metrics and monitoring
 - **Development Tools**: STDOUT and in-memory transports for testing
+- **Production Ready**: Redis transport with automatic reconnection and error handling
 
 ## Installation
 
@@ -36,10 +38,10 @@ Or install it yourself as:
 
 ```ruby
 class OrderMessage < SmartMessage::Base
-  property :order_id
-  property :customer_id
-  property :amount
-  property :items
+  property :order_id, description: "Unique order identifier"
+  property :customer_id, description: "Customer's unique ID"
+  property :amount, description: "Total order amount in dollars"
+  property :items, description: "Array of ordered items"
 
   # Configure transport and serializer at class level
   config do
@@ -85,12 +87,33 @@ order.publish
 
 ### 3. Subscribe to Messages
 
+SmartMessage supports multiple ways to handle incoming messages:
+
 ```ruby
-# Subscribe to process incoming OrderMessage instances
+# 1. Default handler (uses self.process method)
 OrderMessage.subscribe
 
-# Or specify a custom processing method
-OrderMessage.subscribe("OrderMessage.custom_processor")
+# 2. Custom method handler
+OrderMessage.subscribe("PaymentService.process_order")
+
+# 3. Block handler (NEW!)
+OrderMessage.subscribe do |header, payload|
+  order_data = JSON.parse(payload)
+  puts "Quick processing: Order #{order_data['order_id']}"
+end
+
+# 4. Proc handler (NEW!)
+order_processor = proc do |header, payload|
+  order_data = JSON.parse(payload)
+  EmailService.send_confirmation(order_data['customer_id'])
+end
+OrderMessage.subscribe(order_processor)
+
+# 5. Lambda handler (NEW!)
+audit_handler = lambda do |header, payload|
+  AuditLog.record("Order processed at #{header.published_at}")
+end
+OrderMessage.subscribe(audit_handler)
 ```
 
 ## Architecture
@@ -109,6 +132,7 @@ Pluggable message delivery system with built-in implementations:
 
 - **StdoutTransport**: Development and testing transport
 - **MemoryTransport**: In-memory queuing for testing
+- **RedisTransport**: Redis pub/sub transport for production messaging
 - **Custom Transports**: Implement `SmartMessage::Transport::Base`
 
 #### Serializer System
@@ -177,35 +201,85 @@ puts transport.all_messages
 transport.process_all  # Process all pending messages
 ```
 
+### Redis Transport (Production)
+
+```ruby
+# Basic Redis configuration
+transport = SmartMessage::Transport.create(:redis, 
+  url: 'redis://localhost:6379',
+  db: 0
+)
+
+# Production configuration with custom options
+transport = SmartMessage::Transport.create(:redis,
+  url: 'redis://prod-redis:6379',
+  db: 1,
+  auto_subscribe: true,
+  reconnect_attempts: 5,
+  reconnect_delay: 2
+)
+
+# Configure message class to use Redis
+MyMessage.config do
+  transport SmartMessage::Transport.create(:redis, url: 'redis://localhost:6379')
+  serializer SmartMessage::Serializer::JSON.new
+end
+
+# Subscribe to messages (uses message class name as Redis channel)
+MyMessage.subscribe
+
+# Publish messages (automatically publishes to Redis channel named "MyMessage")
+message = MyMessage.new(data: "Hello Redis!")
+message.publish
+```
+
+The Redis transport uses the message class name as the Redis channel name, enabling automatic routing of messages to their appropriate handlers.
+
 ### Custom Transport
 
 ```ruby
-class RedisTransport < SmartMessage::Transport::Base
+class WebhookTransport < SmartMessage::Transport::Base
   def default_options
-    { redis_url: "redis://localhost:6379" }
+    { 
+      webhook_url: "https://api.example.com/webhooks",
+      timeout: 30,
+      retries: 3
+    }
   end
 
   def configure
-    @redis = Redis.new(url: @options[:redis_url])
+    require 'net/http'
+    @uri = URI(@options[:webhook_url])
   end
 
   def publish(message_header, message_payload)
-    channel = message_header.message_class
-    @redis.publish(channel, message_payload)
+    http = Net::HTTP.new(@uri.host, @uri.port)
+    http.use_ssl = @uri.scheme == 'https'
+    
+    request = Net::HTTP::Post.new(@uri)
+    request['Content-Type'] = 'application/json'
+    request['X-Message-Class'] = message_header.message_class
+    request.body = message_payload
+    
+    response = http.request(request)
+    raise "Webhook failed: #{response.code}" unless response.code.to_i < 400
   end
 
   def subscribe(message_class, process_method)
     super
-    # Set up Redis subscription for message_class
+    # For webhooks, subscription would typically be configured 
+    # externally on the webhook provider's side
   end
 end
 
 # Register the transport
-SmartMessage::Transport.register(:redis, RedisTransport)
+SmartMessage::Transport.register(:webhook, WebhookTransport)
 
 # Use the transport
 MyMessage.config do
-  transport SmartMessage::Transport.create(:redis, redis_url: "redis://prod:6379")
+  transport SmartMessage::Transport.create(:webhook, 
+    webhook_url: "https://api.myservice.com/messages"
+  )
 end
 ```
 
@@ -214,8 +288,12 @@ end
 1. **Definition**: Create message class inheriting from `SmartMessage::Base`
 2. **Configuration**: Set transport, serializer, and logger plugins
 3. **Publishing**: Message instance is encoded and sent through transport
-4. **Subscription**: Message classes register with dispatcher for processing
-5. **Processing**: Received messages are decoded and `process` method is called
+4. **Subscription**: Message classes register handlers with dispatcher for processing
+   - Default handlers (`self.process` method)
+   - Custom method handlers (`"ClassName.method_name"`)
+   - Block handlers (`subscribe do |h,p|...end`)
+   - Proc/Lambda handlers (`subscribe(proc {...})`)
+5. **Processing**: Received messages are decoded and routed to registered handlers
 
 ## Advanced Usage
 
@@ -255,9 +333,9 @@ puts dispatcher.subscribers
 
 ```ruby
 class MyMessage < SmartMessage::Base
-  property :user_id
-  property :action
-  property :timestamp, default: -> { Time.now }
+  property :user_id, description: "User's unique identifier"
+  property :action, description: "Action performed by the user"
+  property :timestamp, default: -> { Time.now }, description: "When the action occurred"
 end
 
 message = MyMessage.new(user_id: 123, action: "login")
@@ -266,6 +344,10 @@ message = MyMessage.new(user_id: 123, action: "login")
 puts message.user_id
 puts message.fields  # Returns Set of property names (excluding internal _sm_ properties)
 
+# Access property descriptions
+puts MyMessage.property_description(:user_id)  # => "User's unique identifier"
+puts MyMessage.property_descriptions            # => Hash of all descriptions
+
 # Access message header
 puts message._sm_header.uuid
 puts message._sm_header.message_class

data/docs/README.md

@@ -8,14 +8,15 @@ Welcome to the comprehensive documentation for SmartMessage, a Ruby gem that abs
 - [Installation & Quick Start](getting-started.md)
 - [Basic Usage Examples](examples.md)
 
-### Core Concepts  
+### Core Concepts
 - [Architecture Overview](architecture.md)
 - [Message Lifecycle](message-lifecycle.md)
 - [Plugin System](plugin-system.md)
 
 ### Components
 - [SmartMessage::Base](base.md)
-- [Transport Layer](transports.md) 
+- [Property System](properties.md)
+- [Transport Layer](transports.md)
 - [Serializers](serializers.md)
 - [Dispatcher & Routing](dispatcher.md)
 - [Message Headers](headers.md)
@@ -47,6 +48,6 @@ Welcome to the comprehensive documentation for SmartMessage, a Ruby gem that abs
 
 ## Version
 
-This documentation is for SmartMessage v0.0.1.
+This documentation is for SmartMessage v0.0.2.
 
-For older versions, please check the git tags and corresponding documentation.
+For older versions, please check the git tags and corresponding documentation.

data/docs/architecture.md

@@ -40,10 +40,12 @@ SmartMessage is designed around the principle that **messages should be independ
                                 │
                                 ▼
                     ┌─────────────────────┐
-                    │  Business Logic     │
+                    │  Message Handlers   │
                     │                     │
-                    │ • process() method  │
-                    │ • Domain logic      │
+                    │ • Default handler   │
+                    │ • Block handlers    │
+                    │ • Proc handlers     │
+                    │ • Method handlers   │
                     └─────────────────────┘
 ```
 
@@ -193,21 +195,52 @@ transport.receive(header, payload)
 # 1. Routes to dispatcher
 # 2. Dispatcher finds subscribers
 # 3. Spawns thread for processing
-# 4. Calls OrderMessage.process(header, payload)
+# 4. Calls registered message handlers
 ```
 
-### 5. Processing Phase
+### 5. Message Handler Processing
+
+SmartMessage supports multiple handler types, routed through the dispatcher:
+
 ```ruby
+# Default handler (self.process method)
 def self.process(message_header, message_payload)
-  # 1. Decode payload
   data = JSON.parse(message_payload)
   order = new(data)
-  
-  # 2. Execute business logic
   fulfill_order(order)
 end
+
+# Block handler (inline processing)
+OrderMessage.subscribe do |header, payload|
+  data = JSON.parse(payload)
+  quick_processing(data)
+end
+
+# Proc handler (reusable across message types)
+audit_proc = proc do |header, payload|
+  AuditService.log_message(header.message_class, payload)
+end
+OrderMessage.subscribe(audit_proc)
+
+# Method handler (service class processing)
+class OrderService
+  def self.process_order(header, payload)
+    data = JSON.parse(payload)
+    complex_business_logic(data)
+  end
+end
+OrderMessage.subscribe("OrderService.process_order")
 ```
 
+**Handler Routing Process:**
+1. Dispatcher receives message and header
+2. Looks up all registered handlers for message class
+3. For each handler:
+   - **String handlers**: Resolves to class method via constantize
+   - **Proc handlers**: Calls proc directly from registry
+4. Executes handlers in parallel threads
+5. Collects statistics and handles errors
+
 ## Plugin System Architecture
 
 ### Dual-Level Configuration

data/docs/dispatcher.md

@@ -28,27 +28,49 @@ Located at `lib/smart_message/dispatcher.rb:11-147`, the dispatcher is the centr
 
 ### Adding Subscriptions
 
+SmartMessage supports multiple subscription patterns:
+
 ```ruby
-# Basic subscription - uses default process method
+# 1. Default handler - uses self.process method
 MyMessage.subscribe
 # Registers "MyMessage.process" as the handler
 
-# Custom process method
-MyMessage.subscribe("MyMessage.custom_handler")
-# Registers "MyMessage.custom_handler" as the handler
+# 2. Custom method handler
+MyMessage.subscribe("MyService.handle_message")
+# Registers "MyService.handle_message" as the handler
+
+# 3. Block handler (NEW!)
+handler_id = MyMessage.subscribe do |header, payload|
+  puts "Processing: #{JSON.parse(payload)}"
+end
+# Registers a proc handler with generated ID like "MyMessage.proc_abc123"
+
+# 4. Proc handler (NEW!)
+my_proc = proc { |header, payload| log_message(payload) }
+proc_id = MyMessage.subscribe(my_proc)
+# Registers the proc with generated ID
+
+# 5. Lambda handler (NEW!)
+my_lambda = lambda { |header, payload| validate_message(payload) }
+lambda_id = MyMessage.subscribe(my_lambda)
 
 # Multiple handlers for the same message
-MyMessage.subscribe("MyMessage.handler_one")
-MyMessage.subscribe("MyMessage.handler_two")
-# Both handlers will receive the message
+MyMessage.subscribe("MyMessage.audit")
+MyMessage.subscribe("MyMessage.notify")
+MyMessage.subscribe { |h,p| puts "Quick log" }
+# All handlers will receive the message
 ```
 
 ### Removing Subscriptions
 
 ```ruby
-# Remove specific handler
+# Remove specific method handler
 MyMessage.unsubscribe("MyMessage.custom_handler")
 
+# Remove specific proc/block handler using returned ID
+block_id = MyMessage.subscribe { |h,p| puts p }
+MyMessage.unsubscribe(block_id)  # Cleans up proc from registry too
+
 # Remove ALL handlers for a message class
 MyMessage.unsubscribe!
 
@@ -101,7 +123,7 @@ end
 
 ### 3. Concurrent Processing
 
-Each handler is processed in its own thread:
+Each handler is processed in its own thread, with support for both method and proc handlers:
 
 ```ruby
 @subscribers[message_klass].each do |message_processor|
@@ -109,21 +131,35 @@ Each handler is processed in its own thread:
   
   @router_pool.post do
     # This runs in a separate thread
-    parts = message_processor.split('.')
-    target_klass = parts[0]  # "MyMessage"
-    class_method = parts[1]  # "process"
-    
     begin
-      result = target_klass.constantize
-                  .method(class_method)
-                  .call(message_header, message_payload)
+      # Check if this is a proc handler or a regular method call
+      if proc_handler?(message_processor)
+        # Call the proc handler via SmartMessage::Base
+        SmartMessage::Base.call_proc_handler(message_processor, message_header, message_payload)
+      else
+        # Original method call logic
+        parts = message_processor.split('.')
+        target_klass = parts[0]  # "MyMessage" 
+        class_method = parts[1]  # "process"
+        
+        target_klass.constantize
+                    .method(class_method)
+                    .call(message_header, message_payload)
+      end
     rescue Exception => e
       # Error handling - doesn't crash the dispatcher
+      puts "Error processing message: #{e.message}" if $DEBUG
     end
   end
 end
 ```
 
+**Handler Types Processed:**
+- **Method handlers**: `"ClassName.method_name"` → resolved via constantize
+- **Proc handlers**: `"ClassName.proc_abc123"` → looked up in proc registry  
+- **Block handlers**: `"ClassName.proc_def456"` → treated as proc handlers
+- **Lambda handlers**: `"ClassName.proc_ghi789"` → treated as proc handlers
+
 ## Thread Pool Management
 
 ### Thread Pool Configuration

data/docs/getting-started.md

@@ -64,11 +64,27 @@ end
 
 ### 2. Subscribe to Messages
 
-Before publishing, set up a subscription to receive messages:
+Before publishing, set up a subscription to receive messages. SmartMessage provides several ways to handle incoming messages:
 
 ```ruby
-# Subscribe to process incoming WelcomeMessage instances
+# 1. Default handler (uses the self.process method defined above)
 WelcomeMessage.subscribe
+
+# 2. Block handler (inline processing logic)
+WelcomeMessage.subscribe do |header, payload|
+  data = JSON.parse(payload)
+  puts "👋 Quick welcome for #{data['user_name']}"
+end
+
+# 3. Proc handler (reusable processing logic)
+welcome_processor = proc do |header, payload|
+  data = JSON.parse(payload)
+  EmailService.send_welcome_email(data['email'], data['user_name'])
+end
+WelcomeMessage.subscribe(welcome_processor)
+
+# 4. Custom method handler
+WelcomeMessage.subscribe("UserService.handle_welcome")
 ```
 
 ### 3. Create and Publish a Message
@@ -153,6 +169,52 @@ Serializers handle message encoding/decoding:
 serializer SmartMessage::Serializer::JSON.new
 ```
 
+### Message Handlers
+
+SmartMessage supports four types of message handlers to give you flexibility in how you process messages:
+
+```ruby
+class OrderMessage < SmartMessage::Base
+  # Define your message properties
+  property :order_id
+  property :amount
+  
+  # Default handler - processed when no custom handler specified
+  def self.process(header, payload)
+    puts "Default processing for order"
+  end
+end
+
+# 1. Default handler (uses self.process)
+OrderMessage.subscribe
+
+# 2. Block handler - great for simple, inline logic
+OrderMessage.subscribe do |header, payload|
+  data = JSON.parse(payload)
+  puts "Block handler: Processing order #{data['order_id']}"
+end
+
+# 3. Proc handler - reusable across message types
+audit_logger = proc do |header, payload|
+  puts "Audit: #{header.message_class} at #{header.published_at}"
+end
+OrderMessage.subscribe(audit_logger)
+
+# 4. Method handler - organized in service classes
+class OrderService
+  def self.process_order(header, payload)
+    puts "Service processing order"
+  end
+end
+OrderMessage.subscribe("OrderService.process_order")
+```
+
+**When to use each type:**
+- **Default**: Simple built-in processing for the message type
+- **Block**: Quick inline logic specific to one subscription
+- **Proc**: Reusable handlers that work across multiple message types
+- **Method**: Complex business logic organized in service classes
+
 ## Next Steps
 
 Now that you have the basics working, explore: