BugBunny

RESTful messaging over RabbitMQ for Ruby microservices.

BugBunny maps AMQP messages to controllers, routes, and models using the same patterns as Rails. Services communicate through RabbitMQ without HTTP coupling, with full support for synchronous RPC, fire-and-forget publishing, and sync publisher confirms for delivery-critical events.

---

Installation

gem 'bug_bunny'

bundle install
rails generate bug_bunny:install  # Rails only

---

Quickstart

BugBunny connects two services through RabbitMQ. One service hosts the consumer (server side); the other uses a Resource or Client to call it (client side).

Service B — Consumer

# config/initializers/bug_bunny.rb
BugBunny.configure do |config|
  config.host     = ENV.fetch('RABBITMQ_HOST', 'localhost')
  config.port     = 5672
  config.username = ENV.fetch('RABBITMQ_USER', 'guest')
  config.password = ENV.fetch('RABBITMQ_PASS', 'guest')
end

# config/initializers/bug_bunny_routes.rb
BugBunny.routes.draw do
  resources :nodes
end

# app/controllers/bug_bunny/controllers/nodes_controller.rb
module BugBunny
  module Controllers
    class NodesController < BugBunny::Controller
      def show
        node = Node.find(params[:id])
        render status: :ok, json: node.as_json
      end

      def index
        render status: :ok, json: Node.all.map(&:as_json)
      end
    end
  end
end

# Worker entrypoint (dedicated thread or process)
consumer = BugBunny::Consumer.new
consumer.subscribe(
  queue_name:    'inventory_queue',
  exchange_name: 'inventory',
  routing_key:   'nodes'
)

Service A — Producer

# config/initializers/bug_bunny.rb — same connection config as above

# Pool shared across threads (Puma / Sidekiq)
BUG_BUNNY_POOL = ConnectionPool.new(size: 5, timeout: 5) do
  BugBunny.create_connection
end

class RemoteNode < BugBunny::Resource
  self.exchange      = 'inventory'
  self.resource_name = 'nodes'

  attribute :name,   :string
  attribute :status, :string
end

RemoteNode.connection_pool = BUG_BUNNY_POOL

# Use it like ActiveRecord
node = RemoteNode.find('node-123')   # GET nodes/node-123 via RabbitMQ
node.status = 'active'
node.save                            # PUT nodes/node-123

RemoteNode.where(status: 'active')  # GET nodes?status=active
RemoteNode.create(name: 'web-01', status: 'pending')

---

Modes of Use

Resource ORM — ActiveRecord-like model for a remote service. Handles CRUD, validations, change tracking, and typed or dynamic attributes. Best when you own both sides of the communication.

Direct Client — BugBunny::Client for explicit RPC or fire-and-forget calls with full middleware control. Best when calling external services or when you need precise control over the request.

Consumer — Subscribe loop that routes incoming messages to controllers, with a middleware stack for cross-cutting concerns (tracing, auth, auditing).

---

Configuration

BugBunny.configure do |config|
  # Connection — required
  config.host     = 'localhost'
  config.port     = 5672
  config.username = 'guest'
  config.password = 'guest'
  config.vhost    = '/'

  # Resilience
  config.max_reconnect_attempts    = 10    # nil = infinite
  config.max_reconnect_interval    = 60    # seconds, ceiling for backoff
  config.network_recovery_interval = 5     # seconds, base for exponential backoff

  # Timeouts
  config.rpc_timeout         = 30   # seconds, for synchronous RPC calls
  config.connection_timeout  = 10
  config.read_timeout        = 10
  config.write_timeout       = 10

  # AMQP defaults applied to all exchanges and queues.
  # Gem defaults (since 4.16):
  #   DEFAULT_EXCHANGE_OPTIONS = { durable: false, auto_delete: false }
  #   DEFAULT_QUEUE_OPTIONS    = { exclusive: false, durable: true, auto_delete: false }
  # Override only if your service needs different infrastructure semantics.
  config.exchange_options = { durable: true }
  config.queue_options    = { durable: true }

  # Controller namespace (default: 'BugBunny::Controllers')
  config.controller_namespace = 'MyApp::RabbitHandlers'

  # Logger — any object responding to debug/info/warn/error
  config.logger = Rails.logger

  # Health check file for Kubernetes / Docker Swarm liveness probes
  config.health_check_file = '/tmp/bug_bunny_health'

  # Publisher Confirms — fail-loud defaults (both flags default to true).
  # Set to false to restore legacy log-only behavior.
  config.nack_raise   = true   # broker NACK → raise BugBunny::PublishNacked
  config.return_raise = true   # broker basic.return (mandatory) → raise BugBunny::PublishUnroutable

  # Callback invoked when the broker returns an unroutable mandatory message.
  # Runs BEFORE PublishUnroutable is raised (if return_raise is true).
  # When nil (default), BugBunny logs the return as `session.broker_return` at :warn.
  # Signature: ->(return_info, properties, body) { ... }
  config.on_return = ->(return_info, _props, body) {
    MyAlerts.publish_unroutable(rk: return_info.routing_key, body: body)
  }
end

BugBunny.configure validates all required fields on exit. A missing or invalid value raises BugBunny::ConfigurationError immediately, before any connection attempt.

---

Routing DSL

BugBunny.routes.draw do
  resources :users                    # GET/POST users, GET/PUT/DELETE users/:id
  resources :orders, only: [:index, :show, :create]

  resources :nodes do
    member   { put :drain }           # PUT nodes/:id/drain
    collection { post :rebalance }    # POST nodes/rebalance
  end

  namespace :api do
    namespace :v1 do
      resources :metrics              # Routes to Api::V1::MetricsController
    end
  end

  get  'status',     to: 'health#show'
  post 'events/:id', to: 'events#track'
end

---

Direct Client

pool   = ConnectionPool.new(size: 5, timeout: 5) { BugBunny.create_connection }
client = BugBunny::Client.new(pool: pool) do |stack|
  stack.use BugBunny::Middleware::RaiseError
  stack.use BugBunny::Middleware::JsonResponse
end

# Synchronous RPC
response = client.request('users/42', method: :get)
response['body']  # => { 'id' => 42, 'name' => 'Alice' }

# Fire-and-forget
client.publish('events', body: { type: 'user.signed_in', user_id: 42 })

# With params
client.request('users', method: :get, params: { role: 'admin', page: 2 })

Publisher Confirms (delivery-critical events)

For events where you need a delivery guarantee from the broker (auditing, billing, accounting) without the cost of a full RPC, use publish with confirmed: true. The call blocks until the broker acknowledges receipt:

client.publish('acct.start',
               exchange:        'acct_events',
               exchange_type:   'topic',
               body:            { tenant_id: 42, plan: 'pro' },
               confirmed:       true,
               mandatory:       true,    # broker returns the message if no queue is bound
               confirm_timeout: 0.5)     # seconds; nil waits forever
# => { 'status' => 202, 'body' => nil }  # broker confirmed

Option	Type	Default	Purpose
confirmed	Boolean	false	Block until wait_for_confirms returns.
mandatory	Boolean	false	Broker returns the message if it cannot be routed to any queue. Requires confirmed: true to be useful.
confirm_timeout	Float	nil	Seconds to wait for the broker ACK. Raises BugBunny::RequestTimeout if exceeded.
nack_raise	Boolean	nil	Per-request override of config.nack_raise. When nil, falls back to the global flag (default true).
return_raise	Boolean	nil	Per-request override of config.return_raise. When nil, falls back to the global flag (default true). Requires confirmed: true and mandatory: true to take effect.

Two broker signals, two exceptions:

Broker signal	Default behavior	Exception class	Fields
basic.nack (explicit rejection)	Raises	BugBunny::PublishNacked	path, nacked_count
basic.return (unroutable + mandatory: true)	Raises	BugBunny::PublishUnroutable	path, exchange, routing_key, reply_code, reply_text, correlation_id

Both exceptions translate naturally into HTTP 5xx in critical publishers (audit, billing, RADIUS accounting) so upstream systems retry. The config.on_return callback (if defined) still runs before PublishUnroutable is raised — useful for alerting/metrics. To restore the legacy "log-only" behaviour:

BugBunny.configure do |c|
  c.nack_raise   = false  # or pass `nack_raise: false` per request
  c.return_raise = false  # or pass `return_raise: false` per request
end

When mandatory: false (the default), return_raise is inert — the broker never emits basic.return without mandatory.

---

Consumer Middleware

Middlewares run before every message reaches the router. Use them for distributed tracing, authentication, or audit logging.

class TracingMiddleware < BugBunny::ConsumerMiddleware::Base
  def call(delivery_info, properties, body)
    trace_id = properties.headers&.dig('X-Trace-Id')
    MyTracer.with_trace(trace_id) { @app.call(delivery_info, properties, body) }
  end
end

BugBunny.consumer_middlewares.use TracingMiddleware

---

Observability

BugBunny implementa de forma nativa las OpenTelemetry semantic conventions for messaging, inyectando automáticamente campos como messaging_system, messaging_operation, messaging_destination_name y messaging_message_id tanto en los headers AMQP como en los log events estructurados.

Todos los eventos internos se emiten como logs key=value compatibles con Datadog, CloudWatch, ELK y ExisRay.

component=bug_bunny event=producer.publish method=POST path=acct/publish messaging_destination_name=acct_x messaging_routing_key=acct.start.42
component=bug_bunny event=producer.published method=POST path=acct/publish routing_key=acct.start.42 messaging_message_id=corr-1 duration_s=0.000812
component=bug_bunny event=producer.confirmed method=POST path=acct/publish routing_key=acct.start.42 publish_duration_s=0.000812 confirm_duration_s=0.012 duration_s=0.013
component=bug_bunny event=producer.rpc_response_received method=GET path=users/42 duration_s=0.034 messaging_operation=receive
component=bug_bunny event=consumer.message_processed status=200 duration_s=0.012 messaging_operation=process controller=NodesController action=show
component=bug_bunny event=consumer.execution_error error_class=RuntimeError error_message="..." duration_s=0.003
component=bug_bunny event=consumer.connection_error attempt_count=2 retry_in_s=10 error_message="..."

Duraciones medidas internamente

BugBunny mide y emite duraciones automáticamente — no es necesario envolver llamadas a client.publish con Process.clock_gettime en el código de aplicación. Las unidades siguen las OpenTelemetry metric semantic conventions (s, segundos como Float).

Evento	Duración	Mide
producer.published	duration_s	Solo el basic_publish (TCP enqueue al broker).
producer.confirmed	publish_duration_s + confirm_duration_s + duration_s (total)	Publish + espera de ACK del broker.
producer.rpc_response_received	duration_s	Round-trip RPC completo (publish + procesamiento remoto + reply).
consumer.message_processed	duration_s	Procesamiento del mensaje (router + controller + reply).
consumer.execution_error	duration_s	Tiempo transcurrido hasta el error.

Las claves sensibles (password, token, secret, api_key, authorization, etc.) se filtran automáticamente a [FILTERED] en toda la salida de logs.

---

Error Handling

BugBunny maps RabbitMQ responses to a semantic exception hierarchy, similar to how HTTP clients handle status codes.

Exception Hierarchy

BugBunny::Error
├── CommunicationError                  (network / channel failure)
├── ConfigurationError                  (invalid config attribute)
├── SecurityError                       (unauthorized controller resolution)
├── PublishNacked                       (broker basic.nack on :confirmed publish)
├── PublishUnroutable                   (broker basic.return on mandatory + :confirmed)
├── ClientError (4xx)
│   ├── BadRequest (400)
│   ├── NotFound (404)
│   │   └── RoutingError                (consumer-side: no route for verb + path)
│   ├── NotAcceptable (406)
│   ├── RequestTimeout (408)
│   ├── Conflict (409)
│   └── UnprocessableEntity (422)
└── ServerError (5xx)
    ├── InternalServerError (500+)
    └── RemoteError (500)

Remote Exception Propagation

When a controller raises an unhandled exception, BugBunny serializes it and sends it back to the caller as a 500 response. The client-side middleware reconstructs it as a BugBunny::RemoteError with full access to the original exception details:

begin
  node = RemoteNode.find('node-123')
rescue BugBunny::RemoteError => e
  e.original_class     # => "TypeError"
  e.original_message   # => "nil can't be coerced into Integer"
  e.original_backtrace # => Array<String> from the remote service
rescue BugBunny::NotFound
  # Resource doesn't exist
rescue BugBunny::RequestTimeout
  # Consumer didn't respond in time
end

Validation Errors

Resource#save returns false on validation failure and loads remote errors into the model:

order = RemoteOrder.new(total: -1)
unless order.save
  order.errors.full_messages # => ["total must be greater than 0"]
end

---

Documentation

• Concepts — What BugBunny is, AMQP in 5 minutes, RPC vs fire-and-forget
• Routing — Full routing DSL reference
• Controllers — Filters, rescue_from, render, after_action
• Resource ORM — CRUD, typed and dynamic attributes, .with scoping
• Client Middleware — Request/response middleware stack
• Consumer Middleware — Message processing middleware stack
• Distributed Tracing — Propagating trace context through RPC cycles
• Rails Setup — Full integration: Puma, Sidekiq, Zeitwerk, health checks
• Testing — Unit and integration testing with Bunny mocks

---

License

MIT