bug_bunny 5.1.1 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd173a6f940a79457235d63629891426cba1f94a8381c19a219e38f275fe96dd
-  data.tar.gz: 78f927d9ed2ef4d04bf5b3059a3b3d54b93974ee11a8d7235ade9ae82095a51b
+  metadata.gz: 6ac482578cfbb87414309cc03502be5f11c4ee4b0e799338bfeb9bfcf65488f5
+  data.tar.gz: a4a9e64ac077bd6564790a5de762c804d38c65623f2c7cbc839217bb8f98bd25
 SHA512:
-  metadata.gz: 188ad45954c08cf19dda7625236fdc8da934676de77a6af7136547893f2fc8ae0ad782aa890782dbd59e16b39b90d8fa8dec3f9b1c9a5c3b4b4fd22db5c77f8f
-  data.tar.gz: 87bf5385a97fea06f86fccb396ade8ce2602ec831181e4a2ba7893711a784eccb4d922ca4303137f0e25f7a625d88d015e61858f4f48209fa89624ae02a92cea
+  metadata.gz: e33cbdca7040793e46116fdf744d3f89bdd71a4b278a12aaa85f3845c6aba1ea86dbfded00c3108b60e04759dea07f52a7765d430fcc3bbc3ff2090b01f38c9a
+  data.tar.gz: be41989086784220c62b3e9ee4909f064956c3bf7dcaade12473d039c16743732a75f1d60844ffc22fcbe0afb36c518e14dbb74713cc0ef7007f9658d2be13d1

data/AGENTS.md

@@ -12,7 +12,7 @@ proyecto y convenciones de equipo, ver `CLAUDE.md`. Para la entrada humana, ver
 
 | capa | artefacto | estado | qué responde |
 |---|---|---|---|
-| Comportamiento | `docs/behavior/behavior.md` | completo (6 flujos) | secuencias de publish/RPC/consume/confirms, contrato de error-wrapping |
+| Comportamiento | `docs/behavior/behavior.md` | completo (7 flujos) | secuencias de publish/RPC/consume/confirms, contrato de error-wrapping |
 | Glosario | `docs/glossary/glossary.md` | parcial (acreta por PR) | término de negocio → binding físico en `lib/` |
 | Errores | `docs/errors/errors.md` | completo (§a/b/d estructura + §c política inferida) | jerarquía de excepciones públicas, mapeo `status→excepción`, shape del payload, política retry |
 | Configuración | `docs/config/configuracion.md` | completo (estructura + enrich §f/g/h) | opciones de `Configuration`, defaults, failure-mode/threading, inyecciones del `Railtie`, ENV sugeridas |

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [5.2.0] - 2026-09-29
+
+### Nuevas funcionalidades
+- **`Consumer.drain` / `Consumer#drain` — consumir hasta vaciar la cola y retornar (#65):** el modo para correr un consumidor **como job** (Sidekiq, un Job de k8s) en vez de como proceso eterno. Se suscribe respetando `channel_prefetch` y retorna cuando pasan `drain_idle_timeout` segundos sin entregas y sin nada en proceso; con la cola vacía retorna `0` al instante. Devuelve cuántos mensajes procesó (incluye los rechazados: también salieron de la cola). Un mensaje que llega dentro de la ventana se procesa en esa vuelta; los posteriores, en la próxima. No tiene loop de reconexión ni health check (el reintento es del framework del job). **La conexión es del llamador:** `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. — @gedera
+- **`drain_idle_timeout` (default `5`) y `drain_poll_interval` (default `0.1`) en `Configuration`**, validados en `validate!`. — @gedera
+
+### ⚠️ Cambio de conducta — `subscribe` y `drain`
+- **Una entrega cuyo middleware —o `handle_fatal_error`— levanta antes del ack ahora se rechaza sin requeue** y se loguea `consumer.delivery_failed` (#65). Antes quedaba **sin ack ni reject**: con `channel_prefetch = 1` ocupaba el único lugar de prefetch y el consumidor dejaba de recibir, sin error. Es lo mismo que `process_message` ya hacía con sus propios errores. Si el error llega **después** del ack, sólo se loguea (rechazar un tag ya confirmado cierra el canal). **A mirar si consumís:** si un middleware tuyo levantaba a propósito para que el mensaje se reintentara, ahora el mensaje **se pierde** — el reintento tiene que ser tuyo. — @gedera
+
+### Documentación
+- `subscribe(block: false)` **no** es un modo "drenar": retorna al instante y el `ensure shutdown` cierra el canal, así que no consume nada (medido en #65). Queda documentado en el README; no se cambia en este release. — @gedera
+
+### Tests
+- `configuration_spec` restaura la configuración original en vez de dejar una con defaults: los specs de integración que corrían después se conectaban como `guest` y quedaban *pending* como "RabbitMQ no disponible" aun con broker, según el seed (#65). — @gedera
+
 ## [5.1.1] - 2026-07-31
 
 ### Correcciones

data/CLAUDE.md

@@ -15,7 +15,7 @@ BugBunny es una gema Ruby que implementa una capa de enrutamiento RESTful sobre
   `dev-compose`. Verificación humana antes de commitear.
 - **Estado actual:**
   - `docs/data` = n/a (gema sin DB, declarado solo en índice).
-  - `docs/behavior` completo (6 flujos, backfill on-demand).
+  - `docs/behavior` completo (7 flujos, backfill on-demand).
   - `docs/glossary` parcial (acreta por PR).
   - `docs/errors` (RFC-020) completo: §a/§b/§d (estructura) + §c política
     (enrich, **inferida** de HTTP/AMQP, verificación humana pendiente).

data/README.md

@@ -66,6 +66,28 @@ BugBunny::Consumer.subscribe(
 )
 ```
 
+To run a consumer **as a job** (Sidekiq, a k8s Job) instead of a long-lived process, use `drain`: it consumes until the queue goes quiet and returns how many messages it processed. With an empty queue it returns `0` right away.
+
+```ruby
+connection = BugBunny.create_connection
+begin
+  processed_count = BugBunny::Consumer.drain(
+    connection:    connection,
+    queue_name:    'inventory_queue',
+    exchange_name: 'inventory',
+    routing_key:   'nodes'
+  )
+ensure
+  connection.close # drain closes its channel, not the connection: the connection is yours
+end
+```
+
+- **The connection belongs to the caller.** `drain` closes its channel when it returns, not the connection, because it may be shared (a pool, the publisher's). If you create one per job run, close it — otherwise every run leaks a connection. Reusing the process connection works too.
+- **A delivery that fails leaves the queue.** If a middleware raises before the ack, the message is rejected without requeue (same as `process_message` errors), so it does not block the prefetch.
+- **With a sustained flow, `drain` does not return.** If messages arrive faster than `drain_idle_timeout`, the idle window never closes. Bound it from outside (the Sidekiq job timeout, `activeDeadlineSeconds` in k8s).
+
+> `subscribe(block: false)` is **not** this mode: it returns immediately and closes the channel, so it consumes nothing.
+
 ### Service A — Producer
 
 ```ruby
@@ -146,6 +168,11 @@ BugBunny.configure do |config|
   # Health check file for Kubernetes / Docker Swarm liveness probes
   config.health_check_file = '/tmp/bug_bunny_health'
 
+  # Consumer.drain — seconds without deliveries before the queue counts as empty (default: 5),
+  # and how often that is checked (default: 0.1)
+  config.drain_idle_timeout  = 5
+  config.drain_poll_interval = 0.1
+
   # Publisher Confirms — fail-loud defaults (both flags default to true).
   # Set to false to restore legacy log-only behavior.
   config.nack_raise   = true   # broker NACK → raise BugBunny::PublishNacked
@@ -432,7 +459,7 @@ end
 
 Artefactos de detalle (modelo `dev-*`, RFC-001). El README indexa; no duplica.
 
-Anclado a `v5.1.1`.
+Anclado a `v5.2.0`.
 
 | Capa | Artefacto | Estado |
 |---|---|---|

data/docs/behavior/behavior.md

@@ -1,6 +1,6 @@
 # Comportamiento — bug_bunny
 
-> meta: artefacto `comportamiento` · RFC-007 (cadencia incremental default / completo on-demand) · generado dev-enrich 1.3.0 (backfill on-demand) · anclado a `94de2b4` · cobertura: completa (6 flujos) · verificado por humano 2026-05-18 (base) · 2026-05-26 (refresco scoped: contrato de error wrapping post-#49)
+> meta: artefacto `comportamiento` · RFC-007 (cadencia incremental default / completo on-demand) · generado dev-enrich 1.3.0 (backfill on-demand) · anclado a `35b075a` (squash de #65 en `main`) · cobertura: completa (7 flujos) · verificado por humano 2026-05-18 (base) · 2026-05-26 (refresco scoped: contrato de error wrapping post-#49) — incremento 2026-09-28 (#64, flujo `drain` + re-mapeo de `file:line`): escrito por el agente, **sin verificación humana todavía**
 
 ## 1. Resumen
 
@@ -10,14 +10,15 @@ Flujos de ejecución de la gema. Generado en **modo completo on-demand** (RFC-00
 
 | Flujo | Estado | Anclaje principal |
 |---|---|---|
-| RPC síncrono | **documentado** | `producer.rb:103-134`, `consumer.rb:152-293` |
+| RPC síncrono | **documentado** | `producer.rb:103-134`, `consumer.rb:305-446` |
 | Fire-and-forget | **documentado** | `producer.rb:47-51,146-161` |
 | Confirmed + basic.return bridge | **documentado** | `producer.rb:72-93,299-333`, `session.rb:204-250` |
-| Consumer subscribe loop + reconnect + health | **documentado** | `consumer.rb:66-127,340-361` |
-| Error handling / RemoteError | **documentado** | `consumer.rb:320-329`, `remote_error.rb`, `raise_error.rb:32-65` |
+| Consumer subscribe loop + reconnect + health | **documentado** | `consumer.rb:76-111,493-514` |
+| Consumer drain (drenar y salir) | **documentado** | `consumer.rb:158-176,271-290`, `drain_tracker.rb:28-47` |
+| Error handling / RemoteError | **documentado** | `consumer.rb:473-482`, `remote_error.rb`, `raise_error.rb:32-65` |
 | Client middleware stack (onion) | **documentado** | `middleware/stack.rb:43-47`, `base.rb:35-43` |
 
-Cobertura completa a `a5cdb10`. Acreta incremental en cada PR que toque un flujo (default RFC-007). Ausencia futura ≠ inexistencia.
+Cobertura completa a `35b075a`. Acreta incremental en cada PR que toque un flujo (default RFC-007). Ausencia futura ≠ inexistencia.
 
 ## 2. Cuerpo
 
@@ -50,7 +51,7 @@ sequenceDiagram
     P-->>CL: response hidratada
     Note over P: bloqueo L122 · timeout → RequestTimeout L124
 ```
-Contexto: `client.rb:97-101` → `producer.rb:103-134` (bloqueo L122) → reply listener `producer.rb:405-424` → `consumer.rb:247,272-293`.
+Contexto: `client.rb:97-101` → `producer.rb:103-134` (bloqueo L122) → reply listener `producer.rb:405-424` → `consumer.rb:400,425-446`.
 
 ### Flujo: Fire-and-forget
 Publica y retorna `{ 'status' => 202 }` sin esperar broker ni consumer.
@@ -116,7 +117,34 @@ sequenceDiagram
     Note over C: rescue StandardError → attempt++ · backoff min(nri*2^(n-1), max) · sleep · retry (redeclara)
     Note over C: max_reconnect_attempts alcanzado → raise (fatal) · ensure → shutdown
 ```
-Contexto: `consumer.rb:66-127` (retry L106-124), `consumer.rb:340-361` (health). **Honestidad:** health check es thread aparte (TimerTask); no es parte del manejo de error del loop — se acoplan sólo vía cierre de session. Marcado, no fingido como un único flujo.
+Contexto: `consumer.rb:76-111` (retry L90-108), `consumer.rb:493-514` (health). **Honestidad:** health check es thread aparte (TimerTask); no es parte del manejo de error del loop — se acoplan sólo vía cierre de session. Marcado, no fingido como un único flujo.
+
+### Flujo: Consumer drain (drenar y salir)
+Consume hasta que la cola queda quieta y retorna la cantidad procesada: el modo para correr un consumidor **como job** (#64). A diferencia del loop de `subscribe`, **no** tiene loop de reconexión ni health check (Bunny sí recupera la conexión por su cuenta con `automatically_recover`).
+
+```mermaid
+sequenceDiagram
+    participant J as Job (llamador)
+    participant C as Consumer
+    participant T as DrainTracker
+    participant BR as RabbitMQ
+    J->>C: Consumer.drain(connection:, queue_name:, …)
+    C->>BR: exchange/queue declare · bind · message_count
+    alt message_count == 0
+        C-->>J: 0 (sin esperar) · ensure → shutdown
+    else hay mensajes
+        C->>BR: subscribe(manual_ack, block:false) — respeta channel_prefetch
+        loop por entrega (work pool de Bunny)
+            BR->>C: deliver → T.track { middlewares → process_message → ack/reject }
+        end
+        loop cada drain_poll_interval
+            C->>T: idle?(drain_idle_timeout) — nada en proceso y sin actividad en la ventana
+        end
+        C->>BR: cancel · espera a que T no esté busy
+        C-->>J: T.processed · ensure → shutdown
+    end
+```
+Contexto: `consumer.rb:158-176` (`drain`), `consumer.rb:271-290` (`consume_until_idle`), `drain_tracker.rb:28-47`. **Mensajes que llegan mientras drena:** entran en esta vuelta si llegan antes de que venza la ventana; los posteriores quedan para la próxima corrida. Una entrega ya recibida al cancelar se procesa antes de volver (Bunny drena su work pool al cancelar — leído de la fuente de Bunny 2.24.0, no medido); si igual no se ack-eara, **vuelve a la cola** (at-least-once). El conteo devuelto incluye los rechazados. **Una entrega que falla fuera del rescue de `process_message`** (un middleware, `handle_fatal_error`) se rechaza sin requeue en `handle_delivery` y se loguea `consumer.delivery_failed`; antes quedaba sin ack, trababa el prefetch y `drain` volvía "con éxito" con la cola llena (medido en el review de #65). **Con un flujo sostenido no retorna:** si los mensajes llegan más seguido que `drain_idle_timeout` la ventana no vence — la duración la decide el productor; se acota desde afuera (timeout del job). **La conexión es del llamador:** `drain` cierra el canal, no la conexión. **Distinto de `subscribe(block: false)`:** ese modo retorna al instante y el `ensure shutdown` cierra el canal, así que no consume nada (medido en #64).
 
 ### Flujo: Error handling / RemoteError
 Excepción no manejada en controller → serializada (clase/mensaje/backtrace[0..25]) → reply 500 → reconstruida client-side por `Middleware::RaiseError`.
@@ -137,7 +165,7 @@ sequenceDiagram
     RE->>RE: status 500..599 + bug_bunny_exception
     RE-->>CL: raise BugBunny::RemoteError(class,message,backtrace)
 ```
-Contexto: `controller.rb:200-234`, `consumer.rb:320-329`, `remote_error.rb:29-48`, `raise_error.rb:32-65`. **Honestidad:** backtrace truncado a 25 líneas en serialize; si el controller nunca llega a responder, el cliente expira por timeout en vez de recibir el error (no hay path de error garantizado).
+Contexto: `controller.rb:200-234`, `consumer.rb:473-482`, `remote_error.rb:29-48`, `raise_error.rb:32-65`. **Honestidad:** backtrace truncado a 25 líneas en serialize; si el controller nunca llega a responder, el cliente expira por timeout en vez de recibir el error (no hay path de error garantizado).
 
 ### Flujo: Client middleware stack (onion)
 `Stack#build` hace `@middlewares.reverse.inject(final_action)` → el **primer `use` queda como el más externo** (corre `on_request` primero, `on_complete` último). Documentado en `stack.rb:37-39`; sigue la convención Rack/Faraday (primer registrado = capa externa).
@@ -167,7 +195,7 @@ Contexto: `middleware/stack.rb:31-47` (build L43-47, `reverse.inject`), `base.rb
 |---|---|---|
 | Secuencias y `file:line` extraídos por el LLM del código a `a5cdb10`; 2ª pasada LLM corrigió 3 discrepancias (flujo middleware invertido, timeout RPC `producer.rb:124`, timeout confirmed `producer.rb:214-215`) | confirmed | **verificado por humano 2026-05-18** (invariante RFC-001 §3.3 satisfecho) |
 | Orden wire `basic.return → basic.ack` garantizado por AMQP; `RETURN_RACE_WINDOW_S` cubre GVL | declared (código) / inferred (garantía AMQP) | confirmar lectura de `producer.rb:299-308` + spec AMQP |
-| Health check acoplado flojo al loop vía cierre de session | inferred | confirmar `consumer.rb:340-361` vs `106-124` |
+| Health check acoplado flojo al loop vía cierre de session | inferred | confirmar `consumer.rb:493-514` vs `90-108` |
 | Frontera de error del Client: cualquier `Bunny::Exception` durante `@pool.with` (try_create o in-flight) → `BugBunny::CommunicationError` con `.cause` preservada (`client.rb:155-167`). `Producer#confirmed` rescate estrechado a `Bunny::Exception` (`producer.rb:87-90`) — no traga bugs Ruby. `BugBunny.create_connection` también envuelve (`bug_bunny.rb:96-99`). | declared (código post-#49) | confirmar lectura de `client.rb:155-167`, `producer.rb:87-90`, `bug_bunny.rb:96-99` + specs `communication_error_wrapping_spec.rb` |
 
 ## 4. Cobertura y fronteras

data/docs/config/configuracion.md

@@ -1,12 +1,14 @@
 # Configuración — bug_bunny
 
 > meta: artefacto configuración · RFC-012 · generado `arch-structure` (inventario
-> §a-§e/§i) + `arch-enrich` (§f/§g/§h/§j) · anclado a `24ea397`,
+> §a-§e/§i) + `arch-enrich` (§f/§g/§h/§j) · anclado a `35b075a` (squash de #65 en `main`),
 > `lib/bug_bunny/configuration.rb`, `lib/bug_bunny.rb`, `lib/bug_bunny/railtie.rb`,
 > `lib/bug_bunny/consumer.rb`,
 > `lib/generators/bug_bunny/install/templates/initializer.rb` · fecha 2026-06-30
 > · cobertura: §a-§e/§i (estructura) + §f/§g/§h (enrich, anclado a YARD) completas;
-> §j n/a.
+> §j n/a. Incremento 2026-09-28 (#64): `drain_idle_timeout`/`drain_poll_interval`,
+> anclados a `configuration.rb:37-38,99-105,273-275` y `consumer.rb:271-290`; todas las
+> citas `file:line` re-mapeadas al árbol de `35b075a` (el refactor de #64 las corrió).
 
 ## 1. Resumen
 
@@ -20,13 +22,15 @@ en `lib/`**; el `ENV.fetch` vive en el **template** que sugiere al consumidor
 
 ### a. Hecho verificable
 
-- **Total opciones (`Configuration`):** 29 (attr_accessor/reader).
-- **Validadas requeridas (`VALIDATIONS`, `configuration.rb:25-37`):** 5 (`host`,
+- **Total opciones (`Configuration`):** 32 (31 `attr_accessor` + 1 `attr_reader`; medido
+  2026-09-28 — el `29` anterior ya estaba desfasado del código antes de #64).
+- **Validadas requeridas (`VALIDATIONS`, `configuration.rb:25-39`):** 5 (`host`,
   `port`, `username`, `password`, `vhost` — `required: true`; igual tienen
   default, `validate!` exige no-vacío).
-- **Con default:** 29 (todas; defaults en `initialize`/`init_callback_defaults`).
-- **Con rango validado:** 7 (`port`, `heartbeat`, `connection_timeout`,
-  `read_timeout`, `write_timeout`, `rpc_timeout`, `channel_prefetch`).
+- **Con default:** 32 (todas; defaults en `initialize`/`init_callback_defaults`/`init_drain_defaults`).
+- **Con rango validado:** 9 (`port`, `heartbeat`, `connection_timeout`,
+  `read_timeout`, `write_timeout`, `rpc_timeout`, `channel_prefetch`,
+  `drain_idle_timeout`, `drain_poll_interval`).
 - **Secretas (por nombre):** 1 (`password`).
 - **ENV leídas por la gema en `lib/`:** 0 (config 100% por code-default + bloque).
 
@@ -37,36 +41,38 @@ Origen `code-default` salvo nota. Consumidor = `configuration.rb` (default en
 
 | nombre | tipo | requerida | default | origen | consumidor | secret? |
 |---|---|---|---|---|---|---|
-| `host` | String | sí (validate!) | `'127.0.0.1'` | code-default | `configuration.rb:182` | no |
-| `port` | Integer | sí (validate!, 1..65535) | `5672` | code-default | `:183` | no |
-| `username` | String | sí (validate!) | `'guest'` | code-default | `:184` | no |
-| `password` | String | sí (validate!) | `'guest'` | code-default | `:185` | **sí** |
-| `vhost` | String | sí (validate!) | `'/'` | code-default | `:186` | no |
-| `logger` | Logger | no | `Logger.new($stdout)` INFO | code-default | `:188` | no |
-| `bunny_logger` | Logger | no | `Logger.new($stdout)` WARN | code-default | `:191` | no |
-| `automatically_recover` | Boolean | no | `true` | code-default | `:193` | no |
-| `network_recovery_interval` | Integer | no | `5` | code-default | `:194` | no |
-| `max_reconnect_attempts` | Integer/nil | no | `nil` (reintenta ∞) | code-default | `:195` | no |
-| `max_reconnect_interval` | Integer | no | `60` | code-default | `:196` | no |
-| `connection_timeout` | Integer | no (1..300) | `10` | code-default | `:197` | no |
-| `read_timeout` | Integer | no (1..300) | `30` | code-default | `:198` | no |
-| `write_timeout` | Integer | no (1..300) | `30` | code-default | `:199` | no |
-| `heartbeat` | Integer | no (0..3600) | `15` | code-default | `:200` | no |
-| `continuation_timeout` | Integer (ms) | no | `15000` | code-default | `:201` | no |
-| `channel_prefetch` | Integer | no (1..10000) | `1` | code-default | `:202` | no |
-| `rpc_timeout` | Integer | no (1..3600) | `10` | code-default | `:203` | no |
-| `health_check_interval` | Integer | no | `60` | code-default | `:204` | no |
-| `health_check_file` | String/nil | no | `nil` (desactivado) | code-default | `:207` | no |
-| `controller_namespace` | String | no | `'BugBunny::Controllers'` | code-default | `:210` | no |
-| `log_tags` | Array | no | `[:uuid]` | code-default | `:212` | no |
-| `exchange_options` | Hash | no | `{}` | code-default | `:215` | no |
-| `queue_options` | Hash | no | `{}` | code-default | `:216` | no |
-| `consumer_middlewares` | Stack (attr_reader) | no | `Stack.new` | code-default | `:218` | no |
-| `rpc_reply_headers` | Proc/nil | no | `nil` | code-default | `:251` | no |
-| `on_rpc_reply` | Proc/nil | no | `nil` | code-default | `:252` | no |
-| `on_return` | Proc/nil | no | `nil` | code-default | `:253` | no |
-| `nack_raise` | Boolean | no | `true` | code-default | `:254` | no |
-| `return_raise` | Boolean | no | `true` | code-default | `:255` | no |
+| `host` | String | sí (validate!) | `'127.0.0.1'` | code-default | `configuration.rb:192` | no |
+| `port` | Integer | sí (validate!, 1..65535) | `5672` | code-default | `:193` | no |
+| `username` | String | sí (validate!) | `'guest'` | code-default | `:194` | no |
+| `password` | String | sí (validate!) | `'guest'` | code-default | `:195` | **sí** |
+| `vhost` | String | sí (validate!) | `'/'` | code-default | `:196` | no |
+| `logger` | Logger | no | `Logger.new($stdout)` INFO | code-default | `:198` | no |
+| `bunny_logger` | Logger | no | `Logger.new($stdout)` WARN | code-default | `:201` | no |
+| `automatically_recover` | Boolean | no | `true` | code-default | `:203` | no |
+| `network_recovery_interval` | Integer | no | `5` | code-default | `:204` | no |
+| `max_reconnect_attempts` | Integer/nil | no | `nil` (reintenta ∞) | code-default | `:205` | no |
+| `max_reconnect_interval` | Integer | no | `60` | code-default | `:206` | no |
+| `connection_timeout` | Integer | no (1..300) | `10` | code-default | `:207` | no |
+| `read_timeout` | Integer | no (1..300) | `30` | code-default | `:208` | no |
+| `write_timeout` | Integer | no (1..300) | `30` | code-default | `:209` | no |
+| `heartbeat` | Integer | no (0..3600) | `15` | code-default | `:210` | no |
+| `continuation_timeout` | Integer (ms) | no | `15000` | code-default | `:211` | no |
+| `channel_prefetch` | Integer | no (1..10000) | `1` | code-default | `:212` | no |
+| `rpc_timeout` | Integer | no (1..3600) | `10` | code-default | `:213` | no |
+| `health_check_interval` | Integer | no | `60` | code-default | `:214` | no |
+| `health_check_file` | String/nil | no | `nil` (desactivado) | code-default | `:217` | no |
+| `drain_idle_timeout` | Integer (s) | no (1..3600) | `5` | code-default | `:274` | no |
+| `drain_poll_interval` | Numeric (s) | no (0.01..10) | `0.1` | code-default | `:275` | no |
+| `controller_namespace` | String | no | `'BugBunny::Controllers'` | code-default | `:220` | no |
+| `log_tags` | Array | no | `[:uuid]` | code-default | `:222` | no |
+| `exchange_options` | Hash | no | `{}` | code-default | `:225` | no |
+| `queue_options` | Hash | no | `{}` | code-default | `:226` | no |
+| `consumer_middlewares` | Stack (attr_reader) | no | `Stack.new` | code-default | `:228` | no |
+| `rpc_reply_headers` | Proc/nil | no | `nil` | code-default | `:262` | no |
+| `on_rpc_reply` | Proc/nil | no | `nil` | code-default | `:263` | no |
+| `on_return` | Proc/nil | no | `nil` | code-default | `:264` | no |
+| `nack_raise` | Boolean | no | `true` | code-default | `:265` | no |
+| `return_raise` | Boolean | no | `true` | code-default | `:266` | no |
 
 > **Override por request:** `nack_raise` y `return_raise` se sobreescriben por
 > llamada con `nack_raise:` / `return_raise:` en `Client#publish` (scope-override
@@ -87,7 +93,7 @@ El install template (`initializer.rb`) **sugiere al consumidor** wirear 4 ENV
 ### d. Derivaciones simples
 
 - `url` ← `"amqp://#{username}:#{password}@#{host}:#{port}/#{vhost}"`
-  (`configuration.rb:225`).
+  (`configuration.rb:236`).
 - `create_connection(**options)` ← `merge_connection_options(options)` sobre la
   config global; las options explícitas pisan los defaults (`bug_bunny.rb:88`).
 
@@ -116,21 +122,22 @@ del código.
 | Conexión (`host`/`port`/`username`/`password`/`vhost`) | conectividad | valor inválido/vacío → `ConfigurationError` en `validate!`; credencial/host errados → `CommunicationError` al conectar (`bug_bunny.rb:95`) | abre socket TCP al broker | identidad y destino del broker; `vhost` aísla ambientes |
 | Timeouts (`connection_timeout`/`read_timeout`/`write_timeout`/`heartbeat`/`continuation_timeout`) | resiliencia/latencia | muy bajo → cortes espurios bajo carga; muy alto → detección de fallo lenta | — | tuning de la conexión Bunny; `heartbeat` detecta conexiones zombi |
 | `rpc_timeout` | latencia | el worker remoto no responde a tiempo → `RequestTimeout` (`producer.rb:124,214`) | bloquea el hilo llamante hasta el timeout | techo de espera de un RPC síncrono |
-| Resiliencia (`automatically_recover`/`network_recovery_interval`/`max_reconnect_attempts`/`max_reconnect_interval`) | resiliencia | `max_reconnect_attempts` agotado → el Consumer re-levanta y muere (`consumer.rb:110-112`) | reintentos con **backoff exponencial** `network_recovery_interval * 2^(n-1)` cap `max_reconnect_interval` (`consumer.rb:115-118`) | sobrevivir caídas transitorias del broker sin perder el worker |
+| Resiliencia (`automatically_recover`/`network_recovery_interval`/`max_reconnect_attempts`/`max_reconnect_interval`) | resiliencia | `max_reconnect_attempts` agotado → el Consumer re-levanta y muere (`consumer.rb:94-96`) | reintentos con **backoff exponencial** `network_recovery_interval * 2^(n-1)` cap `max_reconnect_interval` (`consumer.rb:99-102`) | sobrevivir caídas transitorias del broker sin perder el worker |
 | QoS (`channel_prefetch`) | rendimiento | alto → un worker lento acapara mensajes; `1` → menor throughput | controla unacked in-flight (backpressure) | balancea fairness vs throughput (default `1` = fair round-robin) |
 | Health (`health_check_interval`/`health_check_file`) | observabilidad | `health_check_file` no escribible → el touch falla (degradación de visibilidad, no del flujo) | **escribe (touch) un archivo** en cada health check OK; `nil` desactiva | probe para orquestadores (K8s/Swarm) |
-| Callbacks (`on_return`/`on_rpc_reply`/`rpc_reply_headers`) | extensibilidad | una excepción en `on_return` se captura pero **degrada visibilidad** (YARD `configuration.rb:147`) | corren en hilos sensibles (ver §h) | propagar trace-context / alertar unroutable |
+| Drain (`drain_idle_timeout`/`drain_poll_interval`) | latencia | `drain_idle_timeout` muy bajo → un productor lento deja mensajes para la próxima corrida (no se pierden); muy alto → el job tarda más en terminar tras vaciar la cola | ninguno: sólo acota cuánto espera `Consumer#drain` (`consumer.rb:285`) | correr un consumidor como job que termina (#64) |
+| Callbacks (`on_return`/`on_rpc_reply`/`rpc_reply_headers`) | extensibilidad | una excepción en `on_return` se captura pero **degrada visibilidad** (YARD `configuration.rb:157`) | corren en hilos sensibles (ver §h) | propagar trace-context / alertar unroutable |
 | Confirms (`nack_raise`/`return_raise`) | integridad de entrega | `false` → NACK/return solo se logea, la llamada retorna `202` (modo legacy, posible pérdida silenciosa) | habilitan el raise de `PublishNacked`/`PublishUnroutable` | elegir entre fail-fast vs best-effort en publish confirmado |
-| Routing (`controller_namespace`) | seguridad | clase resuelta no subclase de `BugBunny::Controller` → el worker responde **403** + reject (guard anti-RCE, `consumer.rb:222-228`) | acota qué clases son enrutables | superficie de control de RCE |
+| Routing (`controller_namespace`) | seguridad | clase resuelta no subclase de `BugBunny::Controller` → el worker responde **403** + reject (guard anti-RCE, `consumer.rb:375-381`) | acota qué clases son enrutables | superficie de control de RCE |
 | Logging (`logger`/`bunny_logger`/`log_tags`) | observabilidad | — | salida a `$stdout` por default | trazabilidad estructurada |
 | Infra (`exchange_options`/`queue_options`) | infraestructura | options incompatibles con el broker → `PreconditionFailed` (vía `CommunicationError`) | defaults globales mergeados por recurso | declaración AMQP por default |
 
 ### g. Ramificadores intra-config
 
 - `health_check_file = nil` (default) **desactiva** el touchfile aunque
-  `health_check_interval` siga corriendo (`configuration.rb:99-101,207`).
+  `health_check_interval` siga corriendo (`configuration.rb:109-111,217`).
 - `return_raise` es **inerte cuando `mandatory: false`** — sin `mandatory` el
-  broker nunca retorna, así que el flag no tiene efecto (`configuration.rb:171`).
+  broker nunca retorna, así que el flag no tiene efecto (`configuration.rb:181`).
 - `nack_raise`/`return_raise` se sobreescriben **por request** (`Client#publish`),
   ganando sobre el valor global (scope-override).
 
@@ -138,10 +145,10 @@ del código.
 
 | opción | hilo de ejecución | restricción |
 |---|---|---|
-| `on_return` | **hilo interno del consumidor de Bunny** (`configuration.rb:147`) | debe ser rápido y no lanzar; BugBunny captura, pero degrada visibilidad |
-| `on_rpc_reply` | **hilo llamante** tras recibir el reply RPC (`configuration.rb:132`) | hidrata trace-context en el publisher |
-| `rpc_reply_headers` | hilo del consumer, justo antes del `basic_publish` del reply (`configuration.rb:125`) | debe retornar un Hash de headers |
-| reconexión del Consumer | hilo del `subscribe` loop (`consumer.rb:90,122`) | `sleep wait` bloquea ese hilo durante el backoff |
+| `on_return` | **hilo interno del consumidor de Bunny** (`configuration.rb:157`) | debe ser rápido y no lanzar; BugBunny captura, pero degrada visibilidad |
+| `on_rpc_reply` | **hilo llamante** tras recibir el reply RPC (`configuration.rb:142`) | hidrata trace-context en el publisher |
+| `rpc_reply_headers` | hilo del consumer, justo antes del `basic_publish` del reply (`configuration.rb:135`) | debe retornar un Hash de headers |
+| reconexión del Consumer | hilo del `subscribe` loop (`consumer.rb:87,106`) | `sleep wait` bloquea ese hilo durante el backoff |
 
 ### j. Inyección a gemas configuradas
 

data/docs/consumed/rabbitmq.md

@@ -69,16 +69,16 @@ catálogo `docs/errors/errors.md` (RFC-020), no lo redefine.
 
 | aspecto | comportamiento (anclado) |
 |---|---|
-| recuperación de conexión | `automatically_recover = true` (default): Bunny recupera canales/suscripciones tras corte TCP (`configuration.rb:60-61`). |
-| retry del Consumer | `Consumer#subscribe` reintenta en cualquier `StandardError` con **backoff exponencial** `network_recovery_interval * 2^(n-1)` cap `max_reconnect_interval`, hasta `max_reconnect_attempts` (`nil` = ∞) (`consumer.rb:106-124`). |
-| ack | `manual_ack: true` (`consumer.rb:90`) → entrega **at-least-once**: si el worker cae tras procesar pero antes del ack, el mensaje se re-entrega. **El handler debe ser idempotente.** |
+| recuperación de conexión | `automatically_recover = true` (default): Bunny recupera canales/suscripciones tras corte TCP (`configuration.rb:62-63`). |
+| retry del Consumer | `Consumer#subscribe` reintenta en cualquier `StandardError` con **backoff exponencial** `network_recovery_interval * 2^(n-1)` cap `max_reconnect_interval`, hasta `max_reconnect_attempts` (`nil` = ∞) (`consumer.rb:90-108`). |
+| ack | `manual_ack: true` (`consumer.rb:87`) → entrega **at-least-once**: si el worker cae tras procesar pero antes del ack, el mensaje se re-entrega. **El handler debe ser idempotente.** |
 | retry de publish | **no automático** — un publish fallido levanta `CommunicationError`/`PublishNacked`; reintentarlo puede **duplicar** salvo dedup aguas abajo. |
 | RPC | `request` espera reply hasta `rpc_timeout`; el retry de un RPC mutante requiere idempotencia (correlación por `correlation_id`). |
 
 ### e. Degradación (si RabbitMQ cae)
 
 - **Al conectar:** `create_connection` levanta `CommunicationError` (`bug_bunny.rb:95`); no hay fallback ni cola local — el caller decide (circuit-break/alertar).
-- **Consumer:** entra al loop de reconexión con backoff; por default (`max_reconnect_attempts = nil`) **reintenta indefinidamente**, logueando `consumer.connection_error` con `retry_in_s` (`consumer.rb:120-122`). Si se fija un máximo y se agota → `consumer.reconnect_exhausted` y re-raise (el worker muere).
+- **Consumer:** entra al loop de reconexión con backoff; por default (`max_reconnect_attempts = nil`) **reintenta indefinidamente**, logueando `consumer.connection_error` con `retry_in_s` (`consumer.rb:104-106`). Si se fija un máximo y se agota → `consumer.reconnect_exhausted` y re-raise (el worker muere).
 - **Publisher:** cada publish/RPC sobre conexión caída levanta `CommunicationError` (envuelto en `client.rb:168`); **sin buffering** — el mensaje no sale.
 - **Sin circuit-breaker propio:** la gema no trae breaker ni outbox; la resiliencia aguas arriba (reintentar el comando, encolar, alertar) es responsabilidad del consumidor.
 

data/docs/errors/errors.md

@@ -46,7 +46,7 @@ Jerarquía (todas bajo `BugBunny::Error < ::StandardError`):
 |---|---|---|
 | `Error` | `::StandardError` | base — no se levanta directa salvo `resource.rb:122` (pool ausente) |
 | `CommunicationError` | `Error` | `bug_bunny.rb:96`, `session.rb:177,285`, `producer.rb:90`, `client.rb:168` — envuelve cualquier `Bunny::Exception` en la frontera del gem; original en `.cause` |
-| `ConfigurationError` | `Error` | `configuration.rb:262,269,277` — validación al final de `BugBunny.configure` |
+| `ConfigurationError` | `Error` | `configuration.rb:282,289,297` — validación al final de `BugBunny.configure` |
 | `PublishNacked` | `Error` | `producer.rb:235` — NACK del broker en modo `:confirmed`. Attrs: `path`, `nacked_count`. Opt-out `nack_raise: false` |
 | `PublishUnroutable` | `Error` | `producer.rb:325` — `basic.return` con `mandatory: true`. Attrs: `path`, `exchange`, `routing_key`, `reply_code`, `reply_text`, `correlation_id`. Opt-out `return_raise: false` |
 | `ClientError` | `Error` | `raise_error.rb:170` — 4xx no mapeado explícito |
@@ -85,7 +85,7 @@ operaciones de RFC-003 (`docs/api/`, hoy pendiente — ver §4), no las redefine
 | Cliente RPC | otro ≥400 | `ClientError` | 4xx no mapeado |
 | Productor (publish `:confirmed`) | n/a (AMQP) | `PublishNacked` / `PublishUnroutable` | NACK / return del broker — no es status HTTP |
 | Transporte (frontera gem) | n/a (AMQP) | `CommunicationError` | fallo de red/broker, envuelve `Bunny::Exception` |
-| **Worker (dispatch)** | **403** | — (no excepción; responde 403 + reject) | guard anti-RCE: clase enrutada no subclase de `BugBunny::Controller` (`consumer.rb:222-228`) |
+| **Worker (dispatch)** | **403** | — (no excepción; responde 403 + reject) | guard anti-RCE: clase enrutada no subclase de `BugBunny::Controller` (`consumer.rb:375-381`) |
 
 ### c. Política por error
 
@@ -133,7 +133,7 @@ ante una excepción no mapeada por `rescue_from`:
 ```
 
 - El envelope `bug_bunny_exception` lo arma `RemoteError.serialize` (`remote_error.rb:29`);
-  también lo agrega `Consumer` cuando `status == 500 && exception` (`consumer.rb:325`).
+  también lo agrega `Consumer` cuando `status == 500 && exception` (`consumer.rb:478`).
   Es lo que el cliente reconstruye como `RemoteError` (`raise_error.rb:61-64`).
 - `render status:, json:` (`controller.rb:242`) deja el shape del body de error de
   dominio a criterio del worker — la gema no lo impone.
@@ -168,7 +168,7 @@ parsea el body, devuelve `parsed['errors']` por convención o el cuerpo completo
 ## 3. Inferencias
 
 - **Guard anti-RCE = 403, no excepción.** El control de seguridad que valida la
-  herencia de la clase enrutada vive en `consumer.rb:222-228`: si la clase
+  herencia de la clase enrutada vive en `consumer.rb:375-381`: si la clase
   resuelta no es subclase de `BugBunny::Controller`, el worker loguea
   `consumer.security_violation`, responde **403 'Forbidden'** (`handle_fatal_error`)
   y rechaza el mensaje sin requeue — **no levanta una excepción dedicada**. La ex

data/docs/release/release.md

@@ -21,9 +21,9 @@ out-of-repo).
 
 ### a. Hecho verificable
 
-- **Convención de versión:** SemVer `vX.X.X`. Actual: **5.1.1**.
-- **Source of truth:** tag remoto (`v5.1.1`) + **triple mirror**
-  `lib/bug_bunny/version.rb` (`VERSION = '5.1.1'`) ← `bug_bunny.gemspec:7`
+- **Convención de versión:** SemVer `vX.X.X`. Actual: **5.2.0**.
+- **Source of truth:** tag remoto (`v5.2.0`) + **triple mirror**
+  `lib/bug_bunny/version.rb` (`VERSION = '5.2.0'`) ← `bug_bunny.gemspec:7`
   (`spec.version = BugBunny::VERSION`).
 - **Changelog canónico:** `CHANGELOG.md` único.
 - **Patrón de trigger:** `gema-tag` (patrón 1).
@@ -34,7 +34,7 @@ out-of-repo).
 
 - **Convención:** SemVer `vX.X.X` (**con `v`** — distinto al servicio).
 - **Source of truth:** tag remoto canónico (`git tag --sort=-v:refname` →
-  `v5.1.1`).
+  `v5.2.0`).
 - **Mirror:** `lib/bug_bunny/version.rb` (`VERSION`), leído por
   `bug_bunny.gemspec:7` (`spec.version = BugBunny::VERSION`).
   `required_ruby_version >= 2.6.0` (`bug_bunny.gemspec:17`).
@@ -85,9 +85,11 @@ procedimiento per-repo porque no vive acá. Una versión yankeada se anotaría e
   `>= 5.1.0, < 5.2.0`, así que un minor **no entra** sin editar el `Gemfile`.
   Consecuencia operativa: un fix publicado como **patch** lo toman con
   `bundle update bug_bunny`; uno publicado como **minor** requiere tocar el pin
-  en cada consumidor. Estado hoy: `box_manager_service` y `box_radius_manager`
-  en `~> 5.1.0`; `box_acs_manager` y `box_cluster_manager` todavía en
-  `~> 4.19.0` (bumps pendientes). Un cambio de contrato del gem (ej. el
+  en cada consumidor. Estado medido el 2026-09-29 (Gemfiles de los clones del
+  workspace): `box_manager_service` en `~> 5.1.1`; `box_acs_manager`,
+  `box_cluster_manager` y `box_radius_manager` en `~> 5.1.0` — o sea que
+  **5.2.0 no le entra a ninguno** sin tocar el pin. *(El estado anterior decía
+  `box_acs_manager`/`box_cluster_manager` en `~> 4.19.0`: ya no es así.)* Un cambio de contrato del gem (ej. el
   behavior-change de `4.18.0` — `Bunny::Exception` → `CommunicationError`, o la
   eliminación de `BugBunny::SecurityError` en `5.0.0`) obliga a los consumidores
   a migrar; el `CHANGELOG.md` lo documenta como breaking note. **Orden de

data/docs/test/testing.md

@@ -1,14 +1,15 @@
 # Test — bug_bunny
 
 > meta: artefacto test · RFC-013 · generado `arch-structure` (§a-§d) +
-> `arch-enrich` (§e-§h) · anclado a `7bf1da7`, `Rakefile`, `bug_bunny.gemspec`,
+> `arch-enrich` (§e-§h) · anclado a `35b075a` (squash de #65 en `main`; el ancla anterior `7bf1da7` no era ancestro de `main`), `Rakefile`, `bug_bunny.gemspec`,
 > `spec/spec_helper.rb`, `spec/support/integration_helper.rb`,
 > `.github/workflows/main.yml`, `CHANGELOG.md` · fecha 2026-07-22 · cobertura:
 > §a-§d (estructura) + §e-§h (enrich, anclado a specs/CHANGELOG) completas.
+> Incremento 2026-09-28 (#64): conteos, `drain_*_spec` y el gap de aislamiento.
 
 ## 1. Resumen
 
-Suite principal **RSpec** (`spec/`, 23 specs: 16 unit + 7 integration). Tarea
+Suite principal **RSpec** (`spec/`, 25 specs: 17 unit + 8 integration). Tarea
 `:test` legacy de **Minitest** (`test/`, 2 archivos) fuera del default y del CI.
 CI corre `bundle exec rake` (= `:spec`) en Ruby 3.4.4. Sin coverage tool
 configurado.
@@ -19,8 +20,8 @@ configurado.
 
 | framework | dir | nivel | nº | propósito |
 |---|---|---|---|---|
-| **RSpec** `~> 3.0` | `spec/unit/` | unit | 16 | client/session pool, configuration, consumer, producer, controller, raise_error, remote_error, request, route, observability, otel, resource, middleware, `extra_top_level_params` (hook de params hermanos en `Resource#save`) |
-| **RSpec** | `spec/integration/` | integration | 7 | client, consumer_middleware, controller, error_handling, infrastructure, publisher_confirms, resource — **requieren RabbitMQ real** (usan `BugBunny.create_connection` + pool) |
+| **RSpec** `~> 3.0` | `spec/unit/` | unit | 17 | client/session pool, configuration, consumer, `drain_tracker`, producer, controller, raise_error, remote_error, request, route, observability, otel, resource, middleware, `extra_top_level_params` (hook de params hermanos en `Resource#save`) |
+| **RSpec** | `spec/integration/` | integration | 8 | client, consumer_middleware, controller, drain, error_handling, infrastructure, publisher_confirms, resource — **requieren RabbitMQ real** (usan `BugBunny.create_connection` + pool) |
 | **Minitest** `~> 5.0` (+ `mocha`, `minitest-reporters`) | `test/integration/` | integration (legacy) | 2 | `manual_client_test.rb`, `infrastructure_test.rb` — tarea `:test`, **no** en default ni CI |
 
 Sin tags declarados (`:slow`/`:js`) en la config de RSpec.
@@ -58,9 +59,9 @@ umbral de coverage declarado.
 ### e. Gaps de cobertura
 
 - **Integration specs no corren en CI:** `main.yml` no declara servicio RabbitMQ;
-  las 7 integration specs **se skipean** vía `rabbitmq_available?`
+  las 8 integration specs **se skipean** vía `rabbitmq_available?`
   (`spec/support/integration_helper.rb:14`, ver `publisher_confirms_spec.rb:10`).
-  En CI solo se ejercitan las **16 unit specs** → el contrato AMQP real (publish/
+  En CI solo se ejercitan las **17 unit specs** → el contrato AMQP real (publish/
   consume/confirms contra broker) **no se valida en pipeline**, solo localmente
   con broker. Gap relevante.
 - **Sin medición de cobertura:** no hay SimpleCov ni umbral → la cobertura no está
@@ -75,9 +76,18 @@ umbral de coverage declarado.
 | **Errores RFC-020** (status→excepción, materia prima) | `raise_error_spec`, `remote_error_spec`, `communication_error_wrapping_spec`, `error_handling_spec` (integration) | **bien cubierto** (unit) |
 | **Consumed RFC-018** (Bunny::Exception→`CommunicationError`) | `communication_error_wrapping_spec`, `client_session_pool_spec` | cubierto (unit) |
 | **Config RFC-012** (validaciones de `Configuration`) | `configuration_spec` | cubierto |
+| **Consumer#drain** (drenar y salir, #64) | `drain_tracker_spec` (unit, reloj inyectado), `drain_spec` (integration) | cubierto; la parte integration skipea sin broker. Validado por mutación: quitar la espera, el retorno temprano o el chequeo de `busy?` hace fallar el test correspondiente |
 | **Confirms** (`PublishNacked`/`PublishUnroutable`) | `producer_spec`, `publisher_confirms_spec` (integration) | parcial en CI (la parte integration skipea sin broker) |
 | **Operaciones/routing** (RFC-003, capa F2) | `route_spec`, `request_spec`, `controller_spec`, `controller_after_action_spec`, `resource_spec` | cubierto (unit) |
 
+- **Aislamiento entre specs — corregido 2026-09-28 (#64):** el `after` de
+  `configuration_spec` reemplazaba la configuración global por una con defaults
+  (`guest`), así que los specs de integración que corrían después se conectaban
+  como `guest` y se **skipeaban como "RabbitMQ no disponible" aun con broker**.
+  Cuántos, dependía del seed (11 en `main` con `--seed 1`). Ahora un `around`
+  restaura la configuración original (`spec/unit/configuration_spec.rb:14-22`);
+  medido con broker local: 311 examples, 0 failures, 0 pending en los seeds 1, 2 y 3.
+
 ### g. Link a incidente → test de regresión
 
 | incidente | test de regresión | ancla |

data/lib/bug_bunny/configuration.rb

@@ -21,7 +21,7 @@ module BugBunny
     # Claves soportadas:
     # - `:type`     — clase que debe responder `is_a?`
     # - `:required` — si `true`, nil o string vacío lanzan ConfigurationError
-    # - `:range`    — rango válido de valores (solo para Integer)
+    # - `:range`    — rango válido de valores (solo para numéricos)
     VALIDATIONS = {
       host: { type: String, required: true },
       port: { type: Integer, required: true, range: 1..65_535 },
@@ -33,7 +33,9 @@ module BugBunny
       read_timeout: { type: Integer, range: 1..300 },
       write_timeout: { type: Integer, range: 1..300 },
       rpc_timeout: { type: Integer, range: 1..3_600 },
-      channel_prefetch: { type: Integer, range: 1..10_000 }
+      channel_prefetch: { type: Integer, range: 1..10_000 },
+      drain_idle_timeout: { type: Integer, range: 1..3_600 },
+      drain_poll_interval: { type: Numeric, range: 0.01..10 }
     }.freeze
 
     # @return [String] Host o IP del servidor RabbitMQ (ej: 'localhost').
@@ -94,6 +96,14 @@ module BugBunny
     # @return [Integer] Intervalo en segundos para verificar la salud de la cola.
     attr_accessor :health_check_interval
 
+    # @return [Integer] Segundos sin entregas tras los cuales {BugBunny::Consumer#drain}
+    #   da la cola por vacía y retorna (default: 5).
+    attr_accessor :drain_idle_timeout
+
+    # @return [Numeric] Cada cuántos segundos {BugBunny::Consumer#drain} revisa si se
+    #   cumplió la ventana de inactividad (default: 0.1).
+    attr_accessor :drain_poll_interval
+
     # @return [String, nil] Ruta del archivo que se actualizará (touch) en cada health check exitoso.
     #   Ideal para sondas (probes) de orquestadores como Docker Swarm o Kubernetes.
     #   Si es `nil`, la funcionalidad de touchfile se desactiva.
@@ -217,6 +227,7 @@ module BugBunny
 
       @consumer_middlewares = ConsumerMiddleware::Stack.new
       init_callback_defaults
+      init_drain_defaults
     end
 
     # Construye la URL de conexión AMQP basada en los atributos configurados.
@@ -255,6 +266,15 @@ module BugBunny
       @return_raise = true
     end
 
+    # Defaults de {BugBunny::Consumer#drain}.
+    # Extraído de {#initialize} para mantener el ABC size dentro de los límites.
+    #
+    # @return [void]
+    def init_drain_defaults
+      @drain_idle_timeout = 5
+      @drain_poll_interval = 0.1
+    end
+
     def validate_required!(attr, value, rules)
       return unless rules[:required]
       return unless value.nil? || (value.is_a?(String) && value.empty?)