bug_bunny 4.14.0 → 4.17.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.14.0'
+  VERSION = '4.17.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.
@@ -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,48 @@ 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`).
 ```
 
+**Receta canónica de publisher productivo (auditoría / billing / accounting):**
+```ruby
+client.publish('acct.start',
+               exchange:         'ingest.radius',
+               exchange_type:    :topic,
+               exchange_options: { durable: true },    # matchear declaración del consumer
+               body:             payload,
+               confirmed:        true,                 # broker ACK síncrono
+               mandatory:        true,                 # raise PublishUnroutable si no hay binding
+               persistent:       true,                 # delivery_mode: 2 — sobrevive restart
+               correlation_id:   SecureRandom.uuid,    # tracing explícito
+               app_id:           'radius_manager')
+```
+A partir de 4.17, `persistent`, `correlation_id`, `priority`, `app_id`, `content_type`, `content_encoding` y `expiration` están en `Client::REQUEST_ATTRS` y se aceptan como kwargs. El block API sigue funcionando para overrides puntuales o para atributos no expuestos (`timestamp`, `type`).
+
+**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 +303,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.
 
@@ -276,6 +326,29 @@ No guardar el resultado de `Order.with(...)` en una variable para múltiples lla
 ### Registrar middleware durante call()
 No registrar consumer middlewares durante la ejecución de `call()`. El stack toma un snapshot al inicio; los registros concurrentes no afectan la ejecución actual.
 
+### Pasar `path:` como kwarg a `Client#publish` / `#request`
+El primer argumento es **posicional** (`url`). No hay kwarg `:path`. Splatear un hash que tenga `path:` falla con `ArgumentError: wrong number of arguments`. Construir args sin path y pasar la URL aparte:
+```ruby
+args = { exchange: 'x', body: payload }
+client.publish('event.name', **args)   # ✅
+client.publish(**args.merge(path: 'event.name'))  # ❌
+```
+
+### Asumir que `confirmed: true` implica persistencia
+`confirmed: true` solo activa Publisher Confirms (broker ACK síncrono). **NO** setea `delivery_mode: 2`. El default de `Request#persistent` es `false` — el mensaje vive en RAM del broker y se pierde si reinicia. Para eventos críticos sobre queue durable hay que pasar `persistent: true` (a partir de 4.17) o setearlo via block. Tabla de decisión:
+
+| Necesitás | Pasar |
+|---|---|
+| Broker confirma recepción | `confirmed: true` |
+| Mensaje sobrevive restart | `persistent: true` (requiere queue `durable: true`) |
+| Raise si no rutea | `mandatory: true` (+ `return_raise: true` default) |
+
+### Olvidar `exchange_options: { durable: true }` en publishers a exchange compartido
+`DEFAULT_EXCHANGE_OPTIONS = { durable: false, auto_delete: false }`. Si un consumer previamente declaró el exchange como durable (caso normal en producción), un publisher que use el default va a recibir `Bunny::PreconditionFailed - inequivalent arg 'durable'` al re-declarar. Solución: pasar `exchange_options: { durable: true }` en el publisher, o setear global `BugBunny.configure { |c| c.exchange_options = { durable: true } }`.
+
+### Confiar en `instance_double(BugBunny::Client)` para detectar errores de signature
+Limitación de RSpec: `instance_double` valida que el método exista pero **no** valida arity estricta cuando el caller hace `**args` splat. Tests con mocks pasan, integration con broker real rompe. Mitigación: para cada publisher nuevo, sumar un smoke spec `:integration` que declare queue exclusiva con binding, publique, haga `queue.pop`, y verifique `correlation_id`, `delivery_mode`, `headers`, `routing_key`.
+
 ---
 
 ## Errores Comunes

data/skill/references/client-middleware.md

@@ -47,6 +47,18 @@ end
 | `mandatory` | Boolean | `false` | Pide al broker retornar el mensaje si no es ruteable. Solo útil con `confirmed: true`. |
 | `confirm_timeout` | Float | `nil` | Segundos máximos a esperar el ACK. `nil` = espera indefinida. Excedido → `BugBunny::RequestTimeout`. |
 | `nack_raise` | Boolean | `nil` | Override per-request de `config.nack_raise`. `nil` = usa flag global. |
+| `return_raise` | Boolean | `nil` | Override per-request de `config.return_raise`. Requiere `confirmed: true` y `mandatory: true`. |
+| `persistent` | Boolean | `false` | `delivery_mode: 2` AMQP. Mensaje sobrevive restart del broker. Requiere queue durable. |
+| `correlation_id` | String | nil | ID de correlación AMQP. Auto-asignado UUID en RPC y en `confirmed + mandatory + return_raise`. |
+| `priority` | Integer | nil | Prioridad 0-255. Requiere queue con `x-max-priority`. |
+| `app_id` | String | nil | Identificador del publisher (AMQP `app-id`). |
+| `content_type` | String | `'application/json'` | MIME type del payload. |
+| `content_encoding` | String | nil | Encoding del payload (`'gzip'`, `'deflate'`, etc.). |
+| `expiration` | String | nil | TTL del mensaje en ms (formato AMQP). |
+
+**Gotcha:** el primer argumento de `Client#publish` / `#request` es **posicional** (`url`). No existe el kwarg `:path`. Splatear un hash con `path:` falla con `ArgumentError` o se ignora silencioso.
+
+**Atributos no expuestos como kwarg** (solo via block API): `timestamp` (default `Time.now.to_i`), `type` (default `full_path`), `reply_to` (RPC interno).
 
 ## Producer (bajo nivel)
 
@@ -72,7 +84,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 +195,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 }
+   │
+   ├──> publish_message         (exchange.publish con mandatory: true, correlation_id auto-asignado)
+   │
+   ├──> wait_for_confirms!      (espera ACK del broker, con timeout opcional)
    │
-   ├──> 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_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
+   ├──> 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 +258,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 +304,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)