bunny_farm 0.1.2

data/docs/assets/workflow_patterns.svg

@@ -0,0 +1,183 @@
+<svg width="1000" height="800" xmlns="http://www.w3.org/2000/svg">
+  <rect width="1000" height="800" fill="transparent"/>
+  
+  <!-- Title -->
+  <text x="500" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" font-weight="bold" fill="#e0e0e0">
+    Workflow Support: Building Complex Multi-Step Processes
+  </text>
+  
+  <!-- Sequential Workflow -->
+  <g>
+    <text x="200" y="70" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#68d391">
+      Sequential Workflow
+    </text>
+    
+    <rect x="50" y="90" width="120" height="60" rx="8" fill="#2d3748" stroke="#68d391" stroke-width="2"/>
+    <text x="110" y="115" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#68d391">1. Validate</text>
+    <text x="110" y="135" text-anchor="middle" font-family="monospace" font-size="10" fill="#e0e0e0">validate_order</text>
+    
+    <rect x="190" y="90" width="120" height="60" rx="8" fill="#2d3748" stroke="#68d391" stroke-width="2"/>
+    <text x="250" y="115" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#68d391">2. Payment</text>
+    <text x="250" y="135" text-anchor="middle" font-family="monospace" font-size="10" fill="#e0e0e0">process_payment</text>
+    
+    <rect x="330" y="90" width="120" height="60" rx="8" fill="#2d3748" stroke="#68d391" stroke-width="2"/>
+    <text x="390" y="115" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#68d391">3. Fulfill</text>
+    <text x="390" y="135" text-anchor="middle" font-family="monospace" font-size="10" fill="#e0e0e0">fulfill_order</text>
+    
+    <rect x="470" y="90" width="120" height="60" rx="8" fill="#2d3748" stroke="#68d391" stroke-width="2"/>
+    <text x="530" y="115" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#68d391">4. Ship</text>
+    <text x="530" y="135" text-anchor="middle" font-family="monospace" font-size="10" fill="#e0e0e0">ship_order</text>
+    
+    <!-- Arrows -->
+    <defs>
+      <marker id="arrow-workflow" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+        <polygon points="0 0, 10 3.5, 0 7" fill="#68d391"/>
+      </marker>
+      <marker id="arrow-conditional" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+        <polygon points="0 0, 10 3.5, 0 7" fill="#f6e05e"/>
+      </marker>
+      <marker id="arrow-parallel" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+        <polygon points="0 0, 10 3.5, 0 7" fill="#9f7aea"/>
+      </marker>
+    </defs>
+    
+    <line x1="170" y1="120" x2="190" y2="120" stroke="#68d391" stroke-width="2" marker-end="url(#arrow-workflow)"/>
+    <line x1="310" y1="120" x2="330" y2="120" stroke="#68d391" stroke-width="2" marker-end="url(#arrow-workflow)"/>
+    <line x1="450" y1="120" x2="470" y2="120" stroke="#68d391" stroke-width="2" marker-end="url(#arrow-workflow)"/>
+    
+    <!-- Code example -->
+    <rect x="50" y="170" width="540" height="120" rx="8" fill="#1a202c" stroke="#4a5568" stroke-width="1"/>
+    <text x="60" y="190" font-family="monospace" font-size="11" fill="#68d391">def start_order</text>
+    <text x="70" y="205" font-family="monospace" font-size="11" fill="#e0e0e0">self.class.new(@items).publish('validate')</text>
+    <text x="70" y="220" font-family="monospace" font-size="11" fill="#68d391">success!</text>
+    <text x="60" y="235" font-family="monospace" font-size="11" fill="#68d391">end</text>
+    <text x="250" y="190" font-family="monospace" font-size="11" fill="#68d391">def validate</text>
+    <text x="260" y="205" font-family="monospace" font-size="11" fill="#e0e0e0">validate_data</text>
+    <text x="260" y="220" font-family="monospace" font-size="11" fill="#e0e0e0">return unless successful?</text>
+    <text x="260" y="235" font-family="monospace" font-size="11" fill="#e0e0e0">self.class.new(@items).publish('process_payment')</text>
+    <text x="60" y="250" font-family="monospace" font-size="11" fill="#68d391">end</text>
+    <text x="250" y="265" font-family="monospace" font-size="11" fill="#9ca3af"># Each step triggers the next step</text>
+    <text x="250" y="280" font-family="monospace" font-size="11" fill="#9ca3af"># Chain continues until completion or failure</text>
+  </g>
+  
+  <!-- Conditional Workflow -->
+  <g>
+    <text x="200" y="330" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#f6e05e">
+      Conditional Workflow
+    </text>
+    
+    <rect x="110" y="350" width="120" height="60" rx="8" fill="#2d3748" stroke="#f6e05e" stroke-width="2"/>
+    <text x="170" y="375" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#f6e05e">Validate Order</text>
+    <text x="170" y="395" text-anchor="middle" font-family="monospace" font-size="10" fill="#e0e0e0">validate_order</text>
+    
+    <!-- Decision diamond -->
+    <polygon points="320,360 350,380 320,400 290,380" fill="#2d3748" stroke="#f6e05e" stroke-width="2"/>
+    <text x="320" y="375" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#f6e05e">Needs</text>
+    <text x="320" y="390" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#f6e05e">Approval?</text>
+    
+    <!-- Approval path -->
+    <rect x="390" y="320" width="120" height="50" rx="8" fill="#2d3748" stroke="#e53e3e" stroke-width="2"/>
+    <text x="450" y="340" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#e53e3e">Manual Review</text>
+    <text x="450" y="355" text-anchor="middle" font-family="monospace" font-size="10" fill="#e0e0e0">request_approval</text>
+    
+    <!-- Auto process path -->
+    <rect x="390" y="390" width="120" height="50" rx="8" fill="#2d3748" stroke="#68d391" stroke-width="2"/>
+    <text x="450" y="410" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#68d391">Auto Process</text>
+    <text x="450" y="425" text-anchor="middle" font-family="monospace" font-size="10" fill="#e0e0e0">auto_process</text>
+    
+    <!-- Arrows -->
+    <line x1="230" y1="380" x2="290" y2="380" stroke="#f6e05e" stroke-width="2" marker-end="url(#arrow-conditional)"/>
+    <line x1="350" y1="370" x2="390" y2="345" stroke="#e53e3e" stroke-width="2" marker-end="url(#arrow-conditional)"/>
+    <line x1="350" y1="390" x2="390" y2="415" stroke="#68d391" stroke-width="2" marker-end="url(#arrow-conditional)"/>
+    
+    <text x="365" y="365" font-family="Arial, sans-serif" font-size="10" fill="#e53e3e">YES</text>
+    <text x="365" y="405" font-family="Arial, sans-serif" font-size="10" fill="#68d391">NO</text>
+    
+    <!-- Code example -->
+    <rect x="50" y="460" width="540" height="80" rx="8" fill="#1a202c" stroke="#4a5568" stroke-width="1"/>
+    <text x="60" y="480" font-family="monospace" font-size="11" fill="#f6e05e">def process_order</text>
+    <text x="70" y="495" font-family="monospace" font-size="11" fill="#e0e0e0">if @items[:requires_approval]</text>
+    <text x="80" y="510" font-family="monospace" font-size="11" fill="#e0e0e0">self.class.new(@items).publish('request_approval')</text>
+    <text x="70" y="525" font-family="monospace" font-size="11" fill="#e0e0e0">else</text>
+    <text x="80" y="540" font-family="monospace" font-size="11" fill="#e0e0e0">self.class.new(@items).publish('auto_process')</text>
+    <text x="60" y="555" font-family="monospace" font-size="11" fill="#f6e05e">end</text>
+  </g>
+  
+  <!-- Parallel Workflow -->
+  <g>
+    <text x="750" y="70" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#9f7aea">
+      Parallel Workflow
+    </text>
+    
+    <rect x="690" y="90" width="120" height="60" rx="8" fill="#2d3748" stroke="#9f7aea" stroke-width="2"/>
+    <text x="750" y="115" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#9f7aea">Start Process</text>
+    <text x="750" y="135" text-anchor="middle" font-family="monospace" font-size="10" fill="#e0e0e0">start_parallel</text>
+    
+    <!-- Parallel operations -->
+    <rect x="600" y="180" width="100" height="50" rx="8" fill="#2d3748" stroke="#68d391" stroke-width="2"/>
+    <text x="650" y="200" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68d391">Reserve</text>
+    <text x="650" y="215" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68d391">Inventory</text>
+    
+    <rect x="720" y="180" width="100" height="50" rx="8" fill="#2d3748" stroke="#4299e1" stroke-width="2"/>
+    <text x="770" y="200" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#4299e1">Authorize</text>
+    <text x="770" y="215" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#4299e1">Payment</text>
+    
+    <rect x="840" y="180" width="100" height="50" rx="8" fill="#2d3748" stroke="#f6e05e" stroke-width="2"/>
+    <text x="890" y="200" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#f6e05e">Calculate</text>
+    <text x="890" y="215" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#f6e05e">Shipping</text>
+    
+    <!-- Convergence -->
+    <rect x="720" y="260" width="100" height="50" rx="8" fill="#2d3748" stroke="#e53e3e" stroke-width="2"/>
+    <text x="770" y="280" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#e53e3e">Complete</text>
+    <text x="770" y="295" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#e53e3e">Order</text>
+    
+    <!-- Arrows -->
+    <line x1="720" y1="150" x2="650" y2="180" stroke="#9f7aea" stroke-width="2" marker-end="url(#arrow-parallel)"/>
+    <line x1="750" y1="150" x2="770" y2="180" stroke="#9f7aea" stroke-width="2" marker-end="url(#arrow-parallel)"/>
+    <line x1="780" y1="150" x2="890" y2="180" stroke="#9f7aea" stroke-width="2" marker-end="url(#arrow-parallel)"/>
+    
+    <line x1="650" y1="230" x2="720" y2="270" stroke="#9f7aea" stroke-width="2" marker-end="url(#arrow-parallel)"/>
+    <line x1="770" y1="230" x2="770" y2="260" stroke="#9f7aea" stroke-width="2" marker-end="url(#arrow-parallel)"/>
+    <line x1="890" y1="230" x2="820" y2="270" stroke="#9f7aea" stroke-width="2" marker-end="url(#arrow-parallel)"/>
+    
+    <!-- Code example -->
+    <rect x="630" y="330" width="340" height="120" rx="8" fill="#1a202c" stroke="#4a5568" stroke-width="1"/>
+    <text x="640" y="350" font-family="monospace" font-size="11" fill="#9f7aea">def start_parallel_processing</text>
+    <text x="650" y="365" font-family="monospace" font-size="11" fill="#9ca3af"># Trigger multiple parallel operations</text>
+    <text x="650" y="380" font-family="monospace" font-size="11" fill="#e0e0e0">InventoryMessage.new(@items).publish('reserve_items')</text>
+    <text x="650" y="395" font-family="monospace" font-size="11" fill="#e0e0e0">PaymentMessage.new(@items).publish('authorize_payment')</text>
+    <text x="650" y="410" font-family="monospace" font-size="11" fill="#e0e0e0">ShippingMessage.new(@items).publish('calculate_shipping')</text>
+    <text x="650" y="425" font-family="monospace" font-size="11" fill="#68d391">success!</text>
+    <text x="640" y="440" font-family="monospace" font-size="11" fill="#9f7aea">end</text>
+  </g>
+  
+  <!-- State Tracking -->
+  <g>
+    <text x="200" y="590" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#e0e0e0">
+      Workflow State Management
+    </text>
+    
+    <rect x="50" y="610" width="300" height="140" rx="8" fill="#2d3748" stroke="#4a5568" stroke-width="2"/>
+    <text x="200" y="635" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#e0e0e0">State Tracking</text>
+    
+    <text x="60" y="655" font-family="monospace" font-size="10" fill="#e0e0e0">@items[:workflow_state] = 'initialized'</text>
+    <text x="60" y="670" font-family="monospace" font-size="10" fill="#e0e0e0">@items[:completed_steps] = []</text>
+    <text x="60" y="685" font-family="monospace" font-size="10" fill="#e0e0e0">@items[:current_step] = 'validate'</text>
+    <text x="60" y="700" font-family="monospace" font-size="10" fill="#e0e0e0">@items[:started_at] = Time.current</text>
+    <text x="60" y="715" font-family="monospace" font-size="10" fill="#e0e0e0">@items[:retry_count] = 0</text>
+    <text x="60" y="730" font-family="monospace" font-size="10" fill="#e0e0e0">@items[:error_history] = []</text>
+    <text x="60" y="745" font-family="monospace" font-size="10" fill="#e0e0e0">@items[:metadata] = {...}</text>
+    
+    <!-- Benefits -->
+    <rect x="370" y="610" width="300" height="140" rx="8" fill="#2d3748" stroke="#68d391" stroke-width="2"/>
+    <text x="520" y="635" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#68d391">Workflow Benefits</text>
+    
+    <text x="380" y="655" font-family="Arial, sans-serif" font-size="11" fill="#e0e0e0">✅ Complex business processes</text>
+    <text x="380" y="670" font-family="Arial, sans-serif" font-size="11" fill="#e0e0e0">✅ Step-by-step execution</text>
+    <text x="380" y="685" font-family="Arial, sans-serif" font-size="11" fill="#e0e0e0">✅ Error recovery at any step</text>
+    <text x="380" y="700" font-family="Arial, sans-serif" font-size="11" fill="#e0e0e0">✅ Parallel processing support</text>
+    <text x="380" y="715" font-family="Arial, sans-serif" font-size="11" fill="#e0e0e0">✅ State persistence</text>
+    <text x="380" y="730" font-family="Arial, sans-serif" font-size="11" fill="#e0e0e0">✅ Audit trail</text>
+    <text x="380" y="745" font-family="Arial, sans-serif" font-size="11" fill="#e0e0e0">✅ Conditional branching</text>
+  </g>
+</svg>

data/docs/assets/yaml_config_structure.svg

@@ -0,0 +1,72 @@
+<svg width="800" height="600" xmlns="http://www.w3.org/2000/svg">
+  <rect width="800" height="600" fill="transparent"/>
+  
+  <!-- Title -->
+  <text x="400" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#e0e0e0">
+    YAML Configuration Structure
+  </text>
+  
+  <!-- Configuration File Example -->
+  <g>
+    <text x="400" y="70" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#4299e1">
+      bunny_farm.yml Structure
+    </text>
+    
+    <rect x="50" y="90" width="700" height="320" rx="8" fill="#2d3748" stroke="#4299e1" stroke-width="2"/>
+    <text x="400" y="115" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#4299e1">Complete Configuration Example</text>
+    
+    <!-- RabbitMQ Section -->
+    <text x="70" y="140" font-family="monospace" font-size="11" fill="#68d391"># RabbitMQ Connection Settings</text>
+    <text x="70" y="155" font-family="monospace" font-size="11" fill="#f6e05e">rabbitmq:</text>
+    <text x="90" y="170" font-family="monospace" font-size="11" fill="#e0e0e0">url: "amqp://localhost:5672"</text>
+    <text x="90" y="185" font-family="monospace" font-size="11" fill="#e0e0e0">username: "bunny_user"</text>
+    <text x="90" y="200" font-family="monospace" font-size="11" fill="#e0e0e0">password: "bunny_pass"</text>
+    <text x="90" y="215" font-family="monospace" font-size="11" fill="#e0e0e0">vhost: "/production"</text>
+    
+    <!-- Exchange Section -->
+    <text x="70" y="240" font-family="monospace" font-size="11" fill="#68d391"># Message Routing</text>
+    <text x="70" y="255" font-family="monospace" font-size="11" fill="#f6e05e">exchange:</text>
+    <text x="90" y="270" font-family="monospace" font-size="11" fill="#e0e0e0">name: "bunny_farm_production"</text>
+    <text x="90" y="285" font-family="monospace" font-size="11" fill="#e0e0e0">type: "topic"</text>
+    <text x="90" y="300" font-family="monospace" font-size="11" fill="#e0e0e0">durable: true</text>
+    
+    <!-- Error Handling -->
+    <text x="70" y="325" font-family="monospace" font-size="11" fill="#68d391"># Error Handling</text>
+    <text x="70" y="340" font-family="monospace" font-size="11" fill="#f6e05e">retry:</text>
+    <text x="90" y="355" font-family="monospace" font-size="11" fill="#e0e0e0">max_attempts: 5</text>
+    <text x="90" y="370" font-family="monospace" font-size="11" fill="#e0e0e0">backoff: "exponential"</text>
+    <text x="90" y="385" font-family="monospace" font-size="11" fill="#e0e0e0">initial_delay: 2</text>
+    <text x="70" y="400" font-family="monospace" font-size="11" fill="#f6e05e">dead_letter_queue: "failed_messages"</text>
+  </g>
+  
+  <!-- Environment-Specific Configs -->
+  <g>
+    <text x="400" y="450" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#e0e0e0">
+      Environment-Specific Configuration
+    </text>
+    
+    <!-- Development -->
+    <rect x="50" y="470" width="220" height="100" rx="6" fill="#1a202c" stroke="#68d391" stroke-width="1"/>
+    <text x="160" y="490" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#68d391">development.yml</text>
+    <text x="60" y="510" font-family="monospace" font-size="10" fill="#e0e0e0">rabbitmq:</text>
+    <text x="70" y="525" font-family="monospace" font-size="10" fill="#e0e0e0">url: "amqp://localhost:5672"</text>
+    <text x="60" y="540" font-family="monospace" font-size="10" fill="#e0e0e0">exchange:</text>
+    <text x="70" y="555" font-family="monospace" font-size="10" fill="#e0e0e0">name: "bunny_farm_dev"</text>
+    
+    <!-- Testing -->
+    <rect x="290" y="470" width="220" height="100" rx="6" fill="#1a202c" stroke="#f6e05e" stroke-width="1"/>
+    <text x="400" y="490" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#f6e05e">test.yml</text>
+    <text x="300" y="510" font-family="monospace" font-size="10" fill="#e0e0e0">rabbitmq:</text>
+    <text x="310" y="525" font-family="monospace" font-size="10" fill="#e0e0e0">url: "amqp://test:5672"</text>
+    <text x="300" y="540" font-family="monospace" font-size="10" fill="#e0e0e0">exchange:</text>
+    <text x="310" y="555" font-family="monospace" font-size="10" fill="#e0e0e0">name: "bunny_farm_test"</text>
+    
+    <!-- Production -->
+    <rect x="530" y="470" width="220" height="100" rx="6" fill="#1a202c" stroke="#e53e3e" stroke-width="1"/>
+    <text x="640" y="490" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#e53e3e">production.yml</text>
+    <text x="540" y="510" font-family="monospace" font-size="10" fill="#e0e0e0">rabbitmq:</text>
+    <text x="550" y="525" font-family="monospace" font-size="10" fill="#e0e0e0">url: "amqp://prod:5672"</text>
+    <text x="540" y="540" font-family="monospace" font-size="10" fill="#e0e0e0">exchange:</text>
+    <text x="550" y="555" font-family="monospace" font-size="10" fill="#e0e0e0">name: "bunny_farm_prod"</text>
+  </g>
+</svg>

data/docs/configuration/environment-variables.md

@@ -0,0 +1,14 @@
+# Environment Variables
+
+Complete reference for BunnyFarm environment variables.
+
+## Connection Variables
+- `AMQP_HOST` - RabbitMQ hostname
+- `AMQP_PORT` - Connection port
+- `AMQP_USER` - Username
+- `AMQP_PASS` - Password
+
+## Message Routing
+- `AMQP_EXCHANGE` - Exchange name
+- `AMQP_QUEUE` - Queue name
+- `AMQP_ROUTING_KEY` - Routing key pattern

data/docs/configuration/overview.md

@@ -0,0 +1,373 @@
+# Configuration Overview
+
+BunnyFarm provides flexible configuration options to suit different environments and deployment scenarios. This guide covers all available configuration methods and options.
+
+<img src="../assets/configuration_flow.svg" alt="Configuration Flow" width="100%">
+
+## Configuration Methods
+
+BunnyFarm supports multiple configuration approaches that follow a clear priority hierarchy:
+
+1. **Built-in defaults** - Safe defaults for development
+2. **YAML configuration files** - Environment-specific settings
+3. **Environment variables** - Runtime configuration
+4. **Programmatic configuration** - Code-based overrides
+
+Later configurations override earlier ones, giving you maximum flexibility.
+
+## Environment Variables
+
+The simplest way to configure BunnyFarm is through environment variables:
+
+```bash
+# Connection settings
+export AMQP_HOST=localhost
+export AMQP_VHOST=/
+export AMQP_PORT=5672
+export AMQP_USER=guest
+export AMQP_PASS=guest
+
+# Message routing
+export AMQP_EXCHANGE=my_exchange
+export AMQP_QUEUE=my_queue
+export AMQP_ROUTING_KEY='#'
+
+# Application identity
+export AMQP_APP_NAME=my_app
+```
+
+## Programmatic Configuration
+
+Configure BunnyFarm directly in your Ruby code:
+
+```ruby
+BunnyFarm.config do
+  env 'production'
+  app_id 'order_processor'
+  bunny_file 'config/rabbitmq.yml.erb'
+end
+```
+
+### Available Options
+
+#### Basic Configuration
+```ruby
+BunnyFarm.config do
+  app_id 'my_application'        # Application identifier
+  env 'production'               # Environment name  
+end
+```
+
+#### File-based Configuration
+```ruby
+BunnyFarm.config do
+  bunny_file 'config/custom.yml' # Custom config file path
+end
+```
+
+## YAML Configuration
+
+Use YAML files for environment-specific configuration with ERB support:
+
+**config/bunny.yml.erb:**
+```yaml
+defaults: &defaults
+  host: <%= ENV['AMQP_HOST'] || 'localhost' %>
+  vhost: <%= ENV['AMQP_VHOST'] || '/' %>
+  port: <%= (ENV['AMQP_PORT'] || 5672).to_i %>
+  user: <%= ENV['AMQP_USER'] || 'guest' %>
+  pass: <%= ENV['AMQP_PASS'] || 'guest' %>
+  exchange_name: <%= ENV['AMQP_EXCHANGE'] || 'my_exchange' %>
+  queue_name: <%= ENV['AMQP_QUEUE'] || 'my_queue' %>
+  routing_key: <%= ENV['AMQP_ROUTING_KEY'] || '#' %>
+  app_name: <%= ENV['AMQP_APP_NAME'] || 'bunny_farm_job' %>
+
+development:
+  <<: *defaults
+
+test:
+  <<: *defaults
+  exchange_name: test_exchange
+  queue_name: test_queue
+
+production:
+  <<: *defaults
+  host: amqp.production.com
+  exchange_name: prod_exchange
+```
+
+## Configuration Parameters
+
+### Connection Parameters
+
+| Parameter | Environment Variable | Description | Default |
+|-----------|---------------------|-------------|---------|
+| `host` | `AMQP_HOST` | RabbitMQ server hostname | `localhost` |
+| `vhost` | `AMQP_VHOST` | Virtual host | `/` |
+| `port` | `AMQP_PORT` | Connection port | `5672` |
+| `user` | `AMQP_USER` | Username | `guest` |
+| `pass` | `AMQP_PASS` | Password | `guest` |
+
+### Message Routing Parameters
+
+| Parameter | Environment Variable | Description | Default |
+|-----------|---------------------|-------------|---------|
+| `exchange_name` | `AMQP_EXCHANGE` | Exchange name | `bunny_farm_exchange` |
+| `queue_name` | `AMQP_QUEUE` | Queue name | `bunny_farm_queue` |
+| `routing_key` | `AMQP_ROUTING_KEY` | Routing key pattern | `#` |
+
+### Application Parameters
+
+| Parameter | Environment Variable | Description | Default |
+|-----------|---------------------|-------------|---------|
+| `app_name` | `AMQP_APP_NAME` | Application name | `bunny_farm_app` |
+
+## Environment-Specific Configuration
+
+### Development Configuration
+```ruby
+# config/environments/development.rb
+BunnyFarm.config do
+  env 'development'
+  # Uses local RabbitMQ with default settings
+end
+```
+
+### Production Configuration
+```ruby
+# config/environments/production.rb  
+BunnyFarm.config do
+  env 'production'
+  bunny_file Rails.root.join('config', 'rabbitmq.yml.erb')
+end
+```
+
+### Test Configuration
+```ruby
+# config/environments/test.rb
+BunnyFarm.config do
+  env 'test'
+  app_id 'test_suite'
+end
+```
+
+## Common Configuration Patterns
+
+### Docker Configuration
+```bash
+# docker-compose.yml environment section
+environment:
+  - AMQP_HOST=rabbitmq
+  - AMQP_EXCHANGE=app_exchange
+  - AMQP_QUEUE=app_queue
+  - AMQP_USER=app_user
+  - AMQP_PASS=secret_password
+```
+
+### Kubernetes Configuration
+```yaml
+# k8s-configmap.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: bunny-farm-config
+data:
+  AMQP_HOST: "rabbitmq-service"
+  AMQP_EXCHANGE: "production_exchange"
+  AMQP_QUEUE: "production_queue"
+```
+
+### Cloud Configuration
+```ruby
+# For cloud RabbitMQ services
+BunnyFarm.config do
+  case ENV['RAILS_ENV']
+  when 'production'
+    # Use CloudAMQP URL
+    connection_string ENV['CLOUDAMQP_URL']
+  when 'staging'  
+    connection_string ENV['STAGING_AMQP_URL']
+  end
+end
+```
+
+## Advanced Configuration
+
+### Connection Options
+```ruby
+BunnyFarm.config do
+  connection_options do
+    heartbeat 30
+    connection_timeout 10
+    read_timeout 30
+    write_timeout 30
+  end
+end
+```
+
+### Exchange Options
+```ruby
+BunnyFarm.config do
+  exchange_options do
+    durable true
+    auto_delete false
+    type :topic
+  end
+end
+```
+
+### Queue Options  
+```ruby
+BunnyFarm.config do
+  queue_options do
+    durable true
+    auto_delete false
+    exclusive false
+    arguments({
+      'x-message-ttl' => 60000,
+      'x-max-length' => 1000
+    })
+  end
+end
+```
+
+### Message Options
+```ruby
+BunnyFarm.config do
+  message_options do
+    persistent true
+    mandatory false
+    immediate false
+  end
+end
+```
+
+## Configuration Validation
+
+BunnyFarm validates configuration at startup:
+
+```ruby
+begin
+  BunnyFarm.config do
+    host 'invalid-host'
+    port 'invalid-port'
+  end
+rescue BunnyFarm::ConfigurationError => e
+  puts "Configuration error: #{e.message}"
+end
+```
+
+## Best Practices
+
+### 1. Use Environment Variables for Secrets
+```ruby
+# Good: Use environment variables for sensitive data
+BunnyFarm.config do
+  user ENV['RABBITMQ_USER']
+  pass ENV['RABBITMQ_PASSWORD']
+end
+
+# Avoid: Hard-coding secrets
+BunnyFarm.config do
+  user 'admin'
+  pass 'secret123' # Don't do this!
+end
+```
+
+### 2. Environment-Specific Configuration
+```ruby
+# config/application.rb
+case Rails.env
+when 'development'
+  BunnyFarm.config { env 'development' }
+when 'test'
+  BunnyFarm.config { env 'test' }  
+when 'production'
+  BunnyFarm.config do
+    env 'production'
+    bunny_file 'config/production_rabbitmq.yml'
+  end
+end
+```
+
+### 3. Connection Pooling for High Load
+```ruby
+BunnyFarm.config do
+  connection_pool_size 10
+  channel_pool_size 50
+end
+```
+
+### 4. Monitoring Configuration
+```ruby
+BunnyFarm.config do
+  # Enable detailed logging
+  log_level :info
+  
+  # Health check endpoint
+  health_check_enabled true
+  health_check_port 8080
+end
+```
+
+## Configuration Debugging
+
+### Check Current Configuration
+```ruby
+# In Rails console or Ruby script
+puts BunnyFarm.current_config.inspect
+```
+
+### Test Connection
+```ruby
+# Verify connection works
+BunnyFarm.test_connection
+```
+
+### Configuration Validation
+```ruby
+# Validate configuration without connecting
+BunnyFarm.validate_config
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Connection Refused
+```
+Error: Connection refused - connect(2)
+```
+
+**Solutions:**
+- Verify RabbitMQ is running: `systemctl status rabbitmq-server`
+- Check host and port configuration
+- Verify firewall settings
+
+#### Authentication Failed  
+```
+Error: ACCESS_REFUSED - Login was refused
+```
+
+**Solutions:**
+- Verify username and password
+- Check user permissions in RabbitMQ
+- Ensure virtual host exists and user has access
+
+#### Exchange/Queue Not Found
+```
+Error: NOT_FOUND - no exchange 'my_exchange'
+```
+
+**Solutions:**
+- Create exchange and queue manually
+- Enable auto-creation in configuration
+- Check exchange/queue names for typos
+
+## Next Steps
+
+With configuration mastered, explore:
+
+- **[Environment Variables](environment-variables.md)** - Complete environment variable reference
+- **[YAML Configuration](yaml-configuration.md)** - Advanced YAML configuration patterns
+- **[Programmatic Setup](programmatic-setup.md)** - Dynamic configuration scenarios

data/docs/configuration/programmatic-setup.md

@@ -0,0 +1,10 @@
+# Programmatic Setup
+
+Configuring BunnyFarm through Ruby code.
+
+```ruby
+BunnyFarm.config do
+  host 'amqp.example.com'
+  port 5672
+end
+```