bug_bunny 4.14.0 → 4.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6081a471e20278bc190a7d7517b69cf6fe6d852293bca353974c5ba1cbe4e746
-  data.tar.gz: 2e1b952c9627b7f3f1f9ab1e2af25af49ca0422ff59f062ac7499c14265d6a57
+  metadata.gz: 67e58763b6f088c44e17121922ecb618c9ccef8738096d534c578eea021c5f94
+  data.tar.gz: 47fe7485dd056e9ffb8a7e5268b97e4d0173e0441984506b5528f5c43643da7a
 SHA512:
-  metadata.gz: 6cf7de01b98c925c8f02de1e09aafc0113f24f93145498ace1616445deecf6319bde3464d9afcd89b5b461904fbe878d4bfb24ea3a2a310149a32f6f2b06f4d0
-  data.tar.gz: 2560004c6036b238456fe9c9af9bf478dde67b1ff07240fdac942ecab303467d1db04f3029c2579463e5017b7c9f25ad2e5f1c5ef2c999f86bcde0bedb42eb67
+  metadata.gz: f0a5927c4a4a450b414ee38ffbc25a0a97a80b2678d32a19d524a51367572f7b5e2935e29a81bf9afbdd2cfb0b634e9b60a322b828ff14ba0f79e60982148723
+  data.tar.gz: e66726447226ceb96f2d3b81dd759209fd8e54e7ea67bb85870cc805e44747e81f8121a821fd7a6fa65435ae3ba95e3cd62631ef0687fa0543f29848e21f4682

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [4.16.0] - 2026-05-13
+
+### Cambios de comportamiento (semi-breaking)
+- **`DEFAULT_QUEUE_OPTIONS` cambió a `{ exclusive: false, durable: true, auto_delete: false }`** (#42). En versiones previas el default era `{ exclusive: false, durable: false, auto_delete: true }` — la combinación `transient_nonexcl_queues` que **RabbitMQ 4.x deprecó por default**: el broker rechaza la declaración matando la conexión. El nuevo default es el patrón "queue compartida duradera": sobrevive restart del broker, múltiples consumers pueden compartirla, no se elimina cuando se desconecta el último consumer. Esto matchea cómo la mayoría de servicios Wispro ya configuran sus queues explícitamente.
+
+  **Para restaurar el comportamiento anterior** (servicios sobre RabbitMQ 3.x con queues legacy efímeras pre-existentes):
+
+  ```ruby
+  BugBunny.configure do |c|
+    c.queue_options = { exclusive: false, durable: false, auto_delete: true }
+  end
+  ```
+
+  **Síntoma si se necesita override y no se aplicó:** `Bunny::PreconditionFailed - inequivalent arg 'durable' for queue 'foo'`. Indica que la queue existe en el broker con `durable: false` pero el nuevo default intenta declararla con `durable: true`. Aplicar el override de arriba o borrar manualmente la queue legacy en el broker.
+
+### Documentación
+- README + SKILL.md actualizados con sección "queue_options recomendadas" cubriendo patrones worker-pool (default nuevo) y single-instance (`exclusive: true`).
+
+## [4.15.0] - 2026-05-13
+
+### Nuevas funcionalidades
+- **`return_raise` flag para mandatory + basic.return (#38):** `Producer#confirmed` ahora levanta `BugBunny::PublishUnroutable` cuando el broker retorna un mensaje publicado con `mandatory: true` que no pudo rutearse a ninguna cola. Espejo simétrico de `nack_raise`/`PublishNacked`. La excepción expone `path`, `exchange`, `routing_key`, `reply_code`, `reply_text` y `correlation_id`. Internamente la gema implementa el bridge cross-thread (reader thread → publish thread) que antes cada caller tenía que replicar manualmente con `Concurrent::Map` + lambda. Configurable globalmente vía `BugBunny.configuration.return_raise` (default `true`) y por request via `client.publish(..., return_raise: false)`. El callback global `on_return` se sigue invocando antes del raise. — @Gabriel
+
+### Cambios de comportamiento (semi-breaking)
+- **Default `return_raise: true`:** Publicaciones con `confirmed: true, mandatory: true` que reciben `basic.return` del broker ahora levantan excepción por default. En 4.14.0 el return solo se logueaba (o invocaba el callback `on_return`) y la llamada retornaba 202 silenciosamente — ocultando pérdida de mensajes. Para mantener el comportamiento previo: `BugBunny.configuration.return_raise = false` o `return_raise: false` per request. El flag es **inerte cuando `mandatory: false`** — sin mandatory el broker nunca emite return.
+
+### Detalles internos
+- `Producer#confirmed` auto-asigna `correlation_id` (UUID) cuando falta y `mandatory + return_raise` están activos — la correlación bridge↔return depende del cid.
+- Nuevo bound de espera `Producer::RETURN_RACE_WINDOW_S = 0.05` tras un ack positivo: tolera el race scheduling entre reader thread (donde Bunny invoca `on_return`) y publish thread (donde se devuelve `wait_for_confirms`). AMQP garantiza orden wire (return precede a ack), pero defendemos contra GVL.
+- `Session` ahora mantiene un registry interno `@pending_returns` (`Concurrent::Map` de cid → `{event, info}`). `handle_broker_return` setea el event *antes* de invocar el user_cb global — una excepción del callback no impide el raise en el caller.
+- Nuevo evento de log `producer.publish_unroutable` (WARN) con `path`, `exchange`, `routing_key`, `reply_code`, `reply_text`, `messaging_message_id`. Se emite antes de levantar `PublishUnroutable`.
+- Nuevo evento de log `client.return_raise_ignored` (WARN) cuando se pasa `return_raise: true` sin `confirmed: true` o sin `mandatory: true` — el flag se ignora.
+
 ## [4.14.0] - 2026-05-12
 
 ### Nuevas funcionalidades

data/README.md

@@ -129,7 +129,11 @@ BugBunny.configure do |config|
   config.read_timeout        = 10
   config.write_timeout       = 10
 
-  # AMQP defaults applied to all exchanges and queues
+  # AMQP defaults applied to all exchanges and queues.
+  # Gem defaults (since 4.16):
+  #   DEFAULT_EXCHANGE_OPTIONS = { durable: false, auto_delete: false }
+  #   DEFAULT_QUEUE_OPTIONS    = { exclusive: false, durable: true, auto_delete: false }
+  # Override only if your service needs different infrastructure semantics.
   config.exchange_options = { durable: true }
   config.queue_options    = { durable: true }
 
@@ -142,7 +146,13 @@ BugBunny.configure do |config|
   # Health check file for Kubernetes / Docker Swarm liveness probes
   config.health_check_file = '/tmp/bug_bunny_health'
 
+  # 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
+  config.return_raise = true   # broker basic.return (mandatory) → raise BugBunny::PublishUnroutable
+
   # Callback invoked when the broker returns an unroutable mandatory message.
+  # Runs BEFORE PublishUnroutable is raised (if return_raise is true).
   # When nil (default), BugBunny logs the return as `session.broker_return` at :warn.
   # Signature: ->(return_info, properties, body) { ... }
   config.on_return = ->(return_info, _props, body) {
@@ -220,11 +230,26 @@ client.publish('acct.start',
 | `confirmed` | Boolean | `false` | Block until `wait_for_confirms` returns. |
 | `mandatory` | Boolean | `false` | Broker returns the message if it cannot be routed to any queue. Requires `confirmed: true` to be useful. |
 | `confirm_timeout` | Float | `nil` | Seconds to wait for the broker ACK. Raises `BugBunny::RequestTimeout` if exceeded. |
-| `nack_raise` | Boolean | `nil` | Per-request override of `config.nack_raise`. When `nil`, falls back to the global flag. |
+| `nack_raise` | Boolean | `nil` | Per-request override of `config.nack_raise`. When `nil`, falls back to the global flag (default `true`). |
+| `return_raise` | Boolean | `nil` | Per-request override of `config.return_raise`. When `nil`, falls back to the global flag (default `true`). Requires `confirmed: true` and `mandatory: true` to take effect. |
+
+**Two broker signals, two exceptions:**
+
+| Broker signal | Default behavior | Exception class | Fields |
+|---|---|---|---|
+| `basic.nack` (explicit rejection) | Raises | `BugBunny::PublishNacked` | `path`, `nacked_count` |
+| `basic.return` (unroutable + `mandatory: true`) | Raises | `BugBunny::PublishUnroutable` | `path`, `exchange`, `routing_key`, `reply_code`, `reply_text`, `correlation_id` |
 
-If the broker NACKs the publish (explicit rejection — disk full, internal confirm policy, etc.), the call raises `BugBunny::PublishNacked` by default. The exception exposes `path` and `nacked_count`. Critical publishers (audit, billing, RADIUS accounting) can let it bubble up to translate into HTTP 5xx so upstream systems retry. To restore the legacy "log-only" behaviour, set `BugBunny.configuration.nack_raise = false` globally or pass `nack_raise: false` per request.
+Both exceptions translate naturally into HTTP 5xx in critical publishers (audit, billing, RADIUS accounting) so upstream systems retry. The `config.on_return` callback (if defined) still runs before `PublishUnroutable` is raised — useful for alerting/metrics. To restore the legacy "log-only" behaviour:
+
+```ruby
+BugBunny.configure do |c|
+  c.nack_raise   = false  # or pass `nack_raise: false` per request
+  c.return_raise = false  # or pass `return_raise: false` per request
+end
+```
 
-Unroutable returned messages are handled by a single global callback (see `config.on_return` below). The default handler logs them as `session.broker_return` at `warn` level — nothing is dropped silently.
+When `mandatory: false` (the default), `return_raise` is inert — the broker never emits `basic.return` without mandatory.
 
 ---
 
@@ -285,9 +310,15 @@ BugBunny maps RabbitMQ responses to a semantic exception hierarchy, similar to h
 
 ```
 BugBunny::Error
+├── CommunicationError                  (network / channel failure)
+├── ConfigurationError                  (invalid config attribute)
+├── SecurityError                       (unauthorized controller resolution)
+├── PublishNacked                       (broker basic.nack on :confirmed publish)
+├── PublishUnroutable                   (broker basic.return on mandatory + :confirmed)
 ├── ClientError (4xx)
 │   ├── BadRequest (400)
 │   ├── NotFound (404)
+│   │   └── RoutingError                (consumer-side: no route for verb + path)
 │   ├── NotAcceptable (406)
 │   ├── RequestTimeout (408)
 │   ├── Conflict (409)

data/lib/bug_bunny/client.rb

@@ -95,10 +95,16 @@ module BugBunny
     # @option args [Float] :confirm_timeout Segundos a esperar el confirm. `nil` espera indefinidamente.
     # @option args [Boolean] :nack_raise Override per-request del flag
     #   `BugBunny.configuration.nack_raise`. Si `nil` (default), se usa la configuración global.
+    # @option args [Boolean] :return_raise Override per-request del flag
+    #   `BugBunny.configuration.return_raise`. Si `nil` (default), se usa la configuración global.
+    #   Requiere `mandatory: true` y `confirmed: true` para tener efecto — sino se emite un
+    #   warning y el flag se ignora.
     # @yield [req] Bloque para configurar el objeto Request.
     # @return [Hash] `{ 'status' => 202, 'body' => nil }`.
     # @raise [BugBunny::RequestTimeout] Si `confirmed: true` y el broker no confirma a tiempo.
     # @raise [BugBunny::PublishNacked] Si `confirmed: true`, el broker NACKea, y `nack_raise` resuelto es true.
+    # @raise [BugBunny::PublishUnroutable] Si `confirmed: true`, `mandatory: true`, el broker retorna el
+    #   mensaje como no-ruteable, y `return_raise` resuelto es true.
     def publish(url, **args)
       send(url, **args) do |req|
         req.delivery_mode = args[:confirmed] ? :confirmed : :publish
@@ -120,6 +126,10 @@ module BugBunny
       # Configuración del usuario (bloque específico por request)
       yield req if block_given?
 
+      # Check post-block: el block API puede setear delivery_mode/mandatory después
+      # de los keyword args. Evaluamos el warning sobre el estado final del Request.
+      warn_return_raise_misuse(req)
+
       # Ejecución dentro del Pool.
       # Session y Producer se reutilizan por slot de conexión (ver #session_for / #producer_for).
       @pool.with do |conn|
@@ -179,6 +189,33 @@ module BugBunny
       req.mandatory       = args[:mandatory]       if args.key?(:mandatory)
       req.confirm_timeout = args[:confirm_timeout] if args.key?(:confirm_timeout)
       req.nack_raise      = args[:nack_raise]      if args.key?(:nack_raise)
+      req.return_raise    = args[:return_raise]    if args.key?(:return_raise)
+    end
+
+    # Emite un warning si el Request final tiene `return_raise: true` pero le falta
+    # `delivery_mode == :confirmed` o `mandatory: true`. El flag requiere ambos para
+    # tener efecto: sin confirmed no hay synchronization point sobre el cual levantar,
+    # y sin mandatory el broker nunca retorna.
+    #
+    # Se evalúa sobre el Request post-block (no sobre args) para no producir falsos
+    # positivos cuando el caller usa el block API para setear `req.delivery_mode` o
+    # `req.mandatory` después de los keyword args.
+    #
+    # Solo warnea cuando `request.return_raise` fue explícitamente `true` por request —
+    # ignora el default global (que también puede ser `true`) para no inundar logs en
+    # publishes regulares sin mandatory.
+    #
+    # @param request [BugBunny::Request]
+    # @return [void]
+    def warn_return_raise_misuse(request)
+      return unless request.return_raise == true
+      return if request.delivery_mode == :confirmed && request.mandatory
+
+      BugBunny.configuration.logger&.warn do
+        'component=bug_bunny event=client.return_raise_ignored ' \
+          'reason=requires_confirmed_and_mandatory ' \
+          "delivery_mode=#{request.delivery_mode} mandatory=#{!!request.mandatory}"
+      end
     end
 
     # Recupera o crea la Session asociada al slot de conexión dado.

data/lib/bug_bunny/configuration.rb

@@ -162,6 +162,19 @@ module BugBunny
     #   `Client#publish`.
     attr_accessor :nack_raise
 
+    # @return [Boolean] Si `true` (default), {BugBunny::Producer#confirmed} levanta
+    #   {BugBunny::PublishUnroutable} cuando el broker retorna un mensaje publicado
+    #   con `mandatory: true` que no pudo rutearse. Si `false`, el return solo se
+    #   procesa via {#on_return} callback (modo legacy) y la llamada retorna
+    #   `{ 'status' => 202 }`.
+    #
+    #   El flag es inerte cuando `mandatory: false` (sin mandatory, el broker nunca
+    #   retorna). El callback {#on_return} se sigue invocando antes del raise.
+    #
+    #   El valor puede sobreescribirse por request pasando `return_raise:` en
+    #   `Client#publish`.
+    attr_accessor :return_raise
+
     # @!endgroup
 
     # Inicializa la configuración con valores por defecto seguros.
@@ -239,6 +252,7 @@ module BugBunny
       @on_rpc_reply = nil
       @on_return = nil
       @nack_raise = true
+      @return_raise = true
     end
 
     def validate_required!(attr, value, rules)

data/lib/bug_bunny/exception.rb

@@ -50,6 +50,67 @@ module BugBunny
     end
   end
 
+  # Error lanzado cuando el broker retorna un mensaje publicado con `mandatory: true`
+  # que no pudo rutearse a ninguna cola en modo `:confirmed`.
+  #
+  # Un return implica que el publish llegó al broker pero ninguna binding aceptó la
+  # routing key — el mensaje se considera no entregado desde la perspectiva del
+  # publisher. Espejo simétrico de {PublishNacked} pero para la señal `basic.return`
+  # en lugar de `basic.nack`.
+  #
+  # Se levanta por default desde {BugBunny::Producer#confirmed} cuando el request
+  # tiene `mandatory: true`. Para opt-out, configurar
+  # `BugBunny.configuration.return_raise = false` o pasar `return_raise: false`
+  # por request. El callback `BugBunny.configuration.on_return` se sigue invocando
+  # antes del raise (orden: registro interno → user_cb → raise en el caller).
+  #
+  # @example
+  #   rescue BugBunny::PublishUnroutable => e
+  #     e.path           # => 'acct.start'
+  #     e.exchange       # => 'acct_x'
+  #     e.routing_key    # => 'acct.unbound'
+  #     e.reply_code     # => 312
+  #     e.reply_text     # => 'NO_ROUTE'
+  #     e.correlation_id # => 'corr-uuid-...'
+  class PublishUnroutable < Error
+    # @return [String] Ruta lógica del request cuyo publish fue retornado.
+    attr_reader :path
+
+    # @return [String] Nombre del exchange destino.
+    attr_reader :exchange
+
+    # @return [String] Routing key utilizada en el publish.
+    attr_reader :routing_key
+
+    # @return [Integer, nil] Código AMQP de la razón (ej: 312 = NO_ROUTE).
+    attr_reader :reply_code
+
+    # @return [String, nil] Texto humano-legible que describe la razón.
+    attr_reader :reply_text
+
+    # @return [String, nil] Correlation ID del request retornado.
+    attr_reader :correlation_id
+
+    # @param path [String] Ruta lógica del request (ej: 'acct.start').
+    # @param exchange [String] Nombre del exchange destino.
+    # @param routing_key [String] Routing key del publish.
+    # @param reply_code [Integer, nil] Código AMQP del return.
+    # @param reply_text [String, nil] Texto del return.
+    # @param correlation_id [String, nil] Correlation ID del mensaje retornado.
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(path:, exchange:, routing_key:, reply_code: nil, reply_text: nil, correlation_id: nil)
+      @path = path
+      @exchange = exchange
+      @routing_key = routing_key
+      @reply_code = reply_code
+      @reply_text = reply_text
+      @correlation_id = correlation_id
+      super("broker returned unroutable message on path=#{path} exchange=#{exchange} " \
+            "routing_key=#{routing_key} reply_code=#{reply_code} reply_text=#{reply_text}")
+    end
+    # rubocop:enable Metrics/ParameterLists
+  end
+
   # ==========================================
   # Categoría: Errores del Cliente (4xx)
   # ==========================================

data/lib/bug_bunny/producer.rb

@@ -15,6 +15,13 @@ module BugBunny
   class Producer
     include BugBunny::Observability
 
+    # Bound de espera (segundos) que el publish thread aplica tras un ack positivo para
+    # tolerar el scheduling race entre reader thread (donde Bunny invoca `on_return`) y
+    # publish thread (donde se devuelve `wait_for_confirms`). AMQP garantiza que el
+    # `basic.return` precede al `basic.ack` en la wire, así que en la práctica el event
+    # ya está seteado al llegar acá; este wait es defensa contra GVL.
+    RETURN_RACE_WINDOW_S = 0.05
+
     # Inicializa el productor.
     #
     # Prepara las estructuras de concurrencia necesarias para manejar múltiples
@@ -58,8 +65,13 @@ module BugBunny
     # @raise [BugBunny::RequestTimeout] Si el broker no confirma dentro de `confirm_timeout` segundos.
     # @raise [BugBunny::PublishNacked] Si el broker NACKea la publicación y `nack_raise` está activo
     #   (default `true` — ver {BugBunny::Configuration#nack_raise}).
+    # @raise [BugBunny::PublishUnroutable] Si `mandatory: true` y el broker retorna el mensaje como
+    #   no-ruteable, con `return_raise` activo (default `true` — ver
+    #   {BugBunny::Configuration#return_raise}).
     # @raise [BugBunny::CommunicationError] Si el canal AMQP falla durante la publicación o confirm.
     def confirmed(request)
+      return_listener = nil
+      return_listener = setup_return_listener(request)
       started_at = monotonic_now
       publish_duration = publish_message(request)
 
@@ -68,6 +80,7 @@ module BugBunny
       confirm_duration = duration_s(confirm_started_at)
 
       handle_confirm_result(request, acked)
+      handle_return_result(request, return_listener)
       log_confirmed(request, publish_duration, confirm_duration, started_at)
 
       { 'status' => 202, 'body' => nil }
@@ -75,6 +88,8 @@ module BugBunny
       raise
     rescue StandardError => e
       raise BugBunny::CommunicationError, "Publisher confirms failed: #{e.message}"
+    ensure
+      teardown_return_listener(request, return_listener)
     end
 
     # Envía un mensaje y bloquea el hilo actual esperando una respuesta (RPC).
@@ -240,6 +255,95 @@ module BugBunny
       BugBunny.configuration.nack_raise
     end
 
+    # Resuelve el flag `return_raise` con prioridad request > configuración global.
+    # El flag solo tiene efecto cuando `mandatory: true` — sin mandatory el broker
+    # nunca emite `basic.return`.
+    #
+    # @param request [BugBunny::Request]
+    # @return [Boolean]
+    def return_raise?(request)
+      return false unless request.mandatory
+
+      return request.return_raise unless request.return_raise.nil?
+
+      BugBunny.configuration.return_raise
+    end
+
+    # Registra un listener de `basic.return` en la Session asociada al `correlation_id`
+    # del request. Si return_raise? es false (mandatory off o flag desactivado), retorna
+    # `nil` y el resto del flow ignora la lógica de unroutable.
+    #
+    # Auto-asigna `correlation_id` si falta — sin cid no hay clave de correlación.
+    #
+    # @param request [BugBunny::Request]
+    # @return [Hash, nil] Hash con `:cid` y `:slot` (el slot expone `:event` y `:info`),
+    #   o `nil` si no aplica.
+    def setup_return_listener(request)
+      return nil unless return_raise?(request)
+
+      request.correlation_id ||= SecureRandom.uuid
+      cid = request.correlation_id.to_s
+      _event, slot = @session.register_return_listener(cid)
+      { cid: cid, slot: slot }
+    end
+
+    # Tras un ack positivo, espera brevemente al event del listener para tolerar el
+    # scheduling race entre reader thread (donde corre `on_return`) y publish thread.
+    # En AMQP el `basic.return` precede al `basic.ack`, así que normalmente el event
+    # ya está seteado al llegar acá; el bounded wait defiende contra GVL/scheduling.
+    #
+    # @param request [BugBunny::Request]
+    # @param return_listener [Hash, nil] Resultado de {#setup_return_listener}.
+    # @return [void]
+    # @raise [BugBunny::PublishUnroutable] Si el listener recibió un return.
+    def handle_return_result(request, return_listener)
+      return unless return_listener
+
+      slot = return_listener[:slot]
+      slot[:event].wait(RETURN_RACE_WINDOW_S)
+      info = slot[:info]
+      return if info.nil?
+
+      raise_unroutable!(request, return_listener[:cid], info)
+    end
+
+    # Logea y levanta {BugBunny::PublishUnroutable} con los datos del return.
+    #
+    # @param request [BugBunny::Request]
+    # @param cid [String]
+    # @param info [Bunny::ReturnInfo, #exchange, #routing_key, #reply_code, #reply_text]
+    # @raise [BugBunny::PublishUnroutable]
+    def raise_unroutable!(request, cid, info)
+      safe_log(:warn, 'producer.publish_unroutable',
+               path: request.path,
+               exchange: info.exchange,
+               routing_key: info.routing_key,
+               reply_code: info.reply_code,
+               reply_text: info.reply_text,
+               messaging_message_id: cid)
+
+      raise BugBunny::PublishUnroutable.new(
+        path: request.path,
+        exchange: info.exchange,
+        routing_key: info.routing_key,
+        reply_code: info.reply_code,
+        reply_text: info.reply_text,
+        correlation_id: cid
+      )
+    end
+
+    # Cleanup del listener en la Session. Siempre se llama desde el `ensure` de
+    # {#confirmed}, sea cual sea el outcome (ack, nack, timeout, return).
+    #
+    # @param request [BugBunny::Request]
+    # @param return_listener [Hash, nil]
+    # @return [void]
+    def teardown_return_listener(_request, return_listener)
+      return unless return_listener
+
+      @session.unregister_return_listener(return_listener[:cid])
+    end
+
     # Registra la petición en el log calculando las opciones de infraestructura.
     #
     # @param request [BugBunny::Request] Objeto Request que se está enviando.

data/lib/bug_bunny/request.rb

@@ -29,6 +29,9 @@ module BugBunny
   #   `nil` espera indefinidamente.
   # @attr nack_raise [Boolean, nil] Override per-request del flag global
   #   `BugBunny.configuration.nack_raise`. `nil` (default) delega a la configuración global.
+  # @attr return_raise [Boolean, nil] Override per-request del flag global
+  #   `BugBunny.configuration.return_raise`. `nil` (default) delega a la configuración global.
+  #   Requiere `mandatory: true` y `delivery_mode = :confirmed` para tener efecto.
   class Request
     attr_accessor :body, :headers, :params, :path, :method, :exchange, :exchange_type, :routing_key, :timeout,
                   :delivery_mode, :queue_options
@@ -37,7 +40,7 @@ module BugBunny
     attr_accessor :exchange_options
 
     # Publisher Confirms (delivery_mode = :confirmed)
-    attr_accessor :mandatory, :confirm_timeout, :nack_raise
+    attr_accessor :mandatory, :confirm_timeout, :nack_raise, :return_raise
 
     # Metadatos AMQP Estándar
     attr_accessor :app_id, :content_type, :content_encoding, :priority,
@@ -66,6 +69,7 @@ module BugBunny
       @mandatory = false
       @confirm_timeout = nil
       @nack_raise = nil
+      @return_raise = nil
     end
 
     # Combina el path con los params como query string.

data/lib/bug_bunny/session.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'concurrent'
+
 module BugBunny
   # Clase interna que encapsula una unidad de trabajo sobre una conexión RabbitMQ.
   #
@@ -16,7 +18,20 @@ module BugBunny
     DEFAULT_EXCHANGE_OPTIONS = { durable: false, auto_delete: false }.freeze
 
     # Opciones predeterminadas de la gema para Colas.
-    DEFAULT_QUEUE_OPTIONS = { exclusive: false, durable: false, auto_delete: true }.freeze
+    #
+    # `durable: true, exclusive: false, auto_delete: false` es el patrón "queue compartida
+    # duradera" — sobrevive restart del broker, múltiples consumers (worker pool) pueden
+    # consumir, no se elimina cuando el último consumer se desconecta.
+    #
+    # Histórico: hasta 4.15.x el default era `{ exclusive: false, durable: false,
+    # auto_delete: true }` (combo `transient_nonexcl_queues` deprecada en RabbitMQ 4.x).
+    # Ver issue #42 para detalles de la migración. Para restaurar el comportamiento
+    # anterior, configurar explícitamente:
+    #
+    #   BugBunny.configure do |c|
+    #     c.queue_options = { exclusive: false, durable: false, auto_delete: true }
+    #   end
+    DEFAULT_QUEUE_OPTIONS = { exclusive: false, durable: true, auto_delete: false }.freeze
 
     # @!endgroup
 
@@ -36,6 +51,35 @@ module BugBunny
       @channel_mutex = Mutex.new
       @logger = BugBunny.configuration.logger
       @configured_returns = {}
+      @pending_returns = Concurrent::Map.new
+    end
+
+    # Registra interés en una eventual señal `basic.return` correlacionada con `cid`.
+    #
+    # Devuelve un par `(event, slot)`. El caller espera el `event` tras `wait_for_confirms`;
+    # si el broker retorna el mensaje, {#handle_broker_return} setea el event y deposita
+    # la `return_info` en `slot[:info]` antes de invocar el callback global del usuario.
+    #
+    # El caller es responsable de invocar {#unregister_return_listener} en un `ensure`
+    # para evitar fugas en el registry interno.
+    #
+    # @param cid [String] Correlation ID del request en curso.
+    # @return [Array(Concurrent::Event, Hash)] Tupla `[event, slot]`. `slot[:info]` será
+    #   poblado con la `Bunny::ReturnInfo` si el broker retorna el mensaje.
+    # @api private
+    def register_return_listener(cid)
+      slot = { event: Concurrent::Event.new, info: nil }
+      @pending_returns[cid.to_s] = slot
+      [slot[:event], slot]
+    end
+
+    # Elimina el listener registrado por {#register_return_listener}.
+    #
+    # @param cid [String]
+    # @return [void]
+    # @api private
+    def unregister_return_listener(cid)
+      @pending_returns.delete(cid.to_s)
     end
 
     # Obtiene el canal actual o crea uno nuevo si es necesario.
@@ -112,6 +156,7 @@ module BugBunny
         @channel&.close if @channel&.open?
         @channel = nil
         @configured_returns.clear
+        release_pending_returns!
       end
     end
 
@@ -132,6 +177,19 @@ module BugBunny
       raise BugBunny::CommunicationError, "Failed to create channel: #{e.message}"
     end
 
+    # Libera todos los listeners pendientes seteando sus events. Permite que los publish
+    # threads bloqueados en `event.wait` despierten cuando la sesión se cierra (shutdown),
+    # en lugar de esperar a `confirm_timeout`. Solo se invoca desde {#close} — el cleanup
+    # per-publish corre via `ensure` en {Producer#confirmed} → {#unregister_return_listener}.
+    #
+    # @return [void]
+    def release_pending_returns!
+      @pending_returns.each_pair do |_cid, slot|
+        slot[:event].set
+      end
+      @pending_returns.clear
+    end
+
     # Registra el handler `basic.return` sobre el `Bunny::Exchange` indicado.
     #
     # Bunny dispatcha `basic.return` por exchange (no por canal): el callback se setea
@@ -156,11 +214,50 @@ module BugBunny
     # Procesa un evento `basic.return` del broker. Nunca propaga excepciones del callback
     # de usuario para no romper el hilo de I/O de Bunny.
     #
+    # Orden de operaciones:
+    # 1. Si hay un listener registrado con el `correlation_id` del mensaje retornado,
+    #    se deposita la `return_info` en su slot y se setea el event. Esto se hace
+    #    *antes* del callback de usuario para que una excepción del user_cb no impida
+    #    que el publish thread despierte y raisee `PublishUnroutable`.
+    # 2. Se invoca el callback global `configuration.on_return` (o se logea si no hay).
+    #
     # @param return_info [Bunny::ReturnInfo]
     # @param properties [Bunny::MessageProperties]
     # @param body [String]
     # @return [void]
     def handle_broker_return(return_info, properties, body)
+      signal_return_listener(properties, return_info)
+      dispatch_return_callback(return_info, properties, body)
+    rescue StandardError => e
+      safe_log(:error, 'session.on_return_failed', **exception_metadata(e))
+    end
+
+    # Deposita la info del return en el slot asociado al `correlation_id` del mensaje
+    # retornado y setea el event para despertar al publish thread.
+    #
+    # @param properties [Bunny::MessageProperties]
+    # @param return_info [Bunny::ReturnInfo]
+    # @return [void]
+    def signal_return_listener(properties, return_info)
+      cid = properties.respond_to?(:correlation_id) ? properties.correlation_id : nil
+      return if cid.nil?
+
+      slot = @pending_returns[cid.to_s]
+      return unless slot
+
+      slot[:info] = return_info
+      slot[:event].set
+    end
+
+    # Invoca el callback global `on_return` o logea el evento si no hay callback.
+    # Las excepciones del user_cb se capturan en el rescue de {#handle_broker_return}
+    # — el event interno ya fue seteado antes de llegar acá.
+    #
+    # @param return_info [Bunny::ReturnInfo]
+    # @param properties [Bunny::MessageProperties]
+    # @param body [String]
+    # @return [void]
+    def dispatch_return_callback(return_info, properties, body)
       user_cb = BugBunny.configuration.on_return
       if user_cb
         user_cb.call(return_info, properties, body)
@@ -172,8 +269,6 @@ module BugBunny
                  routing_key: return_info.routing_key,
                  body_size: body.respond_to?(:bytesize) ? body.bytesize : nil)
       end
-    rescue StandardError => e
-      safe_log(:error, 'session.on_return_failed', **exception_metadata(e))
     end
 
     # Garantiza que la conexión TCP esté abierta.

data/lib/bug_bunny/version.rb

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