bug_bunny 3.1.0 → 3.1.1

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,6 +409,7 @@ 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'])
@@ -301,12 +418,14 @@ module BugBunny
       elsif response['status'] >= 400
         raise BugBunny::ClientError
       end
+
       assign_attributes(response['body'])
       self.persisted = true
       clear_changes_information
       true
     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)

data/lib/bug_bunny/session.rb

@@ -1,18 +1,23 @@
-# lib/bug_bunny/session.rb
+# frozen_string_literal: true
 
 module BugBunny
   # Clase interna que encapsula una unidad de trabajo sobre una conexión RabbitMQ.
   #
-  # Gestiona el ciclo de vida de un `Bunny::Channel` implementando:
-  # 1. Carga Perezosa (Lazy Loading): El canal solo se abre al usarse.
-  # 2. Resiliencia: Intenta recuperar la conexión TCP si está cerrada.
+  # Implementa la lógica de "Configuración en Cascada" para Exchanges y Colas,
+  # gestionando el ciclo de vida de un `Bunny::Channel` con resiliencia y carga perezosa.
   #
   # @api private
   class Session
-    # Opciones por defecto (Mantenemos las que tenías en tu repo)
+    # @!group Opciones por Defecto (Nivel 1: Gema)
+
+    # Opciones predeterminadas de la gema para Exchanges.
     DEFAULT_EXCHANGE_OPTIONS = { durable: false, auto_delete: false }.freeze
+
+    # Opciones predeterminadas de la gema para Colas.
     DEFAULT_QUEUE_OPTIONS = { exclusive: false, durable: false, auto_delete: true }.freeze
 
+    # @!endgroup
+
     # @return [Bunny::Session] La conexión TCP subyacente.
     attr_reader :connection
 
@@ -42,30 +47,50 @@ module BugBunny
       @channel
     end
 
-    # Factory method para declarar o recuperar un Exchange.
-    # Usa el método robusto `channel` internamente.
+    # Factory method para declarar o recuperar un Exchange aplicando la cascada de configuración.
+    #
+    # Jerarquía de fusión:
+    # 1. Defaults de la gema (`DEFAULT_EXCHANGE_OPTIONS`)
+    # 2. Configuración global (`BugBunny.configuration.exchange_options`)
+    # 3. Opciones específicas pasadas como argumento (`opts`)
     #
     # @param name [String, nil] Nombre del exchange.
-    # @param type [String, Symbol] Tipo de exchange.
-    # @param opts [Hash] Opciones adicionales.
+    # @param type [String, Symbol] Tipo de exchange ('direct', 'topic', 'fanout').
+    # @param opts [Hash] Opciones específicas de infraestructura para este intercambio.
+    # @return [Bunny::Exchange] El objeto exchange de Bunny configurado.
     def exchange(name: nil, type: 'direct', opts: {})
       return channel.default_exchange if name.nil? || name.empty?
 
-      merged_opts = DEFAULT_EXCHANGE_OPTIONS.merge(opts)
-      # public_send permite llamar a :topic, :direct, etc. dinámicamente
+      # Aplicación de la lógica de fusión en cascada
+      merged_opts = DEFAULT_EXCHANGE_OPTIONS
+                    .merge(BugBunny.configuration.exchange_options || {})
+                    .merge(opts)
+
+      # public_send permite llamar a :topic, :direct, etc. dinámicamente según el tipo
       channel.public_send(type, name, merged_opts)
     end
 
-    # Factory method para declarar o recuperar una Cola.
-    # Usa el método robusto `channel` internamente.
+    # Factory method para declarar o recuperar una Cola aplicando la cascada de configuración.
+    #
+    # Jerarquía de fusión:
+    # 1. Defaults de la gema (`DEFAULT_QUEUE_OPTIONS`)
+    # 2. Configuración global (`BugBunny.configuration.queue_options`)
+    # 3. Opciones específicas pasadas como argumento (`opts`)
     #
     # @param name [String] Nombre de la cola.
-    # @param opts [Hash] Opciones adicionales.
+    # @param opts [Hash] Opciones específicas de infraestructura para esta cola.
+    # @return [Bunny::Queue] El objeto cola de Bunny configurado.
     def queue(name, opts = {})
-      channel.queue(name.to_s, DEFAULT_QUEUE_OPTIONS.merge(opts))
+      # Aplicación de la lógica de fusión en cascada
+      merged_opts = DEFAULT_QUEUE_OPTIONS
+                    .merge(BugBunny.configuration.queue_options || {})
+                    .merge(opts)
+
+      channel.queue(name.to_s, merged_opts)
     end
 
     # Cierra el canal asociado a esta sesión de forma segura.
+    # @return [void]
     def close
       @channel&.close if @channel&.open?
       @channel = nil
@@ -73,8 +98,10 @@ module BugBunny
 
     private
 
-    # Crea y configura un nuevo canal.
+    # Crea y configura un nuevo canal con las preferencias globales.
     # Asume que la conexión ya ha sido verificada por `ensure_connection!`.
+    #
+    # @raise [BugBunny::CommunicationError] Si falla la creación del canal.
     def create_channel!
       @channel = @connection.create_channel
 
@@ -90,13 +117,15 @@ module BugBunny
 
     # Garantiza que la conexión TCP esté abierta.
     # Si está cerrada, intenta reconectarla (Reconexión Transparente).
+    #
+    # @raise [BugBunny::CommunicationError] Si falla la reconexión.
     def ensure_connection!
       return if @connection.open?
 
-      BugBunny.configuration.logger.warn("[BugBunny] Connection lost. Attempting to reconnect...")
+      BugBunny.configuration.logger.warn("[BugBunny::Session] ⚠️  Connection lost. Attempting to reconnect...")
       @connection.start
     rescue StandardError => e
-      BugBunny.configuration.logger.error("[BugBunny] Critical connection failure: #{e.message}")
+      BugBunny.configuration.logger.error("[BugBunny::Session] ❌ Critical connection failure: #{e.message}")
       raise BugBunny::CommunicationError, "Could not reconnect to RabbitMQ: #{e.message}"
     end
   end

data/lib/bug_bunny/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BugBunny
-  VERSION = "3.1.0"
+  VERSION = "3.1.1"
 end

data/lib/bug_bunny.rb

@@ -75,7 +75,7 @@ module BugBunny
 
     @global_connection.close if @global_connection.open?
     @global_connection = nil
-    configuration.logger.info('[BugBunny] Global connection closed.')
+    configuration.logger.info('[BugBunny] 🔌 Global connection closed.')
   end
 
   # @api private

data/test/integration/infrastructure_test.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative '../test_helper'
+
+# --- CLASES DE PRUEBA (Namespace Aislado) ---
+module InfraTest
+  class PingController < BugBunny::Controller
+    # Agregamos SHOW para soportar el .find del test
+    def show
+      render status: 200, json: { id: params[:id], message: 'pong', namespace: 'InfraTest' }
+    end
+
+    def index
+      render status: 200, json: { message: 'pong_index', namespace: 'InfraTest' }
+    end
+  end
+end
+
+class InfraResource < BugBunny::Resource
+  self.resource_name = 'ping'
+  self.exchange = 'test_infra_exchange'
+  self.exchange_type = 'topic'
+end
+
+# --- SUITE DE INFRAESTRUCTURA ---
+class InfrastructureTest < Minitest::Test
+  include IntegrationHelper
+
+  def setup
+    skip "RabbitMQ no disponible" unless IntegrationHelper.rabbitmq_available?
+    @queue = "test_infra_queue_#{SecureRandom.hex(4)}"
+    @exchange = "test_infra_exchange"
+  end
+
+  def test_00_worker_lifecycle
+    with_running_worker(queue: @queue, exchange: @exchange) do
+      assert true, "El worker levantó y cedió el control al bloque"
+    end
+  end
+
+  def test_01_dynamic_namespace_resolution
+    BugBunny.configure do |c|
+      c.controller_namespace = 'InfraTest'
+    end
+
+    with_running_worker(queue: @queue, exchange: @exchange) do
+      # Enviamos GET ping/123 -> InfraTest::PingController#show
+      resource = InfraResource.find('123')
+
+      # Verificamos que volvió el objeto construido
+      assert_equal '123', resource.id
+      assert_equal 'InfraTest', resource.namespace
+      assert_equal 'pong', resource.message
+    end
+
+  ensure
+    BugBunny.configure do |c|
+      c.controller_namespace = 'Rabbit::Controllers'
+    end
+  end
+end