bug_bunny 5.1.0 → 5.2.0

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?)

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/exception.rb

@@ -23,11 +23,15 @@ module BugBunny
     #   respuesta RPC (ej: {CommunicationError}, {ConfigurationError}).
     #
     # @note **No loguear ni enviar a sinks (Sentry/logs) sin sanitizar.** El
-    #   cuerpo crudo puede contener datos sensibles (p. ej. en `details`). Antes
-    #   de cualquier sink, filtrar las claves sensibles del fleet
-    #   (`password|pass|passwd|secret|token|api_key|auth`) → `[FILTERED]`. La
-    #   gema entrega el cuerpo crudo a propósito; sanitizarlo es responsabilidad
-    #   del consumidor.
+    #   cuerpo crudo puede contener datos sensibles (p. ej. en `details`). La
+    #   lista canónica de claves sensibles es
+    #   {BugBunny::Observability::SENSITIVE_KEYS} — no la repliques acá ni en el
+    #   consumidor: se desincroniza (ojo que `pass` bare NO está en la lista, a
+    #   propósito, para no filtrar `passport_number`). Para sanear, reusá
+    #   {BugBunny::Observability.sensitive_key?} (filtra por NOMBRE de clave) y
+    #   {BugBunny::Observability.redact_structure} (recorre la estructura y
+    #   además redacta credenciales embebidas en el VALOR). La gema entrega el
+    #   cuerpo crudo a propósito; sanitizarlo es responsabilidad del consumidor.
     attr_accessor :raw_response
 
     # @return [Integer, nil] El código de estado de la respuesta que originó el

data/lib/bug_bunny/observability.rb

@@ -27,6 +27,81 @@ module BugBunny
       SENSITIVE_KEYS.any? { |sensitive| key_str.include?(sensitive) }
     end
 
+    # Alternación de keys sensibles ordenada de más larga a más corta: en un regex
+    # la alternación matchea leftmost-first, así que sin este orden `auth` ganaría
+    # sobre `authorization` y el patrón dejaría de matchear (`orization=x` no sigue
+    # con `[:=]`).
+    SENSITIVE_KEYS_ALTERNATION = SENSITIVE_KEYS.sort_by { |k| -k.length }.join('|').freeze
+
+    # Reglas de VALOR sensible, como pares `[regex, reemplazo]`.
+    #
+    # {.sensitive_key?} solo ve el NOMBRE de la clave; no puede ver una credencial
+    # embebida en TEXTO LIBRE. El caso canónico es el `message` de una excepción
+    # inesperada (llega como `reason=` o `error_message=`, nombres no sensibles):
+    # un `NoMethodError` sobre un objeto de respuesta HTTP puede arrastrar
+    # `Authorization: "Bearer eyJ..."` en su mensaje y el filtro por-clave lo deja
+    # pasar entero al log.
+    #
+    # El reemplazo conserva el nombre de la clave cuando viaja dentro del texto
+    # (`token=[FILTERED]`, no `[FILTERED]`): saber QUÉ credencial apareció es
+    # diagnóstico útil; su valor no.
+    SENSITIVE_VALUE_RULES = [
+      # Esquemas de autenticación HTTP: "Bearer <jwt>", "Basic <base64>".
+      [/\b(?:bearer|basic)\s+[A-Za-z0-9\-._~+\/]{8,}={0,2}/i, '[FILTERED]'],
+      # La key viaja DENTRO del texto: `token=abc`, `password: 'x'`, `"api_key" => "y"`.
+      #
+      # El prefijo `\w*` va en lugar de un `\b`: `_` es word-char, así que un borde de
+      # palabra NO existe dentro de `access_token` ni de `accessToken` y esas variantes
+      # se colarían en claro — justo las que {.sensitive_key?} cubre a propósito con
+      # substring matching. Se captura el prefijo para conservar el nombre COMPLETO de la
+      # key en el log (`access_token=[FILTERED]`): saber qué credencial apareció es
+      # diagnóstico útil. No reintroduce el falso positivo de `passport_number` porque
+      # ninguna key de SENSITIVE_KEYS es substring suyo (por eso `pass` bare está excluida).
+      [/(\w*(?:#{SENSITIVE_KEYS_ALTERNATION}))["']?\s*(?:=>|[:=])\s*["']?[^\s,;"'}\])]+/i,
+       '\1=[FILTERED]'],
+      # Credenciales en una URL: `amqp://user:pass@host` → conserva el esquema y el host.
+      [%r{(://)[^\s/:@]+:[^\s/@]+@}, '\1[FILTERED]@']
+    ].freeze
+
+    # Redacta credenciales embebidas en un valor de texto libre.
+    #
+    # Complementa a {.sensitive_key?}: esa filtra por NOMBRE de clave, esta por
+    # CONTENIDO. Se aplica a todo valor no numérico que {#safe_log} serializa.
+    #
+    # @param value [Object] El valor a redactar (se serializa con `to_s`).
+    # @return [String] El valor con las credenciales reemplazadas por `[FILTERED]`.
+    def self.redact_value(value)
+      SENSITIVE_VALUE_RULES.reduce(value.to_s) do |acc, (pattern, replacement)|
+        acc.gsub(pattern, replacement)
+      end
+    end
+
+    # Redacta una estructura ANTES de serializarla, recorriendo keys y valores.
+    #
+    # Se usa para los valores `Hash` de {#safe_log}. Redactar el JSON ya serializado con
+    # {.redact_value} no sirve: la regla de key-dentro-del-texto normaliza el separador a
+    # `=` y se come la comilla de cierre de la key, dejando un objeto donde el par
+    # `"token": "abc"` quedó colapsado en `"token=[FILTERED]"` — el secreto desaparece,
+    # pero el campo deja de ser JSON parseable y quien consume el log pierde el objeto
+    # entero, no solo el valor redactado.
+    #
+    # Recorriendo la estructura, además, las keys internas SÍ pasan por {.sensitive_key?}
+    # (que solo veía las keys de primer nivel del metadata).
+    #
+    # @param obj [Object] Estructura a redactar (Hash/Array anidados incluidos).
+    # @return [Object] La misma forma, con los valores sensibles reemplazados.
+    def self.redact_structure(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(k, v), acc|
+          acc[k] = sensitive_key?(k) ? '[FILTERED]' : redact_structure(v)
+        end
+      when Array then obj.map { |element| redact_structure(element) }
+      when Numeric, TrueClass, FalseClass, NilClass then obj
+      else redact_value(obj)
+      end
+    end
+
     private
 
     # Registra un evento estructurado. Nunca eleva excepciones.
@@ -43,12 +118,17 @@ module BugBunny
         val = BugBunny::Observability.sensitive_key?(k) ? '[FILTERED]' : v
         next if val.nil?
 
+        # La redacción por CONTENIDO se aplica a todo valor no numérico: el filtro
+        # por-clave de arriba no ve una credencial embebida en texto libre.
         formatted = case val
                     when Numeric then val
                     when Hash
-                      val.to_json
-                    when String then val.include?(' ') ? val.inspect : val
-                    else val.to_s.include?(' ') ? val.to_s.inspect : val
+                      # Se redacta la estructura y DESPUÉS se serializa: al revés el campo
+                      # queda con el secreto tapado pero el JSON roto (ver .redact_structure).
+                      BugBunny::Observability.redact_structure(val).to_json
+                    else
+                      redacted = BugBunny::Observability.redact_value(val)
+                      redacted.include?(' ') ? redacted.inspect : redacted
                     end
         "#{k}=#{formatted}"
       end.compact.join(' ')

data/lib/bug_bunny/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BugBunny
-  VERSION = '5.1.0'
+  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'