bug_bunny 4.14.0 → 4.16.0

data/skill/SKILL.md

@@ -15,7 +15,9 @@ Skill de conocimiento completo sobre BugBunny. Consultame para cualquier pregunt
 **Session** — `BugBunny::Session` envuelve canales de Bunny con thread-safety y double-checked locking.
 **RPC** — Patrón síncrono que usa la pseudo-cola `amq.rabbitmq.reply-to` para respuestas sin crear queues temporales.
 **Fire-and-Forget** — Patrón asíncrono donde el producer publica y continúa sin esperar respuesta. Retorna `{ 'status' => 202 }`.
-**Publisher Confirms** — Extensión de RabbitMQ que confirma al publisher que el broker recibió el mensaje. BugBunny lo expone como `confirmed: true` en `Client#publish`: el publish bloquea hasta `wait_for_confirms`. NACK del broker (rechazo explícito) levanta `BugBunny::PublishNacked` por default; configurable via `config.nack_raise = false` o `nack_raise: false` per request para volver al modo log-only.
+**Publisher Confirms** — Extensión de RabbitMQ que confirma al publisher que el broker recibió el mensaje. BugBunny lo expone como `confirmed: true` en `Client#publish`: el publish bloquea hasta `wait_for_confirms`. Dos señales asíncronas del broker, ambas convertidas en excepciones raise-eables en el publish thread:
+- **NACK** (rechazo explícito) → `BugBunny::PublishNacked` (configurable via `config.nack_raise = false`).
+- **basic.return** (mandatory unroutable) → `BugBunny::PublishUnroutable` (configurable via `config.return_raise = false`).
 **Mandatory** — Flag de `basic.publish` que pide al broker retornar el mensaje al publisher si no es ruteable a ninguna cola. Se procesa via `basic.return` (no es respuesta del request).
 **basic.return** — Evento asincrónico que Bunny dispatcha por exchange (`Bunny::Exchange#on_return`). BugBunny registra un handler único por nombre de exchange al resolverlo en `Session#exchange` y lo delega a `Configuration#on_return` o al default que logea.
 **Resource** — ORM tipo ActiveRecord que mapea operaciones CRUD a llamadas AMQP.
@@ -109,6 +111,8 @@ BugBunny mide y emite duraciones automáticamente. **No envolver llamadas a `cli
 | `producer.published` | INFO | `Producer#publish_message` (post) | `method`, `path`, `routing_key`, `messaging_message_id`, **`duration_s`** (publish solo) |
 | `producer.confirmed` | INFO | `Producer#confirmed` (post-ACK) | `method`, `path`, `routing_key`, **`publish_duration_s`**, **`confirm_duration_s`**, **`duration_s`** (total) |
 | `producer.confirms_nacked` | WARN | `Producer#confirmed` (NACK) | `count`, `path` |
+| `producer.publish_unroutable` | WARN | `Producer#confirmed` (basic.return) | `path`, `exchange`, `routing_key`, `reply_code`, `reply_text`, `messaging_message_id` |
+| `client.return_raise_ignored` | WARN | `Client#publish` | `delivery_mode`, `mandatory` (cuando `return_raise:true` se pasa sin prereqs) |
 | `producer.rpc_waiting` | DEBUG | `Producer#rpc` | `messaging_message_id`, `timeout_s` |
 | `producer.rpc_response_received` | INFO | `Producer#rpc` (reply recibido) | `method`, `path`, **`duration_s`** (round-trip total), `response_body` |
 | `producer.rpc_response_orphaned` | WARN | reply listener | `correlation_id` |
@@ -160,8 +164,14 @@ BugBunny.configure do |config|
   config.rpc_reply_headers = -> { { 'X-Trace-Id' => Tracer.id } }
   config.on_rpc_reply = ->(h) { Tracer.hydrate(h['X-Trace-Id']) }
 
-  # Publisher Confirms — handler global para basic.return (mensajes mandatory no ruteados).
-  # Si es nil, BugBunny logea como `session.broker_return` con nivel :warn.
+  # Publisher Confirms — fail-loud por default (ambos true).
+  # Setear false para volver al comportamiento legacy "log y retorna 202".
+  config.nack_raise   = true   # NACK → raise BugBunny::PublishNacked
+  config.return_raise = true   # basic.return (mandatory) → raise BugBunny::PublishUnroutable
+
+  # Callback global para basic.return. Corre ANTES del raise PublishUnroutable
+  # cuando return_raise es true. Si on_return es nil, BugBunny logea
+  # `session.broker_return` con nivel :warn.
   # Firma: ->(return_info, properties, body)
   config.on_return = ->(ri, _props, body) { MyAlerts.unroutable(rk: ri.routing_key, body: body) }
 
@@ -233,12 +243,33 @@ client.publish('events', method: :post, body: { type: 'order.placed' })
 client.publish('acct.start', exchange: 'acct_x', body: payload,
                confirmed: true, mandatory: true, confirm_timeout: 0.5)
 # → { 'status' => 202, 'body' => nil }   # broker ACK confirmado
-# Si broker NACK: logea `producer.confirms_nacked` y raise BugBunny::PublishNacked
-#   (default — opt-out con config.nack_raise = false o nack_raise: false per request).
-# Si timeout: raise BugBunny::RequestTimeout.
-# Si mandatory + no ruteable: dispara `Configuration#on_return` (default: logea `session.broker_return`).
 ```
 
+**Dos señales del broker, dos excepciones simétricas:**
+
+| Señal | Default | Excepción | Campos |
+|---|---|---|---|
+| `basic.nack` | raise | `BugBunny::PublishNacked` | `path`, `nacked_count` |
+| `basic.return` (mandatory unrouted) | raise | `BugBunny::PublishUnroutable` | `path`, `exchange`, `routing_key`, `reply_code`, `reply_text`, `correlation_id` |
+
+```ruby
+# Comportamiento default (4.13+ para nack_raise, 4.15+ para return_raise):
+#   broker NACK → PublishNacked
+#   mandatory + unroutable → on_return callback (si está) → PublishUnroutable
+#   timeout en wait_for_confirms → RequestTimeout
+#
+# Opt-out (modo "log + 202 silencioso"):
+config.nack_raise   = false  # o per-request: nack_raise: false
+config.return_raise = false  # o per-request: return_raise: false
+
+# Override per-request gana sobre config global:
+client.publish('foo', confirmed: true, mandatory: true, return_raise: false, body: {})
+```
+
+**Bridge cross-thread interno (basic.return):** `basic.return` viaja en el reader thread de Bunny (asíncrono). Para hacer `PublishUnroutable` raise-able en el publish thread, BugBunny mantiene un `Session#@pending_returns = Concurrent::Map` correlacionado por `correlation_id`. `Producer#confirmed` auto-asigna `correlation_id` (UUID v4) si falta, registra un `Concurrent::Event` antes del publish, y tras `wait_for_confirms` true espera `RETURN_RACE_WINDOW_S` (50ms) para tolerar GVL scheduling — AMQP garantiza orden wire `return → ack`. El `on_return` user callback se invoca igual antes del raise (orden: signal event → user_cb → raise), así una excepción en el callback no impide el raise.
+
+**Inert cases:** `return_raise: true` sin `mandatory: true` o sin `confirmed: true` emite `client.return_raise_ignored` (WARN) y se ignora — el flag requiere ambos prereqs.
+
 `Bunny::Channel#wait_for_confirms` no soporta timeout nativo en Bunny 2.x. BugBunny lo implementa lanzando la espera en un hilo auxiliar y usando `Concurrent::IVar#value(timeout)` como reloj.
 
 ---
@@ -257,6 +288,10 @@ Cada slot del pool cachea su `Session` y `Producer` durante su vida útil. Esto
 ### ¿Cómo funciona la cascada de configuración?
 3 niveles: Gem defaults → Global config (`BugBunny.configure`) → Per-request (args en `client.request` o `Resource.with`). Se mergean con `merge`.
 
+**Defaults de la gema desde 4.16:**
+- `DEFAULT_EXCHANGE_OPTIONS = { durable: false, auto_delete: false }`
+- `DEFAULT_QUEUE_OPTIONS = { exclusive: false, durable: true, auto_delete: false }` — queue compartida duradera, válida en RabbitMQ 3.x y 4.x. Previo a 4.16 era `{ durable: false, auto_delete: true }` (deprecated `transient_nonexcl_queues` en RMQ 4.x). Para legacy: override explícito en `config.queue_options`.
+
 ### ¿Cómo funciona fork safety?
 `BugBunny::Railtie` registra hooks en `ActiveSupport::ForkTracker` (Rails 7.1+), `Puma.events.on_worker_boot` y `Spring.after_fork` para llamar `BugBunny.disconnect` y evitar sockets TCP heredados.
 

data/skill/references/client-middleware.md

@@ -72,7 +72,7 @@ El `Producer` es usado internamente por el `Client`. Implementa tres patrones de
 - Publica y bloquea hasta `channel.wait_for_confirms` del broker.
 - Bunny 2.x **no soporta timeout** nativo en `wait_for_confirms` — BugBunny envuelve la llamada en un hilo auxiliar y usa `Concurrent::IVar#value(timeout)` como reloj. Si `confirm_timeout` expira → `BugBunny::RequestTimeout`.
 - Si `wait_for_confirms` devuelve `false` (broker NACKea), se logea `producer.confirms_nacked` con `count` y `path`. Por default (`config.nack_raise = true`) levanta `BugBunny::PublishNacked` con `path` y `nacked_count`. Para opt-out: `config.nack_raise = false` o pasar `nack_raise: false` per request — en ese caso solo logea y retorna 202.
-- Si `mandatory: true` y el mensaje no es ruteable, el broker dispara `basic.return`. El handler se atacha vía `Bunny::Exchange#on_return` en `Session#exchange` la primera vez que se resuelve cada exchange (cacheado por nombre, una sola vez por canal) y delega a `Configuration#on_return` o al logger por default.
+- Si `mandatory: true` y el mensaje no es ruteable, el broker dispara `basic.return`. El handler se atacha vía `Bunny::Exchange#on_return` en `Session#exchange` la primera vez que se resuelve cada exchange (cacheado por nombre, una sola vez por canal) y delega a `Configuration#on_return` o al logger por default. **Por default (`config.return_raise = true`)** además levanta `BugBunny::PublishUnroutable` en el publish thread con `path`, `exchange`, `routing_key`, `reply_code`, `reply_text`, `correlation_id`. Para opt-out: `config.return_raise = false` o pasar `return_raise: false` per request — solo logea/invoca callback y retorna 202.
 - Errores del canal se envuelven en `BugBunny::CommunicationError`; errores `BugBunny::Error` pre-existentes se propagan sin envolver.
 - **Emite `producer.confirmed` (INFO) con tres duraciones desglosadas**: `publish_duration_s` (TCP enqueue), `confirm_duration_s` (`wait_for_confirms`), `duration_s` (total). Útil para distinguir latencia de red vs latencia de confirm policy del broker.
 
@@ -183,18 +183,35 @@ client.publish('x', confirmed: true, mandatory: true)
    ▼
 Producer#confirmed
    │
-   ├──> publish_message     (exchange.publish con mandatory: true)
+   ├──> setup_return_listener  (si return_raise? → Session#register_return_listener(cid))
+   │                            │
+   │                            └─ @session.@pending_returns[cid] = { event:, info: nil }
    │
-   ├──> wait_for_confirms!  (espera ACK del broker, con timeout opcional)
+   ├──> publish_message         (exchange.publish con mandatory: true, correlation_id auto-asignado)
    │
-   └──> handle_confirm_result
-            ├─ acked == true  → return { status: 202 }
-            └─ acked == false → log WARN producer.confirms_nacked
-                                  └─ raise BugBunny::PublishNacked  (si config.nack_raise || req.nack_raise)
-
-Asíncronamente, si el broker no pudo rutear:
-   broker ──basic.return──> Exchange#on_return ──> Session handler ──> Configuration#on_return
-                                                                   └──> default: log session.broker_return WARN
+   ├──> wait_for_confirms!      (espera ACK del broker, con timeout opcional)
+   │
+   ├──> handle_confirm_result
+   │        ├─ acked == true  → continúa
+   │        └─ acked == false → log WARN producer.confirms_nacked
+   │                              └─ raise BugBunny::PublishNacked  (si config.nack_raise || req.nack_raise)
+   │
+   ├──> handle_return_result    (si listener registrado)
+   │        ├─ slot.event.wait(RETURN_RACE_WINDOW_S = 0.05)
+   │        ├─ slot.info == nil → return (ack normal sin return)
+   │        └─ slot.info != nil → log WARN producer.publish_unroutable
+   │                                └─ raise BugBunny::PublishUnroutable
+   │
+   └──> ensure: teardown_return_listener (Session#unregister_return_listener(cid))
+
+Asíncronamente en el reader thread, si el broker no pudo rutear:
+   broker ──basic.return──> Exchange#on_return ──> Session#handle_broker_return
+                                                       │
+                                                       ├─ signal_return_listener   (busca cid en @pending_returns,
+                                                       │                            setea slot.info + slot.event)
+                                                       │
+                                                       └─ dispatch_return_callback (invoca Configuration#on_return
+                                                                                    o logea session.broker_return)
 ```
 
 ### `Configuration#on_return`
@@ -229,14 +246,43 @@ Excepciones del callback se capturan y se logean como `session.on_return_failed`
 | Auditoría, billing, eventos críticos | `:confirmed` (con `mandatory: true` si es ruteable) |
 | Request-response síncrono | `:rpc` |
 
-`:confirmed` cuesta un round-trip al broker pero **no** al consumer remoto — más rápido que RPC, con garantía de entrega al broker. NACK del broker es raro (típicamente por confirm policies internas, disk full, replicación insuficiente) pero **sí** implica que el mensaje no fue aceptado. Por default BugBunny levanta `BugBunny::PublishNacked` para que el caller pueda escalar (ej: convertir a HTTP 503 y dejar que el sistema upstream reintente). Opt-out con `config.nack_raise = false` o `nack_raise: false` per request.
+`:confirmed` cuesta un round-trip al broker pero **no** al consumer remoto — más rápido que RPC, con garantía de entrega al broker. Dos modos de falla broker-side, ambos raise-eables por default:
+
+- **NACK** (raro: confirm policies internas, disk full, replicación insuficiente) → `BugBunny::PublishNacked` (`path`, `nacked_count`). Opt-out: `config.nack_raise = false`.
+- **basic.return + mandatory** (queue inexistente, sin bindings, routing key sin match) → `BugBunny::PublishUnroutable` (`path`, `exchange`, `routing_key`, `reply_code`, `reply_text`, `correlation_id`). Opt-out: `config.return_raise = false`.
+
+El `on_return` user callback se invoca igual antes del raise (orden: signal interno → user_cb → raise en caller), así que alerting/metrics siguen funcionando.
+
+### Bridge cross-thread (`basic.return` → publish thread)
+
+`basic.return` llega en el reader thread de Bunny mientras el publish thread está dentro de `wait_for_confirms`. Para que `PublishUnroutable` sea raise-eable sincrónicamente desde la perspectiva del caller, `Session` mantiene un registry indexado por `correlation_id`:
+
+```ruby
+# Session (api privada)
+@pending_returns = Concurrent::Map.new
+# slot = { event: Concurrent::Event.new, info: nil }
+```
+
+`Producer#confirmed`:
+1. Si `return_raise?` resuelto es true, auto-asigna `request.correlation_id` si falta (UUID v4 vía `SecureRandom`).
+2. Registra slot vía `Session#register_return_listener(cid)`.
+3. Publica con `correlation_id` propagado a las message properties (el broker lo echo back en `basic.return.properties`).
+4. Tras `wait_for_confirms` true, `event.wait(RETURN_RACE_WINDOW_S = 0.05)` para tolerar GVL scheduling. AMQP wire garantiza `return → ack`, así que normalmente el event ya está seteado.
+5. Si `slot[:info]` no es nil, logea `producer.publish_unroutable` y raise.
+6. `ensure` block siempre llama `Session#unregister_return_listener(cid)` para cleanup.
+
+`Session#handle_broker_return` (reader thread):
+1. `signal_return_listener` busca cid por `properties.correlation_id`, setea `slot[:info]` y `slot[:event]`. **Esto corre ANTES del user_cb** — una excepción en el callback no impide el raise.
+2. `dispatch_return_callback` invoca `Configuration#on_return` o logea `session.broker_return`.
+
+Si `return_raise: true` se pasa sin `confirmed: true` o sin `mandatory: true`, el flag es inerte y se emite `client.return_raise_ignored` WARN. El bridge no aplica en `:publish` puro porque no hay synchronization point (`wait_for_confirms`) sobre el cual raise-ear en el caller.
 
 ## Cascada de Configuración (3 niveles)
 
 ```ruby
-# Level 1: Gem defaults
-{ durable: false, auto_delete: false }   # exchanges
-{ exclusive: false, durable: false, auto_delete: true }  # queues
+# Level 1: Gem defaults (BugBunny::Session)
+{ durable: false, auto_delete: false }                       # DEFAULT_EXCHANGE_OPTIONS
+{ exclusive: false, durable: true, auto_delete: false }      # DEFAULT_QUEUE_OPTIONS (cambio en 4.16)
 
 # Level 2: Global config
 BugBunny.configure { |c| c.exchange_options = { durable: true } }
@@ -246,3 +292,5 @@ client.request('users', exchange_options: { durable: true })
 
 # Merge final: Level1.merge(Level2).merge(Level3)
 ```
+
+**Nota 4.16+:** `DEFAULT_QUEUE_OPTIONS` previamente era `{ exclusive: false, durable: false, auto_delete: true }` (combo `transient_nonexcl_queues` deprecada en RabbitMQ 4.x). El nuevo default es queue compartida duradera. Para restaurar el comportamiento previo: `c.queue_options = { exclusive: false, durable: false, auto_delete: true }`.

data/skill/references/errores.md

@@ -9,6 +9,7 @@ StandardError
     ├── BugBunny::ConfigurationError
     ├── BugBunny::SecurityError
     ├── BugBunny::PublishNacked
+    ├── BugBunny::PublishUnroutable
     ├── BugBunny::ClientError (4xx)
     │   ├── BugBunny::BadRequest (400)
     │   ├── BugBunny::NotFound (404)
@@ -44,6 +45,12 @@ StandardError
 **Atributos:** `path` (ruta del request) y `nacked_count` (cantidad de delivery tags NACKeados).
 **Resolución:** Para casos críticos (auditoría, billing, RADIUS accounting), dejar que la excepción bubble para que el caller upstream reintente (ej: HTTP 503 → retry). Para tolerar NACKs (eventos best-effort), `BugBunny.configuration.nack_raise = false` global o `nack_raise: false` per request — en ese caso solo se logea `producer.confirms_nacked`.
 
+### BugBunny::PublishUnroutable
+**Causa:** El broker retornó un mensaje publicado con `mandatory: true` que no pudo rutearse a ninguna cola en modo `:confirmed` (queue inexistente, sin bindings que matcheen la routing key, etc.). Espejo simétrico de `PublishNacked` pero para la señal `basic.return` en lugar de `basic.nack`.
+**Cuándo:** `Producer#confirmed` con `mandatory: true` detecta un `basic.return` correlacionado por `correlation_id` antes/durante el ACK. Se levanta por default (`config.return_raise = true`, introducido en 4.15).
+**Atributos:** `path`, `exchange`, `routing_key`, `reply_code` (típicamente 312 = NO_ROUTE), `reply_text` y `correlation_id`.
+**Resolución:** Mismo patrón que `PublishNacked` — bubble en publishers críticos para traducir a HTTP 5xx + retry upstream. El `config.on_return` callback se sigue invocando antes del raise (alerting/metrics intactos). Para opt-out: `config.return_raise = false` global o `return_raise: false` per request. Inert cuando `mandatory: false` (sin mandatory el broker nunca emite `basic.return`).
+
 ## Errores de Cliente (4xx)
 
 ### BugBunny::BadRequest (400)

data/spec/integration/publisher_confirms_spec.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'support/integration_helper'
+
+# Specs de integración para Publisher Confirms en modo :confirmed + mandatory.
+# Verifican el flow end-to-end del bridge `basic.return` → `PublishUnroutable`
+# contra un RabbitMQ real.
+#
+# Se skippean automáticamente si el broker no está disponible (ver
+# `spec_helper.rb` → `before(:each, :integration)`).
+RSpec.describe 'Publisher Confirms — return_raise', :integration do
+  let(:client) { BugBunny::Client.new(pool: TEST_POOL) }
+
+  # Exchange unbound: existe pero ninguna cola está bindeada a él.
+  # Cualquier publish con mandatory:true sobre este exchange retornará.
+  let(:unbound_exchange) { unique('unroutable_x') }
+  # Exchange con cola bindeada: publish con mandatory:true llega bien.
+  let(:routable_exchange) { unique('routable_x') }
+
+  # Declara el exchange sin bindings para asegurar que `basic.return` se dispare.
+  # Usa una conexión fresca para no contaminar el pool.
+  def declare_unbound_exchange!(name)
+    conn = BugBunny.create_connection
+    ch = conn.create_channel
+    ch.topic(name, BugBunny.configuration.exchange_options)
+    ch.close
+    conn.close
+  end
+
+  before do
+    declare_unbound_exchange!(unbound_exchange)
+    # Reset flag a default conocido por si algún spec previo lo cambió.
+    BugBunny.configuration.return_raise = true
+    BugBunny.configuration.on_return = nil
+  end
+
+  after do
+    BugBunny.configuration.return_raise = true
+    BugBunny.configuration.on_return = nil
+  end
+
+  describe 'mandatory: true sobre exchange sin bindings' do
+    it 'levanta BugBunny::PublishUnroutable por default (return_raise=true)' do
+      expect {
+        client.publish('acct.unbound',
+                       exchange: unbound_exchange,
+                       exchange_type: 'topic',
+                       confirmed: true,
+                       mandatory: true,
+                       body: { tenant: 42 })
+      }.to raise_error(BugBunny::PublishUnroutable) do |err|
+        expect(err.path).to eq('acct.unbound')
+        expect(err.exchange).to eq(unbound_exchange)
+        expect(err.routing_key).to eq('acct.unbound')
+        expect(err.reply_code).to eq(312)
+        expect(err.reply_text).to match(/NO_ROUTE/i)
+        expect(err.correlation_id).to be_a(String)
+        expect(err.correlation_id).not_to be_empty
+      end
+    end
+
+    it 'NO levanta si el request override `return_raise: false`' do
+      result = client.publish('acct.unbound',
+                              exchange: unbound_exchange,
+                              exchange_type: 'topic',
+                              confirmed: true,
+                              mandatory: true,
+                              return_raise: false,
+                              body: { tenant: 42 })
+
+      expect(result).to eq('status' => 202, 'body' => nil)
+    end
+
+    it 'NO levanta si la config global tiene `return_raise = false`' do
+      BugBunny.configuration.return_raise = false
+
+      result = client.publish('acct.unbound',
+                              exchange: unbound_exchange,
+                              exchange_type: 'topic',
+                              confirmed: true,
+                              mandatory: true,
+                              body: { tenant: 42 })
+
+      expect(result).to eq('status' => 202, 'body' => nil)
+    end
+
+    it 'invoca el callback global on_return antes de levantar' do
+      captured = nil
+      BugBunny.configuration.on_return = lambda { |return_info, _props, _body|
+        captured = { exchange: return_info.exchange, rk: return_info.routing_key }
+      }
+
+      expect {
+        client.publish('acct.unbound',
+                       exchange: unbound_exchange,
+                       exchange_type: 'topic',
+                       confirmed: true,
+                       mandatory: true,
+                       body: { tenant: 42 })
+      }.to raise_error(BugBunny::PublishUnroutable)
+
+      expect(captured).not_to be_nil
+      expect(captured[:exchange]).to eq(unbound_exchange)
+      expect(captured[:rk]).to eq('acct.unbound')
+    end
+
+    it 'levanta igual cuando el user_cb on_return explota' do
+      BugBunny.configuration.on_return = ->(_, _, _) { raise 'boom in user cb' }
+
+      expect {
+        client.publish('acct.unbound',
+                       exchange: unbound_exchange,
+                       exchange_type: 'topic',
+                       confirmed: true,
+                       mandatory: true,
+                       body: { tenant: 42 })
+      }.to raise_error(BugBunny::PublishUnroutable)
+    end
+
+    it 'override per-request gana sobre config global = false' do
+      BugBunny.configuration.return_raise = false
+
+      expect {
+        client.publish('acct.unbound',
+                       exchange: unbound_exchange,
+                       exchange_type: 'topic',
+                       confirmed: true,
+                       mandatory: true,
+                       return_raise: true,
+                       body: { tenant: 42 })
+      }.to raise_error(BugBunny::PublishUnroutable)
+    end
+  end
+
+  describe 'mandatory: true sobre exchange con binding (happy path)' do
+    # Declara queue exclusive + binding contra `routable_exchange` para que el
+    # publish sea ruteable. Exclusive evita la deprecación de transient_nonexcl_queues
+    # en versiones modernas de RabbitMQ.
+    def with_exclusive_binding(exchange:, routing_key:)
+      conn = BugBunny.create_connection
+      ch = conn.create_channel
+      x = ch.topic(exchange, BugBunny.configuration.exchange_options)
+      q = ch.queue('', exclusive: true, auto_delete: true)
+      q.bind(x, routing_key: routing_key)
+      yield
+    ensure
+      ch&.close
+      conn&.close
+    end
+
+    it 'retorna 202 sin levantar — el mensaje rutea normal' do
+      with_exclusive_binding(exchange: routable_exchange, routing_key: 'acct.#') do
+        result = client.publish('acct.start',
+                                exchange: routable_exchange,
+                                exchange_type: 'topic',
+                                confirmed: true,
+                                mandatory: true,
+                                body: { tenant: 99 })
+
+        expect(result).to eq('status' => 202, 'body' => nil)
+      end
+    end
+  end
+
+  describe 'mandatory: false (flag inerte)' do
+    it 'no levanta aunque return_raise=true y la routing key no rutee a ninguna cola' do
+      result = client.publish('acct.unbound',
+                              exchange: unbound_exchange,
+                              exchange_type: 'topic',
+                              confirmed: true,
+                              mandatory: false,
+                              return_raise: true,
+                              body: { tenant: 1 })
+
+      expect(result).to eq('status' => 202, 'body' => nil)
+    end
+  end
+
+  describe 'concurrencia multi-thread sobre el mismo client' do
+    # Verifica que la correlación por correlation_id aísla los outcomes:
+    # N threads publican simultáneamente sobre el mismo exchange unbound, cada uno
+    # debe recibir SU propio PublishUnroutable (no el de otro thread).
+    it 'cada caller recibe su propio raise sin contaminación cross-thread' do
+      threads = 8
+      results = Concurrent::Array.new
+
+      pool = Array.new(threads) do |i|
+        Thread.new do
+          rk = "thread.#{i}.unbound"
+          client.publish(rk,
+                         exchange: unbound_exchange,
+                         exchange_type: 'topic',
+                         confirmed: true,
+                         mandatory: true,
+                         body: { tid: i })
+          results << { tid: i, raised: false }
+        rescue BugBunny::PublishUnroutable => e
+          results << { tid: i, raised: true, rk: e.routing_key, cid: e.correlation_id }
+        end
+      end
+
+      pool.each(&:join)
+
+      expect(results.size).to eq(threads)
+      expect(results.all? { |r| r[:raised] }).to be(true), 'todos deberían haber raised'
+      expect(results.map { |r| r[:rk] }.sort).to eq((0...threads).map { |i| "thread.#{i}.unbound" }.sort)
+      # Todos los correlation_ids deben ser distintos (no hubo cross-thread leakage)
+      cids = results.map { |r| r[:cid] }
+      expect(cids.uniq.size).to eq(threads)
+    end
+  end
+
+  describe 'aislamiento entre exchanges sobre el mismo channel' do
+    # Publish A sobre exchange unbound (debe raisear) y publish B sobre exchange routable
+    # (debe pasar). Validamos que el return de A no contamina B.
+    it 'return en exchange A no afecta publish concurrente a exchange B' do
+      bound_ex = unique('bound_b_x')
+      bound_q = unique('bound_b_q')
+
+      # Setup: exchange routable con queue exclusive bindeada
+      conn = BugBunny.create_connection
+      ch = conn.create_channel
+      x = ch.topic(bound_ex, BugBunny.configuration.exchange_options)
+      q = ch.queue('', exclusive: true, auto_delete: true)
+      q.bind(x, routing_key: '#')
+
+      results = Concurrent::Array.new
+
+      t_a = Thread.new do
+        client.publish('a.unbound',
+                       exchange: unbound_exchange,
+                       exchange_type: 'topic',
+                       confirmed: true,
+                       mandatory: true,
+                       body: { side: 'A' })
+        results << { side: 'A', raised: false }
+      rescue BugBunny::PublishUnroutable
+        results << { side: 'A', raised: true }
+      end
+
+      t_b = Thread.new do
+        client.publish('b.routable',
+                       exchange: bound_ex,
+                       exchange_type: 'topic',
+                       confirmed: true,
+                       mandatory: true,
+                       body: { side: 'B' })
+        results << { side: 'B', raised: false }
+      rescue BugBunny::PublishUnroutable
+        results << { side: 'B', raised: true }
+      end
+
+      [t_a, t_b].each(&:join)
+
+      a = results.find { |r| r[:side] == 'A' }
+      b = results.find { |r| r[:side] == 'B' }
+      expect(a[:raised]).to be(true),  'A (unbound) debería haber raised'
+      expect(b[:raised]).to be(false), 'B (routable) NO debería haber raised'
+    ensure
+      ch&.close
+      conn&.close
+    end
+  end
+
+  describe 'no hay leak en el registry tras publishes seriales' do
+    # 30 publishes seriales (mix routable + unroutable). Tras todos, el registry
+    # @pending_returns debe estar en 0. Detecta entries colgadas por cleanup mal hecho.
+    it 'registry vuelve a 0 tras una serie de publishes' do
+      30.times do |i|
+        target = i.even? ? unbound_exchange : nil
+        if target
+          begin
+            client.publish("serial.#{i}",
+                           exchange: target,
+                           exchange_type: 'topic',
+                           confirmed: true,
+                           mandatory: true,
+                           body: { i: i })
+          rescue BugBunny::PublishUnroutable
+            # esperado en routes no-ruteables
+          end
+        else
+          # publish sin mandatory para no triggerear return — no-op para el registry
+          client.publish("serial.#{i}",
+                         exchange: unbound_exchange,
+                         exchange_type: 'topic',
+                         confirmed: true,
+                         mandatory: false,
+                         body: { i: i })
+        end
+      end
+
+      # Inspeccionar cada Session del pool — el registry debe estar vacío en todas.
+      total_pending = 0
+      TEST_POOL.with do |conn|
+        session = conn.instance_variable_get(:@_bug_bunny_session)
+        registry = session.instance_variable_get(:@pending_returns)
+        total_pending += registry.size
+      end
+      expect(total_pending).to eq(0)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -23,8 +23,11 @@ BugBunny.configure do |config|
   config.password = ENV.fetch('RABBITMQ_PASS', 'guest')
   config.vhost    = '/'
   config.logger   = Logger.new($stdout).tap { |l| l.level = Logger::WARN }
+  # exchange_options: explícito para que los specs declaren exchanges efímeros.
+  # queue_options: NO override — confiamos en `DEFAULT_QUEUE_OPTIONS` (durable shared,
+  # válido en RMQ 3.x y 4.x). Specs que necesitan colas efímeras usan
+  # `TEST_WORKER_QUEUE_OPTS` desde `spec/support/integration_helper.rb`.
   config.exchange_options = { durable: false, auto_delete: true }
-  config.queue_options    = { exclusive: false, durable: false, auto_delete: true }
 end
 
 TEST_POOL ||= ConnectionPool.new(size: 5, timeout: 5) { BugBunny.create_connection }

data/spec/support/integration_helper.rb

@@ -2,6 +2,12 @@
 
 require 'timeout'
 
+# Queue options usados por los workers de integración. \`exclusive: true\` evita
+# la deprecación de \`transient_nonexcl_queues\` en RabbitMQ 4.x — la queue queda
+# ligada a la conexión del worker y desaparece automáticamente al cerrarla.
+# Sobreescribe la cascada de \`BugBunny.configuration.queue_options\`.
+TEST_WORKER_QUEUE_OPTS = { exclusive: true, durable: false, auto_delete: true }.freeze unless defined?(TEST_WORKER_QUEUE_OPTS)
+
 # Helpers compartidos para specs de integración con RabbitMQ real.
 # Incluido automáticamente en todos los specs marcados con :integration.
 RSpec.shared_context 'integration helpers' do
@@ -31,6 +37,7 @@ RSpec.shared_context 'integration helpers' do
         exchange_name: exchange,
         exchange_type: exchange_type,
         routing_key:   routing_key,
+        queue_opts:    TEST_WORKER_QUEUE_OPTS,
         block:         true
       )
     rescue StandardError => e
@@ -57,7 +64,7 @@ RSpec.shared_context 'integration helpers' do
     worker_thread = Thread.new do
       ch = conn.create_channel
       x  = ch.public_send(exchange_type, exchange, BugBunny.configuration.exchange_options)
-      q  = ch.queue(queue, BugBunny.configuration.queue_options)
+      q  = ch.queue(queue, TEST_WORKER_QUEUE_OPTS)
       q.bind(x, routing_key: routing_key)
       q.subscribe(block: true) do |delivery, props, body|
         messages << { body: body, routing_key: delivery.routing_key, headers: props.headers }

data/spec/unit/client_session_pool_spec.rb

@@ -215,6 +215,78 @@ RSpec.describe BugBunny::Client, 'session pooling' do
     end
   end
 
+  describe 'warn_return_raise_misuse' do
+    let(:log_io) { StringIO.new }
+
+    before do
+      @prev_logger = BugBunny.configuration.logger
+      BugBunny.configuration.logger = Logger.new(log_io).tap { |l| l.level = Logger::WARN }
+    end
+
+    after do
+      BugBunny.configuration.logger = @prev_logger
+    end
+
+    def stub_producer_to_noop
+      allow_any_instance_of(BugBunny::Producer).to receive(:confirmed) { { 'status' => 202, 'body' => nil } }
+      allow_any_instance_of(BugBunny::Producer).to receive(:fire) { { 'status' => 202, 'body' => nil } }
+    end
+
+    it 'logea warning cuando return_raise:true se pasa sin confirmed' do
+      stub_producer_to_noop
+      client = described_class.new(pool: fake_pool(fake_conn))
+
+      client.publish('foo', exchange: 'x', exchange_type: 'direct',
+                            return_raise: true, mandatory: true)
+
+      expect(log_io.string).to include('event=client.return_raise_ignored')
+      expect(log_io.string).to include('delivery_mode=publish')
+    end
+
+    it 'logea warning cuando return_raise:true se pasa sin mandatory' do
+      stub_producer_to_noop
+      client = described_class.new(pool: fake_pool(fake_conn))
+
+      client.publish('foo', exchange: 'x', exchange_type: 'direct',
+                            return_raise: true, confirmed: true)
+
+      expect(log_io.string).to include('event=client.return_raise_ignored')
+      expect(log_io.string).to include('mandatory=false')
+    end
+
+    it 'NO logea warning cuando confirmed+mandatory se setean via block API' do
+      stub_producer_to_noop
+      client = described_class.new(pool: fake_pool(fake_conn))
+
+      client.publish('foo', exchange: 'x', exchange_type: 'direct', return_raise: true) do |req|
+        req.delivery_mode = :confirmed
+        req.mandatory = true
+      end
+
+      expect(log_io.string).not_to include('client.return_raise_ignored')
+    end
+
+    it 'NO logea warning cuando return_raise no fue seteado per-request (deja el default global)' do
+      stub_producer_to_noop
+      client = described_class.new(pool: fake_pool(fake_conn))
+
+      # Default global es true, pero el caller no fue explícito → no warneamos
+      client.publish('foo', exchange: 'x', exchange_type: 'direct')
+
+      expect(log_io.string).not_to include('client.return_raise_ignored')
+    end
+
+    it 'NO logea warning cuando confirmed+mandatory+return_raise:true coexisten' do
+      stub_producer_to_noop
+      client = described_class.new(pool: fake_pool(fake_conn))
+
+      client.publish('foo', exchange: 'x', exchange_type: 'direct',
+                            confirmed: true, mandatory: true, return_raise: true)
+
+      expect(log_io.string).not_to include('client.return_raise_ignored')
+    end
+  end
+
   describe 'Session no se cierra entre requests' do
     it 'no invoca close en la Session al terminar el request' do
       conn   = fake_conn