bug_bunny 4.13.0 → 4.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1bcda002a00d8ebc93786a496f8649d43e82d58645aa2b77e3d9b72044e7e07
-  data.tar.gz: b49f4c724ae39592d6c1a1774873fc8b272cf853688d998cbfb2f22d721d3589
+  metadata.gz: 67e58763b6f088c44e17121922ecb618c9ccef8738096d534c578eea021c5f94
+  data.tar.gz: 47fe7485dd056e9ffb8a7e5268b97e4d0173e0441984506b5528f5c43643da7a
 SHA512:
-  metadata.gz: 3b16b769d198b82f5455294bfca2c9c157f6dc7cb34a4cceedf9441d11677035a51c97b1d29e7cb59994d7d954072062919c24958ac340d9da018dded6c9e199
-  data.tar.gz: fdea4a6b6d49dd032787c520e5516045812d94afa5ba4dc8a6ff818e7e89bc6263f92877266e82a40a3789907a2aafd9727ecd2770949511b3e8584915cc87ab
+  metadata.gz: f0a5927c4a4a450b414ee38ffbc25a0a97a80b2678d32a19d524a51367572f7b5e2935e29a81bf9afbdd2cfb0b634e9b60a322b828ff14ba0f79e60982148723
+  data.tar.gz: e66726447226ceb96f2d3b81dd759209fd8e54e7ea67bb85870cc805e44747e81f8121a821fd7a6fa65435ae3ba95e3cd62631ef0687fa0543f29848e21f4682

data/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## [4.16.0] - 2026-05-13
+
+### Cambios de comportamiento (semi-breaking)
+- **`DEFAULT_QUEUE_OPTIONS` cambió a `{ exclusive: false, durable: true, auto_delete: false }`** (#42). En versiones previas el default era `{ exclusive: false, durable: false, auto_delete: true }` — la combinación `transient_nonexcl_queues` que **RabbitMQ 4.x deprecó por default**: el broker rechaza la declaración matando la conexión. El nuevo default es el patrón "queue compartida duradera": sobrevive restart del broker, múltiples consumers pueden compartirla, no se elimina cuando se desconecta el último consumer. Esto matchea cómo la mayoría de servicios Wispro ya configuran sus queues explícitamente.
+
+  **Para restaurar el comportamiento anterior** (servicios sobre RabbitMQ 3.x con queues legacy efímeras pre-existentes):
+
+  ```ruby
+  BugBunny.configure do |c|
+    c.queue_options = { exclusive: false, durable: false, auto_delete: true }
+  end
+  ```
+
+  **Síntoma si se necesita override y no se aplicó:** `Bunny::PreconditionFailed - inequivalent arg 'durable' for queue 'foo'`. Indica que la queue existe en el broker con `durable: false` pero el nuevo default intenta declararla con `durable: true`. Aplicar el override de arriba o borrar manualmente la queue legacy en el broker.
+
+### Documentación
+- README + SKILL.md actualizados con sección "queue_options recomendadas" cubriendo patrones worker-pool (default nuevo) y single-instance (`exclusive: true`).
+
+## [4.15.0] - 2026-05-13
+
+### Nuevas funcionalidades
+- **`return_raise` flag para mandatory + basic.return (#38):** `Producer#confirmed` ahora levanta `BugBunny::PublishUnroutable` cuando el broker retorna un mensaje publicado con `mandatory: true` que no pudo rutearse a ninguna cola. Espejo simétrico de `nack_raise`/`PublishNacked`. La excepción expone `path`, `exchange`, `routing_key`, `reply_code`, `reply_text` y `correlation_id`. Internamente la gema implementa el bridge cross-thread (reader thread → publish thread) que antes cada caller tenía que replicar manualmente con `Concurrent::Map` + lambda. Configurable globalmente vía `BugBunny.configuration.return_raise` (default `true`) y por request via `client.publish(..., return_raise: false)`. El callback global `on_return` se sigue invocando antes del raise. — @Gabriel
+
+### Cambios de comportamiento (semi-breaking)
+- **Default `return_raise: true`:** Publicaciones con `confirmed: true, mandatory: true` que reciben `basic.return` del broker ahora levantan excepción por default. En 4.14.0 el return solo se logueaba (o invocaba el callback `on_return`) y la llamada retornaba 202 silenciosamente — ocultando pérdida de mensajes. Para mantener el comportamiento previo: `BugBunny.configuration.return_raise = false` o `return_raise: false` per request. El flag es **inerte cuando `mandatory: false`** — sin mandatory el broker nunca emite return.
+
+### Detalles internos
+- `Producer#confirmed` auto-asigna `correlation_id` (UUID) cuando falta y `mandatory + return_raise` están activos — la correlación bridge↔return depende del cid.
+- Nuevo bound de espera `Producer::RETURN_RACE_WINDOW_S = 0.05` tras un ack positivo: tolera el race scheduling entre reader thread (donde Bunny invoca `on_return`) y publish thread (donde se devuelve `wait_for_confirms`). AMQP garantiza orden wire (return precede a ack), pero defendemos contra GVL.
+- `Session` ahora mantiene un registry interno `@pending_returns` (`Concurrent::Map` de cid → `{event, info}`). `handle_broker_return` setea el event *antes* de invocar el user_cb global — una excepción del callback no impide el raise en el caller.
+- Nuevo evento de log `producer.publish_unroutable` (WARN) con `path`, `exchange`, `routing_key`, `reply_code`, `reply_text`, `messaging_message_id`. Se emite antes de levantar `PublishUnroutable`.
+- Nuevo evento de log `client.return_raise_ignored` (WARN) cuando se pasa `return_raise: true` sin `confirmed: true` o sin `mandatory: true` — el flag se ignora.
+
+## [4.14.0] - 2026-05-12
+
+### Nuevas funcionalidades
+- **Duraciones medidas internamente en el Producer:** BugBunny ahora emite `duration_s` automáticamente en los eventos del publisher siguiendo las [OpenTelemetry metric semantic conventions](https://opentelemetry.io/docs/specs/semconv/general/metrics/) (`Float` en segundos). El código de aplicación ya no necesita envolver `client.publish` con `Process.clock_gettime`. — @Gabriel
+  - `producer.published` (INFO): `duration_s` del `basic_publish` (TCP enqueue al broker, sin esperar ACK).
+  - `producer.confirmed` (INFO): tres duraciones desglosadas — `publish_duration_s`, `confirm_duration_s` (espera de `wait_for_confirms`) y `duration_s` total. Útil para distinguir latencia de red vs latencia del confirm policy del broker.
+  - `producer.rpc_response_received`: ahora incluye `duration_s` con el round-trip RPC completo (publish + procesamiento remoto + reply).
+
+### Cambios de comportamiento
+- **`producer.rpc_response_received` promovido de DEBUG a INFO.** No es breaking de API pero aumenta el volumen de logs en clientes RPC. Si el cambio impacta tu pipeline de observabilidad, filtralo por nivel.
+
+### Documentación
+- README + `skill/SKILL.md` + `skill/references/client-middleware.md` actualizados con el catálogo completo de eventos de log emitidos por la gema y la tabla de qué mide cada `duration_s`. Mensaje explícito en ambas audiencias (humana + agente) advirtiendo no duplicar la medición en código de aplicación.
+
 ## [4.13.0] - 2026-05-11
 
 ### Nuevas funcionalidades

data/README.md

@@ -129,7 +129,11 @@ BugBunny.configure do |config|
   config.read_timeout        = 10
   config.write_timeout       = 10
 
-  # AMQP defaults applied to all exchanges and queues
+  # AMQP defaults applied to all exchanges and queues.
+  # Gem defaults (since 4.16):
+  #   DEFAULT_EXCHANGE_OPTIONS = { durable: false, auto_delete: false }
+  #   DEFAULT_QUEUE_OPTIONS    = { exclusive: false, durable: true, auto_delete: false }
+  # Override only if your service needs different infrastructure semantics.
   config.exchange_options = { durable: true }
   config.queue_options    = { durable: true }
 
@@ -142,7 +146,13 @@ BugBunny.configure do |config|
   # Health check file for Kubernetes / Docker Swarm liveness probes
   config.health_check_file = '/tmp/bug_bunny_health'
 
+  # Publisher Confirms — fail-loud defaults (both flags default to true).
+  # Set to false to restore legacy log-only behavior.
+  config.nack_raise   = true   # broker NACK → raise BugBunny::PublishNacked
+  config.return_raise = true   # broker basic.return (mandatory) → raise BugBunny::PublishUnroutable
+
   # Callback invoked when the broker returns an unroutable mandatory message.
+  # Runs BEFORE PublishUnroutable is raised (if return_raise is true).
   # When nil (default), BugBunny logs the return as `session.broker_return` at :warn.
   # Signature: ->(return_info, properties, body) { ... }
   config.on_return = ->(return_info, _props, body) {
@@ -220,11 +230,26 @@ client.publish('acct.start',
 | `confirmed` | Boolean | `false` | Block until `wait_for_confirms` returns. |
 | `mandatory` | Boolean | `false` | Broker returns the message if it cannot be routed to any queue. Requires `confirmed: true` to be useful. |
 | `confirm_timeout` | Float | `nil` | Seconds to wait for the broker ACK. Raises `BugBunny::RequestTimeout` if exceeded. |
-| `nack_raise` | Boolean | `nil` | Per-request override of `config.nack_raise`. When `nil`, falls back to the global flag. |
+| `nack_raise` | Boolean | `nil` | Per-request override of `config.nack_raise`. When `nil`, falls back to the global flag (default `true`). |
+| `return_raise` | Boolean | `nil` | Per-request override of `config.return_raise`. When `nil`, falls back to the global flag (default `true`). Requires `confirmed: true` and `mandatory: true` to take effect. |
+
+**Two broker signals, two exceptions:**
 
-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.
+| 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` |
 
-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.
+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
+```
+
+When `mandatory: false` (the default), `return_raise` is inert — the broker never emits `basic.return` without mandatory.
 
 ---
 
@@ -252,11 +277,27 @@ BugBunny implementa de forma nativa las [OpenTelemetry semantic conventions for
 Todos los eventos internos se emiten como logs `key=value` compatibles con Datadog, CloudWatch, ELK y ExisRay.
 
 ```
+component=bug_bunny event=producer.publish method=POST path=acct/publish messaging_destination_name=acct_x messaging_routing_key=acct.start.42
+component=bug_bunny event=producer.published method=POST path=acct/publish routing_key=acct.start.42 messaging_message_id=corr-1 duration_s=0.000812
+component=bug_bunny event=producer.confirmed method=POST path=acct/publish routing_key=acct.start.42 publish_duration_s=0.000812 confirm_duration_s=0.012 duration_s=0.013
+component=bug_bunny event=producer.rpc_response_received method=GET path=users/42 duration_s=0.034 messaging_operation=receive
 component=bug_bunny event=consumer.message_processed status=200 duration_s=0.012 messaging_operation=process controller=NodesController action=show
 component=bug_bunny event=consumer.execution_error error_class=RuntimeError error_message="..." duration_s=0.003
 component=bug_bunny event=consumer.connection_error attempt_count=2 retry_in_s=10 error_message="..."
 ```
 
+### Duraciones medidas internamente
+
+BugBunny mide y emite duraciones automáticamente — **no es necesario envolver llamadas a `client.publish` con `Process.clock_gettime` en el código de aplicación**. Las unidades siguen las [OpenTelemetry metric semantic conventions](https://opentelemetry.io/docs/specs/semconv/general/metrics/) (`s`, segundos como `Float`).
+
+| Evento | Duración | Mide |
+|---|---|---|
+| `producer.published` | `duration_s` | Solo el `basic_publish` (TCP enqueue al broker). |
+| `producer.confirmed` | `publish_duration_s` + `confirm_duration_s` + `duration_s` (total) | Publish + espera de ACK del broker. |
+| `producer.rpc_response_received` | `duration_s` | Round-trip RPC completo (publish + procesamiento remoto + reply). |
+| `consumer.message_processed` | `duration_s` | Procesamiento del mensaje (router + controller + reply). |
+| `consumer.execution_error` | `duration_s` | Tiempo transcurrido hasta el error. |
+
 Las claves sensibles (`password`, `token`, `secret`, `api_key`, `authorization`, etc.) se filtran automáticamente a `[FILTERED]` en toda la salida de logs.
 
 ---
@@ -269,9 +310,15 @@ BugBunny maps RabbitMQ responses to a semantic exception hierarchy, similar to h
 
 ```
 BugBunny::Error
+├── CommunicationError                  (network / channel failure)
+├── ConfigurationError                  (invalid config attribute)
+├── SecurityError                       (unauthorized controller resolution)
+├── PublishNacked                       (broker basic.nack on :confirmed publish)
+├── PublishUnroutable                   (broker basic.return on mandatory + :confirmed)
 ├── ClientError (4xx)
 │   ├── BadRequest (400)
 │   ├── NotFound (404)
+│   │   └── RoutingError                (consumer-side: no route for verb + path)
 │   ├── NotAcceptable (406)
 │   ├── RequestTimeout (408)
 │   ├── Conflict (409)

data/lib/bug_bunny/client.rb

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

data/lib/bug_bunny/configuration.rb

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

data/lib/bug_bunny/exception.rb

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

data/lib/bug_bunny/producer.rb

@@ -15,6 +15,13 @@ module BugBunny
   class Producer
     include BugBunny::Observability
 
+    # Bound de espera (segundos) que el publish thread aplica tras un ack positivo para
+    # tolerar el scheduling race entre reader thread (donde Bunny invoca `on_return`) y
+    # publish thread (donde se devuelve `wait_for_confirms`). AMQP garantiza que el
+    # `basic.return` precede al `basic.ack` en la wire, así que en la práctica el event
+    # ya está seteado al llegar acá; este wait es defensa contra GVL.
+    RETURN_RACE_WINDOW_S = 0.05
+
     # Inicializa el productor.
     #
     # Prepara las estructuras de concurrencia necesarias para manejar múltiples
@@ -58,16 +65,31 @@ 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)
-      publish_message(request)
+      return_listener = nil
+      return_listener = setup_return_listener(request)
+      started_at = monotonic_now
+      publish_duration = publish_message(request)
+
+      confirm_started_at = monotonic_now
       acked = wait_for_confirms!(request)
+      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 }
     rescue BugBunny::Error
       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).
@@ -90,6 +112,7 @@ module BugBunny
       future = Concurrent::IVar.new
       @pending_requests[cid] = future
 
+      started_at = monotonic_now
       begin
         fire(request)
 
@@ -101,11 +124,7 @@ module BugBunny
         raise BugBunny::RequestTimeout, "Timeout waiting for RPC: #{request.path} [#{request.method}]" if result.nil?
 
         BugBunny.configuration.on_rpc_reply&.call(result[:headers])
-
-        safe_log(:debug, 'producer.rpc_response_received',
-                 messaging_system: 'rabbitmq', messaging_operation: 'receive', messaging_message_id: cid,
-                 response_body: result[:body]&.truncate(500),
-                 response_headers: result[:headers]&.to_json&.truncate(300))
+        log_rpc_response_received(request, cid, result, started_at)
 
         parse_response(result[:body])
       ensure
@@ -119,8 +138,11 @@ module BugBunny
     # Resuelve exchange, serializa payload, logea y publica el mensaje.
     # Compartido por {#fire} y {#confirmed}.
     #
+    # Emite `producer.publish` antes y `producer.published` después con `duration_s`
+    # midiendo solo el `basic_publish` (TCP enqueue al broker, sin esperar ACK).
+    #
     # @param request [BugBunny::Request]
-    # @return [void]
+    # @return [Float] duración del publish en segundos.
     def publish_message(request)
       x = @session.exchange(
         name: request.exchange,
@@ -129,7 +151,43 @@ module BugBunny
       )
       payload = serialize_message(request.body)
       log_request(request, payload)
+
+      started_at = monotonic_now
       x.publish(payload, request.amqp_options.merge(routing_key: request.final_routing_key))
+      publish_duration = duration_s(started_at)
+
+      log_published(request, publish_duration)
+      publish_duration
+    end
+
+    # @api private
+    def log_published(request, publish_duration_s)
+      safe_log(:info, 'producer.published',
+               method: request.method.to_s.upcase, path: request.path,
+               routing_key: request.final_routing_key,
+               messaging_message_id: request.correlation_id,
+               duration_s: publish_duration_s)
+    end
+
+    # @api private
+    def log_rpc_response_received(request, cid, result, started_at)
+      safe_log(:info, 'producer.rpc_response_received',
+               method: request.method.to_s.upcase, path: request.path,
+               messaging_system: 'rabbitmq', messaging_operation: 'receive', messaging_message_id: cid,
+               duration_s: duration_s(started_at),
+               response_body: result[:body]&.truncate(500),
+               response_headers: result[:headers]&.to_json&.truncate(300))
+    end
+
+    # @api private
+    def log_confirmed(request, publish_duration_s, confirm_duration_s, started_at)
+      safe_log(:info, 'producer.confirmed',
+               method: request.method.to_s.upcase, path: request.path,
+               routing_key: request.final_routing_key,
+               messaging_message_id: request.correlation_id,
+               publish_duration_s: publish_duration_s,
+               confirm_duration_s: confirm_duration_s,
+               duration_s: duration_s(started_at))
     end
 
     # Espera la confirmación del broker con timeout opcional.
@@ -197,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.