bug_bunny 4.8.0 → 4.9.0

data/skill/SKILL.md

@@ -0,0 +1,253 @@
+# BugBunny Expert
+
+Skill de conocimiento completo sobre BugBunny. Consultame para cualquier pregunta sobre integración, arquitectura, API, errores y antipatrones.
+
+---
+
+## Glosario
+
+**AMQP** — Advanced Message Queuing Protocol. Protocolo binario que implementa RabbitMQ.
+**Bunny** — Cliente Ruby para AMQP. BugBunny lo usa internamente para conexiones, canales y publicación.
+**Exchange** — Recibe mensajes del producer y los enruta a queues según reglas. Tipos: `direct` (match exacto), `topic` (wildcards), `fanout` (broadcast).
+**Queue** — Almacena mensajes hasta que un consumer los consume. Las queues durables sobreviven reinicios del broker.
+**Routing Key** — String que el producer adjunta al mensaje. El exchange lo usa para decidir a qué queues enrutar.
+**Binding** — Enlace entre un exchange y una queue, opcionalmente con un patrón de routing key.
+**Session** — `BugBunny::Session` envuelve canales de Bunny con thread-safety y double-checked locking.
+**RPC** — Patrón síncrono que usa la pseudo-cola `amq.rabbitmq.reply-to` para respuestas sin crear queues temporales.
+**Fire-and-Forget** — Patrón asíncrono donde el producer publica y continúa sin esperar respuesta. Retorna `{ 'status' => 202 }`.
+**Resource** — ORM tipo ActiveRecord que mapea operaciones CRUD a llamadas AMQP.
+**Consumer** — Worker bloqueante que despacha mensajes a controladores mediante un Router.
+**Connection Pool** — Pool de conexiones (`connection_pool` gem) que comparte sessions entre threads. Cada slot cachea su `Session` y `Producer`.
+
+---
+
+## Arquitectura: Flujo RPC
+
+```
+┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
+│ Resource  │────>│  Client  │────>│ Middleware│────>│ Producer │
+└──────────┘     └──────────┘     │  Stack   │     └────┬─────┘
+                                  └──────────┘          │
+                                                        ▼
+                                                  ┌──────────┐
+                                                  │ Exchange  │
+                                                  └────┬─────┘
+                                                       │
+                                                       ▼
+                                                  ┌──────────┐
+                                                  │  Queue   │
+                                                  └────┬─────┘
+                                                       │
+                                                       ▼
+┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
+│  Reply   │<────│Controller│<────│  Router  │<────│ Consumer │
+└──────────┘     └──────────┘     └──────────┘     └──────────┘
+```
+
+1. El `Client` pasa la petición por una pila de middlewares client-side.
+2. El `Producer` publica en el exchange con `correlation_id`, `reply_to` y el path en el header `type`.
+3. El hilo emisor se bloquea en un `Concurrent::IVar` esperando la respuesta.
+4. El `Consumer` recibe, ejecuta consumer middlewares, rutea al controller.
+5. El controller ejecuta callbacks y la acción, luego responde via `reply_to`.
+6. Se aplican ganchos de traza (`on_rpc_reply`) y se devuelve el objeto hidratado.
+
+---
+
+## Arquitectura: Componentes Clave
+
+| Clase | Responsabilidad |
+|---|---|
+| `BugBunny::Configuration` | Configuración global. Valida campos requeridos en `BugBunny.configure`. |
+| `BugBunny::Session` | Wrapper de canal Bunny. Declara exchanges y queues. Thread-safe con double-checked locking. |
+| `BugBunny::Producer` | Publica mensajes. Implementa RPC con `Concurrent::IVar` y direct reply-to. |
+| `BugBunny::Client` | API de alto nivel. Pool de conexiones y middleware stack (onion architecture). |
+| `BugBunny::Consumer` | Subscribe loop con health check. Rutea mensajes via `BugBunny.routes`. |
+| `BugBunny::ConsumerMiddleware::Stack` | Pipeline de middlewares antes de `process_message`. Thread-safe. |
+| `BugBunny::Controller` | Base class tipo Rails. `before_action`, `around_action`, `after_action`, `rescue_from`, `render`. |
+| `BugBunny::Resource` | ORM sobre AMQP. `find`, `where`, `create`, `save`, `destroy`. ActiveModel validations y callbacks. |
+| `BugBunny::Routing::RouteSet` | DSL de rutas: `resources`, `namespace`, `member`, `collection`. |
+| `BugBunny::Observability` | Mixin de logging estructurado. `safe_log` nunca lanza excepciones. Filtra keys sensibles. |
+| `BugBunny::Middleware::Stack` | Builder de middlewares client-side (onion architecture tipo Faraday). |
+| BugBunny::Request | Value object del mensaje saliente con metadata AMQP completa. |
+| BugBunny::OTel | Helpers para emitir campos siguiendo las OTel semantic conventions for messaging. |
+| BugBunny::Railtie | Integración Rails: autoload de `app/rabbit`, fork safety (Puma, Spring). |
+
+---
+
+## Observability: OpenTelemetry
+
+BugBunny implementa las [OpenTelemetry semantic conventions for messaging](https://opentelemetry.io/docs/specs/otel/trace/semantic-conventions/messaging/) de forma nativa para garantizar la trazabilidad entre servicios en entornos distribuidos.
+
+### Campos Estándar (Flat-naming)
+
+| Campo | Valor / Origen | Propósito |
+|---|---|---|
+| `messaging_system` | `"rabbitmq"` | Identifica el broker. |
+| `messaging_operation` | `"publish"`, `"receive"`, `"process"` | Tipo de interacción. |
+| `messaging_destination_name` | `exchange_name` | Exchange destino (o `""` para default). |
+| `messaging_routing_key` | `routing_key` | Clave de ruteo final. |
+| `messaging_message_id` | `correlation_id` | ID único para correlación y traza. |
+
+### Inyección y Extracción
+
+- **Publisher:** Inyecta estos campos en los headers AMQP bajo el prefijo `messaging_`. El usuario puede sobrescribirlos como *escape hatch* desde `headers`.
+- **Consumer:** Extrae los campos de los logs estructurados sin mutar los headers originales. Los eventos `consumer.message_received` y `consumer.message_processed` incluyen estos campos automáticamente.
+- **RPC Reply:** El consumer inyecta los mismos campos en el reply para cerrar el ciclo de traza del lado del cliente.
+
+---
+
+## API: Configuración Global
+
+```ruby
+BugBunny.configure do |config|
+  # Conexión
+  config.host = 'localhost'          # default: '127.0.0.1'
+  config.port = 5672                 # default: 5672
+  config.username = 'guest'          # default: 'guest'
+  config.password = 'guest'          # default: 'guest'
+  config.vhost = '/'                 # default: '/'
+
+  # Resiliencia
+  config.automatically_recover = true
+  config.network_recovery_interval = 5
+  config.max_reconnect_attempts = nil  # nil = infinito
+  config.connection_timeout = 10
+  config.heartbeat = 15
+
+  # Performance
+  config.channel_prefetch = 1
+  config.rpc_timeout = 10
+
+  # Logging
+  config.logger = Rails.logger
+  config.log_tags = [:uuid]
+
+  # Propagación de trazas
+  config.rpc_reply_headers = -> { { 'X-Trace-Id' => Tracer.id } }
+  config.on_rpc_reply = ->(h) { Tracer.hydrate(h['X-Trace-Id']) }
+
+  # Infraestructura (cascade level 2)
+  config.exchange_options = { durable: true }
+  config.queue_options = { auto_delete: false }
+
+  # Health check
+  config.health_check_interval = 60
+  config.health_check_file = 'tmp/bb_health'
+
+  # Routing
+  config.controller_namespace = 'BugBunny::Controllers'
+end
+```
+
+La validación es automática tras el bloque; lanza `ConfigurationError` si faltan campos requeridos o los valores están fuera de rango.
+
+---
+
+## API: Routing DSL
+
+```ruby
+BugBunny.routes.draw do
+  resources :users
+  resources :orders, only: [:index, :show]
+  resources :products, except: [:destroy]
+
+  namespace :admin do
+    resources :reports
+    resources :nodes do
+      member do
+        put :drain           # PUT nodes/:id/drain
+      end
+      collection do
+        get :stats           # GET nodes/stats
+      end
+    end
+  end
+end
+```
+
+Genera rutas REST estándar (index, show, create, update, destroy) mapeadas a controladores. El `namespace` añade prefijo al path y busca controladores dentro del módulo correspondiente.
+
+---
+
+## API: RPC vs Fire-and-Forget
+
+**RPC síncrono** — Bloquea hasta respuesta. Usa `amq.rabbitmq.reply-to`. Timeout configurable.
+```ruby
+response = client.request('users/42', method: :get)
+# → { 'status' => 200, 'body' => { 'id' => 42, 'name' => 'John' } }
+```
+
+**Fire-and-Forget** — Publica y continúa. Sin confirmación.
+```ruby
+client.publish('events', method: :post, body: { type: 'order.placed' })
+# → { 'status' => 202, 'body' => nil }
+```
+
+---
+
+## FAQ
+
+### ¿Cómo se integra con Rails?
+`rails generate bug_bunny:install` genera el inicializador, crea `app/bug_bunny/controllers/` y actualiza `CLAUDE.md`. El pool se define en el inicializador y se asigna a `BugBunny::Resource.connection_pool`.
+
+### ¿Cómo funciona el Health Check?
+El consumer ejecuta un check periódico (default 60s) que verifica la conexión AMQP con un `queue.declare(passive: true)`. Si `health_check_file` está configurado, actualiza su mtime. En Kubernetes, usar un `livenessProbe` tipo `exec` que verifique recencia del archivo.
+
+### ¿Cómo funciona el Connection Pool?
+Cada slot del pool cachea su `Session` y `Producer` durante su vida útil. Esto evita recrear canales AMQP (costoso) y previene el error de doble `basic_consume`. Thread-safety garantizada por `ConnectionPool`.
+
+### ¿Cómo funciona la cascada de configuración?
+3 niveles: Gem defaults → Global config (`BugBunny.configure`) → Per-request (args en `client.request` o `Resource.with`). Se mergean con `merge`.
+
+### ¿Cómo funciona fork safety?
+`BugBunny::Railtie` registra hooks en `ActiveSupport::ForkTracker` (Rails 7.1+), `Puma.events.on_worker_boot` y `Spring.after_fork` para llamar `BugBunny.disconnect` y evitar sockets TCP heredados.
+
+---
+
+## Antipatrones
+
+### Consumer en Puma
+No ejecutar el `Consumer` dentro de hilos de Puma. Es un bucle bloqueante que saturará el servidor web. Usar un proceso worker dedicado o una tarea Rake separada.
+
+### Reasignación de Pool en Runtime
+No asignar `Resource.connection_pool` dentro de controllers o models durante una petición. Es un ajuste global que causa condiciones de carrera y fugas de conexiones.
+
+### Abuso de .with persistente
+No guardar el resultado de `Order.with(...)` en una variable para múltiples llamadas. Lanzará error tras la primera ejecución. Para múltiples llamadas, usar siempre la forma de bloque.
+
+### Registrar middleware durante call()
+No registrar consumer middlewares durante la ejecución de `call()`. El stack toma un snapshot al inicio; los registros concurrentes no afectan la ejecución actual.
+
+---
+
+## Errores Comunes
+
+### BugBunny::RequestTimeout (408)
+**Causa:** No hubo respuesta en `config.rpc_timeout` segundos.
+**Resolución:** Verificar que el worker esté activo y que el controlador remoto no lance excepciones silenciosas.
+
+### BugBunny::SecurityError
+**Causa:** El mensaje intenta ejecutar un controlador que no hereda de `BugBunny::Controller`.
+**Resolución:** Verificar la jerarquía de controladores y que `config.controller_namespace` coincida.
+
+### BugBunny::UnprocessableEntity (422)
+**Causa:** Fallo de validación en el servicio remoto.
+**Resolución:** `resource.save` devuelve `false`. Acceder a `resource.errors` o `rescue` con `e.error_messages`.
+
+### BugBunny::CommunicationError
+**Causa:** Fallo de conexión o reconexión agotada.
+**Resolución:** Verificar conectividad a RabbitMQ. Revisar `max_reconnect_attempts` y logs de reconexión.
+
+Ver catálogo completo en [Errores](references/errores.md).
+
+---
+
+## Referencias
+
+- [Routing](references/routing.md) — DSL de rutas, bindings, namespaces, member y collection
+- [Controllers](references/controller.md) — Acciones, callbacks, render, rescue_from y log tags
+- [Resources](references/resource.md) — CRUD sobre AMQP, .with, callbacks y change tracking
+- [Client y Middleware](references/client-middleware.md) — Client, Producer, middleware stack onion
+- [Consumer](references/consumer.md) — Subscribe loop, consumer middleware, health check
+- [Catálogo de Errores](references/errores.md) — Jerarquía completa de excepciones con resolución
+- [Testing](references/testing.md) — RSpec helpers, mocks, patrones de integración

data/skill/references/client-middleware.md

@@ -0,0 +1,161 @@
+# Client y Middleware
+
+## Client
+
+API de alto nivel para publicar mensajes. Usa un pool de conexiones y una pila de middlewares.
+
+### Métodos Principales
+
+```ruby
+# RPC síncrono — bloquea hasta respuesta
+response = client.request('users/123', method: :get, timeout: 30)
+response = client.request('users', method: :post, body: { name: 'John' })
+# → { 'status' => 200, 'body' => {...} }
+
+# Fire-and-Forget — no bloquea
+client.publish('events/user_created', method: :post, body: { user_id: 42 })
+# → { 'status' => 202, 'body' => nil }
+
+# General con bloque
+client.send(url) { |req| req.delivery_mode = :publish }
+```
+
+### Argumentos de Request
+
+| Argumento | Tipo | Default | Propósito |
+|-----------|------|---------|-----------|
+| `method` | Symbol | `:get` | Verbo HTTP |
+| `body` | Hash/String | nil | Payload del mensaje |
+| `headers` | Hash | {} | Headers AMQP custom |
+| `params` | Hash | {} | Query string params |
+| `timeout` | Integer | config | Override de RPC timeout |
+| `exchange` | String | config | Exchange destino |
+| `exchange_type` | String | 'direct' | Tipo de exchange |
+| `routing_key` | String | path | Override de routing key |
+| `exchange_options` | Hash | {} | Cascade level 3 |
+| `queue_options` | Hash | {} | Cascade level 3 |
+
+## Producer (bajo nivel)
+
+El `Producer` es usado internamente por el `Client`. Implementa los dos patrones de entrega.
+
+### RPC
+
+- Usa `amq.rabbitmq.reply-to` (direct reply-to pattern).
+- Tracking de `correlation_id` en `Concurrent::Map` (thread-safe).
+- Reply listener (`basic_consume`) auto-iniciado en el primer RPC.
+- Double-checked locking mutex para seguridad del listener.
+- Timeout lanza `BugBunny::RequestTimeout`.
+
+### Fire-and-Forget
+
+- Publica en el exchange y retorna `{ 'status' => 202 }` inmediatamente.
+- Sin confirmación de procesamiento.
+
+## Middleware Stack (Client-side, Onion Architecture)
+
+```
+Request  ─→ RaiseError ─→ JsonResponse ─→ Custom ─→ Producer
+Response ←─ RaiseError ←─ JsonResponse ←─ Custom ←─
+```
+
+### Registrar Middlewares
+
+```ruby
+class Order < BugBunny::Resource
+  client_middleware do |stack|
+    stack.use BugBunny::Middleware::RaiseError
+    stack.use BugBunny::Middleware::JsonResponse
+    stack.use MyCustomMiddleware
+  end
+end
+```
+
+### Crear un Middleware Custom
+
+```ruby
+class MyMiddleware < BugBunny::Middleware::Base
+  def on_request(env)
+    # Modificar request antes de enviar
+    env.headers['X-Custom'] = 'value'
+  end
+
+  def on_complete(response)
+    # Modificar response después de recibir
+    response['body'] = transform(response['body'])
+  end
+end
+```
+
+El método `call` del `Base` invoca `on_request`, delega a `@app.call`, y luego `on_complete`.
+
+### Middlewares Incluidos
+
+**RaiseError** — Mapea status HTTP a excepciones:
+
+| Status | Excepción |
+|--------|-----------|
+| 200-299 | (ninguna) |
+| 400 | `BadRequest` |
+| 404 | `NotFound` |
+| 406 | `NotAcceptable` |
+| 408 | `RequestTimeout` |
+| 409 | `Conflict` |
+| 422 | `UnprocessableEntity` (con smart extraction de errors) |
+| 500+ | `InternalServerError` / `ServerError` |
+| 4xx otros | `ClientError` |
+
+**JsonResponse** — Auto-parsea `response['body']` de String a Hash/Array. Aplica `HashWithIndifferentAccess` si disponible.
+
+## OpenTelemetry: Publisher Injection
+
+El `Producer` (vía `Request#amqp_options`) inyecta automáticamente los campos de OTel semantic conventions en los headers AMQP del mensaje saliente.
+
+```ruby
+# Headers inyectados automáticamente
+{
+  'messaging_system' => 'rabbitmq',
+  'messaging_operation' => 'publish',
+  'messaging_destination_name' => 'exchange_name',
+  'messaging_routing_key' => 'rk',
+  'messaging_message_id' => 'uuid'
+}
+```
+
+El orden de merge es: **OTel base** → **headers del usuario** → **x-http-method**. Esto permite al desarrollador sobrescribir valores de OTel si es necesario, pero garantiza que el ruteo interno (`x-http-method`) se mantenga íntegro.
+
+## Request Object
+
+Value object con toda la metadata AMQP:
+
+```ruby
+req.path                  # 'users/123'
+req.method                # :get
+req.body                  # Hash, Array, String o nil
+req.headers               # Hash custom
+req.params                # Hash query string
+req.full_path             # path + query string
+req.delivery_mode         # :rpc o :publish
+req.exchange              # String destino
+req.exchange_type         # 'direct', 'topic', 'fanout'
+req.correlation_id        # UUID auto-generado
+req.reply_to              # 'amq.rabbitmq.reply-to' (auto para RPC)
+req.timestamp             # Time.now.to_i
+req.content_type          # 'application/json'
+```
+
+## Cascada de Configuración (3 niveles)
+
+```ruby
+# Level 1: Gem defaults
+{ durable: false, auto_delete: false }   # exchanges
+{ exclusive: false, durable: false, auto_delete: true }  # queues
+
+# Level 2: Global config
+BugBunny.configure { |c| c.exchange_options = { durable: true } }
+
+# Level 3: Per-request
+client.request('users', exchange_options: { durable: true })
+
+# Merge final: Level1.merge(Level2).merge(Level3)
+```

data/skill/references/consumer.md

@@ -0,0 +1,122 @@
+# Consumer
+
+## Subscribe
+
+```ruby
+consumer = BugBunny::Consumer.subscribe(
+  connection: bunny_session,
+  queue_name: 'my_app_queue',
+  exchange_name: 'my_exchange',
+  routing_key: 'users.*',
+  exchange_type: 'topic',
+  exchange_opts: { durable: true },
+  queue_opts: { auto_delete: false },
+  block: true   # Si false, retorna inmediatamente
+)
+```
+
+## Flujo de Procesamiento
+
+1. Escucha en la queue con `manual_ack: true`.
+2. Extrae campos **OTel messaging** del mensaje para logs estructurados (sin mutar headers).
+3. Valida que el mensaje tenga header `type` (path).
+4. Parsea el método HTTP de headers (`x-http-method` o `method`).
+5. Emite log `consumer.message_received` con campos OTel (`messaging_operation: 'process'`).
+6. Reconoce la ruta con `BugBunny.routes.recognize(method, path)`.
+7. Resuelve el controlador validando herencia de `BugBunny::Controller`.
+8. Ejecuta consumer middlewares → controller callbacks → acción.
+9. Responde via `reply_to` si está presente (RPC), inyectando campos OTel (`messaging_operation: 'publish'`).
+10. Emite log `consumer.message_processed` con campos OTel y duraciones.
+11. Hace `ack` del mensaje. En caso de error, `reject`.
+
+## Observability: OTel Fields
+
+El consumer construye automáticamente el hash de campos OTel al inicio de `process_message`:
+
+```ruby
+otel_fields = BugBunny::OTel.messaging_headers(
+  operation: 'process',
+  destination: delivery_info.exchange,
+  routing_key: delivery_info.routing_key,
+  message_id: properties.correlation_id
+)
+```
+
+Estos campos se mergean en todos los eventos de log del ciclo de vida del mensaje, permitiendo que ExisRay los rastree sin necesidad de propagarlos manualmente en los headers del usuario.
+
+## Lifecycle
+
+```ruby
+consumer.shutdown          # Cierra canal, detiene health check
+consumer.session           # Accede al Session subyacente
+```
+
+## Consumer Middleware
+
+### Registrar
+
+```ruby
+BugBunny.configuration.consumer_middlewares.use MyTracing::Middleware
+BugBunny.configuration.consumer_middlewares.use MyAuth::Middleware
+```
+
+### Crear Middleware
+
+```ruby
+class MyMiddleware < BugBunny::ConsumerMiddleware::Base
+  def call(delivery_info, properties, body)
+    # Pre-procesamiento (ej: hidratar trace context)
+    @app.call(delivery_info, properties, body)
+    # Post-procesamiento (ej: cleanup)
+  end
+end
+```
+
+### Comportamiento del Stack
+
+- El stack toma un **snapshot** al inicio de `call()`.
+- Registros concurrentes durante la ejecución NO afectan la cadena actual.
+- Thread-safe para registros con `use()`.
+- Orden FIFO: el primero registrado es el primero en ejecutar.
+
+```ruby
+stack.use(A)   # A.call → B.call → core
+stack.use(B)
+stack.empty?   # false
+```
+
+## Health Check
+
+- **Intervalo:** Configurable (default 60s).
+- **Verificación:** `queue.declare(passive: true)` para confirmar conexión.
+- **Touchfile:** Si `config.health_check_file` está configurado, actualiza mtime.
+- **Fallo:** Cierra canal, dispara loop de reconexión.
+
+### Kubernetes Integration
+
+```yaml
+livenessProbe:
+  exec:
+    command:
+      - test
+      - -f
+      - /app/tmp/bb_health
+  initialDelaySeconds: 30
+  periodSeconds: 60
+```
+
+## Reconexión
+
+- Exponential backoff desde `network_recovery_interval` hasta `max_reconnect_interval`.
+- Intentos limitados por `max_reconnect_attempts` (nil = infinito).
+- Logs estructurados en cada intento: `event=session.reconnect_attempt`.
+- Si se agotan intentos: `event=consumer.reconnect_exhausted`, lanza `CommunicationError`.
+
+## Manejo de Errores
+
+| Situación | Respuesta |
+|-----------|-----------|
+| Ruta no encontrada | 404 + log `event=consumer.route_not_found` |
+| Controller no encontrado (namespace) | 404 + log `event=consumer.controller_not_found` |
+| Controller no hereda de BugBunny::Controller | `SecurityError` |
+| Excepción no capturada en controller | 500 + log `event=controller.unhandled_exception` con backtrace |

data/skill/references/controller.md

@@ -0,0 +1,105 @@
+# Controllers
+
+## Estructura Base
+
+```ruby
+class UsersController < BugBunny::Controller
+  before_action :authenticate, only: [:create, :update, :destroy]
+  around_action :with_tracing
+  after_action :log_response, only: [:index, :show]
+  rescue_from BugBunny::NotFound, with: :render_not_found
+
+  def index
+    users = UserService.list(params[:filter])
+    render status: :ok, json: { users: users }
+  end
+
+  def show
+    user = UserService.find(params[:id])
+    render status: :ok, json: user
+  end
+
+  private
+
+  def authenticate
+    render status: :forbidden, json: { error: 'Unauthorized' } unless valid_token?
+  end
+
+  def with_tracing
+    Tracer.start
+    yield
+  ensure
+    Tracer.finish
+  end
+
+  def log_response
+    logger.info("Response: #{rendered_response[:status]}")
+  end
+
+  def render_not_found(exception)
+    render status: :not_found, json: { error: exception.message }
+  end
+end
+```
+
+## Callbacks — Orden de Ejecución
+
+1. `around_action` blocks (capa externa, envuelve todo con `yield`)
+2. `before_action` callbacks (se detiene si se llama `render`)
+3. Acción del controlador
+4. `after_action` callbacks (NO se ejecuta si before_action haltó o si hubo excepción)
+
+## Filtros: only / except
+
+```ruby
+before_action :authenticate, only: [:create, :update]
+after_action :audit, except: [:index]
+```
+
+## rescue_from
+
+Captura excepciones con handler method o bloque:
+
+```ruby
+rescue_from BugBunny::UnprocessableEntity, with: :handle_validation
+rescue_from StandardError do |e|
+  render status: :internal_server_error, json: { error: e.message }
+end
+```
+
+## Atributos Disponibles en el Controller
+
+```ruby
+@headers             # Hash — metadata del mensaje AMQP (method, routing_key, id, etc.)
+@params              # HashWithIndifferentAccess — body JSON + query params unificados
+@raw_string          # String — body crudo si no es JSON
+@response_headers    # Hash — headers para el reply RPC
+@rendered_response   # Hash o nil — respuesta renderizada
+```
+
+## Render
+
+```ruby
+render(status: :ok, json: { users: [...] })
+render(status: 201, json: @user)
+render(status: :unprocessable_entity, json: { errors: @resource.errors }, headers: { 'X-Custom' => 'val' })
+```
+
+Si no se llama `render`, el response default es `{ status: 204, body: nil }`.
+
+## Log Tags
+
+```ruby
+# Global
+BugBunny.configuration.log_tags = [:uuid, :user_id, ->(c) { c.current_user }]
+
+# Por controller
+class UsersController < BugBunny::Controller
+  self.log_tags = [:uuid]
+end
+```
+
+Tipos soportados:
+- **Symbol:** Llama al método del controller (ej: `:uuid` → `self.uuid`)
+- **Proc:** Ejecuta con el controller como argumento
+- **String:** Valor literal