bug_bunny 4.14.0 → 4.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6081a471e20278bc190a7d7517b69cf6fe6d852293bca353974c5ba1cbe4e746
-  data.tar.gz: 2e1b952c9627b7f3f1f9ab1e2af25af49ca0422ff59f062ac7499c14265d6a57
+  metadata.gz: ec5013f4d782766d388826265255b008a9c17119b15acef95a05fcb01a9722d5
+  data.tar.gz: 0cd930d1d4c982a0ba9bf73e9562504d0e776c88c760e427dc440a1399b57a13
 SHA512:
-  metadata.gz: 6cf7de01b98c925c8f02de1e09aafc0113f24f93145498ace1616445deecf6319bde3464d9afcd89b5b461904fbe878d4bfb24ea3a2a310149a32f6f2b06f4d0
-  data.tar.gz: 2560004c6036b238456fe9c9af9bf478dde67b1ff07240fdac942ecab303467d1db04f3029c2579463e5017b7c9f25ad2e5f1c5ef2c999f86bcde0bedb42eb67
+  metadata.gz: 800c22370b7e39812cc1d90ca74db9ea4736e4354e4061d39a0e0e9d5fbb7fa5ff05c56474f61056a7fe072144339c48d725f040c34c16ba7f0805a314881d66
+  data.tar.gz: 921e0359f5426db49beaf327e67885568313282c3972e9bc2e9d7f88e28fdad032f3258ab73e4cca16f9b3f70cdbf5f42311e3d4f910e4430494ebb4ea8e05a8

data/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## [4.17.0] - 2026-05-13
+
+### Nuevas funcionalidades
+- **`Client::REQUEST_ATTRS` extendido con metadata AMQP estándar (#45):** Los siguientes atributos del Request ahora pueden pasarse como kwargs directos en `client.publish` / `client.request` sin necesidad del block API:
+  - `persistent` (Boolean) — `delivery_mode: 2` AMQP. Critical: por default es `false`; `confirmed: true` **NO** lo implica.
+  - `correlation_id` (String) — Tracing explícito (sobreescribe el auto-asignado por RPC y `return_raise`).
+  - `priority` (Integer 0-255).
+  - `app_id` (String).
+  - `content_type` (String, default `'application/json'`).
+  - `content_encoding` (String).
+  - `expiration` (String, TTL en ms).
+
+  ```ruby
+  # Antes (4.16): requería block API
+  client.publish('evt', exchange: 'x', confirmed: true) do |req|
+    req.persistent = true
+    req.correlation_id = 'cid-123'
+  end
+
+  # Ahora (4.17): kwargs directos
+  client.publish('evt', exchange: 'x', confirmed: true,
+                 persistent: true, correlation_id: 'cid-123')
+  ```
+
+  El block API sigue funcionando para overrides puntuales o para atributos no expuestos (`timestamp`, `type`, `reply_to`).
+
+### Correcciones
+- **`apply_args` usa `args.key?` en lugar de truthy check:** Permite pasar valores falsy explícitos (ej. `persistent: false`, `priority: 0`) que antes se filtraban silenciosamente como si no se hubieran pasado.
+
+### Documentación (motivado por #45 — adopción real en sequre/box_radius_manager#18)
+- README + SKILL.md cubren cuatro gotchas detectados solo en integration tests:
+  1. `url` es positional, no kwarg `:path`. Splatear un hash con `path:` rompe.
+  2. `confirmed: true` no implica `persistent: true` — son flags ortogonales.
+  3. Default `exchange_options` es `{ durable: false }` — publishers a exchange compartido deben pasar `exchange_options: { durable: true }` explícito.
+  4. `instance_double` no detecta arity mismatch con splat de kwargs — recomendación de smoke test integration para cada publisher nuevo.
+- Nueva sección "Production publisher recipe" en README y receta canónica en SKILL.md con la combinación recomendada para auditoría/billing/accounting.
+- `skill/references/client-middleware.md` con tabla completa de kwargs de Request actualizada.
+
+## [4.16.0] - 2026-05-13
+
+### Cambios de comportamiento (semi-breaking)
+- **`DEFAULT_QUEUE_OPTIONS` cambió a `{ exclusive: false, durable: true, auto_delete: false }`** (#42). En versiones previas el default era `{ exclusive: false, durable: false, auto_delete: true }` — la combinación `transient_nonexcl_queues` que **RabbitMQ 4.x deprecó por default**: el broker rechaza la declaración matando la conexión. El nuevo default es el patrón "queue compartida duradera": sobrevive restart del broker, múltiples consumers pueden compartirla, no se elimina cuando se desconecta el último consumer. Esto matchea cómo la mayoría de servicios Wispro ya configuran sus queues explícitamente.
+
+  **Para restaurar el comportamiento anterior** (servicios sobre RabbitMQ 3.x con queues legacy efímeras pre-existentes):
+
+  ```ruby
+  BugBunny.configure do |c|
+    c.queue_options = { exclusive: false, durable: false, auto_delete: true }
+  end
+  ```
+
+  **Síntoma si se necesita override y no se aplicó:** `Bunny::PreconditionFailed - inequivalent arg 'durable' for queue 'foo'`. Indica que la queue existe en el broker con `durable: false` pero el nuevo default intenta declararla con `durable: true`. Aplicar el override de arriba o borrar manualmente la queue legacy en el broker.
+
+### Documentación
+- README + SKILL.md actualizados con sección "queue_options recomendadas" cubriendo patrones worker-pool (default nuevo) y single-instance (`exclusive: true`).
+
+## [4.15.0] - 2026-05-13
+
+### Nuevas funcionalidades
+- **`return_raise` flag para mandatory + basic.return (#38):** `Producer#confirmed` ahora levanta `BugBunny::PublishUnroutable` cuando el broker retorna un mensaje publicado con `mandatory: true` que no pudo rutearse a ninguna cola. Espejo simétrico de `nack_raise`/`PublishNacked`. La excepción expone `path`, `exchange`, `routing_key`, `reply_code`, `reply_text` y `correlation_id`. Internamente la gema implementa el bridge cross-thread (reader thread → publish thread) que antes cada caller tenía que replicar manualmente con `Concurrent::Map` + lambda. Configurable globalmente vía `BugBunny.configuration.return_raise` (default `true`) y por request via `client.publish(..., return_raise: false)`. El callback global `on_return` se sigue invocando antes del raise. — @Gabriel
+
+### Cambios de comportamiento (semi-breaking)
+- **Default `return_raise: true`:** Publicaciones con `confirmed: true, mandatory: true` que reciben `basic.return` del broker ahora levantan excepción por default. En 4.14.0 el return solo se logueaba (o invocaba el callback `on_return`) y la llamada retornaba 202 silenciosamente — ocultando pérdida de mensajes. Para mantener el comportamiento previo: `BugBunny.configuration.return_raise = false` o `return_raise: false` per request. El flag es **inerte cuando `mandatory: false`** — sin mandatory el broker nunca emite return.
+
+### Detalles internos
+- `Producer#confirmed` auto-asigna `correlation_id` (UUID) cuando falta y `mandatory + return_raise` están activos — la correlación bridge↔return depende del cid.
+- Nuevo bound de espera `Producer::RETURN_RACE_WINDOW_S = 0.05` tras un ack positivo: tolera el race scheduling entre reader thread (donde Bunny invoca `on_return`) y publish thread (donde se devuelve `wait_for_confirms`). AMQP garantiza orden wire (return precede a ack), pero defendemos contra GVL.
+- `Session` ahora mantiene un registry interno `@pending_returns` (`Concurrent::Map` de cid → `{event, info}`). `handle_broker_return` setea el event *antes* de invocar el user_cb global — una excepción del callback no impide el raise en el caller.
+- Nuevo evento de log `producer.publish_unroutable` (WARN) con `path`, `exchange`, `routing_key`, `reply_code`, `reply_text`, `messaging_message_id`. Se emite antes de levantar `PublishUnroutable`.
+- Nuevo evento de log `client.return_raise_ignored` (WARN) cuando se pasa `return_raise: true` sin `confirmed: true` o sin `mandatory: true` — el flag se ignora.
+
 ## [4.14.0] - 2026-05-12
 
 ### Nuevas funcionalidades

data/README.md

@@ -129,7 +129,11 @@ BugBunny.configure do |config|
   config.read_timeout        = 10
   config.write_timeout       = 10
 
-  # AMQP defaults applied to all exchanges and queues
+  # AMQP defaults applied to all exchanges and queues.
+  # Gem defaults (since 4.16):
+  #   DEFAULT_EXCHANGE_OPTIONS = { durable: false, auto_delete: false }
+  #   DEFAULT_QUEUE_OPTIONS    = { exclusive: false, durable: true, auto_delete: false }
+  # Override only if your service needs different infrastructure semantics.
   config.exchange_options = { durable: true }
   config.queue_options    = { durable: true }
 
@@ -142,7 +146,13 @@ BugBunny.configure do |config|
   # Health check file for Kubernetes / Docker Swarm liveness probes
   config.health_check_file = '/tmp/bug_bunny_health'
 
+  # Publisher Confirms — fail-loud defaults (both flags default to true).
+  # Set to false to restore legacy log-only behavior.
+  config.nack_raise   = true   # broker NACK → raise BugBunny::PublishNacked
+  config.return_raise = true   # broker basic.return (mandatory) → raise BugBunny::PublishUnroutable
+
   # Callback invoked when the broker returns an unroutable mandatory message.
+  # Runs BEFORE PublishUnroutable is raised (if return_raise is true).
   # When nil (default), BugBunny logs the return as `session.broker_return` at :warn.
   # Signature: ->(return_info, properties, body) { ... }
   config.on_return = ->(return_info, _props, body) {
@@ -200,6 +210,73 @@ client.publish('events', body: { type: 'user.signed_in', user_id: 42 })
 client.request('users', method: :get, params: { role: 'admin', page: 2 })
 ```
 
+### Gotchas
+
+**URL is positional, not a kwarg.** The first argument of `client.request` / `client.publish` is positional. There is **no** `path:` kwarg, splatting a hash with `path:` will fail silently or raise `ArgumentError`:
+
+```ruby
+args = { exchange: 'ingest.x', body: payload }
+client.publish(**args)              # ❌ ArgumentError: wrong number of arguments
+client.publish('event.name', **args) # ✅
+```
+
+**Block runs after kwargs.** Keyword args are applied first; the block (if given) can override them. Use kwargs for the common case and block for atypical setup:
+
+```ruby
+client.publish('evt', exchange: 'x', persistent: true) do |req|
+  req.timestamp = some_past_time   # only via block — not in REQUEST_ATTRS
+end
+```
+
+### Production publisher recipe
+
+Defaults aimed at sane microservices — declare durable exchanges, persistent messages, confirmed delivery with mandatory routing, explicit correlation id:
+
+```ruby
+client.publish('acct.start',
+               exchange:         'ingest.radius',
+               exchange_type:    :topic,
+               exchange_options: { durable: true },   # match consumer-declared exchange
+               body:             payload,
+               confirmed:        true,
+               mandatory:        true,                # raise PublishUnroutable if no binding
+               persistent:       true,                # delivery_mode: 2 — survives broker restart
+               correlation_id:   SecureRandom.uuid,
+               app_id:           'radius_manager')
+```
+
+| AMQP property | Kwarg | Reason it matters for critical publishers |
+|---|---|---|
+| `delivery_mode` | `persistent: true` | Without it, the message lives only in broker RAM (lost on restart). Default `false`. |
+| `confirmation` | `confirmed: true` | Block until the broker acks. Without it, `client.publish` returns 202 before the broker sees the message. |
+| `mandatory` | `mandatory: true` | Catches misrouted publishes. Combined with `return_raise` (default `true`), raises `PublishUnroutable` instead of silently dropping. |
+| `exchange durable` | `exchange_options: { durable: true }` | Match the exchange definition that consumers declare. Mismatch raises `Bunny::PreconditionFailed`. |
+| `correlation_id` | `correlation_id:` | Tracing. Auto-generated when missing for RPC and for `confirmed + mandatory + return_raise`, but explicit is preferred. |
+
+### Testing publishers
+
+Mocks of `Client` (via `instance_double`) **do not catch arity mismatches** when the caller does splat (`**args`). Signature errors like passing `path:` as kwarg or unknown keys won't surface in unit tests with mocks. **Add a smoke integration test** for new publishers — declare an exclusive queue, bind to the exchange, publish, `queue.pop`, assert `correlation_id`, `headers`, `routing_key`, `delivery_mode`:
+
+```ruby
+RSpec.describe 'MyPublisher', :integration do
+  it 'publishes with correct AMQP metadata' do
+    conn = BugBunny.create_connection
+    ch   = conn.create_channel
+    x    = ch.topic('ingest.radius', durable: true)
+    q    = ch.queue('', exclusive: true).bind(x, routing_key: 'acct.#')
+
+    MyPublisher.call(payload)
+
+    _delivery, props, body = q.pop(manual_ack: false)
+    expect(props.correlation_id).not_to be_nil
+    expect(props.delivery_mode).to eq(2)         # persistent
+    expect(JSON.parse(body)).to include(...)
+  ensure
+    conn&.close
+  end
+end
+```
+
 ### Publisher Confirms (delivery-critical events)
 
 For events where you need a delivery guarantee from the broker (auditing, billing, accounting) without the cost of a full RPC, use `publish` with `confirmed: true`. The call blocks until the broker acknowledges receipt:
@@ -220,11 +297,26 @@ client.publish('acct.start',
 | `confirmed` | Boolean | `false` | Block until `wait_for_confirms` returns. |
 | `mandatory` | Boolean | `false` | Broker returns the message if it cannot be routed to any queue. Requires `confirmed: true` to be useful. |
 | `confirm_timeout` | Float | `nil` | Seconds to wait for the broker ACK. Raises `BugBunny::RequestTimeout` if exceeded. |
-| `nack_raise` | Boolean | `nil` | Per-request override of `config.nack_raise`. When `nil`, falls back to the global flag. |
+| `nack_raise` | Boolean | `nil` | Per-request override of `config.nack_raise`. When `nil`, falls back to the global flag (default `true`). |
+| `return_raise` | Boolean | `nil` | Per-request override of `config.return_raise`. When `nil`, falls back to the global flag (default `true`). Requires `confirmed: true` and `mandatory: true` to take effect. |
+
+**Two broker signals, two exceptions:**
+
+| Broker signal | Default behavior | Exception class | Fields |
+|---|---|---|---|
+| `basic.nack` (explicit rejection) | Raises | `BugBunny::PublishNacked` | `path`, `nacked_count` |
+| `basic.return` (unroutable + `mandatory: true`) | Raises | `BugBunny::PublishUnroutable` | `path`, `exchange`, `routing_key`, `reply_code`, `reply_text`, `correlation_id` |
 
-If the broker NACKs the publish (explicit rejection — disk full, internal confirm policy, etc.), the call raises `BugBunny::PublishNacked` by default. The exception exposes `path` and `nacked_count`. Critical publishers (audit, billing, RADIUS accounting) can let it bubble up to translate into HTTP 5xx so upstream systems retry. To restore the legacy "log-only" behaviour, set `BugBunny.configuration.nack_raise = false` globally or pass `nack_raise: false` per request.
+Both exceptions translate naturally into HTTP 5xx in critical publishers (audit, billing, RADIUS accounting) so upstream systems retry. The `config.on_return` callback (if defined) still runs before `PublishUnroutable` is raised — useful for alerting/metrics. To restore the legacy "log-only" behaviour:
+
+```ruby
+BugBunny.configure do |c|
+  c.nack_raise   = false  # or pass `nack_raise: false` per request
+  c.return_raise = false  # or pass `return_raise: false` per request
+end
+```
 
-Unroutable returned messages are handled by a single global callback (see `config.on_return` below). The default handler logs them as `session.broker_return` at `warn` level — nothing is dropped silently.
+When `mandatory: false` (the default), `return_raise` is inert — the broker never emits `basic.return` without mandatory.
 
 ---
 
@@ -285,9 +377,15 @@ BugBunny maps RabbitMQ responses to a semantic exception hierarchy, similar to h
 
 ```
 BugBunny::Error
+├── CommunicationError                  (network / channel failure)
+├── ConfigurationError                  (invalid config attribute)
+├── SecurityError                       (unauthorized controller resolution)
+├── PublishNacked                       (broker basic.nack on :confirmed publish)
+├── PublishUnroutable                   (broker basic.return on mandatory + :confirmed)
 ├── ClientError (4xx)
 │   ├── BadRequest (400)
 │   ├── NotFound (404)
+│   │   └── RoutingError                (consumer-side: no route for verb + path)
 │   ├── NotAcceptable (406)
 │   ├── RequestTimeout (408)
 │   ├── Conflict (409)

data/lib/bug_bunny/client.rb

@@ -29,9 +29,17 @@ module BugBunny
     attr_accessor :delivery_mode
 
     # Argumentos del cliente que se mapean 1:1 a setters del Request.
+    #
+    # Incluye opciones de enrutamiento (`delivery_mode`, `method`, `body`, `exchange`,
+    # `exchange_type`, `routing_key`, `timeout`, `params`), de infraestructura
+    # (`exchange_options`, `queue_options`) y de metadata AMQP estándar
+    # (`persistent`, `correlation_id`, `priority`, `app_id`, `content_type`,
+    # `content_encoding`, `expiration`). Lo que no esté acá debe setearse via
+    # block API (`do |req| ... end`).
     REQUEST_ATTRS = %i[
       delivery_mode method body exchange exchange_type routing_key
       timeout exchange_options queue_options params
+      persistent correlation_id priority app_id content_type content_encoding expiration
     ].freeze
 
     # Inicializa un nuevo cliente.
@@ -64,7 +72,8 @@ module BugBunny
     #
     # Envía un mensaje y bloquea la ejecución del hilo actual hasta recibir respuesta.
     #
-    # @param url [String] La ruta del recurso (ej: 'users/1').
+    # @param url [String] La ruta del recurso (ej: 'users/1'). **Argumento posicional** —
+    #   no existe el kwarg `:path`. Splatear un hash con `path:` falla silencioso.
     # @param args [Hash] Opciones de configuración.
     # @option args [Symbol] :method El verbo HTTP (:get, :post, :put, :delete). Default: :get.
     # @option args [Object] :body El cuerpo del mensaje.
@@ -72,7 +81,18 @@ module BugBunny
     # @option args [Integer] :timeout Tiempo máximo de espera.
     # @option args [Hash] :exchange_options Opciones específicas para la declaración del Exchange.
     # @option args [Hash] :queue_options Opciones específicas para la declaración de la Cola.
-    # @yield [req] Bloque para configurar el objeto Request directamente.
+    # @option args [Boolean] :persistent Si `true`, `delivery_mode: 2` (mensaje persiste en disco
+    #   del broker). Default `false`. Útil para mensajes críticos sobre queues durables.
+    # @option args [String] :correlation_id ID de correlación AMQP. Útil para tracing custom.
+    #   Si no se setea, `Producer#rpc` y `Producer#confirmed` (con return_raise) auto-asignan UUID.
+    # @option args [Integer] :priority Prioridad del mensaje (0-255). Requiere queue declarada con
+    #   `x-max-priority` para que el broker la respete.
+    # @option args [String] :app_id Identificador del publisher.
+    # @option args [String] :content_type MIME type. Default `'application/json'`.
+    # @option args [String] :content_encoding Encoding del payload (ej: 'gzip').
+    # @option args [String] :expiration TTL del mensaje en ms (formato AMQP).
+    # @yield [req] Bloque para configurar el objeto Request directamente. Necesario para
+    #   atributos no mapeados como kwarg (ej: `req.timestamp = ...`).
     # @return [Hash] La respuesta del servidor.
     def request(url, **args)
       send(url, **args) do |req|
@@ -87,7 +107,8 @@ module BugBunny
     # que el broker confirme la recepción del mensaje. Útil para eventos críticos (auditoría,
     # billing) donde se requiere garantía de entrega sin el overhead de un RPC completo.
     #
-    # @param url [String] La ruta del evento/recurso.
+    # @param url [String] La ruta del evento/recurso. **Argumento posicional** — no
+    #   existe el kwarg `:path`. Splatear un hash con `path:` falla silencioso.
     # @param args [Hash] Mismas opciones que {#request}, excepto `:timeout`. Adicionales:
     # @option args [Boolean] :confirmed Si `true`, espera `wait_for_confirms` del broker.
     # @option args [Boolean] :mandatory Si `true`, el broker retorna el mensaje si no es ruteable.
@@ -95,10 +116,16 @@ module BugBunny
     # @option args [Float] :confirm_timeout Segundos a esperar el confirm. `nil` espera indefinidamente.
     # @option args [Boolean] :nack_raise Override per-request del flag
     #   `BugBunny.configuration.nack_raise`. Si `nil` (default), se usa la configuración global.
+    # @option args [Boolean] :return_raise Override per-request del flag
+    #   `BugBunny.configuration.return_raise`. Si `nil` (default), se usa la configuración global.
+    #   Requiere `mandatory: true` y `confirmed: true` para tener efecto — sino se emite un
+    #   warning y el flag se ignora.
     # @yield [req] Bloque para configurar el objeto Request.
     # @return [Hash] `{ 'status' => 202, 'body' => nil }`.
     # @raise [BugBunny::RequestTimeout] Si `confirmed: true` y el broker no confirma a tiempo.
     # @raise [BugBunny::PublishNacked] Si `confirmed: true`, el broker NACKea, y `nack_raise` resuelto es true.
+    # @raise [BugBunny::PublishUnroutable] Si `confirmed: true`, `mandatory: true`, el broker retorna el
+    #   mensaje como no-ruteable, y `return_raise` resuelto es true.
     def publish(url, **args)
       send(url, **args) do |req|
         req.delivery_mode = args[:confirmed] ? :confirmed : :publish
@@ -120,6 +147,10 @@ module BugBunny
       # Configuración del usuario (bloque específico por request)
       yield req if block_given?
 
+      # Check post-block: el block API puede setear delivery_mode/mandatory después
+      # de los keyword args. Evaluamos el warning sobre el estado final del Request.
+      warn_return_raise_misuse(req)
+
       # Ejecución dentro del Pool.
       # Session y Producer se reutilizan por slot de conexión (ver #session_for / #producer_for).
       @pool.with do |conn|
@@ -148,12 +179,16 @@ module BugBunny
 
     # Mapea los argumentos generales (no específicos de Publisher Confirms) sobre el Request.
     #
+    # Usa `args.key?` en lugar de truthy check para que `persistent: false`,
+    # `priority: 0` u otros valores falsy explícitos del caller sean honrados
+    # (no se filtran como si no hubieran sido pasados).
+    #
     # @param req [BugBunny::Request]
     # @param args [Hash]
     # @return [void]
     def apply_args(req, args)
       REQUEST_ATTRS.each do |key|
-        req.public_send("#{key}=", args[key]) if args[key]
+        req.public_send("#{key}=", args[key]) if args.key?(key)
       end
       req.headers.merge!(args[:headers]) if args[:headers]
     end
@@ -179,6 +214,33 @@ module BugBunny
       req.mandatory       = args[:mandatory]       if args.key?(:mandatory)
       req.confirm_timeout = args[:confirm_timeout] if args.key?(:confirm_timeout)
       req.nack_raise      = args[:nack_raise]      if args.key?(:nack_raise)
+      req.return_raise    = args[:return_raise]    if args.key?(:return_raise)
+    end
+
+    # Emite un warning si el Request final tiene `return_raise: true` pero le falta
+    # `delivery_mode == :confirmed` o `mandatory: true`. El flag requiere ambos para
+    # tener efecto: sin confirmed no hay synchronization point sobre el cual levantar,
+    # y sin mandatory el broker nunca retorna.
+    #
+    # Se evalúa sobre el Request post-block (no sobre args) para no producir falsos
+    # positivos cuando el caller usa el block API para setear `req.delivery_mode` o
+    # `req.mandatory` después de los keyword args.
+    #
+    # Solo warnea cuando `request.return_raise` fue explícitamente `true` por request —
+    # ignora el default global (que también puede ser `true`) para no inundar logs en
+    # publishes regulares sin mandatory.
+    #
+    # @param request [BugBunny::Request]
+    # @return [void]
+    def warn_return_raise_misuse(request)
+      return unless request.return_raise == true
+      return if request.delivery_mode == :confirmed && request.mandatory
+
+      BugBunny.configuration.logger&.warn do
+        'component=bug_bunny event=client.return_raise_ignored ' \
+          'reason=requires_confirmed_and_mandatory ' \
+          "delivery_mode=#{request.delivery_mode} mandatory=#{!!request.mandatory}"
+      end
     end
 
     # Recupera o crea la Session asociada al slot de conexión dado.

data/lib/bug_bunny/configuration.rb

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

data/lib/bug_bunny/exception.rb

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

data/lib/bug_bunny/producer.rb

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

data/lib/bug_bunny/request.rb

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