bug_bunny 5.1.0 → 5.2.0

data/skill/SKILL.md

@@ -19,7 +19,11 @@ Gema Ruby: capa de routing RESTful sobre AMQP/RabbitMQ. Microservicios se comuni
 
 ## Contrato resumido (piso mínimo)
 
-> Resume el contrato de **`bug_bunny` 4.18.0**. Suficiente para el uso típico sin abrir el detalle; el detalle version-locked está en [`../docs/behavior/behavior.md`](../docs/behavior/behavior.md) (6 flujos) y [`../docs/glossary/glossary.md`](../docs/glossary/glossary.md) (símbolos→significado). Antipatrones/API completa: más abajo (embebido interim, ver Cobertura y fronteras).
+> Resume el contrato de **`bug_bunny` 5.2.0** (anclado a `v5.2.0`). Suficiente para el uso típico sin abrir el detalle; el detalle version-locked está en el **Índice de artefactos** de abajo. Antipatrones/API completa: más abajo (embebido interim, ver Cobertura y fronteras).
+>
+> **Si venís de 5.1.x, un cambio de conducta (5.2.0):** una entrega cuyo middleware —o `handle_fatal_error`— levanta **antes del ack** ahora se **rechaza sin requeue** (evento `consumer.delivery_failed`), en `subscribe` y en `drain`. Antes quedaba sin ack ni reject y trababa el consumidor. Si un middleware levantaba a propósito para que el mensaje se reintentara, ahora el mensaje se pierde: el reintento es tuyo. Detalle en [`docs/behavior/behavior.md`](../docs/behavior/behavior.md).
+>
+> **Si venís de 4.x, dos breaking a mirar antes de subir:** `5.0.0` eliminó la constante pública `BugBunny::SecurityError` (un `rescue BugBunny::SecurityError` que sobreviva revienta con `NameError` y **enmascara la excepción original**) y `4.18.0` cambió el wrapping `Bunny::Exception` → `CommunicationError`. Detalle en `CHANGELOG.md`.
 
 **Símbolos públicos clave**
 
@@ -27,7 +31,7 @@ Gema Ruby: capa de routing RESTful sobre AMQP/RabbitMQ. Microservicios se comuni
 |---|---|
 | `BugBunny::Client` | `client.request(url, method: :get)` (RPC sync) · `client.publish(url, body:)` (fire-and-forget, 202) · `client.publish(url, confirmed: true, mandatory: true)` (publisher confirms) |
 | `BugBunny::Resource` | ORM tipo AR: `self.exchange=` / `self.resource_name=` / `connection_pool=`; `find/where/create/save/destroy` |
-| `BugBunny::Consumer` | `BugBunny::Consumer.subscribe(connection: BugBunny.create_connection, queue_name:, exchange_name:, routing_key:)` (loop bloqueante) |
+| `BugBunny::Consumer` | `BugBunny::Consumer.subscribe(connection:, queue_name:, exchange_name:, routing_key:)` (loop bloqueante) · `BugBunny::Consumer.drain(...)` (mismos args; consume hasta que la cola queda quieta y retorna cuántos procesó — para correrlo como job, 5.2.0) |
 | `BugBunny::Controller` | `before/around/after_action`, `rescue_from`, `render status:, json:` |
 | `BugBunny.routes.draw` | `resources :x` · `namespace` · `member`/`collection` |
 | `BugBunny.configure` | `host/port/username/password` · `rpc_timeout` (default 10) · `nack_raise`/`return_raise` (default `true`) · `on_return` |
@@ -54,18 +58,26 @@ client.publish('events', body: { type: 'x' })   # => { 'status' => 202 }
 - `confirmed:true + mandatory:true` con `return_raise` (default `true`) → `PublishUnroutable` si no rutea.
 - `BugBunny::Consumer.subscribe` requiere `connection:`. No correr el Consumer en threads de Puma (loop bloqueante).
 - `exchange_options: { durable: true }` debe matchear la declaración del consumer, o `Bunny::PreconditionFailed`.
+- **`drain` (5.2.0):** la conexión es **de quien llama** — `drain` cierra su canal, no la conexión; si la creás por corrida, cerrala (`ensure connection.close`) o cada corrida deja una abierta. Con un flujo sostenido más rápido que `drain_idle_timeout` **no retorna**: acotalo desde el job. Detalle en [`skill/references/consumer.md`](references/consumer.md) y [`docs/behavior/behavior.md`](../docs/behavior/behavior.md).
 - **Errores de transporte (4.18+):** TCP fail, conn rota, canal cerrado → siempre `BugBunny::CommunicationError`. No rescatar `Bunny::TCPConnectionFailed`/`ConnectionClosedError` directo — quedó atrás de la frontera. La original sigue accesible vía `.cause`.
 
 ## Índice de artefactos (fuente de verdad)
 
-El detalle vive en `docs/<capa>/` (modelo `dev-*`); esta skill **indexa y resume**, no duplica. Links relativos = version-locked (mismo tag del release; `gemspec.files` incluye `docs/**`).
+El detalle vive en `docs/<capa>/` (modelo `dev-*`); esta skill **indexa y resume**, no duplica. Links relativos = version-locked (mismo tag del release, `v5.2.0`; `gemspec.files` incluye `docs/**`, así que estos archivos viajan dentro del `.gem` que ya tenés instalado).
 
 | Capa | Artefacto | Estado |
 |---|---|---|
 | Glosario de dominio | [docs/glossary/glossary.md](../docs/glossary/glossary.md) | parcial, acreta por PR |
 | Comportamiento (flujos) | [docs/behavior/behavior.md](../docs/behavior/behavior.md) | completa — 6 flujos |
+| Configuración | [docs/config/configuracion.md](../docs/config/configuracion.md) | §a-§e/§i estructura + §f/§g/§h enrich — completa |
+| Dependencias consumidas | [docs/consumed/rabbitmq.md](../docs/consumed/rabbitmq.md) | §a/§b/§d estructura + §c/§e enrich |
+| Errores | [docs/errors/errors.md](../docs/errors/errors.md) | §a/§b/§d completas; §c política inferida (verificación humana pendiente) |
+| Test | [docs/test/testing.md](../docs/test/testing.md) | §a-§h — 16 unit / 7 integration |
+| Release | [docs/release/release.md](../docs/release/release.md) | completa (régimen gema: build→publish; §e/f/g n/a) |
 | Datos | — | n/a — gema sin DB |
-| Operaciones / Interfaz / Topología | — | F2 no implementado — ver Cobertura y fronteras |
+| Eventos | — | n/a — la gema **es** el transporte; no declara catálogo de eventos de dominio propio |
+| Seguridad | — | n/a — sin authn/authz propias; el guard anti-RCE (403) está en `docs/errors/` |
+| Operaciones / Interfaz / Topología | — | pendiente — ver Cobertura y fronteras |
 
 > **Glosario:** migrado a [docs/glossary/glossary.md](../docs/glossary/glossary.md)
 > (RFC-008 §2 — el compuesto referencia, no copia). Términos AMQP base
@@ -74,13 +86,15 @@ El detalle vive en `docs/<capa>/` (modelo `dev-*`); esta skill **indexa y resume
 
 ## Cobertura y fronteras
 
-**Coexistencia transitoria con destino pendiente (RFC-008 §2 — interim de migración):** mientras la capa de detalle destino (operaciones/interfaz/topología) esté declarada pero **no implementada** (dev-structure F1, F2 del plan), permanecen embebidos bajo el interim normado:
+**Coexistencia transitoria con destino pendiente (RFC-008 §2 — interim de migración):** mientras las capas `docs/api/` (operaciones), `docs/interface/` y `docs/topology/` no estén generadas para este repo, el contrato que les correspondería permanece embebido bajo el interim normado:
 
 - **En esta skill (abajo):** el contrato detallado (jerarquía de excepciones, API de config, modos de entrega) **y** el diagrama de arquitectura (flujo RPC). El *Contrato resumido* de arriba es el piso mínimo (RFC-008 §2); lo de abajo es el detalle interim hasta que exista `docs/api|interface|topology`.
 - **En `README.md`:** el contrato (sin el diagrama de arquitectura).
 - **Guías how-to** (`references/*.md`, pre-estándar): destino futuro `docs/howto/`.
 
-Por RFC-008 §2: no se fabrica la capa, no se borra contrato sin destino, no se duplica; migra cuando F2 entregue, mismo PR. Estado transitorio declarado, no excepción permanente. Origen del gap (resuelto, normado): [sequre/ai_knowledge#95](https://github.com/sequre/ai_knowledge/issues/95).
+Por RFC-008 §2: no se fabrica la capa, no se borra contrato sin destino, no se duplica; migra cuando se generen, mismo PR. Estado transitorio declarado, no excepción permanente. Origen del gap (resuelto, normado): [sequre/ai_knowledge#95](https://github.com/sequre/ai_knowledge/issues/95).
+
+> **Nota de alcance (2026-07-31):** la justificación original de este interim era que el generador no implementaba esas capas. Ya las implementa, así que el pendiente es de **este repo**, no de tooling — en particular `docs/interface/` (RFC-004), donde correspondería registrar la API pública (incluidos `Observability.redact_value` y `.redact_structure`, agregados en `5.1.1`). Queda como trabajo propio, fuera del alcance de este release.
 
 ---
 
@@ -129,7 +143,7 @@ Por RFC-008 §2: no se fabrica la capa, no se borra contrato sin destino, no se
 | `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::Observability` | Mixin de logging estructurado. `safe_log` nunca lanza excepciones. Redacta credenciales en dos capas: por nombre de clave (`sensitive_key?`) y por contenido del valor (`redact_value` / `redact_structure`, para la credencial embebida en texto libre). |
 | `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. |
@@ -241,6 +255,10 @@ BugBunny.configure do |config|
   config.health_check_interval = 60
   config.health_check_file = 'tmp/bb_health'
 
+  # Consumer.drain (5.2.0): segundos sin entregas para dar la cola por vacía, y cada cuánto se chequea
+  config.drain_idle_timeout  = 5
+  config.drain_poll_interval = 0.1
+
   # Routing
   config.controller_namespace = 'BugBunny::Controllers'
 end
@@ -417,7 +435,7 @@ Limitación de RSpec: `instance_double` valida que el método exista pero **no**
 
 ### Guard anti-RCE (403, no es excepción)
 **Causa:** El mensaje intenta ejecutar un controlador que no hereda de `BugBunny::Controller`.
-**Comportamiento:** El worker responde **403 Forbidden** + reject + log `event=consumer.security_violation` (`consumer.rb:222-228`); no levanta una excepción dedicada.
+**Comportamiento:** El worker responde **403 Forbidden** + reject + log `event=consumer.security_violation` (`consumer.rb:375-381`); no levanta una excepción dedicada.
 **Resolución:** Verificar la jerarquía de controladores y que `config.controller_namespace` coincida.
 
 ### BugBunny::RouteNotFoundError (404)

data/skill/references/consumer.md

@@ -11,10 +11,36 @@ consumer = BugBunny::Consumer.subscribe(
   exchange_type: 'topic',
   exchange_opts: { durable: true },
   queue_opts: { auto_delete: false },
-  block: true   # Si false, retorna inmediatamente
+  block: true   # false retorna al instante y cierra el canal: no consume nada (#64)
 )
 ```
 
+## Drain (drenar y salir)
+
+Para correr un consumidor **como job**: consume hasta que la cola queda quieta y retorna cuántos mensajes procesó (incluye los rechazados). Con la cola vacía retorna `0` sin esperar.
+
+```ruby
+connection = BugBunny.create_connection
+begin
+  processed_count = BugBunny::Consumer.drain(
+    connection: connection,
+    queue_name: 'my_app_queue',
+    exchange_name: 'my_exchange',
+    routing_key: 'users.*'
+  )
+ensure
+  connection.close # drain cierra su canal, no la conexión: la conexión es de quien llama
+end
+```
+
+- Respeta `channel_prefetch`, igual que `subscribe`.
+- Termina tras `drain_idle_timeout` segundos (default `5`) sin entregas y sin nada en proceso; lo chequea cada `drain_poll_interval` (default `0.1`).
+- Un mensaje que llega dentro de esa ventana entra en esta vuelta; los posteriores, en la próxima corrida. Una entrega ya recibida al cancelar se procesa antes de volver; si igual no se ack-eara, vuelve a la cola (at-least-once).
+- **Con un flujo sostenido no retorna**: si los mensajes llegan más seguido que `drain_idle_timeout`, la ventana nunca vence. Acotalo desde afuera (timeout del job).
+- **Una entrega que falla sale de la cola**: si un middleware levanta antes del ack, se rechaza sin requeue y no traba el prefetch.
+- **La conexión es de quien llama**: `drain` cierra su canal, no la conexión. Si la creaste para la corrida, cerrala (si no, cada corrida deja una abierta).
+- **No** tiene loop de reconexión ni health check: si falla, lo reintenta el framework del job (Bunny sí recupera la conexión por su cuenta con `automatically_recover`).
+
 ## Flujo de Procesamiento
 
 1. Escucha en la queue con `manual_ack: true`.

data/skill/references/errores.md

@@ -37,9 +37,13 @@ rescue BugBunny::Error => e
 end
 ```
 
-> ⚠️ **No loguear `raw_response` crudo.** Puede contener datos sensibles. Filtrar
-> claves (`password|pass|passwd|secret|token|api_key|auth`) → `[FILTERED]` antes
-> de Sentry/logs. La gema lo entrega a propósito; sanitizar es del consumidor.
+> ⚠️ **No loguear `raw_response` crudo.** Puede contener datos sensibles. Sanear
+> antes de Sentry/logs con `Observability.redact_structure` (recorre la
+> estructura: filtra por nombre de clave y también redacta la credencial
+> embebida en el valor). **No replicar la lista de claves** — la canónica es
+> `Observability::SENSITIVE_KEYS`; replicarla la desincroniza (y `pass` bare NO
+> está en ella, a propósito, para no filtrar `passport_number`). La gema entrega
+> el cuerpo crudo a propósito; sanitizar es del consumidor.
 
 Para consumir un envelope estructurado de dominio (ej. `{ error: { code,
 message, details } }`), parsealo en el boundary del servicio desde
@@ -59,7 +63,7 @@ message, details } }`), parsealo en el boundary del servicio desde
 
 ### Guard anti-RCE (403, no es excepción)
 **Causa:** Un mensaje intenta ejecutar un controlador que no hereda de `BugBunny::Controller`.
-**Cuándo:** El consumer resuelve la clase (`constantize`) pero falla `controller_class < BugBunny::Controller` (`consumer.rb:222-228`).
+**Cuándo:** El consumer resuelve la clase (`constantize`) pero falla `controller_class < BugBunny::Controller` (`consumer.rb:375-381`).
 **Comportamiento:** El worker **no levanta una excepción** — loguea `event=consumer.security_violation`, responde **403 Forbidden** al caller RPC y rechaza el mensaje sin requeue.
 **Resolución:** Verificar que el controlador herede de `BugBunny::Controller` y que `config.controller_namespace` sea correcto.
 

data/skill/references/routing.md

@@ -69,7 +69,7 @@ El consumer resuelve el controlador concatenando:
 
 Ejemplo: namespace `:admin`, controller `:reports` → `BugBunny::Controllers::Admin::ReportsController`
 
-Valida que el controlador sea subclase de `BugBunny::Controller` (guard anti-RCE). Si no, el worker loguea `consumer.security_violation`, responde **403 Forbidden** y rechaza el mensaje sin requeue (`consumer.rb:222-228`) — no levanta una excepción dedicada.
+Valida que el controlador sea subclase de `BugBunny::Controller` (guard anti-RCE). Si no, el worker loguea `consumer.security_violation`, responde **403 Forbidden** y rechaza el mensaje sin requeue (`consumer.rb:375-381`) — no levanta una excepción dedicada.
 
 ## Route Object
 

data/spec/integration/drain_spec.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'support/integration_helper'
+
+module DrainSpec
+  # Controller que sólo cuenta cuántas veces se lo invocó.
+  class PingController < BugBunny::Controller
+    def self.handled_count
+      @handled_count ||= Concurrent::AtomicFixnum.new(0)
+    end
+
+    def index
+      self.class.handled_count.increment
+      render status: 200, json: { pong: true }
+    end
+  end
+end
+
+RSpec.describe 'Consumer.drain', :integration do
+  let(:queue_name)    { unique('drain_q') }
+  let(:exchange_name) { unique('drain_x') }
+  let(:client)        { BugBunny::Client.new(pool: TEST_POOL) }
+  let(:admin_connection) { BugBunny.create_connection }
+
+  # Durable y no exclusiva: drain declara la cola con su propia conexión, y RabbitMQ 4
+  # rechaza las colas no durables y no exclusivas.
+  let(:queue_opts) { { durable: true, exclusive: false, auto_delete: false } }
+
+  let(:drain_args) do
+    { queue_name: queue_name, exchange_name: exchange_name, exchange_type: 'topic',
+      routing_key: 'ping', queue_opts: queue_opts }
+  end
+
+  before do
+    DrainSpec::PingController.handled_count.value = 0
+    BugBunny.configure do |config|
+      config.controller_namespace = 'DrainSpec'
+      config.drain_idle_timeout = 1
+      config.drain_poll_interval = 0.05
+    end
+
+    admin_channel = admin_connection.create_channel
+    effective_exchange_opts = BugBunny::Session::DEFAULT_EXCHANGE_OPTIONS.merge(BugBunny.configuration.exchange_options)
+    exchange = admin_channel.topic(exchange_name, effective_exchange_opts)
+    admin_channel.queue(queue_name, queue_opts).bind(exchange, routing_key: 'ping')
+  end
+
+  after do
+    BugBunny.configure do |config|
+      config.controller_namespace = 'BugBunny::Controllers'
+      config.drain_idle_timeout = 5
+      config.drain_poll_interval = 0.1
+    end
+
+    cleanup_channel = admin_connection.create_channel
+    cleanup_channel.queue_delete(queue_name)
+    cleanup_channel.exchange_delete(exchange_name)
+    admin_connection.close
+  end
+
+  def publish_ping
+    client.publish('ping', method: :get, exchange: exchange_name, exchange_type: 'topic', routing_key: 'ping')
+  end
+
+  def passive_queue
+    admin_connection.create_channel.queue(queue_name, queue_opts.merge(passive: true))
+  end
+
+  def messages_in_queue
+    passive_queue.message_count
+  end
+
+  # La conexión es del llamador: drain cierra su canal, no la conexión.
+  def drain
+    connection = BugBunny.create_connection
+    BugBunny::Consumer.drain(connection: connection, **drain_args)
+  ensure
+    connection&.close
+  end
+
+  it 'procesa todos los mensajes encolados, los ack-ea y retorna cuántos fueron' do
+    BugBunny.configure { |config| config.channel_prefetch = 3 }
+    5.times { publish_ping }
+    sleep 0.3
+
+    expect(drain).to eq(5)
+    expect(DrainSpec::PingController.handled_count.value).to eq(5)
+    expect(messages_in_queue).to eq(0)
+  ensure
+    BugBunny.configure { |config| config.channel_prefetch = 1 }
+  end
+
+  it 'con la cola vacía retorna 0 sin esperar la ventana de inactividad' do
+    started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    expect(drain).to eq(0)
+    expect(Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at).to be < 1
+  end
+
+  # Criterio 5: shutdown corre al volver y cierra el canal. Se mira el canal y no el
+  # `consumer_count`: ése queda en 0 por el `cancel` aunque falte el `ensure shutdown`, así
+  # que un test sobre él pasaría con el defecto intacto. El canal se toma antes: es el mismo
+  # que después usa drain.
+  it 'cierra su canal al volver, con la cola vacía y con mensajes' do
+    [0, 2].each do |pending|
+      pending.times { publish_ping }
+      sleep 0.3 if pending.positive?
+
+      connection = BugBunny.create_connection
+      consumer = BugBunny::Consumer.new(connection)
+      channel = consumer.session.channel
+
+      consumer.drain(**drain_args)
+
+      expect(channel).not_to be_open, "con #{pending} mensajes el canal quedó abierto"
+    ensure
+      connection&.close
+    end
+  end
+
+  # Review de #65: un middleware que levanta dejaba la entrega sin ack ni reject; con
+  # prefetch 1 trababa la cola y drain volvía "con éxito" sin haber sacado nada.
+  it 'una entrega cuyo middleware levanta sale de la cola y no traba el prefetch' do
+    exploding = Class.new(BugBunny::ConsumerMiddleware::Base) do
+      def call(*)
+        raise 'middleware roto'
+      end
+    end
+    BugBunny.consumer_middlewares.use exploding
+    BugBunny.configure { |config| config.channel_prefetch = 1 }
+    3.times { publish_ping }
+    sleep 0.3
+
+    expect(drain).to eq(3)
+    expect(messages_in_queue).to eq(0)
+    expect(DrainSpec::PingController.handled_count.value).to eq(0)
+  ensure
+    BugBunny.configuration.instance_variable_set(:@consumer_middlewares, BugBunny::ConsumerMiddleware::Stack.new)
+    BugBunny.configure { |config| config.channel_prefetch = 1 }
+  end
+
+  # Review de #65: la guarda `unless settled` de `settle_failed_delivery`. Si el error
+  # llega DESPUÉS del ack, rechazar el tag ya confirmado hace que el broker cierre el
+  # canal; sin la guarda, drain terminaba en Timeout::Error con mensajes en la cola.
+  it 'un middleware que levanta después del ack no rechaza la entrega ya resuelta' do
+    after_ack = Class.new(BugBunny::ConsumerMiddleware::Base) do
+      def call(*args)
+        @app.call(*args)
+        raise 'después del ack'
+      end
+    end
+    BugBunny.consumer_middlewares.use after_ack
+    BugBunny.configure { |config| config.channel_prefetch = 1 }
+    3.times { publish_ping }
+    sleep 0.3
+
+    expect(drain).to eq(3)
+    expect(messages_in_queue).to eq(0)
+    expect(DrainSpec::PingController.handled_count.value).to eq(3)
+  ensure
+    BugBunny.configuration.instance_variable_set(:@consumer_middlewares, BugBunny::ConsumerMiddleware::Stack.new)
+    BugBunny.configure { |config| config.channel_prefetch = 1 }
+  end
+
+  it 'procesa en la misma vuelta un mensaje que llega dentro de la ventana de inactividad' do
+    publish_ping
+    sleep 0.3
+
+    drain_thread = Thread.new { drain }
+    sleep 0.5
+    publish_ping
+
+    expect(drain_thread.value).to eq(2)
+    expect(messages_in_queue).to eq(0)
+  end
+end

data/spec/unit/configuration_spec.rb

@@ -11,7 +11,15 @@ RSpec.describe BugBunny::Configuration do
     end
   end
 
-  after { BugBunny.configuration = BugBunny::Configuration.new }
+  # Restaura la configuración de spec_helper (host, credenciales) y no una con defaults:
+  # si no, los specs de integración que corren después se conectan como `guest` y se
+  # saltean como "RabbitMQ no disponible" en vez de correr.
+  around do |example|
+    original_configuration = BugBunny.configuration
+    example.run
+  ensure
+    BugBunny.configuration = original_configuration
+  end
 
   describe 'defaults' do
     it 'pasan validate! sin ninguna configuración adicional' do
@@ -124,6 +132,24 @@ RSpec.describe BugBunny::Configuration do
     end
   end
 
+  describe 'drain_idle_timeout' do
+    it 'levanta ConfigurationError si es 0' do
+      expect { configure_with(drain_idle_timeout: 0) }
+        .to raise_error(BugBunny::ConfigurationError, /drain_idle_timeout must be in/)
+    end
+  end
+
+  describe 'drain_poll_interval' do
+    it 'acepta fracciones de segundo' do
+      expect { configure_with(drain_poll_interval: 0.05) }.not_to raise_error
+    end
+
+    it 'levanta ConfigurationError si es 0' do
+      expect { configure_with(drain_poll_interval: 0) }
+        .to raise_error(BugBunny::ConfigurationError, /drain_poll_interval must be in/)
+    end
+  end
+
   describe 'configuración válida completa' do
     it 'acepta todos los atributos con valores correctos' do
       expect do

data/spec/unit/drain_tracker_spec.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe BugBunny::DrainTracker do
+  # Reloj controlado por el test: el tiempo avanza sólo cuando el spec lo mueve.
+  let(:current_time) { [100.0] }
+  let(:tracker) { described_class.new(clock: -> { current_time.first }) }
+
+  def advance(seconds)
+    current_time[0] += seconds
+  end
+
+  it 'no está ocioso mientras una entrega sigue en proceso, aunque venza la ventana' do
+    tracker.track do
+      advance(10)
+      expect(tracker.idle?(5)).to be(false)
+    end
+  end
+
+  it 'queda ocioso recién cuando pasa la ventana completa desde la última entrega' do
+    tracker.track { advance(1) }
+
+    advance(4.9)
+    expect(tracker.idle?(5)).to be(false)
+
+    advance(0.1)
+    expect(tracker.idle?(5)).to be(true)
+  end
+
+  it 'cuenta la entrega como procesada y la libera aunque el procesamiento levante' do
+    expect { tracker.track { raise 'boom' } }.to raise_error('boom')
+
+    expect(tracker.processed).to eq(1)
+    expect(tracker.busy?).to be(false)
+  end
+end

data/spec/unit/observability_spec.rb

@@ -29,6 +29,164 @@ RSpec.describe BugBunny::Observability do
     log_output.string.split("\n").last.to_s.sub(/\A.*?:\s*/, '')
   end
 
+  describe '.redact_value (contenido sensible en texto libre)' do
+    # Complementa a .sensitive_key?: esa mira el NOMBRE de la clave, esta el
+    # CONTENIDO. El caso que motiva la feature es el `message` de una excepción.
+    it 'redacta un Bearer token' do
+      redacted = BugBunny::Observability.redact_value(
+        'undefined method for #<Faraday::Response headers={"Authorization"=>"Bearer eyJhbGciOiJIUzI1NiJ9.abc"}>'
+      )
+
+      expect(redacted).not_to include('eyJhbGciOiJIUzI1NiJ9.abc')
+      expect(redacted).to include('[FILTERED]')
+    end
+
+    it 'redacta un esquema Basic' do
+      redacted = BugBunny::Observability.redact_value('Authorization: Basic dXNlcjpwYXNzd29yZA==')
+
+      expect(redacted).not_to include('dXNlcjpwYXNzd29yZA')
+      expect(redacted).to include('[FILTERED]')
+    end
+
+    it 'redacta el valor cuando la key viaja DENTRO del texto, conservando el nombre' do
+      redacted = BugBunny::Observability.redact_value('connect failed (token=abc123, host=rabbit)')
+
+      expect(redacted).not_to include('abc123')
+      expect(redacted).to include('token=[FILTERED]')
+      # El resto del mensaje sobrevive: la redacción es quirúrgica, no destructiva.
+      expect(redacted).to include('host=rabbit')
+    end
+
+    it 'matchea la key más larga primero (authorization no se parte en auth)' do
+      redacted = BugBunny::Observability.redact_value('authorization: "Bearer-less-secret-value"')
+
+      expect(redacted).not_to include('Bearer-less-secret-value')
+      expect(redacted).to include('authorization=[FILTERED]')
+    end
+
+    it 'redacta credenciales de una URL conservando esquema y host' do
+      redacted = BugBunny::Observability.redact_value('amqp://guest:s3cr3t@rabbit:5672/vhost')
+
+      expect(redacted).not_to include('s3cr3t')
+      expect(redacted).to include('amqp://[FILTERED]@rabbit:5672/vhost')
+    end
+
+    it 'deja intacto un texto sin credenciales' do
+      expect(BugBunny::Observability.redact_value('timeout after 30s on queue acs.rpc'))
+        .to eq('timeout after 30s on queue acs.rpc')
+    end
+
+    it 'no confunde una key no sensible que contiene un substring parecido' do
+      expect(BugBunny::Observability.redact_value('passport_number=AB123'))
+        .to include('AB123')
+    end
+
+    # `_` es word-char: un `\b` antes de la key NO encuentra borde dentro de
+    # `access_token` ni de `accessToken`, y esas variantes se colaban en claro.
+    # Son exactamente las que sensitive_key? cubre a propósito con substring matching.
+    it 'redacta la variante con separador (access_token) conservando el nombre completo' do
+      redacted = BugBunny::Observability.redact_value('request failed access_token=eyJsecret.jwt')
+
+      expect(redacted).not_to include('eyJsecret.jwt')
+      expect(redacted).to include('access_token=[FILTERED]')
+    end
+
+    it 'redacta la variante con prefijo (user_password)' do
+      redacted = BugBunny::Observability.redact_value('invalid params user_password=hunter2')
+
+      expect(redacted).not_to include('hunter2')
+      expect(redacted).to include('user_password=[FILTERED]')
+    end
+
+    it 'redacta la variante camelCase (accessToken)' do
+      redacted = BugBunny::Observability.redact_value('boom accessToken=eyJsecret.jwt')
+
+      expect(redacted).not_to include('eyJsecret.jwt')
+      expect(redacted).to include('accessToken=[FILTERED]')
+    end
+
+    it 'no redacta una key no sensible con sufijo numérico (processing_session_count)' do
+      expect(BugBunny::Observability.redact_value('processing_session_count=5'))
+        .to eq('processing_session_count=5')
+    end
+  end
+
+  describe '.redact_structure (estructura antes de serializar)' do
+    it 'redacta por key interna y deja la forma intacta' do
+      redacted = BugBunny::Observability.redact_structure(
+        'token' => 'abc123', 'host' => 'rabbit'
+      )
+
+      expect(redacted).to eq('token' => '[FILTERED]', 'host' => 'rabbit')
+    end
+
+    it 'recorre Hash anidado y Array' do
+      redacted = BugBunny::Observability.redact_structure(
+        'nested' => { 'api_key' => 'xyz', 'n' => 1 },
+        'list' => ['token=abc123', 'clean']
+      )
+
+      expect(redacted).to eq(
+        'nested' => { 'api_key' => '[FILTERED]', 'n' => 1 },
+        'list' => ['token=[FILTERED]', 'clean']
+      )
+    end
+
+    it 'no altera numéricos ni booleanos ni nil' do
+      expect(BugBunny::Observability.redact_structure('n' => 1, 'ok' => true, 'x' => nil))
+        .to eq('n' => 1, 'ok' => true, 'x' => nil)
+    end
+  end
+
+  describe '#safe_log — redacción por contenido' do
+    # El caso real: el nombre de la clave NO es sensible (`reason`), así que el
+    # filtro por-clave lo deja pasar; la credencial va en el valor.
+    it 'filtra una credencial embebida en el valor de una key NO sensible' do
+      host.safe_log(:error, 'unhandled_exception',
+                    reason: 'NoMethodError on headers {"Authorization"=>"Bearer eyJsupersecret.jwt"}')
+
+      expect(last_log_line).not_to include('eyJsupersecret.jwt')
+      expect(last_log_line).to include('[FILTERED]')
+    end
+
+    it 'filtra dentro de un Hash serializado (las keys internas no pasan por sensitive_key?)' do
+      host.safe_log(:error, 'unhandled_exception', details: { 'token' => 'abc123xyz' })
+
+      expect(last_log_line).not_to include('abc123xyz')
+      expect(last_log_line).to include('[FILTERED]')
+    end
+
+    # La redacción no puede costar la estructura: quien consume el log parsea este campo
+    # como JSON, y un objeto roto le hace perder TODOS los pares, no solo el redactado.
+    it 'mantiene el campo Hash como JSON parseable después de redactar' do
+      host.safe_log(:error, 'unhandled_exception',
+                    details: { 'token' => 'abc123xyz', 'host' => 'rabbit',
+                               'nested' => { 'api_key' => 'xyz789', 'n' => 1 } })
+
+      field = last_log_line[/details=(\S+)/, 1]
+
+      expect { JSON.parse(field) }.not_to raise_error
+      expect(JSON.parse(field)).to eq(
+        'token' => '[FILTERED]', 'host' => 'rabbit',
+        'nested' => { 'api_key' => '[FILTERED]', 'n' => 1 }
+      )
+    end
+
+    it 'no altera un valor numérico' do
+      host.safe_log(:info, 'done', duration_s: 1.5, status: 200)
+
+      expect(last_log_line).to include('duration_s=1.5', 'status=200')
+    end
+
+    it 'preserva el resto de la línea (component, event y campos limpios)' do
+      host.safe_log(:error, 'request_error', kind: 'unavailable', reason: 'ACS down')
+
+      line = last_log_line
+      expect(line).to include('event=request_error', 'kind=unavailable')
+      expect(line).to include('reason="ACS down"')
+    end
+  end
+
   describe '.sensitive_key? (módulo público)' do
     subject(:sensitive?) { BugBunny::Observability.method(:sensitive_key?) }
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 5.1.0
+  version: 5.2.0
 platform: ruby
 authors:
 - gabix
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-22 00:00:00.000000000 Z
+date: 2026-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -248,6 +248,7 @@ files:
 - lib/bug_bunny/consumer.rb
 - lib/bug_bunny/consumer_middleware.rb
 - lib/bug_bunny/controller.rb
+- lib/bug_bunny/drain_tracker.rb
 - lib/bug_bunny/exception.rb
 - lib/bug_bunny/middleware/base.rb
 - lib/bug_bunny/middleware/json_response.rb
@@ -281,6 +282,7 @@ files:
 - spec/integration/client_spec.rb
 - spec/integration/consumer_middleware_spec.rb
 - spec/integration/controller_spec.rb
+- spec/integration/drain_spec.rb
 - spec/integration/error_handling_spec.rb
 - spec/integration/infrastructure_spec.rb
 - spec/integration/publisher_confirms_spec.rb
@@ -294,6 +296,7 @@ files:
 - spec/unit/consumer_middleware_spec.rb
 - spec/unit/consumer_spec.rb
 - spec/unit/controller_after_action_spec.rb
+- spec/unit/drain_tracker_spec.rb
 - spec/unit/extra_top_level_params_spec.rb
 - spec/unit/observability_spec.rb
 - spec/unit/otel_spec.rb
@@ -314,7 +317,7 @@ metadata:
   homepage_uri: https://github.com/gedera/bug_bunny
   source_code_uri: https://github.com/gedera/bug_bunny
   changelog_uri: https://github.com/gedera/bug_bunny/blob/main/CHANGELOG.md
-  documentation_uri: https://github.com/gedera/bug_bunny/blob/v5.1.0/skill
+  documentation_uri: https://github.com/gedera/bug_bunny/blob/v5.2.0/skill
 post_install_message:
 rdoc_options: []
 require_paths: