bug_bunny 3.0.6 → 3.1.1

data/lib/bug_bunny/resource.rb

@@ -1,71 +1,53 @@
-# lib/bug_bunny/resource.rb
+# frozen_string_literal: true
+
 require 'active_model'
 require 'active_support/core_ext/string/inflections'
 require 'uri'
+require 'set' # Necesario para el tracking manual
 require 'rack/utils'
 
 module BugBunny
   # Clase base para modelos remotos que implementan **Active Record over AMQP (RESTful)**.
   #
-  # Esta clase transforma operaciones CRUD estándar en peticiones RPC utilizando
-  # verbos HTTP semánticos (GET, POST, PUT, DELETE) transportados sobre headers AMQP.
-  #
-  # También gestiona la serialización automática de parámetros ("wrapping") para
-  # compatibilidad con Strong Parameters de Rails.
-  #
-  # @example Definición de un recurso
-  #   class User < BugBunny::Resource
-  #     self.exchange = 'app.topic'
-  #     self.resource_name = 'users'
-  #     # Opcional: Personalizar la clave raíz del JSON
-  #     self.param_key = 'user_data'
-  #   end
+  # 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`.
   #
-  # @example Uso con contexto temporal
-  #   # La instancia 'user' recordará que debe usar la routing_key 'urgent'
-  #   user = User.with(routing_key: 'urgent').new(name: 'Gaby')
-  #   user.save # Enviará a la cola 'urgent' aunque estemos fuera del bloque .with
+  # @author Gabriel
+  # @since 3.1.0
   class Resource
     include ActiveModel::API
+    include ActiveModel::Attributes
     include ActiveModel::Dirty
     include ActiveModel::Validations
     extend ActiveModel::Callbacks
 
     define_model_callbacks :save, :create, :update, :destroy
 
-    # @return [HashWithIndifferentAccess] Contenedor de los atributos remotos (JSON crudo).
     attr_reader :remote_attributes
-
-    # @return [Boolean] Indica si el objeto ha sido guardado en el servicio remoto.
     attr_accessor :persisted
+    attr_accessor :routing_key, :exchange, :exchange_type
 
-    # @return [String, nil] Routing Key capturada en el momento de la instanciación.
-    attr_accessor :routing_key
-
-    # @return [String, nil] Exchange capturado en el momento de la instanciación.
-    attr_accessor :exchange
-
-    # @return [String, nil] Tipo de Exchange capturado en el momento de la instanciación.
-    attr_accessor :exchange_type
+    # @return [Hash] Opciones específicas de instancia para exchange y queue.
+    attr_accessor :exchange_options, :queue_options
 
     class << self
-      # Configuración heredable
       attr_writer :connection_pool, :exchange, :exchange_type, :resource_name, :routing_key, :param_key
 
-      # Lee la configuración del Thread actual (usado por el scope .with).
-      # @api private
-      def thread_config(key)
-        Thread.current["bb_#{object_id}_#{key}"]
-      end
+      # @!group Configuración de Infraestructura Específica
+      attr_writer :exchange_options, :queue_options
 
-      # Resuelve la configuración buscando en: 1. Thread (Scope), 2. Clase, 3. Herencia.
       # @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)
-        # 1. Prioridad: Contexto de hilo (.with)
         val = thread_config(key)
         return val if val
-
-        # 2. Prioridad: Jerarquía de clases
         target = self
         while target <= BugBunny::Resource
           value = target.instance_variable_get(instance_var)
@@ -75,32 +57,32 @@ module BugBunny
         nil
       end
 
-      # @return [ConnectionPool] El pool de conexiones asignado.
+      # @return [ConnectionPool, nil]
       def connection_pool; resolve_config(:pool, :@connection_pool); end
 
-      # @return [String] El exchange configurado.
-      # @raise [ArgumentError] Si no se ha definido un exchange.
-      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] El tipo de exchange (default: direct).
+      # @return [String] Tipo de exchange ('direct', 'topic', 'fanout').
       def current_exchange_type; resolve_config(:exchange_type, :@exchange_type) || 'direct'; end
 
-      # @return [String] El nombre del recurso (ej: 'users'). Se infiere del nombre de la clase si no existe.
+      # @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
 
-      # Define la clave raíz para envolver el payload JSON (Wrapping).
-      #
-      # Por defecto utiliza `model_name.element`, lo que elimina los namespaces.
-      # Ej: `Manager::Service` -> `'service'`.
-      #
-      # @return [String] La clave paramétrica.
+      # @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
 
-      # Define un middleware para el cliente HTTP/AMQP de este recurso.
+      # @api private
       def client_middleware(&block)
         @client_middleware_stack ||= []
         @client_middleware_stack << block
@@ -118,32 +100,42 @@ module BugBunny
         stack
       end
 
-      # Instancia un cliente configurado con el pool y middlewares del recurso.
+      # 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
-
         BugBunny::Client.new(pool: pool) do |conn|
           resolve_middleware_stack.each { |block| block.call(conn) }
         end
       end
 
-      # Ejecuta un bloque (o retorna un Proxy) con una configuración temporal.
-      # Útil para cambiar de exchange o routing_key para una operación específica.
+      # Permite configurar dinámicamente el contexto AMQP para una operación.
       #
-      # @example
-      #   User.with(routing_key: 'urgent').create(params)
-      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" }
+      # @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] }
 
-        # Seteamos valores temporales
         Thread.current[keys[:exchange]] = exchange if exchange
         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
@@ -152,39 +144,42 @@ module BugBunny
         end
       end
 
-      # Proxy para permitir encadenamiento: User.with(...).find(1)
+      # 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.
+      # Calcula la routing key final.
+      # @param id [String, nil] ID del recurso.
       # @return [String]
       def calculate_routing_key(id = nil)
-        # 1. Contexto .with
         manual_rk = thread_config(:routing_key)
         return manual_rk if manual_rk
-
-        # 2. Configuración estática
         static_rk = resolve_config(:routing_key, :@routing_key)
         return static_rk if static_rk.present?
-
-        # 3. Default: Resource name
         resource_name
       end
 
-      # @!group Acciones CRUD RESTful (Clase)
+      # @!group Acciones CRUD RESTful
 
-      # Busca recursos que coincidan con los filtros.
-      # Envía: GET resource?query
+      # Realiza una búsqueda filtrada (GET).
+      # @param filters [Hash]
+      # @return [Array<BugBunny::Resource>]
       def where(filters = {})
         rk = calculate_routing_key
         path = resource_name
-
-        # Usamos Rack para serializar anidamiento (q[service]=val)
         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|
@@ -195,28 +190,38 @@ module BugBunny
         end
       end
 
+      # Devuelve todos los registros.
+      # @return [Array<BugBunny::Resource>]
       def all; where({}); end
 
-      # Busca un recurso por ID.
-      # Envía: GET resource/id
+      # 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
-
-        attributes = response['body']
-        return nil unless attributes.is_a?(Hash)
-
-        instance = new(attributes)
+        return nil unless response['body'].is_a?(Hash)
+        instance = new(response['body'])
         instance.persisted = true
         instance.send(:clear_changes_information)
         instance
       end
 
-      # Crea un nuevo recurso.
+      # Crea una nueva instancia y la persiste.
+      # @param payload [Hash]
+      # @return [BugBunny::Resource]
       def create(payload)
         instance = new(payload)
         instance.save
@@ -226,70 +231,94 @@ module BugBunny
 
     # @!group Instancia
 
-    # Inicializa una nueva instancia del recurso.
-    #
-    # **IMPORTANTE:** Captura la configuración del contexto actual (`.with`)
-    # y la guarda en la instancia. Esto permite que objetos creados dentro de un bloque `with`
-    # mantengan esa configuración (routing_key, exchange) durante todo su ciclo de vida,
-    # incluso si `save` se llama fuera del bloque.
-    #
-    # @param attributes [Hash] Atributos iniciales.
+    # 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
 
-      # === CAPTURA DE CONTEXTO ===
+      # 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
 
-      assign_attributes(attributes)
       super()
+      assign_attributes(attributes)
     end
 
-    # Prioridad Routing Key: 1. Instancia (Capturada), 2. Clase
-    def calculate_routing_key(id=nil)
-      return @routing_key if @routing_key
-      self.class.calculate_routing_key(id)
+    # Limpia tanto el rastreo de ActiveModel como nuestro rastreo dinámico.
+    def clear_changes_information
+      super
+      @dynamic_changes.clear
     end
 
-    # Prioridad Exchange: 1. Instancia (Capturada), 2. Clase
-    def current_exchange
-      @exchange || self.class.current_exchange
+    # Serialización combinada.
+    # @return [Hash]
+    def attributes_for_serialization
+      @remote_attributes.merge(attributes)
     end
 
-    # Prioridad Exchange Type: 1. Instancia (Capturada), 2. Clase
-    def current_exchange_type
-      @exchange_type || self.class.current_exchange_type
-    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 solo los atributos que han cambiado.
+    # Retorna el hash combinado de cambios (Tipados + Dinámicos).
+    # @return [Hash]
     def changes_to_send
-      return changes.transform_values(&:last) unless changes.empty?
-      @remote_attributes.except('id', 'ID', 'Id', '_id')
+      # 1. Cambios de ActiveModel (Tipados)
+      payload = changes.transform_values(&:last)
+
+      # 2. Cambios Dinámicos (Manuales)
+      @dynamic_changes.each do |key|
+        payload[key] = @remote_attributes[key]
+      end
+
+      return payload unless payload.empty?
+
+      # Fallback: Si no hay cambios detectados, enviamos todo (útil para create)
+      attributes_for_serialization.except('id', 'ID', 'Id', '_id')
     end
 
-    # Métodos mágicos para atributos.
+    # Intercepta asignaciones dinámicas y las marca como sucias.
     def method_missing(method_name, *args, &block)
       attribute_name = method_name.to_s
       if attribute_name.end_with?('=')
         key = attribute_name.chop
         val = args.first
-        attribute_will_change!(key) unless @remote_attributes[key] == val
+
+        if @remote_attributes[key] != val
+          @dynamic_changes << key
+        end
+
         @remote_attributes[key] = val
       else
         @remote_attributes.key?(attribute_name) ? @remote_attributes[attribute_name] : super
@@ -300,51 +329,51 @@ module BugBunny
       @remote_attributes.key?(method_name.to_s.sub(/=$/, '')) || super
     end
 
+    # @return [Object] Valor del ID buscando en múltiples nomenclaturas.
     def id
-      @remote_attributes['id'] || @remote_attributes['ID'] || @remote_attributes['Id'] || @remote_attributes['_id']
+      attributes['id'] || @remote_attributes['id'] || @remote_attributes['ID'] || @remote_attributes['Id'] || @remote_attributes['_id']
     end
 
     def id=(value)
-      @remote_attributes['id'] = value
+      if self.class.attribute_names.include?('id')
+        super(value)
+      else
+        @remote_attributes['id'] = value
+      end
     end
 
     def read_attribute_for_validation(attr)
-      @remote_attributes[attr.to_s]
+      attr_s = attr.to_s
+      self.class.attribute_names.include?(attr_s) ? attribute(attr_s) : @remote_attributes[attr_s]
     end
 
-    # @!group Persistencia RESTful
+    # @!group Persistencia
 
-    # Guarda el registro.
-    # Envía POST si es nuevo, PUT si ya existe.
-    #
-    # **AUTOMÁTICO:** Envuelve los parámetros en la clave del modelo (`param_key`).
-    # Ej: Manager::Service -> "service". Esto facilita `params.require(:service)`.
-    #
-    # @return [Boolean] true si se guardó correctamente.
+    # Guarda el recurso en el servidor remoto vía AMQP (POST o PUT).
+    # @return [Boolean]
     def save
       return false unless valid?
 
       run_callbacks(:save) do
         is_new = !persisted?
         rk = calculate_routing_key(id)
-
-        # 1. Obtenemos el payload plano (atributos modificados)
         flat_payload = changes_to_send
-
-        # 2. Wrappeamos automáticamente en la clave del modelo
         key = self.class.param_key
         wrapped_payload = { key => flat_payload }
 
-        # Mapeo a verbos HTTP
-        if is_new
-          # REST: POST resource (Create)
-          path = self.class.resource_name
-          response = bug_bunny_client.request(path, method: :post, exchange: current_exchange, exchange_type: current_exchange_type, routing_key: rk, body: wrapped_payload)
-        else
-          # REST: PUT resource/id (Update)
-          path = "#{self.class.resource_name}/#{id}"
-          response = bug_bunny_client.request(path, method: :put, exchange: current_exchange, exchange_type: current_exchange_type, routing_key: rk, body: wrapped_payload)
-        end
+        path = is_new ? self.class.resource_name : "#{self.class.resource_name}/#{id}"
+        method = is_new ? :post : :put
+
+        response = bug_bunny_client.request(
+          path,
+          method: method,
+          exchange: current_exchange,
+          exchange_type: current_exchange_type,
+          routing_key: rk,
+          exchange_options: @exchange_options,
+          queue_options: @queue_options,
+          body: wrapped_payload
+        )
 
         handle_save_response(response)
       end
@@ -353,16 +382,23 @@ module BugBunny
       false
     end
 
-    # Elimina el registro.
-    # Envía DELETE resource/id.
+    # 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
@@ -373,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'])
@@ -388,6 +425,7 @@ module BugBunny
       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)