bug_bunny 3.0.1 → 3.0.2

data/lib/bug_bunny/consumer.rb

@@ -8,20 +8,37 @@ require 'cgi'
 module BugBunny
   # Consumidor de mensajes y Router RPC estilo REST.
   #
-  # Parsea el header `type` (URL) y el header `x-http-method` (Verbo)
-  # para despachar al controlador y acción correctos siguiendo convenciones Rails.
+  # Esta clase se encarga de escuchar una cola específica, deserializar los mensajes,
+  # interpretar los headers REST (`x-http-method`, `type`) y despacharlos al
+  # controlador correspondiente.
+  #
+  # También gestiona el ciclo de vida de la respuesta RPC, asegurando que siempre
+  # se envíe una contestación (éxito o error) para evitar timeouts en el cliente.
   class Consumer
+    # @return [BugBunny::Session] La sesión de RabbitMQ wrapper.
     attr_reader :session
 
+    # Método de conveniencia para instanciar y suscribir en un solo paso.
+    # @param connection [Bunny::Session] Conexión activa.
+    # @param args [Hash] Argumentos para {#subscribe}.
     def self.subscribe(connection:, **args)
       new(connection).subscribe(**args)
     end
 
+    # Inicializa el consumidor.
+    # @param connection [Bunny::Session] Conexión nativa de Bunny.
     def initialize(connection)
       @session = BugBunny::Session.new(connection)
     end
 
-    # Inicia la suscripción a la cola.
+    # Inicia la suscripción a la cola y el procesamiento de mensajes.
+    #
+    # @param queue_name [String] Nombre de la cola a escuchar.
+    # @param exchange_name [String] Exchange al que se bindeará la cola.
+    # @param routing_key [String] Routing key para el binding.
+    # @param exchange_type [String] Tipo de exchange ('direct', 'topic', etc).
+    # @param queue_opts [Hash] Opciones de declaración de la cola (durable, auto_delete).
+    # @param block [Boolean] Si es true, bloquea el hilo principal (loop).
     def subscribe(queue_name:, exchange_name:, routing_key:, exchange_type: 'direct', queue_opts: {}, block: true)
       x = session.exchange(name: exchange_name, type: exchange_type)
       q = session.queue(queue_name, queue_opts)
@@ -41,8 +58,16 @@ module BugBunny
 
     private
 
-    # Procesa el mensaje entrante.
-    # Infiere la acción basándose en Verbo + URL.
+    # Procesa un mensaje individual.
+    #
+    # 1. Parsea headers y body.
+    # 2. Enruta al controlador/acción.
+    # 3. Envía la respuesta RPC si es necesario.
+    # 4. Maneja excepciones y envía errores formateados al cliente.
+    #
+    # @param delivery_info [Bunny::DeliveryInfo] Metadatos de entrega.
+    # @param properties [Bunny::MessageProperties] Headers y propiedades AMQP.
+    # @param body [String] Payload del mensaje.
     def process_message(delivery_info, properties, body)
       if properties.type.nil? || properties.type.empty?
         BugBunny.configuration.logger.error("[Consumer] Missing 'type'. Rejected.")
@@ -50,11 +75,9 @@ module BugBunny
         return
       end
 
-      # 1. Leemos el verbo HTTP desde el header (Default: GET)
-      # Nota: Bunny devuelve los headers en propiedades.headers
       http_method = properties.headers ? (properties.headers['x-http-method'] || 'GET') : 'GET'
 
-      # 2. Despachamos usando lógica Rails
+      # Inferencia de rutas (Router)
       route_info = router_dispatch(http_method, properties.type)
 
       headers = {
@@ -69,78 +92,78 @@ module BugBunny
         reply_to: properties.reply_to
       }
 
-      # Convention: "users" -> Rabbit::Controllers::UsersController
+      # 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
 
+      # Ejecución del pipeline del controlador
       response_payload = controller_class.call(headers: headers, body: body)
 
+      # Respuesta RPC (Éxito)
       if properties.reply_to
         reply(response_payload, properties.reply_to, properties.correlation_id)
       end
 
       session.channel.ack(delivery_info.delivery_tag)
+
     rescue NameError => e
-      BugBunny.configuration.logger.error("[Consumer] Controller/Action not found: #{e.message}")
+      # Caso: Controlador o Acción no existen (404/501)
+      BugBunny.configuration.logger.error("[Consumer] Routing Error: #{e.message}")
+
+      # FIX CRÍTICO: Responder con error para evitar Timeout en el cliente
+      if properties.reply_to
+        error_payload = { status: 501, body: { error: "Routing Error", detail: e.message } }
+        reply(error_payload, properties.reply_to, properties.correlation_id)
+      end
+
       session.channel.reject(delivery_info.delivery_tag, false)
+
     rescue StandardError => e
+      # Caso: Crash interno de la aplicación (500)
       BugBunny.configuration.logger.error("[Consumer] Execution Error: #{e.message}")
-      session.channel.reject(delivery_info.delivery_tag, false)
+
+      # FIX CRÍTICO: Responder con 500 para evitar Timeout
       if properties.reply_to
-        reply({ error: e.message }, properties.reply_to, properties.correlation_id)
+        error_payload = { status: 500, body: { error: "Internal Server Error", detail: e.message } }
+        reply(error_payload, properties.reply_to, properties.correlation_id)
       end
+
+      session.channel.reject(delivery_info.delivery_tag, false)
     end
 
-    # Router: Simula el config/routes.rb de Rails.
+    # Simula el Router de Rails.
+    # Convierte Verbo + Path en Controlador + Acción + ID.
     #
-    # @param method [String] Verbo HTTP (GET, POST, etc).
-    # @param path [String] URL Path (ej: 'users/1').
-    # @return [Hash] {controller, action, id, params}
+    # @return [Hash] { controller, action, id, params }
     def router_dispatch(method, path)
       uri = URI.parse("http://dummy/#{path}")
-      segments = uri.path.split('/').reject(&:empty?) # ["users", "123"]
+      segments = uri.path.split('/').reject(&:empty?)
       query_params = uri.query ? CGI.parse(uri.query).transform_values(&:first) : {}
 
-      controller_name = segments[0] # "users"
-      id = segments[1]              # "123" o nil
+      controller_name = segments[0]
+      id = segments[1]
 
-      # Lógica de Inferencia Rails Standard
-      # GET users      -> index
-      # GET users/1    -> show
-      # POST users     -> create
-      # PUT users/1    -> update
-      # DELETE users/1 -> destroy
       action = case method.to_s.upcase
-               when 'GET'
-                 id ? 'show' : 'index'
-               when 'POST'
-                 'create'
-               when 'PUT', 'PATCH'
-                 'update'
-               when 'DELETE'
-                 'destroy'
-               else
-                 id || 'index' # Fallback para verbos custom
+               when 'GET' then id ? 'show' : 'index'
+               when 'POST' then 'create'
+               when 'PUT', 'PATCH' then 'update'
+               when 'DELETE' then 'destroy'
+               else id || 'index'
                end
 
-      # Soporte para Member Actions Custom (ej: POST users/1/activate)
-      # Path: users/1/activate -> segments: [users, 1, activate]
+      # Soporte para Custom Member Actions (POST users/1/promote)
       if segments.size >= 3
          id = segments[1]
          action = segments[2]
       end
 
-      # Inyectar ID en params para acceso unificado en el controller
       query_params['id'] = id if id
 
-      {
-        controller: controller_name,
-        action: action,
-        id: id,
-        params: query_params
-      }
+      { controller: controller_name, action: action, id: id, params: query_params }
     end
 
+    # Envía la respuesta a la cola temporal del cliente (Direct Reply-to).
     def reply(payload, reply_to, correlation_id)
       session.channel.default_exchange.publish(
         payload.to_json,
@@ -150,6 +173,7 @@ module BugBunny
       )
     end
 
+    # Tarea de fondo para asegurar que la cola sigue existiendo.
     def start_health_check(q_name)
       Concurrent::TimerTask.new(execution_interval: 60) do
         session.channel.queue_declare(q_name, passive: true)

data/lib/bug_bunny/controller.rb

@@ -6,109 +6,183 @@ module BugBunny
   # Clase base para Controladores de Mensajes.
   #
   # Provee una abstracción similar a ActionController para manejar peticiones RPC.
-  # Unifica el acceso a parámetros (`params`) independientemente de si vinieron
-  # en el cuerpo del mensaje, en la URL (query string) o en la ruta (ID).
+  # Incluye soporte para `before_action`, manejo de excepciones declarativo (`rescue_from`)
+  # y normalización de parámetros.
   class Controller
     include ActiveModel::Model
     include ActiveModel::Attributes
 
-    # @return [Hash] Metadatos completos (headers, query_params, route info).
+    # @return [Hash] Metadatos del mensaje (headers AMQP, routing info).
     attribute :headers
 
-    # @return [ActiveSupport::HashWithIndifferentAccess] Parámetros unificados.
+    # @return [ActiveSupport::HashWithIndifferentAccess] Parámetros unificados (Body + Query + Route).
     attribute :params
 
-    # @return [String] Cuerpo crudo si no es JSON.
+    # @return [String] Cuerpo crudo si el payload no es JSON.
     attribute :raw_string
 
-    # @return [Hash] Respuesta renderizada.
+    # @return [Hash, nil] La respuesta renderizada { status, body }.
     attr_reader :rendered_response
 
+    # --- INFRAESTRUCTURA DE FILTROS (Before Actions) ---
+
     # @api private
     def self.before_actions
-      @before_actions ||= Hash.new { |hash, key| hash[key] = [] }
+      @before_actions ||= Hash.new { |h, k| h[k] = [] }
     end
 
-    # Registra un callback before_action.
+    # 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]
     def self.before_action(method_name, **options)
-      actions = options.delete(:only) || []
-      target = actions.empty? ? :_all_actions : actions
-      Array(target).each do |action|
-        key = action == :_all_actions ? :_all_actions : action.to_sym
-        before_actions[key] << method_name
+      only = Array(options[:only]).map(&:to_sym)
+      target_actions = only.empty? ? [:_all_actions] : only
+
+      target_actions.each do |action|
+        before_actions[action] << method_name
       end
     end
 
-    # Pipeline de ejecución principal.
-    # @param headers [Hash] Metadatos parseados por el Consumer.
-    # @param body [String, Hash] Payload.
+    # --- INFRAESTRUCTURA DE MANEJO DE ERRORES (Rescue From) ---
+
+    # @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: {})
-      controller = new(headers: headers)
-      controller.prepare_params(body)
+      new(headers: headers).process(body)
+    end
 
-      return controller.rendered_response unless controller.run_callbacks
+    # 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)
+      action_name = headers[:action].to_sym
 
-      action_method = controller.headers[:action].to_sym
-      if controller.respond_to?(action_method)
-        controller.send(action_method)
+      # 1. Ejecutar Before Actions (si retorna false, hubo render/halt)
+      return rendered_response unless run_before_actions(action_name)
+
+      # 2. Ejecutar Acción
+      if respond_to?(action_name)
+        public_send(action_name)
       else
-        raise NameError, "Action '#{action_method}' not found in #{name}"
+        raise NameError, "Action '#{action_name}' not found in #{self.class.name}"
       end
 
-      controller.rendered_response || { status: 204, body: nil }
+      # 3. Respuesta por defecto (204 No Content) si la acción no llamó a render
+      rendered_response || { status: 204, body: nil }
+
     rescue StandardError => e
-      rescue_from(e)
+      handle_exception(e)
+    end
+
+    private
+
+    # Busca un manejador registrado para la excepción y lo ejecuta.
+    # Si no hay ninguno, loguea y devuelve 500.
+    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) }
+
+      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)
+        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
 
-    # Construye la respuesta RPC.
-    # @param status [Symbol, Integer] Código HTTP equivalente (ej: :ok, 422).
-    # @param json [Object] Objeto a devolver.
+    # 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
+    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 }
     end
 
-    # Unifica parámetros de múltiples fuentes en `params`.
+    # Normaliza y fusiona parámetros de múltiples fuentes.
     # Prioridad: Body > ID Ruta > Query Params.
-    #
-    # @param body [Hash, String] Payload.
     def prepare_params(body)
-      self.params ||= {}.with_indifferent_access
-
-      # 1. Query Params (de la URL ?active=true)
-      if headers[:query_params].present?
-        params.merge!(headers[:query_params])
-      end
+      self.params = {}.with_indifferent_access
 
-      # 2. ID explícito de ruta (/users/show/12)
+      params.merge!(headers[:query_params]) if headers[:query_params].present?
       params[:id] = headers[:id] if headers[:id].present?
 
-      # 3. Payload Body (JSON)
       if body.is_a?(Hash)
         params.merge!(body)
-      elsif body.is_a?(String) && headers[:content_type] =~ /json/
+      elsif body.is_a?(String) && headers[:content_type].to_s.include?('json')
         parsed = JSON.parse(body) rescue nil
         params.merge!(parsed) if parsed
       else
         self.raw_string = body
       end
     end
-
-    # Ejecuta callbacks. Retorna false si hubo `render` (halt).
-    # @api private
-    def run_callbacks
-      current = headers[:action].to_sym
-      chain = self.class.before_actions[:_all_actions] + self.class.before_actions[current]
-      chain.each do |method|
-        send(method)
-        return false if @rendered_response
-      end
-      true
-    end
-
-    def self.rescue_from(e)
-      BugBunny.configuration.logger.error("Controller Error: #{e.message}")
-      { status: 500, error: e.message }
-    end
   end
 end

data/lib/bug_bunny/producer.rb

@@ -37,7 +37,14 @@ module BugBunny
       payload = serialize_message(request.body)
       opts = request.amqp_options
 
-      BugBunny.configuration.logger.info("[BugBunny] Publishing to #{request.exchange}/#{request.final_routing_key}")
+      # 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}'")
 
       x.publish(payload, opts.merge(routing_key: request.final_routing_key))
     end
@@ -76,7 +83,8 @@ module BugBunny
         response_payload = future.value(wait_timeout)
 
         if response_payload.nil?
-          raise BugBunny::RequestTimeout, "Timeout waiting for RPC: #{request.action}"
+          # 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
 
         parse_response(response_payload)