bug_bunny 3.1.0 → 3.1.1

data/lib/bug_bunny/client.rb

@@ -1,14 +1,16 @@
-# lib/bug_bunny/client.rb
+# frozen_string_literal: true
+
 require_relative 'middleware/stack'
 
 module BugBunny
   # Cliente principal para realizar peticiones a RabbitMQ.
   #
   # Implementa el patrón "Onion Middleware" (Arquitectura de Cebolla) similar a Faraday.
-  # Mantiene una interfaz flexible donde el verbo HTTP se pasa como opción.
+  # Mantiene una interfaz flexible donde el verbo HTTP se pasa como opción y permite
+  # configurar la infraestructura AMQP de forma granular por petición.
   #
-  # @example Petición RPC (GET)
-  #   client.request('users/123', method: :get)
+  # @example Petición RPC (GET) con opciones de infraestructura
+  #   client.request('users/123', method: :get, exchange_options: { durable: true })
   #
   # @example Publicación Fire-and-Forget (POST)
   #   client.publish('logs', method: :post, body: { msg: 'Error' })
@@ -41,6 +43,8 @@ module BugBunny
     # @option args [Object] :body El cuerpo del mensaje.
     # @option args [Hash] :headers Headers AMQP adicionales.
     # @option args [Integer] :timeout Tiempo máximo de espera.
+    # @option args [Hash] :exchange_options Opciones específicas para la declaración del Exchange.
+    # @option args [Hash] :queue_options Opciones específicas para la declaración de la Cola.
     # @yield [req] Bloque para configurar el objeto Request directamente.
     # @return [Hash] La respuesta del servidor.
     def request(url, **args)
@@ -65,18 +69,28 @@ module BugBunny
 
     # Ejecuta la lógica de envío dentro del contexto del Pool.
     # Mapea los argumentos al objeto Request y ejecuta la cadena de middlewares.
+    #
+    # @param method_name [Symbol] El método del productor a llamar (:rpc o :fire).
+    # @param url [String] La ruta destino.
+    # @param args [Hash] Argumentos pasados a los métodos públicos.
+    # @yield [req] Bloque para configuración adicional del Request.
     def run_in_pool(method_name, url, args)
       # 1. Builder del Request
       req = BugBunny::Request.new(url)
 
       # 2. Syntactic Sugar: Mapeo de argumentos a atributos del Request
-      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]
-      req.headers.merge!(args[:headers])       if args[:headers]
+      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.headers.merge!(args[:headers])             if args[:headers]
 
       # 3. Configuración del usuario (bloque específico por request)
       yield req if block_given?
@@ -94,6 +108,7 @@ module BugBunny
           app = @stack.build(final_action)
           app.call(req)
         ensure
+          # Aseguramos el cierre del canal pero mantenemos la conexión del pool
           session.close
         end
       end

data/lib/bug_bunny/configuration.rb

@@ -4,7 +4,14 @@ require 'logger'
 
 module BugBunny
   # Clase de configuración global para la gema BugBunny.
-  # Almacena las credenciales de conexión, timeouts y parámetros de ajuste de RabbitMQ.
+  # Almacena las credenciales de conexión, timeouts y parámetros de ajuste de RabbitMQ,
+  # así como las opciones por defecto para la declaración de infraestructura AMQP.
+  #
+  # @example Configuración en un inicializador (e.g., config/initializers/bug_bunny.rb)
+  #   BugBunny.configure do |config|
+  #     config.host = '127.0.0.1'
+  #     config.exchange_options = { durable: true, auto_delete: false }
+  #   end
   class Configuration
     # @return [String] Host o IP del servidor RabbitMQ (ej: 'localhost').
     attr_accessor :host
@@ -60,9 +67,23 @@ module BugBunny
     # @return [String] Namespace base donde se buscarán los controladores (default: 'Rabbit::Controllers').
     attr_accessor :controller_namespace
 
-    # @return [Array<Symbol, Proc, String>]
+    # @return [Array<Symbol, Proc, String>] Etiquetas para el log estructurado.
     attr_accessor :log_tags
 
+    # @!group Configuración de Infraestructura Global
+
+    # @return [Hash] Opciones globales por defecto para la declaración de Exchanges.
+    #   Estas opciones se fusionarán con los valores por defecto de la gema y las específicas del recurso.
+    #   @example { durable: true, auto_delete: false }
+    attr_accessor :exchange_options
+
+    # @return [Hash] Opciones globales por defecto para la declaración de Colas.
+    #   Estas opciones se fusionarán con los valores por defecto de la gema y las específicas del recurso.
+    #   @example { durable: true, exclusive: false }
+    attr_accessor :queue_options
+
+    # @!endgroup
+
     # Inicializa la configuración con valores por defecto seguros.
     def initialize
       @host = '127.0.0.1'
@@ -91,9 +112,14 @@ module BugBunny
       @controller_namespace = 'Rabbit::Controllers'
 
       @log_tags = [:uuid]
+
+      # Inicialización de opciones de infraestructura como hashes vacíos para permitir fusiones posteriores.
+      @exchange_options = {}
+      @queue_options = {}
     end
 
     # Construye la URL de conexión AMQP basada en los atributos configurados.
+    # @return [String] URL formateada amqp://user:pass@host:port/vhost
     def url
       "amqp://#{username}:#{password}@#{host}:#{port}/#{vhost}"
     end

data/lib/bug_bunny/consumer.rb

@@ -61,7 +61,7 @@ module BugBunny
       q = session.queue(queue_name, queue_opts)
       q.bind(x, routing_key: routing_key)
 
-      BugBunny.configuration.logger.info("[Consumer] Listening on #{queue_name} (Exchange: #{exchange_name})")
+      BugBunny.configuration.logger.info("[BugBunny::Consumer] 🎧 Listening on '#{queue_name}' | Exchange: '#{exchange_name}' | Routing Key: '#{routing_key}'")
       start_health_check(queue_name)
 
       q.subscribe(manual_ack: true, block: block) do |delivery_info, properties, body|
@@ -78,7 +78,7 @@ module BugBunny
         end
       end
     rescue StandardError => e
-      BugBunny.configuration.logger.error("[Consumer] Connection Error: #{e.message}. Retrying...")
+      BugBunny.configuration.logger.error("[BugBunny::Consumer] 💥 Connection Error: #{e.message}. Retrying in #{BugBunny.configuration.network_recovery_interval}s...")
       sleep BugBunny.configuration.network_recovery_interval
       retry
     end
@@ -94,15 +94,11 @@ module BugBunny
     # @param body [String] El payload crudo del mensaje.
     # @return [void]
     def process_message(delivery_info, properties, body)
-      BugBunny.configuration.logger.debug("delivery_info: #{delivery_info}, properties: #{properties}, body: #{body}")
-      # 1. Recuperación Robusta del Path (Ruta)
-      path = properties.type
-      if path.nil? || path.empty?
-        path = properties.headers ? properties.headers['path'] : nil
-      end
+      # 1. Validación de Headers
+      path = properties.type || (properties.headers && properties.headers['path'])
 
       if path.nil? || path.empty?
-        BugBunny.configuration.logger.error("[Consumer] Missing 'type' or 'path' header. Message rejected.")
+        BugBunny.configuration.logger.error("[BugBunny::Consumer] ⛔ Rejected: Missing 'type' header.")
         session.channel.reject(delivery_info.delivery_tag, false)
         return
       end
@@ -114,6 +110,9 @@ module BugBunny
       # 3. Router: Inferencia de Controlador y Acción
       route_info = router_dispatch(http_method, path)
 
+      BugBunny.configuration.logger.info("[BugBunny::Consumer] 📥 Started #{http_method} \"/#{path}\" for Routing Key: #{delivery_info.routing_key}")
+      BugBunny.configuration.logger.debug("[BugBunny::Consumer] 📦 Body: #{body.truncate(200)}")
+
       request_metadata = {
         type: path,
         http_method: http_method,
@@ -133,7 +132,7 @@ module BugBunny
         controller_name = route_info[:controller].camelize
 
         # Construcción: "Messaging::Handlers" + "::" + "Users"
-        controller_class_name = "#{namespace}::#{controller_name}"
+        controller_class_name = "#{namespace}::#{controller_name}Controller"
 
         controller_class = controller_class_name.constantize
 
@@ -141,7 +140,7 @@ module BugBunny
           raise BugBunny::SecurityError, "Class #{controller_class} is not a valid BugBunny Controller"
         end
       rescue NameError => _e
-        BugBunny.configuration.logger.error("[Consumer] Controller not found: #{controller_class_name}")
+        BugBunny.configuration.logger.warn("[BugBunny::Consumer] ⚠️  Controller not found: #{controller_class_name} (Path: #{path})")
         handle_fatal_error(properties, 404, "Not Found", "Controller #{controller_class_name} not found")
         session.channel.reject(delivery_info.delivery_tag, false)
         return
@@ -159,7 +158,7 @@ module BugBunny
       session.channel.ack(delivery_info.delivery_tag)
 
     rescue StandardError => e
-      BugBunny.configuration.logger.error("[Consumer] Execution Error: #{e.message}")
+      BugBunny.configuration.logger.error("[BugBunny::Consumer] 💥 Execution Error (#{e.class}): #{e.message}")
       handle_fatal_error(properties, 500, "Internal Server Error", e.message)
       session.channel.reject(delivery_info.delivery_tag, false)
     end
@@ -216,7 +215,7 @@ module BugBunny
     # @param correlation_id [String] ID para correlacionar la respuesta con la petición original.
     # @return [void]
     def reply(payload, reply_to, correlation_id)
-      BugBunny.configuration.logger.debug("[Consumer] 📤 Enviando REPLY a: #{reply_to} | ID: #{correlation_id}")
+      BugBunny.configuration.logger.debug("[BugBunny::Consumer] 📤 Sending RPC Reply to #{reply_to} | ID: #{correlation_id}")
       session.channel.default_exchange.publish(
         payload.to_json,
         routing_key: reply_to,
@@ -247,7 +246,7 @@ module BugBunny
       Concurrent::TimerTask.new(execution_interval: BugBunny.configuration.health_check_interval) do
         session.channel.queue_declare(q_name, passive: true)
       rescue StandardError
-        BugBunny.configuration.logger.warn("[Consumer] Queue check failed. Reconnecting session...")
+        BugBunny.configuration.logger.warn("[BugBunny::Consumer] ⚠️  Queue check failed. Reconnecting session...")
         session.close
       end.execute
     end

data/lib/bug_bunny/controller.rb

@@ -167,8 +167,8 @@ module BugBunny
         return rendered_response if rendered_response
       end
 
-      BugBunny.configuration.logger.error("Controller Error (#{exception.class}): #{exception.message}")
-      BugBunny.configuration.logger.error(exception.backtrace.join("\n"))
+      BugBunny.configuration.logger.error("[BugBunny::Controller] 💥 Unhandled Exception (#{exception.class}): #{exception.message}")
+      BugBunny.configuration.logger.error(exception.backtrace.first(5).join("\n")) # Limitamos a 5 líneas para no ensuciar
 
       {
         status: 500,

data/lib/bug_bunny/producer.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'concurrent'
 require 'json'
 require 'securerandom'
@@ -27,39 +29,30 @@ module BugBunny
 
     # Envía un mensaje de forma asíncrona (Fire-and-Forget).
     #
-    # Serializa el cuerpo del request, resuelve el exchange y publica el mensaje
-    # sin esperar confirmación ni respuesta del consumidor.
+    # Serializa el cuerpo del request, resuelve el exchange aplicando la cascada de
+    # configuración y publica el mensaje sin esperar respuesta.
     #
-    # @param request [BugBunny::Request] Objeto con la configuración del envío (body, routing_key, etc).
+    # @param request [BugBunny::Request] Objeto con la configuración del envío (body, exchange_options, etc).
     # @return [void]
     def fire(request)
-      x = @session.exchange(name: request.exchange, type: request.exchange_type)
+      # 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 ESTRUCTURADO Y LEGIBLE
-      # Muestra claramente: Verbo, Recurso, Exchange (y su tipo) y la Routing Key usada.
-      verb = request.method.to_s.upcase
-      target = request.path
-      ex_info = "'#{request.exchange}' (Type: #{request.exchange_type})"
-      rk = request.final_routing_key
-
-      BugBunny.configuration.logger.info("[BugBunny] [#{verb}] '/#{target}' | Exchange: #{ex_info} | Routing Key: '#{rk}'")
+      log_request(request, payload)
 
       x.publish(payload, opts.merge(routing_key: request.final_routing_key))
     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`)
-    # para recibir la respuesta directamente sin necesidad de crear colas temporales
-    # por cada petición, lo cual mejora significativamente el rendimiento.
-    #
-    # El flujo es:
-    # 1. Asegura que hay un consumidor escuchando en `amq.rabbitmq.reply-to`.
-    # 2. Genera un `correlation_id` único.
-    # 3. Crea una promesa (`Concurrent::IVar`) y la registra.
-    # 4. Publica el mensaje y bloquea esperando que la promesa se resuelva.
+    # Implementa el mecanismo "Direct Reply-to" de RabbitMQ (`amq.rabbitmq.reply-to`).
     #
     # @param request [BugBunny::Request] Objeto request configurado.
     # @return [Hash] El cuerpo de la respuesta parseado desde JSON.
@@ -80,11 +73,12 @@ module BugBunny
       begin
         fire(request)
 
+        BugBunny.configuration.logger.debug("[BugBunny::Producer] ⏳ Waiting for RPC response | ID: #{cid} | Timeout: #{wait_timeout}s")
+
         # Bloqueamos el hilo aquí hasta que llegue la respuesta o expire el timeout
         response_payload = future.value(wait_timeout)
 
         if response_payload.nil?
-          # CORRECCIÓN: Usamos request.path y request.method en lugar de request.action
           raise BugBunny::RequestTimeout, "Timeout waiting for RPC: #{request.path} [#{request.method}]"
         end
 
@@ -97,7 +91,21 @@ module BugBunny
 
     private
 
+    def log_request(request, payload)
+      verb = request.method.to_s.upcase
+      target = request.path
+      rk = request.final_routing_key
+      id = request.correlation_id
+
+      # INFO: Resumen de una línea (Traffic)
+      BugBunny.configuration.logger.info("[BugBunny::Producer] 📤 #{verb} /#{target} | RK: '#{rk}' | ID: #{id}")
+
+      # DEBUG: Detalle completo (Payload)
+      BugBunny.configuration.logger.debug("[BugBunny::Producer] 📦 Payload: #{payload.truncate(300)}") if payload.is_a?(String)
+    end
+
     # Serializa el mensaje para su transporte.
+    #
     # @param msg [Hash, String, Object] El mensaje a serializar.
     # @return [String] Cadena JSON o string crudo.
     def serialize_message(msg)
@@ -105,6 +113,9 @@ module BugBunny
     end
 
     # Intenta parsear la respuesta recibida.
+    #
+    # @param payload [String] El cuerpo de la respuesta recibida.
+    # @return [Hash] El JSON parseado.
     # @raise [BugBunny::InternalServerError] Si el payload no es JSON válido.
     def parse_response(payload)
       JSON.parse(payload)
@@ -115,27 +126,25 @@ module BugBunny
     # Inicia el consumidor de respuestas RPC de forma perezosa (Lazy Initialization).
     #
     # Utiliza un patrón de "Double-Checked Locking" con Mutex para asegurar que
-    # solo se crea un listener por instancia de Producer, incluso en entornos multi-hilo.
+    # solo se crea un listener por instancia de Producer.
     #
-    # Escucha en la pseudo-cola `amq.rabbitmq.reply-to`. Cuando llega un mensaje,
-    # busca el `correlation_id` en el mapa de pendientes y completa el futuro (`IVar`),
-    # desbloqueando así al hilo que llamó a {#rpc}.
+    # @return [void]
     def ensure_reply_listener!
       return if @reply_listener_started
 
       @reply_listener_mutex.synchronize do
         return if @reply_listener_started
 
-        BugBunny.configuration.logger.debug("[Producer] 👂 Iniciando escucha en amq.rabbitmq.reply-to...")
+        BugBunny.configuration.logger.debug("[BugBunny::Producer] 👂 Starting Reply Listener on 'amq.rabbitmq.reply-to'")
 
         # Consumimos sin ack (auto-ack) porque reply-to no soporta acks manuales de forma estándar
         @session.channel.basic_consume('amq.rabbitmq.reply-to', '', true, false, nil) do |_, props, body|
-          BugBunny.configuration.logger.debug("[Producer] 📥 RESPUESTA RECIBIDA | ID: #{props.correlation_id}")
-          incoming_cid = props.correlation_id.to_s
-          if (future = @pending_requests[incoming_cid])
+          cid = props.correlation_id.to_s
+          BugBunny.configuration.logger.debug("[BugBunny::Producer] 📥 RPC Response matched | ID: #{cid}")
+          if (future = @pending_requests[cid])
             future.set(body)
-            else
-              BugBunny.configuration.logger.warn("[Producer] ⚠️ ID #{incoming_cid} no encontrado en pendientes: #{@pending_requests.keys}")
+          else
+            BugBunny.configuration.logger.warn("[BugBunny::Producer] ⚠️ Orphaned RPC Response received | ID: #{cid}")
           end
         end
         @reply_listener_started = true

data/lib/bug_bunny/request.rb

@@ -1,10 +1,11 @@
-# lib/bug_bunny/request.rb
+# frozen_string_literal: true
 
 module BugBunny
   # Encapsula toda la información necesaria para realizar una petición o publicación.
   #
   # Actúa como el objeto "Environment" en la arquitectura de middlewares.
-  # Contiene el cuerpo del mensaje, la configuración de enrutamiento y el **Verbo HTTP**.
+  # Contiene el cuerpo del mensaje, la configuración de enrutamiento, el **Verbo HTTP**
+  # y las opciones de infraestructura específicas para la petición.
   #
   # @attr body [Object] El cuerpo del mensaje (Hash, Array o String).
   # @attr headers [Hash] Cabeceras personalizadas (Headers AMQP).
@@ -14,6 +15,9 @@ module BugBunny
   # @attr exchange_type [String] El tipo de exchange ('direct', 'topic', 'fanout').
   # @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 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.
   class Request
     attr_accessor :body
     attr_accessor :headers
@@ -24,6 +28,10 @@ module BugBunny
     attr_accessor :routing_key
     attr_accessor :timeout
 
+    # Configuración de Infraestructura Específica
+    attr_accessor :exchange_options
+    attr_accessor :queue_options
+
     # Metadatos AMQP Estándar
     attr_accessor :app_id, :content_type, :content_encoding, :priority,
                   :timestamp, :expiration, :persistent, :reply_to,
@@ -40,6 +48,10 @@ module BugBunny
       @timestamp = Time.now.to_i
       @persistent = false
       @exchange_type = 'direct'
+
+      # Inicialización de opciones de infraestructura para evitar errores de nil durante el merge.
+      @exchange_options = {}
+      @queue_options = {}
     end
 
     # Calcula la Routing Key final que se usará en RabbitMQ.