bunny_farm 0.1.2

data/docs/message-structure/actions-dsl.md

@@ -0,0 +1,163 @@
+# Actions DSL
+
+The Actions DSL defines the operations that your message can perform. Each action becomes a routable method that can be called when the message is consumed.
+
+## Basic Actions
+
+```ruby
+class OrderMessage < BunnyFarm::Message
+  actions :validate, :process, :ship, :cancel
+  
+  def validate
+    # Validation logic
+    success!
+  end
+  
+  def process
+    # Processing logic
+    success!
+  end
+  
+  def ship
+    # Shipping logic
+    success!
+  end
+  
+  def cancel
+    # Cancellation logic
+    success!
+  end
+end
+```
+
+## Action Method Implementation
+
+Each action must be implemented as a method:
+
+```ruby
+class PaymentMessage < BunnyFarm::Message
+  actions :authorize, :capture, :refund
+  
+  def authorize
+    result = payment_gateway.authorize(@items[:amount], @items[:card_token])
+    
+    if result.success?
+      @items[:authorization_id] = result.authorization_id
+      success!
+    else
+      failure("Authorization failed: #{result.error_message}")
+    end
+    
+    successful?
+  end
+  
+  def capture
+    return failure("No authorization ID") unless @items[:authorization_id]
+    
+    result = payment_gateway.capture(@items[:authorization_id])
+    
+    if result.success?
+      @items[:transaction_id] = result.transaction_id
+      success!
+    else
+      failure("Capture failed: #{result.error_message}")
+    end
+    
+    successful?
+  end
+end
+```
+
+## Action Routing
+
+Actions create routing keys automatically:
+
+```ruby
+# Publishing creates routing keys
+message = PaymentMessage.new
+message.publish('authorize')  # Routing key: PaymentMessage.authorize
+message.publish('capture')    # Routing key: PaymentMessage.capture
+message.publish('refund')     # Routing key: PaymentMessage.refund
+```
+
+## Action Patterns
+
+### CRUD Operations
+```ruby
+class UserMessage < BunnyFarm::Message
+  actions :create, :read, :update, :delete
+end
+```
+
+### Workflow Actions
+```ruby
+class OrderWorkflow < BunnyFarm::Message
+  actions :start, :validate, :process_payment, :fulfill, :ship, :complete
+end
+```
+
+### State Machine Actions
+```ruby
+class DocumentMessage < BunnyFarm::Message
+  actions :draft, :review, :approve, :publish, :archive
+end
+```
+
+## Action Validation
+
+```ruby
+class ValidatedActions < BunnyFarm::Message
+  actions :process
+  
+  def process
+    # Validate before processing
+    return unless validate_preconditions
+    
+    # Perform work
+    do_processing
+    
+    # Validate after processing
+    return unless validate_postconditions
+    
+    success!
+  end
+  
+  private
+  
+  def validate_preconditions
+    failure("Missing required data") unless required_data_present?
+    successful?
+  end
+  
+  def validate_postconditions
+    failure("Processing incomplete") unless processing_complete?
+    successful?
+  end
+end
+```
+
+## Best Practices
+
+### 1. Use Descriptive Action Names
+```ruby
+# Good: Clear, descriptive names
+actions :validate_order, :process_payment, :ship_order, :send_confirmation
+
+# Avoid: Vague or generic names
+actions :do_stuff, :handle, :process
+```
+
+### 2. Single Responsibility
+```ruby
+# Good: Each action has one purpose
+actions :validate_customer, :validate_inventory, :validate_payment
+
+# Avoid: Actions that do too much
+actions :validate_everything
+```
+
+### 3. Logical Flow
+```ruby
+# Good: Actions follow logical order
+actions :create_draft, :add_content, :review, :approve, :publish
+```

data/docs/message-structure/fields-dsl.md

@@ -0,0 +1,146 @@
+# Fields DSL
+
+The Fields DSL is BunnyFarm's declarative syntax for defining the data structure of your messages. It provides a clean, readable way to specify expected fields and their organization.
+
+![Fields DSL Structure](../assets/fields_dsl_structure.svg)
+
+## Basic Field Declaration
+
+```ruby
+class UserMessage < BunnyFarm::Message
+  # Simple fields
+  fields :user_id, :email, :name, :created_at
+end
+```
+
+## Nested Objects
+
+```ruby
+class CustomerMessage < BunnyFarm::Message
+  fields :customer_id, :email,
+         { address: [:street, :city, :state, :zip] },
+         { preferences: [:newsletter, :promotions, :sms] }
+end
+```
+
+## Complex Structures
+
+```ruby
+class OrderMessage < BunnyFarm::Message
+  fields :order_id, :total, :tax, :shipping,
+         { customer: [:name, :email, :phone] },
+         { billing_address: [:street, :city, :state, :zip, :country] },
+         { shipping_address: [:street, :city, :state, :zip, :country] },
+         { items: [:product_id, :name, :quantity, :unit_price, :total_price] },
+         { payment: [:method, :transaction_id, :status] }
+end
+```
+
+## Data Access
+
+```ruby
+message = OrderMessage.new
+
+# Simple fields
+message[:order_id] = 12345
+message[:total] = 99.99
+
+# Nested objects
+message[:customer] = {
+  name: "John Doe",
+  email: "john@example.com",
+  phone: "+1-555-123-4567"
+}
+
+# Arrays of objects
+message[:items] = [
+  {
+    product_id: 1,
+    name: "Widget",
+    quantity: 2,
+    unit_price: 29.99,
+    total_price: 59.98
+  },
+  {
+    product_id: 2,
+    name: "Gadget",
+    quantity: 1,
+    unit_price: 39.99,
+    total_price: 39.99
+  }
+]
+
+# Access nested data
+puts message[:customer][:name]        # "John Doe"
+puts message[:items][0][:product_id]  # 1
+puts message[:billing_address][:city] # Access nested fields
+```
+
+## Field Validation
+
+```ruby
+class ValidatedMessage < BunnyFarm::Message
+  fields :user_id, :email, :age
+  
+  def validate
+    failure("User ID required") unless @items[:user_id]
+    failure("Invalid email") unless valid_email?(@items[:email])
+    failure("Age must be positive") unless @items[:age]&.positive?
+    
+    success! if errors.empty?
+  end
+  
+  private
+  
+  def valid_email?(email)
+    email =~ /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
+  end
+end
+```
+
+## Dynamic Field Access
+
+```ruby
+message = OrderMessage.new
+
+# Get all field keys
+field_keys = message.keys
+# => [:order_id, :total, :customer, :items, ...]
+
+# Check if field exists
+has_customer = message.keys.include?(:customer)
+
+# Iterate over fields
+message.keys.each do |field|
+  value = message[field]
+  puts "#{field}: #{value}"
+end
+```
+
+## Best Practices
+
+### 1. Logical Grouping
+```ruby
+# Good: Related fields grouped together
+fields :order_id, :status, :created_at,
+       { customer: [:id, :name, :email] },
+       { items: [:id, :name, :price] }
+```
+
+### 2. Consistent Naming
+```ruby
+# Good: Consistent snake_case
+fields :user_id, :created_at, :email_address
+
+# Avoid: Mixed conventions
+fields :userId, :created_at, :EmailAddress
+```
+
+### 3. Meaningful Structure
+```ruby
+# Good: Clear hierarchy
+fields { address: [:street, :city, :state, :zip] }
+
+# Avoid: Flat structure
+fields :address_street, :address_city, :address_state, :address_zip
+```

data/docs/message-structure/instance-methods.md

@@ -0,0 +1,115 @@
+# Instance Methods
+
+BunnyFarm message instances provide a rich set of methods for data access, state management, and message operations.
+
+## Data Access Methods
+
+### Hash-like Access
+```ruby
+message = OrderMessage.new
+
+# Get values
+order_id = message[:order_id]
+customer_name = message[:customer][:name]
+
+# Set values
+message[:order_id] = 12345
+message[:customer] = { name: "John", email: "john@example.com" }
+```
+
+### Field Introspection
+```ruby
+# Get all field keys
+keys = message.keys  # => [:order_id, :customer, :items]
+
+# Check if field exists
+has_customer = message.respond_to?(:[]) && message[:customer]
+
+# Get field count
+field_count = message.keys.length
+```
+
+## State Management
+
+### Success/Failure Tracking
+```ruby
+def process_order
+  validate_data
+  return unless successful?
+  
+  charge_payment
+  return unless successful?
+  
+  update_inventory
+  success!  # Mark as successful
+end
+
+# Check state
+if message.successful?
+  puts "Order processed successfully"
+else
+  puts "Order failed: #{message.errors.join(', ')}"
+end
+```
+
+### Error Management
+```ruby
+def validate
+  failure("Order ID required") unless @items[:order_id]
+  failure("Invalid email") unless valid_email?(@items[:email])
+  
+  # Check error state
+  if failed?
+    puts "Validation errors: #{errors.join(', ')}"
+  else
+    success!
+  end
+end
+```
+
+## Message Operations
+
+### Publishing
+```ruby
+# Publish message
+message.publish('process')  # Routing key: MessageClass.process
+
+# Check if publish succeeded
+if message.successful?
+  puts "Message published successfully"
+else
+  puts "Publish failed: #{message.errors.join(', ')}"
+end
+```
+
+### Serialization
+```ruby
+# Convert to JSON
+json_string = message.to_json
+puts json_string
+# => {"order_id":12345,"customer":{"name":"John"}}
+
+# Get raw payload (if received message)
+original_json = message.payload
+```
+
+## Utility Methods
+
+### Inspection and Debugging
+```ruby
+# Inspect message contents
+puts message.inspect
+
+# Pretty print for debugging
+puts JSON.pretty_generate(message.to_hash)
+```
+
+### Cloning and Copying
+```ruby
+# Create copy with same data
+new_message = message.class.new
+message.keys.each { |key| new_message[key] = message[key] }
+
+# Publish copy with different action
+new_message.publish('different_action')
+```

data/docs/message-structure/overview.md

@@ -0,0 +1,211 @@
+# Message Structure Overview
+
+Understanding how BunnyFarm messages are structured is key to using the library effectively. This section covers the anatomy of a BunnyFarm message and how the DSL components work together.
+
+<img src="../assets/message_structure.svg" alt="Message Structure" width="100%">
+
+## Message Class Anatomy
+
+A BunnyFarm message class consists of several key components:
+
+```ruby
+class OrderMessage < BunnyFarm::Message
+  # 1. Fields DSL - Define data structure
+  fields :order_id, :total, 
+         { customer: [:name, :email] }, 
+         { items: [:id, :qty] }
+
+  # 2. Actions DSL - Define available operations  
+  actions :validate, :process_payment, :ship, :cancel
+
+  # 3. Action Methods - Business logic
+  def validate
+    # Validation logic here
+    success!
+    successful?
+  end
+
+  def process_payment
+    # Payment processing logic
+    success!
+    successful?
+  end
+
+  # 4. Helper Methods (private)
+  private
+
+  def validate_customer
+    # Helper logic
+  end
+end
+```
+
+## DSL Components
+
+### Fields DSL
+The `fields` DSL defines the expected data structure for your messages:
+
+- **Simple fields**: Basic data types like strings, numbers, booleans
+- **Nested objects**: Complex data structures with sub-fields
+- **Arrays**: Lists of items or objects
+
+### Actions DSL  
+The `actions` DSL defines the operations your message can perform:
+
+- Each action becomes a routable method
+- Actions map to routing keys: `MessageClass.action`
+- Must implement corresponding methods
+
+## Instance Structure
+
+When a message is instantiated, it contains several important instance variables:
+
+### @items
+Validated and structured data extracted from the raw JSON based on your fields definition.
+
+```ruby
+message[:customer][:name] # Access via hash-like interface
+```
+
+### @elements
+Raw JSON data as received from the message broker.
+
+```ruby
+message.elements # Access raw data
+```
+
+### @payload
+The original JSON string as received from RabbitMQ.
+
+```ruby
+message.payload # Original JSON string
+```
+
+### @errors
+Array of error messages accumulated during processing.
+
+```ruby
+message.errors # => ["Validation failed", "Payment declined"]
+```
+
+## Data Flow
+
+The message goes through several stages:
+
+1. **JSON Input** - Raw message data from RabbitMQ
+2. **Parse & Validate** - Extract fields using DSL definition  
+3. **Route Action** - Call method based on routing key
+4. **Execute Logic** - Run business logic in action method
+5. **ACK/NACK** - Acknowledge to RabbitMQ based on success/failure
+
+## Access Methods
+
+BunnyFarm provides several ways to access and manipulate message data:
+
+### Hash-like Access
+```ruby
+msg[:field]       # Get value
+msg[:field] = val # Set value
+```
+
+### JSON Serialization
+```ruby
+msg.to_json # Convert to JSON string
+```
+
+### Field Inspection
+```ruby
+msg.keys # Get all available fields
+```
+
+## State Management
+
+Messages track their processing state throughout the lifecycle:
+
+### Success States
+```ruby
+success!     # Mark as successful
+successful?  # Check if successful
+```
+
+### Failure States
+```ruby
+failure(msg) # Mark as failed with reason
+failed?      # Check if failed
+```
+
+### Publishing
+```ruby
+msg.publish(action) # Send message with routing key
+```
+
+## Best Practices
+
+### 1. Design Clear Field Structures
+```ruby
+# Good: Clear, hierarchical structure
+fields :order_id, :amount,
+       { customer: [:name, :email, :phone] },
+       { billing_address: [:street, :city, :state, :zip] }
+
+# Avoid: Flat, unclear structure  
+fields :order_id, :customer_name, :customer_email, 
+       :billing_street, :billing_city # ... too flat
+```
+
+### 2. Use Meaningful Action Names
+```ruby
+# Good: Descriptive action names
+actions :validate_order, :process_payment, :ship_order, :send_confirmation
+
+# Avoid: Generic action names
+actions :process, :handle, :do_work
+```
+
+### 3. Implement Proper Error Handling
+```ruby
+def process_payment
+  return failure("Missing payment info") unless payment_present?
+  return failure("Invalid amount") unless valid_amount?
+  
+  charge_result = payment_gateway.charge(@items[:amount])
+  
+  if charge_result.success?
+    success!
+  else
+    failure("Payment failed: #{charge_result.error}")
+  end
+  
+  successful?
+end
+```
+
+### 4. Keep Methods Focused
+Each action method should have a single, clear responsibility:
+
+```ruby
+def validate_order
+  validate_customer_info
+  validate_items
+  validate_shipping_address
+  
+  success! if errors.empty?
+  successful?
+end
+
+private
+
+def validate_customer_info
+  failure("Customer name required") if @items[:customer][:name].blank?
+  failure("Customer email required") if @items[:customer][:email].blank?
+end
+```
+
+## Next Steps
+
+Now that you understand message structure, explore:
+
+- **[Fields DSL](fields-dsl.md)** - Detailed guide to defining data structures
+- **[Actions DSL](actions-dsl.md)** - Complete actions DSL reference
+- **[Instance Methods](instance-methods.md)** - All available instance methods
+- **[Configuration](../configuration/overview.md)** - Message configuration options