bug_bunny 5.1.1 → 5.2.0

data/lib/bug_bunny/consumer.rb

@@ -41,6 +41,16 @@ module BugBunny
       new(connection).subscribe(**args)
     end
 
+    # Método de conveniencia para instanciar y drenar en un solo paso.
+    #
+    # @param connection [Bunny::Session] Una conexión TCP activa a RabbitMQ. Es de quien
+    #   llama: `drain` no la cierra (ver {#drain}).
+    # @param args [Hash] Argumentos que se pasarán al método {#drain}.
+    # @return [Integer] Cantidad de mensajes procesados.
+    def self.drain(connection:, **args)
+      new(connection).drain(**args)
+    end
+
     # Inicializa un nuevo consumidor.
     #
     # @param connection [Bunny::Session] Conexión nativa de Bunny.
@@ -68,40 +78,14 @@ module BugBunny
       attempt = 0
 
       begin
-        # Declaración de Infraestructura
-        x = session.exchange(name: exchange_name, type: exchange_type, opts: exchange_opts)
-        q = session.queue(queue_name, queue_opts)
-        q.bind(x, routing_key: routing_key)
-
-        # 📊 LOGGING DE OBSERVABILIDAD: Calculamos las opciones finales para mostrarlas en consola
-        final_x_opts = BugBunny::Session::DEFAULT_EXCHANGE_OPTIONS
-                       .merge(BugBunny.configuration.exchange_options || {})
-                       .merge(exchange_opts || {})
-        final_q_opts = BugBunny::Session::DEFAULT_QUEUE_OPTIONS
-                       .merge(BugBunny.configuration.queue_options || {})
-                       .merge(queue_opts || {})
-
-        safe_log(:info, 'consumer.start', queue: queue_name, queue_opts: final_q_opts)
-        safe_log(:info, 'consumer.bound', exchange: exchange_name, exchange_type: exchange_type,
-                                          routing_key: routing_key, exchange_opts: final_x_opts)
+        queue = declare_infrastructure(queue_name: queue_name, exchange_name: exchange_name,
+                                       routing_key: routing_key, exchange_type: exchange_type,
+                                       exchange_opts: exchange_opts, queue_opts: queue_opts)
 
         start_health_check(queue_name)
 
-        q.subscribe(manual_ack: true, block: block) do |delivery_info, properties, body|
-          trace_id = properties.correlation_id
-          logger = BugBunny.configuration.logger
-
-          core = lambda {
-            if logger.respond_to?(:tagged)
-              logger.tagged(trace_id) { process_message(delivery_info, properties, body) }
-            elsif defined?(Rails) && Rails.logger.respond_to?(:tagged)
-              Rails.logger.tagged(trace_id) { process_message(delivery_info, properties, body) }
-            else
-              process_message(delivery_info, properties, body)
-            end
-          }
-
-          BugBunny.configuration.consumer_middlewares.call(delivery_info, properties, body, &core)
+        queue.subscribe(manual_ack: true, block: block) do |delivery_info, properties, body|
+          handle_delivery(delivery_info, properties, body)
         end
       rescue StandardError => e
         attempt += 1
@@ -126,6 +110,71 @@ module BugBunny
       shutdown
     end
 
+    # Consume la cola hasta vaciarla y retorna: el modo para correr un consumidor como job
+    # (Sidekiq, un Job de k8s) en vez de como un proceso eterno.
+    #
+    # A diferencia de `subscribe(block: false)`, que retorna al instante, este método
+    # bloquea mientras haya mensajes y vuelve cuando la cola queda quieta:
+    #
+    # 1. Si la cola tiene 0 mensajes al arrancar, retorna `0` sin esperar.
+    # 2. Si hay mensajes, se suscribe con `manual_ack: true` respetando `channel_prefetch`,
+    #    igual que el modo bloqueante.
+    # 3. Termina cuando pasaron `drain_idle_timeout` segundos (ver {Configuration}) sin
+    #    entregas y no queda ningún mensaje en proceso. Cancela el consumer y cierra el
+    #    canal ({#shutdown}).
+    #
+    # **Mensajes que llegan mientras drena:** un mensaje que llega antes de que venza la
+    # ventana de inactividad se procesa en esta vuelta; lo que llega después queda para
+    # la próxima corrida. Una entrega ya recibida cuando se cancela se procesa antes de
+    # volver (Bunny drena su work pool al cancelar); si igual no llegara a ack-earse, vuelve
+    # a la cola (at-least-once, nunca se pierde).
+    #
+    # **Con un flujo sostenido, no retorna.** Si los mensajes llegan más seguido que
+    # `drain_idle_timeout`, la ventana nunca vence: la duración la decide el productor, no
+    # la cola que había al arrancar. Acotalo desde afuera (el timeout del job de Sidekiq,
+    # `activeDeadlineSeconds` en k8s), sabiendo que cortarlo a mitad de una entrega da
+    # redelivery.
+    #
+    # **Una entrega que falla sale de la cola.** Si un middleware o el manejo de error
+    # levanta antes del ack, se rechaza sin requeue, igual que los errores de
+    # `process_message`; no queda ocupando el prefetch.
+    #
+    # No tiene loop de reconexión ni health check: un job que falla lo reintenta el
+    # framework que lo corre. (Bunny sí recupera la conexión por su cuenta si
+    # `automatically_recover` está activo.)
+    #
+    # **La conexión es de quien llama:** `drain` cierra su canal al volver, no la conexión,
+    # porque puede ser compartida (un pool, la del publisher). Si la creaste para esta
+    # corrida, cerrala vos (ver el README).
+    #
+    # @param queue_name [String] Nombre de la cola a drenar.
+    # @param exchange_name [String] Nombre del exchange al cual enlazar la cola.
+    # @param routing_key [String] Patrón de enrutamiento (ej: 'users.*').
+    # @param exchange_type [String] Tipo de exchange ('direct', 'topic', 'fanout').
+    # @param exchange_opts [Hash] Opciones adicionales para el exchange (durable, auto_delete).
+    # @param queue_opts [Hash] Opciones adicionales para la cola (durable, auto_delete).
+    # @return [Integer] Cantidad de mensajes procesados en esta vuelta (incluye los rechazados:
+    #   también salieron de la cola).
+    def drain(queue_name:, exchange_name:, routing_key:, exchange_type: 'direct', exchange_opts: {},
+              queue_opts: {})
+      started_at = monotonic_now
+      queue = declare_infrastructure(queue_name: queue_name, exchange_name: exchange_name,
+                                     routing_key: routing_key, exchange_type: exchange_type,
+                                     exchange_opts: exchange_opts, queue_opts: queue_opts)
+
+      pending_count = queue.message_count
+      safe_log(:info, 'consumer.drain_start', queue: queue_name, pending_count: pending_count)
+      return 0 if pending_count.zero?
+
+      processed_count = consume_until_idle(queue)
+
+      safe_log(:info, 'consumer.drain_finished', queue: queue_name, processed_count: processed_count,
+                                                 duration_s: (monotonic_now - started_at).round(3))
+      processed_count
+    ensure
+      shutdown
+    end
+
     # Detiene el health check timer y cierra el canal de forma ordenada.
     #
     # Llamar explícitamente al hacer shutdown del worker (SIGTERM, at_exit, etc.).
@@ -141,6 +190,110 @@ module BugBunny
 
     private
 
+    # Declara exchange y cola, los enlaza y loguea las opciones efectivas.
+    #
+    # @param queue_name [String] Nombre de la cola.
+    # @param exchange_name [String] Nombre del exchange.
+    # @param routing_key [String] Patrón de enrutamiento del binding.
+    # @param exchange_type [String] Tipo de exchange.
+    # @param exchange_opts [Hash] Opciones del exchange para esta llamada.
+    # @param queue_opts [Hash] Opciones de la cola para esta llamada.
+    # @return [Bunny::Queue] La cola declarada y enlazada.
+    def declare_infrastructure(queue_name:, exchange_name:, routing_key:, exchange_type:, exchange_opts:, queue_opts:)
+      exchange = session.exchange(name: exchange_name, type: exchange_type, opts: exchange_opts)
+      queue = session.queue(queue_name, queue_opts)
+      queue.bind(exchange, routing_key: routing_key)
+
+      # 📊 LOGGING DE OBSERVABILIDAD: Calculamos las opciones finales para mostrarlas en consola
+      effective_exchange_opts = BugBunny::Session::DEFAULT_EXCHANGE_OPTIONS
+                                .merge(BugBunny.configuration.exchange_options || {})
+                                .merge(exchange_opts || {})
+      effective_queue_opts = BugBunny::Session::DEFAULT_QUEUE_OPTIONS
+                             .merge(BugBunny.configuration.queue_options || {})
+                             .merge(queue_opts || {})
+
+      safe_log(:info, 'consumer.start', queue: queue_name, queue_opts: effective_queue_opts)
+      safe_log(:info, 'consumer.bound', exchange: exchange_name, exchange_type: exchange_type,
+                                        routing_key: routing_key, exchange_opts: effective_exchange_opts)
+      queue
+    end
+
+    # Pasa una entrega por los middlewares y el logger con tags, y la procesa.
+    #
+    # @param delivery_info [Bunny::DeliveryInfo, Bunny::GetResponse] Metadatos de entrega.
+    # @param properties [Bunny::MessageProperties] Headers y propiedades AMQP.
+    # @param body [String] El payload crudo del mensaje.
+    # @return [void]
+    def handle_delivery(delivery_info, properties, body)
+      settled = false
+
+      core = lambda {
+        with_log_tags(properties.correlation_id) { process_message(delivery_info, properties, body) }
+        settled = true
+      }
+
+      BugBunny.configuration.consumer_middlewares.call(delivery_info, properties, body, &core)
+    rescue StandardError => e
+      settle_failed_delivery(delivery_info, settled, e)
+    end
+
+    # Corre el bloque con el `correlation_id` como tag del logger, si el logger los soporta.
+    #
+    # @param trace_id [String, nil]
+    # @return [Object] lo que devuelva el bloque
+    def with_log_tags(trace_id, &block)
+      logger = BugBunny.configuration.logger
+      if logger.respond_to?(:tagged)
+        logger.tagged(trace_id, &block)
+      elsif defined?(Rails) && Rails.logger.respond_to?(:tagged)
+        Rails.logger.tagged(trace_id, &block)
+      else
+        yield
+      end
+    end
+
+    # Una entrega cuyo procesamiento levantó FUERA del rescue de `process_message` (un
+    # middleware, o `handle_fatal_error`) quedaba sin ack ni reject: con prefetch 1 ocupaba
+    # el único lugar, el broker dejaba de entregar y `drain` volvía "con éxito" con la cola
+    # llena. Se rechaza sin requeue, igual que `process_message` hace con sus propios
+    # errores. Si ya se había resuelto (el error vino después del ack), sólo se loguea:
+    # rechazar un tag ya confirmado cierra el canal.
+    #
+    # @param delivery_info [Bunny::DeliveryInfo, Bunny::GetResponse] Metadatos de entrega.
+    # @param settled [Boolean] si `process_message` ya hizo ack o reject.
+    # @param error [StandardError] lo que levantó.
+    # @return [void]
+    def settle_failed_delivery(delivery_info, settled, error)
+      safe_log(:error, 'consumer.delivery_failed', settled: settled, **exception_metadata(error))
+      session.channel.reject(delivery_info.delivery_tag, false) unless settled
+    end
+
+    # Se suscribe sin bloquear y espera a que la cola quede quieta `drain_idle_timeout`
+    # segundos sin ningún mensaje en proceso; después cancela la suscripción.
+    #
+    # @param queue [Bunny::Queue] La cola ya declarada y enlazada.
+    # @return [Integer] Cantidad de mensajes procesados.
+    def consume_until_idle(queue)
+      idle_timeout = BugBunny.configuration.drain_idle_timeout
+      poll_interval = BugBunny.configuration.drain_poll_interval
+      tracker = BugBunny::DrainTracker.new
+
+      subscription = queue.subscribe(manual_ack: true, block: false) do |delivery_info, properties, body|
+        tracker.track { handle_delivery(delivery_info, properties, body) }
+      end
+
+      sleep poll_interval until tracker.idle?(idle_timeout)
+
+      subscription.cancel
+      sleep poll_interval while tracker.busy?
+      tracker.processed
+    end
+
+    # @return [Float] Reloj monotónico en segundos.
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
     # Procesa un mensaje individual recibido de la cola orquestando el ruteo declarativo.
     #
     # Realiza la orquestación completa: Parsing -> Reconocimiento de Ruta -> Ejecución -> Respuesta.

data/lib/bug_bunny/drain_tracker.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module BugBunny
+  # Lleva la cuenta de un drenaje de {Consumer#drain}: cuántos mensajes se procesaron,
+  # cuántos están en proceso y cuándo fue la última actividad.
+  #
+  # Es thread-safe: las entregas corren en el work pool de Bunny y la espera en el hilo
+  # que llamó a `drain`.
+  #
+  # @api private
+  class DrainTracker
+    # @param clock [#call] Reloj monotónico en segundos (inyectable para tests).
+    def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      @clock = clock
+      @processed = Concurrent::AtomicFixnum.new(0)
+      @in_flight = Concurrent::AtomicFixnum.new(0)
+      @last_activity = Concurrent::AtomicReference.new(clock.call)
+    end
+
+    # Envuelve el procesamiento de una entrega. Cuenta la entrega como procesada aunque
+    # el bloque levante: {Consumer#handle_delivery} rechaza la que falla antes del ack, así
+    # que en todos los caminos el mensaje ya salió de la cola (ack o reject).
+    #
+    # @yield El procesamiento de la entrega.
+    # @return [void]
+    def track
+      @in_flight.increment
+      yield
+    ensure
+      @processed.increment
+      @last_activity.set(@clock.call)
+      @in_flight.decrement
+    end
+
+    # @return [Boolean] `true` si hay alguna entrega en proceso.
+    def busy?
+      @in_flight.value.positive?
+    end
+
+    # @param idle_timeout [Numeric] Segundos sin actividad.
+    # @return [Boolean] `true` si no hay nada en proceso y pasaron `idle_timeout` segundos
+    #   desde la última actividad.
+    def idle?(idle_timeout)
+      !busy? && @clock.call - @last_activity.get >= idle_timeout
+    end
+
+    # @return [Integer] Entregas procesadas hasta ahora.
+    def processed
+      @processed.value
+    end
+  end
+end

data/lib/bug_bunny/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BugBunny
-  VERSION = '5.1.1'
+  VERSION = '5.2.0'
 end

data/lib/bug_bunny.rb

@@ -16,6 +16,7 @@ require_relative 'bug_bunny/middleware/raise_error'
 require_relative 'bug_bunny/middleware/json_response'
 require_relative 'bug_bunny/client'
 require_relative 'bug_bunny/session'
+require_relative 'bug_bunny/drain_tracker'
 require_relative 'bug_bunny/consumer'
 require_relative 'bug_bunny/request'
 require_relative 'bug_bunny/producer'

data/skill/SKILL.md

@@ -19,7 +19,9 @@ Gema Ruby: capa de routing RESTful sobre AMQP/RabbitMQ. Microservicios se comuni
 
 ## Contrato resumido (piso mínimo)
 
-> Resume el contrato de **`bug_bunny` 5.1.1** (anclado a `v5.1.1`). 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).
+> 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`.
 
@@ -29,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` |
@@ -56,11 +58,12 @@ 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, `v5.1.1`; `gemspec.files` incluye `docs/**`, así que estos archivos viajan dentro del `.gem` que ya tenés instalado).
+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 |
 |---|---|---|
@@ -252,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
@@ -428,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

@@ -63,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