bug_bunny 4.11.1 → 4.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc50591b1ca19df77acdb6233edef462736da631e6e81b9fa24f203ac3c67b39
-  data.tar.gz: 5abcaec4329fcda360d7b88854e249b9582ca2399203fef0e7edf2eefdde3dbc
+  metadata.gz: 0e38ff38727e34da253f669937054e58f4bda0d5a42ce270cc9ac1e7853d8feb
+  data.tar.gz: 47b090304aaf7743addd2136c963d82ea8fd67bb82a17aad8958551047b79015
 SHA512:
-  metadata.gz: 29a3b9cc5385e33b3755224af8829d68f6b7a1cad08dcdeed79375004202827c7ae3c314141a39581076fb77f8d94b26a77777ca2d5c5f3f91eb91bd2460f7b9
-  data.tar.gz: 6e3ee7a4845f5ce8c3e37f1ee0624a84693692ef348b0836ae800088a1307e2ef91bfaf985be4d6a9ad28422400151316f1882c3da564aa210b3d244d659751c
+  metadata.gz: 1811143e41e170668c68f8a4b57721c4e9e6111145c253f62e09c5653027e75ee32d6432ac950a54b80a5e4f282ca1a64f184535935c5b1dad7f8df4bac12593
+  data.tar.gz: b896459d25cea7925eaa3a010aa85cd5bcd302ab6f4551eb5b6d4cad554f4478050476e7cd9a4980590343d6a65e9822b10a7f864378117778b543f665ce9eb2

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [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,29 @@ 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. |
+
+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,24 @@ 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.
     # @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.
     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 +112,71 @@ 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)
+    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,24 @@ 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
+
     # @!endgroup
 
     # Inicializa la configuración con valores por defecto seguros.
@@ -178,6 +196,7 @@ module BugBunny
       @consumer_middlewares = ConsumerMiddleware::Stack.new
       @rpc_reply_headers = nil
       @on_rpc_reply = nil
+      @on_return = nil
     end
 
     # Construye la URL de conexión AMQP basada en los atributos configurados.

data/lib/bug_bunny/producer.rb

@@ -38,24 +38,35 @@ 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` 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::CommunicationError] Si el canal AMQP falla durante la publicación o confirm.
+    def confirmed(request)
+      publish_message(request)
+      wait_for_confirms!(request)
+      log_nacks_if_any(request)
+      { '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 +113,63 @@ 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
+
+    # Logea las nack-eadas del canal si las hay.
+    # NACK no es un error fatal: el broker rechazó rutear (ej. confirm policy interna),
+    # pero el mensaje no se perdió silenciosamente — queda en el set para auditoría.
+    #
+    # @param request [BugBunny::Request]
+    # @return [void]
+    def log_nacks_if_any(request)
+      ch = @session.channel
+      return unless ch.respond_to?(:nacked_set)
+
+      nacked = ch.nacked_set
+      return if nacked.nil? || nacked.empty?
+
+      safe_log(:warn, 'producer.confirms_nacked', count: nacked.size, path: request.path)
+    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,14 @@ 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.
   class Request
     attr_accessor :body, :headers, :params, :path, :method, :exchange, :exchange_type, :routing_key, :timeout,
                   :delivery_mode, :queue_options
@@ -29,6 +34,9 @@ module BugBunny
     # Configuración de Infraestructura Específica
     attr_accessor :exchange_options
 
+    # Publisher Confirms (delivery_mode = :confirmed)
+    attr_accessor :mandatory, :confirm_timeout
+
     # Metadatos AMQP Estándar
     attr_accessor :app_id, :content_type, :content_encoding, :priority,
                   :timestamp, :expiration, :persistent, :reply_to,
@@ -51,6 +59,10 @@ 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
     end
 
     # Combina el path con los params como query string.
@@ -114,7 +126,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.12.0'
 end

data/skill/SKILL.md

@@ -15,6 +15,9 @@ Skill de conocimiento completo sobre BugBunny. Consultame para cualquier pregunt
 **Session** — `BugBunny::Session` envuelve canales de Bunny con thread-safety y double-checked locking.
 **RPC** — Patrón síncrono que usa la pseudo-cola `amq.rabbitmq.reply-to` para respuestas sin crear queues temporales.
 **Fire-and-Forget** — Patrón asíncrono donde el producer publica y continúa sin esperar respuesta. Retorna `{ 'status' => 202 }`.
+**Publisher Confirms** — Extensión de RabbitMQ que confirma al publisher que el broker recibió el mensaje. BugBunny lo expone como `confirmed: true` en `Client#publish`: el publish bloquea hasta `wait_for_confirms`. NACK no es fatal; se logea pero el método retorna 202.
+**Mandatory** — Flag de `basic.publish` que pide al broker retornar el mensaje al publisher si no es ruteable a ninguna cola. Se procesa via `basic.return` (no es respuesta del request).
+**basic.return** — Evento asincrónico que Bunny dispatcha por exchange (`Bunny::Exchange#on_return`). BugBunny registra un handler único por nombre de exchange al resolverlo en `Session#exchange` y lo delega a `Configuration#on_return` o al default que logea.
 **Resource** — ORM tipo ActiveRecord que mapea operaciones CRUD a llamadas AMQP.
 **Consumer** — Worker bloqueante que despacha mensajes a controladores mediante un Router.
 **Connection Pool** — Pool de conexiones (`connection_pool` gem) que comparte sessions entre threads. Cada slot cachea su `Session` y `Producer`.
@@ -59,7 +62,7 @@ Skill de conocimiento completo sobre BugBunny. Consultame para cualquier pregunt
 |---|---|
 | `BugBunny::Configuration` | Configuración global. Valida campos requeridos en `BugBunny.configure`. |
 | `BugBunny::Session` | Wrapper de canal Bunny. Declara exchanges y queues. Thread-safe con double-checked locking. |
-| `BugBunny::Producer` | Publica mensajes. Implementa RPC con `Concurrent::IVar` y direct reply-to. |
+| `BugBunny::Producer` | Publica mensajes. Implementa tres modos: `#fire` (async), `#confirmed` (sync con `wait_for_confirms`) y `#rpc` (direct reply-to + `Concurrent::IVar`). |
 | `BugBunny::Client` | API de alto nivel. Pool de conexiones y middleware stack (onion architecture). |
 | `BugBunny::Consumer` | Subscribe loop con health check. Rutea mensajes via `BugBunny.routes`. |
 | `BugBunny::ConsumerMiddleware::Stack` | Pipeline de middlewares antes de `process_message`. Thread-safe. |
@@ -126,6 +129,11 @@ BugBunny.configure do |config|
   config.rpc_reply_headers = -> { { 'X-Trace-Id' => Tracer.id } }
   config.on_rpc_reply = ->(h) { Tracer.hydrate(h['X-Trace-Id']) }
 
+  # Publisher Confirms — handler global para basic.return (mensajes mandatory no ruteados).
+  # Si es nil, BugBunny logea como `session.broker_return` con nivel :warn.
+  # Firma: ->(return_info, properties, body)
+  config.on_return = ->(ri, _props, body) { MyAlerts.unroutable(rk: ri.routing_key, body: body) }
+
   # Infraestructura (cascade level 2)
   config.exchange_options = { durable: true }
   config.queue_options = { auto_delete: false }
@@ -169,7 +177,13 @@ Genera rutas REST estándar (index, show, create, update, destroy) mapeadas a co
 
 ---
 
-## API: RPC vs Fire-and-Forget
+## API: Modos de Entrega
+
+| Modo | Espera | Uso | Método |
+|---|---|---|---|
+| `:rpc` | Reply del consumer remoto | Request-response síncrono | `client.request(...)` |
+| `:publish` | Nada | Logs, eventos best-effort | `client.publish(...)` |
+| `:confirmed` | ACK del broker (`wait_for_confirms`) | Auditoría, billing, eventos críticos | `client.publish(..., confirmed: true)` |
 
 **RPC síncrono** — Bloquea hasta respuesta. Usa `amq.rabbitmq.reply-to`. Timeout configurable.
 ```ruby
@@ -183,6 +197,18 @@ client.publish('events', method: :post, body: { type: 'order.placed' })
 # → { 'status' => 202, 'body' => nil }
 ```
 
+**Confirmed (Publisher Confirms)** — Bloquea hasta el ACK del broker. Garantía de entrega al broker (no al consumer remoto).
+```ruby
+client.publish('acct.start', exchange: 'acct_x', body: payload,
+               confirmed: true, mandatory: true, confirm_timeout: 0.5)
+# → { 'status' => 202, 'body' => nil }   # broker ACK confirmado
+# Si broker NACK: logea `producer.confirms_nacked` y retorna 202 igual (NACK ≠ pérdida).
+# Si timeout: raise BugBunny::RequestTimeout.
+# Si mandatory + no ruteable: dispara `Configuration#on_return` (default: logea `session.broker_return`).
+```
+
+`Bunny::Channel#wait_for_confirms` no soporta timeout nativo en Bunny 2.x. BugBunny lo implementa lanzando la espera en un hilo auxiliar y usando `Concurrent::IVar#value(timeout)` como reloj.
+
 ---
 
 ## FAQ

data/skill/references/client-middleware.md

@@ -7,7 +7,7 @@ API de alto nivel para publicar mensajes. Usa un pool de conexiones y una pila d
 ### Métodos Principales
 
 ```ruby
-# RPC síncrono — bloquea hasta respuesta
+# RPC síncrono — bloquea hasta respuesta del consumer
 response = client.request('users/123', method: :get, timeout: 30)
 response = client.request('users', method: :post, body: { name: 'John' })
 # → { 'status' => 200, 'body' => {...} }
@@ -16,8 +16,17 @@ response = client.request('users', method: :post, body: { name: 'John' })
 client.publish('events/user_created', method: :post, body: { user_id: 42 })
 # → { 'status' => 202, 'body' => nil }
 
-# General con bloque
-client.send(url) { |req| req.delivery_mode = :publish }
+# Publisher Confirms — bloquea hasta ACK del broker (no del consumer)
+client.publish('acct.start', exchange: 'acct_x', body: payload,
+               confirmed: true, mandatory: true, confirm_timeout: 0.5)
+# → { 'status' => 202, 'body' => nil }
+
+# General con bloque — máximo control
+client.send(url) do |req|
+  req.delivery_mode = :confirmed
+  req.mandatory = true
+  req.confirm_timeout = 1.0
+end
 ```
 
 ### Argumentos de Request
@@ -34,12 +43,15 @@ client.send(url) { |req| req.delivery_mode = :publish }
 | `routing_key` | String | path | Override de routing key |
 | `exchange_options` | Hash | {} | Cascade level 3 |
 | `queue_options` | Hash | {} | Cascade level 3 |
+| `confirmed` | Boolean | `false` | En `Client#publish`, flipea `delivery_mode` a `:confirmed`. Bloquea hasta `wait_for_confirms`. |
+| `mandatory` | Boolean | `false` | Pide al broker retornar el mensaje si no es ruteable. Solo útil con `confirmed: true`. |
+| `confirm_timeout` | Float | `nil` | Segundos máximos a esperar el ACK. `nil` = espera indefinida. Excedido → `BugBunny::RequestTimeout`. |
 
 ## Producer (bajo nivel)
 
-El `Producer` es usado internamente por el `Client`. Implementa los dos patrones de entrega.
+El `Producer` es usado internamente por el `Client`. Implementa tres patrones de entrega.
 
-### RPC
+### RPC (`Producer#rpc`)
 
 - Usa `amq.rabbitmq.reply-to` (direct reply-to pattern).
 - Tracking de `correlation_id` en `Concurrent::Map` (thread-safe).
@@ -47,11 +59,19 @@ El `Producer` es usado internamente por el `Client`. Implementa los dos patrones
 - Double-checked locking mutex para seguridad del listener.
 - Timeout lanza `BugBunny::RequestTimeout`.
 
-### Fire-and-Forget
+### Fire-and-Forget (`Producer#fire`)
 
 - Publica en el exchange y retorna `{ 'status' => 202 }` inmediatamente.
 - Sin confirmación de procesamiento.
 
+### Confirmed (`Producer#confirmed`)
+
+- Publica y bloquea hasta `channel.wait_for_confirms` del broker.
+- Bunny 2.x **no soporta timeout** nativo en `wait_for_confirms` — BugBunny envuelve la llamada en un hilo auxiliar y usa `Concurrent::IVar#value(timeout)` como reloj. Si `confirm_timeout` expira → `BugBunny::RequestTimeout`.
+- NACK del broker no es fatal: se logea `producer.confirms_nacked` con `count` y `path`, y retorna 202 igual.
+- Si `mandatory: true` y el mensaje no es ruteable, el broker dispara `basic.return`. El handler se atacha vía `Bunny::Exchange#on_return` en `Session#exchange` la primera vez que se resuelve cada exchange (cacheado por nombre, una sola vez por canal) y delega a `Configuration#on_return` o al logger por default.
+- Errores del canal se envuelven en `BugBunny::CommunicationError`; errores `BugBunny::Error` pre-existentes se propagan sin envolver.
+
 ## Middleware Stack (Client-side, Onion Architecture)
 
 ```
@@ -135,15 +155,74 @@ req.body                  # Hash, Array, String o nil
 req.headers               # Hash custom
 req.params                # Hash query string
 req.full_path             # path + query string
-req.delivery_mode         # :rpc o :publish
+req.delivery_mode         # :rpc, :publish o :confirmed
 req.exchange              # String destino
 req.exchange_type         # 'direct', 'topic', 'fanout'
 req.correlation_id        # UUID auto-generado
 req.reply_to              # 'amq.rabbitmq.reply-to' (auto para RPC)
 req.timestamp             # Time.now.to_i
 req.content_type          # 'application/json'
+req.mandatory             # Boolean — solo modo :confirmed
+req.confirm_timeout       # Float|nil — solo modo :confirmed
 ```
 
+Cuando `mandatory == true`, `Request#amqp_options` inyecta `mandatory: true` en el hash que va a `basic_publish`.
+
+## Publisher Confirms y `basic.return`
+
+### Flujo
+
+```
+client.publish('x', confirmed: true, mandatory: true)
+   │
+   ▼
+Producer#confirmed
+   │
+   ├──> publish_message     (exchange.publish con mandatory: true)
+   │
+   ├──> wait_for_confirms!  (espera ACK del broker, con timeout opcional)
+   │
+   └──> log_nacks_if_any    (si nacked_set no está vacío → log WARN)
+
+Asíncronamente, si el broker no pudo rutear:
+   broker ──basic.return──> Exchange#on_return ──> Session handler ──> Configuration#on_return
+                                                                   └──> default: log session.broker_return WARN
+```
+
+### `Configuration#on_return`
+
+El handler se registra **una sola vez por exchange** en `Session#exchange` (cuando `publisher_confirms: true`) usando `Bunny::Exchange#on_return`. Bunny dispatcha `basic.return` por exchange, no por canal, así que el handler vive en cada `Bunny::Exchange` resuelto vía cascada. `Session` cachea los exchanges ya configurados por nombre en `@configured_returns` para no re-registrar en cada publish; el set se limpia al recrear el canal.
+
+```ruby
+BugBunny.configure do |c|
+  c.on_return = ->(return_info, properties, body) {
+    # return_info: Bunny::ReturnInfo (reply_code, reply_text, exchange, routing_key)
+    # properties:  Bunny::MessageProperties
+    # body:        String (payload crudo)
+    MyAlerts.unroutable(rk: return_info.routing_key, body: body)
+  }
+end
+```
+
+Si `on_return` es `nil` (default), BugBunny logea:
+
+```
+component=bug_bunny event=session.broker_return reply_code=312
+   reply_text="NO_ROUTE" exchange=evt_x routing_key=acct.start body_size=64
+```
+
+Excepciones del callback se capturan y se logean como `session.on_return_failed` para no romper el hilo I/O de Bunny.
+
+### Cuándo usar `:confirmed`
+
+| Escenario | Modo recomendado |
+|---|---|
+| Logs, eventos best-effort | `:publish` |
+| Auditoría, billing, eventos críticos | `:confirmed` (con `mandatory: true` si es ruteable) |
+| Request-response síncrono | `:rpc` |
+
+`:confirmed` cuesta un round-trip al broker pero **no** al consumer remoto — más rápido que RPC, con garantía de entrega al broker. NACK del broker es raro (típicamente por confirm policies internas) y no implica pérdida del mensaje.
+
 ## Cascada de Configuración (3 niveles)
 
 ```ruby

data/skills.yml

@@ -2,43 +2,28 @@ mcps:
   - github
   - clickup
 skills:
-  skill-manager:
-    repo: sequre/ai_knowledge
-    scope: local
   yard:
     repo: sequre/ai_knowledge
-    scope: local
   quality-code:
     repo: sequre/ai_knowledge
-    scope: local
   gem-release:
     repo: sequre/ai_knowledge
-    scope: local
   skill-builder:
     repo: sequre/ai_knowledge
-    scope: local
-  ai-reports:
+  matrix-element:
     repo: sequre/ai_knowledge
-    scope: local
     environment:
-      space_id: "${AI_REPORTS_SPACE_ID}"
-      bug_reports_list_id: "${AI_REPORTS_BUG_REPORTS_LIST_ID}"
-      improvements_list_id: "${AI_REPORTS_IMPROVEMENTS_LIST_ID}"
-  agent-review:
+      homeserver: "https://matrix.cloud.wispro.co"
+      auth_token: "${MATRIX_AUTH_TOKEN}"
+      rooms:
+        agents: "!VCHwQXgmXdyhhhPhoz:matrix.cloud.wispro.co"
+  skill-feedback:
+    repo: sequre/ai_knowledge
+  agent-issue:
     repo: sequre/ai_knowledge
-    scope: local
-    environment:
-      space_id: "${AGENT_REVIEW_SAPCE_ID}"
-      list_id: "${AGENT_LIST_ID}"
   documentation-writer:
     repo: github/awesome-copilot
     path: skills/documentation-writer
-    scope: local
-  find-skills:
-    repo: vercel-labs/skills
-    path: skills/find-skills
-    scope: local
   rabbitmq-expert:
     repo: martinholovsky/claude-skills-generator
     path: skills/rabbitmq-expert
-    scope: local

data/spec/support/bunny_mocks.rb

@@ -3,11 +3,47 @@
 # Stubs livianos de Bunny para specs unitarios que no necesitan RabbitMQ real.
 
 module BunnyMocks
+  # Stub mínimo de `Bunny::Exchange`: cachea el bloque pasado a `on_return`
+  # (Bunny lo invoca al recibir un `basic.return` del broker) y permite que
+  # los specs disparen retornos sintéticos vía `fire_return`.
+  class FakeExchange
+    attr_reader :name, :type, :opts
+
+    def initialize(name, type, opts = {})
+      @name = name
+      @type = type
+      @opts = opts
+    end
+
+    def on_return(&block)
+      @on_return_handler = block
+    end
+
+    def publish(_payload, _opts = {}); end
+
+    def fire_return(return_info, properties, body)
+      @on_return_handler&.call(return_info, properties, body)
+    end
+  end
+
   FakeChannel = Struct.new(:open) do
     def open?       = open
     def close       = (self.open = false)
     def confirm_select; end
     def prefetch(_n); end
+
+    def topic(name, opts = {})   = exchange_for(name, 'topic', opts)
+    def direct(name, opts = {})  = exchange_for(name, 'direct', opts)
+    def fanout(name, opts = {})  = exchange_for(name, 'fanout', opts)
+    def headers(name, opts = {}) = exchange_for(name, 'headers', opts)
+    def default_exchange         = exchange_for('', 'direct', {})
+
+    private
+
+    def exchange_for(name, type, opts)
+      @exchanges ||= {}
+      @exchanges[name] ||= FakeExchange.new(name, type, opts)
+    end
   end
 
   FakeConnection = Struct.new(:open, :channel_to_return) do

data/spec/unit/client_session_pool_spec.rb

@@ -27,7 +27,7 @@ RSpec.describe BugBunny::Client, 'session pooling' do
   def client_with_pool(pool)
     client = described_class.new(pool: pool)
     # Stub Producer#rpc para que no toque RabbitMQ real
-    allow_any_instance_of(BugBunny::Producer).to receive(:rpc) do |_prod, req|
+    allow_any_instance_of(BugBunny::Producer).to receive(:rpc) do |_prod, _req|
       { 'status' => 200, 'body' => '{"ok":true}' }
     end
     allow_any_instance_of(BugBunny::Producer).to receive(:fire) do |_prod, _req|
@@ -115,7 +115,7 @@ RSpec.describe BugBunny::Client, 'session pooling' do
 
   describe 'thread-safety' do
     it 'múltiples threads con la misma conexión no generan Sessions duplicadas' do
-      conn   = fake_conn
+      conn = fake_conn
       # Pool siempre devuelve la misma conexión — simula concurrencia en el mismo slot
       pool = Object.new
       mutex = Mutex.new
@@ -138,6 +138,83 @@ RSpec.describe BugBunny::Client, 'session pooling' do
     end
   end
 
+  describe 'Delivery mode routing' do
+    def fake_conn_local
+      channel = BunnyMocks::FakeChannel.new(true)
+      BunnyMocks::FakeConnection.new(true, channel)
+    end
+
+    it 'publish con confirmed: true enruta a Producer#confirmed' do
+      conn = fake_conn_local
+      client = described_class.new(pool: fake_pool(conn))
+
+      confirmed_called = false
+      allow_any_instance_of(BugBunny::Producer).to receive(:confirmed) do |_prod, _req|
+        confirmed_called = true
+        { 'status' => 202, 'body' => nil }
+      end
+
+      client.publish('acct.start',
+                     exchange: 'x', exchange_type: 'direct', body: { a: 1 },
+                     confirmed: true)
+
+      expect(confirmed_called).to be(true)
+    end
+
+    it 'propaga mandatory y confirm_timeout al Request' do
+      conn = fake_conn_local
+      client = described_class.new(pool: fake_pool(conn))
+
+      captured = nil
+      allow_any_instance_of(BugBunny::Producer).to receive(:confirmed) do |_prod, req|
+        captured = req
+        { 'status' => 202, 'body' => nil }
+      end
+
+      client.publish('acct.start',
+                     exchange: 'x', exchange_type: 'direct',
+                     confirmed: true, mandatory: true, confirm_timeout: 0.5)
+
+      expect(captured.delivery_mode).to eq(:confirmed)
+      expect(captured.mandatory).to be(true)
+      expect(captured.confirm_timeout).to eq(0.5)
+    end
+
+    it 'publish sin confirmed: true sigue invocando #fire (backward compat)' do
+      conn = fake_conn_local
+      client = described_class.new(pool: fake_pool(conn))
+
+      fire_called = false
+      allow_any_instance_of(BugBunny::Producer).to receive(:fire) do |_prod, _req|
+        fire_called = true
+        { 'status' => 202, 'body' => nil }
+      end
+
+      client.publish('evt', exchange: 'x', exchange_type: 'direct', body: {})
+
+      expect(fire_called).to be(true)
+    end
+
+    it 'send con bloque permite setear delivery_mode = :confirmed' do
+      conn = fake_conn_local
+      client = described_class.new(pool: fake_pool(conn))
+
+      confirmed_called = false
+      allow_any_instance_of(BugBunny::Producer).to receive(:confirmed) do |_prod, _req|
+        confirmed_called = true
+        { 'status' => 202, 'body' => nil }
+      end
+
+      client.send('evt.x', exchange: 'x', exchange_type: 'direct') do |req|
+        req.delivery_mode = :confirmed
+        req.mandatory = true
+        req.confirm_timeout = 0.2
+      end
+
+      expect(confirmed_called).to be(true)
+    end
+  end
+
   describe 'Session no se cierra entre requests' do
     it 'no invoca close en la Session al terminar el request' do
       conn   = fake_conn

data/spec/unit/configuration_spec.rb

@@ -149,6 +149,19 @@ RSpec.describe BugBunny::Configuration do
     end
   end
 
+  describe 'on_return callback' do
+    it 'tiene default nil' do
+      expect(BugBunny::Configuration.new.on_return).to be_nil
+    end
+
+    it 'acepta un Proc' do
+      cb = ->(_, _, _) { :noop }
+      configure_with(on_return: cb)
+
+      expect(BugBunny.configuration.on_return).to be(cb)
+    end
+  end
+
   describe '.validate! directamente' do
     it 'es invocable directamente sobre la instancia' do
       config = BugBunny::Configuration.new

data/spec/unit/producer_spec.rb

@@ -184,4 +184,108 @@ RSpec.describe BugBunny::Producer do
       end
     end
   end
+
+  describe '#confirmed' do
+    let(:fake_exchange) { double('exchange') }
+
+    let(:mock_channel) do
+      ch = double('channel')
+      allow(ch).to receive(:publish)
+      allow(ch).to receive(:open?).and_return(true)
+      allow(ch).to receive(:wait_for_confirms).and_return(true)
+      allow(ch).to receive(:nacked_set).and_return(Set.new)
+      ch
+    end
+
+    let(:mock_session) do
+      s = instance_double(BugBunny::Session)
+      allow(s).to receive(:exchange).and_return(fake_exchange)
+      allow(s).to receive(:channel).and_return(mock_channel)
+      s
+    end
+
+    let(:confirmed_producer) { described_class.new(mock_session) }
+
+    before do
+      allow(confirmed_producer).to receive(:safe_log) do |level, event, **kwargs|
+        logged_events << { level: level, event: event, kwargs: kwargs }
+      end
+      allow(fake_exchange).to receive(:publish)
+    end
+
+    def build_request
+      req = BugBunny::Request.new('acct.start')
+      req.exchange = 'acct_x'
+      req.method = :post
+      req.body = { tenant: 42 }
+      req
+    end
+
+    it 'retorna { status: 202 } cuando el broker confirma' do
+      result = confirmed_producer.confirmed(build_request)
+
+      expect(result).to eq('status' => 202, 'body' => nil)
+    end
+
+    it 'invoca wait_for_confirms en el canal' do
+      confirmed_producer.confirmed(build_request)
+
+      expect(mock_channel).to have_received(:wait_for_confirms)
+    end
+
+    it 'publica con mandatory: true cuando el request lo activa' do
+      req = build_request
+      req.mandatory = true
+
+      confirmed_producer.confirmed(req)
+
+      expect(fake_exchange).to have_received(:publish).with(
+        anything,
+        hash_including(mandatory: true, routing_key: 'acct.start')
+      )
+    end
+
+    it 'logea producer.confirms_nacked cuando hay nacks' do
+      allow(mock_channel).to receive(:nacked_set).and_return(Set.new([1, 2]))
+
+      confirmed_producer.confirmed(build_request)
+
+      nack_event = logged_events.find { |e| e[:event] == 'producer.confirms_nacked' }
+      expect(nack_event).not_to be_nil
+      expect(nack_event[:kwargs]).to include(count: 2, path: 'acct.start')
+    end
+
+    it 'NO logea producer.confirms_nacked cuando nacked_set está vacío' do
+      confirmed_producer.confirmed(build_request)
+
+      nack_event = logged_events.find { |e| e[:event] == 'producer.confirms_nacked' }
+      expect(nack_event).to be_nil
+    end
+
+    it 'levanta BugBunny::RequestTimeout si wait_for_confirms excede confirm_timeout' do
+      allow(mock_channel).to receive(:wait_for_confirms) {
+        sleep 1
+        true
+      }
+
+      req = build_request
+      req.confirm_timeout = 0.05
+
+      expect { confirmed_producer.confirmed(req) }.to raise_error(BugBunny::RequestTimeout, /Timeout/)
+    end
+
+    it 'envuelve errores del canal como BugBunny::CommunicationError' do
+      allow(mock_channel).to receive(:wait_for_confirms).and_raise(StandardError, 'boom')
+
+      expect { confirmed_producer.confirmed(build_request) }
+        .to raise_error(BugBunny::CommunicationError, /boom/)
+    end
+
+    it 'propaga BugBunny::Error sin envolver' do
+      allow(fake_exchange).to receive(:publish).and_raise(BugBunny::CommunicationError, 'chan dead')
+
+      expect { confirmed_producer.confirmed(build_request) }
+        .to raise_error(BugBunny::CommunicationError, 'chan dead')
+    end
+  end
 end

data/spec/unit/request_spec.rb

@@ -47,5 +47,34 @@ RSpec.describe BugBunny::Request do
 
       expect(request.amqp_options[:headers]['x-http-method']).to eq('POST')
     end
+
+    it 'omite :mandatory cuando no fue activado' do
+      expect(request.amqp_options).not_to have_key(:mandatory)
+    end
+
+    it 'incluye :mandatory => true cuando se activa' do
+      request.mandatory = true
+
+      expect(request.amqp_options[:mandatory]).to be(true)
+    end
+  end
+
+  describe 'Publisher Confirms attributes' do
+    it 'tiene mandatory=false y confirm_timeout=nil por defecto' do
+      req = described_class.new('foo')
+
+      expect(req.mandatory).to be(false)
+      expect(req.confirm_timeout).to be_nil
+    end
+
+    it 'permite asignar mandatory y confirm_timeout' do
+      req = described_class.new('foo')
+
+      req.mandatory = true
+      req.confirm_timeout = 0.5
+
+      expect(req.mandatory).to be(true)
+      expect(req.confirm_timeout).to eq(0.5)
+    end
   end
 end

data/spec/unit/session_spec.rb

@@ -69,6 +69,88 @@ RSpec.describe BugBunny::Session do
     end
   end
 
+  describe '#on_return handler' do
+    let(:return_info) do
+      Struct.new(:reply_code, :reply_text, :exchange, :routing_key)
+            .new(312, 'NO_ROUTE', 'evt_x', 'unbound.key')
+    end
+    let(:properties) { double('properties') }
+    let(:body) { '{"a":1}' }
+
+    before do
+      # Logger en memoria para inspeccionar el default
+      @log_io = StringIO.new
+      BugBunny.configuration.logger = Logger.new(@log_io)
+      BugBunny.configuration.on_return = nil
+    end
+
+    after do
+      BugBunny.configuration.logger = Logger.new($stdout).tap { |l| l.level = Logger::INFO }
+      BugBunny.configuration.on_return = nil
+    end
+
+    it 'se registra sobre el exchange cuando publisher_confirms está activo' do
+      exchange = session.exchange(name: 'evt_x', type: 'topic')
+
+      expect { exchange.fire_return(return_info, properties, body) }.not_to raise_error
+    end
+
+    it 'registra una sola vez por nombre de exchange' do
+      first  = session.exchange(name: 'evt_x', type: 'topic')
+      second = session.exchange(name: 'evt_x', type: 'topic')
+
+      expect(second).to be(first)
+      expect(session.instance_variable_get(:@configured_returns)).to include('evt_x' => true)
+    end
+
+    it 'NO se registra cuando publisher_confirms está desactivado' do
+      fresh_channel = BunnyMocks::FakeChannel.new(true)
+      fresh_conn = BunnyMocks::FakeConnection.new(true, fresh_channel)
+      no_confirms = described_class.new(fresh_conn, publisher_confirms: false)
+      exchange = no_confirms.exchange(name: 'evt_x', type: 'topic')
+
+      expect(exchange.instance_variable_get(:@on_return_handler)).to be_nil
+    end
+
+    it 'NO se registra sobre el default exchange (name vacío)' do
+      default = session.exchange # name nil → default_exchange
+
+      expect(default.instance_variable_get(:@on_return_handler)).to be_nil
+    end
+
+    it 'invoca el callback de Configuration#on_return cuando está definido' do
+      received = nil
+      BugBunny.configuration.on_return = lambda { |ri, props, b|
+        received = { rk: ri.routing_key, props: props, body: b }
+      }
+
+      exchange = session.exchange(name: 'evt_x', type: 'topic')
+      exchange.fire_return(return_info, properties, body)
+
+      expect(received).to include(rk: 'unbound.key', body: '{"a":1}')
+    end
+
+    it 'logea session.broker_return como :warn cuando no hay callback' do
+      exchange = session.exchange(name: 'evt_x', type: 'topic')
+      exchange.fire_return(return_info, properties, body)
+
+      log = @log_io.string
+      expect(log).to include('event=session.broker_return')
+      expect(log).to include('reply_code=312')
+      expect(log).to include('routing_key=unbound.key')
+      expect(log).to include('body_size=7')
+    end
+
+    it 'no propaga excepciones del callback de usuario' do
+      BugBunny.configuration.on_return = ->(_, _, _) { raise 'boom' }
+
+      exchange = session.exchange(name: 'evt_x', type: 'topic')
+
+      expect { exchange.fire_return(return_info, properties, body) }.not_to raise_error
+      expect(@log_io.string).to include('event=session.on_return_failed')
+    end
+  end
+
   describe '#close' do
     it 'cierra el canal y lo nilifica' do
       session.channel

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 4.11.1
+  version: 4.12.0
 platform: ruby
 authors:
 - gabix
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-09 00:00:00.000000000 Z
+date: 2026-05-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -269,7 +269,6 @@ files:
 - skill/references/routing.md
 - skill/references/testing.md
 - skills-lock.json
-- skills.lock
 - skills.yml
 - spec/integration/client_spec.rb
 - spec/integration/consumer_middleware_spec.rb
@@ -304,7 +303,7 @@ metadata:
   homepage_uri: https://github.com/gedera/bug_bunny
   source_code_uri: https://github.com/gedera/bug_bunny
   changelog_uri: https://github.com/gedera/bug_bunny/blob/main/CHANGELOG.md
-  documentation_uri: https://github.com/gedera/bug_bunny/blob/v4.11.1/skill
+  documentation_uri: https://github.com/gedera/bug_bunny/blob/v4.12.0/skill
 post_install_message:
 rdoc_options: []
 require_paths:

data/skills.lock

@@ -1,33 +0,0 @@
----
-synced_at: '2026-04-08 09:13:30'
-skills:
-- name: agent-review
-  scope: local
-  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/agent-review"
-- name: ai-reports
-  scope: local
-  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/ai-reports"
-- name: documentation-writer
-  scope: local
-  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/documentation-writer"
-- name: find-skills
-  scope: local
-  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/find-skills"
-- name: gem-release
-  scope: local
-  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/gem-release"
-- name: quality-code
-  scope: local
-  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/quality-code"
-- name: rabbitmq-expert
-  scope: local
-  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/rabbitmq-expert"
-- name: skill-builder
-  scope: local
-  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/skill-builder"
-- name: skill-manager
-  scope: local
-  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/skill-manager"
-- name: yard
-  scope: local
-  path: "/Users/gabriel/src/gems/bug_bunny/.agents/skills/yard"