bug_bunny 4.11.1 → 4.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc50591b1ca19df77acdb6233edef462736da631e6e81b9fa24f203ac3c67b39
-  data.tar.gz: 5abcaec4329fcda360d7b88854e249b9582ca2399203fef0e7edf2eefdde3dbc
+  metadata.gz: d1bcda002a00d8ebc93786a496f8649d43e82d58645aa2b77e3d9b72044e7e07
+  data.tar.gz: b49f4c724ae39592d6c1a1774873fc8b272cf853688d998cbfb2f22d721d3589
 SHA512:
-  metadata.gz: 29a3b9cc5385e33b3755224af8829d68f6b7a1cad08dcdeed79375004202827c7ae3c314141a39581076fb77f8d94b26a77777ca2d5c5f3f91eb91bd2460f7b9
-  data.tar.gz: 6e3ee7a4845f5ce8c3e37f1ee0624a84693692ef348b0836ae800088a1307e2ef91bfaf985be4d6a9ad28422400151316f1882c3da564aa210b3d244d659751c
+  metadata.gz: 3b16b769d198b82f5455294bfca2c9c157f6dc7cb34a4cceedf9441d11677035a51c97b1d29e7cb59994d7d954072062919c24958ac340d9da018dded6c9e199
+  data.tar.gz: fdea4a6b6d49dd032787c520e5516045812d94afa5ba4dc8a6ff818e7e89bc6263f92877266e82a40a3789907a2aafd9727ecd2770949511b3e8584915cc87ab

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [4.13.0] - 2026-05-11
+
+### Nuevas funcionalidades
+- **NACK explícito como excepción en modo `:confirmed` (#37):** `Producer#confirmed` ahora levanta `BugBunny::PublishNacked` cuando el broker NACKea la publicación, en lugar de retornar 202 silenciosamente. La excepción expone `path` y `nacked_count` para que callers críticos (auditoría, billing, RADIUS accounting) puedan escalar a HTTP 5xx y permitir retries upstream. Configurable globalmente vía `BugBunny.configuration.nack_raise` (default `true`) y por request via `client.publish(..., nack_raise: false)`. El evento `producer.confirms_nacked` se sigue logueando para observabilidad. — @Gabriel
+
+### Cambios de comportamiento (semi-breaking)
+- **Default `nack_raise: true`:** Publicaciones con `confirmed: true` que reciben NACK del broker ahora levantan excepción por default. En 4.12.0, el NACK se logueaba pero retornaba 202 igualmente — comportamiento que ocultaba pérdida de mensajes desde la perspectiva del publisher. Para mantener el comportamiento previo: `BugBunny.configuration.nack_raise = false` o `nack_raise: false` per request.
+
+## [4.12.0] - 2026-05-11
+
+### Nuevas funcionalidades
+- **`:confirmed` delivery mode con Publisher Confirms (#36):** `Client#publish(..., confirmed: true)` activa Publisher Confirms síncronos — bloquea hasta que el broker confirme la recepción del mensaje. Soporta `mandatory: true` con callback `BugBunny.configuration.on_return` para mensajes no ruteables, `confirm_timeout` opcional (vía `Concurrent::IVar` ya que Bunny 2.24 no soporta timeout nativo en `wait_for_confirms`) y logging de NACKs. Útil para eventos críticos (auditoría, billing) sin el overhead de un RPC completo. — @Gabriel
+
+### Correcciones
+- **`on_return` registrado sobre Exchange, no Channel:** El handler `basic.return` se registra ahora vía `Bunny::Exchange#on_return` (la API real de Bunny 2.24) en lugar de `Bunny::Channel#on_return`, que no existe y rompía la creación del canal con `NoMethodError: undefined method 'on_return' for an instance of Bunny::Channel`. Cada exchange se configura una sola vez por nombre; el set se resetea al recrear el canal. — @Gabriel
+
 ## [4.11.1] - 2026-04-09
 
 ### Correcciones

data/README.md

@@ -4,7 +4,7 @@
 
 RESTful messaging over RabbitMQ for Ruby microservices.
 
-BugBunny maps AMQP messages to controllers, routes, and models using the same patterns as Rails. Services communicate through RabbitMQ without HTTP coupling, with full support for synchronous RPC and fire-and-forget publishing.
+BugBunny maps AMQP messages to controllers, routes, and models using the same patterns as Rails. Services communicate through RabbitMQ without HTTP coupling, with full support for synchronous RPC, fire-and-forget publishing, and sync publisher confirms for delivery-critical events.
 
 ---
 
@@ -141,6 +141,13 @@ BugBunny.configure do |config|
 
   # Health check file for Kubernetes / Docker Swarm liveness probes
   config.health_check_file = '/tmp/bug_bunny_health'
+
+  # Callback invoked when the broker returns an unroutable mandatory message.
+  # 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) {
+    MyAlerts.publish_unroutable(rk: return_info.routing_key, body: body)
+  }
 end
 ```
 
@@ -193,6 +200,32 @@ client.publish('events', body: { type: 'user.signed_in', user_id: 42 })
 client.request('users', method: :get, params: { role: 'admin', page: 2 })
 ```
 
+### 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:
+
+```ruby
+client.publish('acct.start',
+               exchange:        'acct_events',
+               exchange_type:   'topic',
+               body:            { tenant_id: 42, plan: 'pro' },
+               confirmed:       true,
+               mandatory:       true,    # broker returns the message if no queue is bound
+               confirm_timeout: 0.5)     # seconds; nil waits forever
+# => { 'status' => 202, 'body' => nil }  # broker confirmed
+```
+
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `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. |
+
+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.
+
+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.
+
 ---
 
 ## Consumer Middleware

data/lib/bug_bunny/client.rb

@@ -14,6 +14,10 @@ module BugBunny
   #
   # @example Publicación Fire-and-Forget (POST)
   #   client.publish('logs', method: :post, body: { msg: 'Error' })
+  #
+  # @example Publicación con Publisher Confirms sincrónicos
+  #   client.publish('acct.start', exchange: 'acct_x', body: payload,
+  #                  confirmed: true, mandatory: true, confirm_timeout: 0.5)
   class Client
     # @return [ConnectionPool] El pool de conexiones subyacente a RabbitMQ.
     attr_reader :pool
@@ -21,9 +25,15 @@ module BugBunny
     # @return [BugBunny::Middleware::Stack] La pila de middlewares configurada.
     attr_reader :stack
 
-    # @return [Symbol] El modo de entrega por defecto para este cliente (:rpc o :publish).
+    # @return [Symbol] El modo de entrega por defecto para este cliente (:rpc, :publish o :confirmed).
     attr_accessor :delivery_mode
 
+    # Argumentos del cliente que se mapean 1:1 a setters del Request.
+    REQUEST_ATTRS = %i[
+      delivery_mode method body exchange exchange_type routing_key
+      timeout exchange_options queue_options params
+    ].freeze
+
     # Inicializa un nuevo cliente.
     #
     # @param pool [ConnectionPool] Pool de conexiones a RabbitMQ configurado previamente.
@@ -71,15 +81,27 @@ module BugBunny
       end
     end
 
-    # Realiza una publicación Asíncrona (Fire-and-Forget).
+    # Realiza una publicación Fire-and-Forget. Por default es asíncrono (no espera confirmación).
+    #
+    # Pasando `confirmed: true` activa Publisher Confirms síncronos: el método bloquea hasta
+    # 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 args [Hash] Mismas opciones que {#request}, excepto `:timeout`.
+    # @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.
+    #   Para procesar retornos, configurar {BugBunny.configuration.on_return}.
+    # @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.
     # @yield [req] Bloque para configurar el objeto Request.
-    # @return [void]
+    # @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.
     def publish(url, **args)
       send(url, **args) do |req|
-        req.delivery_mode = :publish
+        req.delivery_mode = args[:confirmed] ? :confirmed : :publish
         yield req if block_given?
       end
     end
@@ -93,47 +115,72 @@ module BugBunny
     # @param args [Hash] Argumentos pasados a los métodos públicos.
     # @yield [req] Bloque para configuración adicional del Request.
     def run_in_pool(url, args)
-      # 1. Builder del Request
-      req = BugBunny::Request.new(url)
-
-      # 2. Syntactic Sugar: Mapeo de argumentos a atributos del Request
-      req.delivery_mode    = delivery_mode # Default del cliente
-      req.delivery_mode    = args[:delivery_mode]    if args[:delivery_mode]
-      req.method           = args[:method]           if args[:method]
-      req.body             = args[:body]             if args[:body]
-      req.exchange         = args[:exchange]         if args[:exchange]
-      req.exchange_type    = args[:exchange_type]    if args[:exchange_type]
-      req.routing_key      = args[:routing_key]      if args[:routing_key]
-      req.timeout          = args[:timeout]          if args[:timeout]
-
-      # Inyección de opciones de infraestructura (Nivel 3 de la cascada)
-      req.exchange_options = args[:exchange_options] if args[:exchange_options]
-      req.queue_options    = args[:queue_options]    if args[:queue_options]
-
-      req.params = args[:params] if args[:params]
-      req.headers.merge!(args[:headers]) if args[:headers]
+      req = build_request(url, args)
 
-      # 3. Configuración del usuario (bloque específico por request)
+      # Configuración del usuario (bloque específico por request)
       yield req if block_given?
 
-      # 4. Ejecución dentro del Pool
+      # Ejecución dentro del Pool.
       # Session y Producer se reutilizan por slot de conexión (ver #session_for / #producer_for).
       @pool.with do |conn|
         session  = session_for(conn)
         producer = producer_for(conn, session)
 
-        # Mapeo de delivery_mode al método del productor (:rpc o :fire)
-        method_name  = req.delivery_mode == :publish ? :fire : :rpc
-
         # Onion Architecture: La acción final es llamar al Producer real.
-        final_action = ->(env) { producer.send(method_name, env) }
+        final_action = ->(env) { producer.send(producer_method_for(req.delivery_mode), env) }
+
+        @stack.build(final_action).call(req)
+      end
+    end
+
+    # Construye y completa un Request a partir de los argumentos del usuario.
+    #
+    # @param url [String] La ruta destino.
+    # @param args [Hash] Argumentos pasados a los métodos públicos.
+    # @return [BugBunny::Request] Request listo para entrar al stack de middlewares.
+    def build_request(url, args)
+      req = BugBunny::Request.new(url)
+      req.delivery_mode = delivery_mode # Default del cliente
+      apply_args(req, args)
+      apply_publisher_confirms_args(req, args)
+      req
+    end
+
+    # Mapea los argumentos generales (no específicos de Publisher Confirms) sobre el Request.
+    #
+    # @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]
+      end
+      req.headers.merge!(args[:headers]) if args[:headers]
+    end
 
-        # Construimos y ejecutamos la cadena de middlewares
-        app = @stack.build(final_action)
-        app.call(req)
+    # Mapea un delivery_mode al nombre del método correspondiente en el Producer.
+    #
+    # @param mode [Symbol] :rpc, :publish o :confirmed.
+    # @return [Symbol] :rpc, :fire o :confirmed.
+    def producer_method_for(mode)
+      case mode
+      when :publish   then :fire
+      when :confirmed then :confirmed
+      else :rpc
       end
     end
 
+    # Aplica los argumentos específicos del modo :confirmed sobre el Request.
+    #
+    # @param req [BugBunny::Request]
+    # @param args [Hash] Argumentos originales pasados al cliente.
+    # @return [void]
+    def apply_publisher_confirms_args(req, args)
+      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)
+    end
+
     # Recupera o crea la Session asociada al slot de conexión dado.
     #
     # La Session (y su canal AMQP) se almacena como ivar en el objeto `conn`.

data/lib/bug_bunny/configuration.rb

@@ -135,6 +135,33 @@ module BugBunny
     #     config.on_rpc_reply = ->(headers) { ExisRay::Tracer.hydrate(headers['X-Amzn-Trace-Id']) }
     attr_accessor :on_rpc_reply
 
+    # @return [Proc, nil] Callback invocado cuando el broker retorna un mensaje publicado con
+    #   `mandatory: true` que no pudo ser ruteado a ninguna cola. Si es `nil`, BugBunny logea
+    #   el evento como `session.broker_return` con nivel `:warn` por default.
+    #
+    #   Firma: `->(return_info, properties, body) { ... }` donde:
+    #   - `return_info` es `Bunny::ReturnInfo` (reply_code, reply_text, exchange, routing_key)
+    #   - `properties` es `Bunny::MessageProperties`
+    #   - `body` es el payload crudo como `String`
+    #
+    #   El callback se ejecuta en el hilo del consumidor interno de Bunny — debe ser rápido
+    #   y no lanzar excepciones (BugBunny las captura, pero degradan visibilidad).
+    #
+    #   @example
+    #     config.on_return = ->(ri, _props, body) {
+    #       MyAlerts.publish_unroutable(rk: ri.routing_key, body: body)
+    #     }
+    attr_accessor :on_return
+
+    # @return [Boolean] Si `true` (default), {BugBunny::Producer#confirmed} levanta
+    #   {BugBunny::PublishNacked} cuando el broker NACKea la publicación. Si `false`,
+    #   el NACK solo se logea como `producer.confirms_nacked` y la llamada retorna
+    #   `{ 'status' => 202 }` (modo legacy).
+    #
+    #   El valor puede sobreescribirse por request pasando `nack_raise:` en
+    #   `Client#publish`.
+    attr_accessor :nack_raise
+
     # @!endgroup
 
     # Inicializa la configuración con valores por defecto seguros.
@@ -176,8 +203,7 @@ module BugBunny
       @queue_options = {}
 
       @consumer_middlewares = ConsumerMiddleware::Stack.new
-      @rpc_reply_headers = nil
-      @on_rpc_reply = nil
+      init_callback_defaults
     end
 
     # Construye la URL de conexión AMQP basada en los atributos configurados.
@@ -204,6 +230,17 @@ module BugBunny
 
     private
 
+    # Defaults para callbacks y flags relacionados con publish/RPC.
+    # Extraído de {#initialize} para mantener el ABC size dentro de los límites.
+    #
+    # @return [void]
+    def init_callback_defaults
+      @rpc_reply_headers = nil
+      @on_rpc_reply = nil
+      @on_return = nil
+      @nack_raise = true
+    end
+
     def validate_required!(attr, value, rules)
       return unless rules[:required]
       return unless value.nil? || (value.is_a?(String) && value.empty?)

data/lib/bug_bunny/exception.rb

@@ -19,6 +19,37 @@ module BugBunny
   # Protege contra vulnerabilidades de RCE validando la herencia de las clases enrutadas.
   class SecurityError < Error; end
 
+  # Error lanzado cuando el broker responde NACK a una publicación en modo `:confirmed`.
+  #
+  # Un NACK significa que el broker rechazó explícitamente el mensaje (ej: política de
+  # confirms interna, disk full, replicación insuficiente). El mensaje no fue aceptado
+  # y se considera no entregado — equivalente a un fallo de transporte desde la
+  # perspectiva del publisher.
+  #
+  # Se levanta por default desde {BugBunny::Producer#confirmed}. Para opt-out,
+  # configurar `BugBunny.configuration.nack_raise = false` o pasar
+  # `nack_raise: false` por request.
+  #
+  # @example
+  #   rescue BugBunny::PublishNacked => e
+  #     e.path         # => 'acct.start'
+  #     e.nacked_count # => 1
+  class PublishNacked < Error
+    # @return [String] La ruta del request cuyo publish fue NACKeado.
+    attr_reader :path
+
+    # @return [Integer] Cantidad de mensajes NACKeados según `Bunny::Channel#nacked_set`.
+    attr_reader :nacked_count
+
+    # @param path [String] Ruta lógica del request (ej: 'acct.start').
+    # @param nacked_count [Integer] Cantidad de NACKs reportados por el broker.
+    def initialize(path:, nacked_count:)
+      @path = path
+      @nacked_count = nacked_count
+      super("broker NACK on path=#{path} (nacked=#{nacked_count})")
+    end
+  end
+
   # ==========================================
   # Categoría: Errores del Cliente (4xx)
   # ==========================================

data/lib/bug_bunny/producer.rb

@@ -38,24 +38,38 @@ module BugBunny
     # @param request [BugBunny::Request] Objeto con la configuración del envío (body, exchange_options, etc).
     # @return [Hash] Un hash de éxito simbólico ({ 'status' => 202 }).
     def fire(request)
-      # Obtenemos el exchange pasando las opciones específicas del request para la fusión en cascada
-      x = @session.exchange(
-        name: request.exchange,
-        type: request.exchange_type,
-        opts: request.exchange_options
-      )
-
-      payload = serialize_message(request.body)
-      opts = request.amqp_options
-
-      log_request(request, payload)
-
-      x.publish(payload, opts.merge(routing_key: request.final_routing_key))
-
+      publish_message(request)
       # Devolvemos un hash para evitar NoMethodError en el cliente (que espera una respuesta tipo Hash)
       { 'status' => 202, 'body' => nil }
     end
 
+    # Envía un mensaje con Publisher Confirms síncronos (Fire-and-Forget confirmado).
+    #
+    # Publica el mensaje y bloquea el hilo actual hasta que el broker confirme su recepción
+    # vía `wait_for_confirms`. Soporta `mandatory: true` con callback `on_return` para
+    # mensajes que no pudieron rutearse.
+    #
+    # A diferencia de {#rpc} (que espera la respuesta de un Consumer remoto), aquí solo se
+    # espera el ACK del propio broker — no hay round-trip al servicio destino.
+    #
+    # @param request [BugBunny::Request] Request con `mandatory`, `confirm_timeout`, `nack_raise`
+    #   y/o `on_return` opcionales.
+    # @return [Hash] `{ 'status' => 202, 'body' => nil }` si el broker confirmó la recepción.
+    # @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::CommunicationError] Si el canal AMQP falla durante la publicación o confirm.
+    def confirmed(request)
+      publish_message(request)
+      acked = wait_for_confirms!(request)
+      handle_confirm_result(request, acked)
+      { 'status' => 202, 'body' => nil }
+    rescue BugBunny::Error
+      raise
+    rescue StandardError => e
+      raise BugBunny::CommunicationError, "Publisher confirms failed: #{e.message}"
+    end
+
     # Envía un mensaje y bloquea el hilo actual esperando una respuesta (RPC).
     #
     # Implementa el mecanismo "Direct Reply-to" de RabbitMQ (`amq.rabbitmq.reply-to`).
@@ -102,6 +116,87 @@ module BugBunny
 
     private
 
+    # Resuelve exchange, serializa payload, logea y publica el mensaje.
+    # Compartido por {#fire} y {#confirmed}.
+    #
+    # @param request [BugBunny::Request]
+    # @return [void]
+    def publish_message(request)
+      x = @session.exchange(
+        name: request.exchange,
+        type: request.exchange_type,
+        opts: request.exchange_options
+      )
+      payload = serialize_message(request.body)
+      log_request(request, payload)
+      x.publish(payload, request.amqp_options.merge(routing_key: request.final_routing_key))
+    end
+
+    # Espera la confirmación del broker con timeout opcional.
+    # Bunny 2.24 no soporta timeout nativo en `wait_for_confirms`, así que delegamos
+    # la espera a un hilo auxiliar y usamos `Concurrent::IVar#value(timeout)` como reloj.
+    #
+    # @param request [BugBunny::Request]
+    # @raise [BugBunny::RequestTimeout] Si el broker no confirma a tiempo.
+    # @return [Boolean] true si todas las confirmaciones fueron positivas.
+    def wait_for_confirms!(request)
+      timeout = request.confirm_timeout
+      return @session.channel.wait_for_confirms if timeout.nil?
+
+      ivar = Concurrent::IVar.new
+      Thread.new do
+        ivar.set(@session.channel.wait_for_confirms)
+      rescue StandardError => e
+        ivar.fail(e)
+      end
+
+      result = ivar.value(timeout)
+      return result if ivar.complete?
+
+      raise BugBunny::RequestTimeout,
+            "Timeout (#{timeout}s) waiting for publisher confirms: #{request.path}"
+    end
+
+    # Procesa el resultado de `wait_for_confirms`.
+    #
+    # Si el broker NACKeó (`acked == false`), logea el evento `producer.confirms_nacked`
+    # y opcionalmente levanta {BugBunny::PublishNacked} según el flag `nack_raise`
+    # resuelto desde el request o la configuración global.
+    #
+    # @param request [BugBunny::Request]
+    # @param acked [Boolean] Resultado de `wait_for_confirms` (true = todos los confirms positivos).
+    # @raise [BugBunny::PublishNacked] Si hay NACK y `nack_raise?` es true.
+    # @return [void]
+    def handle_confirm_result(request, acked)
+      return if acked
+
+      count = nacked_count
+      safe_log(:warn, 'producer.confirms_nacked', count: count, path: request.path)
+      return unless nack_raise?(request)
+
+      raise BugBunny::PublishNacked.new(path: request.path, nacked_count: count)
+    end
+
+    # Cuenta los delivery tags NACKeados reportados por el canal.
+    #
+    # @return [Integer]
+    def nacked_count
+      ch = @session.channel
+      return 0 unless ch.respond_to?(:nacked_set)
+
+      ch.nacked_set&.size || 0
+    end
+
+    # Resuelve el flag `nack_raise` con prioridad request > configuración global.
+    #
+    # @param request [BugBunny::Request]
+    # @return [Boolean]
+    def nack_raise?(request)
+      return request.nack_raise unless request.nack_raise.nil?
+
+      BugBunny.configuration.nack_raise
+    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

@@ -19,9 +19,16 @@ module BugBunny
   # @attr routing_key [String] La routing key específica. Si es nil, se usará {#path}.
   # @attr timeout [Integer] Tiempo máximo en segundos para timeout RPC.
   #
-  # @attr delivery_mode [Symbol] El modo de entrega (:rpc o :publish).
+  # @attr delivery_mode [Symbol] El modo de entrega (:rpc, :publish o :confirmed).
   # @attr exchange_options [Hash] Opciones específicas para la declaración del Exchange en esta petición.
   # @attr queue_options [Hash] Opciones específicas para la declaración de la Cola en esta petición.
+  # @attr mandatory [Boolean] Si `true`, el mensaje debe ser ruteable o el broker lo retorna.
+  #   Solo aplica en modo :confirmed. El handler de retornos se configura globalmente
+  #   vía {BugBunny.configuration.on_return}.
+  # @attr confirm_timeout [Float, nil] Segundos máximos a esperar el `wait_for_confirms`.
+  #   `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.
   class Request
     attr_accessor :body, :headers, :params, :path, :method, :exchange, :exchange_type, :routing_key, :timeout,
                   :delivery_mode, :queue_options
@@ -29,6 +36,9 @@ module BugBunny
     # Configuración de Infraestructura Específica
     attr_accessor :exchange_options
 
+    # Publisher Confirms (delivery_mode = :confirmed)
+    attr_accessor :mandatory, :confirm_timeout, :nack_raise
+
     # Metadatos AMQP Estándar
     attr_accessor :app_id, :content_type, :content_encoding, :priority,
                   :timestamp, :expiration, :persistent, :reply_to,
@@ -51,6 +61,11 @@ module BugBunny
       # Inicialización de opciones de infraestructura para evitar errores de nil durante el merge.
       @exchange_options = {}
       @queue_options = {}
+
+      # Defaults para Publisher Confirms (modo :confirmed)
+      @mandatory = false
+      @confirm_timeout = nil
+      @nack_raise = nil
     end
 
     # Combina el path con los params como query string.
@@ -114,7 +129,8 @@ module BugBunny
         persistent: persistent,
         headers: final_headers,
         reply_to: reply_to,
-        correlation_id: correlation_id
+        correlation_id: correlation_id,
+        mandatory: (true if mandatory)
       }.compact
     end
   end

data/lib/bug_bunny/session.rb

@@ -35,6 +35,7 @@ module BugBunny
       @channel = nil
       @channel_mutex = Mutex.new
       @logger = BugBunny.configuration.logger
+      @configured_returns = {}
     end
 
     # Obtiene el canal actual o crea uno nuevo si es necesario.
@@ -80,7 +81,9 @@ module BugBunny
                     .merge(opts)
 
       # public_send permite llamar a :topic, :direct, etc. dinámicamente según el tipo
-      channel.public_send(type.to_s, name.to_s, merged_opts)
+      x = channel.public_send(type.to_s, name.to_s, merged_opts)
+      register_on_return!(x) if @publisher_confirms
+      x
     end
 
     # Factory method para declarar o recuperar una Cola aplicando la cascada de configuración.
@@ -108,6 +111,7 @@ module BugBunny
       @channel_mutex.synchronize do
         @channel&.close if @channel&.open?
         @channel = nil
+        @configured_returns.clear
       end
     end
 
@@ -119,6 +123,7 @@ module BugBunny
     # @raise [BugBunny::CommunicationError] Si falla la creación del canal.
     def create_channel!
       @channel = @connection.create_channel
+      @configured_returns.clear
 
       @channel.confirm_select if @publisher_confirms
 
@@ -127,6 +132,50 @@ module BugBunny
       raise BugBunny::CommunicationError, "Failed to create channel: #{e.message}"
     end
 
+    # Registra el handler `basic.return` sobre el `Bunny::Exchange` indicado.
+    #
+    # Bunny dispatcha `basic.return` por exchange (no por canal): el callback se setea
+    # con `Exchange#on_return`. Como cada `Session#exchange` resuelve la misma instancia
+    # cacheada en el canal, registramos una sola vez por nombre.
+    #
+    # - Si `BugBunny.configuration.on_return` está definido, lo invoca.
+    # - Sino, logea el retorno como `session.broker_return` con nivel `:warn`.
+    #
+    # @param exchange [Bunny::Exchange] Exchange recién resuelto vía cascada.
+    # @return [void]
+    def register_on_return!(exchange)
+      key = exchange.name.to_s
+      return if key.empty? || @configured_returns[key]
+
+      exchange.on_return do |return_info, properties, body|
+        handle_broker_return(return_info, properties, body)
+      end
+      @configured_returns[key] = true
+    end
+
+    # Procesa un evento `basic.return` del broker. Nunca propaga excepciones del callback
+    # de usuario para no romper el hilo de I/O de Bunny.
+    #
+    # @param return_info [Bunny::ReturnInfo]
+    # @param properties [Bunny::MessageProperties]
+    # @param body [String]
+    # @return [void]
+    def handle_broker_return(return_info, properties, body)
+      user_cb = BugBunny.configuration.on_return
+      if user_cb
+        user_cb.call(return_info, properties, body)
+      else
+        safe_log(:warn, 'session.broker_return',
+                 reply_code: return_info.reply_code,
+                 reply_text: return_info.reply_text,
+                 exchange: return_info.exchange,
+                 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.
     # Si está cerrada, intenta reconectarla (Reconexión Transparente).
     #

data/lib/bug_bunny/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BugBunny
-  VERSION = '4.11.1'
+  VERSION = '4.13.0'
 end