bug_bunny 4.13.0 → 4.16.0

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.13.0'
+  VERSION = '4.16.0'
 end

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.
@@ -97,6 +99,39 @@ BugBunny implementa las [OpenTelemetry semantic conventions for messaging](https
 - **Consumer:** Extrae los campos de los logs estructurados sin mutar los headers originales. Los eventos `consumer.message_received` y `consumer.message_processed` incluyen estos campos automáticamente.
 - **RPC Reply:** El consumer inyecta los mismos campos en el reply para cerrar el ciclo de traza del lado del cliente.
 
+### Eventos de log y duraciones internas
+
+BugBunny mide y emite duraciones automáticamente. **No envolver llamadas a `client.publish` con `Process.clock_gettime` en código de aplicación** — duplica el trabajo. Las duraciones siguen las [OpenTelemetry metric semantic conventions](https://opentelemetry.io/docs/specs/semconv/general/metrics/) (`duration_s` como `Float` en segundos).
+
+| Evento | Nivel | Emitido por | Campos clave |
+|---|---|---|---|
+| `producer.publish` | INFO | `Producer#publish_message` (pre) | `method`, `path`, `messaging_*` |
+| `producer.publish_payload` | INFO | `Producer#publish_message` | `payload` (truncado), `body_size` |
+| `producer.publish_detail` | DEBUG | `Producer#publish_message` | `exchange_opts` final |
+| `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` |
+| `consumer.message_received` | INFO | `Consumer#process_message` | `method`, `path`, `messaging_*` |
+| `consumer.message_processed` | INFO | `Consumer#process_message` (post) | `response_status`, **`duration_s`**, `controller`, `action`, `messaging_*` |
+| `consumer.execution_error` | ERROR | `Consumer#process_message` (rescue) | **`duration_s`**, `error_class`, `error_message` |
+| `consumer.route_not_found` | WARN | `Consumer#process_message` | `method`, `path` |
+| `consumer.connection_error` | ERROR | `Consumer#subscribe` (retry loop) | `attempt_count`, `retry_in_s`, `error_*` |
+| `session.broker_return` | WARN | `Session` (mandatory unrouted) | `reply_code`, `reply_text`, `exchange`, `routing_key` |
+
+**Resumen de qué mide cada `duration_s`:**
+
+- `producer.published.duration_s` — solo el `basic_publish` (TCP enqueue al broker).
+- `producer.confirmed.publish_duration_s` — el publish.
+- `producer.confirmed.confirm_duration_s` — la espera del ACK del broker (`wait_for_confirms`).
+- `producer.confirmed.duration_s` — total (publish + ACK).
+- `producer.rpc_response_received.duration_s` — round-trip RPC completo (publish + procesamiento remoto + reply).
+- `consumer.message_processed.duration_s` — procesamiento server-side (router + controller + reply).
+
 ---
 
 ## API: Configuración Global
@@ -129,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) }
 
@@ -202,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.
 
 ---
@@ -226,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

@@ -59,19 +59,22 @@ El `Producer` es usado internamente por el `Client`. Implementa tres patrones de
 - Reply listener (`basic_consume`) auto-iniciado en el primer RPC.
 - Double-checked locking mutex para seguridad del listener.
 - Timeout lanza `BugBunny::RequestTimeout`.
+- **Emite `producer.rpc_response_received` (INFO) con `duration_s` = round-trip total** (publish + procesamiento remoto + reply). No medir en código de aplicación.
 
 ### Fire-and-Forget (`Producer#fire`)
 
 - Publica en el exchange y retorna `{ 'status' => 202 }` inmediatamente.
 - Sin confirmación de procesamiento.
+- **Emite `producer.published` (INFO) con `duration_s`** = solo el `basic_publish` (TCP enqueue al broker).
 
 ### Confirmed (`Producer#confirmed`)
 
 - 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.
 
 ## Middleware Stack (Client-side, Onion Architecture)
 
@@ -180,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`
@@ -226,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 } }
@@ -243,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)