bunny_farm 0.1.2

data/docs/core-features/smart-routing.md

@@ -0,0 +1,467 @@
+# Smart Routing
+
+BunnyFarm's smart routing system automatically creates predictable routing keys based on your message classes and actions. This eliminates the need for manual routing configuration while maintaining full transparency and debuggability.
+
+## How Smart Routing Works
+
+### Routing Key Pattern
+
+BunnyFarm uses a simple, predictable pattern for routing keys:
+
+```
+MessageClassName.action
+```
+
+**Examples:**
+- `OrderMessage.process` 
+- `EmailMessage.send`
+- `ReportMessage.generate`
+- `UserRegistrationMessage.create_account`
+
+### Automatic Generation
+
+When you publish a message, the routing key is automatically generated:
+
+```ruby
+class OrderMessage < BunnyFarm::Message
+  actions :validate, :process, :ship
+end
+
+# Publishing automatically creates routing keys
+message = OrderMessage.new
+message.publish('validate')  # Routing key: OrderMessage.validate
+message.publish('process')   # Routing key: OrderMessage.process
+message.publish('ship')      # Routing key: OrderMessage.ship
+```
+
+## Routing Flow
+
+### 1. Publisher Side
+
+```ruby
+# 1. Create message
+order_msg = OrderMessage.new
+order_msg[:order_id] = 12345
+
+# 2. Publish with action
+order_msg.publish('process')
+
+# 3. BunnyFarm generates routing key: "OrderMessage.process"
+# 4. Message sent to RabbitMQ with this routing key
+```
+
+### 2. RabbitMQ Routing
+
+```
+Publisher → Exchange → Queue(s) → Consumer(s)
+            ↑
+    Routes based on
+    "OrderMessage.process"
+```
+
+### 3. Consumer Side
+
+```ruby
+# 1. Consumer receives message with routing key "OrderMessage.process"
+# 2. BunnyFarm parses routing key → class: OrderMessage, action: process  
+# 3. Message deserialized to OrderMessage instance
+# 4. The 'process' method is called automatically
+
+class OrderMessage < BunnyFarm::Message
+  def process
+    # This method is called automatically
+    puts "Processing order #{@items[:order_id]}"
+    success!
+  end
+end
+```
+
+## Exchange and Queue Configuration
+
+### Topic Exchange
+
+BunnyFarm typically uses RabbitMQ's **topic exchange** for flexible routing:
+
+```ruby
+BunnyFarm.config do
+  exchange_name 'bunny_farm_exchange'
+  exchange_type :topic  # Supports pattern matching
+end
+```
+
+### Queue Bindings
+
+Queues can bind to specific routing patterns:
+
+```ruby
+# Bind to all OrderMessage actions
+queue.bind(exchange, routing_key: 'OrderMessage.*')
+
+# Bind to specific actions only
+queue.bind(exchange, routing_key: 'OrderMessage.process')
+
+# Bind to all messages
+queue.bind(exchange, routing_key: '#')
+
+# Bind to all validation actions across message types
+queue.bind(exchange, routing_key: '*.validate')
+```
+
+## Routing Patterns
+
+### 1. Single Message Type, Single Action
+
+**Use case:** Dedicated worker for specific operations
+
+```ruby
+# Worker specializes in order processing
+BunnyFarm.config do
+  queue_name 'order_processing'
+  routing_key 'OrderMessage.process'
+end
+
+# Only processes OrderMessage.process
+BunnyFarm.manage
+```
+
+### 2. Single Message Type, Multiple Actions
+
+**Use case:** Worker handles all operations for one domain
+
+```ruby
+# Worker handles all order operations
+BunnyFarm.config do
+  queue_name 'order_worker'
+  routing_key 'OrderMessage.*'  # All OrderMessage actions
+end
+
+class OrderMessage < BunnyFarm::Message
+  actions :validate, :process, :ship, :cancel
+  
+  def validate; end    # Handled by order_worker
+  def process; end     # Handled by order_worker
+  def ship; end        # Handled by order_worker
+  def cancel; end      # Handled by order_worker
+end
+```
+
+### 3. Multiple Message Types, Specific Actions
+
+**Use case:** Worker specializes in one type of operation across domains
+
+```ruby
+# Worker handles validation for all message types
+BunnyFarm.config do
+  queue_name 'validation_worker'
+  routing_key '*.validate'  # All validation actions
+end
+
+# These would all be handled by validation_worker:
+# OrderMessage.validate
+# CustomerMessage.validate  
+# ProductMessage.validate
+```
+
+### 4. Multiple Message Types, All Actions
+
+**Use case:** General-purpose worker
+
+```ruby
+# Worker handles everything
+BunnyFarm.config do
+  queue_name 'general_worker'
+  routing_key '#'  # All messages
+end
+```
+
+## Advanced Routing Scenarios
+
+### Priority Queues
+
+Route urgent messages to high-priority queues:
+
+```ruby
+class UrgentOrderMessage < BunnyFarm::Message
+  actions :process_immediately
+end
+
+# High-priority worker
+BunnyFarm.config do
+  queue_name 'urgent_orders'
+  routing_key 'UrgentOrderMessage.*'
+  queue_options do
+    arguments 'x-max-priority' => 10
+  end
+end
+
+# Regular priority worker
+BunnyFarm.config do
+  queue_name 'regular_orders'  
+  routing_key 'OrderMessage.*'
+end
+```
+
+### Geographic Routing
+
+Route messages based on regions:
+
+```ruby
+class USOrderMessage < BunnyFarm::Message
+  actions :process, :ship
+end
+
+class EUOrderMessage < BunnyFarm::Message
+  actions :process, :ship
+end
+
+# US worker
+BunnyFarm.config do
+  queue_name 'us_orders'
+  routing_key 'USOrderMessage.*'
+end
+
+# EU worker
+BunnyFarm.config do
+  queue_name 'eu_orders'
+  routing_key 'EUOrderMessage.*'
+end
+```
+
+### Load Balancing
+
+Multiple workers can consume from the same queue:
+
+```ruby
+# Worker 1
+BunnyFarm.config do
+  app_id 'worker_1'
+  queue_name 'order_processing'
+  routing_key 'OrderMessage.process'
+end
+
+# Worker 2  
+BunnyFarm.config do
+  app_id 'worker_2'
+  queue_name 'order_processing'  # Same queue
+  routing_key 'OrderMessage.process'
+end
+
+# RabbitMQ automatically load balances between workers
+```
+
+## Routing Key Introspection
+
+### Debugging Routing
+
+Check what routing key will be generated:
+
+```ruby
+class OrderMessage < BunnyFarm::Message
+  actions :process
+end
+
+message = OrderMessage.new
+routing_key = "#{message.class.name}.process"
+puts routing_key  # => "OrderMessage.process"
+```
+
+### Runtime Routing Information
+
+Access routing information during processing:
+
+```ruby
+class OrderMessage < BunnyFarm::Message
+  def process
+    puts "Processing with routing key: #{self.class.name}.process"
+    puts "Message class: #{self.class.name}"
+    puts "Action: process"
+    
+    success!
+  end
+end
+```
+
+## Error Routing
+
+### Dead Letter Queues
+
+Failed messages can be routed to error queues:
+
+```ruby
+BunnyFarm.config do
+  queue_name 'order_processing'
+  routing_key 'OrderMessage.*'
+  
+  queue_options do
+    arguments({
+      'x-dead-letter-exchange' => 'failed_messages',
+      'x-dead-letter-routing-key' => 'failed.OrderMessage'
+    })
+  end
+end
+```
+
+### Retry Queues
+
+Implement retry logic with delayed routing:
+
+```ruby
+class OrderMessage < BunnyFarm::Message
+  def process
+    begin
+      perform_processing
+      success!
+    rescue RetryableError => e
+      if retry_count < 3
+        # Publish to retry queue with delay
+        retry_message = self.class.new(@items)
+        retry_message[:retry_count] = retry_count + 1
+        retry_message.publish_delayed('process', delay: 30.seconds)
+        success!  # Don't NACK original message
+      else
+        failure("Max retries exceeded: #{e.message}")
+      end
+    end
+    
+    successful?
+  end
+  
+  private
+  
+  def retry_count
+    @items[:retry_count] || 0
+  end
+end
+```
+
+## Monitoring and Debugging
+
+### RabbitMQ Management UI
+
+Use RabbitMQ's management interface to monitor routing:
+
+1. **Exchanges tab** - See message routing statistics
+2. **Queues tab** - Monitor queue depths and consumption rates
+3. **Connections tab** - View active publishers and consumers
+
+### Routing Metrics
+
+Track routing patterns in your application:
+
+```ruby
+class OrderMessage < BunnyFarm::Message
+  def process
+    # Track routing metrics
+    Metrics.increment("message.routed.#{self.class.name}.process")
+    
+    # Your processing logic
+    perform_order_processing
+    
+    Metrics.increment("message.processed.#{self.class.name}.process")
+    success!
+  end
+end
+```
+
+### Logging Routing Events
+
+Log routing information for debugging:
+
+```ruby
+class OrderMessage < BunnyFarm::Message
+  def process
+    logger.info "Processing message",
+                routing_key: "#{self.class.name}.process",
+                message_id: @items[:order_id]
+    
+    # Processing logic
+    success!
+  end
+end
+```
+
+## Best Practices
+
+### 1. Predictable Naming
+
+Use clear, consistent class and action names:
+
+```ruby
+# Good: Clear domain and action
+class CustomerRegistrationMessage < BunnyFarm::Message
+  actions :validate_email, :create_account, :send_welcome
+end
+
+# Avoid: Vague or abbreviated names
+class CRM < BunnyFarm::Message
+  actions :val, :cr8, :snd
+end
+```
+
+### 2. Logical Grouping
+
+Group related actions in the same message class:
+
+```ruby
+# Good: Related order operations
+class OrderMessage < BunnyFarm::Message  
+  actions :validate, :process_payment, :fulfill, :ship, :complete
+end
+
+# Avoid: Mixing unrelated operations
+class MixedMessage < BunnyFarm::Message
+  actions :process_order, :send_email, :backup_database, :clean_temp_files
+end
+```
+
+### 3. Queue Design
+
+Design queues around processing capabilities:
+
+```ruby
+# Good: Separate concerns
+BunnyFarm.config do
+  case worker_type
+  when 'payment_processor'
+    routing_key '*.process_payment'
+  when 'email_sender'
+    routing_key '*.send_email'
+  when 'order_validator'
+    routing_key 'OrderMessage.validate'
+  end
+end
+```
+
+### 4. Error Handling
+
+Plan for routing errors:
+
+```ruby
+def process
+  validate_message_structure
+  return unless successful?
+  
+  perform_business_logic
+  return unless successful?
+  
+  log_success
+end
+
+private
+
+def validate_message_structure
+  required_fields = [:order_id, :customer_id, :amount]
+  missing = required_fields.select { |field| @items[field].nil? }
+  
+  failure("Missing required fields: #{missing.join(', ')}") if missing.any?
+end
+```
+
+## Next Steps
+
+Understanding smart routing enables you to:
+
+- **[Configure](../configuration/overview.md)** routing for your specific needs
+- **[Design message structures](../message-structure/overview.md)** that route effectively  
+- **[Scale your architecture](../architecture/scaling.md)** with proper queue design
+- **[Handle errors](error-handling.md)** with appropriate routing strategies

data/docs/core-features/task-scheduling.md

@@ -0,0 +1,67 @@
+# Task Scheduling
+
+BunnyFarm supports delayed message processing and task scheduling, allowing you to build sophisticated time-based workflows and recurring operations.
+
+![Task Scheduling Flow](../assets/task_scheduling_flow.svg)
+
+## Delayed Messages
+
+```ruby
+class ScheduledTask < BunnyFarm::Message
+  actions :schedule, :execute
+  
+  def schedule
+    # Schedule execution for later
+    delay_seconds = @items[:delay] || 3600  # 1 hour default
+    
+    # Use RabbitMQ delayed message plugin or custom delay queue
+    publish_delayed('execute', delay: delay_seconds)
+    success!
+  end
+  
+  def execute
+    puts "Executing scheduled task at #{Time.current}"
+    perform_scheduled_work
+    success!
+  end
+end
+```
+
+## Recurring Tasks
+
+```ruby
+def execute_recurring
+  perform_work
+  
+  # Schedule next execution
+  next_run = @items[:interval] || 3600  # 1 hour
+  self.class.new(@items).publish_delayed('execute_recurring', delay: next_run)
+  
+  success!
+end
+```
+
+## Retry Patterns
+
+```ruby
+def execute_with_retry
+  begin
+    risky_operation
+    success!
+  rescue => e
+    retry_count = (@items[:retry_count] || 0) + 1
+    
+    if retry_count < 3
+      delay = 2 ** retry_count  # Exponential backoff
+      
+      retry_msg = self.class.new(@items)
+      retry_msg[:retry_count] = retry_count
+      retry_msg.publish_delayed('execute_with_retry', delay: delay)
+      
+      success!
+    else
+      failure("Max retries exceeded: #{e.message}")
+    end
+  end
+end
+```

data/docs/core-features/workflow-support.md

@@ -0,0 +1,112 @@
+# Workflow Support
+
+BunnyFarm excels at building complex, multi-step workflows where messages can trigger subsequent operations, creating sophisticated business processes through message chaining and coordination.
+
+![Workflow Patterns](../assets/workflow_patterns.svg)
+
+## Workflow Patterns
+
+### Sequential Workflows
+
+Messages can trigger follow-up messages in sequence:
+
+```ruby
+class OrderWorkflow < BunnyFarm::Message
+  actions :start_order, :validate, :process_payment, :fulfill, :ship, :complete
+  
+  def start_order
+    # Step 1: Validate order
+    self.class.new(@items).publish('validate')
+    success!
+  end
+  
+  def validate
+    validate_order_data
+    return unless successful?
+    
+    # Step 2: Process payment
+    self.class.new(@items).publish('process_payment')
+    success!
+  end
+  
+  def process_payment
+    charge_customer
+    return unless successful?
+    
+    # Step 3: Fulfill order
+    self.class.new(@items).publish('fulfill')
+    success!
+  end
+end
+```
+
+### Conditional Workflows
+
+```ruby
+def process_order
+  validate_order
+  return unless successful?
+  
+  if @items[:requires_approval]
+    self.class.new(@items).publish('request_approval')
+  else
+    self.class.new(@items).publish('auto_process')
+  end
+  
+  success!
+end
+```
+
+### Parallel Workflows
+
+```ruby
+def start_parallel_processing
+  # Trigger multiple parallel operations
+  InventoryMessage.new(@items).publish('reserve_items')
+  PaymentMessage.new(@items).publish('authorize_payment')
+  ShippingMessage.new(@items).publish('calculate_shipping')
+  
+  success!
+end
+```
+
+## State Management
+
+### Workflow State Tracking
+
+```ruby
+class OrderWorkflow < BunnyFarm::Message
+  def initialize
+    super
+    @items[:workflow_state] = 'initialized'
+    @items[:completed_steps] = []
+  end
+  
+  def validate
+    @items[:workflow_state] = 'validating'
+    
+    perform_validation
+    
+    if successful?
+      @items[:completed_steps] << 'validate'
+      @items[:workflow_state] = 'validated'
+      trigger_next_step
+    end
+  end
+  
+  private
+  
+  def trigger_next_step
+    case @items[:workflow_state]
+    when 'validated'
+      self.class.new(@items).publish('process_payment')
+    when 'payment_processed'
+      self.class.new(@items).publish('fulfill')
+    end
+  end
+end
+```
+
+## Next Steps
+
+Workflows enable complex business processes through message orchestration.