smart_message 0.0.1 → 0.0.3

data/docs/properties.md

@@ -0,0 +1,471 @@
+# SmartMessage Property System
+
+The SmartMessage property system builds on Hashie::Dash to provide a robust, declarative way to define message attributes. This document covers all available property options and features.
+
+## Table of Contents
+- [Basic Property Definition](#basic-property-definition)
+- [Class-Level Description](#class-level-description)
+- [Property Options](#property-options)
+- [Accessing Property Information](#accessing-property-information)
+- [Hashie Extensions](#hashie-extensions)
+- [Examples](#examples)
+
+## Basic Property Definition
+
+Properties are defined using the `property` method in your message class:
+
+```ruby
+class MyMessage < SmartMessage::Base
+  property :field_name
+end
+```
+
+## Class-Level Description
+
+In addition to property-level descriptions, you can add a description for the entire message class:
+
+```ruby
+class OrderMessage < SmartMessage::Base
+  description "Handles order processing and fulfillment workflow"
+  
+  property :order_id, description: "Unique order identifier"
+  property :amount, description: "Total amount in cents"
+end
+
+# Access the class description
+OrderMessage.description  # => "Handles order processing and fulfillment workflow"
+
+# Class descriptions can also be set after class definition
+class PaymentMessage < SmartMessage::Base
+  property :payment_id
+end
+
+PaymentMessage.description "Processes payment transactions"
+PaymentMessage.description  # => "Processes payment transactions"
+
+# Can be set within config block
+class NotificationMessage < SmartMessage::Base
+  config do
+    description "Sends notifications to users"
+    transport MyTransport.new
+    serializer MySerializer.new
+  end
+end
+```
+
+Class descriptions are useful for:
+- Documenting the overall purpose of a message class
+- Providing context for code generation tools
+- Integration with documentation systems
+- API documentation generation
+
+Note: Class descriptions are not inherited by subclasses. Each class maintains its own description.
+
+## Property Options
+
+SmartMessage supports all Hashie::Dash property options plus additional features:
+
+### 1. Default Values
+
+Specify a default value for a property when not provided during initialization:
+
+```ruby
+class OrderMessage < SmartMessage::Base
+  # Static default
+  property :status, default: 'pending'
+
+  # Dynamic default using a Proc
+  property :created_at, default: -> { Time.now }
+
+  # Default array
+  property :items, default: []
+end
+
+order = OrderMessage.new
+order.status     # => 'pending'
+order.created_at # => Current time
+order.items      # => []
+```
+
+### 2. Required Properties
+
+Mark properties as required to ensure they're provided during initialization:
+
+```ruby
+class PaymentMessage < SmartMessage::Base
+  property :payment_id, required: true
+  property :amount, required: true
+  property :note  # Optional
+end
+
+# This raises ArgumentError: The property 'payment_id' is required
+PaymentMessage.new(amount: 100)
+
+# This works
+PaymentMessage.new(payment_id: 'PAY-123', amount: 100)
+```
+
+### 3. Property Transformation
+
+Transform property values when they're set:
+
+```ruby
+class UserMessage < SmartMessage::Base
+  property :email, transform_with: ->(v) { v.to_s.downcase }
+  property :name, transform_with: ->(v) { v.to_s.strip.capitalize }
+  property :tags, transform_with: ->(v) { Array(v).map(&:to_s) }
+end
+
+user = UserMessage.new(
+  email: 'USER@EXAMPLE.COM',
+  name: '  john  ',
+  tags: 'admin'
+)
+
+user.email # => 'user@example.com'
+user.name  # => 'John'
+user.tags  # => ['admin']
+```
+
+### 4. Property Translation (from Hashie::Extensions::Dash::PropertyTranslation)
+
+Map external field names to internal property names:
+
+```ruby
+class ApiMessage < SmartMessage::Base
+  property :user_id, from: :userId
+  property :order_date, from: 'orderDate'
+  property :total_amount, from: [:totalAmount, :total, :amount]
+end
+
+# All of these work
+msg1 = ApiMessage.new(userId: 123)
+msg2 = ApiMessage.new(user_id: 123)
+msg3 = ApiMessage.new('orderDate' => '2024-01-01')
+msg4 = ApiMessage.new(totalAmount: 100)  # or total: 100, or amount: 100
+
+msg1.user_id # => 123
+```
+
+### 5. Type Coercion (from Hashie::Extensions::Coercion)
+
+Automatically coerce property values to specific types:
+
+```ruby
+class TypedMessage < SmartMessage::Base
+  property :count
+  property :price
+  property :active
+  property :tags
+  property :metadata
+
+  coerce_key :count, Integer
+  coerce_key :price, Float
+  coerce_key :active, ->(v) { v.to_s.downcase == 'true' }
+  coerce_key :tags, Array[String]
+  coerce_key :metadata, Hash
+end
+
+msg = TypedMessage.new(
+  count: '42',
+  price: '19.99',
+  active: 'yes',
+  tags: 'important',
+  metadata: nil
+)
+
+msg.count    # => 42 (Integer)
+msg.price    # => 19.99 (Float)
+msg.active   # => false (Boolean logic)
+msg.tags     # => ['important'] (Array)
+msg.metadata # => {} (Hash)
+```
+
+### 6. Property Descriptions (SmartMessage Enhancement)
+
+Add human-readable descriptions to document your properties for dynamic LLM integration:
+
+```ruby
+class DocumentedMessage < SmartMessage::Base
+  property :transaction_id,
+           required: true,
+           description: "Unique identifier for the transaction"
+
+  property :amount,
+           transform_with: ->(v) { BigDecimal(v.to_s) },
+           description: "Transaction amount in the smallest currency unit"
+
+  property :currency,
+           default: 'USD',
+           description: "ISO 4217 currency code"
+
+  property :status,
+           default: 'pending',
+           description: "Current transaction status: pending, completed, failed"
+
+  property :metadata,
+           default: {},
+           description: "Additional transaction metadata as key-value pairs"
+end
+
+# Access descriptions programmatically
+DocumentedMessage.property_description(:amount)
+# => "Transaction amount in the smallest currency unit"
+
+DocumentedMessage.property_descriptions
+# => {
+#      transaction_id: "Unique identifier for the transaction",
+#      amount: "Transaction amount in the smallest currency unit",
+#      currency: "ISO 4217 currency code",
+#      status: "Current transaction status: pending, completed, failed",
+#      metadata: "Additional transaction metadata as key-value pairs"
+#    }
+
+DocumentedMessage.described_properties
+# => [:transaction_id, :amount, :currency, :status, :metadata]
+```
+
+## Accessing Property Information
+
+SmartMessage provides several methods to introspect properties:
+
+```ruby
+class IntrospectionExample < SmartMessage::Base
+  property :id, required: true, description: "Unique identifier"
+  property :name, description: "Display name"
+  property :created_at, default: -> { Time.now }
+  property :tags
+end
+
+# Instance methods
+instance = IntrospectionExample.new(id: 1, name: "Test")
+instance.fields  # => Set[:id, :name, :created_at, :tags]
+instance.to_h    # => Hash of all properties and values
+
+# Class methods
+IntrospectionExample.fields              # => Set[:id, :name, :created_at, :tags]
+IntrospectionExample.property_descriptions  # => Hash of descriptions
+IntrospectionExample.described_properties   # => [:id, :name]
+```
+
+## Hashie Extensions
+
+SmartMessage::Base automatically includes these Hashie extensions:
+
+### 1. DeepMerge
+Allows deep merging of nested hash properties:
+
+```ruby
+msg = MyMessage.new(config: { a: 1, b: { c: 2 } })
+msg.deep_merge(config: { b: { d: 3 } })
+# => config: { a: 1, b: { c: 2, d: 3 } }
+```
+
+### 2. IgnoreUndeclared
+Silently ignores properties that haven't been declared:
+
+```ruby
+# Won't raise an error for unknown properties
+msg = MyMessage.new(known: 'value', unknown: 'ignored')
+```
+
+### 3. IndifferentAccess
+Access properties with strings or symbols:
+
+```ruby
+msg = MyMessage.new('name' => 'John')
+msg[:name]    # => 'John'
+msg['name']   # => 'John'
+msg.name      # => 'John'
+```
+
+### 4. MethodAccess
+Access properties as methods:
+
+```ruby
+msg = MyMessage.new(name: 'John')
+msg.name         # => 'John'
+msg.name = 'Jane'
+msg.name         # => 'Jane'
+```
+
+### 5. MergeInitializer
+Allows initializing with merged hash values:
+
+```ruby
+defaults = { status: 'active', retries: 3 }
+msg = MyMessage.new(defaults.merge(status: 'pending'))
+# => status: 'pending', retries: 3
+```
+
+## Examples
+
+### Complete Example: Order Processing Message
+
+```ruby
+class OrderProcessingMessage < SmartMessage::Base
+  description "Manages the complete order lifecycle from placement to delivery"
+  
+  # Required fields with descriptions
+  property :order_id,
+           required: true,
+           description: "Unique order identifier from the ordering system"
+
+  property :customer_id,
+           required: true,
+           description: "Customer who placed the order"
+
+  # Amount with transformation and description
+  property :total_amount,
+           transform_with: ->(v) { BigDecimal(v.to_s) },
+           description: "Total order amount including tax and shipping"
+
+  # Status with default and validation description
+  property :status,
+           default: 'pending',
+           description: "Order status: pending, processing, shipped, delivered, cancelled"
+
+  # Items with coercion
+  property :items,
+           default: [],
+           description: "Array of order line items"
+
+  # Timestamps with dynamic defaults
+  property :created_at,
+           default: -> { Time.now },
+           description: "When the order was created"
+
+  property :updated_at,
+           default: -> { Time.now },
+           description: "Last modification timestamp"
+
+  # Optional fields
+  property :notes,
+           description: "Optional order notes or special instructions"
+
+  property :shipping_address,
+           description: "Shipping address as a nested hash"
+
+  # Field translation for external APIs
+  property :external_ref,
+           from: [:externalReference, :ext_ref],
+           description: "Reference ID from external system"
+end
+
+# Usage
+order = OrderProcessingMessage.new(
+  order_id: 'ORD-2024-001',
+  customer_id: 'CUST-123',
+  total_amount: '149.99',
+  items: [
+    { sku: 'WIDGET-A', quantity: 2, price: 49.99 },
+    { sku: 'WIDGET-B', quantity: 1, price: 50.01 }
+  ],
+  shipping_address: {
+    street: '123 Main St',
+    city: 'Springfield',
+    state: 'IL',
+    zip: '62701'
+  },
+  externalReference: 'EXT-789'  # Note: uses translated field name
+)
+
+# Access properties
+order.order_id         # => 'ORD-2024-001'
+order.total_amount     # => BigDecimal('149.99')
+order.status           # => 'pending' (default)
+order.external_ref     # => 'EXT-789' (translated)
+order.created_at       # => Time object
+
+# Get class and property information
+OrderProcessingMessage.description
+# => "Manages the complete order lifecycle from placement to delivery"
+
+OrderProcessingMessage.property_description(:total_amount)
+# => "Total order amount including tax and shipping"
+
+OrderProcessingMessage.property_descriptions.keys
+# => [:order_id, :customer_id, :total_amount, :status, :items, ...]
+```
+
+### Example: API Integration Message
+
+```ruby
+class ApiWebhookMessage < SmartMessage::Base
+  # Handle different API naming conventions
+  property :event_type,
+           from: [:eventType, :event, :type],
+           required: true,
+           description: "Type of webhook event"
+
+  property :payload,
+           required: true,
+           description: "Event payload data"
+
+  property :timestamp,
+           from: [:timestamp, :created_at, :occurredAt],
+           transform_with: ->(v) { Time.parse(v.to_s) },
+           description: "When the event occurred"
+
+  property :retry_count,
+           from: :retryCount,
+           default: 0,
+           transform_with: ->(v) { v.to_i },
+           description: "Number of delivery attempts"
+
+  property :signature,
+           description: "HMAC signature for webhook validation"
+end
+
+# Can initialize with various field names
+webhook1 = ApiWebhookMessage.new(
+  eventType: 'order.completed',
+  payload: { order_id: 123 },
+  occurredAt: '2024-01-01T10:00:00Z',
+  retryCount: '2'
+)
+
+webhook2 = ApiWebhookMessage.new(
+  type: 'order.completed',        # Alternative field name
+  payload: { order_id: 123 },
+  timestamp: Time.now,             # Alternative field name
+  retry_count: 2                   # Internal field name
+)
+```
+
+## Best Practices
+
+1. **Always add descriptions** to document the purpose and format of each property
+2. **Use required properties** for fields that must be present for valid messages
+3. **Provide sensible defaults** for optional fields to reduce boilerplate
+4. **Use transformations** to ensure data consistency and type safety
+5. **Leverage field translation** when integrating with external APIs that use different naming conventions
+6. **Document valid values** in descriptions for enum-like fields (e.g., status fields)
+7. **Use type coercion** for fields that may come from untrusted sources (like HTTP parameters)
+
+## Property Option Compatibility
+
+Multiple options can be combined on a single property:
+
+```ruby
+property :amount,
+         required: true,
+         from: [:amount, :total, :value],
+         transform_with: ->(v) { BigDecimal(v.to_s) },
+         description: "Transaction amount in cents"
+```
+
+The processing order is:
+1. Field translation (from)
+2. Default value (if not provided)
+3. Required validation
+4. Type coercion
+5. Transformation
+6. Value assignment
+
+## Limitations
+
+- Property names must be valid Ruby method names
+- The `_sm_` prefix is reserved for internal SmartMessage properties
+- Descriptions are metadata only and don't affect runtime behavior
+- Some Hashie options may conflict if used incorrectly (e.g., required with default)

data/docs/transports.md

@@ -125,6 +125,194 @@ messages.each do |msg|
 end
 ```
 
+### Redis Transport
+
+Production-ready Redis pub/sub transport for distributed messaging.
+
+**Features:**
+- Redis pub/sub messaging
+- Automatic channel management using message class names
+- Thread-safe subscriber management
+- Connection resilience with automatic reconnection
+- Configurable connection parameters
+- Background message subscription threads
+
+**Usage:**
+
+```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 in message class
+class OrderMessage < SmartMessage::Base
+  property :order_id
+  property :customer_id
+  property :amount
+  
+  config do
+    transport SmartMessage::Transport.create(:redis, 
+      url: 'redis://localhost:6379',
+      db: 1
+    )
+    serializer SmartMessage::Serializer::JSON.new
+  end
+  
+  def self.process(message_header, message_payload)
+    order_data = JSON.parse(message_payload)
+    order = new(order_data)
+    puts "Processing order #{order.order_id} for $#{order.amount}"
+    # Your business logic here
+  end
+end
+
+# Subscribe to messages (creates Redis subscription to "OrderMessage" channel)
+OrderMessage.subscribe
+
+# Publish messages (publishes to "OrderMessage" Redis channel)
+order = OrderMessage.new(
+  order_id: "ORD-123",
+  customer_id: "CUST-456", 
+  amount: 99.99
+)
+order.publish
+```
+
+**Options:**
+- `url` (String): Redis connection URL (default: 'redis://localhost:6379')
+- `db` (Integer): Redis database number (default: 0)
+- `auto_subscribe` (Boolean): Automatically start subscriber thread (default: true)
+- `reconnect_attempts` (Integer): Number of reconnection attempts (default: 5)
+- `reconnect_delay` (Integer): Delay between reconnection attempts in seconds (default: 1)
+- `debug` (Boolean): Enable debug output (default: false)
+
+**Channel Naming:**
+
+The Redis transport uses the message class name as the Redis channel name. This provides automatic routing:
+
+```ruby
+class UserMessage < SmartMessage::Base
+  # Messages published to/from Redis channel "UserMessage"
+end
+
+class AdminMessage < SmartMessage::Base  
+  # Messages published to/from Redis channel "AdminMessage"
+end
+
+class OrderProcessing::PaymentMessage < SmartMessage::Base
+  # Messages published to/from Redis channel "OrderProcessing::PaymentMessage"
+end
+```
+
+**Connection Management:**
+
+```ruby
+transport = SmartMessage::Transport.create(:redis, url: 'redis://localhost:6379')
+
+# Check connection status
+puts transport.connected?  # => true/false
+
+# Manual connection management
+transport.connect
+transport.disconnect
+
+# The transport automatically reconnects on connection failures
+```
+
+**Multi-Message Type Support:**
+
+```ruby
+# Different message types can share the same Redis transport
+redis_transport = SmartMessage::Transport.create(:redis, 
+  url: 'redis://localhost:6379',
+  auto_subscribe: true
+)
+
+# Configure multiple message classes to use the same transport
+[OrderMessage, PaymentMessage, ShippingMessage].each do |msg_class|
+  msg_class.config do
+    transport redis_transport
+    serializer SmartMessage::Serializer::JSON.new
+  end
+  
+  # Subscribe to each message type (creates separate Redis subscriptions)
+  msg_class.subscribe
+end
+
+# Publishing to any message type routes to its specific Redis channel
+OrderMessage.new(order_id: "123").publish      # -> "OrderMessage" channel
+PaymentMessage.new(amount: 50.0).publish       # -> "PaymentMessage" channel
+ShippingMessage.new(tracking: "ABC").publish   # -> "ShippingMessage" channel
+```
+
+**Error Handling and Resilience:**
+
+The Redis transport includes built-in error handling:
+
+```ruby
+# Automatic reconnection on connection failures
+transport = SmartMessage::Transport.create(:redis,
+  url: 'redis://localhost:6379',
+  reconnect_attempts: 5,    # Try 5 times to reconnect
+  reconnect_delay: 2        # Wait 2 seconds between attempts
+)
+
+# Connection failures during publishing will trigger automatic retry
+# If all reconnection attempts fail, the original error is raised
+```
+
+**Production Deployment:**
+
+```ruby
+# Production Redis configuration
+class ProductionMessage < SmartMessage::Base
+  config do
+    transport SmartMessage::Transport.create(:redis,
+      url: ENV['REDIS_URL'] || 'redis://localhost:6379',
+      db: ENV['REDIS_DB']&.to_i || 0,
+      auto_subscribe: true,
+      reconnect_attempts: 10,
+      reconnect_delay: 5
+    )
+    serializer SmartMessage::Serializer::JSON.new
+    logger Logger.new(STDOUT)
+  end
+end
+```
+
+**Testing with Redis:**
+
+```ruby
+# Test configuration (using separate Redis database)
+class TestMessage < SmartMessage::Base
+  config do
+    transport SmartMessage::Transport.create(:redis,
+      url: 'redis://localhost:6379',
+      db: 15,  # Use separate database for tests
+      auto_subscribe: true
+    )
+    serializer SmartMessage::Serializer::JSON.new
+  end
+end
+
+# In your test setup
+def setup
+  # Clear test database
+  Redis.new(url: 'redis://localhost:6379', db: 15).flushdb
+end
+```
+
 ## Transport Interface
 
 All transports must implement the `SmartMessage::Transport::Base` interface:
@@ -188,19 +376,24 @@ transport.receive(message_header, message_payload)  # protected method
 Register custom transports for easy creation:
 
 ```ruby
-# Register a transport class
-SmartMessage::Transport.register(:redis, RedisTransport)
+# Register custom transport classes
 SmartMessage::Transport.register(:kafka, KafkaTransport)
+SmartMessage::Transport.register(:webhook, WebhookTransport)
 
-# List all registered transports
+# List all registered transports (includes built-ins)
 puts SmartMessage::Transport.available
-# => [:stdout, :memory, :redis, :kafka]
+# => [:stdout, :memory, :redis, :kafka, :webhook]
 
-# Create instances
+# Create instances of built-in transports
 redis_transport = SmartMessage::Transport.create(:redis, 
   url: "redis://localhost:6379"
 )
 
+memory_transport = SmartMessage::Transport.create(:memory,
+  auto_process: true
+)
+
+# Create instances of custom transports
 kafka_transport = SmartMessage::Transport.create(:kafka,
   servers: ["localhost:9092"]
 )
@@ -311,12 +504,13 @@ SmartMessage::Transport.create(:memory,
   max_messages: 1000
 )
 
-# Hypothetical Redis specific
+# Redis specific
 SmartMessage::Transport.create(:redis,
   url: "redis://localhost:6379",
   db: 1,
-  namespace: "messages",
-  ttl: 3600
+  auto_subscribe: true,
+  reconnect_attempts: 5,
+  reconnect_delay: 2
 )
 ```