bug_bunny 3.1.0 → 3.1.2

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,31 @@ module BugBunny
 
     private
 
+    # Registra la petición en el log calculando las opciones de infraestructura.
+    #
+    # @param request [BugBunny::Request] Objeto Request que se está enviando.
+    # @param payload [String] El cuerpo del mensaje serializado.
+    def log_request(request, payload)
+      verb = request.method.to_s.upcase
+      target = request.path
+      rk = request.final_routing_key
+      id = request.correlation_id
+
+      # 📊 LOGGING DE OBSERVABILIDAD: Calculamos las opciones finales para mostrarlas en consola
+      final_x_opts = BugBunny::Session::DEFAULT_EXCHANGE_OPTIONS
+                       .merge(BugBunny.configuration.exchange_options || {})
+                       .merge(request.exchange_options || {})
+
+      # INFO: Resumen de una línea (Traffic)
+      BugBunny.configuration.logger.info("[BugBunny::Producer] 📤 #{verb} /#{target} | RK: '#{rk}' | ID: #{id}")
+
+      # DEBUG: Detalle completo de Infraestructura y Payload
+      BugBunny.configuration.logger.debug("[BugBunny::Producer] ⚙️  Exchange Opts: #{final_x_opts}")
+      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 +123,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 +136,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.

data/lib/bug_bunny/resource.rb

@@ -9,15 +9,13 @@ require 'rack/utils'
 module BugBunny
   # Clase base para modelos remotos que implementan **Active Record over AMQP (RESTful)**.
   #
-  # Soporta un esquema híbrido de datos:
-  # 1. **Atributos Tipados:** Definidos con `attribute :name, :type`.
-  # 2. **Atributos Dinámicos:** Asignados al vuelo sin definición previa.
-  #
-  # Implementa un sistema de "Dirty Tracking" híbrido para detectar cambios
-  # tanto en atributos tipados (via ActiveModel) como dinámicos (via Set manual).
+  # Soporta un esquema híbrido de datos y configuración de infraestructura en cascada:
+  # 1. **Defaults:** Definidos en la sesión.
+  # 2. **Global:** Definidos en BugBunny.configuration.
+  # 3. **Específico:** Definidos en la clase del recurso o vía `with`.
   #
   # @author Gabriel
-  # @since 3.0.6
+  # @since 3.1.0
   class Resource
     include ActiveModel::API
     include ActiveModel::Attributes
@@ -31,11 +29,22 @@ module BugBunny
     attr_accessor :persisted
     attr_accessor :routing_key, :exchange, :exchange_type
 
+    # @return [Hash] Opciones específicas de instancia para exchange y queue.
+    attr_accessor :exchange_options, :queue_options
+
     class << self
       attr_writer :connection_pool, :exchange, :exchange_type, :resource_name, :routing_key, :param_key
 
+      # @!group Configuración de Infraestructura Específica
+      attr_writer :exchange_options, :queue_options
+
+      # @api private
       def thread_config(key); Thread.current["bb_#{object_id}_#{key}"]; end
 
+      # Resuelve la configuración buscando en el hilo, luego en la jerarquía de clases.
+      # @param key [Symbol] Clave en el Thread.current.
+      # @param instance_var [Symbol] Nombre de la variable de instancia en la clase.
+      # @return [Object, nil]
       def resolve_config(key, instance_var)
         val = thread_config(key)
         return val if val
@@ -48,23 +57,38 @@ module BugBunny
         nil
       end
 
+      # @return [ConnectionPool, nil]
       def connection_pool; resolve_config(:pool, :@connection_pool); end
-      def current_exchange; resolve_config(:exchange, :@exchange) || raise(ArgumentError, "Exchange not defined"); end
+
+      # @return [String] Nombre del exchange actual.
+      def current_exchange; resolve_config(:exchange, :@exchange) || raise(ArgumentError, "Exchange not defined for #{name}"); end
+
+      # @return [String] Tipo de exchange ('direct', 'topic', 'fanout').
       def current_exchange_type; resolve_config(:exchange_type, :@exchange_type) || 'direct'; end
 
+      # @return [Hash] Opciones de exchange específicas (Nivel 3 de la cascada).
+      def current_exchange_options; resolve_config(:exchange_options, :@exchange_options) || {}; end
+
+      # @return [Hash] Opciones de cola específicas.
+      def current_queue_options; resolve_config(:queue_options, :@queue_options) || {}; end
+
+      # @return [String] Nombre del recurso para la construcción de rutas.
       def resource_name
         resolve_config(:resource_name, :@resource_name) || name.demodulize.underscore.pluralize
       end
 
+      # @return [String] Clave raíz para envolver el payload en las peticiones.
       def param_key
         resolve_config(:param_key, :@param_key) || model_name.element
       end
 
+      # @api private
       def client_middleware(&block)
         @client_middleware_stack ||= []
         @client_middleware_stack << block
       end
 
+      # @api private
       def resolve_middleware_stack
         stack = []
         target = self
@@ -76,6 +100,8 @@ module BugBunny
         stack
       end
 
+      # Instancia el cliente inyectando los middlewares configurados.
+      # @return [BugBunny::Client]
       def bug_bunny_client
         pool = connection_pool
         raise BugBunny::Error, "Connection pool missing for #{name}" unless pool
@@ -84,8 +110,23 @@ module BugBunny
         end
       end
 
-      def with(exchange: nil, routing_key: nil, exchange_type: nil, pool: nil)
-        keys = { exchange: "bb_#{object_id}_exchange", exchange_type: "bb_#{object_id}_exchange_type", pool: "bb_#{object_id}_pool", routing_key: "bb_#{object_id}_routing_key" }
+      # Permite configurar dinámicamente el contexto AMQP para una operación.
+      #
+      # @param exchange [String] Nombre del exchange.
+      # @param routing_key [String] Routing key manual.
+      # @param exchange_type [String] Tipo de exchange.
+      # @param pool [ConnectionPool] Pool de conexiones.
+      # @param exchange_options [Hash] Opciones de infraestructura.
+      # @param queue_options [Hash] Opciones de cola.
+      def with(exchange: nil, routing_key: nil, exchange_type: nil, pool: nil, exchange_options: nil, queue_options: nil)
+        keys = {
+          exchange: "bb_#{object_id}_exchange",
+          exchange_type: "bb_#{object_id}_exchange_type",
+          pool: "bb_#{object_id}_pool",
+          routing_key: "bb_#{object_id}_routing_key",
+          exchange_options: "bb_#{object_id}_exchange_options",
+          queue_options: "bb_#{object_id}_queue_options"
+        }
         old_values = {}
         keys.each { |k, v| old_values[k] = Thread.current[v] }
 
@@ -93,6 +134,8 @@ module BugBunny
         Thread.current[keys[:exchange_type]] = exchange_type if exchange_type
         Thread.current[keys[:pool]] = pool if pool
         Thread.current[keys[:routing_key]] = routing_key if routing_key
+        Thread.current[keys[:exchange_options]] = exchange_options if exchange_options
+        Thread.current[keys[:queue_options]] = queue_options if queue_options
 
         if block_given?
           begin; yield; ensure; keys.each { |k, v| Thread.current[v] = old_values[k] }; end
@@ -101,11 +144,15 @@ module BugBunny
         end
       end
 
+      # Proxy para el encadenamiento del método `.with`.
       class ScopeProxy < BasicObject
         def initialize(target, keys, old_values); @target = target; @keys = keys; @old_values = old_values; end
         def method_missing(method, *args, &block); @target.public_send(method, *args, &block); ensure; @keys.each { |k, v| ::Thread.current[v] = @old_values[k] }; end
       end
 
+      # Calcula la routing key final.
+      # @param id [String, nil] ID del recurso.
+      # @return [String]
       def calculate_routing_key(id = nil)
         manual_rk = thread_config(:routing_key)
         return manual_rk if manual_rk
@@ -115,11 +162,25 @@ module BugBunny
       end
 
       # @!group Acciones CRUD RESTful
+
+      # Realiza una búsqueda filtrada (GET).
+      # @param filters [Hash]
+      # @return [Array<BugBunny::Resource>]
       def where(filters = {})
         rk = calculate_routing_key
         path = resource_name
         path += "?#{Rack::Utils.build_nested_query(filters)}" if filters.present?
-        response = bug_bunny_client.request(path, method: :get, exchange: current_exchange, exchange_type: current_exchange_type, routing_key: rk)
+
+        response = bug_bunny_client.request(
+          path,
+          method: :get,
+          exchange: current_exchange,
+          exchange_type: current_exchange_type,
+          routing_key: rk,
+          exchange_options: current_exchange_options,
+          queue_options: current_queue_options
+        )
+
         return [] unless response['body'].is_a?(Array)
         response['body'].map do |attrs|
           inst = new(attrs)
@@ -129,12 +190,27 @@ module BugBunny
         end
       end
 
+      # Devuelve todos los registros.
+      # @return [Array<BugBunny::Resource>]
       def all; where({}); end
 
+      # Busca un registro por ID (GET).
+      # @param id [String, Integer]
+      # @return [BugBunny::Resource, nil]
       def find(id)
         rk = calculate_routing_key(id)
         path = "#{resource_name}/#{id}"
-        response = bug_bunny_client.request(path, method: :get, exchange: current_exchange, exchange_type: current_exchange_type, routing_key: rk)
+
+        response = bug_bunny_client.request(
+          path,
+          method: :get,
+          exchange: current_exchange,
+          exchange_type: current_exchange_type,
+          routing_key: rk,
+          exchange_options: current_exchange_options,
+          queue_options: current_queue_options
+        )
+
         return nil if response.nil? || response['status'] == 404
         return nil unless response['body'].is_a?(Hash)
         instance = new(response['body'])
@@ -143,6 +219,9 @@ module BugBunny
         instance
       end
 
+      # Crea una nueva instancia y la persiste.
+      # @param payload [Hash]
+      # @return [BugBunny::Resource]
       def create(payload)
         instance = new(payload)
         instance.save
@@ -152,13 +231,19 @@ module BugBunny
 
     # @!group Instancia
 
+    # Inicializa el recurso.
+    # @param attributes [Hash]
     def initialize(attributes = {})
       @remote_attributes = {}.with_indifferent_access
       @dynamic_changes = Set.new # Rastreo manual para atributos dinámicos
       @persisted = false
+
+      # Contexto de infraestructura
       @routing_key = self.class.thread_config(:routing_key)
       @exchange = self.class.thread_config(:exchange)
       @exchange_type = self.class.thread_config(:exchange_type)
+      @exchange_options = self.class.thread_config(:exchange_options) || self.class.current_exchange_options
+      @queue_options = self.class.thread_config(:queue_options) || self.class.current_queue_options
 
       super()
       assign_attributes(attributes)
@@ -170,30 +255,46 @@ module BugBunny
       @dynamic_changes.clear
     end
 
+    # Serialización combinada.
+    # @return [Hash]
     def attributes_for_serialization
       @remote_attributes.merge(attributes)
     end
 
+    # @return [String]
     def calculate_routing_key(id=nil); @routing_key || self.class.calculate_routing_key(id); end
+
+    # @return [String]
     def current_exchange; @exchange || self.class.current_exchange; end
+
+    # @return [String]
     def current_exchange_type; @exchange_type || self.class.current_exchange_type; end
+
+    # @return [BugBunny::Client]
     def bug_bunny_client; self.class.bug_bunny_client; end
+
+    # @return [Boolean]
     def persisted?; !!@persisted; end
 
+    # Asignación masiva de atributos.
+    # @param new_attributes [Hash]
     def assign_attributes(new_attributes)
       return if new_attributes.nil?
       new_attributes.each { |k, v| public_send("#{k}=", v) }
     end
 
+    # Actualiza y guarda.
+    # @param attributes [Hash]
+    # @return [Boolean]
     def update(attributes)
       assign_attributes(attributes)
       save
     end
 
     # Retorna el hash combinado de cambios (Tipados + Dinámicos).
+    # @return [Hash]
     def changes_to_send
       # 1. Cambios de ActiveModel (Tipados)
-      # changes returns { 'attr' => [old, new] } -> nos quedamos con new
       payload = changes.transform_values(&:last)
 
       # 2. Cambios Dinámicos (Manuales)
@@ -214,8 +315,6 @@ module BugBunny
         key = attribute_name.chop
         val = args.first
 
-        # Dirty Tracking Manual
-        # Si el valor cambia, lo marcamos en nuestro Set
         if @remote_attributes[key] != val
           @dynamic_changes << key
         end
@@ -230,6 +329,7 @@ module BugBunny
       @remote_attributes.key?(method_name.to_s.sub(/=$/, '')) || super
     end
 
+    # @return [Object] Valor del ID buscando en múltiples nomenclaturas.
     def id
       attributes['id'] || @remote_attributes['id'] || @remote_attributes['ID'] || @remote_attributes['Id'] || @remote_attributes['_id']
     end
@@ -249,6 +349,8 @@ module BugBunny
 
     # @!group Persistencia
 
+    # Guarda el recurso en el servidor remoto vía AMQP (POST o PUT).
+    # @return [Boolean]
     def save
       return false unless valid?
 
@@ -268,6 +370,8 @@ module BugBunny
           exchange: current_exchange,
           exchange_type: current_exchange_type,
           routing_key: rk,
+          exchange_options: @exchange_options,
+          queue_options: @queue_options,
           body: wrapped_payload
         )
 
@@ -278,12 +382,24 @@ module BugBunny
       false
     end
 
+    # Elimina el recurso del servidor remoto (DELETE).
+    # @return [Boolean]
     def destroy
       return false unless persisted?
       run_callbacks(:destroy) do
         path = "#{self.class.resource_name}/#{id}"
         rk = calculate_routing_key(id)
-        bug_bunny_client.request(path, method: :delete, exchange: current_exchange, exchange_type: current_exchange_type, routing_key: rk)
+
+        bug_bunny_client.request(
+          path,
+          method: :delete,
+          exchange: current_exchange,
+          exchange_type: current_exchange_type,
+          routing_key: rk,
+          exchange_options: @exchange_options,
+          queue_options: @queue_options
+        )
+
         self.persisted = false
       end
       true
@@ -293,20 +409,38 @@ module BugBunny
 
     private
 
+    # Maneja la lógica de respuesta para la acción de guardado.
     def handle_save_response(response)
       if response['status'] == 422
         raise BugBunny::UnprocessableEntity.new(response['body']['errors'] || response['body'])
       elsif response['status'] >= 500
-        raise BugBunny::InternalServerError
+        raise BugBunny::InternalServerError, format_error_message(response['body'])
       elsif response['status'] >= 400
-        raise BugBunny::ClientError
+        raise BugBunny::ClientError, format_error_message(response['body'])
       end
+
       assign_attributes(response['body'])
       self.persisted = true
       clear_changes_information
       true
     end
 
+    # Formatea el cuerpo de la respuesta de error para que sea legible en las excepciones
+    def format_error_message(body)
+      return "Unknown Error" if body.nil?
+      return body if body.is_a?(String)
+
+      # Si el worker devolvió un JSON con una key 'error' (nuestra convención en Controller), la priorizamos
+      if body.is_a?(Hash) && body['error']
+        detail = body['detail'] ? " - #{body['detail']}" : ""
+        "#{body['error']}#{detail}"
+      else
+        # Fallback: Convertir todo el Hash a JSON string para que se vea claro en Sentry/Logs
+        body.to_json
+      end
+    end
+
+    # Carga errores remotos en el objeto local.
     def load_remote_rabbit_errors(errors_hash)
       return if errors_hash.nil?
       if errors_hash.is_a?(String)