bug_bunny 3.1.0 → 3.1.2

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

@@ -53,15 +53,27 @@ module BugBunny
     # @param exchange_name [String] Nombre del exchange al cual enlazar la cola.
     # @param routing_key [String] Patrón de enrutamiento (ej: 'users.*').
     # @param exchange_type [String] Tipo de exchange ('direct', 'topic', 'fanout').
+    # @param exchange_opts [Hash] Opciones adicionales para el exchange (durable, auto_delete).
     # @param queue_opts [Hash] Opciones adicionales para la cola (durable, auto_delete).
     # @param block [Boolean] Si es `true`, bloquea el hilo actual (loop infinito).
     # @return [void]
-    def subscribe(queue_name:, exchange_name:, routing_key:, exchange_type: 'direct', queue_opts: {}, block: true)
-      x = session.exchange(name: exchange_name, type: exchange_type)
+    def subscribe(queue_name:, exchange_name:, routing_key:, exchange_type: 'direct', exchange_opts: {}, queue_opts: {}, block: true)
+      # Declaración de Infraestructura
+      x = session.exchange(name: exchange_name, type: exchange_type, opts: exchange_opts)
       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})")
+      # 📊 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(exchange_opts || {})
+      final_q_opts = BugBunny::Session::DEFAULT_QUEUE_OPTIONS
+                       .merge(BugBunny.configuration.queue_options || {})
+                       .merge(queue_opts || {})
+
+      BugBunny.configuration.logger.info("[BugBunny::Consumer] 🎧 Listening on '#{queue_name}' (Opts: #{final_q_opts})")
+      BugBunny.configuration.logger.info("[BugBunny::Consumer] 🔀 Bounded to Exchange '#{exchange_name}' (#{exchange_type}) | Opts: #{final_x_opts} | RK: '#{routing_key}'")
+
       start_health_check(queue_name)
 
       q.subscribe(manual_ack: true, block: block) do |delivery_info, properties, body|
@@ -78,7 +90,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 +106,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 +122,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 +144,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 +152,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 +170,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 +227,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 +258,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

@@ -7,99 +7,146 @@ require 'active_support/core_ext/class/attribute'
 module BugBunny
   # Clase base para todos los Controladores de Mensajes en BugBunny.
   #
+  # Actúa como el receptor final de los mensajes enrutados desde el consumidor.
+  # Implementa un ciclo de vida similar a ActionController en Rails, soportando:
+  # - Filtros (`before_action`, `around_action`).
+  # - Manejo declarativo de errores (`rescue_from`).
+  # - Parsing de parámetros unificados (`params`).
+  # - Respuestas estructuradas (`render`).
+  #
   # @author Gabriel
   # @since 3.0.6
   class Controller
     include ActiveModel::Model
     include ActiveModel::Attributes
 
-    # @return [Hash] Metadatos del mensaje entrante.
+    # @!group Atributos de Instancia
+
+    # @return [Hash] Metadatos del mensaje entrante (ej. HTTP method, routing_key, id).
     attribute :headers
 
-    # @return [ActiveSupport::HashWithIndifferentAccess] Parámetros unificados.
+    # @return [ActiveSupport::HashWithIndifferentAccess] Parámetros unificados (Body JSON + Query String).
     attribute :params
 
-    # @return [String] Cuerpo crudo.
+    # @return [String] Cuerpo crudo original en caso de no ser JSON.
     attribute :raw_string
 
-    # @return [Hash] Headers de respuesta.
+    # @return [Hash] Headers de respuesta que serán enviados de vuelta en RPC.
     attr_reader :response_headers
 
-    # @return [Hash, nil] Respuesta renderizada.
+    # @return [Hash, nil] Respuesta final renderizada.
     attr_reader :rendered_response
 
-    # --- INFRAESTRUCTURA DE FILTROS (DEFINICIÓN) ---
-    # Deben definirse ANTES de ser usados por la configuración de logs.
+    # @!endgroup
 
-    # @api private
-    def self.before_actions
-      @before_actions ||= Hash.new { |h, k| h[k] = [] }
-    end
 
-    # @api private
-    def self.around_actions
-      @around_actions ||= Hash.new { |h, k| h[k] = [] }
-    end
+    # ==========================================
+    # INFRAESTRUCTURA DE FILTROS Y LOGS (HEREDABLES)
+    # ==========================================
+
+    # Usamos `class_attribute` con `default` para garantizar la herencia correcta
+    # hacia las subclases (ej. de ApplicationController a ServicesController).
+    class_attribute :before_actions, default: {}
+    class_attribute :around_actions, default: {}
+    class_attribute :log_tags, default: []
+    class_attribute :rescue_handlers, default: []
 
     # Registra un filtro que se ejecutará **antes** de la acción.
+    # Si el filtro invoca `render`, la cadena se interrumpe y la acción no se ejecuta.
+    #
+    # @param method_name [Symbol] Nombre del método privado a ejecutar.
+    # @param options [Hash] Opciones como `only: [:show, :update]`.
+    # @return [void]
     def self.before_action(method_name, **options)
-      register_callback(before_actions, method_name, options)
+      register_callback(:before_actions, method_name, options)
     end
 
     # Registra un filtro que **envuelve** la ejecución de la acción.
+    # El método registrado debe invocar `yield` para continuar la ejecución.
+    #
+    # @param method_name [Symbol] Nombre del método privado a ejecutar.
+    # @param options [Hash] Opciones como `only: [:index]`.
+    # @return [void]
     def self.around_action(method_name, **options)
-      register_callback(around_actions, 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 }
+    # Manejo declarativo de excepciones.
+    # Atrapa errores específicos que ocurran durante la ejecución de la acción.
+    #
+    # @example
+    #   rescue_from Api::Error::NotFound, with: :render_not_found
+    #   rescue_from StandardError do |e|
+    #     render status: 500, json: { error: e.message }
+    #   end
+    #
+    # @param klasses [Array<Class, String>] Clases de excepciones a atrapar.
+    # @param with [Symbol, nil] Nombre del método manejador.
+    # @yield [Exception] Bloque opcional para manejar el error inline.
+    # @raise [ArgumentError] Si no se provee un manejador (with o block).
+    def self.rescue_from(*klasses, with: nil, &block)
+      handler = with || block
+      raise ArgumentError, "Need a handler. Supply 'with: :method' or a block." unless handler
+
+      # Duplicamos el array del padre para no mutarlo al registrar reglas en el hijo
+      new_handlers = self.rescue_handlers.dup
+
+      klasses.each do |klass|
+        new_handlers.unshift([klass, handler])
+      end
+
+      self.rescue_handlers = new_handlers
     end
 
-    # --- CONFIGURACIÓN DE LOGGING ---
+    # Helper interno para registrar callbacks garantizando Thread-Safety e Inmutabilidad del padre.
+    # @api private
+    def self.register_callback(collection_name, method_name, options)
+      current_hash = send(collection_name)
 
-    # Define los tags que se antepondrán a cada línea de log.
-    class_attribute :log_tags
-    self.log_tags = []
+      # Deep dup: Clonamos el hash y sus arrays internos para no modificar la clase padre
+      new_hash = current_hash.transform_values(&:dup)
 
-    # AHORA SÍ: Podemos llamar a around_action porque ya fue definido arriba.
-    around_action :apply_log_tags
+      only = Array(options[:only]).map(&:to_sym)
+      target_actions = only.empty? ? [:_all_actions] : only
 
-    # --- INICIALIZACIÓN ---
+      target_actions.each do |action|
+        new_hash[action] ||= []
+        new_hash[action] << method_name
+      end
 
-    def initialize(attributes = {})
-      super
-      @response_headers = {}
+      send("#{collection_name}=", new_hash)
     end
 
-    # --- MANEJO DE ERRORES ---
+    # Aplicamos automáticamente las etiquetas de logs a todas las acciones.
+    around_action :apply_log_tags
 
-    # @api private
-    def self.rescue_handlers
-      @rescue_handlers ||= []
-    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
+    # ==========================================
+    # INICIALIZACIÓN Y CICLO DE VIDA
+    # ==========================================
 
-      klasses.each do |klass|
-        rescue_handlers.unshift([klass, handler])
-      end
+    def initialize(attributes = {})
+      super
+      @response_headers = {}
     end
 
-    # --- PIPELINE DE EJECUCIÓN ---
-
+    # Punto de entrada principal estático llamado por el Router (`BugBunny::Consumer`).
+    #
+    # @param headers [Hash] Metadatos y variables de enrutamiento.
+    # @param body [String, Hash] El payload del mensaje AMQP.
+    # @return [Hash] Respuesta final estructurada.
     def self.call(headers:, body: {})
       new(headers: headers).process(body)
     end
 
+    # Ejecuta el ciclo de vida completo de la petición: Params -> Before -> Action -> Rescue.
+    #
+    # @param body [String, Hash] El cuerpo del mensaje.
+    # @return [Hash] La respuesta lista para ser enviada vía RabbitMQ RPC.
     def process(body)
       prepare_params(body)
 
-      # Inyección de configuración global de logs si no hay específica
+      # Inyección de configuración global de logs si el controlador no define propios
       if self.class.log_tags.empty? && BugBunny.configuration.log_tags.any?
         self.class.log_tags = BugBunny.configuration.log_tags
       end
@@ -118,15 +165,14 @@ module BugBunny
         end
       end
 
-      # Construir la cadena de responsabilidad
+      # Construir e invocar la cadena de responsabilidad (Middlewares/Around Actions)
       execution_chain = current_arounds.reverse.inject(core_execution) do |next_step, method_name|
         lambda { send(method_name, &next_step) }
       end
 
-      # Ejecutar la cadena
       execution_chain.call
 
-      # Respuesta final
+      # Si no hubo renderización explícita, devuelve 204 No Content
       rendered_response || { status: 204, headers: response_headers, body: nil }
 
     rescue StandardError => e
@@ -135,21 +181,14 @@ module BugBunny
 
     private
 
-    # --- 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
+    # ==========================================
+    # HELPERS INTERNOS
+    # ==========================================
 
+    # Evalúa la excepción lanzada y busca el manejador más adecuado definido en `rescue_from`.
+    #
+    # @param exception [StandardError] La excepción atrapada.
+    # @return [Hash] Respuesta de error renderizada.
     def handle_exception(exception)
       handler_entry = self.class.rescue_handlers.find do |klass, _|
         if klass.is_a?(String)
@@ -161,24 +200,34 @@ module BugBunny
 
       if handler_entry
         _, handler = handler_entry
-        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
         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"))
+      # Fallback genérico si la excepción no fue mapeada
+      BugBunny.configuration.logger.error("[BugBunny::Controller] 💥 Unhandled Exception (#{exception.class}): #{exception.message}")
+      BugBunny.configuration.logger.error(exception.backtrace.first(5).join("\n"))
 
       {
         status: 500,
         headers: response_headers,
-        body: { error: exception.message, type: exception.class.name }
+        body: { error: "Internal Server Error", detail: exception.message, type: exception.class.name }
       }
     end
 
+    # Renderiza una respuesta que será enviada de vuelta por la cola reply-to.
+    #
+    # @param status [Symbol, Integer] Código HTTP (ej. :ok, :not_found, 201).
+    # @param json [Object] El payload a serializar como JSON.
+    # @return [Hash] La estructura renderizada interna.
     def render(status:, json: nil)
-      code = Rack::Utils::SYMBOL_TO_STATUS_CODE[status] || 200
+      code = Rack::Utils::SYMBOL_TO_STATUS_CODE[status] || status.to_i
+      code = 200 if code.zero? # Fallback de seguridad
+
       @rendered_response = {
         status: code,
         headers: response_headers,
@@ -186,21 +235,43 @@ module BugBunny
       }
     end
 
+    # Unifica el query string, parámetros de ruta y el body JSON en un solo objeto `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?
 
       if body.is_a?(Hash)
         params.merge!(body)
       elsif body.is_a?(String) && headers[:content_type].to_s.include?('json')
-        parsed = JSON.parse(body) rescue nil
+        parsed = begin
+                   JSON.parse(body)
+                 rescue JSON::ParserError
+                   nil
+                 end
         params.merge!(parsed) if parsed
       else
         self.raw_string = body
       end
     end
 
+    # Obtiene la lista combinada de callbacks globales y específicos para una acción.
+    def resolve_callbacks(collection, action_name)
+      (collection[:_all_actions] || []) + (collection[action_name] || [])
+    end
+
+    # Ejecuta secuencialmente todos los before_actions.
+    # Si alguno invoca render(), detiene el flujo devolviendo `false`.
+    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
+
     # --- LÓGICA DE LOGGING ENCAPSULADA ---
 
     def apply_log_tags
@@ -225,6 +296,7 @@ module BugBunny
       end.compact
     end
 
+    # @return [String] Identificador único de trazabilidad de la petición.
     def uuid
       headers[:correlation_id] || headers['X-Request-Id']
     end