bug_bunny 3.0.6 → 3.1.1

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
@@ -57,10 +64,30 @@ module BugBunny
     # @return [Integer] Intervalo en segundos para verificar la salud de la cola.
     attr_accessor :health_check_interval
 
+    # @return [String] Namespace base donde se buscarán los controladores (default: 'Rabbit::Controllers').
+    attr_accessor :controller_namespace
+
+    # @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' # Valor por defecto explícito
-      @port = 5672        # <--- AGREGADO (Default RabbitMQ Port)
+      @host = '127.0.0.1'
+      @port = 5672
       @username = 'guest'
       @password = 'guest'
       @vhost = '/'
@@ -80,9 +107,19 @@ module BugBunny
       @channel_prefetch = 1
       @rpc_timeout = 10
       @health_check_interval = 60
+
+      # Configuración por defecto para mantener compatibilidad
+      @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,14 +61,24 @@ 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|
-        process_message(delivery_info, properties, body)
+        trace_id = properties.correlation_id
+
+        logger = BugBunny.configuration.logger
+
+        if logger.respond_to?(:tagged)
+          logger.tagged(trace_id) { process_message(delivery_info, properties, body) }
+        elsif defined?(Rails) && Rails.logger.respond_to?(:tagged)
+          Rails.logger.tagged(trace_id) { process_message(delivery_info, properties, body) }
+        else
+          process_message(delivery_info, properties, body)
+        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
@@ -84,20 +94,27 @@ module BugBunny
     # @param body [String] El payload crudo del mensaje.
     # @return [void]
     def process_message(delivery_info, properties, body)
-      if properties.type.nil? || properties.type.empty?
-        BugBunny.configuration.logger.error("[Consumer] Missing 'type' header. Message rejected.")
+      # 1. Validación de Headers
+      path = properties.type || (properties.headers && properties.headers['path'])
+
+      if path.nil? || path.empty?
+        BugBunny.configuration.logger.error("[BugBunny::Consumer] ⛔ Rejected: Missing 'type' header.")
         session.channel.reject(delivery_info.delivery_tag, false)
         return
       end
 
-      # 1. Determinar Verbo HTTP (Default: GET)
-      http_method = properties.headers ? (properties.headers['x-http-method'] || 'GET') : 'GET'
+      # 2. Recuperación Robusta del Verbo HTTP
+      headers_hash = properties.headers || {}
+      http_method = headers_hash['x-http-method'] || headers_hash['method'] || 'GET'
+
+      # 3. Router: Inferencia de Controlador y Acción
+      route_info = router_dispatch(http_method, path)
 
-      # 2. Router: Inferencia de Controlador y Acción
-      route_info = router_dispatch(http_method, properties.type)
+      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)}")
 
-      headers = {
-        type: properties.type,
+      request_metadata = {
+        type: path,
         http_method: http_method,
         controller: route_info[:controller],
         action: route_info[:action],
@@ -106,33 +123,42 @@ module BugBunny
         content_type: properties.content_type,
         correlation_id: properties.correlation_id,
         reply_to: properties.reply_to
-      }
+      }.merge(properties.headers)
+
+      # 4. Instanciación Dinámica del Controlador
+      # Utilizamos el namespace configurado en lugar de hardcodear "Rabbit::Controllers"
+      begin
+        namespace = BugBunny.configuration.controller_namespace
+        controller_name = route_info[:controller].camelize
 
-      # 3. Instanciación Dinámica del Controlador
-      # Ej: "users" -> Rabbit::Controllers::UsersController
-      controller_class_name = "rabbit/controllers/#{route_info[:controller]}".camelize
-      controller_class = controller_class_name.constantize
+        # Construcción: "Messaging::Handlers" + "::" + "Users"
+        controller_class_name = "#{namespace}::#{controller_name}Controller"
 
-      # 4. Ejecución del Pipeline (Filtros -> Acción)
-      response_payload = controller_class.call(headers: headers, body: body)
+        controller_class = controller_class_name.constantize
 
-      # 5. Respuesta RPC (Si se solicita respuesta)
+        unless controller_class < BugBunny::Controller
+          raise BugBunny::SecurityError, "Class #{controller_class} is not a valid BugBunny Controller"
+        end
+      rescue NameError => _e
+        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
+      end
+
+      # 5. Ejecución del Pipeline (Middleware + Acción)
+      response_payload = controller_class.call(headers: request_metadata, body: body)
+
+      # 6. Respuesta RPC
       if properties.reply_to
         reply(response_payload, properties.reply_to, properties.correlation_id)
       end
 
-      # 6. Acknowledge (Confirmación de procesado)
+      # 7. Acknowledge
       session.channel.ack(delivery_info.delivery_tag)
 
-    rescue NameError => e
-      # Error 501/404: El controlador o la acción no existen.
-      BugBunny.configuration.logger.error("[Consumer] Routing Error: #{e.message}")
-      handle_fatal_error(properties, 501, "Routing Error", e.message)
-      session.channel.reject(delivery_info.delivery_tag, false)
-
     rescue StandardError => e
-      # Error 500: Crash interno de la aplicación.
-      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
@@ -189,6 +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("[BugBunny::Consumer] 📤 Sending RPC Reply to #{reply_to} | ID: #{correlation_id}")
       session.channel.default_exchange.publish(
         payload.to_json,
         routing_key: reply_to,
@@ -219,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

@@ -1,115 +1,133 @@
-# lib/bug_bunny/controller.rb
+# frozen_string_literal: true
+
 require 'active_model'
 require 'rack'
+require 'active_support/core_ext/class/attribute'
 
 module BugBunny
-  # Clase base para Controladores de Mensajes.
+  # Clase base para todos los Controladores de Mensajes en BugBunny.
   #
-  # Provee una abstracción similar a ActionController para manejar peticiones RPC.
-  # Incluye soporte para `before_action`, manejo de excepciones declarativo (`rescue_from`)
-  # y normalización de parámetros.
+  # @author Gabriel
+  # @since 3.0.6
   class Controller
     include ActiveModel::Model
     include ActiveModel::Attributes
 
-    # @return [Hash] Metadatos del mensaje (headers AMQP, routing info).
+    # @return [Hash] Metadatos del mensaje entrante.
     attribute :headers
 
-    # @return [ActiveSupport::HashWithIndifferentAccess] Parámetros unificados (Body + Query + Route).
+    # @return [ActiveSupport::HashWithIndifferentAccess] Parámetros unificados.
     attribute :params
 
-    # @return [String] Cuerpo crudo si el payload no es JSON.
+    # @return [String] Cuerpo crudo.
     attribute :raw_string
 
-    # @return [Hash, nil] La respuesta renderizada { status, body }.
+    # @return [Hash] Headers de respuesta.
+    attr_reader :response_headers
+
+    # @return [Hash, nil] Respuesta renderizada.
     attr_reader :rendered_response
 
-    # --- INFRAESTRUCTURA DE FILTROS (Before Actions) ---
+    # --- INFRAESTRUCTURA DE FILTROS (DEFINICIÓN) ---
+    # Deben definirse ANTES de ser usados por la configuración de logs.
 
     # @api private
     def self.before_actions
       @before_actions ||= Hash.new { |h, k| h[k] = [] }
     end
 
-    # Registra un callback que se ejecutará antes de las acciones.
-    #
-    # @param method_name [Symbol] Nombre del método a ejecutar.
-    # @param options [Hash] Opciones de filtro (:only).
-    # @example
-    #   before_action :set_user, only: [:show, :update]
+    # @api private
+    def self.around_actions
+      @around_actions ||= Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Registra un filtro que se ejecutará **antes** de la acción.
     def self.before_action(method_name, **options)
+      register_callback(before_actions, method_name, options)
+    end
+
+    # Registra un filtro que **envuelve** la ejecución de la acción.
+    def self.around_action(method_name, **options)
+      register_callback(around_actions, method_name, options)
+    end
+
+    # Helper interno para registrar callbacks.
+    def self.register_callback(collection, method_name, options)
       only = Array(options[:only]).map(&:to_sym)
       target_actions = only.empty? ? [:_all_actions] : only
+      target_actions.each { |action| collection[action] << method_name }
+    end
 
-      target_actions.each do |action|
-        before_actions[action] << method_name
-      end
+    # --- CONFIGURACIÓN DE LOGGING ---
+
+    # Define los tags que se antepondrán a cada línea de log.
+    class_attribute :log_tags
+    self.log_tags = []
+
+    # AHORA SÍ: Podemos llamar a around_action porque ya fue definido arriba.
+    around_action :apply_log_tags
+
+    # --- INICIALIZACIÓN ---
+
+    def initialize(attributes = {})
+      super
+      @response_headers = {}
     end
 
-    # --- INFRAESTRUCTURA DE MANEJO DE ERRORES (Rescue From) ---
+    # --- MANEJO DE ERRORES ---
 
     # @api private
     def self.rescue_handlers
       @rescue_handlers ||= []
     end
 
-    # Registra un manejador para una o más excepciones.
-    # Los manejadores se evalúan en orden inverso (el último registrado tiene prioridad).
-    #
-    # @param klasses [Class] Clases de excepción a capturar.
-    # @param with [Symbol] Nombre del método manejador.
-    # @param block [Proc] Bloque manejador.
-    #
-    # @example Con método
-    #   rescue_from User::NotAuthorized, with: :deny_access
-    #
-    # @example Con bloque
-    #   rescue_from ActiveRecord::RecordNotFound do |e|
-    #     render status: :not_found, json: { error: e.message }
-    #   end
     def self.rescue_from(*klasses, with: nil, &block)
       handler = with || block
       raise ArgumentError, "Need a handler. Supply 'with: :method' or a block." unless handler
 
       klasses.each do |klass|
-        # Insertamos al principio para que las últimas definiciones tengan prioridad (LIFO)
         rescue_handlers.unshift([klass, handler])
       end
     end
 
     # --- PIPELINE DE EJECUCIÓN ---
 
-    # Punto de entrada principal llamado por el Consumer.
-    # Instancia el controlador y procesa el mensaje.
-    #
-    # @param headers [Hash] Metadatos del mensaje.
-    # @param body [Hash, String] Payload deserializado.
-    # @return [Hash] La respuesta final { status, body }.
     def self.call(headers:, body: {})
       new(headers: headers).process(body)
     end
 
-    # Ejecuta el ciclo de vida de la petición: Params -> Filtros -> Acción.
-    # Captura cualquier error y delega al sistema `rescue_from`.
-    #
-    # @param body [Hash, String] Payload.
-    # @return [Hash] Respuesta RPC.
     def process(body)
       prepare_params(body)
+
+      # Inyección de configuración global de logs si no hay específica
+      if self.class.log_tags.empty? && BugBunny.configuration.log_tags.any?
+        self.class.log_tags = BugBunny.configuration.log_tags
+      end
+
       action_name = headers[:action].to_sym
+      current_arounds = resolve_callbacks(self.class.around_actions, action_name)
 
-      # 1. Ejecutar Before Actions (si retorna false, hubo render/halt)
-      return rendered_response unless run_before_actions(action_name)
+      # Definir el núcleo de ejecución
+      core_execution = lambda do
+        return unless run_before_actions(action_name)
 
-      # 2. Ejecutar Acción
-      if respond_to?(action_name)
-        public_send(action_name)
-      else
-        raise NameError, "Action '#{action_name}' not found in #{self.class.name}"
+        if respond_to?(action_name)
+          public_send(action_name)
+        else
+          raise NameError, "Action '#{action_name}' not found in #{self.class.name}"
+        end
+      end
+
+      # Construir la cadena de responsabilidad
+      execution_chain = current_arounds.reverse.inject(core_execution) do |next_step, method_name|
+        lambda { send(method_name, &next_step) }
       end
 
-      # 3. Respuesta por defecto (204 No Content) si la acción no llamó a render
-      rendered_response || { status: 204, body: nil }
+      # Ejecutar la cadena
+      execution_chain.call
+
+      # Respuesta final
+      rendered_response || { status: 204, headers: response_headers, body: nil }
 
     rescue StandardError => e
       handle_exception(e)
@@ -117,61 +135,59 @@ module BugBunny
 
     private
 
-    # Busca un manejador registrado para la excepción y lo ejecuta.
-    # Si no hay ninguno, loguea y devuelve 500.
+    # --- HELPERS INTERNOS ---
+
+    def resolve_callbacks(collection, action_name)
+      (collection[:_all_actions] || []) + (collection[action_name] || [])
+    end
+
+    def run_before_actions(action_name)
+      current_befores = resolve_callbacks(self.class.before_actions, action_name)
+      current_befores.uniq.each do |method_name|
+        send(method_name)
+        return false if rendered_response
+      end
+      true
+    end
+
     def handle_exception(exception)
-      # Buscamos el primer handler compatible con la clase del error
-      handler_entry = self.class.rescue_handlers.find { |klass, _| exception.is_a?(klass) }
+      handler_entry = self.class.rescue_handlers.find do |klass, _|
+        if klass.is_a?(String)
+          exception.class.name == klass
+        else
+          exception.is_a?(klass)
+        end
+      end
 
       if handler_entry
         _, handler = handler_entry
-
-        # Ejecutamos el handler en el contexto de la INSTANCIA
-        if handler.is_a?(Symbol)
-          send(handler, exception)
-        elsif handler.respond_to?(:call)
-          instance_exec(exception, &handler)
+        if handler.is_a?(Symbol); send(handler, exception)
+        elsif handler.respond_to?(:call); instance_exec(exception, &handler)
         end
-
-        # Si el handler hizo render, retornamos esa respuesta
         return rendered_response if rendered_response
       end
 
-      # === FALLBACK POR DEFECTO ===
-      # Si el error no fue rescatado por el usuario, actuamos como red de seguridad.
-      BugBunny.configuration.logger.error("Controller Error (#{exception.class}): #{exception.message}")
-      BugBunny.configuration.logger.error(exception.backtrace.join("\n"))
-
-      { status: 500, body: { error: exception.message, type: exception.class.name } }
-    end
+      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
 
-    # Ejecuta la cadena de filtros before_action.
-    def run_before_actions(action_name)
-      chain = (self.class.before_actions[:_all_actions] || []) +
-              (self.class.before_actions[action_name] || [])
-
-      chain.uniq.each do |method_name|
-        send(method_name)
-        # Si un filtro llamó a 'render', detenemos la cadena (halt)
-        return false if rendered_response
-      end
-      true
+      {
+        status: 500,
+        headers: response_headers,
+        body: { error: exception.message, type: exception.class.name }
+      }
     end
 
-    # Construye la respuesta RPC normalizada.
-    #
-    # @param status [Symbol, Integer] Código HTTP (ej: :ok, 200, :not_found).
-    # @param json [Object] Objeto a serializar en el body.
     def render(status:, json: nil)
       code = Rack::Utils::SYMBOL_TO_STATUS_CODE[status] || 200
-      @rendered_response = { status: code, body: json }
+      @rendered_response = {
+        status: code,
+        headers: response_headers,
+        body: json
+      }
     end
 
-    # Normaliza y fusiona parámetros de múltiples fuentes.
-    # Prioridad: Body > ID Ruta > Query Params.
     def prepare_params(body)
       self.params = {}.with_indifferent_access
-
       params.merge!(headers[:query_params]) if headers[:query_params].present?
       params[:id] = headers[:id] if headers[:id].present?
 
@@ -184,5 +200,33 @@ module BugBunny
         self.raw_string = body
       end
     end
+
+    # --- LÓGICA DE LOGGING ENCAPSULADA ---
+
+    def apply_log_tags
+      tags = compute_tags
+      if defined?(Rails) && Rails.logger.respond_to?(:tagged) && tags.any?
+        Rails.logger.tagged(*tags) { yield }
+      else
+        yield
+      end
+    end
+
+    def compute_tags
+      self.class.log_tags.map do |tag|
+        case tag
+        when Proc
+          tag.call(self)
+        when Symbol
+          respond_to?(tag, true) ? send(tag) : tag
+        else
+          tag
+        end
+      end.compact
+    end
+
+    def uuid
+      headers[:correlation_id] || headers['X-Request-Id']
+    end
   end
 end

data/lib/bug_bunny/exception.rb

@@ -10,6 +10,10 @@ module BugBunny
   # Suele envolver excepciones nativas de la gema `bunny` (ej: TCP connection failure).
   class CommunicationError < Error; end
 
+  # Error lanzado cuando ocurren un acceso no permitido a controladores.
+  # Suele envolver excepciones nativas de la gema `bunny` (ej: TCP connection failure).
+  class SecurityError < Error; end
+
   # === Categoría: Errores del Cliente (4xx) ===
 
   # Clase base para errores causados por una petición incorrecta del cliente.