bug_bunny 4.6.1 → 4.8.0

data/README.md

@@ -1,312 +1,245 @@
-# 🐰 BugBunny
+# BugBunny
 
 [![Gem Version](https://badge.fury.io/rb/bug_bunny.svg)](https://badge.fury.io/rb/bug_bunny)
 
-**Active Record over AMQP.**
+RESTful messaging over RabbitMQ for Ruby microservices.
 
-BugBunny transforma la complejidad de la mensajería asíncrona (RabbitMQ) en una arquitectura familiar RESTful. Permite que tus microservicios se comuniquen como si fueran APIs locales, utilizando controladores, rutas y modelos con una interfaz idéntica a Active Record.
-
-## ✨ Características
-
-*   **RESTful Routing:** Define tus endpoints AMQP con un DSL estilo Rails (`get`, `post`, `resources`).
-*   **Active Record Pattern:** Modela tus recursos remotos con validaciones, callbacks y tracking de cambios.
-*   **Middleware Stack:** Arquitectura de cebolla (Onion) para interceptar peticiones, manejar errores y transformar payloads.
-*   **RPC & Pub/Sub:** Soporta nativamente tanto peticiones síncronas (Request-Response) como publicaciones asíncronas.
-*   **Observabilidad de Clase Mundial:** Integración nativa con **ExisRay** (Tracing distribuido y Logs estructurados KV).
-*   **Resiliencia Enterprise:** Reconexión automática con Backoff Exponencial y Health Checks automáticos.
+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 and fire-and-forget publishing.
 
 ---
 
-## 🚀 Instalación
-
-Añade esta línea al `Gemfile` de tu aplicación:
+## Installation
 
 ```ruby
 gem 'bug_bunny'
 ```
 
-Y luego ejecuta:
 ```bash
-$ bundle install
-```
-
-O instálalo manualmente:
-```bash
-$ gem install bug_bunny
-```
-
-Luego, genera el inicializador (en Rails):
-```bash
-$ rails generate bug_bunny:install
+bundle install
+rails generate bug_bunny:install  # Rails only
 ```
 
 ---
 
-## 🛠️ Configuración
+## 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).
 
-Configura la conexión a RabbitMQ y las opciones globales:
+### Service B — Consumer
 
 ```ruby
 # config/initializers/bug_bunny.rb
 BugBunny.configure do |config|
-  config.host = ENV['RABBITMQ_HOST'] || '127.0.0.1'
-  config.port = 5672
-  config.username = 'guest'
-  config.password = 'guest'
-  
-  # Resiliencia
-  config.max_reconnect_attempts = 10      # Falla tras 10 intentos (útil en K8s)
-  config.max_reconnect_interval = 60      # Máximo 60s entre reintentos
-  config.network_recovery_interval = 5    # Intervalo base para backoff
-  
-  # Infraestructura por defecto (Nivel 2)
-  config.exchange_options = { durable: true }
+  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
 
-## 📦 Uso como Modelo (Consumer + Producer)
+# Worker entrypoint (dedicated thread or process)
+consumer = BugBunny::Consumer.new
+consumer.subscribe(
+  queue_name:    'inventory_queue',
+  exchange_name: 'inventory',
+  routing_key:   'nodes'
+)
+```
 
-BugBunny permite definir modelos que representan recursos en otros microservicios.
+### Service A — Producer
 
 ```ruby
+# 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
-  # Configuración del canal
-  self.exchange = 'inventory_exchange'
-  self.resource_name = 'nodes' # Equivale al path de la URL
+  self.exchange      = 'inventory'
+  self.resource_name = 'nodes'
 
-  # Atributos (ActiveRecord style)
-  attribute :name, :string
+  attribute :name,   :string
   attribute :status, :string
-  attribute :cpu_cores, :integer
-
-  # Validaciones
-  validates :name, presence: true
 end
 
-# Uso:
-node = RemoteNode.find('node-123')
+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 # Realiza un PUT a inventory_exchange con routing_key 'nodes.node-123'
-
-# Búsqueda con filtros (query params)
-# Los filtros se serializan como query string en el header 'type' del mensaje.
-# El consumer los recibe en params[] igual que en Rails.
-RemoteNode.all                               # GET nodes
-RemoteNode.where(status: 'active')           # GET nodes?status=active
-RemoteNode.where(q: { cpu_cores: 4 })        # GET nodes?q[cpu_cores]=4
+node.save                            # PUT nodes/node-123
+
+RemoteNode.where(status: 'active')  # GET nodes?status=active
+RemoteNode.create(name: 'web-01', status: 'pending')
 ```
 
 ---
 
-## 🛣️ Enrutamiento y Controladores (Server side)
-
-Define cómo debe responder tu aplicación a los mensajes entrantes:
+## Modes of Use
 
-```ruby
-# config/rabbit_routes.rb
-BugBunny.routes.draw do
-  resources :nodes do
-    member do
-      put :drain
-    end
-  end
-end
+**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.
 
-# app/controllers/bug_bunny/nodes_controller.rb
-module BugBunny
-  module Controllers
-    class NodesController < BugBunny::Controller
-      def index
-        nodes = Node.all # Lógica local de tu app
-        render status: :ok, json: nodes
-      end
+**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.
 
-      def drain
-        # El ID viene automáticamente en params[:id]
-        Node.find(params[:id]).start_drain_process!
-        render status: :accepted, json: { message: "Draining started" }
-      end
-    end
-  end
-end
-```
-
-> **Namespace de Controladores:** Por defecto BugBunny busca los controladores bajo `BugBunny::Controllers`. Podés cambiarlo en la configuración:
-> ```ruby
-> BugBunny.configure do |config|
->   config.controller_namespace = 'MyApp::RabbitControllers'
-> end
-> ```
+**Consumer** — Subscribe loop that routes incoming messages to controllers, with a middleware stack for cross-cutting concerns (tracing, auth, auditing).
 
 ---
 
-## 🔌 Middlewares
-
-Puedes extender el comportamiento del cliente globalmente o por recurso:
+## Configuration
 
 ```ruby
-# Globalmente en el inicializador
 BugBunny.configure do |config|
-  # ...
-end
+  # Connection — required
+  config.host     = 'localhost'
+  config.port     = 5672
+  config.username = 'guest'
+  config.password = 'guest'
+  config.vhost    = '/'
 
-# Uso con el cliente manual
-client = BugBunny::Client.new(pool: BUG_BUNNY_POOL) do |stack|
-  stack.use BugBunny::Middleware::RaiseError
-  stack.use BugBunny::Middleware::JsonResponse
-end
+  # 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
 
-# 1. Método genérico 'send' (Estilo Faraday)
-# El comportamiento (RPC o Fire-and-forget) depende de 'delivery_mode'
-client.delivery_mode = :rpc # Default
-client.send('users/1', method: :get)
+  # Timeouts
+  config.rpc_timeout         = 30   # seconds, for synchronous RPC calls
+  config.connection_timeout  = 10
+  config.read_timeout        = 10
+  config.write_timeout       = 10
 
-# 2. Configuración flexible del modo de entrega
-# Por cada petición
-client.send('logs', method: :post, body: { msg: 'system_up' }, delivery_mode: :publish)
+  # AMQP defaults applied to all exchanges and queues
+  config.exchange_options = { durable: true }
+  config.queue_options    = { durable: true }
 
-# O mediante un bloque para configuración avanzada
-client.send('users/1') do |req|
-  req.method = :get
-  req.delivery_mode = :rpc
-  req.timeout = 5
-end
+  # Controller namespace (default: 'BugBunny::Controllers')
+  config.controller_namespace = 'MyApp::RabbitHandlers'
 
-# 3. Query params (estilo Faraday)
-# Usá req.params para enviar filtros. La gema los serializa como query string
-# en el header 'type' del mensaje (que el consumer usa para rutear).
-# La routing_key del exchange NO se ve afectada.
-client.request('users') do |req|
-  req.method = :get
-  req.params = { q: { active: true }, page: 2 }
+  # 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'
 end
-# Equivalente usando args:
-client.request('users', method: :get, params: { q: { active: true }, page: 2 })
+```
 
-# 4. Métodos de conveniencia (Atajos)
-client.request('users/1') # Siempre :rpc
-client.publish('events', body: { type: 'click' }) # Siempre :publish
+`BugBunny.configure` validates all required fields on exit. A missing or invalid value raises `BugBunny::ConfigurationError` immediately, before any connection attempt.
 
-# Ahora el cliente devolverá Hashes y lanzará errores si el worker falla
-response = client.request('users/1', method: :get)
-```
+---
 
-**Middlewares Personalizados**
+## Routing DSL
 
 ```ruby
-class MyCustomMiddleware < BugBunny::Middleware::Base
-  def call(request)
-    puts "Enviando mensaje a: #{request.path}"
-    app.call(request)
+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
 ```
 
 ---
 
-## 🔗 Consumer Middleware Stack
-
-BugBunny expone un middleware stack que se ejecuta **antes** de que la gema procese cada mensaje entrante (antes del primer log `consumer.message_received`). Es el punto ideal para hidratar contexto de tracing distribuido, autenticación, auditoría, etc.
-
-### Implementar un middleware
+## Direct Client
 
 ```ruby
-class MyMiddleware < BugBunny::ConsumerMiddleware::Base
-  def call(delivery_info, properties, body)
-    # lógica pre-procesamiento
-    # properties.headers contiene todos los headers AMQP custom
-    @app.call(delivery_info, properties, body)
-    # lógica post-procesamiento (opcional)
-  end
+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
-```
 
-### Registrar un middleware
+# Synchronous RPC
+response = client.request('users/42', method: :get)
+response['body']  # => { 'id' => 42, 'name' => 'Alice' }
 
-```ruby
-BugBunny.configure do |config|
-  # ...
-end
+# Fire-and-forget
+client.publish('events', body: { type: 'user.signed_in', user_id: 42 })
 
-BugBunny.consumer_middlewares.use MyMiddleware
+# With params
+client.request('users', method: :get, params: { role: 'admin', page: 2 })
 ```
 
-### Auto-registro desde una gema externa
+---
+
+## Consumer Middleware
 
-Las gemas de integración pueden registrarse automáticamente al ser requeridas, sin que el usuario tenga que tocar el bloque `configure`:
+Middlewares run before every message reaches the router. Use them for distributed tracing, authentication, or audit logging.
 
 ```ruby
-# lib/exis_ray/bug_bunny/consumer_tracing.rb
-require 'exis_ray/bug_bunny/consumer_tracing_middleware'
-BugBunny.consumer_middlewares.use ExisRay::BugBunny::ConsumerTracingMiddleware
+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
 
-# El usuario solo necesita:
-# require 'exis_ray/bug_bunny/consumer_tracing'
+BugBunny.consumer_middlewares.use TracingMiddleware
 ```
 
-### Datos disponibles en el middleware
-
-| Argumento | Tipo | Contenido |
-|---|---|---|
-| `delivery_info` | `Bunny::DeliveryInfo` | `routing_key`, `exchange`, `delivery_tag` |
-| `properties` | `Bunny::MessageProperties` | `headers` (headers AMQP custom), `correlation_id`, `reply_to`, `content_type` |
-| `body` | `String` | Payload crudo del mensaje |
-
-> **Orden de ejecución:** FIFO — el primero en registrarse es el primero en ejecutarse.
-> `Middleware A → Middleware B → process_message`
-
 ---
 
-## 🔎 Observabilidad y Tracing
+## Observability
 
-BugBunny implementa Distributed Tracing nativo y sigue los estándares de observabilidad de **ExisRay** para logs estructurados.
+All internal events are emitted as structured key=value logs compatible with Datadog, CloudWatch, and ELK.
 
-### 1. Logs Estructurados (Key-Value)
-A partir de la v4.3.0, todos los logs internos de la gema utilizan un formato `key=value` optimizado para motores de logs (CloudWatch, Datadog, ELK).
-
-*   **Data First:** Las unidades están en la llave (`_s`, `_ms`, `_count`), permitiendo que los valores sean números puros para agregaciones automáticas.
-*   **Reloj Monotónico:** Las duraciones (`duration_s`) se calculan con precisión de microsegundos usando el reloj monotónico del sistema.
-*   **Campos de Identidad:** Todos los logs incluyen `component=bug_bunny` y un `event` semántico.
-
-**Ejemplos de Logs:**
-```text
-# Mensaje procesado con éxito (incluye duración y status numérico)
-component=bug_bunny event=consumer.message_processed status=200 duration_s=0.015432 controller=UsersController action=show
-
-# Error de ejecución (campos estandarizados)
-component=bug_bunny event=consumer.execution_error error_class=NoMethodError error_message="undefined method..." duration_s=0.008123
-
-# Reintento de conexión con backoff (sufijos de unidad)
-component=bug_bunny event=consumer.connection_error error_message="..." attempt_count=3 retry_in_s=20
+```
+component=bug_bunny event=consumer.message_processed status=200 duration_s=0.012 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="..."
 ```
 
-**Ventaja en Cloud:**
-Al usar `duration_s` como un float puro, puedes realizar consultas analíticas directamente en tu motor de logs sin parsear strings:
-`stats avg(duration_s), max(duration_s) by controller, action`
-
-### 2. Distributed Tracing
-El `correlation_id` se mantiene intacto a través de toda la cadena: `Producer -> RabbitMQ -> Consumer -> Controller`.
+Sensitive keys (`password`, `token`, `secret`, `api_key`, `authorization`, etc.) are automatically filtered to `[FILTERED]` in all log output.
 
-### 3. Manejo de Errores Declarativo
-Captura excepciones y devuélvelas como códigos de estado AMQP/HTTP.
+---
 
-```ruby
-class ApplicationController < BugBunny::Controller
-  rescue_from ActiveRecord::RecordNotFound do |e|
-    render status: :not_found, json: { error: "Resource missing" }
-  end
+## Documentation
 
-  rescue_from StandardError do |e|
-    safe_log(:error, "application.crash", **exception_metadata(e))
-    render status: :internal_server_error, json: { error: "Crash" }
-  end
-end
-```
+- [Concepts](docs/concepts.md) — What BugBunny is, AMQP in 5 minutes, RPC vs fire-and-forget
+- [Routing](docs/howto/routing.md) — Full routing DSL reference
+- [Controllers](docs/howto/controller.md) — Filters, `rescue_from`, `render`, `after_action`
+- [Resource ORM](docs/howto/resource.md) — CRUD, typed and dynamic attributes, `.with` scoping
+- [Client Middleware](docs/howto/middleware_client.md) — Request/response middleware stack
+- [Consumer Middleware](docs/howto/middleware_consumer.md) — Message processing middleware stack
+- [Distributed Tracing](docs/howto/tracing.md) — Propagating trace context through RPC cycles
+- [Rails Setup](docs/howto/rails.md) — Full integration: Puma, Sidekiq, Zeitwerk, health checks
+- [Testing](docs/howto/testing.md) — Unit and integration testing with Bunny mocks
 
 ---
 
-## 📄 Licencia
+## License
 
-Código abierto bajo [MIT License](https://opensource.org/licenses/MIT).
+[MIT](https://opensource.org/licenses/MIT)

data/Rakefile

@@ -1,12 +1,28 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
+require 'rspec/core/rake_task'
 
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = '--require spec_helper'
+end
+
+RSpec::Core::RakeTask.new('spec:unit') do |t|
+  t.pattern  = 'spec/unit/**/*_spec.rb'
+  t.rspec_opts = '--require spec_helper'
+end
+
+RSpec::Core::RakeTask.new('spec:integration') do |t|
+  t.pattern  = 'spec/integration/**/*_spec.rb'
+  t.rspec_opts = '--require spec_helper'
+end
+
+# Mantiene la tarea :test apuntando a los tests de integración legacy de Minitest
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
   t.libs << 'lib'
   t.test_files = FileList['test/**/*_test.rb']
-  t.verbose = true
-  t.warning = false
+  t.verbose    = true
+  t.warning    = false
 end
 
-task default: :test
+task default: :spec

data/docs/_index.md

@@ -0,0 +1,50 @@
+# docs/_index.md — Documentation Manifest
+
+This file is the source of truth for the `docs/` directory structure.
+It is read by the `/release` command to know which files to generate or update.
+
+---
+
+## Human documentation (developers integrating BugBunny)
+
+| File | Purpose |
+|---|---|
+| `concepts.md` | AMQP in 5 min, architecture diagram, RPC vs fire-and-forget, connection pool |
+| `howto/routing.md` | Routes DSL: `resources`, `namespace`, `member`, `collection`, `recognize` |
+| `howto/controller.md` | `params`, `before_action`, `after_action`, `around_action`, `rescue_from`, `render` |
+| `howto/resource.md` | CRUD methods, typed vs dynamic attributes, dirty tracking, validations, `.with` |
+| `howto/middleware_client.md` | Client-side middlewares: built-ins, custom, usage in Client and Resource |
+| `howto/middleware_consumer.md` | Consumer-side middlewares: execution order, writing, registering |
+| `howto/tracing.md` | Trace context propagation: `rpc_reply_headers`, `on_rpc_reply`, consumer middleware |
+| `howto/rails.md` | Full Rails setup: initializer, connection pool, Zeitwerk, Puma, Sidekiq, K8s health checks |
+| `howto/testing.md` | Bunny doubles, unit tests for controllers/middleware, integration helper |
+
+These files are referenced by `README.md`. Update them before updating the README.
+
+---
+
+## AI documentation (agents consuming or maintaining BugBunny)
+
+Managed by `docs/ai/_index.md`. See that file for the full manifest and audience breakdown.
+
+| File | Audience | Purpose |
+|---|---|---|
+| `ai/_index.md` | internal + external | Manifest: version, profile, file index |
+| `ai/glossary.md` | internal + external | Domain terms with precise definitions |
+| `ai/architecture.md` | internal | Internal patterns, component map, data flows |
+| `ai/api.md` | external | Public API contracts |
+| `ai/faq_internal.md` | internal | Q&A for gem maintainers |
+| `ai/faq_external.md` | external | Q&A for gem integrators |
+| `ai/antipatterns.md` | internal + external | What NOT to do and why |
+| `ai/errors.md` | external | All exceptions with cause and resolution |
+
+---
+
+## Update rules for `/release`
+
+1. Run tests first. If they fail, stop.
+2. Read this file to discover all files to update.
+3. For each file in **Human documentation**: update only sections affected by the changes in this release.
+4. For each file in **AI documentation**: update only sections affected by the changes. Update `version` in `ai/_index.md`.
+5. Update `README.md` last — it depends on `docs/howto/` being up to date.
+6. Show the full diff to the developer and wait for approval before touching version or CHANGELOG.

data/docs/ai/_index.md

@@ -0,0 +1,56 @@
+---
+type: knowledge_base
+kind: gem
+name: bug_bunny
+version: 4.8.0
+profile: full
+language: ruby
+generated_by: gem-ai-setup@1.0.0
+audiences:
+  - internal
+  - external
+files:
+  - path: glossary.md
+    audience: [internal, external]
+  - path: architecture.md
+    audience: [internal]
+  - path: api.md
+    audience: [external]
+  - path: faq_internal.md
+    audience: [internal]
+  - path: faq_external.md
+    audience: [external]
+  - path: antipatterns.md
+    audience: [internal, external]
+  - path: errors.md
+    audience: [external]
+---
+
+## What is BugBunny?
+
+BugBunny is a Ruby gem that implements a RESTful routing layer over AMQP (RabbitMQ). It lets microservices communicate via RabbitMQ using familiar HTTP patterns: verbs (GET, POST, PUT, DELETE), controllers, declarative routes, synchronous RPC, and fire-and-forget.
+
+**Problem solved:** Eliminates direct HTTP coupling between microservices. RabbitMQ acts as the message bus with the same ergonomics as a web framework.
+
+## Version
+
+4.8.0 — April 2026
+
+## Key features in this version
+
+- Namespace routing (`namespace :admin { resources :users }`)
+- `after_action` filter (runs after action, not after `before_action` halts)
+- `render(headers:)` — inject custom headers into RPC replies
+- `Consumer#shutdown` — explicit graceful shutdown with health check cleanup
+- `Configuration#validate!` — invoked automatically at end of `BugBunny.configure`
+- Producer/Session caching per connection slot (prevents double-consumer AMQP error)
+- Expanded `SENSITIVE_KEYS` filter in `safe_log`
+- `ConsumerMiddleware::Stack` mutex for thread-safe registration
+
+## How to use this knowledge base
+
+- **Building an integration** → start with `api.md`, then `faq_external.md`
+- **Debugging errors** → `errors.md`
+- **Avoiding mistakes** → `antipatterns.md`
+- **Understanding internals** → `architecture.md`, then `faq_internal.md`
+- **Domain vocabulary** → `glossary.md`