bug_bunny 4.8.0 → 4.8.1

data/skill/references/client-middleware.md

@@ -0,0 +1,144 @@
+# 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.
+
+## 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,104 @@
+# 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. Valida que el mensaje tenga header `type` (path).
+3. Parsea el método HTTP de headers (`x-http-method` o `method`).
+4. Reconoce la ruta con `BugBunny.routes.recognize(method, path)`.
+5. Resuelve el controlador validando herencia de `BugBunny::Controller`.
+6. Ejecuta consumer middlewares → controller callbacks → acción.
+7. Responde via `reply_to` si está presente (RPC).
+8. Hace `ack` del mensaje. En caso de error, `reject`.
+
+## 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

data/skill/references/errores.md

@@ -0,0 +1,97 @@
+# Catálogo de Errores
+
+## Jerarquía
+
+```
+StandardError
+└── BugBunny::Error
+    ├── BugBunny::CommunicationError
+    ├── BugBunny::ConfigurationError
+    ├── BugBunny::SecurityError
+    ├── BugBunny::ClientError (4xx)
+    │   ├── BugBunny::BadRequest (400)
+    │   ├── BugBunny::NotFound (404)
+    │   ├── BugBunny::NotAcceptable (406)
+    │   ├── BugBunny::RequestTimeout (408)
+    │   ├── BugBunny::Conflict (409)
+    │   └── BugBunny::UnprocessableEntity (422)
+    └── BugBunny::ServerError (5xx)
+        └── BugBunny::InternalServerError (500+)
+```
+
+## Errores de Infraestructura
+
+### BugBunny::CommunicationError
+**Causa:** Fallo de conexión TCP/AMQP o reconexión agotada (`max_reconnect_attempts`).
+**Cuándo:** Al intentar publicar o consumir sin conexión activa, o tras agotar intentos de reconexión.
+**Resolución:** Verificar conectividad a RabbitMQ (host, port, firewall). Revisar logs `event=session.reconnect_failed`. Ajustar `max_reconnect_attempts` y `max_reconnect_interval`.
+
+### BugBunny::ConfigurationError
+**Causa:** Campo requerido faltante o valor fuera de rango en `BugBunny.configure`.
+**Validaciones:** host (String no vacío), port (1-65535), username/password (no nil), heartbeat (0-3600), rpc_timeout (>0), channel_prefetch (1-10000).
+**Resolución:** Revisar el bloque `BugBunny.configure` y corregir valores.
+
+### BugBunny::SecurityError
+**Causa:** Un mensaje intenta ejecutar un controlador que no hereda de `BugBunny::Controller`.
+**Cuándo:** El consumer resuelve la clase pero falla la validación `is_a?(BugBunny::Controller)`.
+**Resolución:** Verificar que el controlador herede de `BugBunny::Controller` y que `config.controller_namespace` sea correcto.
+
+## Errores de Cliente (4xx)
+
+### BugBunny::BadRequest (400)
+**Causa:** Request malformado o sintaxis inválida.
+**Resolución:** Verificar formato del body y headers.
+
+### BugBunny::NotFound (404)
+**Causa:** El recurso solicitado no existe en el servicio remoto.
+**Resolución:** Verificar ID del recurso y que el endpoint exista.
+
+### BugBunny::NotAcceptable (406)
+**Causa:** Negociación de contenido falló.
+**Resolución:** Verificar `content_type` del request.
+
+### BugBunny::RequestTimeout (408)
+**Causa:** No hubo respuesta en `config.rpc_timeout` segundos.
+**Cuándo:** El `Concurrent::IVar` expira sin recibir reply.
+**Resolución:** Verificar que el worker esté activo. Revisar saturación de prefetch. Aumentar `rpc_timeout` si el procesamiento es legítimamente lento.
+
+### BugBunny::Conflict (409)
+**Causa:** Conflicto de regla de negocio (ej: recurso ya existe, versión desactualizada).
+**Resolución:** Reintentar tras refrescar el estado del recurso.
+
+### BugBunny::UnprocessableEntity (422)
+**Causa:** Fallo de validación en el servicio remoto.
+**Acceso a errores:**
+```ruby
+begin
+  order.save
+rescue BugBunny::UnprocessableEntity => e
+  e.error_messages   # Hash, Array o String con detalles
+  e.raw_response     # Response original completo
+end
+```
+**Smart extraction:** Busca `errors`, `error`, `detail`, `message` en el body. Formatea como Hash descriptivo si no encuentra convención.
+**En Resource:** `save` captura 422 automáticamente, carga `resource.errors` y retorna `false`.
+
+## Errores de Servidor (5xx)
+
+### BugBunny::InternalServerError (500+)
+**Causa:** Error no controlado en el servicio remoto.
+**Resolución:** Revisar logs del servicio remoto. Verificar backtrace en `event=controller.unhandled_exception`.
+
+### BugBunny::ServerError (base 5xx)
+**Causa:** Cualquier error de servidor no mapeado a InternalServerError.
+**Resolución:** Similar a InternalServerError.
+
+## Formato de Mensajes de Error
+
+El middleware `RaiseError` construye el mensaje así:
+1. Busca `{ "error": "...", "detail": "..." }` en el body.
+2. Si no encuentra, usa el Hash completo como JSON.
+3. Si el body está vacío, usa `"Unknown Error"`.
+
+## Connection Pool Missing
+
+**No es una excepción BugBunny**, pero es un error común:
+**Causa:** Se intentó usar un Resource sin asignar el pool global.
+**Resolución:** Asegurar que `BugBunny::Resource.connection_pool = MY_POOL` se ejecute en el arranque.

data/skill/references/resource.md

@@ -0,0 +1,116 @@
+# Resources
+
+## Definición
+
+```ruby
+class Order < BugBunny::Resource
+  # Infraestructura AMQP
+  @connection_pool = MY_POOL
+  @exchange = 'orders_ex'
+  @exchange_type = 'topic'
+  @resource_name = 'orders'        # path en la URL
+  @routing_key = 'orders.#'
+  @param_key = 'order'             # wrapper key en payloads
+  @exchange_options = { durable: true }
+  @queue_options = { auto_delete: false }
+
+  # Atributos tipados (ActiveModel::Attributes)
+  attribute :id, :integer
+  attribute :status, :string
+  attribute :total, :decimal
+  attribute :active, :boolean
+
+  # Validaciones (ActiveModel::Validations)
+  validates :status, presence: true
+
+  # Callbacks
+  before_save :normalize_status
+  after_create :notify_warehouse
+  around_destroy :audit_deletion
+
+  # Middleware client-side
+  client_middleware do |stack|
+    stack.use BugBunny::Middleware::RaiseError
+    stack.use BugBunny::Middleware::JsonResponse
+  end
+end
+```
+
+## Operaciones CRUD
+
+### Class Methods
+
+```ruby
+Order.find(42)                           # GET orders/42 → Order
+Order.where(status: 'active')            # GET orders?status=active → [Order, ...]
+Order.all                                # GET orders → [Order, ...]
+Order.create(status: 'pending', total: 100) # POST orders → Order
+```
+
+### Instance Methods
+
+```ruby
+order = Order.new(status: 'pending')
+order.save                               # POST orders (nuevo) o PUT orders/42 (existente)
+order.update(status: 'shipped')          # assign + save
+order.destroy                            # DELETE orders/42
+order.persisted?                         # true si fue guardado
+order.changed?                           # true si tiene cambios sin guardar
+order.errors                             # ActiveModel::Errors
+```
+
+### Save: Create vs Update
+
+- **Nuevo** (`persisted? == false`): Envía POST con todos los atributos.
+- **Existente** (`persisted? == true`): Envía PUT solo con atributos cambiados (`changes_to_send`).
+- Captura `BugBunny::UnprocessableEntity` (422) y carga `resource.errors`. Retorna `false`.
+
+## Contexto Dinámico (.with)
+
+### Forma de bloque (recomendada)
+
+```ruby
+Order.with(exchange: 'priority_ex', routing_key: 'priority.orders') do
+  Order.all                    # Usa config temporal
+  Order.find(1)                # También usa config temporal
+end
+# Config restaurada automáticamente
+```
+
+### Forma de cadena (single use)
+
+```ruby
+order = Order.with(pool: special_pool).find(42)
+# Siguiente llamada requiere nuevo .with()
+```
+
+**Antipatrón:** No guardar el proxy en variable para múltiples llamadas → lanza error.
+
+## Change Tracking
+
+Combina `ActiveModel::Dirty` con atributos dinámicos:
+
+```ruby
+order = Order.find(42)
+order.name = 'New Name'              # Atributo definido
+order.custom_field = 'value'         # Atributo dinámico
+order.changed                        # → ['name', 'custom_field']
+order.changes_to_send                # → { 'name' => 'New Name', 'custom_field' => 'value' }
+```
+
+## Callbacks Disponibles
+
+Definidos con `define_model_callbacks`:
+- `:save` — before/after/around save (create o update)
+- `:create` — before/after/around create (recurso nuevo)
+- `:update` — before/after/around update (recurso existente)
+- `:destroy` — before/after/around destroy
+
+## Coerción de Tipos
+
+Los atributos tipados usan `ActiveModel::Attributes`:
+- `'25.50'` → `BigDecimal` (con `:decimal`)
+- `'1'` / `'true'` → `true` (con `:boolean`)
+- `'2026-04-01T...'` → `Time` (con `:time`)
+
+Los atributos dinámicos (no declarados) se almacenan sin coerción.

data/skill/references/routing.md

@@ -0,0 +1,82 @@
+# Routing
+
+## DSL Completo
+
+```ruby
+BugBunny.routes.draw do
+  # Verbos HTTP individuales
+  get    'health',       to: 'health#check'
+  post   'events',       to: 'events#create'
+  put    'settings',     to: 'settings#update'
+  patch  'settings',     to: 'settings#patch'
+  delete 'cache',        to: 'cache#clear'
+
+  # Resources genera 5 rutas REST
+  resources :users
+  # GET    users      → UsersController#index
+  # GET    users/:id  → UsersController#show
+  # POST   users      → UsersController#create
+  # PUT    users/:id  → UsersController#update
+  # DELETE users/:id  → UsersController#destroy
+
+  # Filtros
+  resources :orders, only: [:index, :show]
+  resources :products, except: [:destroy]
+
+  # Namespaces (anidables)
+  namespace :admin do
+    namespace :v2 do
+      resources :reports   # → Admin::V2::ReportsController
+    end
+  end
+
+  # Member y Collection
+  resources :nodes do
+    member do
+      put :drain           # PUT nodes/:id/drain → NodesController#drain
+      post :restart        # POST nodes/:id/restart → NodesController#restart
+    end
+    collection do
+      get :stats           # GET nodes/stats → NodesController#stats
+      get :health          # GET nodes/health → NodesController#health
+    end
+  end
+end
+```
+
+## Route Matching
+
+El `RouteSet#recognize(method, path)` busca la primera ruta que matchee:
+
+- **Normalización:** Strips leading/trailing slashes del path.
+- **Parámetros:** `:id` se compila a regex `(?<id>[^/]+)`. Los valores se extraen como Hash.
+- **No match:** Retorna `nil` → el consumer responde 404.
+
+```ruby
+route = BugBunny.routes.recognize('GET', 'users/42')
+route.controller  # => "users"
+route.action      # => "show"
+route.namespace   # => nil
+route.params      # => { 'id' => '42' }
+```
+
+## Resolución de Controller
+
+El consumer resuelve el controlador concatenando:
+1. `config.controller_namespace` (default: `BugBunny::Controllers`)
+2. `route.namespace` (si existe)
+3. `route.controller.classify + "Controller"`
+
+Ejemplo: namespace `:admin`, controller `:reports` → `BugBunny::Controllers::Admin::ReportsController`
+
+Valida que el controlador sea subclase de `BugBunny::Controller`. Si no, lanza `SecurityError`.
+
+## Route Object
+
+```ruby
+route.http_method       # String: "GET", "POST", etc.
+route.path_pattern      # String: "users/:id"
+route.controller        # String: "users"
+route.action            # String: "show"
+route.namespace         # String o nil: "Admin::V2"
+```