bunny_farm 0.1.2

data/docs/getting-started/basic-concepts.md

@@ -0,0 +1,274 @@
+# Basic Concepts
+
+Understanding BunnyFarm's core concepts will help you design effective message-driven applications. This guide covers the fundamental principles behind BunnyFarm's architecture.
+
+## Message-Centric Architecture
+
+BunnyFarm is built around the concept of **messages as living entities**. Unlike traditional job queues where jobs are simple data structures, BunnyFarm messages are full Ruby classes that encapsulate both data and behavior.
+
+![Message Encapsulation](../assets/message_encapsulation.svg)
+
+```ruby
+class OrderMessage < BunnyFarm::Message
+  # Data structure
+  fields :order_id, :customer_email, :items
+  
+  # Behavior
+  actions :process, :ship, :cancel
+  
+  def process
+    validate_order
+    charge_payment
+    update_inventory
+    success!
+  end
+end
+```
+
+## Core Components
+
+### 1. Message Classes
+
+Message classes inherit from `BunnyFarm::Message` and define:
+
+- **Fields**: The data structure using the `fields` DSL
+- **Actions**: Available operations using the `actions` DSL  
+- **Methods**: Business logic for each action
+
+### 2. Routing Keys
+
+BunnyFarm uses a predictable routing pattern:
+
+```
+MessageClassName.action
+```
+
+Examples:
+- `OrderMessage.process`
+- `EmailMessage.send`
+- `ReportMessage.generate`
+
+This makes routing transparent and debuggable.
+
+![Smart Routing](../assets/smart_routing_diagram.svg)
+
+### 3. JSON Serialization
+
+All message data is serialized as JSON for:
+- **Human readability** - Easy debugging and monitoring
+- **Language interoperability** - Other systems can read/write messages
+- **Simplicity** - No complex binary protocols
+
+![JSON Serialization](../assets/json_serialization_flow.svg)
+
+## Message Lifecycle
+
+![Message Lifecycle](../assets/message_lifecycle.svg)
+
+1. **Creation**: Message instance is created with data
+2. **Publishing**: Message is serialized to JSON and sent to RabbitMQ
+3. **Routing**: RabbitMQ routes based on the routing key
+4. **Consumption**: Worker receives and deserializes the message
+5. **Processing**: The appropriate action method is called
+6. **Acknowledgment**: Success/failure determines ACK/NACK
+
+## Fields DSL
+
+The `fields` DSL defines the expected data structure:
+
+```ruby
+class CustomerMessage < BunnyFarm::Message
+  fields :name, :email, 
+         { address: [:street, :city, :state, :zip] },
+         { preferences: [:newsletter, :promotions] }
+end
+```
+
+This creates:
+- Simple fields: `name`, `email`
+- Nested objects: `address` with sub-fields
+- Arrays: `preferences` as a list
+
+## Actions DSL
+
+The `actions` DSL defines available operations:
+
+```ruby
+class OrderMessage < BunnyFarm::Message
+  actions :validate, :process, :ship, :cancel, :refund
+  
+  def validate
+    # Validation logic
+  end
+  
+  def process
+    # Processing logic  
+  end
+  
+  # ... other action methods
+end
+```
+
+Each action becomes a routable endpoint.
+
+## Data Access
+
+BunnyFarm provides hash-like access to message data:
+
+```ruby
+message = CustomerMessage.new
+
+# Setting data
+message[:name] = "John Doe"
+message[:email] = "john@example.com"
+message[:address] = {
+  street: "123 Main St",
+  city: "Boston", 
+  state: "MA",
+  zip: "02101"
+}
+
+# Getting data
+puts message[:name]           # "John Doe"
+puts message[:address][:city] # "Boston"
+```
+
+## State Management
+
+Messages track their processing state:
+
+```ruby
+def process_order
+  validate_payment
+  
+  if payment_valid?
+    charge_customer
+    success!  # Mark as successful
+  else
+    failure("Invalid payment method")
+  end
+  
+  successful? # Returns true/false for ACK/NACK
+end
+```
+
+State methods:
+- `success!` - Mark operation as successful
+- `failure(message)` - Mark operation as failed with reason
+- `successful?` - Check if operation succeeded
+- `failed?` - Check if operation failed
+- `errors` - Array of error messages
+
+## Configuration Patterns
+
+BunnyFarm supports multiple configuration approaches:
+
+### Environment Variables
+```bash
+export AMQP_HOST=localhost
+export AMQP_EXCHANGE=my_exchange
+export AMQP_QUEUE=my_queue
+```
+
+### Programmatic Configuration
+```ruby
+BunnyFarm.config do
+  env 'production'
+  app_id 'order_processor'
+  bunny_file 'config/rabbitmq.yml'
+end
+```
+
+### YAML Configuration
+```yaml
+production:
+  host: amqp.example.com
+  exchange_name: orders
+  queue_name: order_processing
+```
+
+## Error Handling
+
+BunnyFarm provides built-in error handling:
+
+```ruby
+def risky_operation
+  begin
+    perform_external_api_call
+    success!
+  rescue ExternalAPIError => e
+    failure("API call failed: #{e.message}")
+  rescue StandardError => e
+    failure("Unexpected error: #{e.message}")
+  end
+  
+  successful?
+end
+```
+
+Failed messages can be:
+- Retried automatically (RabbitMQ feature)
+- Sent to dead letter queues
+- Logged for manual inspection
+
+## Best Practices
+
+### 1. Keep Actions Focused
+Each action should have a single responsibility:
+
+```ruby
+# Good
+actions :validate, :process, :ship
+
+# Avoid
+actions :validate_and_process_and_ship
+```
+
+### 2. Use Meaningful Names
+Choose descriptive names for clarity:
+
+```ruby
+# Good
+class OrderProcessingMessage
+  actions :validate_payment, :update_inventory
+
+# Better than
+class OrderMessage  
+  actions :do_stuff, :handle
+```
+
+### 3. Handle Errors Gracefully
+Always use proper error handling:
+
+```ruby
+def process
+  validate_data
+  return unless successful?
+  
+  perform_work
+  return unless successful?
+  
+  finalize
+end
+```
+
+### 4. Design for Idempotency
+Make operations safe to retry:
+
+```ruby
+def charge_payment
+  return if payment_already_charged?
+  
+  # Perform charge
+  success!
+end
+```
+
+## Next Steps
+
+With these concepts in mind, you're ready to explore:
+
+- **[Message Structure](../message-structure/overview.md)** - Deep dive into Fields and Actions DSL
+- **[Configuration](../configuration/overview.md)** - Advanced configuration options  
+- **[Examples](../examples/overview.md)** - Real-world usage patterns
+- **[API Reference](../api/message-class.md)** - Complete API documentation

data/docs/getting-started/installation.md

@@ -0,0 +1,122 @@
+# Installation
+
+BunnyFarm is distributed as a Ruby gem and can be installed using bundler or gem directly.
+
+## Requirements
+
+Before installing BunnyFarm, ensure you have:
+
+- **Ruby 2.5 or higher** - BunnyFarm supports modern Ruby versions
+- **RabbitMQ server** - Either local installation or cloud service
+- **Bundler** - For dependency management
+
+## Installing BunnyFarm
+
+### Using Bundler (Recommended)
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'bunny_farm'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+### Using Gem Directly
+
+Install it yourself as:
+
+```bash
+gem install bunny_farm
+```
+
+## Setting up RabbitMQ
+
+### Local Installation
+
+#### macOS (using Homebrew)
+
+```bash
+# Install RabbitMQ
+brew install rabbitmq
+
+# Start RabbitMQ server
+brew services start rabbitmq
+
+# Enable management plugin (optional but recommended)
+rabbitmq-plugins enable rabbitmq_management
+```
+
+#### Ubuntu/Debian
+
+```bash
+# Install RabbitMQ
+sudo apt-get update
+sudo apt-get install rabbitmq-server
+
+# Start RabbitMQ server
+sudo systemctl start rabbitmq-server
+sudo systemctl enable rabbitmq-server
+
+# Enable management plugin
+sudo rabbitmq-plugins enable rabbitmq_management
+```
+
+#### Docker
+
+```bash
+# Run RabbitMQ with management plugin
+docker run -d \
+  --name rabbitmq \
+  -p 5672:5672 \
+  -p 15672:15672 \
+  rabbitmq:3-management
+```
+
+### Cloud Services
+
+BunnyFarm works with cloud RabbitMQ services:
+
+- **CloudAMQP** - Managed RabbitMQ service
+- **Amazon MQ** - AWS managed message broker
+- **Google Cloud Pub/Sub** - With AMQP support
+- **Azure Service Bus** - With AMQP 1.0 support
+
+## Verification
+
+Verify your installation by checking if BunnyFarm loads correctly:
+
+```ruby
+require 'bunny_farm'
+puts BunnyFarm::VERSION
+```
+
+You should see the version number output without any errors.
+
+## Environment Setup
+
+Set up your environment variables for development:
+
+```bash
+export AMQP_HOST=localhost
+export AMQP_VHOST=/
+export AMQP_PORT=5672
+export AMQP_USER=guest
+export AMQP_PASS=guest
+export AMQP_EXCHANGE=bunny_farm_exchange
+export AMQP_QUEUE=bunny_farm_queue
+export AMQP_ROUTING_KEY='#'
+export AMQP_APP_NAME=my_bunny_farm_app
+```
+
+## Next Steps
+
+With BunnyFarm installed and RabbitMQ running, you're ready to:
+
+1. **[Quick Start Guide](quick-start.md)** - Get your first message processing in 5 minutes
+2. **[Basic Concepts](basic-concepts.md)** - Understand BunnyFarm's core concepts
+3. **[Configuration](../configuration/overview.md)** - Learn about configuration options

data/docs/getting-started/quick-start.md

@@ -0,0 +1,158 @@
+# Quick Start
+
+This guide will get you up and running with BunnyFarm in just a few minutes. We'll create a simple message class, publish a message, and process it.
+
+## Prerequisites
+
+Before starting, make sure you have:
+
+- [BunnyFarm installed](installation.md)
+- RabbitMQ server running locally or accessible remotely
+- Basic familiarity with Ruby
+
+## Step 1: Create Your First Message Class
+
+Create a file called `greeting_message.rb`:
+
+```ruby
+require 'bunny_farm'
+
+class GreetingMessage < BunnyFarm::Message
+  # Define the fields this message expects
+  fields :name, :language
+  
+  # Define the actions this message can perform
+  actions :send_greeting
+  
+  def send_greeting
+    puts "Hello #{@items[:name]}! (in #{@items[:language]})"
+    
+    # Mark the message as successfully processed
+    success!
+    
+    # Return true to ACK the message
+    successful?
+  end
+end
+```
+
+## Step 2: Configure BunnyFarm
+
+Create a simple configuration (or use environment variables):
+
+```ruby
+# Basic configuration using defaults
+BunnyFarm.config do
+  app_id 'greeting_app'
+end
+```
+
+## Step 3: Publish a Message
+
+Create a file called `publisher.rb`:
+
+```ruby
+require_relative 'greeting_message'
+
+# Configure BunnyFarm
+BunnyFarm.config do
+  app_id 'greeting_publisher'
+end
+
+# Create a new message
+message = GreetingMessage.new
+
+# Set the message data
+message[:name] = 'Alice'
+message[:language] = 'English'
+
+# Publish the message with the 'send_greeting' action
+message.publish('send_greeting')
+
+if message.successful?
+  puts "Message published successfully!"
+else
+  puts "Failed to publish message: #{message.errors.join(', ')}"
+end
+```
+
+## Step 4: Create a Consumer
+
+Create a file called `consumer.rb`:
+
+```ruby
+require_relative 'greeting_message'
+
+# Configure BunnyFarm
+BunnyFarm.config do
+  app_id 'greeting_consumer'
+end
+
+puts "Starting message consumer..."
+puts "Press Ctrl+C to stop"
+
+# Start processing messages (this will block)
+BunnyFarm.manage
+```
+
+## Step 5: Run the Example
+
+1. **Start the consumer** (in one terminal):
+   ```bash
+   ruby consumer.rb
+   ```
+
+2. **Publish a message** (in another terminal):
+   ```bash
+   ruby publisher.rb
+   ```
+
+You should see output like:
+
+**Consumer terminal:**
+```
+Starting message consumer...
+Press Ctrl+C to stop
+Hello Alice! (in English)
+```
+
+**Publisher terminal:**
+```
+Message published successfully!
+```
+
+## Understanding What Happened
+
+1. **Message Class**: `GreetingMessage` defines the structure and behavior
+2. **Fields DSL**: `fields :name, :language` specifies expected data
+3. **Actions DSL**: `actions :send_greeting` defines available operations
+4. **Routing Key**: The message was routed using `GreetingMessage.send_greeting`
+5. **JSON Serialization**: Data was automatically serialized/deserialized
+6. **AMQP Flow**: Message traveled through RabbitMQ from publisher to consumer
+
+## Next Steps
+
+Now that you have a basic understanding, explore:
+
+- **[Basic Concepts](basic-concepts.md)** - Understand BunnyFarm's architecture
+- **[Message Structure](../message-structure/overview.md)** - Learn about the Fields and Actions DSL
+- **[Configuration Options](../configuration/overview.md)** - Advanced configuration
+- **[Examples](../examples/overview.md)** - More comprehensive examples
+
+## Common Issues
+
+### Connection Refused
+If you see connection errors, ensure RabbitMQ is running:
+```bash
+# Check RabbitMQ status
+sudo systemctl status rabbitmq-server
+
+# Or for Docker
+docker ps | grep rabbitmq
+```
+
+### Permission Denied
+Make sure your AMQP credentials are correct in your environment variables or configuration.
+
+### Messages Not Processing
+Verify that your consumer is listening to the correct queue and routing key configuration.

data/docs/index.md

@@ -0,0 +1,106 @@
+# BunnyFarm
+
+<div align="center">
+  <img src="assets/bunny_farm_logo.png" alt="BunnyFarm - Lightweight AMQP Job Manager" width="400">
+  <br />
+  <p>
+    <a href="https://badge.fury.io/rb/bunny_farm"><img src="https://badge.fury.io/rb/bunny_farm.svg" alt="Gem Version" /></a>
+    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+  </p>
+</div>
+
+Like a well-organized farm where messages hop efficiently from producers to consumers, BunnyFarm provides a lightweight Ruby gem for managing background jobs using RabbitMQ. Each message becomes a living entity with its own behavior, routing intelligently through the message broker to the right workers.
+
+## What is BunnyFarm?
+
+The bunny farm is an abstraction in which the messages are encapsulated as classes. Instances of these BunnyFarm::Messages are hopping around the RabbitMQ as JSON strings with routing keys in the form of `MessageClassName.action` where action is a method on the MessageClassName instance.
+
+## Key Features
+
+- **🐰 [Message-Centric Design](core-features/message-design.md)** - Classes encapsulate behavior and data
+- **🔀 [Smart Routing](core-features/smart-routing.md)** - Automatic routing with ClassName.action keys
+- **📨 [JSON Serialization](core-features/json-serialization.md)** - Simple, readable message format
+- **⚙️ [Flexible Configuration](core-features/configuration.md)** - Environment, YAML, or programmatic setup
+- **🔄 [Workflow Support](core-features/workflow-support.md)** - Multi-step processes with message chaining
+- **⏰ [Task Scheduling](core-features/task-scheduling.md)** - Delayed execution with retry logic
+- **🛡️ [Error Handling](core-features/error-handling.md)** - Built-in success/failure tracking
+- **🎯 Simplicity First** - K.I.S.S. design philosophy
+
+## Architecture Overview
+
+BunnyFarm provides a clean, layered architecture that separates concerns and enables scalable message processing:
+
+<img src="assets/architecture_overview.svg" alt="Architecture Overview" width="100%">
+
+The architecture consists of four main layers:
+
+1. **Ruby Application Layer** - Your web apps, API servers, schedulers, and worker processes
+2. **BunnyFarm Library Layer** - Core components including Message classes, Publisher, Consumer, Config, and Router
+3. **RabbitMQ Message Broker** - Handles message routing, queuing, and delivery with exchanges and queues
+4. **Persistence & External Services** - Databases, email services, file storage, APIs, and caching layers
+
+## Quick Start
+
+Get up and running with BunnyFarm in minutes:
+
+### Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'bunny_farm'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+### Basic Usage
+
+```ruby
+require 'bunny_farm'
+require 'my_message_class'
+
+# Configure BunnyFarm
+BunnyFarm.config
+
+# Start processing messages (blocks)
+BunnyFarm.manage
+```
+
+### Publishing Messages
+
+```ruby
+require 'bunny_farm'
+
+BunnyFarm.config do
+  app_id 'my_job_name'
+end
+
+# Create and publish a message
+message = MyMessageClass.new
+message[:field1] = 'Hello'
+message[:field2] = 'World'
+message.publish('action') # routing key: MyMessageClass.action
+
+puts 'Success!' if message.successful?
+```
+
+## Why BunnyFarm?
+
+- **Simplistic?** Because extensive is sometimes overkill
+- **JSON?** Because binary compression is sometimes overkill  
+- **Bunny?** Who doesn't like bunnies? They're like cats with long ears
+- **AMQP?** I like AMQP. I like RabbitMQ as an AMQP broker
+
+BTW, at the farm bunnies grow best if planted ears up. 🐰
+
+## What's Next?
+
+- **[Installation Guide](getting-started/installation.md)** - Detailed installation and setup
+- **[Quick Start](getting-started/quick-start.md)** - Get running in 5 minutes
+- **[Basic Concepts](getting-started/basic-concepts.md)** - Understand the fundamentals
+- **[Examples](examples/overview.md)** - Comprehensive, runnable examples
+- **[API Reference](api/message-class.md)** - Complete API documentation