bug_bunny 3.0.1 → 3.0.3

data/lib/bug_bunny/consumer.rb

@@ -4,24 +4,58 @@ require 'concurrent'
 require 'json'
 require 'uri'
 require 'cgi'
+require 'rack/utils' # Necesario para parse_nested_query
 
 module BugBunny
-  # Consumidor de mensajes y Router RPC estilo REST.
+  # Consumidor de mensajes AMQP que actúa como un Router RESTful.
   #
-  # 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 es el corazón del procesamiento de mensajes en el lado del servidor/worker.
+  # Sus responsabilidades son:
+  # 1. Escuchar una cola específica.
+  # 2. Deserializar el mensaje y sus headers.
+  # 3. Enrutar el mensaje a un Controlador (`BugBunny::Controller`) basándose en el "path" y el verbo HTTP.
+  # 4. Gestionar el ciclo de respuesta RPC (Request-Response) para evitar timeouts en el cliente.
+  #
+  # @example Suscripción manual
+  #   connection = BugBunny.create_connection
+  #   BugBunny::Consumer.subscribe(
+  #     connection: connection,
+  #     queue_name: 'my_app_queue',
+  #     exchange_name: 'my_exchange',
+  #     routing_key: 'users.#'
+  #   )
   class Consumer
+    # @return [BugBunny::Session] La sesión wrapper de RabbitMQ que gestiona el canal.
     attr_reader :session
 
+    # Método de conveniencia para instanciar y suscribir en un solo paso.
+    #
+    # @param connection [Bunny::Session] Una conexión TCP activa a RabbitMQ.
+    # @param args [Hash] Argumentos que se pasarán al método {#subscribe}.
+    # @return [BugBunny::Consumer] La instancia del consumidor creada.
     def self.subscribe(connection:, **args)
       new(connection).subscribe(**args)
     end
 
+    # Inicializa un nuevo 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 comienza el bucle de procesamiento.
+    #
+    # Declara el exchange y la cola (si no existen), realiza el "binding" y
+    # se queda escuchando mensajes entrantes.
+    #
+    # @param queue_name [String] Nombre de la cola a escuchar.
+    # @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 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)
       q = session.queue(queue_name, queue_opts)
@@ -41,20 +75,25 @@ module BugBunny
 
     private
 
-    # Procesa el mensaje entrante.
-    # Infiere la acción basándose en Verbo + URL.
+    # Procesa un mensaje individual recibido de la cola.
+    #
+    # Realiza la orquestación completa: Parsing -> Routing -> Ejecución -> Respuesta.
+    #
+    # @param delivery_info [Bunny::DeliveryInfo] Metadatos de entrega (tag, redelivered, etc).
+    # @param properties [Bunny::MessageProperties] Headers y propiedades AMQP (reply_to, correlation_id).
+    # @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'. Rejected.")
+        BugBunny.configuration.logger.error("[Consumer] Missing 'type' header. Message rejected.")
         session.channel.reject(delivery_info.delivery_tag, false)
         return
       end
 
-      # 1. Leemos el verbo HTTP desde el header (Default: GET)
-      # Nota: Bunny devuelve los headers en propiedades.headers
+      # 1. Determinar Verbo HTTP (Default: GET)
       http_method = properties.headers ? (properties.headers['x-http-method'] || 'GET') : 'GET'
 
-      # 2. Despachamos usando lógica Rails
+      # 2. Router: Inferencia de Controlador y Acción
       route_info = router_dispatch(http_method, properties.type)
 
       headers = {
@@ -69,78 +108,86 @@ module BugBunny
         reply_to: properties.reply_to
       }
 
-      # Convention: "users" -> Rabbit::Controllers::UsersController
+      # 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
 
+      # 4. Ejecución del Pipeline (Filtros -> Acción)
       response_payload = controller_class.call(headers: headers, body: body)
 
+      # 5. Respuesta RPC (Si se solicita respuesta)
       if properties.reply_to
         reply(response_payload, properties.reply_to, properties.correlation_id)
       end
 
+      # 6. Acknowledge (Confirmación de procesado)
       session.channel.ack(delivery_info.delivery_tag)
+
     rescue NameError => e
-      BugBunny.configuration.logger.error("[Consumer] Controller/Action not found: #{e.message}")
+      # 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}")
+      handle_fatal_error(properties, 500, "Internal Server Error", e.message)
       session.channel.reject(delivery_info.delivery_tag, false)
-      if properties.reply_to
-        reply({ error: e.message }, properties.reply_to, properties.correlation_id)
-      end
     end
 
-    # Router: Simula el config/routes.rb de Rails.
+    # Interpreta la URL y el verbo para decidir qué controlador ejecutar.
+    #
+    # Utiliza `Rack::Utils.parse_nested_query` para soportar parámetros anidados
+    # como `q[service]=rabbit`.
     #
     # @param method [String] Verbo HTTP (GET, POST, etc).
-    # @param path [String] URL Path (ej: 'users/1').
-    # @return [Hash] {controller, action, id, params}
+    # @param path [String] URL virtual del recurso (ej: 'users/1?active=true').
+    # @return [Hash] Estructura con keys {:controller, :action, :id, :params}.
     def router_dispatch(method, path)
+      # Usamos URI para separar path de query string
       uri = URI.parse("http://dummy/#{path}")
-      segments = uri.path.split('/').reject(&:empty?) # ["users", "123"]
-      query_params = uri.query ? CGI.parse(uri.query).transform_values(&:first) : {}
-
-      controller_name = segments[0] # "users"
-      id = segments[1]              # "123" o nil
-
-      # Lógica de Inferencia Rails Standard
-      # GET users      -> index
-      # GET users/1    -> show
-      # POST users     -> create
-      # PUT users/1    -> update
-      # DELETE users/1 -> destroy
+      segments = uri.path.split('/').reject(&:empty?)
+
+      # --- FIX: Uso de Rack para soportar params anidados ---
+      query_params = uri.query ? Rack::Utils.parse_nested_query(uri.query) : {}
+
+      # Si estamos en Rails, convertimos a HashWithIndifferentAccess para comodidad
+      if defined?(ActiveSupport::HashWithIndifferentAccess)
+        query_params = query_params.with_indifferent_access
+      end
+
+      # Lógica de Ruteo Convencional
+      controller_name = segments[0]
+      id = segments[1]
+
       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 rutas miembro custom (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
+      # Inyectamos el ID en los params si existe en la ruta
       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 una respuesta al cliente RPC utilizando Direct Reply-to.
+    #
+    # @param payload [Hash] Cuerpo de la respuesta ({ status: ..., body: ... }).
+    # @param reply_to [String] Cola de respuesta (generalmente pseudo-cola amq.rabbitmq.reply-to).
+    # @param correlation_id [String] ID para correlacionar la respuesta con la petición original.
+    # @return [void]
     def reply(payload, reply_to, correlation_id)
       session.channel.default_exchange.publish(
         payload.to_json,
@@ -150,10 +197,29 @@ module BugBunny
       )
     end
 
+    # Maneja errores fatales asegurando que el cliente reciba una respuesta.
+    # Evita que el cliente RPC se quede esperando hasta el timeout.
+    #
+    # @api private
+    def handle_fatal_error(properties, status, error_title, detail)
+      return unless properties.reply_to
+
+      error_payload = {
+        status: status,
+        body: { error: error_title, detail: detail }
+      }
+      reply(error_payload, properties.reply_to, properties.correlation_id)
+    end
+
+    # Tarea de fondo (Heartbeat lógico) para verificar la salud del canal.
+    # Si la cola desaparece o la conexión se cierra, fuerza una reconexión.
+    #
+    # @param q_name [String] Nombre de la cola a monitorear.
     def start_health_check(q_name)
-      Concurrent::TimerTask.new(execution_interval: 60) do
+      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...")
         session.close
       end.execute
     end

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)